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
reslink@us.ibm.com 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 reslink@us.ibm.com. 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.
dump-configuration- Integer Optional Selects the boot configuration to use from among multiple such boot
selector (0-30) configurations that have been defined by the operating system
dump program to be loaded. Whether and how this parameter is
used to determine boot parameters depends on the dump program
and its boot process.

Default: 0, which indicates that the dump program's default boot

configuration should be used.
dump-os-specific- String Optional Specifies parameters that are passed unmodified to the loaded
parameters operating system dump program as part of the boot process. The
way in which these parameters are used depends on the dump
program, but in general, these parameters are intended to specify
boot-time configuration settings.

Default: an empty string.

dump-record-lba String Optional Specifies the logical block number of the anchor point for locating
(1-16) the operating system dump program on the SCSI disk from which
the dump program is loaded. The way in which this parameter is
used to locate the operating system depends on the operating
system and its boot process.

Default: 0, identifying the first block on the device.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 198. The job-results field is null when this operation
| is successful. When it is not successful, the job-results field contains an object with the following field:

196 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 loads a standalone dump program into the partition and begins its execution. It does so in
such a way that the existing contents of the partition's memory are not overwritten so that the dump
program can dump those contents.

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
198.

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 user does not have action/task permission to the Dump Partition task, a 403 (Forbidden) status
code is returned. A 409 (Conflict) status code is returned if the partition's status is not valid to perform
the operation. The valid partition states are "active" or "paused" or "terminated". A 409 (Conflict) is also
returned when there is no storage controller at the WWPN specified, when the storage controller does not
have a device with the specified LUN, or if the specified device does not contain a bootable dump
| program. If the partition has the "dpm-storage-management" feature enabled, a 409 (Conflict) status code
| is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition.
v Action/task permission for the Dump 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 196.

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.
Table 91. Dump 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 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.
2 A URI in the request body does not designate a resource of an expected type

Chapter 10. Dynamic Partition Manager (DPM) 197

 Level 04a

Table 91. Dump Partition: HTTP status and reason codes (continued)
HTTP error status Reason
code code Description
| 409 (Conflict) 12 The operation is not supported when the "dpm-storage-management"
| feature is enabled on the partition.
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 92. Dump Partition: Job status and reason codes
HTTP error status Reason
code code Description
200 (OK) N/A Operation completed successfully.
409 (Conflict) 1 Partition status is not valid to perform the operation (must be "active",
"paused", or "terminated".
2 Partition object with ID {partition-id} was busy and request timed out.
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.
119 The specified device does not contain a bootable dump program.
500 (Server Error) 263 Operation failed.

Example HTTP interaction

POST /api/partitions/d28fc978-d535-11e5-804c-42f2e9cfe851/operations/scsi-dump HTTP/1.1

x-api-session: 12a74m6cfuaiiebwuceikrhaqq8bxx1a6kxl6xoihyyfel8x5d
content-type: application/json
content-length: 205
{
"dump-load-hba-uri":"/api/partitions/d28fc978-d535-11e5-804c-42f2e9cfe851/hbas/bab7e3f8-
d53a-11e5-a366-42f2e9cfe851",
"dump-logical-unit-number":"00000",
"dump-world-wide-port-name":"AFFCB01FF21BCAFA"
}

Figure 44. Dump Partition: Request

198 HMC Web Services API

 Level 04a

202 Accepted
server: zSeries management console API web server / 2.0
location: /api/jobs/ec9c31e8-d53b-11e5-a9b8-5ef3fcb21ee8
cache-control: no-cache
date: Wed, 17 Feb 2016 06:01:45 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri":"/api/jobs/ec9c31e8-d53b-11e5-a9b8-5ef3fcb21ee8"
}

Figure 45. Dump Partition: Response

| Start Dump Program

| The Start Dump Program operation loads a standalone dump program from a designated external
| location such as a storage disk.

| HTTP method and URI

| POST /api/partitions/{partition-id}/operations/start-dump-program

| 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 a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| dump-program-info Object Required An object which identifies the location of the
| dump program and any additional parameters
| for loading or executing the dump program.
| The dump-program-type field indicates the type
| dump program and the type of object contained
| in this field.
| dump-program-type String Enum Required Indicates the type of dump program and
| identifies the type of object in
| dump-program-info. Valid values:
| v "storage" - The dump program resides on a
| storage volume. The dump-program-info
| field contains a storage-volume-dump-
| program-info object as described in the next
| table.
|

| The storage-volume-dump-program-info object contains the following fields:

|| Field name Type Rqd/Opt Description
| storage-volume-uri String/ URI Required Specifies the storage volume that shall be used
| to load the dump program. The value has to
| point to a valid URI of a fulfilled storage
| volume contained in a storage group attached to
| the partition.

Chapter 10. Dynamic Partition Manager (DPM) 199

 Level 04a

| Field name Type Rqd/Opt Description

| dump-configuration- Integer (0-30) Optional Selects the boot configuration to use from
| selector among multiple such boot configurations that
| have been defined by the operating system
| dump program to be loaded. Whether and how
| this parameter is used to determine boot
| parameters depends on the dump program and
| its boot process.

| Not valid when storage-volume-uri points to a

| FICON volume.

| Default: 0 which indicates that the dump

| program's default boot configuration should be
| used.
| dump-load-parameters String (0-8) Optional Specifies parameters that are passed unmodified
| to the loaded operating system dump program
| as part of the boot process. The way in which
| these parameters are used depends on the
| dump program, but in general, these parameters
| are intended to specify boot-time configuration
| settings.

| Not valid when storage-volume-uri points to a

| FICON volume.

| Default : an empty string

| dump-os-specific- String (0-256) Optional Specifies parameters that are passed unmodified
| parameters to the loaded operating system dump program
| as part of the boot process. The way in which
| these parameters are used depends on the
| dump program, but in general, these parameters
| are intended to specify boot-time configuration
| settings.

| Default : an empty string

| dump-record-lba String (1-16) Optional Specifies the logical block number of the anchor
| point for locating the operating system dump
| program on the SCSI disk from which the dump
| program is loaded. The way in which this
| parameter is used to locate the operating system
| depends on the operating system and its boot
| process.

| Not valid when storage-volume-uri points to a

| FICON volume.

| Default : 0 (identifying the first block on the

| device)
| timeout Integer (60-600) Optional The time in seconds that is waited before the
| load of the dump program is aborted.

| Default: 60
|

200 HMC Web Services API

 Level 04a

| 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 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 202. The job-results field is 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

| This operation loads a standalone dump program into the partition and begins its execution. It does so in
| a special way that the existing contents of the partition's memory are not overwritten so that the dump
| program can dump those contents.

| 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
| 202.

| 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 field in the "dump-program-info" does
| not designate a valid object to which the user has object-access permission.

| If the user does not have authority to perform the Dump Partition action, a 403 (Forbidden) status code is
| returned. A 409 (Conflict) status code is returned if the partition's status is not valid to perform the
| operation. The valid partition states are "active" or "paused" or "terminated".

| If the partition does not have the "dpm-storage-management" feature enabled, a 409 (Conflict) status
| code is returned.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object-access permission to the partition
| v Action/task permission for the Dump Partition task.

Chapter 10. Dynamic Partition Manager (DPM) 201

 Level 04a

| 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 201.

| 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 it.
| 2 A URI in the request body does not designate a storage volume in a storage
| group attached to the partition.
| 409 (Conflict) 13 The operation is not supported when the "dpm-storage-management"
| feature is not enabled on the partition.
| 122 The operation cannot be performed because the "dump-program-info"
| contains a "storage-volume-uri" property that does not designate a storage
| volume that is fulfilled.
| 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 93. Start Dump Program: 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 (must be "active",
| "paused" or "terminated".)
| 2 Partition object with ID {partition-id} was busy and request timed out.
| 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" and "exceptions".)
| 119 The specified device does not contain a bootable dump program.
| 500 (Server Error) 263 Operation failed.
|

202 HMC Web Services API

 Level 04a

| Example HTTP interaction

|

POST /api/partitions/a5987806-9af5-11e8-86f5-00106f0ddbc9/operations/start-dump-program HTTP/1.1

x-api-session: 5o0m316dydfq37m0uo06mqyzg0bf06yq9t8qm4j80kyx18cnc
content-type: application/json
content-length: 222
{
"dump-program-info":{
"dump-load-parameters":"ABCD",
"storage-volume-uri":"/api/storage-groups/9e5d850c-9fc5-11e8-8c3e-00106f0ddbc9/
storage-volumes/9e765546-9fc5-11e8-8c3e-00106f0ddbc9"
},
"dump-program-type":"storage"
}

Figure 46. Start Dump Program: Request

202 Accepted
server: Hardware management console API web server / 2.0
location: /api/jobs/8cbf1be8-a057-11e8-a48e-00106f0d84e1
cache-control: no-cache
date: Wed, 15 Aug 2018 06:50:51 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri":"/api/jobs/8cbf1be8-a057-11e8-a48e-00106f0d84e1"
}

Figure 47. Start Dump Program: Response

| Perform PSW Restart

The Perform PSW Restart operation restarts the first available processor of the Partition object designated
by {partition-id}.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/psw-restart

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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

Chapter 10. Dynamic Partition Manager (DPM) 203

 Level 04a

indicated in “Job status and reason codes” on page 205. 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.

Description
Information about PSW Restart can be found on the console help system.

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 205.

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 PSW Restart task, a 403 (Forbidden) status code is returned. A 409 (Conflict) status code is returned if
the partition's status is not valid to perform this operation. The valid partition states are "active",
"paused" or "terminated".

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition.
v Action/task permission for the PSW Restart 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 203.

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 it.
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.

204 HMC Web Services API

 Level 04a

Job status and reason codes

Table 94. Perform PSW Restart: Job status and reason codes
HTTP error status Reason
code code Description
200 (OK) N/A Operation completed successfully.
409 (Conflict 1 Partition status is not valid to perform the operation (must be "active",
"paused", or "terminated".
2 Partition object with ID {partition-id} was busy and request timed out.
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) 263 Operation failed.

Example HTTP interaction

POST /api/partitions/2052747e-52ac-11e5-a8c4-42f2e9cfe851/operations/psw-restart
x-api-session: 65aw2jahugn1wop51hsq0c6aldkkx773dz9ulirrvg2z853m4u
content-type: application/json

Figure 48. Perform PSW Restart: Request

202 Accepted
server: zSeries management console API web server / 2.0
location: /api/jobs/ec9c31e8-d53b-11e5-a9b8-5ef3fcb21ee8
cache-control: no-cache
date: Wed, 17 Feb 2016 06:01:45 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri":"/api/jobs/ec9c31e8-d53b-11e5-a9b8-5ef3fcb21ee8"
}

Figure 49. Perform PSW Restart: Response

Create Virtual Function

The Create Virtual Function operation creates a virtual function for the partition with the given
identifier.

HTTP method and URI

POST /api/partitions/{partition-id}/virtual-functions

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Chapter 10. Dynamic Partition Manager (DPM) 205

 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

name String Required The value to be set as the virtual function's name
(1-64) property.
description String Optional The value to be set as the virtual function's description
(0-1024) property.
adapter-uri String/ Required The URI of the physical Accelerator adapter which will
URI back the new virtual function.
device-number String Optional The value to be set as the virtual function's
device-number property.

Response body contents

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

Field name Type Description

element-uri String/URI The element-uri property of the created virtual function object.

Description
This operation creates a virtual function for the identified partition and then returns the URI of the
created object. Upon success, the response includes a Location header that provides the URI of the
created virtual function object. An Inventory Change notification is emitted asynchronously to this
operation.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if the request URI does not designate an existing partition or
designates a partition for which the API user does not have object-access permission. If the API user
doesn't have action/task permission to the Partition Details task 403 (Forbidden) status code is returned.
If the partition is in one of the transitional states ("starting" or "stopping"), or if the CPC is not in a valid
state, a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}.
v Object-access permission to the Accelerator adapter designated by the request body.
v Action/task permission to the Partition Details 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

206 HMC Web Services API

 Level 04a

Table 95. Create Virtual Function: 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 The virtual function name provided by the user is already in use by another
virtual function of the partition, or the provided device-number is already in
use by another Virtual Function element or by a NIC element of type "roce"
of the partition.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
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.
2 The adapter-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.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with ID {partition-id} was busy and request timed out.
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.
116 The partition does not have sufficient resources to perform 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.

Example HTTP interaction

POST /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/virtual-functions HTTP/1.1

x-api-session: 63ba4ynuscmvljkablyprvm2ajhr67pa9b9jon5fz4k5jlt7gw
content-type: application/json
content-length: 101
{
"adapter-uri":"/api/adapters/f36bf9ec-974f-11e5-bfaa-020000000192",
"name":"New Virtual Function"
}

Figure 50. Create Virtual Function: Request

Chapter 10. Dynamic Partition Manager (DPM) 207

 Level 04a

201 Created
server: zSeries management console API web server / 2.0
location: /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/virtual-functions/621c6430-
97e6-11e5-9e1e-020000000192
cache-control: no-cache
date: Tue, 01 Dec 2015 04:45:49 GMT
content-type: application/json;charset=UTF-8
content-length: 124
{
"element-uri":"/api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/virtual-functions/621c6430-
97e6-11e5-9e1e-020000000192"
}

Figure 51. Create Virtual Function: Response

Delete Virtual Function

The Delete Virtual Function operation removes an existing virtual function designated by its element ID
and the object ID of the owning partition.

HTTP method and URI

DELETE /api/partitions/{partition-id}/virtual-functions/{virtual-function-id}

URI variables:

Name Type Description

{partition-id} String Object ID of the Partition object.
{virtual-function-id} String Element ID of the virtual function object.

Description
This operation deletes the specified virtual function for the identified partition. Upon success, an
Inventory Change notification is emitted asynchronously to this operation.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if the request URI does not designate an existing partition or
designates a partition for which the API user does not have object-access permission. If the API user does
not have action/task permission to the Partition Details task, 403 (Forbidden) status code is returned. If
the partition is in one of the transitional state ("starting" or "stopping"), or if the CPC is not in a valid
state, a 409 (Conflict) status code is returned.

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 no response body is provided.

208 HMC Web Services API

 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.
Table 96. Delete Virtual Function: 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 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource or designates a
resource for which the API user does not have object-access permission
5 The request URI does not designate an existing virtual function element of
an existing partition.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with ID {partition-id} was busy and request timed out.
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.
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/b4c4bf9e-97e0-11e5-9d1f-020000000192/virtual-functions/621c6430-
97e6-11e5-9e1e-020000000192 HTTP/1.1
x-api-session: pz3qrhjpvhw10jsfypo8m8qyca10np08wgq8zmdifixd9r629

Figure 52. Delete Virtual Function: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 01 Dec 2015 04:52:01 GMT

Figure 53. Delete Virtual Function: Response

Get Virtual Function Properties

The Get Virtual Function Properties operation retrieves the properties of a single virtual function that is
designated by its element ID and the object ID of the owning partition.

HTTP method and URI

GET /api/partitions/{partition-id}/virtual-functions/{virtual-function-id}

URI variables:

Chapter 10. Dynamic Partition Manager (DPM) 209

 Level 04a

Name Type Description

{partition-id} String Object ID of the Partition object.
{virtual-function-id} String Element ID of the virtual function for which properties are to be obtained.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the virtual function object.

Description
This operation returns the current properties of the virtual function object that is specified by the request
URI. On successful execution, all of the current properties as defined by the “Data model - Virtual
Function element object” on page 161 are provided in the response body and HTTP status code 200 (OK)
is returned.

A 404 (Not Found) status code is returned if the request URI does not designate an existing virtual
function element of an existing partition, or if the API user does not have object-access permission to that
partition.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the partition.

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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 97. Get Virtual Function 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.
404 (Not Found) 1 The request URI does not designate an existing resource or designates a
resource for which the API user does not have object-access permission.
5 The request URI does not designate an existing virtual function element of
an existing partition.

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

210 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/partitions/de4acc6c-361f-11e7-87dd-00106f0d81cb/virtual-functions/
7e89bce4-4479-11e7-9af6-00106f0d81cb HTTP/1.1
x-api-session: 3yg30uqxt7k97dxkei8rxn8mhbvngwka6nq9ftuxk3qhaka69f

Figure 54. Get Virtual Function Properties: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Wed, 31 May 2017 09:44:55 GMT
content-type: application/json;charset=UTF-8
content-length: 399
{
"adapter-uri":"/api/adapters/d7077406-f839-11e6-af0f-00106f0d81cb",
"class":"virtual-function",
"description":"",
"device-number":"0001",
"element-id":"7e89bce4-4479-11e7-9af6-00106f0d81cb",
"element-uri":"/api/partitions/de4acc6c-361f-11e7-87dd-00106f0d81cb/virtual-functions/
7e89bce4-4479-11e7-9af6-00106f0d81cb",
"fid":null,
"name":"ttt",
"parent":"/api/partitions/de4acc6c-361f-11e7-87dd-00106f0d81cb"
}

Figure 55. Get Virtual Function Properties: Response

Update Virtual Function Properties

The Update Virtual Function Properties operation modifies an existing virtual function that is designated
by its element ID and the object ID of the owning partition.

HTTP method and URI

POST /api/partitions/{partition-id}/virtual-functions/{virtual-function-id}

URI variables:

Name Type Description

{partition-id} String Object ID of the Partition object.
{virtual-function-id} String Element ID of the virtual function.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
This operation modifies an existing virtual function specified by the request URI.

Chapter 10. Dynamic Partition Manager (DPM) 211

 Level 04a

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if the request URI does not designate an existing virtual
function element of an existing partition, or if the API user does not have object-access permission to that
partition. If the API user doesn't have action/task permission to Partition Details task 403 (Forbidden)
status code is returned. If the partition is in one of the transitional states ("starting" or "stopping"), or if
the CPC is not in a valid state, a 409 (Conflict) status code is returned.

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.
v When updating adapter-uri, object-access permission to the adapter identified in that URI.

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.
Table 98. Update Virtual Function Properties: HTTP status and reason codes.
HTTP error status
code Reason 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 The virtual function name provided by the user is already in use by another
virtual function of the partition, or the provided device-number is already
in use by another Virtual Function element or by a NIC element of type
"roce" of the partition.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource or designates a
resource for which the API user does not have object-access permission.
2 The adapter-uri in the request body does not designated an existing
resource of the expected type, or designates a resource for which the API
user does not have object-access permission.
5 The request URI does not designate an existing virtual function element of
an existing partition.
409 (Conflict) 1 Partition status is not valid to perform the operation
2 Partition object with ID {partition-id} was busy and request timed out.
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.
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.

212 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/virtual-functions/621c6430-
97e6-11e5-9e1e-020000000192 HTTP/1.1
x-api-session: 1chtesqt42ehx99ayericoofm6gz1gt85wedt8piouotf6doyh
content-type: application/json
content-length: 46
{
"name":"Virtual Function Name after update"
}

Figure 56. Update Virtual Function Properties: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 01 Dec 2015 04:50:36 GMT
<No response body>

Figure 57. Update Virtual Function Properties: Response

Create NIC
The Create NIC operation creates a NIC for the partition with the given identifier.

HTTP method and URI

POST /api/partitions/{partition-id}/nics

In this request, the URI variable {partition-id} is the object ID of the partition.

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The value to be set as the NIC's name property.
(1-64)
description String Optional The value to be set as the NIC's description property.
(0-1024)
network-adapter- String/ Required, if the The value to be set as the NIC's network-adapter-port-uri
port-uri URI adapter type is property.
"roce"
Required if the type of the adapter containing the port
referenced by the network-adapter-port-uri field is "roce".
virtual-switch-uri String/ Required, if the The value to be set as the NIC's virtual-switch-uri
URI adapter type is "osd" property.
or "iqd"
Required if the type of the adapter containing the port
referenced by the virtual-switch-uri field is "osd" or
"iqd".
device-number String (4) Optional The value to be set as the NIC's device-number property.

Device number for this NIC. If not provided, a

device-number is auto-generated.

Chapter 10. Dynamic Partition Manager (DPM) 213

 Level 04a

Field name Type Rqd/Opt Description

ssc-management-nic Boolean Optional The value to be set as the NIC's ssc-management-nic
property. Cannot be set to true when the partition's type
is not "ssc".

Default: false
ssc-ip-address- String Required if The value to be set as the NIC's ssc-ip-address-type
type Enum ssc-management-nic property. Cannot be set when the partition's type is not
is true "ssc".
ssc-ip-address String/ Required if The value to be set as the NIC's ssc-ip-address property.
IPv4 ssc-ip-address-type Cannot be set when the partition's type is not "ssc".
Address or is "ipv4" or "ipv6"
String/
IPv6
Address
vlan-id Integer Optional The value to be set as the NIC's vlan-id property.
ssc-mask-prefix String Required if The value to be set as the NIC's ssc-mask-prefix. Cannot
ssc-ip-address-type be set when the partition's type is not "ssc".
is "ipv4" or "ipv6"
mac-address String Optional The value to be set as the NIC's mac-address property.
vlan-type String Required if vlan-id The value to be set as the NIC's vlan-type property.
Enum is provided

Response body contents

On successful completion, the response body contains the URI of the created NIC object.

Field name Type Description

element-uri String/URI The element-uri property of the created NIC object.

Description
This operation creates a NIC for the identified partition and then returns the URI of the created object.
Upon success, the response includes a Location header that provides the URI of the created NIC object.
An Inventory Change notification is emitted asynchronously to this operation. The request identifies the
NIC's backing adapter by specifying either a network port URI or a virtual switch URI.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if 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. If the API user
doesn't have action/task permission to Partition Details task 403 (Forbidden) status code is returned. If
the partition is in one of the transitional states ("starting" or "stopping"), or if the CPC is not in a valid
state , a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}.
v Object-access permission to the backing Adapter object of the Virtual Switch object or to the RoCE
adapter specified in the request body.
v Action/task permission to the Partition Details task.

214 HMC Web Services API

 Level 04a

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 214.

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.
Table 99. Create NIC: 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.
5 For partitions that are not of type "ssc":
v The user specified a valid value for the vlan-id property, but did not
specify a value for the vlan-type property or it was null.
v The user did not specify a value for the vlan-id property, but specified the
value for the vlan-type property as "enforced".
7 The locally administered bit in the value specified for the mac-address
property is invalid.
8 For NIC elements of type "roce", the NIC name provided by the user is
already in use by another NIC of the partition, or the provided
device-number is already in use by another NIC element of type "roce" or
by a Virtual Function element of the partition.

For NIC elements of type "iqd" or "osd", the NIC name provided by the
user is already in use by another NIC of the partition, or the provided
device-number is already in use by another NIC element of type "iqd" or
"osd" or by an HBA element, or the mac-address provided by the user is
already in use by another NIC in any of the partitions in the CPC.
15 ssc-management-nic was set to true, but no value for ssc-ip-address-type
was provided.

ssc-ip-address-type was set to "ipv4" or "ipv6", but no value for

ssc-ip-address or ssc-mask-prefix was provided.

For partitions that are not of type "ssc":

v The user specified a valid value for the vlan-id property, but vlan-type
was null.
v The user specified the value for the vlan-id property as null, but specified
the value of the vlan-type property as "enforced".
18 For partitions of type "ssc":
v A non-null value was specified for the vlan-type property.
v A value for the mac-address property was specified for the NIC element
of type "roce".

For partitions of other types:

v A value for the properties mac-address, vlan-id, or vlan-type was
specified for the NIC element of type "roce".
403 (Forbidden) 1 The API user does not have the required permission for this operation.

Chapter 10. Dynamic Partition Manager (DPM) 215

 Level 04a

Table 99. Create NIC: HTTP status and reason codes (continued).
HTTP error status Reason
code code Description
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 The object ID in the Network Port URI in request body field
network-adapter-port-uri does not designate an existing Adapter object, or
the API user does not have object-access permission to that adapter, or the
object ID in the virtual switch URI in the request body field
virtual-switch-uri does not designate an existing Virtual Switch object, or the
API user does not have object-access permission to that virtual switch.
6 The element ID in the Network Port URI in request body field
network-adapter-port-uri does not designate an existing adapter port of the
adapter.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with ID {partition-id} was busy and request timed out.
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 ssc-management-nic was set to true, but the partition's type is not "ssc".
10 The operation cannot be performed because the affected SE is in the process
of being shut down.
116 The partition does not have sufficient resources to perform 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.

Example HTTP interaction

POST /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/nics HTTP/1.1

x-api-session: 35yero3ati5fholesprwebpbn3ktukx59cucm4tt4c86m6n9id
content-type: application/json
content-length: 100
{
"name":"Nic1",
"virtual-switch-uri":"/api/virtual-switches/0c797342-9750-11e5-bfaa-020000000192"
}

Figure 58. Create NIC: Request

216 HMC Web Services API

 Level 04a

201 Created
server: zSeries management console API web server / 2.0
location: /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/nics/eb6887e4-97e8-11e5-9d1f-
020000000192
cache-control: no-cache
date: Tue, 01 Dec 2015 05:03:57 GMT
content-type: application/json;charset=UTF-8
content-length: 123
{
"element-uri":"/api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/nics/eb6887e4-
97e8-11e5-9d1f-020000000192"
}

Figure 59. Create NIC: Response

Delete NIC
The Delete NIC operation deletes an existing NIC objects that is designated by its element ID and the
object ID of the owning partition.

HTTP method and URI

DELETE /api/partitions/{partition-id}/nics/{nic-id}

URI variables:

Name Type Description

{partition-id} String Object ID of the Partition object.
{nic-id} String Element ID of the NIC.

Description
This operation deletes the specified NIC. Upon success, an Inventory Change notification is emitted
asynchronously to this operation.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if the request URI does not designate an existing NIC element
of an existing partition, or if the API user does not have object-access permission to that partition. If the
API user doesn't have action/task permission to Partition Details task, 403 (Forbidden) status code is
returned. If the partition is in one of the transitional states ("starting" or "stopping"), or if the CPC is not
in a valid state, a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}.
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.

Chapter 10. Dynamic Partition Manager (DPM) 217

 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.
Table 100. Delete NIC: 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 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 designated an existing
Partition object, or the API user does not have object-access permission to it.
5 The request URI does not designate an existing NIC of an existing partition.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with ID {partition-id} was busy and request timed out.
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", or "exceptions".)
8 NIC cannot be deleted as it is set as the partition's boot device.
10 The operation cannot be performed because the affected SE is in the process
of being shut down.
| 100 NIC cannot be deleted as it is the last SSC Management NIC
| (ssc-management-nic is true) on an active partition.
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/b4c4bf9e-97e0-11e5-9d1f-020000000192/nics/eb6887e4-97e8-
11e5-9d1f-020000000192 HTTP/1.1
x-api-session: 4qhwaoj0lyleh8l57e0z8znsnpphgelqnatcpe5pu5cjk69qeg

Figure 60. Delete NIC: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 01 Dec 2015 05:21:30 GMT
<No response body>

Figure 61. Delete NIC: Response

Get NIC Properties

The Get NIC Properties operation retrieves the properties of a single NIC object that is designated by its
element ID and the object ID of the owning partition.

218 HMC Web Services API

 Level 04a

HTTP method and URI

GET /api/partitions/{partition-id}/nics/{nic-id}

URI variables:

Name Type Description

{partition-id} String Object ID of the Partition object.
{nic-id} String Element ID of the NIC.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the NIC object as defined in the “Data model - NIC element object” on page 161. Field
names and data types in the JSON object are the same as the property names and data types defined in
the “Data model” on page 146.

Description
This operation returns the current properties for the NIC object that is specified by the request URI.

On successful execution, all of the current properties as defined by the “Data model - NIC element
object” on page 161 are provided in the response body and HTTP status code 200 (OK) is returned.

A 404 (Not Found) status code is returned if the request URI does not designate an existing NIC element
of an existing partition, or if the API user does not have object-access permission to that partition.

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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 101. Get NIC 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.
404 (Not Found) 1 The object-id in the URI {partition-id} does not designated an existing
Partition object, or the API user does not have object-access permission to it.
5 The request URI does not designate an existing NIC of an existing partition.

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) 219

 Level 04a

Example HTTP interaction

GET /api/partitions/fd93be7e-e928-11e6-bcc9-42f2e9cfe851/nics/9ff431cc-e92d-11e6-
9563-42f2e9cfe851 HTTP/1.1
x-api-session: 14ort688m7f2j5yi4tp1eedxo78x7d0ko7qrm7evk5h28p7bzc

Figure 62. Get NIC Properties: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 06 Feb 2017 09:11:27 GMT
content-type: application/json;charset=UTF-8
content-length: 551
{
"class":"nic",
"description":"",
"device-number":"0004",
"element-id":"9ff431cc-e92d-11e6-9563-42f2e9cfe851",
"element-uri":"/api/partitions/fd93be7e-e928-11e6-bcc9-42f2e9cfe851/nics/
9ff431cc-e92d-11e6-9563-42f2e9cfe851",
"mac-address":"02:ff:ec:00:21:07",
"name":"ttt",
"parent":"/api/partitions/fd93be7e-e928-11e6-bcc9-42f2e9cfe851",
"ssc-ip-address":"fc01:1234:1234:1234::3",
"ssc-ip-address-type":"ipv6",
"ssc-management-nic":true,
"ssc-mask-prefix":"/24",
"type":"osd",
"virtual-switch-uri":"/api/virtual-switches/2b0d93e8-b64d-11e6-99ee-42f2e9cfe851",
"vlan-id":10
"vlan-type":"enforced"
}

Figure 63. Get NIC Properties: Response

Update NIC Properties

The Update NIC Properties operation updates the properties of a single NIC object that is designated by
its element ID and the object ID of the owning partition.

HTTP method and URI

POST /api/partitions/{partition-id}/nics/{nic-id}

URI variables:

Name Type Description

{partition-id} String Object ID of the Partition object.
{nic-id} String Element ID of the NIC.

Request body contents

The request body is expected to contain one or more field names representing writable NIC properties,
along with the new values for those fields.

220 HMC Web Services API

 Level 04a

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
This operation modifies the NIC properties for the NIC specified by the request URI.

A 404 (Not Found) status code is returned if the request URI does not designate an existing NIC element
of an existing partition, or if the API user does not have object-access permission to that partition.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

If the API user doesn't have action/task permission to the Partition Details task, 403 (Forbidden) status
code is returned. If the partition is in one of the transitional states ("starting" or "stopping"), or if the
CPC is not in a valid state, a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}.
v Action/task permission to the Partition Details task.
v When updating network-adapter-port-uri, object-access permission to the adapter identified in that
URI.
v When updating virtual-switch-uri, object-access permission to the backing Adapter object of the Virtual
Switch object identified in that URI.

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.

Chapter 10. Dynamic Partition Manager (DPM) 221

 Level 04a

Table 102. Update NIC Properties: HTTP status and reason codes.
HTTP error status
code Reason 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.
5 For partitions that are not of type "ssc":
v The user specified a valid value for the property vlan-id, but did not
specify a value for the property vlan-type or was null.
v The user did not specify a value for the property vlan-id or was null, but
specified the value for the property vlan-type as "enforced".
7 The locally administered bit in the value specified for the mac-address
property is invalid.
8 For NIC elements of type "roce", the NIC name provided by the user is
already in use by another NIC of the partition, or the provided
device-number is already in use by another NIC element of type "roce" or
by a Virtual Function element of the partition.

For NIC elements of type "iqd" or "osd", the NIC name provided by the
user is already in use by another NIC of the partition, or the provided
device-number is already in use by another NIC element of type "iqd" or
"osd" or by an HBA element, or the mac-address provided by the user is
already in use by another NIC in any of the partitions in the CPC.
15 ssc-management-nic was set to true, but no value for ssc-ip-address-type
was provided.

ssc-ip-address-type was set to "ipv4" or "ipv6", but no value for

ssc-ip-address or ssc-mask-prefix was provided.

For partitions that are not of type "ssc":

v The user specified a value for both vlan-id and vlan-type properties, but
either or both of the properties values are invalid.
18 For partitions of type "ssc":
v A non-null value was specified for the vlan-type property.
v A value for the mac-address property was specified for the NIC element
of type "roce".

For partitions of other types:

v A value for the properties mac-address, vlan-id, or vlan-type was
specified for the NIC element of type "roce".
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 designated an existing
Partition object, or the API user does not have object-access permission to it.
2
The object ID in the Network Port URI in request body field
network-adapter-port-uri does not designate an existing Adapter object, or
the API user does not have object-access permission to that adapter, or the
object ID in the virtual switch URI in request body field virtual-switch-uri
does not designate an existing Virtual Switch object, or the API user does
not have object-access permission to that virtual switch.
5 The request URI does not designate an existing NIC of an existing partition.
6
The element ID in the Network Port URI in request body field
network-adapter-port-uri does not designate an existing adapter port of the
adapter.

222 HMC Web Services API

 Level 04a

Table 102. Update NIC Properties: HTTP status and reason codes (continued).
HTTP error status
code Reason code Description
409 (Conflict) 1
Partition status is not valid to perform the operation.
2 Partition object with ID {partition-id} was busy and request timed out.
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 request cannot be processed because the update to virtual-switch-uri/
network-adapter-port-uri attempts to change the switch/port type.

ssc-management-nic was set to true, but the partition's type is not "ssc".

For partitions that are not of type "ssc":

v The user specified a valid value for vlan-id but it is not compatible with
the current value of vlan-type.
v The user specified a valid value for vlan-type but it is not compatible
with the current value of vlan-id.
10 The operation cannot be performed because the affected SE is in the process
of being shut down.
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

POST /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/nics/eb6887e4-97e8-11e5-9d1f-
020000000192 HTTP/1.1
x-api-session: 3nho0b70bohx2ei3wjryvayxgxxnqo7wtqyj3lsifu4kfok2nf
content-type: application/json
content-length: 25
{
"name":"NicUpdateName"
}

Figure 64. Update NIC Properties: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 01 Dec 2015 05:17:57 GMT
<No response body>

Figure 65. Update NIC Properties: Response

Increase Crypto Configuration

The Increase Crypto Configuration operation can be used to add more elements to an existing (empty or
non-empty) crypto configuration.

Chapter 10. Dynamic Partition Manager (DPM) 223

 Level 04a

HTTP method and URI

POST /api/partitions/{partition-id}/operations/increase-crypto-configuration

In this request, the URI variable {partition-id} is the object ID of the target partition.

Request body contents

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

Field name Type Rqd/Opt Description

crypto-adapter-uris Array of String/ Optional Array of URIs listing crypto adapters that should
URI be added to the crypto configuration of this
partition.
crypto-domain- Array of Optional Array of crypto-domain-configuration objects (see
configurations crypto-domain- Table 78 on page 160) that should be added to the
configuration crypto configuration of this partition.
objects

Description
This operation adds the specified adapters and/or domain configurations to the crypto configuration of
the corresponding partition.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if 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. If the API user
doesn't have action/task permission to the Partition Details task, 403 (Forbidden) status code is returned.
If the partition is in one of the transitional states ("starting" or "stopping"), or if the CPC is not in a valid
state, a 409 (Conflict) status code is returned. A 400 (Bad Request) status code is returned when no lists
are provided or both the lists are empty.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition object designated by {partition-id}.
v Object-access permission to all crypto adapter objects specified in crypto-adapter-uris.
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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 103. Increase Crypto Configuration: HTTP status and reason codes.
HTTP error status
code Reason 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.
101 No lists provided, or both provided lists are empty.

224 HMC Web Services API

 Level 04a

Table 103. Increase Crypto Configuration: HTTP status and reason codes (continued).
HTTP error status
code Reason code Description
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The partition with object-id {partition-id} does not exist, or the API user
does not have object-access permission to it.
2 A URI in the request body does not designated an existing resource of the
expected type, or designates a resource for which the API user does not
have object-access permission.
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.
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.
111 The resulting crypto configuration is invalid because it does not contain at
least one domain configuration with "control-usage".
112 The resulting crypto configuration contains at least one domain index with
"control-usage" which is already configured for "control-usage" by another
partition.
113 The list crypto-adapter-uris contains an adapter that is already part of the
existing crypto configuration.
114 The list crypto-domain-configurations contains a domain index which is
already part of the existing crypto configuration.
119 The resulting crypto configuration is invalid because it does not contain at
least one adapter URI.
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) 225

 Level 04a

Example HTTP interaction

POST /api/partitions/7eedd6e4-e0fb-11e5-9731-42f2e9cfe851/operations/increase-crypto-
configuration HTTP/1.1
x-api-session: 4zzbvb5b1f5i2huscdbya9c3jp5iwoqv1jp5p5qal2vvmpwmil
content-type: application/json
content-length: 166
{
"crypto-adapter-uris":[
"/api/adapters/cd8d52b2-d614-11e5-93bf-42f2e9cfe851"
],
"crypto-domain-configurations":[
{
"access-mode":"control-usage",
"domain-index":1
}
]
}

Figure 66. Increase Crypto Configuration: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 03 Mar 2016 05:28:51 GMT

<No response body>

Figure 67. Increase Crypto Configurations: Response

Change Crypto Domain Configuration

The Change Crypto Domain Configuration operation can be used to change the configuration of a single
crypto domain that is already configured.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/change-crypto-domain-configuration

In this request, the URI variable {partition-id} is the object ID partition.

Request body contents

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

Field name Type Rqd/Opt Description

domain-index Integer Required Index of the domain to be changed. See
Table 78 on page 160.
access-mode String Enum Required The new value of the access-mode property of
the crypto domain configuration identified by
the domain-index. See Table 78 on page 160.

The structure of crypto domain configuration objects is described in “crypto-configuration object

properties” on page 159.

226 HMC Web Services API

 Level 04a

Description
This operation changes the access mode for a crypto domain configuration that is currently included in
the crypto configuration of the partition.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if 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. If the API user
doesn't have action/task permission to Partition Details task 403 (Forbidden) status code is returned. If
the partition is in one of the transitional states ("starting" or "stopping"), or if the CPC is not in a valid
state, a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}.
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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 104. Change Crypto Domain Configuration: HTTP status and reason codes.
HTTP error status
code Reason 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 partition with object-id {partition-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 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.
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.
111 The resulting crypto configuration is invalid because it does not contain at
least one domain configuration with "control-usage".
112 The resulting crypto configuration contains at least one domain index with
"control-usage" which is already configured for "control-usage" by another
partition.
115 The index used in the request is not part of the crypto configuration of the
targeted partition.

Chapter 10. Dynamic Partition Manager (DPM) 227

 Level 04a

Table 104. Change Crypto Domain Configuration: HTTP status and reason codes (continued).
HTTP error status
code Reason code Description
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

POST /api/partitions/7eedd6e4-e0fb-11e5-9731-42f2e9cfe851/operations/change-crypto-
domain-configuration HTTP/1.1
x-api-session: 4eiaktj22cbpeiya9yxax1af21u0lwyodll9iicrhy6egy3trp
content-type: application/json
content-length: 51
{
"access-mode":"control-usage",
"domain-index":1
}

Figure 68. Change Crypto Domain Configuration: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 03 Mar 2016 06:01:20 GMT

<No response body>

Figure 69. Change Crypto Domain Configuration: Response

Decrease Crypto Configuration

The Decrease Crypto Configuration operation can be used to remove some or all elements of an existing
(non-empty) crypto configuration.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/decrease-crypto-configuration

In this request, the URI variable {partition-id} is the object ID of the partition.

Request body contents

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

Field name Type Rqd/Opt Description

crypto-adapter-uris Array of Optional Array of URIs listing crypto adapters that
String/ URI should be removed from the crypto
configuration of this partition.
crypto-domain-indexes Array of Optional Array of integers, listing all crypto domain
Integer indexes that should be removed from the
crypto configuration of this partition.

228 HMC Web Services API

 Level 04a

Description
This operation removes the specified adapters and/or domain configurations from the crypto
configuration of the corresponding partition.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if 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. If the API user
doesn't have action/task permission to Partition Details task 403 (Forbidden) status code is returned. If
the partition is in one of the transitional states ("starting" or "stopping"), or if the CPC is not in a valid
state, a 409 (Conflict) status code is returned. A 400 (Bad Request) status code is returned if no lists were
provided or both the lists were empty.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}.
v Object-access permission to all crypto adapter objects specified in crypto-adapter-uris.
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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 105. Decrease Crypto Configuration: HTTP status and reason codes.
HTTP error status
code Reason 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.
101 No lists provided, or both provided lists are empty.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The partition with object-id {partition-id} does not exist, or the API user does
not have object-access permission to it.
2 A URI in request body field crypto-adapter-uris does not designated an
existing crypto adapter, or the API user does not have object-access
permission to it.

Chapter 10. Dynamic Partition Manager (DPM) 229

 Level 04a

Table 105. Decrease Crypto Configuration: HTTP status and reason codes (continued).
HTTP error status
code Reason 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.
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.
111 The resulting crypto configuration is invalid because it does not contain at
least one domain configuration with "control-usage".
112 The resulting crypto configuration contains at least one domain index with
"control-usage" which is already configured for "control-usage" by another
partition.
115 The index used in the request is not part of the crypto configuration of the
targeted partition.
117 One or more of the provided adapter URIs are not part of the configuration
of the targeted partition.
119 The resulting crypto configuration is invalid because it contains a domain
configuration but does not contain any crypto adapters.
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

POST /api/partitions/7eedd6e4-e0fb-11e5-9731-42f2e9cfe851/operations/decrease-crypto-
configuration HTTP/1.1
x-api-session: 6al0zfk8sivht7i6bd0xeo4byaklto8al0de8fru67wpdn0coz
content-type: application/json
content-length: 109
{
"crypto-adapter-uris":[
"/api/adapters/cd8d52b2-d614-11e5-93bf-42f2e9cfe851"
],
"crypto-domain-indexes":[
1
]
}

Figure 70. Decrease Crypto Configuration: Request

230 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 03 Mar 2016 05:32:46 GMT

<No response body>

Figure 71. Decrease Crypto Configuration: Response

Mount ISO Image

The Mount ISO Image operation can be used to upload a user provided ISO image. The uploaded ISO
image is the image that gets attached to the partition. The contents of the ISO image are specified as
binary data in the body of the POST request.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/mount-iso-image

In this request, the URI variable {partition-id} is the object ID of the partition.

Query parameters:

Name Type Rqd/Opt Description

image-name String Required
This field is used as the displayable name of
the ISO image contained in the request body. It
becomes the value of the boot-iso-image-name
in the partition properties.

The image-name must conform to the

requirements of the boot-iso-image-name
property as documented in the “Data model”
on page 146.
ins-file-name String Required This field is used to set the boot-iso-ins-file in
the partition properties.The ins-file-name must
conform to the requirements of the
boot-iso-ins-file property as documented in the
“Data model” on page 146.

Request body contents

The request body is the binary contents of an ISO image file. A MIME media type of
application/octet-stream should be specified as the content-type on the request.

Description
This operation uploads an ISO image and associates it to the partition. If this operation is requested when
the partition already has an ISO image associated, the newly uploaded image replaces the current one.

A 404 (Not Found) status code is returned if the object-id {partition-id} does not identify a Partition object
to which the API user has object-access permission. If the API user does not have action permission for
the Partition Details task, a 403 (Forbidden) status code is returned. If the partition is in one of the
transitional states ("starting" or "stopping"), a 409 (Conflict) status code is returned.

Chapter 10. Dynamic Partition Manager (DPM) 231

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}.
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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 106. Mount ISO Image: HTTP status and reason codes.
HTTP error status
code Reason 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.
14 The required query parameters have not been specified.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The partition with 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.
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.
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

POST /api/partitions/2052747e-52ac-11e5-a8c4-42f2e9cfe851/mount-iso-image?image-
name=TestISO&ins-file-name=TestISO.ins HTTP/1.1
x-api-session: pd0nrulei0qsa1mwlpaw7cmq26rnsdcdhtp4w4m9gzse7gybg

Figure 72. Mount ISO Image: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Wed, 17 Feb 2016 05:30:34 GMT
<No response body>

Figure 73. Mount ISO Image: Response

232 HMC Web Services API

 Level 04a

Unmount ISO Image

The Unmount ISO Image operation unmounts the currently mounted ISO from the identified partition.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/unmount-iso-image

In this request, the URI variable {partition-id} is the object ID of the targeted partition.

Description
This operation unmounts an ISO image that is associated to a partition. This operation sets the partition's
boot-iso-image-name and boot-iso-ins-file properties to null.

A 404 (Not Found) status code is returned if the object-id {partition-id} does not identify a partition object
to which the API user has object-access permission. If the API user does not have action permission for
the Partition Details task, a 403 (Forbidden) status code is returned. If the partition is in one of the
transitional states ("starting" or "stopping"), a 409 (Conflict) status code is returned. A 409 (Conflict)
status code is also returned if the partition does not currently have an ISO image associated with it.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}.
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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 107. Unmount ISO Image: HTTP status and reason codes.
HTTP error status
code Reason 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 partition with 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.
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.
118 The partition does not have any image associated with it to perform the
operation.
119 The partition is currently configured to boot from the ISO image. That is, the
partition's boot-device property is currently set to "iso-image".
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.

Chapter 10. Dynamic Partition Manager (DPM) 233

 Level 04a

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/partitions/2052747e-52ac-11e5-a8c4-42f2e9cfe851/unmount-iso-image HTTP/1.1

x-api-session: pd0nrulei0qsa1mwlpaw7cmq26rnsdcdhtp4w4m9gzse7gybg

Figure 74. Unmount ISO Image: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Wed, 17 Feb 2016 05:30:34 GMT
<No response body>

Figure 75. Unmount ISO Image: Response

| Attach Storage Group to Partition

| The Attach Storage Group to Partition operation attaches a storage group to a partition.

| HTTP method and URI

| POST /api/partitions/{partition-id}/operations/attach-storage-group

| In this request, the URI variable {partition-id} is the object ID of the partition.

| Request body contents

|| Name Type Rqd/Opt Description
| storage-group-uri String/ URI Required The canonical URI of the Storage Group object
| to be attached to the partition.
|

| Description

| The Attach Storage Group to Partition operation attaches the storage group to the partition specified by
| the {partition-id} portion of the request URI.

| On successful execution, the storage group gets associated with the partition.

| For a storage group of type "fc", the virtual storage resources are created if the partition is in one of the
| following states: "active", "degraded", "paused" or "terminated", if the fulfillment state of the storage
| group is "complete".

| For a storage group of type "fcp", the operation is allowed only if the storage group is in one of the valid
| fulfillment states ("complete", "pending", "pending-with-mismatches" and "checking-migration"). The
| virtual storage resources are created immediately on the storage ports depending on the status of the
| unassigned world wide port names of the storage group. If the status of the world wide port name is
| "validated", a previously verified storage port is used to create the virtual storage resource. If the status
| of the world wide port name is "not-validated", a virtual storage resource is created without a storage

234 HMC Web Services API

 Level 04a

| port. In that case, a storage port is assigned to the virtual storage resource later, when DPM successfully
| verifies connectivity to the defined storage volumes on storage ports.

| If this operation changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation.

| This operation enables the operating system in the partition to access the storage volumes defined in the
| storage group, through the virtual storage resources that are assigned to storage ports. The operating
| system may not be able to access all the volumes defined in the storage group, until the fulfillment state
| of the storage group is "complete".

| The URI path must designate an existing Partition object and the API user must have object-access
| permission to it. In addition, storage-group-uri field in the request body must designate an existing
| Storage Group and the API user must have object-access permission to that storage group.

| If either of these conditions are not met, status code 404 (Not Found) is returned. In addition, the API
| user must have action/task permissions to Partition Details task; otherwise, status code 403 (Forbidden)
| is returned. If the request body is not valid, status code 400 (Bad Request) is returned with a reason code
| indicating the validation error encountered.

| If the partition is in any of the transitional states ("starting" or "stopping") or if the CPC is not in a valid
| state, 409 (Conflict) status code is returned. If the partition does not have the "dpm-storage-management"
| feature enabled or if the fulfillment state of the storage group is "incomplete", a 409 (Conflict) status code
| is returned.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object-access permission to the Partition object designated by {partition-id}.
| v Object-access permission to the Storage Group object designated by the storage-group-uri field.
| 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, and the response body is a
| standard error response body providing the reason code indicated and associated error message.
| Table 108. Attach Storage Group to Partition: HTTP status and reason codes
| HTTP error status
| code Reason 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 partition.
| 2 The object ID in the storage group URI in request body field
| storage-group-uri does not designate an existing Storage Group object, or
| the API user does not have object-access permission to that storage group.

Chapter 10. Dynamic Partition Manager (DPM) 235

 Level 04a

| Table 108. Attach Storage Group to Partition: HTTP status and reason codes (continued)
| HTTP error status
| code Reason code Description
| 409 (Conflict) 1 Partition status is not valid to perform the operation.
| 2 Partition object with ID {partition-id} was 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".)
| 13 The operation is not supported when the "dpm-storage-management"
| feature is not enabled on the partition.
| 118 The Storage Group specified by storage-group-uri is already attached to the
| partition.
| 119 The Storage Group specified by storage-group-uriis already attached to
| maximum partitions according to its specification.
| 124 The storage group object designated by the {storage-group-uri} was busy
| performing some other operation.
| 471 The fulfillment state of the storage group is not valid to perform this
| operation.

| Valid values for the storage group's fulfillment-state property are:

| "complete", "pending", "pending-with-mismatches" and
| "checking-migration".
| 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

|

POST /api/partitions/acab6d72-8107-11e8-9d6f-00106f0d81cb/operations/attach-storage-
group HTTP/1.1
content-length:81,
content-type:application/json,
x-api-session:1zpqlegsp02sdzr2h04uxhc91ou8fdmxvpn0ukxtaouqg6k3e0
{
“storage-group-uri”: “/api/storage-groups/519578c6-9569-11e8-a732-00106f0d81cb”
}

Figure 76. Attach Storage Group to Partition: Request

204 No Content
cache-control:no-cache,
date:Wed, 01 Aug 2018 09:00:27 GMT,
server:Hardware management console API web server / 2.0

<No response body>

Figure 77. Attach Storage Group to Partition: Response

236 HMC Web Services API

 Level 04a

| Detach Storage Group from Partition

| The Detach Storage Group from Partition operation detaches a storage group from a partition specified
| by the {partition-id} portion of the request URI.

| HTTP method and URI

| POST /api/partitions/{partition-id}/operations/detach-storage-group

| In this request, the URI variable {partition-id} is the object ID of the partition.

| Request body contents

|| Name Type Rqd/Opt Description
| storage-group-uri String/ URI Required The canonical URI of the Storage Group object
| to be detached from the partition.
|

| Description

| The Detach Storage Group from Partition operation detaches a storage group from the partition
| specified by the {partition-id} portion of the request URI. The virtual storage resources that were created
| for this partition will be deleted as part of this operation.

| On successful execution, the storage group is detached from the partition and the virtual storage
| resources created in this storage group specifically for this partition are removed. The operating system in
| the partition will no longer be able to access the storage volumes defined in the storage group. If this
| operation changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation.

| The URI path must designate an existing Partition object and the API user must have object-access
| permission to it. In addition, storage-group-uri field in the request body must designate an existing
| Storage Group. If either of these conditions are not met, status code 404 (Not Found) is returned.

| In addition, the API user must have action/task permissions to the Partition Details task; otherwise,
| status code 403(Forbidden) is returned.

| If the partition is in any of the transitional states ("starting" or "stopping") or if the CPC is not in a valid
| state, 409 (Conflict) status code is returned. If the partition does not have the "dpm-storage-management"
| feature enabled, a 409 (Conflict) status code is returned.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object-access permission to the Partition object designated by {partition-id}.
| 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, and the response body is a
| standard error response body providing the reason code indicated and associated error message.

Chapter 10. Dynamic Partition Manager (DPM) 237

 Level 04a

| Table 109. Detach Storage Group from Partition: HTTP status and reason codes
| HTTP error status
| code Reason 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 partition.
| 2 The object ID in the storage group URI in request body field
| storage-group-uri does not designate an existing Storage Group object, or
| the API user does not have object-access permission to that storage group.
| 409 (Conflict) 1 Partition status is not valid to perform the operation.
| 2 Partition object with ID {partition-id} was 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".)
| 13 The operation is not supported when the "dpm-storage-management"
| feature is not enabled on the partition.
| 117 The storage-group-uri does not designate a storage group that is attached to
| the partition.
| 124 The storage group object designated by the {storage-group-uri} was busy
| performing some other 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.

| Example HTTP interaction

|

POST /api/partitions/acab6d72-8107-11e8-9d6f-00106f0d81cb/operations/detach-storage-
group HTTP/1.1
content-type:application/json,
x-api-session:1zpqlegsp02sdzr2h04uxhc91ou8fdmxvpn0ukxtaouqg6k3e0
content-length:81,
{
“storage-group-uri”: “/api/storage-groups/519578c6-9569-11e8-a732-00106f0d81cb”
}

Figure 78. Detach Storage Group from Partition: Request

238 HMC Web Services API

 Level 04a

204 No Content
cache-control:no-cache,
date:Wed, 01 Aug 2018 09:00:28 GMT,
server:Hardware management console API web server / 2.0

<No response body>

Figure 79. Detach Storage Group from Partition: Response

| Create HBA
The Create HBA operation creates an HBA and adds it to the specified partition.

HTTP method and URI

POST /api/partitions/{partition-id}/hbas

In this request, the URI variable {partition-id} is the object ID of the partition to which the HBA is to be
added.

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The value to be set as the HBA's name property.
(1-64)
description String Optional The value to be set as the HBA's description property.
(0-1024)
adapter-port-uri String/ Required The value to be set as the HBA's adapter-port-uri
URI property.
device-number String (4) Optional The value to be set as the HBA's device-number property.

Response body contents

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

Field name Type Description

element-uri String/URI The element-uri property of the newly created HBA object.

Description
The Create HBA operation creates and adds a new HBA to the partition specified by the {partition-id}
portion of the request URI.

On successful execution, the element-uri field of the response body and the Location response header
identify the new HBA. An Inventory Change notification is emitted asynchronously to this operation.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

The URI path must designate an existing Partition object and the API user must have object-access
permission to it. In addition, the adapter-port-uri field in the request body must designate an existing
Storage Port of an existing adapter, and the API user must have object-access permission to that adapter.

Chapter 10. Dynamic Partition Manager (DPM) 239

 Level 04a

If either of these conditions is not met, status code 404 (Not Found) is returned. In addition, the API user
must have action task permission to Partition Details task; otherwise, status code 403 (Forbidden) is
returned. If the request body is not valid, status code 400 (Bad Request) is returned with a reason code
indicating the validation error encountered.

If the partition is in any of the transitional states ("starting" or "stopping") or CPC is not in a valid state
| or if the partition has the "dpm-storage-management" feature enabled, 409 (Conflict) status code is
returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id} specified in the request URI.
v Object-access permission to the adapter containing the port designated by the adapter-port-uri field.
v Action/task permission to the Partition Details 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” on page 239, and the Location response header contains the URI of the
newly created object.

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.
Table 110. Create HBA: 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 value of device-number is not in the range as expected by the “Data
model - HBA element object” on page 163.
8 The HBA name provided by the user is already in use by another HBA of
the partition, or the provided device-number is already in use by another
HBA element or by a NIC element of type "iqd" or "osd" of the partition.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the request URI ({partition-id}) does not designated an
existing Partition object, or the API user does not have object-access
permission to the object.
2 The object ID in the Storage Port URI in request body field adapter-port-uri
does not designate an existing Adapter object, or the API user does not have
object-access permission to the object.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with ID {partition-id} was busy and request timed out
6 The state of the CPC hosting partition is not valid to perform the operation.
It must be in one of these valid states: "active", "service-required",
"degraded", or "exceptions".
| 12 The operation is not supported when the "dpm-storage-management"
| feature is enabled on the partition.
116 The partition does not have sufficient resources to perform 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.

240 HMC Web Services API

 Level 04a

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/partitions/4e12c87e-c8b2-11e5-97e4-020000000192/hbas HTTP/1.1

x-api-session: p7gzv1s0wo6ops84jpy88eqspkomjrn0u887n2zm8f8l5pcnd
content-type: application/json
content-length: 134
{
"adapter-port-uri":"/api/adapters/55a89b60-c027-11e5-80b4-020000000192/storage-ports/0",
"device-number":"1007",
"name":"MyHba_7"
}

Figure 80. Create HBA: Request

201 Created
server: zSeries management console API web server / 2.0
location: /api/partitions/4e12c87e-c8b2-11e5-97e4-020000000192/hbas/b6fe29c2-c8b3-11e5-bcda-020000000192
cache-control: no-cache
date: Mon, 01 Feb 2016 07:15:09 GMT
content-type: application/json;charset=UTF-8
content-length: 112
{
"element-uri":"/api/partitions/4e12c87e-c8b2-11e5-97e4-020000000192/hbas/b6fe29c2-c8b3-11e5-bcda-
020000000192"
}

Figure 81. Create HBA: Response

Delete HBA
The Delete HBA operation deletes the HBA and removes it from the specified partition.

HTTP method and URI

DELETE /api/partitions/{partition-id}/hbas/{hba-id}

URI variables:

Name Type Description

{partition-id} String Object ID of the partition from which the HBA is to be removed.
{hba-id} String Element ID of the HBA to be removed from the partition.

Description
The Delete HBA operation deletes the HBA and removes it from the partition specified by the
{partition-id} portion of the request URI. The HBA to be deleted is identified by the {hba-id} variable in the
URI.

Upon successfully removing the HBA, HTTP status code 204 (No Content) is returned and no response
body is provided. An Inventory Change notification is emitted asynchronously to this operation.

Chapter 10. Dynamic Partition Manager (DPM) 241

 Level 04a

If this operation changes the value of any property for which property change notifications are due, those
notifications are issued asynchronously to this operation.

The URI path must designate an existing HBA element of an existing partition and the API user must
have object-access permission to that partition, otherwise status code 404 (Not Found) is returned. In
addition, the API user must have action/task permission to the Partition Details task; otherwise, status
code 403 (Forbidden) is returned.

If the partition is in any of the transitional states ("starting" or "stopping") or CPC is not in a valid state,
409 (Conflict) status code is returned.

| If the partition has the "dpm-storage-management" feature enabled, a 404 (Not Found) status code is
| returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition containing the HBA element specified by the request URI.
v Action/task permission to the Partition Details task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned 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.
Table 111. Delete HBA: 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 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing Partition object, or the API
user does not have object-access permission to it.
| 5 The element ID in the request URI {hba-id} does not designate an existing
| HBA of the partition. Note that a partition has no HBA element objects when
| the "dpm-storage-management" feature is enabled on the partition.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with {partition-id} was busy and request timed out.
6 The state of the CPC hosting partition is not valid to perform the operation.
It must be in one of these valid states: "active", "service-required",
"degraded", or "exceptions".
151 The HBA cannot be deleted because it is currently identified with the
partition's boot device.
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.

242 HMC Web Services API

 Level 04a

Example HTTP interaction

Delete HBA: Request

DELETE /api/partitions/5fca3d9a-c8b2-11e5-97e4-020000000192/hbas/4658f530-
c8b3-11e5-bcda-020000000192 HTTP/1.1
x-api-session: 1xsytajjb0a8oer7bl2s7e7uarli8qb33vh3kenfgv9ibesj7c

Figure 82. Delete HBA: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 01 Feb 2016 09:55:38 GMT

<No response body>

Figure 83. Delete HBA: Response

Update HBA Properties

The Update HBA Properties operation updates one or more writable properties of an HBA designated by
the element ID and object ID of the hosting partition.

HTTP method and URI

POST /api/partitions/{partition-id}/hbas/{hba-id}

URI variables:

Name Type Description

{partition-id} String Object ID of the partition that has the HBA.
{hba-id} String Element ID of the HBA for which properties are to be updated.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined in the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
This operation updates the writable properties of HBA specified by {hba-id} as mentioned in the “Data
model - HBA element object” on page 163.

On successful execution, the HBA object has been updated with the supplied property values and status
code 204 (No Content) is returned without supplying a response body.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Chapter 10. Dynamic Partition Manager (DPM) 243

 Level 04a

The URI path must designate an existing HBA element of an existing partition and the API user must
have object-access permission to that partition, otherwise status code 404 (Not Found) is returned. In
addition, the API user must also have action/task permission to the Partition Details task as well,
otherwise status code 403 (Forbidden) is returned.

The request body is validated against the data model for this object type to ensure that it 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.

If the partition is in any of the transitional states ("starting" or "stopping") or the CPC is not in a valid
state, 409 ( Conflict) status code is returned.

| If the partition has the "dpm-storage-management" feature enabled, a 404 (Not Found) status code is
| returned.

Authorization requirements
This operation has the following authorization requirements:
v Action/task permission to the Partition Details task.
v Object-access permission to the partition containing the HBA element specified by the request URI.

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 112. Update HBA 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 value of device-number is not in the range.
8 The HBA name provided by the user is already in use by another HBA of
the partition, or the provided device-number is already in use by another
HBA element or by a NIC element of type "iqd" or "osd" of the partition.
403 (Forbidden) 1 API user does not have the required permission to this operation.
404 (Not Found) 1 The {partition-id} in the request URI does not designate an existing Partition
object, or the API user does not have object-access permission to it.
| 5 The element ID in the request URI {hba-id} does not designate an existing
| HBA of the partition. Note that a partition has no HBA element objects when
| the "dpm-storage-management" feature is enabled on the partition.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with {partition-id} was busy and request timed out.
6 The state of the CPC hosting the partition is not valid to perform the
operation. It must be in one of these valid 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.

244 HMC Web Services API

 Level 04a

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/partitions/4e12c87e-c8b2-11e5-97e4-020000000192/hbas/09aea4b8-c8b3-11e5-a3ad-
020000000192 HTTP/1.1
x-api-session: 3pwf2qvaioh3fld3vrlwye8zmdq4cckae3s2mtsn5sxu9dv6c0
content-type: application/json
content-length: 44
{
"device-number":"1007",
"name":"MyHba_7"
}

Figure 84. Update HBA Properties: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 01 Feb 2016 09:57:18 GMT

<No response body>

Figure 85. Update HBA Properties: Response

Get HBA Properties

The Get HBA Properties operation retrieves the properties of an HBA designated by its element ID and
object ID of the hosting partition.

HTTP method and URI

GET /api/partitions/{partition-id}/hbas/{hba-id}

URI variables:

Name Type Description

{partition-id} String Object ID of the partition that owns the HBA.
{hba-id} String Element ID of the HBA for which properties are to be returned.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the HBA element object as defined in the “Data model - HBA element object” on page 163.
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
This operation returns the current properties for the HBA specified by element ID {hba-id}.

On successful execution, all of the current properties as defined by the “Data model - HBA element
object” on page 163 are provided in the response body and HTTP status code 200 (OK) is returned.

Chapter 10. Dynamic Partition Manager (DPM) 245

 Level 04a

If the URI path does not designate an existing HBA element of an existing partition or if the API user
does not have object-access permission to that partition or if the partition has the "dpm-storage-
management" feature enabled, a 404 (Not Found) status code is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Partition object in the request URI.

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 245.

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 113. Get HBA 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID in the request URI {partition-id} does not designate an existing
Partition object, or the API user does not have object-access permission to
the object.
| 5 The element ID in the request URI {hba-id} does not designate an existing
| HBA of the partition. Note that a partition has no HBA element objects when
| the "dpm-storage-management" feature is enabled on the partition.

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/4e12c87e-c8b2-11e5-97e4-020000000192/hbas/ea792b18-c8b2-
11e5-a3ad-020000000192 HTTP/1.1
x-api-session: 2xvikaohvoji3npmjrdx2ezrpi7tll6z6zur1chx864oda1f6u

Figure 86. Get HBA Properties: Request

246 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 01 Feb 2016 10:02:29 GMT
content-type: application/json;charset=UTF-8
content-length: 417
{
"adapter-port-uri":"/api/adapters/55e59092-c027-11e5-80b4-020000000192/storage-ports/0",
"class":"hba",
"description":"Test",
"device-number":"1003",
"element-id":"ea792b18-c8b2-11e5-a3ad-020000000192",
"element-uri":"/api/partitions/4e12c87e-c8b2-11e5-97e4-020000000192/hbas/ea792b18-
c8b2-11e5-a3ad-020000000192",
"name":"MyHba_3",
"parent":"/api/partitions/4e12c87e-c8b2-11e5-97e4-020000000192",
"wwpn":"0000000000000007"
}

Figure 87. Get HBA Properties: Response

Reassign Storage Adapter Port

The Reassign Storage Adapter Port operation reassigns the backing storage adapter to which the
specified HBA is associated to a new backing FCP adapter.

HTTP method and URI

POST /api/partitions/{partition-id}/hbas/{hba-id}/operations/reassign-
storage-adapter-port

URI variables:

Name Type Description

{partition-id} String Object ID of the partition that owns the HBA.
{hba-id} String Element ID of the HBA for which properties are to be reassigned.

Request body contents

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

Field name Type Rqd/Opt Description

adapter-port-uri String/ Required The value to be set as the HBA's adapter-port-uri property.
URI

Description
The Reassign Storage Adapter Port operation changes the adapter port associated with specified
partition to different adapter port specified in the request body.

On successful execution, status code 204 (No Content) is returned without supplying a response body.

The request URI must designate an existing HBA element of an existing partition and the API user must
have object-access permission to that partition, otherwise status code 404 (Not Found) is returned

Chapter 10. Dynamic Partition Manager (DPM) 247

 Level 04a

In addition, the API user must have action/task permission to the Partition Details task, otherwise status
code 403 (Forbidden) is returned.

If the partition is in any of the transitional states ("starting" or "stopping") or CPC is not in a valid state,
409 (Conflict) status code is returned.

| If the partition has the "dpm-storage-management" feature enabled, a 404 (Not Found) status code is
| returned.

If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the partition containing the HBA element specified by the request URI.
v Object-access permission to the adapter containing the port designated by the adapter-port-uri field.
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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 114. Reassign Storage Adapter Port: 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 required permission for this operation.
404 (Not Found) 1 The object ID in the request URI {partition-id} does not designate an existing
Partition object, or the API user does not have object-access permission to
the object.
2 The object ID in the Storage Port URI in the request body field
adapter-port-uri does not designate an existing Adapter object, or the API
user does not have object-access permission to the object.
| 5 The element ID in the request URI {hba-id} does not designate an existing
| HBA of the partition. Note that a partition has no HBA element objects when
| the "dpm-storage-management" feature is enabled on the partition.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with {partition-id} was busy and request timed out.
6 The state of the CPC hosting the partition is not valid to perform the
operation. It must be in one of these valid 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.

248 HMC Web Services API

 Level 04a

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/partitions/4e12c87e-c8b2-11e5-97e4-020000000192/hbas/9b76b558-c8b2-11e5-97e4-
020000000192/operations/reassign-storage-adapter-port HTTP/1.1
x-api-session: 4x5d5t0yyqcr52ngjj3zc8y8d1ztaunjkwn8g9bw2uku2iflii
content-type: application/json
content-length: 90
{
"adapter-port-uri":"/api/adapters/55a89b60-c027-11e5-80b4-020000000192/storage-ports/0"
}

Figure 88. Reassign Storage Adapter Port: Request

204 No Content

Figure 89. Reassign Storage Adapter Port: Response

Send OS Command
The Send OS Command operation sends a command to the operating system running in a partition.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/send-os-cmd

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 a JSON object with the following fields:

Field name Type Rqd/Opt Description

is-priority Boolean Optional An indication of whether this is a priority operating
system command. Set to true for priority operating
system commands or false for non-priority operating
system commands. The default is false.
operating-system- String (1-200) Required The text of the operating system command.
command-text

Description
This operation sends a command to the operating system running in the Partition targeted by the request
URI.

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. In
addition to having object-access permission to the Partition, the API user must also have permission to
the Operating System Messages task, otherwise status code 403 (Forbidden) is returned. Status code 409
(Conflict) is returned when the message interface for the operating system running in the targeted
partition is not available. Some examples are when the Partition is not active, there is no operating
system running in the partition, or when the operating system is not enabled for console integration.

Chapter 10. Dynamic Partition Manager (DPM) 249

 Level 04a

On successful execution, the command is sent to the operating system running in the target Partition
object and status code 204 (No Content) is returned without supplying a response body.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}
v Action/task permission for the Operating System Messages 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, 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 user under which the API request was authenticated does not have the
required action/task permission to this operation.
404 (Not Found) 1 The object ID in the URI ({partition-id}) does not designated an existing
Partition object, or the API user does not have object-access permission to
the object.
409 (Conflict) 332 The messages interface is not available.
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

POST /api/partitions/458e44e1-b0c2-391b-83ff-ecfd847295bd/operations/
send-os-cmd HTTP/1.1
x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4qymqa8ktzjep7dbyrll0k
content-type: application/json
content-length: 69
{
“is-priority”: false,
“operating-system-command-text”: “help”
}

Figure 90. Send OS Command: Request

250 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 01 Feb 2016 09:57:18 GMT

<No response body>

Figure 91. Send OS Command: Response

Open OS Message Channel

The Open OS Message Channel operation opens a message channel to the operating system running in
a partition.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/open-os-message-channel

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Request body contents

An optional request body can be specified as a JSON object with the following field:

Field name Type Rqd/Opt Description

include-refresh- Boolean Optional An indication of whether refresh operating system
messages messages should be sent. Set to true to receive refresh
messages, or false to prevent refresh messages. The
default is true.

Response body contents

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

Field name Type Description

topic-name String The name of the os-message-notification topic.
(1-128)

Description
This operation opens a message channel to the operating system running in the Partition targeted by the
request URI. The message channel is implemented as a JMS topic, specifically as an os-message-
notification topic. See Chapter 4, “Asynchronous notification,” on page 47 for information on JMS usage
on the HMC. The API user can connect to this topic to start the flow of new (and refreshed) operating
system messages.

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. In
addition to having object-access permission to the Partition, the API user must also have permission to
the Operating System Messages task, otherwise status code 403 (Forbidden) is returned. Status code 409
(Conflict) is returned when the message interface for the operating system running in the targeted
partition is not available. Some examples are when the Partition is not active, there is no operating
system running in the partition, or when the operating system is not enabled for console integration.

Chapter 10. Dynamic Partition Manager (DPM) 251

 Level 04a

If an os-message-notification topic already exists for this partition for the current API session, the
operation fails.

On successful execution, the message channel is opened and the os-message-notification topic name is
returned in the response body.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}
v Action/task permission for the Operating System Messages task, or the Operating System Messages
task in view-only mode.

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 251.

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.
Table 115. Open OS Message Channel: 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 The user under which the API request was authenticated does not have the
required action/task permission to 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.
409 (Conflict) 331 An os-message-notification topic already exists for this partition for the
current API session. Use the Get Notification Topics operation to determine
the topic name.
332 The messages interface is not available.

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/partitions/458e44e1-b0c2-391b-83ff-ecfd847295bd/operations/open-os-message-channel HTTP/1.1

x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4qymqa8ktzjep7dbyrll0k
content-type: application/json
content-length: 38
{ “include-refresh-messages”: false }

Figure 92. Open OS Message Channel: Request

252 HMC Web Services API

 Level 04a

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
{ “topic-name”: “mikeuser.1osmsg.cpc1.par1” }

Figure 93. Open OS Message Channel: Response

List OS Messages of a Partition

The List OS Messages of a Partition operation lists all currently available operating system (OS)
messages for a partition.

HTTP method and URI

GET /api/partitions/{partition-id}/operations/list-os-messages

In this request, the URI variable {partition-id} is the object ID of the target partition.

Query parameters:

Name Type Rqd/Opt Description

begin-sequence- Long Optional A message sequence number to limit returned messages. OS
number messages with a sequence number less than this are omitted from
the results. If not specified, then no such filtering is performed.
end-sequence- Long Optional A message sequence number to limit returned messages. OS
number messages with a sequence number greater than this are omitted from
the results. If not specified, then no such filtering is performed.

Response body contents

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

Field name Type Description

os-messages Array of Array of nested os-message-info objects as described in the next table. The
os- array elements are in order of increasing sequence number, unless that
message- number has wrapped back around to 0 in which case the element with
info sequence number 0 follows the element with the highest sequence
objects number, thus maintaining the temporal order of the messages.

Each nested os-message-info object contains the following fields:

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. It can be used for
filtering purposes.
message-text String The text of the operating system message.
message-id String The message identifier of the operating system message.
timestamp Timestamp The time when the operating system message was created or -1 if this
information is not available from the corresponding operating system.

Chapter 10. Dynamic Partition Manager (DPM) 253

 Level 04a

Field name Type Description

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.
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 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.

Description
This operation lists the currently available messages from the operating system running in the specified
partition. Only a certain amount of OS message data from each partition is preserved by the HMC for
retrieval by this operation. If the OS produces more than that amount, the oldest non-held, non-priority
OS messages are no longer available. A gap in the sequence numbers indicates a loss of messages. A loss
may be due to that space limitation, or it may be due to the deletion of messages by a console user or the
OS.

If the request URI does not identify a Partition object to which the API user has object-access permission,
HTTP status code 404 (Not Found) is returned. In addition to having object-access permission to the
partition, the API user must also have permission to the Operating System Messages task or the
Operating System Messages task in view-only mode, otherwise status code 403 (Forbidden) is returned.
Status code 409 (Conflict) is returned when the message interface for the operating system running in the
target partition is not available. Some examples are when the partition is not active, there is no operating
system running in the partition, or when the operating system is not enabled for console integration.

If the begin-sequence-number query parameter is specified, then any OS messages with a

sequence-number less than that are omitted from the response. If the end-sequence-number query
parameter is specified, then any OS messages with a sequence-number greater than that are omitted
from the response.

If there are no available OS messages for the specified partition or if no OS messages are to be included
in the response due to filtering, 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 Partition object designated by {partition-id}.
v Action/task permission for the Operating System Messages task, or the Operating System Messages
task in view-only mode.

254 HMC Web Services API

 Level 04a

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 253.

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.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
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) 332 The messages interface is not available.

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/05ca8cc6-8d0c-11e7-804a-00106f0dc539/operations/
list-os-messages HTTP/1.1
x-api-session: 5uj6itqzadjd9rb7o6rjgpf0de5494qop489hv8fdp2k6mfjjf

Figure 94. List OS Messages of a Partition: Request

Chapter 10. Dynamic Partition Manager (DPM) 255

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Thu, 31 Aug 2017 02:02:26 GMT
content-type: application/json;charset=UTF-8
content-length: 593
{
"os-messages":[
{
"is-held":false,
"is-priority":false,
"message-id":1011,
"message-text":"Preparing system.\n",
"os-name":null,
"prompt-text":"",
"sequence-number":0,
"sound-alarm":false,
"timestamp":-1
},
{
"is-held":false,
"is-priority":false,
"message-id":1012,
"message-text":"Starting system.\n",
"os-name":null,
"prompt-text":"",
"sequence-number":1,
"sound-alarm":false,
"timestamp":-1
},
{
"is-held":false,
"is-priority":false,
"message-id":1023,
"message-text":"[ 75.476186] systemd-udevd[66]: starting version 208\n",
"os-name":null,
"prompt-text":"",
"sequence-number":2,
"sound-alarm":false,
"timestamp":-1
}
]
}

Figure 95. List OS Messages of a Partition: Response

Get ASCII Console WebSocket URI

The Get ASCII Console WebSocket URI operation returns a new WebSocket URI for the ASCII console
exposed by the operating system running in this partition.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/get-ascii-console-websocket-uri

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

256 HMC Web Services API

 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

force-takeover Boolean Optional Whether the ASCII console session for this partition opened
from another HMC should be forcefully closed and taken
over by this HMC.

Default: False

Note: This flag does not affect the ASCII console session for
this partition opened from the same HMC.

Response body contents

On successful completion, HTTP status code 200 (OK) is returned and the response body is a JSON object
with the following fields:

Field name Type Description

websocket-uri String The WebSocket URI that should be used to connect to the ASCII console
exposed for the operating system running in this partition.

Description
The Get ASCII Console WebSocket URI operation returns the URI that a WebSocket client should use to
connect to the ASCII console of a partition's operating system. The API client should prepend the secure
protocol ('wss'), the WebSocket host, and port information to the URI before using a WebSocket client to
connect to it. The HMC is the WebSocket host that accepts incoming WebSocket connection requests.

It is possible that another client has already connected to the ASCII console of a partition from the same
HMC or from a different HMC. When the client opens a WebSocket connection with the WebSocket URI
obtained by specifying the force-takeover flag as true, the existing connection from a different HMC is
broken and the same ASCII console session is taken over by this client. It is not possible to break or take
over an existing connection to the ASCII console of a partition from the same HMC, even if the
force-takeover flag was specified as true.

A maximum of 50 WebSocket URIs may be associated with any given API session. If there are already 50
WebSocket URIs associated with the API session, a 409 (Conflict) status code is returned.

Once returned by this operation, a WebSocket URI remains associated with the API session until the
corresponding WebSocket is opened and closed.

A 404 (Not Found) status code is returned if the object-id {partition-id} does not identify a Partition object
to which the API user has object-access permission. If the API user does not have action/task permission
for the Integrated ASCII Console task, a 403 (Forbidden) status code is returned. If the partition is in any
other state than "active" or if there is already an active connection to this partition's ASCII console, a 409
(Conflict) status code is returned unless the active connection is from a different HMC and the
force-takeover flag was specified as true.

Note: This operation does not create a connection to the partition's ASCII console. A connection does not
exist until the client specifically opens a connection using the WebSocket URI returned by this operation.

Chapter 10. Dynamic Partition Manager (DPM) 257

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Partition object designated by {partition-id}
v Action/Task permission to the Integrated ASCII Console task.

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 257.

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.
403 (Forbidden) 1 API user does not have action/task permission to the Integrated ASCII
Console task.
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.
100 There is already a connection to this partition's ASCII console opened from
this HMC.
101 There are already 50 WebSocket URIs associated with this API session.

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/partitions/dc63eeac-ce0d-11e7-8b57-00106f0dc513/operations/
get-ascii-console-websocket-uri HTTP/1.1
x-api-session: 4a4f1hj12hldmm26brcpfnydk663gt6gtyxq4iwto26g2r6wq1
content-type: application/json
content-length: 24
{
"force-takeover":true
}

Figure 96. Get ASCII Console WebSocket URI: Request

258 HMC Web Services API

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 12 Dec 2017 14:50:15 GMT
content-type: application/json;charset=UTF-8
content-length: 85
{
"websocket-uri":"/api/websock/4a4f1hj12hldmm26brcpfnydk663gt6gtyxq4iwto26g2r6wq1/1"
}

Figure 97. Get ASCII Console WebSocket URI: Response

Inventory service data

Information about the partitions managed by the HMC can be optionally included in the inventory data
provided by the Inventory Service.

Inventory entries for partition objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by inventory class, implicitly via a containing
category, or by default) that objects of the class "partition" are to be included. An entry for a particular
partition is included only if the API user has object-access permission to that object as described in the
Get Partition Properties operation.

For each partition to be included, the inventory response array includes the following:
v An array entry for the Partition object itself. This entry is a JSON object with the same contents as is
specified in the response body contents section for “Get Partition Properties” on page 179. That is, the
data provided is the same as would be provided if a Get Partition Properties operation were requested
targeting this object.
v An array entry for each NIC associated with the partition. For each such NIC, an entry is included that
is a JSON object with the same contents as is specified in the response body contents section for “Get
NIC Properties” on page 218.
v An array entry for each virtual function associated with the partition. For each such virtual function,
an entry is included that is a JSON object with the same contents as is specified in the response body
contents section for “Get Virtual Function Properties” on page 209.
v An array entry for each HBA associated with the partition. For each such HBA, an entry is included
that is a JSON object with the same contents as is specified in the response body contents section for
“Get HBA Properties” on page 245.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single partition. This object would appear as a sequence of array entries in the
response array:

Chapter 10. Dynamic Partition Manager (DPM) 259

 Level 04a

{
"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,
"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,

Figure 98. Partition object: Sample inventory data - Response (Part 1)

260 HMC Web Services API

 Level 04a

"cp-processing-weight-capped":false,
"cp-processors":1,
"crypto-configuration":null,
"current-cp-processing-weight":1,
"current-ifl-processing-weight":1,
"degraded-adapters":[],
"description":"",
"has-unacceptable-status":false,
"hba-uris":[],
"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":"Demo_DPM",
"nic-uris":[],
"object-id":"2812231a-048c-11e7-a266-00106f0d81cb",
"object-uri":"/api/partitions/2812231a-048c-11e7-a266-00106f0d81cb",
"os-name":"",
"os-type":"Linux",
"os-version":"3.10.0",

Figure 99. Partition object: Sample inventory data - Response (Part 2)

"parent":"/api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e",
"partition-id":"03",
"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":"DEMODPM",
"ssc-boot-selection":null,
"ssc-dns-servers":[],
"ssc-host-name":null,
"ssc-ipv4-gateway":null,
"ssc-ipv6-gateway":null,
"ssc-master-pw":null,
"ssc-master-userid":null,
"status":"active",
"threads-per-processor":1,
"type":"linux",
"virtual-function-uris":[]
}

Figure 100. Partition object: Sample inventory data - Response (Part 3)

Chapter 10. Dynamic Partition Manager (DPM) 261

 Level 04a

Adapter object
An Adapter object represents a single adapter for a DPM-enabled CPC. The Adapter object APIs provide
access to the set of adapters that are managed by a CPC that is enabled for DPM. APIs exist to query
adapters, update selected properties of physical adapters, and create, delete, and update HiperSockets™.
APIs also exist to query and update properties of the ports of the adapters and to get a list of the
partitions for which an adapter is allocated to provide I/O and virtual functions.

Data model
This object includes the properties that are defined in the “Base managed object properties schema” on
page 60, including the operational-status-related properties, with the following class-specific
specializations:.
Table 116. Adapter object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/ The canonical URI path for an Adapter object is of the form
URI /api/adapters/{adapter-id} where {adapter-id} is the value of
the object-id property of the Adapter object.
object-id — String (36) The unique identifier for the adapter instance.
parent — String/URI The parent of an adapter is conceptually its owning CPC, and so
the parent value is the canonical URI path for the CPC.
class — String (7) The class of an Adapter object is "adapter".
name (w)(pc) String The display name specified for the adapter. The length and
(1-64) character requirements on this property are the same as those of
the name property described in the “Base managed object
properties schema” on page 60. Names must be unique to the other
configured adapters and created HiperSockets for the CPC.
description (w)(pc) String Arbitrary text providing more descriptive information about the
(0-1024) adapter.
status (sc) String The status of the adapter, which must be one of the following
Enum values:
v "active" - The adapter is configured and functioning normally.
v "not-active" - The adapter is configured as not active.
v "not-detected" - The previously configured adapter is no longer
detected; usually indicates that the card has been physically
removed from the system. Not applicable if type is
"hipersockets".
v "exceptions" - The adapter is configured but unavailable due to
an error affecting the adapter hardware. The adapter is not
active.
v "service" - The adapter is configured but unavailable because it
is being serviced.
additional-status — String This property is not supported for adapters and will not be
Enum included in its data model.
acceptable-status — Array of This property is not supported for adapters and will not be
String included in its data model.
Enum

Class specific additional properties

In addition to the properties defined via included schema, this object includes the following additional
class-specific properties:

262 HMC Web Services API

 Level 04a

Table 117. Adapter object: class-specific properties

Supported
"adapter
Name Qualifier Type Description family" values
type (pc) String The type of the adapter. Values: All
Enum v "crypto" - Cryptographic adapter.
v "fcp" - A Fibre Channel attached storage resource.
v "hipersockets" - A HiperSockets virtual adapter.
v "osd" - OSA Direct Express.
v "osm" - OSA-Express for zManager.
v "roce" - RDMA over Converged Ethernet.
v "zedc" - zEnterprise Data Compression.
| v "fc" - Fibre Connection attached storage resource.
| v "not-configured" - The adapter is not configured.
| Currently this applies only to adapters of
| adapter-family "ficon".
| This value will change when the adapter type is
| updated via the Change Adapter Type operation.
adapter-id — String (3) ID of the adapter; three character hex string. This All
string is the PCHID of the physical adapter or the
VCHID of the virtual HiperSockets adapter
adapter-family — String The family of the card detected for this adapter at the All
Enum time of its creation. Values:
v "hipersockets" - A virtual HiperSockets card.
v "osa" - An OSA card.
v "ficon" - A FICON card.
v "roce" - An RDMA over Converged Ethernet card.
v "crypto" - A cryptographic card.
v "accelerator" - Adapter card which provides
acceleration capability.

Chapter 10. Dynamic Partition Manager (DPM) 263

 Level 04a

Table 117. Adapter object: class-specific properties (continued)

Supported
"adapter
Name Qualifier Type Description family" values
detected-card- (pc) String The type detected for the card with the adapter-id of All
type Enum this Adapter object. Values:
v "hipersockets" - A virtual HiperSockets card
v "osa-express-4s-1gb" - An OSA Express4S Gigabit
Ethernet LX/SX.
v "osa-express-4s-10gb" - An OSA Express4S Gigabit
Ethernet LR/SR.
v "osa-express-4s-1000base-t" - An OSA Express4S
1000BASE-T Ethernet.
v "osa-express-5s-1gb" - An OSA Express5S Gigabit
Ethernet LX/SX.
v "osa-express-5s-10gb" - An OSA Express5S Gigabit
Ethernet LR/SR.
v "osa-express-5s-1000base-t" - An OSA Express5S
1000BASE-T Ethernet.
v "osa-express-6s-1gb" - An OSA Express6S Gigabit
Ethernet LX/SX.
v "osa-express-6s-10gb" - An OSA Express6S Gigabit
Ethernet LR/SR.
v "osa-express-6s-1000base-t" - An OSA Express6s
1000BASE-T Ethernet.
v "10gbe-roce-express" - 10 GbE RoCE Express.
v "crypto-express-5s" - Crypto Express5S.
v "crypto-express-6s" - Crypto Express6S.
v "ficon-express-8" - FICON Express8 10KM LX (2, 4,
8 Gbps) or FICON Express8 SX (2, 4, 8 Gbps).
v "ficon-express-8s"- FICON Express8S 10KM LX (2,
4, 8 Gbps) or FICON Express8S SX (2, 4, 8 Gbps).
v "ficon-express-16s"- FICON Express16S 10KM LX
(4, 8, 16 Gbps) or FICON Express16S SX (4, 8, 16
Gbps).
v "ficon-express-16s-plus" - FICON Express 16S+ LX
10KM (4, 8, 16 Gbps) or FICON Express16S+ SX (4,
8, 16 Gbps).
v "zedc-express" - zEnterprise Data Compression
(FPGA Corsa A5).
v "unknown" - The detected-card-type could not be
determined.
| card-location — String (14 or Location of the physical I/O card. ficon, osa,
| 20) roce, crypto,
| 14 or 20 characters: "wwww-xxxx-J.yy" for single-port accelerator
adapters, or "wwww-xxxx-J.yy-J.zz" for two-port
adapters, where:
v wwww - ID of the cage in which the card is
installed.
v xxxx - ID of the slot in the cage in which the card is
installed.
v yy - ID of the first jack/port on the card.
v zz - ID of the second jack/port on the card.

264 HMC Web Services API

 Level 04a

Table 117. Adapter object: class-specific properties (continued)

Supported
"adapter
Name Qualifier Type Description family" values
port-count — Integer Number of ports on the adapter. ficon, osa,
roce,
hipersockets
network-port- — Array of List of network ports for this adapter. Each element in osa, roce,
uris String/URI this array is the canonical URI path of a Network Port hipersockets
object.

The number of entries in this list matches the value of

the port-count property.
storage-port- — Array of List of storage ports for this adapter. Each element in ficon
uris String/URI this array is the canonical URI path of a Storage Port
object.

The number of entries in this list matches the value of

the port-count property.
state (pc) String The current state of the adapter, which must be one of All
Enum the following values:
v "online" - The adapter is online.
v "stand-by" - The adapter has been configured off.
v "reserved" - The adapter has been configured into
service mode.
v "unknown" - The state of the adapter cannot be
determined because of a communications issue.
maximum- (w)(pc) Integer The maximum transmission unit size of the virtual hipersockets
transmission- Enum switch. The maximum frame size is implied by this
unit-size value. Values:
v 8 - 8 KB MTU size and 16 KB maximum frame size.
v 16 - 16 KB MTU size and 24 KB maximum frame
size.
v 32 - 32 KB MTU size and 40 KB maximum frame
size.
v 56 - 56 KB MTU size and 64 KB maximum frame
size.

Chapter 10. Dynamic Partition Manager (DPM) 265

 Level 04a

Table 117. Adapter object: class-specific properties (continued)

Supported
"adapter
Name Qualifier Type Description family" values
configured- (pc) Integer For FCP adapters (type is "fcp"), this value is the ficon, osa,
capacity number of host bus adapters (HBAs) that are roce,
configured, but not necessarily allocated, to the hipersockets,
partitions assigned to the adapter. accelerator

For channel-based network adapters (type is "osd" or

"hipersockets"), this value is the number of
subchannels that are configured, but not necessarily
allocated, to partitions assigned to the adapter.

For Single Root I/O Virtualization (SR-IOV) adapters

(type is "roce", or "zedc"), this value is the number of
virtual PCI functions that are configured, but not
necessarily allocated, to partitions assigned to the
adapter.

| For adapters with type values of "osm", or

| "not-configured", the value will always be 0.

configured-capacity may be larger than

allowed-capacity or maximum-total-capacity, which
indicates that the adapter is over-committed, and
therefore, all partitions that include this adapter in
their configuration cannot be active at the same time.
used-capacity (pc) Integer For FCP adapters (type is "fcp"), this value is the ficon, osa,
number of host bus adapters (HBAs) that are allocated roce,
to partitions assigned to the adapter. hipersockets,
accelerator
For channel-based network adapters (type is "osd" or
"hipersockets"), this value is the number of
subchannels that are allocated to partitions assigned to
the adapter.

For Single Root I/O Virtualization (SR-IOV) adapters

(type is "roce", or "zedc"), this value is the number of
virtual PCI functions that are allocated to partitions
assigned to the adapter.

For adapters with type value "osm", the value will

always be 0.

266 HMC Web Services API

 Level 04a

Table 117. Adapter object: class-specific properties (continued)

Supported
"adapter
Name Qualifier Type Description family" values
allowed- (w)(pc) Integer For FCP adapters (type is "fcp"), this value is the ficon, osa,
capacity maximum number of host bus adapters (HBAs) that roce,
may be allocated to the partitions assigned to the hipersockets,
adapter. For FCP adapters, this property is writable accelerator
and must be an integer from 0 to maximum-total-
capacity.

For channel-based network adapters (type is"osd" or

"hipersockets"), this value is the maximum number of
subchannels that may be allocated to partitions
assigned to the adapter. For these adapters, this
property is read-only and its value will be
automatically defined by the system when the adapter
is configured.

For Single Root I/O Virtualization (SR-IOV) adapters

(type is "roce", or "zedc"), this value is the maximum
number of virtual PCI functions that may be allocated
to partitions assigned to the adapter. For these
adapters, this property is read-only and its value will
be automatically defined by the system when the
adapter is configured.

For adapters with type value "osm", this property is

read-only and its value will always be 0.
maximum-total- (pc) Integer This is the largest permitted value of ficon, osa,
capacity allowed-capacity. roce,
hipersockets,
For adapters with type value "osm", the value will accelerator
always be 0.
channel-path-id (w)(pc) String (2) Channel path ID (CHPID) used by the adapter's ficon, osa,
| partition; two character hex string. This value will be hipersockets
| null when the value of type is "not-configured".

channel-path-id cannot be written if the adapter is

configured to any partition.

Chapter 10. Dynamic Partition Manager (DPM) 267

 Level 04a

Table 117. Adapter object: class-specific properties (continued)

Supported
"adapter
Name Qualifier Type Description family" values
physical- (pc) String Status of the physical channel. Values: all
channel-status Enum v "operating" - The channel path is operating. Maps
to status value "active".
v "no-power" - The power is off for the hardware that
supports the channel path, the channel path is not
operating. Maps to status value "not-active".
v "service" - The path is in single channel service
(SCS) mode and is not in the active I/O
configuration. The channel path is not operating.
Maps to status value "service".
v "stopped" - The channel path is not operating. Maps
to status value "not-active".
v "not-defined" - The channel path is not defined in
the active IOCDS. The channel path is not
operating. Maps to status value "not-active".
v "definition-error" - The channel path that is
specified in the active input/output configuration
data set (IOCDS) does not match the characteristics
of the installed channel, or the channel type is
incompatible with the current storage allocation, or
the level of the installed channel hardware does not
support the definition in the IOCDS. The channel
path is not operating. Maps to status value
"exceptions".
v "suspended" - The channel path is suspended. The
channel path is not operating. Maps to status value
"service".
v "check-stopped" - The channel path is unavailable
due to a permanent machine error affecting the
channel hardware. The channel path is not
operating. Maps to status value "exceptions".
v "wrap-block" - A wrap block is installed on the
channel path's channel interface.
Note: Wrap blocks are used during special
diagnostic tests performed on the channel. Wrap
blocks must be removed before system initialization
to allow the channel to initialize completely.
The channel path is not operating. Maps to status
value "exceptions".
v "permanent-error" - The channel path is unavailable
due to a permanent outboard error. The channel
path is not operating. Maps to status value
"exceptions".
v "initializing" - The firmware is being loaded into
the channel card and then the channel card is
starting. Maps to status value "not-active".

268 HMC Web Services API

 Level 04a

Table 117. Adapter object: class-specific properties (continued)

Supported
"adapter
Name Qualifier Type Description family" values
v "loss-of-signal" - The channel path detected a
link-signal error. The level of the signal on the link
is below the value specified for reliable
communication. Maps to status value "exceptions".
v "loss-of-synchronization" - The channel path
detected a link-signal error. The bit synchronization
with the signal was lost. The channel path is not
operating. Maps to status value "exceptions".
v "not-operational-link" - The channel path detected
a link failure due to a non-operational sequence.
The channel path is not operating. Maps to status
value "exceptions".
v "sequence-time-out" - The channel path detected a
link failure due to a sequence timeout. The channel
path is not operating. Maps to status value
"exceptions".
v "sequence-not-permitted" - The channel path
detected a link failure due to an illegal sequence for
a link. The channel path is not operating. Maps to
status value "exception".
v "terminal-condition" - The channel path is not
available due to an interface-hung condition. This
condition can occur after an interface or channel
error if the control unit or device fails to disconnect
from the interface when requested by the channel.
The channel path is not operating. Maps to status
value "exceptions".
v "offline-signal-received" - The channel path
detected an offline sequence, indicating that the
sender is in offline mode and subsequent link-signal
errors that are detected by the channel path are not
to be reported. For an ES conversion channel, this
condition can occur only when the channel is
wrongly attached to another channel, switch, or
control unit instead of an ESCON Converter. The
channel path is not operating. Maps to status value
"exceptions".
v "fabric-login-sequence-failure" - This condition
means that the channel detected a failure during the
Fabric Login procedure. Maps to status value
"exceptions".
v "port-login-sequence-failure" - This condition
means that the channel detected a failure during the
registration procedure. In order for a FICON
channel to communicate with devices on a control
unit, it must perform a Port Login with that control
unit. Maps to status value "exceptions".
v "state-change-registration-failure" - This condition
means that the channel detected a failure during the
registration procedure. A FICON channel is required
to register with the switch to receive state change
notification. Maps to status value "exceptions".

Chapter 10. Dynamic Partition Manager (DPM) 269

 Level 04a

Table 117. Adapter object: class-specific properties (continued)

Supported
"adapter
Name Qualifier Type Description family" values
v "invalid-attachment-failure" - Occurs when the
channel determines that it is connected to a switch,
but the IOCDS specifies that it should be directly
connected to a control unit or the contrary. Maps to
status value "exceptions".
v "test-mode" - The channel path is in test mode. The
channel path is not operating. Maps to status value
"not-active".
v "bit-error-threshold-exceeded" - The number of bit
errors the channel path detected while receiving or
sending data is more than the threshold set for its
bit error counter. The channel path is not operating.
Maps to status value "exceptions".
v "ifcc-threshold-exceeded" - The number of interface
control checks (IFCCs) the channel path detected is
more than the threshold set for its IFCC counter.
IFCCs may continue to occur; the error logs will not
be created and sent to the Support Element. Maps
to status value "exceptions".
v "io-supressed" - The channel path input/output
(I/O) suppression is active. I/O suppression
prevents the channel subsystem from selecting any
device and fetching the first channel command
word (CCW) of a channel program. The channel
path is not operating. Maps to status value
"not-active".
crypto-number (w)(pc) Integer Identifier of the crypto adapter in the range 0-15. crypto
Crypto number must be unique to other configured
crypto adapters for the CPC.
crypto-type (pc) String Crypto type. Values: crypto
Enum v "accelerator" - Crypto Express5S Accelerator.
v "cca-coprocessor" - Crypto Express5S Coprocessor.
v "ep11-coprocessor" - Crypto Express5S EP11
Coprocessor.
udx-loaded (pc) Boolean true if the configured crypto was UDX-loaded; false crypto
otherwise.

udx-loaded cannot be read, and a null is returned, if

any of the following conditions are true:
v The CPC that contains the cryptographic adapter is
not started.
v The adapter's status is "exceptions".
v The adapter's status is "not-active".
v The adapter's state is not "online".

270 HMC Web Services API

 Level 04a

Table 117. Adapter object: class-specific properties (continued)

Supported
"adapter
Name Qualifier Type Description family" values
tke-commands- (w)(pc) Boolean true if the crypto permits TKE commands; false crypto
enabled otherwise.

tke-command-enabled cannot be read or written, and

a null is returned on a read, if any of the following
conditions are true:
v The CPC that contains the cryptographic adapter is
not started.
v The adapter's status is "exceptions".
v The adapter's status is "not-active".
v The adapter's state is not "online".

Network Port element object

A Network Port element object defines the index and description associated with a network adapter port.
Table 118. Network Port element object properties
Name Qualifier Type Description
element-id — String (1-2) Unique ID for the network port within the scope of the containing
adapter.
element-uri — String/URI The canonical URI path for the network port object, of the form
/api/adapters/{adapter-id}/network-ports/{network-port-id},
where {adapter-id} is the object-id of the adapter, and
{network-port-id} is the element-id of this network port.
parent — String/URI The parent of a network port is its owning adapter, so the parent
value is the canonical URI path for the adapter.
class — String (12) The class of a network port object is "network-port".
index — Integer The index of the port. Adapters whose type is"osd" or
"hipersockets" use a base index of zero while adapters whose type
is "roce" use a base index of one.

If adapter type is "osd" or "hipersockets", values may range from

zero to port-count. Values may go from one to (port-count + 1) if
adapter type is "roce".
name — String (1-64) The name of the network port, which is currently always of the
form "Port #", where # is the index of the network port. This form
is subject to change in the future.
description (w)(pc) String Arbitrary text providing additional descriptive information about
(0-1024) the port.

Storage Port element object

A Storage Port element object defines the index and description associated with a storage adapter port.
Table 119. Storage Port element object properties
Supported
adapter "type"
Name Qualifier Type Description values
element-id — String (1-2) Unique ID for the storage port within All
the scope of the containing adapter.

Chapter 10. Dynamic Partition Manager (DPM) 271

 Level 04a

Table 119. Storage Port element object properties (continued)

Supported
adapter "type"
Name Qualifier Type Description values
element-uri — String/URI The canonical URI path for the storage All
port object, of the form
/api/adapters/{adapter-id}/storage-
ports/{storage-port-id}, where
{adapter-id} is the object-id of the
adapter, and {storage-port-id} is the
element-id of this storage port.
parent — String/URI The parent of a storage port is its All
owning adapter, so the parent value is
the canonical URI path for the adapter.
class — String (12) The class of a storage port object is All
"storage-port".
index — Integer The index of the port. Adapters whose All
type is "fcp" use a base index of zero.

If adapter type is "fcp", values may

range from zero to port-count.
name — String (1-64) The name of the storage port, which is All
currently always of the form "Port #",
where # is the index of the storage port.
This form is subject to change in the
future.
description (w)(pc) String (0-1024) Arbitrary text providing additional All
descriptive information about the port.
fabric-id (pc) String (16) The World Wide Name (WWN) of the fcp
uplink Fibre Channel switch.

When an adapter is not configured into a

storage network, null is returned.
| connection-endpoint- (w)(pc) String/URI The canonical URI of the storage switch fc
| uri or storage subsystem to which this
| adapter is connected.

| This value may be null, which indicates

| that the adapter identified by
| connection-endpoint-uri is not
| connected to anything.
| connection-endpoint- — String Enum The class of the object to which this fc
| class adapter is connected. Values:
| v "storage-subsystem" – The adapter is
| directly connected to a storage
| subsystem.
| v "storage-switch" – The adapter is
| connected to a storage switch.

| This value will be null when

| connection-endpoint-uri is null and
| non-null when connection-endpoint-uri
| is non-null.

272 HMC Web Services API

 Level 04a

List Adapters of a CPC

The List Adapters of a CPC operation lists the adapters managed by the CPC with the given identifier.

HTTP method and URI

GET /api/cpcs/{cpc-id}/adapters

In this request, the URI variable {cpc-id} is the object ID of the CPC object.

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern to limit returned objects to those that have a matching
name property
adapter-id String Optional Filter pattern to limit returned objects to those that have a matching
adapter-id property.
adapter-family String Optional Filter string to limit returned objects to those that have a matching
Enum adapter-family property.

Value must be a valid adapter adapter-family 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 adapter type property.

status String Optional Filter string to limit returned objects to those that have a matching
Enum status property.

Value must be a valid adapter status property value.

Response body contents

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

Field name Type Description

adapters Array of Array of adapter-info objects, described in the next table. Returned array
adapter- may be empty.
info
objects

Each nested adapter-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the Adapter object.
URI
name String The name property of the Adapter object.
adapter-id String The adapter-id property of the Adapter object.
adapter-family String The adapter-family property of the Adapter object.
Enum
type String The type property of the Adapter object.
Enum
status String The status property of the Adapter object.
Enum

Chapter 10. Dynamic Partition Manager (DPM) 273

 Level 04a

Description
This operation lists the adapters that are managed by the identified CPC. The object-uri, name,
adapter-id, adapter-family, type, and status are provided for each.

If the object-id {cpc-id} does not identify a CPC object to which the API user has object-access permission,
a 404 (Not Found) status code is returned. If the CPC identified by {cpc-id} is not enabled for DPM, an
empty list is returned.

If the name or adapter-id query parameters are specified, the returned list is limited to those adapters
that have a same-named property matching the specified filter pattern. If the name or adapter-id
parameter is omitted, this filtering is not done for the corresponding property.

If the adapter-family, type or status query parameters are specified, the parameter is validated to ensure
it is a valid value for the same-named property according to the data model. If the value is not valid, a
400 (Bad Request) is returned. If the value is valid, the returned list is limited to those adapters that have
a corresponding property matching the specified value. If the adapter-family, type or status parameter is
omitted, this filtering is not done for the corresponding property.

An adapter is included in the list only if the API user has object-access permission for that object. If the
specified CPC is a manager of an adapter but the API user does not have permission to it, that object is
simply omitted from the list but no error status code results.

If no adapters are to be included in the results due to filtering or lack of object-access permission, 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 whose object-id is specified in the request URI.
v Object-access permission to any adapter 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 273.

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 120. List Adapters of a CPC: 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.
14 A query parameter defines an invalid value.
404 (Not Found) 1 A CPC with the object ID {cpc-id} does not exist on the HMC or the API user
does not have object-access permission for it.
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.

274 HMC Web Services API

 Level 04a

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/87dbe268-0b43-362f-9f80-c79923cc4a29/adapters
x-api-session:3aonctd6ljeg2k4amfb4sz2rb6yo2esgah7dtlpgofor3rzgk1

<no request body>

Figure 101. List Adapters of a CPC: Request

200 OK
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:30:36 GMT",
"content-type":"application/json;charset=UTF-8",
"content-length":"884",
{
"adapters":[
{
"adapter-family":"osa",
"adapter-id":"18C",
"name":"OSD 018C Z15B-04",
"object-uri":"/api/adapters/e77d39f8-c930-11e5-a978-020000000338",
"status":"active",
"type":"osd"
},
{
"adapter-family":"crypto",
"adapter-id":"1C4",
"name":"Crypto 01C4 Z15B-21",
"object-uri":"/api/adapters/f7956dc4-c930-11e5-a978-020000000338",
"status":"not-active",
"type":"crypto"
},
{
"adapter-family":"ficon",
"adapter-id":"141",
"name":"FCP 0141 Z22B-07",
"object-uri":"/api/adapters/d71902a4-c930-11e5-a978-020000000338",
"status":"active",
"type":"fcp"
}
]
}

Figure 102. List Adapters of a CPC: Response

Get Adapter Properties

The Get Adapter Properties operation retrieves the properties of a single Adapter object that is
designated by its object-id.

HTTP method and URI

GET /api/adapters/{adapter-id}

In this request, the URI variable {adapter-id} is the object ID of the Adapter object for which properties are
to be obtained.

Chapter 10. Dynamic Partition Manager (DPM) 275

 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 Adapter object as defined in the “Data model” on page 262. 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
Returns the current values of the properties for the adapter object as defined in the “Data model” on
page 262.

If the object-id {adapter-id} does not identify an adapter object to which the API user has object-access
permission, a 404 (Not Found) status code is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the adapter whose object-id is {adapter-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 An adapter with object ID {adapter-id} does not exist on the HMC 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/adapters/d71902a4-c930-11e5-a978-020000000338
x-api-session:
34ccos1y7i88xnu1jbpl9ekpdnar1hwxujg62ots98p3rrvjoy

<no request body>

Figure 103. Get Adapter Properties: Request

276 HMC Web Services API

 Level 04a

200 OK
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:34:11 GMT",
"content-type":"application/json;charset=UTF-8",
"content-length":"670",
{
"adapter-family":"ficon",
"adapter-id":"141",
"allowed-capacity":32,
"card-location":"Z22B-D207-J.01",
"channel-path-id":"01",
"class":"adapter",
"configured-capacity":1,
"description":"",
"detected-card-type":"ficon-express-8",
"maximum-total-capacity":255,
"name":"FCP 0141 Z22B-07",
"object-id":"d71902a4-c930-11e5-a978-020000000338",
"object-uri":"/api/adapters/d71902a4-c930-11e5-a978-020000000338",
"parent":"/api/cpcs/87dbe268-0b43-362f-9f80-c79923cc4a29",
"physical-channel-status":"operating",
"port-count":1,
"state":"online",
"status":"active",
"storage-port-uris":[
"/api/adapters/d71902a4-c930-11e5-a978-020000000338/storage-ports/0"
],
"type":"fcp",
"used-capacity":1
}

Figure 104. Get Adapter Properties: Response

Update Adapter Properties

The Update Adapter Properties operation updates one or more of the writable properties of an adapter.

HTTP method and URI

POST /api/adapters/{adapter-id}

In this request, the URI variable {adapter-id} is the object ID of the Adapter object for which properties are
to be updated.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the “Data model” on
page 262. The JSON object can and should omit fields for properties whose values are not to be changed
by this operation.

Fields are only valid if they are supported for an adapter of the targeted type. For instance, an adapter
with type property "fcp" may define a description property (all types) but not a maximum-transmission-
unit-size property (HiperSockets only).

Chapter 10. Dynamic Partition Manager (DPM) 277

 Level 04a

Description
This operation updates an adapter's properties with the values specified.

If the API user does not have action/task permission to the Adapter Details task, a 403 (Forbidden)
status code is returned. A 404 (Not Found) status code is returned if the object-id {adapter-id} does not
identify an Adapter object to which the API user has object-access permission. If the adapter status is
"definition-error", a 409 (Conflict) status code is returned; in this case either a valid card must be
installed or the adapter must have its configuration removed and a new configuration added.

If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because
the document defines a field that is not supported for the given adapter type.

If the request body contents are valid, the adapter's properties are updated to their corresponding request
body content's field's values. All fields are optional and may be excluded from the request body; if a field
is not found in the request body, its property's value will not be modified.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the adapter whose object ID is {adapter-id}.
v Action/task permission to the Adapter 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.
Table 121. Update Adapter Properties: HTTP status and reason codes
Reason
HTTP error status 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 An adapter with the name specified in the request body already exists on its
parent CPC.
18 An updated property is not valid for an adapter's adapter-family.
420 A crypto adapter for the CPC is already configured with the given
crypto-number.
403 (Forbidden) 1 API user does not have action permission to the Adapter Details task.
404 (Not Found) 1 An adapter with the object ID {adapter-id} does not exist on the HMC or the
API user does not have object-access permission for it.

278 HMC Web Services API

 Level 04a

Table 121. Update Adapter Properties: HTTP status and reason codes (continued)
Reason
HTTP error status code code Description
409 (Conflict) 1 Adapter status is not valid to perform the operation (does not allow the
updating of a specified adapter property).
2 Adapter object with the object ID {adapter-id} was busy and request timed
out.
420 The given allowed-capacity value is not valid because it is less than the
current used-capacity value.
421 The tke-commands-enabled property cannot be updated when the CPC has
not been started.
422 The tke-commands-enabled property cannot be updated when the current
crypto-type value is "cca-coprocessor".
423 The tke-commands-enabled property cannot be updated when the current
status value is "exceptions".
424 The tke-commands-enabled property cannot be updated when the current
status value is "not-active".
425 The tke-commands-enabled property cannot be updated when the current
adapter-state value is "online".
429 The channel-path-id property cannot be updated when the adapter is
configured to any partition.
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

POST /api/adapters/d71902a4-c930-11e5-a978-020000000338
x-api-session:1nnqtc5mo3yntwilbk96er2jekdekba2nvv3ivphfvmdqym8po
content-type: application/json
content-length: 33
{
"description":"My FCP adapter"
}

Figure 105. Update Adapter Properties: Request

204 No Content
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:35:11 GMT",

<no response body>

Figure 106. Update Adapter Properties: Response

Change Crypto Type

The Change Crypto Type operation reconfigures a cryptographic adapter to a different crypto type. This
operation is only supported for cryptographic adapters.

Chapter 10. Dynamic Partition Manager (DPM) 279

 Level 04a

HTTP method and URI

POST /api/adapters/{adapter-id}/operations/change-crypto-type

In this request, the URI variable {adapter-id} is the object ID of the target cryptographic Adapter object.

Request body contents

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

Field name Type Rqd/Opt Description

crypto-type String Required The value to be set as the cryptographic adapter's crypto-type
Enum property. Values:
v "accelerator" - Crypto Express5S Accelerator.
v "cca-coprocessor" - Crypto Express5S Coprocessor.
v "ep11-coprocessor" - Crypto Express5S EP11 Coprocessor.
zeroize Boolean Optional Specifies whether the cryptographic adapter will be zeroized when
it is reconfigured to a crypto-type of "accelerator".

This field is only valid when crypto-type is "accelerator".

Default: true

Description
This operation reconfigures a cryptographic adapter to a new crypto type. For a cryptographic adapter
that is becoming an accelerator, the adapter may optionally be zeroized as part of the reconfiguration
process. A cryptographic adapter must be varied offline before its crypto type can be changed.

If the API user does not have action/task permission to the Adapter Details task, a 403 (Forbidden)
status code is returned. A 404 (Not Found) status code is returned if the object-id {adapter-id} does not
identify a crypto adapter object to which the API user has object-access permission. If the given
crypto-type is not valid, a 400 (Bad Request) status code is returned. If the adapter's adapter-family is not
"crypto", a 404 (Not Found) status code is returned. If the adapter is online (state is "online"), a 409
(Conflict) status code is returned. If the CPC that contains the cryptographic adapter has not been started,
a 409 (Conflict) status code is returned.

If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because
the document defines a field that is not supported for the given adapter type.

If the request body contents are valid, the cryptographic adapter's crypto type is changed to the new
value specified in the request body.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the adapter whose object ID is {adapter-id}
v Action/task permission to the Adapter Details task.

HTTP status and reason codes

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

280 HMC Web Services API

 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.
Table 122. Change Crypto Type: 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 crypto-type value in the request body is not valid.
15 The zeroize value in the request body is not applicable with this
crypto-type.
403 (Forbidden) 1 The API user does not have action/task permission to the Adapter Details
task.
404 (Not Found) 1 An adapter with object ID {adapter-id} does not exist on the HMC or the API
user does not have object-access permission to it.
4 The operation does not support an adapter of the given adapter-family.
409 (Conflict) 1 Adapter status is not valid to perform the operation (does not allow the
updating of a specified adapter property).
2 Adapter object with ID {adapter-id} is not started.
421 The CPC containing the adapter with object ID {adapter-id} is not started.
426 Adapter adapter-state is "online".
428 The adapter is already configured to be the requested crypto-type.
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

POST /api/adapters/f7956dc4-c930-11e5-a978-020000000338/operations/change-crypto-type
x-api-session: 4polovirzt2a8qts11nt5ea7mr1it9q1bhez3h3ukh7wvnb8e4
content-type: application/json
content-length: 35
{
"crypto-type":"ep11-coprocessor"
}

Figure 107. Change Crypto Type: Request

204 No Content
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:38:40 GMT",

<no response body>

Figure 108. Change Crypto Type: Response

Chapter 10. Dynamic Partition Manager (DPM) 281

 Level 04a

Create Hipersocket
The Create Hipersocket operation creates and configures a HiperSockets adapter (type is "hipersockets").

HTTP method and URI

POST /api/cpcs/{cpc-id}/adapters

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The value to be set as the adapter's name property. The
(1-64) name value must be unique among all other adapters
owned by the targeted CPC.
description String Optional The value to be set as the adapter's description property.
(0-1024)
Default value: An empty string.
port-description String Optional The value to be set as the description property of the
(0-1024) HiperSocket's single network-port.

Default value: An empty string.

maximum- Integer Optional The value to be set as the adapter's maximum-
transmission-unit- Enum transmission-unit-size property.
size
Default value: 8

Response body contents

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

Field name Type Description

object-uri String/URI The object-uri of the newly created Adapter object.

Description
This operation creates and configures a HiperSocket 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.

If the API user does not have action/task permission to Create HiperSockets Adapter task, a 403
(Forbidden) status code is returned. If the object-id {cpc-id} does not identify a CPC object to which the
API user has object-access permission, a 404 (Not Found) status code is returned. If the CPC identified by
{cpc-id} already contains an adapter with the specified name, a 400 (Bad Request) status code is returned.
If the CPC identified by {cpc-id} is not enabled for DPM, a 409 (Conflict) status code is returned. If the
CPC identified by {cpc-id} already contains the number of HiperSockets identified by its
maximum-hipersockets property, a 409 (Conflict) status code is returned.

If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because
the document defines a field that is not supported for the given adapter type.

If the request body contents are valid, the HiperSocket is created and its properties are configured to their
corresponding request body content's field's values. If a field is not found in the request body, its
property's value will be defaulted.

282 HMC Web Services API

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Action/task permission to the Create HiperSockets Adapter task.
v Object-access permission to the CPC whose object ID is {cpc-id}.

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 282.

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.
Table 123. Create Hipersocket: 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 An adapter with the name specified in the request body already exists.
403 (Forbidden) 1 The API user does not have the action/task permission to the Create
HiperSockets Adapter task.
404 (Not Found) 1 A CPC with object ID {cpc-id} does not exist on the HMC or the API user
does not have object-access permission for it.
409 (Conflict) 5 A CPC with object ID {cpc-id} is not enabled for DPM.
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.
427 A CPC with object ID {cpc-id} already has the maximum number of
HiperSockets adapters (identified by its maximum-hipersockets property)
defined.
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

POST /api/cpcs/87dbe268-0b43-362f-9f80-c79923cc4a29/adapters
x-api-session: 3mwtrej0fkbg719l3jr5tvxyl2fd6h35que4x8jrukcl7l1802
content-type: application/json
content-length: 59
{
"name":"hiper1",
"description":"My hipersocket adapter"
}

Figure 109. Create Hipersocket: Request

Chapter 10. Dynamic Partition Manager (DPM) 283

 Level 04a

201 Created
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:41:57 GMT",
"location":"/api/adapters/542b9406-d033-11e5-9f39-020000000338",
"content-type":"application/json;charset=UTF-8",
"content-length":"67",
{
"object-uri":"/api/adapters/542b9406-d033-11e5-9f39-020000000338"
}

Figure 110. Create Hipersocket: Response

Delete Hipersocket
The Delete Hipersocket operation deletes a HiperSocket adapter.

HTTP method and URI

DELETE /api/adapters/{adapter-id}

In this request, the URI variable {adapter-id} is the object ID of the adapter to be deleted.

Description
This operation deletes a HiperSocket adapter. An Inventory Change notification is emitted
asynchronously to this operation.

If the API user does not have action/task permission to Delete HiperSocket, a 403 (Forbidden) status
code is returned. A 404 (Not Found) status code is returned if the object-id {adapter-id} does not identify
an adapter object to which the API user has object-access permission. If the adapter is not a HiperSocket
(adapter-family is not "hipersockets"), a 404 (Not Found) is returned. If the adapter is currently
configured to any partition, a 409 (Conflict) is returned.

This operation deletes the identified adapter, and removes the HiperSocket adapter from the CPC.

Authorization requirements
This operation has the following authorization requirements:
v Action/task permission to the Delete HiperSocket task.
v Object-access permission to the adapter whose object ID is {adapter-id}.

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.
Table 124. Delete Hipersocket: 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.

284 HMC Web Services API

 Level 04a

Table 124. Delete Hipersocket: HTTP status and reason codes (continued).
HTTP error status Reason
code code Description
403 (Forbidden) 1 The API user does not have action/task permission to the Delete
HiperSocket task.
404 (Not Found) 1 An adapter with object-id {adapter-id} does not exist on the HMC or the API
user does not have object-access permission for it.
4 The operation does not support an adapter of the given type.
409 (Conflict) 2 Adapter object with ID {adapter-id} was busy and request timed out.
430 The HiperSocket adapter cannot be deleted because it is currently assigned
to one or more partitions.
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/adapters/542b9406-d033-11e5-9f39-020000000338
x-api-session:
62ykfwnk1ds6raibywt03j6ta8g146q06hjneovt2is3lplwl

<no request body>

Figure 111. Delete Hipersocket: Request

204 No Content
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:42:51 GMT",

<no response body>

Figure 112. Delete Hipersocket: Response

Get Partitions Assigned to Adapter

The Get Partitions Assigned to Adapter operation lists the partitions to which the adapter is configured
to provide I/O and virtual functions. This operation is not supported for adapters whose type is "osm".

HTTP method and URI

GET /api/adapters/{adapter-id}/operations/get-partitions-assigned-to-adapter

In this request, the URI variable {adapter-id} is the object ID of the Adapter object whose partitions should
be returned.

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern to limit returned Partition objects to those that have a
matching name property

Chapter 10. Dynamic Partition Manager (DPM) 285

 Level 04a

Name Type Rqd/Opt Description

status String Optional Filter string to limit returned Partition objects to those that have a
Enum matching status property.

Value must be a valid partition status property value.

Response body contents

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

Field name Type Description

partitions-assigned-to- Array of Array of partition-info objects, described in the next table.
adapter 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 current value of the name property of the partition.
status String The current value of the status property of the Partition object.
Enum

Description
The Get Partitions Assigned to Adapter operation lists the partitions to which the adapter is configured.
The object URI, display name, and status information are provided for each.

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, this filtering is not done.

If the status query parameter is specified, the parameter is validated to ensure it is a valid value for the
status property according to the partition data model. If the value is not valid, a 400 (Bad Request) is
returned. If the value is valid, the returned list is limited to those partitions that have the specified status
value. If the status parameter is omitted, this filtering is not done.

A 404 (Not Found) status code is also returned if the object-id {adapter-id} does not identify an adapter
object to which the API user has object-access permission. If the adapter's type is "osm" a 404 (Not
Found) status code is returned.

If no partitions are to be included in the results due to filtering (or no partitions exist), 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 adapter whose object ID is {adapter-id}.

286 HMC Web Services API

 Level 04a

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 286.

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.
Table 125. Get Partitions Assigned to Adapter: 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.
14 A status query parameter defines an invalid value.
404 (Not Found) 1 An adapter with object-id {adapter-id} does not exist on the HMC or the API
user does not have object-access permission for it.
4 An adapter with type of "osm" cannot be assigned to any partitions.

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/adapters/d71902a4-c930-11e5-a978-020000000338/operations/get-partitions-assigned-to-adapter
x-api-session:
2gr3xkfjj6991vvlwpmnkys8814y68i4anucrudo90ytylfuo5

<no request body>

Figure 113. Get Partitions Assigned to Adapter: Request

200 OK
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:47:42 GMT",
"content-type":"application/json;charset=UTF-8",
"content-length":"140",
{
"partitions-assigned-to-adapter":[
{
"name":"MyPartition",
"object-uri":"/api/partitions/c0430acc-c9c9-11e5-be4f-020000000338",
"status":"active"
}
]
}

Figure 114. Get Partitions Assigned to Adapter: Response

Get Network Port Properties

The Get Network Port Properties operation retrieves the properties of a single Network Port element
object.

Chapter 10. Dynamic Partition Manager (DPM) 287

 Level 04a

HTTP method and URI

GET /api/adapters/{adapter-id}/network-ports/{network-port-id}

In this request, the URI variable {adapter-id} is the object ID of the Adapter object and the URI variable
{network-port-id} is the element ID of the Network Port object.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the network port object as defined in the “Data model” on page 262. 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
Returns the current values of the properties for the network port object as defined in the “Data model”
on page 262.

A 404 (Not Found) status code is returned if the object-id {adapter-id} does not identify an adapter object
to which the API user has object-access permission or if the element-id {network-port-id} does not identify
a network port in the adapter. If the adapter type is not "osd", "roce" or "hipersockets", a 404 (Not
Found) status code is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the adapter whose object ID is {adapter-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.
Table 126. Get Network Port 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.
404 (Not Found) 1 An adapter with object ID {adapter-id} does not exist on the HMC or the API
user does not have object-access permission for it.
4 The operation does not support an adapter of the given type.
5 A network port with element-id {network-port-id} does not exist for the
adapter on the HMC.

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

288 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/adapters/e77d39f8-c930-11e5-a978-020000000338/network-ports/0
x-api-session:
54dwyb1qutbd5ck8ultlmh752r7lfi3ljbk8pt9814e6j1g1wu

<no request body>

Figure 115. Get Network Port Properties: Request

200 OK
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:51:27 GMT",
"content-type":"application/json;charset=UTF-8",
"content-length":"229",
{
"class":"network-port",
"description":"",
"element-id":"0",
"element-uri":"/api/adapters/e77d39f8-c930-11e5-a978-020000000338/network-ports/0",
"index":0,
"name":"Port 0",
"parent":"/api/adapters/e77d39f8-c930-11e5-a978-020000000338"
}

Figure 116. Get Network Port Properties: Response

Update Network Port Properties

The Update Network Port Properties operation updates one or more of the writable properties of a
Network Port object. This operation only supports configured adapters whose type is "osd", "roce", or
"hipersockets".

HTTP method and URI

POST /api/adapters/{adapter-id}/network-ports/{network-port-id}

In this request, the URI variable {adapter-id} is the object ID of the Adapter object and the URI variable
{network-port-id} is the element ID of the Network Port object.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the “Data model” on
page 262. The JSON object can and should omit fields for properties whose values are not to be changed
by this operation.

Description
This operation updates a network port's properties with the values specified.

If the API user does not have action/task permission to the Adapter Details task, a 403 (Forbidden)
status code is returned. A 404 (Not Found) status code is returned if the object-id {adapter-id} does not
identify an adapter object to which the API user has object-access permission or if the element-id

Chapter 10. Dynamic Partition Manager (DPM) 289

 Level 04a

{network-port-id} does not identify a network port in the adapter. If the adapter type is not "osd", "roce"
or "hipersockets", a 404 (Not Found) status code is returned.

If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because
the document defines a field that is not supported.

If the request body contents are valid, the network port's properties are updated to their corresponding
request body content's field's values. All fields are optional and may be excluded from the request body;
if a field is not found in the request body, its property's value will not be modified.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the adapter whose object ID is {adapter-id}.
v Action/task permission to the Adapter 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.
Table 127. Update Network Port 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.
403 (Forbidden) 1 API user does not have action/task permission to the Adapter Details task.
404 (Not Found) 1 An adapter with the object ID {adapter-id} does not exist on the HMC or the
API user does not have object-access permission for it.
4 The operation does not support an adapter of the given type.
5 A network port with element-id {network-port-id} does not exist for the
adapter on the HMC.
409 (Conflict) 2 Adapter object with ID {adapter-id} was busy and request timed out.
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.

290 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/adapters/e77d39f8-c930-11e5-a978-020000000338/network-ports/0
x-api-session: 3y0dr1g0lob607lzurmcwggc2lu4vbjjjiskngz26uno8pa8cz
content-type: application/json
content-length: 30
{
"description":"My OSA port"
}

Figure 117. Update Network Port Properties: Request

204 No Content
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:52:01 GMT",

<no response body>

Figure 118. Update Network Port Properties: Response

Get Storage Port Properties

The Get Storage Port Properties operation retrieves the properties of a single Storage Port element object.

HTTP method and URI

GET /api/adapters/{adapter-id}/storage-ports/{storage-port-id}

In this request, the URI variable {adapter-id} is the object ID of the Adapter object and the URI variable
{storage-port-id} is the element ID of the Storage Port object.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the storage port object as defined in the “Data model” on page 262. 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
Returns the current values of the properties for the storage port object as defined in the “Data model” on
page 262.

A 404 (Not Found) status code is returned if the object-id {adapter-id} does not identify an adapter object
to which the API user has object-access permission or if the element-id {storage-port-id} does not identify a
storage port in the adapter. If the adapter type is not "fcp", a 404 (Not Found) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the adapter whose object ID is {adapter-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.”

Chapter 10. Dynamic Partition Manager (DPM) 291

 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.
Table 128. Get Storage Port 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.
404 (Not Found) 1 An adapter with the object ID {adapter-id} does not exist on the HMC or the
API user does not have object-access permission for it.
5 A storage port with element-id of {storage-port-id} does not exist for the
adapter on the HMC.

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/adapters/e7b8811c-9fe7-11e8-bc9a-fa163e3c2af4/storage-ports/0 HTTP/1.1

x-api-session: 46jg2ldhqdx5k27ty3owaiipupfkvmy3bksas8ih3j4wp0exwk

Figure 119. Get Storage Port Properties: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 14 Aug 2018 19:07:51 GMT
content-type: application/json;charset=UTF-8
content-length: 361
{
"class":"storage-port",
"connection-endpoint-class":"storage-switch",
"connection-endpoint-uri":"/api/storage-switches/09f4f570-9fe9-11e8-8c0c-fa163e3c2af4",
"description":"",
"element-id":"0",
"element-uri":"/api/adapters/e7b8811c-9fe7-11e8-bc9a-fa163e3c2af4/storage-ports/0",
"index":0,
"name":"Port 0",
"parent":"/api/adapters/e7b8811c-9fe7-11e8-bc9a-fa163e3c2af4"
}

Figure 120. Get Storage Port Properties: Response

Update Storage Port Properties

The Update Storage Port Properties operation updates one or more of the writable properties of a
storage port. This operation only supports configured adapters whose type is "fcp".

HTTP method and URI

POST /api/adapters/{adapter-id}/storage-ports/{storage-port-id}

In this request, the URI variable {adapter-id} is the object ID of the Adapter object and the URI variable
{storage-port-id} is the element ID of the Storage Port object.

292 HMC Web Services API

 Level 04a

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
This operation updates a storage port's properties with the values specified.

If the API user does not have action/task permission to the Adapter Details task, a 403 (Forbidden)
status code is returned. A 404 (Not Found) status code is returned if the object-id {adapter-id} does not
identify an adapter object to which the API user has object-access permission or if the element-id
{storage-port-id} does not identify a storage port in the adapter. If the adapter type is not "fcp", a 404
(Not Found) status code is returned.

If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because
the document defines a field that is not supported.

If the request body contents are valid, the storage port's properties are updated to their corresponding
request body content's field's values. All fields are optional and may be excluded from the request body;
if a field is not found in the request body, its property's value will not be modified.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the adapter whose object ID is {adapter-id}.
v Action/task permission to the Adapter 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.
Table 129. Update Storage Port 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.
403 (Forbidden) 1 API user does not have action/task permission to the Adapter Details task.
404 (Not Found) 1 An adapter with the object ID {adapter-id} does not exist on the HMC or the
API user does not have object-access permission for it.
4 The operation does not support an adapter of the given type.
5 A storage port with element-id of {storage-port-id} does not exist for the
adapter on the HMC.

Chapter 10. Dynamic Partition Manager (DPM) 293

 Level 04a

Table 129. Update Storage Port Properties: HTTP status and reason codes (continued)
HTTP error status Reason
code code Description
409 (Conflict) 2 Adapter object with the ID {adapter-id} was busy and the request timed out
455 A direct endpoint connection cannot be made to a storage subsystem when
storage fabrics are defined.
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

POST /api/adapters/d71902a4-c930-11e5-a978-020000000338/storage-ports/0
x-api-session: 4sw8s1089cczsejp5vzonbleyrvwsmx6edkqdudskevrcp0bvf
content-type: application/json
content-length: 30
{
"description":"My FCP port"
}

Figure 121. Update Storage Port Properties: Request

204 No Content
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:50:05 GMT",

<no response body>

Figure 122. Update Storage Port Properties: Response

| Change Adapter Type

| The Change Adapter Type operation reconfigures an adapter from one type to another. Currently, only
| storage adapters can be reconfigured. Storage adapter instances represent daughter cards on a physical
| storage card. Current storage cards require both daughter cards to be configured to the same protocol, so
| changing the configuration of the targeted adapter will also change the configuration of the adapter
| instance that represents the other daughter card on the same physical adapter. API clients that need to
| determine the related adapter instance can do so by finding the storage adapter card with a matching
| first 9 characters (card ID and slot ID) of their card-location property values.

| HTTP method and URI

| POST /api/adapters/{adapter-id}/operations/change-adapter-type

| In this request, the URI variable {adapter-id} is the object ID of the Adapter object.

294 HMC Web Services API

 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
| type String Required The value to be set as the adapter's type property. Values:
| Enum v "fcp" - Fibre Channel attached storage resource.
| v "fc" - Fibre Connection attached storage.
| v "not-configured" - The adapter is not configured.
|

| Description

| This operation reconfigures a storage adapter to support a new storage protocol.

| If the API user does not have action/task permission to the Configure Storage – System Programmer
| task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID
| {adapter-id} does not identify an Adapter object on the HMC.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| the current value of the adapter’s adapter-family property is not "ficon". If the value of the adapter’s
| status property is "exceptions", or if the current value of the adapter’s type property is already set to the
| value specified in the type field in the request body, of if the adapter is configured to any partition, a 409
| (Conflict) status code is returned.

| If the request body contents are valid, the adapter’s type property and the type property of the adapter
| with the same card id and slot id, as identified by the first 9 characters of their card-location property
| values, are updated to the value specified in the type field in the request body. The two adapters are
| reconfigured to the new storage protocol.

| Property change notifications for the type property of both affected adapters are emitted asynchronously
| to this operation.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object-access permission to the adapter whose object ID is {adapter-id}
| v Action/task permission to the Configure Storage – System Programmer 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, and the response body is a
| standard error response body providing the reason code indicated and associated error message.
| Table 130. Change Adapter Type: 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.
| 18 The operation is not allowed for the adapter’s type.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer task.

Chapter 10. Dynamic Partition Manager (DPM) 295

 Level 04a

| Table 130. Change Adapter Type: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 404 (Not Found) 1 An adapter with object ID {adapter-id} does not exist on the HMC.
| 409 (Conflict) 1 Adapter status is not valid to perform the operation (does not allow the
| updating of a specified adapter property).
| 2 The adapter object with the object-id {adapter-id} was busy and the request
| timed out.
| 488 The adapter’s type property is already set to the value of the type field in
| the request body.
| 489 The adapter is configured to at least one partition.
| 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

|

POST /api/adapters/e835bb78-9fe7-11e8-bc9a-fa163e3c2af4/operations/change-adapter-
type HTTP/1.1
x-api-session: 2fypcb9w0z7kzv9rtq7yfxaypayrdh209nmrrdyv1jetvhxfu0
content-type: application/json
content-length: 15
{
"type":"fcp"
}

Figure 123. Change Adapter Type: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Wed, 15 Aug 2018 17:02:33 GMT

<No response body>

Figure 124. Change Adapter Type: Response

| Inventory service data

Information about the Adapters managed by the HMC can be optionally included in the inventory data
provided by the Inventory Service.

Inventory entries for Adapter objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "adapter" are to be included. Information for a particular adapter is
included only if the API user has object-access permission to that object.

For each adapter to be included, the inventory response array includes the following:

296 HMC Web Services API

 Level 04a

v An array entry for the Adapter object itself. This entry is a JSON object with the same contents as is
specified in the response body contents section for “Get Adapter Properties” on page 275. That is, the
data provided is the same as would be provided if a Get Adapter Properties operation were requested
targeting this object.
v An array entry for each network port associated with the adapter. For each such network port, an
entry is included that is a JSON object with the same contents as is specified in the response body
contents section for “Get Network Port Properties” on page 287.
v An array entry for each storage port associated with the adapter. For each such storage port, an entry
is included that is a JSON object with the same contents as is specified in the response body contents
section for “Get Storage Port Properties” on page 291.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single adapter. This object would appear as a sequence of array entries in the
response array:

{
"adapter-family":"osa",
"adapter-id":"18C",
"allowed-capacity":1920,
"card-location":"Z15B-D104-J.01",
"channel-path-id":"10",
"class":"adapter",
"configured-capacity":3,
"description":"My OSA",
"detected-card-type":"osa-express-5s-10gb",
"maximum-total-capacity":1920,
"name":"OSD 018C Z15B-04",
"network-port-uris":[
"/api/adapters/e77d39f8-c930-11e5-a978-020000000338/network-ports/0"
],
"object-id":"e77d39f8-c930-11e5-a978-020000000338",
"object-uri":"/api/adapters/e77d39f8-c930-11e5-a978-020000000338",
"parent":"/api/cpcs/87dbe268-0b43-362f-9f80-c79923cc4a29",
"physical-channel-status":"operating",
"port-count":1,
"state":"online",
"status":"active",
"type":"osd",
"used-capacity":3
},
{
"class":"network-port",
"description":"My OSA port",
"element-id":"0",
"element-uri":"/api/adapters/e77d39f8-c930-11e5-a978-020000000338/network-ports/0",
"index":0,
"name":"Port 0",
"parent":"/api/adapters/e77d39f8-c930-11e5-a978-020000000338"
},

Figure 125. Adapter object: Sample inventory data

Chapter 10. Dynamic Partition Manager (DPM) 297

 Level 04a

Virtual Switch object

A Virtual Switch object is a virtualized representation of a CPC's networking adapter and port. Network
adapters without a physical port, such as HiperSockets or single port OSAs are virtualized to a single
virtual switch. Network adapters with multiple ports are virtualized into multiple virtual switches one
for each port. Virtual switches are generated automatically every time a new network adapter is detected
and configured. The virtual switch serves as the connection point for network interfaces (VNICs) created
by the virtual server administrator.

Data model
For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

This object includes the properties defined in the “Base managed object properties schema” on page 60,
but does not provide the operational-status-related properties defined in that schema because it does not
maintain the concept of an operational status. The following class-specific specializations apply to the
other base managed object properties:
Table 131. Virtual Switch object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/ The canonical URI path for a Virtual Switch object is of the form
URI /api/virtual-switches/{vswitch-id} where {vswitch-id} is the
value of the object-id property of the Virtual Switch object.
object-id — String (36) The unique identifier for the virtual switch instance.
parent — String/URI The canonical URI path of the CPC object.
class — String (14) The class of a Virtual Switch object is "virtual-switch".
name (w)(pc) String The display name of the Virtual Switch object. This name must be
(1-64) unique among all of the CPC's virtual switches, and it must
conform to the length and character requirements of the name
property described in “Base managed object properties schema” on
page 60.

Default: A string of the form {PCHID}.{portNumber}.{type} where

{PCHID} is the PCHID of the backing adapter, {portNumber}is the
value of the port property, and {type} is the abbreviated type
property folded to uppercase. For example, "019F.0.OSD".
description (w)(pc) String The description of the Virtual Switch object, or an empty string.
(0-1024)
Default: empty string.

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:
Table 132. Virtual Switch object: class specific properties
Name Qualifier Type Description
type — String v "hipersockets" – a HiperSockets virtual switch.
Enum
v "osd" – OSA Direct Express virtual switch.
backing-adapter-uri — String/ The canonical URI path of the backing Adapter object.
URI

298 HMC Web Services API

 Level 04a

Table 132. Virtual Switch object: class specific properties (continued)

Name Qualifier Type Description
port — Integer
Physical port identifier associated with the virtual switch. Valid
port numbers are 0 and 1. Network adapters that do not have a
physical port (HiperSockets) are considered to have a single
“virtual” port that is identified as port number 0.
connected-vnic-uris (p)(pc)(c) Array of The list of network interfaces (VNICs) connected to this virtual
String/ switch. The list is available via the Get Connected VNICs of a
URI Virtual Switch operation. Each element in this array is a canonical
URI path for a NIC element of a Partition object.

This array is initially empty when the virtual switch is created.

List Virtual Switches of a CPC

The List Virtual Switches of a CPC operation lists virtual switches that are defined to the CPC.

HTTP method and URI

GET /api/cpcs/{cpc-id}/virtual-switches

In this request, the URI variable {cpc-id} is the object ID of the CPC for which virtual switches are to be
listed.

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) to limit returned objects to those
objects that have a matching name property
type String Optional Filter string to limit returned objects to those objects that have a
enum matching type property. The value must be a valid type property
value.

Response body contents

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

Field name Type Description

virtual-switches Array of Array of nested virtual-switch-info objects as described in the next table.
objects

Each nested virtual-switch-info object contains the following fields:

Field name Type Description

object-uri String/ The object-uri property of the Virtual Switch object.
URI
name String The name property of the Virtual Switch object
type String The type property of the Virtual Switch object
Enum

Chapter 10. Dynamic Partition Manager (DPM) 299

 Level 04a

Description
This operation lists Virtual Switches defined to the CPC. Some basic properties are provided for each
virtual switch that is included in the response.

If the request URI does not identify a CPC object to which the API user has object-access permission,
HTTP status code 404 (Not Found) is returned.

If the name query parameter is specified, the returned list is limited to those virtual switches 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 that it is a valid virtual
switch 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 virtual switches that have a type property matching
the specified value. If the type parameter is omitted, no such filtering is performed.

A virtual switch is included in the list only if the API user has object-access permission to the backing
adapter of that virtual switch. If there is a virtual switch to which the API user does not have permission,
that object is omitted from the list, but no error status code results.

If the CPC is not in DPM mode, or there are no virtual switches defined to the CPC, or no virtual
switches 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 identified in the request URI
v Object-access permission to the backing adapter of the Virtual Switch objects to be 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 299.

Otherwise, 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 it 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.

300 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/cpcs/8e543aa6-1c26-3544-8197-4400110ef5ef/virtual-switches
x-api-session: 1jgbldxyy2inf0p7aaj9a8p87j7awxsr1mstmfnw07hvoaz8da

Figure 126. List Virtual Switches of a CPC: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control:no-cache
date: Tue, 31 Mar 2015 06:20:54 GMT
content-type: application/json;charset=UTF-8
content-length: 255
{
"virtual-switches":[
{
"name":"PrimeIQDVSwitch1",
"object-uri":"/api/virtual-switches/f6b4c70e-d491-11e4-a555-020000003058",
"type":"hipersockets"
},
{
"name":"5F1.P0.OSD",
"object-uri":"/api/virtual-switches/dff0b71c-d491-11e4-a555-020000003058",
"type":"osd"
}
]
}

Figure 127. List Virtual Switches of a CPC: Response

Get Virtual Switch Properties

The Get Virtual Switch Properties operation retrieves the properties of a single Virtual Switch object that
is designated by its object ID.

HTTP method and URI

GET /api/virtual-switches/{vswitch-id}

In this request, the URI variable {vswitch-id} is the object ID of the Virtual Switch object for which
properties are to be returned.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Virtual Switch object as defined in the “Data model” on page 298. 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
This operation returns the current property values for the Virtual Switch object specified by {vswitch-id}.

On successful execution, all of the current properties as defined in the “Data model” on page 298 for the
Virtual Switch object are provided in the response body, and HTTP status code 200 (OK) is returned.

Chapter 10. Dynamic Partition Manager (DPM) 301

 Level 04a

The URI path must designate an existing Virtual Switch object and the API user must have object-access
permission to the backing Adapter object of the virtual switch. If either of these conditions is not met,
status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the backing Adapter object of the Virtual Switch object specified in the
request URI

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 301.

Otherwise, 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 request URI {vswitch-id}) does not designate an existing
Virtual Switch object, or the API user does not have object-access permission
to the backing Adapter object of the Virtual Switch object.

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/virtual-switches/f6b4c70e-d491-11e4-a555-020000003058
x-api-session: 5an6scz1o7mikkmyeew077vj9yggo5qe781wgegwpw3yilxq4j

Figure 128. Get Virtual Switch Properties: Request

302 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Mar 2015 07:00:51 GMT
content-type: 'application/json;charset=UTF-8
content-length: 306
{
"backing-adapter-uri":"/api/adapters/f718c7a0-d490-11e4-a555-020000003058",
"class":"virtual-switch",
"description":"",
"name":"PrimeIQDVSwitch1",
"object-id":"f6b4c70e-d491-11e4-a555-020000003058",
"object-uri":"/api/virtual-switches/f6b4c70e-d491-11e4-a555-020000003058",
"parent":"/api/cpcs/8e543aa6-1c26-3544-8197-4400110ef5ef",
"port":0,
"type":"hipersockets"
}

Figure 129. Get Virtual Switch Properties: Response

Get Connected VNICs of a Virtual Switch

The Get Connected VNICs of a Virtual Switch operation retrieves the list of network interfaces (VNICs)
connected to a single Virtual Switch object that is designated by its object ID.

HTTP method and URI

GET /api/virtual-switches/{vswitch-id}/operations/get-connected-vnics

In this request, the URI variable {vswitch-id} is the object ID of the Virtual Switch object whose VNIC list
is to be returned.

Response body contents

On successful completion, the response body contains a JSON object that provides the
connected-vnic-uris property of the Virtual Switch object as defined in the “Data model” on page 298.

Description
This operation returns the list of VNICs connected to the Virtual Switch object specified by {vswitch-id}.

On successful execution, the current list of VNICs connected to the Virtual Switch is provided in the
response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing Virtual Switch object and the API user must have object-access
permission to the backing Adapter object of the Virtual Switch object. If these conditions are not met,
HTTP status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the backing Adapter object of the Virtual Switch object specified by the
request URI.

Chapter 10. Dynamic Partition Manager (DPM) 303

 Level 04a

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 303.

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 object ID in the request URI ({vswitch-id}) does not designate an existing
Virtual Switch object, or the API user does not have object-access permission
to the backing Adapter object of the Virtual Switch object.

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/virtual-switches/f6b4c70e-d491-11e4-a555-020000003058/operations/get-connected-
vnics
x-api-session: 5an6scz1o7mikkmyeew077vj9yggo5qe781wgegwpw3yilxq4j

Figure 130. Get Connected VNICs of a Virtual Switch: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Mar 2015 07:00:51 GMT
content-type: ’application/json;charset=UTF-8
content-length: 370
{
"connected-vnic-uris":[
"/api/partitions/675fe728-dfc7-11e4-8582-020000003022/nics/0bc27850-dfc9-11e4-a45e-020000003022",
"/api/partitions/675fe728-dfc8-11e4-8583-020000003022/nics/0bc27850-dfc9-11e4-a45e-020000003022",
"/api/partitions/684fe825-dfc9-11e4-8681-020000003022/nics/0ba26450-dfc8-11e4-a36e-020000003022"
],
}

Figure 131. Get Connected VNICs of a Virtual Switch: Response

Update Virtual Switch Properties

The Update Virtual Switch Properties operation updates the properties of a single Virtual Switch object
that is designated by its object ID.

HTTP method and URI

POST /api/virtual-switches/{vswitch-id}

In this request, the URI variable {vswitch-id} is the object ID of the Virtual Switch object for which
properties are to be updated.

304 HMC Web Services API

 Level 04a

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined in the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
The Update Virtual Switch Properties operation updates writable properties of the Virtual Switch object
specified by {vswitch-id}.

The URI path must designate an existing Virtual Switch object, and the API user must have object-access
permission to the backing Adapter object of the Virtual Switch object. If these conditions are not met,
HTTP status code 404 (Not Found) is returned. In addition, the API user must have action/task
permission to the Manage Adapters task; otherwise, HTTP status code 403 (Forbidden) is returned.

The request body is validated against the schema described in “Request body contents.” If the request
body is not valid, HTTP status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

The request body does not need to specify a value for all writable properties, but rather can and should
contain fields only for the properties to be updated. Object properties for which no input value is
provided remain unchanged by this operation unless a prerequisite or linked property is changed.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the backing Adapter object of the Virtual Switch object specified in the
request URI
v Action/task permission to the Manage Adapters task.

HTTP status and reason codes

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

Otherwise, 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 133. Update Virtual Switch 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.
403 (Forbidden) 1 API user does not have action/task permission to the Manage Adapters
task.
404 (Not Found) 1 The object ID {vswitch-id} does not designate an existing Virtual Switch
object, or the API user does not have object-access permission to the backing
Adapter object of the Virtual Switch object.

Chapter 10. Dynamic Partition Manager (DPM) 305

 Level 04a

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/virtual-switches/f6b4c70e-d491-11e4-a555-020000003058
x-api-session: rxkrzf6v287nn0klyk4zah94i91r49eskxkut8242kdqfa9so
content-type: application/json
content-length: 68
{
"description": "the neNetwork virtual switch",
"name": "neVswitch"
}

Figure 132. Update Virtual Switch Properties: Request

204 No Content
date: Tue, 31 Mar 2015 07:05:50 GMT
server: zSeries management console API web server / 2.0
cache-control: no-cache

<No response body>

Figure 133. Update Virtual Switch Properties: Response

Inventory service data

Information about the virtual switches can be optionally included in the inventory data provided by the
Inventory Service.

Inventory entries for the Virtual Switch objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by inventory class, implicitly via a containing
category, or by default) that objects of the class "virtual-switch" to be included. An entry for a particular
virtual switch is included only if the API user has access permission to that object as described in the Get
Virtual Switch Properties operation.

For each Virtual Switch object to be included, the inventory response array includes an entry that is a
JSON object with the same contents as is specified in the response body contents section for “Get Virtual
Switch Properties” on page 301. That is, the data provided is the same as would be provided if a Get
Virtual Switch Properties operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single virtual switch. This object would appear as one array entry in the response
array:

306 HMC Web Services API

 Level 04a

{
"backing-adapter-uri":"/api/adapters/df863694-08b1-11e6-91a3-42f2e90df693",
"class":"virtual-switch",
"description":"",
"name":"5F1.P0.OSD",
"object-id":"dff0b71c-d491-11e4-a555-020000003058",
"object-uri":"/api/virtual-switches/dff0b71c-d491-11e4-a555-020000003058",
"parent":"/api/cpcs/8e543aa6-1c26-3544-8197-4400110ef5ef",
"port":0,
"type":"osd"
}

Figure 134. Virtual Switch object: Sample inventory data - Response

Capacity Group element object

A Capacity Group is an element object of a CPC that is in DPM mode. It consists of a set of partitions
and specifies the absolute processor cap per processor type for that set of partitions. The defined absolute
processor cap for a specific processor type dictates the total amount of the specified processing capacity
that the active partitions in the group can consume at any time. The absolute processor cap is specified as
a value between 0.01 and 255.0, where a value of 1.00 represents the processing capacity provided by one
processor.

The scope of a Capacity Group is within a single CPC and it is required that the CPC is in DPM mode
for a Capacity Group to be created.

The absolute processor cap can be modified after the group is created, at which time, the partitions that
are already active in the group will be affected.

Data model
The following attributes are identified for the Capacity Group element object:
Table 134. Capacity Group element object properties
Name Qualifier Type Description of specialization
element-uri — String/ The canonical URI path of the Capacity Group element object is of
URI the form /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-
id} where {capacity-group-id} is the unique identifier for a
capacity group within a CPC.
element-id — String (36) The unique identifier for the capacity group. The element-id is in
the form of a UUID.
parent — String/URI The canonical URI path of the parent CPC object.
class — String (14) The class of a Capacity Group object is "capacity-group"
name (w)(pc) String The name of the capacity group. The name must be unique among
(1-64) all capacity groups in the CPC. The length and character
requirements on this property are the same as those of the name
property described in the “Base managed object properties schema”
on page 60.

Chapter 10. Dynamic Partition Manager (DPM) 307

 Level 04a

Table 134. Capacity Group element object properties (continued)

Name Qualifier Type Description of specialization
short-name (w)(pc) String (1-8) The name of the capacity group that will be presented to the guest
OS, when capping is enabled on this capacity group.

Only alpha-numeric uppercase characters are allowed. The

short-name must be unique among all capacity groups in the CPC.
The words PHYSICAL, REC, SYSTEM, and PRIMnnnn (where nnnn
is a 4-digit number) are reserved and cannot be used.
description (w)(pc) String The description of the capacity group.
(0-1024)
Default: An empty string.
capping-enabled (w)(pc) Boolean This indicates if capping is enabled for this capacity group or not.

If set to true, the partitions in this capacity group are capped

according to the values set.

If set to false, any specified cap values are not effective and the
partitions in this capacity group are not capped.

Default: True.
absolute-general- (w)(pc) Float The limit on the absolute capacity of general purpose processors
purpose-proc-cap (0-255) that the partitions in this group are allowed to consume at any
point in time. It is expressed in the units of processors. The range
of valid values is between 0.0 and 255.0 and in the increments of
0.01.

Default: 0.0.

The value of 0.0 indicates that the general purpose processors are
not capped for the partitions in this capacity group.

Exactly one of the processor types must have a value other than
0.0.
absolute-ifl-proc-cap (w)(pc) Float The limit on the absolute capacity of IFL processors that the
(0-255) partitions in this group are allowed to consume at any point in
time. It is expressed in the units of processors. The range of valid
values is between 0.0 and 255.0 and in the increments of 0.01.

Default: 0.0.

The value of 0.0 indicates that the IFL processors are not capped for
the partitions in this capacity group.

Exactly one of the processor types must have a value other than
0.0.
partition-uris (c)(pc) Array of Array of URIs of the partitions that belong to this capacity group.
String/ Each partition in this capacity group must have the type of
URIs processor (general purpose or IFL) that is being capped by this
capacity group.

This property can be modified using the Add Partition to Capacity

Group and Remove Partition from Capacity Group operations.

List Capacity Groups of a CPC

The List Capacity Groups of a CPC operation lists the defined capacity groups for the specified CPC.

308 HMC Web Services API

 Level 04a

HTTP method and URI

GET /api/cpcs/{cpc-id}/capacity-groups

In this request, the URI variable {cpc-id} is the object ID of the CPC.

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.

Response body contents

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

Field name Type Description

capacity-groups Array of Array of capacity-group-info objects, described in the next table. Returned
capacity- array may be empty.
group-info
objects

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

Field name Type Description

element-uri String/ Canonical URI path of the Capacity Group object. More details about this
URI capacity group can be fetched using this element-uri.
name String The name of the capacity group.
(1-64)

Description
This operation lists the capacity groups that are defined for the specified CPC. The element-uri and name
are returned for each capacity group.

If the name query parameter is specified for the request, the returned list is limited to the Capacity
Group elements that have a name matching the specified filter pattern. If no match is found, then the
response will be an empty array. If the parameter is not specified, all the Capacity Group elements are
returned.

The response could be an empty array, if the CPC does not have a Capacity Group associated with it or if
the CPC is not in DPM mode.

The URI path must designate an existing CPC, and the API user must have object-access permission to
the CPC object specified by the {cpc-id}. If these conditions are not met, HTTP status code 404 (Not
Found) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the specified CPC.

Chapter 10. Dynamic Partition Manager (DPM) 309

 Level 04a

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 309.

Otherwise, 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 any 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 CPC identified by {cpc-id} does not exist or the user does not have
object-access permission to it.
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/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups HTTP/1.1

x-api-session: 4xjbyzz8iip3fv0j77gyuk3e6r7lp0pl9yb4zfpf1n46u3z7ec

Figure 135. List Capacity Groups of a CPC: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 22 Feb 2016 10:00:54 GMT
content-type: application/json;charset=UTF-8
content-length: 363
{
"capacity-groups":[
{
"element-uri":"/api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/e0118d40-
d088-11e5-a631-42f2e9ef1641",
"name":"Test18311"
},
{
"element-uri":"/api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/d95f6418-
d6eb-11e5-92b9-42f2e9ef1641",
"name":"myNewGroup1"
}
]
}

Figure 136. List Capacity Groups of a CPC: Response

Create Capacity Group

The Create Capacity Group operation creates a capacity group for the specified CPC.

310 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/cpcs/{cpc-id}/capacity-groups

In this request, the URI variable {cpc-id} is the object ID of the CPC.

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The value to be set as the Capacity Group's name
(1-64) property.
short-name String (1-8) Optional The value to be set as the Capacity Group's short-name
property.

If a short-name is not specified, it will be auto-generated

and assigned to this capacity group.

The name, if specified, must be unique within the CPC.

description String Optional The value to be set as the Capacity Group's description
(0-1024) property.
capping-enabled Boolean Optional The value to be set as the capacity group's
capping-enabled property.
absolute-general- Float Optional The value to be set as the Capacity Group's
purpose-proc-cap absolute-general-purpose-proc-cap property.
absolute-ifl-proc- Float Optional The value to be set as the Capacity Group's
cap absolute-ifl-proc-cap property.

Response body contents

On successful completion, HTTP status code 201 (Created) is returned and a JSON object with the
following field is also provided. The element-uri of the capacity group created is also available in the
Location header of the response.

Field name Type Description

element-uri String/URI The element-uri property of the created capacity group.

Description
This operation creates a capacity group with the specified attributes. It is required that the CPC
designated by {cpc-id} is in DPM mode. On successful execution, the element-uri of the created capacity
group is returned in the response body and in the Location response header. An Inventory Change
notification is emitted asynchronously to this operation.

Exactly one processor type must have an absolute processor cap other than 0.0 and within the valid range
of 0.01 and 255.0. Otherwise, a 400 (Bad Request) status code is returned.

If the {cpc-id} does not designate a CPC that is in DPM mode, an HTTP status code 409 (Conflict) is
returned.

The URI path must designate an existing CPC, and the API user must have object-access permission to
the CPC object specified by the {cpc-id}. If these conditions are not met, HTTP status code 404 (Not

Chapter 10. Dynamic Partition Manager (DPM) 311

 Level 04a

Found) is returned. In addition, the API user must have action/task permission to the Manage Processor
Sharing task; otherwise, HTTP status code 403 (Forbidden) is returned.

If the request body contents fail to validate, a 400 (Bad Request) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the specified CPC.
v Action/task permission to the Manage Processor Sharing 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” on page 311.

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 the associated error message.
Table 135. Create Capacity Group: 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 The API user does not have the required action/task permission to the
Manage Processor Sharing task.
404 (Not Found) 1 The CPC identified by {cpc-id} does not exist or the user does not have
object-access permission to the CPC.
409 (Conflict) 5 The CPC is not in DPM mode.
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 the 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.

312 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups HTTP/1.1

x-api-session: jht693kvysnx78mws1i0sacatmvougd2y11jz0e0jmgy3fv94
content-type: application/json
content-length: 160
{
"absolute-general-purpose-proc-cap":5.0,
"capping-enabled":true,
"description":"Test Group for CP Procs",
"name":"Cap group 123",
"short-name":"CPGRP111"
}

Figure 137. Create Capacity Group: Request

201 Created
server: zSeries management console API web server / 2.0
location: /api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/a4d8826c-
d9fa-11e5-8b15-42f2e9ef1641
cache-control: no-cache
date: Tue, 23 Feb 2016 07:00:57 GMT
content-type: application/json;charset=UTF-8
content-length: 117
{
"element-uri":"/api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/1de263e4-
d9fb-11e5-8b3e-42f2e9ef1641"
}

Figure 138. Create Capacity Group: Response

Delete Capacity Group

The Delete Capacity Group operation deletes the specified capacity group.

HTTP method and URI

DELETE /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}

URI variables:

Name Description
{cpc-id} Object ID of the CPC.
{capacity-group-id} Element ID of the capacity group.

Description
This operation deletes the capacity group with the specified {capacity-group-id}. It is required that the
specified capacity group does not contain any partition, at the time of deletion. An Inventory Change
notification is emitted asynchronously to this operation.

The URI path must designate an existing Capacity Group, and the API user must have object-access
permission to the CPC object specified by the {cpc-id}. If these conditions are not met, HTTP status code
404 (Not Found) is returned. In addition, the API user must have action/task permission to the Manage
Processor Sharing task; otherwise, HTTP status code 403 (Forbidden) is returned.

Chapter 10. Dynamic Partition Manager (DPM) 313

 Level 04a

A 409 (Conflict) status code is returned if the capacity group contains any partitions. The Remove
Partition from Capacity Group operation should be used to delete all the partitions from this capacity
group before attempting this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the specified CPC.
v Action/task permission to the Manage Processor Sharing 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, and the response body is a
standard error response body providing the reason code and associated error message.
Table 136. Delete Capacity Group: 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 The API user does not have action/task permission to the Manage Processor
Sharing task
404 (Not Found) 1 The CPC identified by {cpc-id} does not exist or the user does not have
object-access permission to the CPC.
150 The capacity group identified by {capacity-group-id} does not exist.
409 (Conflict) 110 The capacity group contains one or more partitions, and thus could not be
deleted.
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 the 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/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/a4d8826c-d9fa-
11e5-8b15-42f2e9ef1641 HTTP/1.1
x-api-session: 2saqzhzg358oqoke89osqrgt09k27rqwy4d0mtdp6j2z05ok6q

Figure 139. Delete Capacity Group: Request

314 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 23 Feb 2016 07:02:43 GMT
<No response body>

Figure 140. Delete Capacity Group: Response

Get Capacity Group Properties

The Get Capacity Group Properties operation retrieves the properties of a single capacity group.

HTTP method and URI

GET /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}

URI variables:

Name Description
{cpc-id} Object ID of the CPC.
{capacity-group-id} Element ID of the capacity group.

Response body contents

On successful completion, an HTTP status code 200 (OK) is returned and a JSON object containing the
current values of the properties for the Capacity Group element object as defined in the “Data model” on
page 307 is provided as a response body. Field names and data types in the JSON object are the same as
the property names and data types that are defined in the data model.

Description
This operation retrieves the current values of the properties of the capacity group.

The URI path must designate an existing Capacity Group, and the API user must have object-access
permission to the CPC object specified by the {cpc-id}. If these conditions are not met, HTTP status code
404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the specified CPC.

HTTP status and reason codes

On success, the HTTP status code 200 (OK) is returned and a response body with the current values for
the properties of the capacity group is provided.

Otherwise, 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) 315

 Level 04a

Table 137. Get Capacity Group 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.
404 (Not Found) 1 The object ID {cpc-id} does not designate an existing CPC object, or the API
user does not have object-access permission to it.
150 The capacity group identified by {capacity-group-id} does not exist.
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.
503 (Service 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with the 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

GET /api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/1de263e4-d9fb-11e5-
8b3e-42f2e9ef1641 HTTP/1.1
x-api-session: 487yumkfzjybynsm00a5qn7v916s8eq49krcnpfqut4n0kfv4

Figure 141. Get Capacity Group Properties: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 23 Feb 2016 07:14:23 GMT
content-type: application/json;charset=UTF-8
content-length: 504
{
"absolute-general-purpose-proc-cap":5.0,
"absolute-ifl-proc-cap":0.0,
"capping-enabled":true,
"class":"capacity-group",
"description":"Test Group for CP Procs",
"element-id":"1de263e4-d9fb-11e5-8b3e-42f2e9ef1641",
"element-uri":"/api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/1de263e4-
d9fb-11e5-8b3e-42f2e9ef1641",
"name":"Cap group 123",
"parent":"/api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0",
"partition-uris":[
"/api/partitions/880c3272-cbeb-11e5-90fe-42f2e9ef1641"
],
"short-name":"CPGRP111"
}

Figure 142. Get Capacity Group Properties: Response

Add Partition to Capacity Group

The Add Partition to Capacity Group operation adds a partition to the specified capacity group.

316 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}/operations/add-partition

URI variables:

Name Description
{cpc-id} Object ID of the CPC.
{capacity-group-id} Element ID of the capacity group.

Request body contents

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

Name Type Rqd/Opt Description

partition-uri String/URI Required The canonical URI of the Partition object to be added to the capacity
group.

Description
This operation adds a partition to an existing capacity group identified by the {capacity-group-id}.

A partition can be added to the capacity group, only if the processor type that the partition uses has a
nonzero cap value in the specified capacity group. Otherwise, a status code 409 (Conflict) is returned.

A capacity group can only contain partitions with shared processors. If the partition specified in the
request is configured for dedicated processors, a status code 409 (Conflict) will be returned.

A partition cannot become a member of more than one capacity group. If the partition specified in the
request is currently a member of another capacity group or the capacity group identified by
{capacity-group-id}, a status code 409 (Conflict) is returned.

If the partition does not belong to the same CPC as the capacity group, a status code 400 (Bad Request) is
returned.

The URI path must designate an existing capacity group, and the API user must have object-access
permission to the CPC object specified by the {cpc-id}. If these conditions are not met, HTTP status code
404 (Not Found) is returned. In addition, the API user must have action/task permission to the Manage
Processor Sharing task; otherwise, HTTP status code 403 (Forbidden) is returned.

On successful execution, the partition is added to the capacity group and the number of processors that
could be used by this partition becomes governed by the absolute proc cap values that are defined for
this capacity group.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the specified CPC.
v Action/task permission to the Manage Processor Sharing task.

Chapter 10. Dynamic Partition Manager (DPM) 317

 Level 04a

HTTP status and reason codes

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

Otherwise, 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 138. Add Partition to Capacity Group: 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.
160 The partition does not belong to the same CPC as the capacity group.
403 (Forbidden) 1 API user does not have action/task permission to the Manage Processor
Sharing task.
404 (Not Found) 1 The CPC identified by {cpc-id} does not have object-access permission to the
CPC.
2 The partition designated by the partition-uri in the request body does not
exist.
150 The capacity group identified by {capacity-group-id} does not exist.
409 (Conflict) 120 The partition is currently a member of another capacity group and thus,
cannot be added to this capacity group.
130 The partition is already a member of the capacity group identified by
{capacity-group-id}.
170 The partition is configured with dedicated processors.
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 the 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

POST /api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/1de263e4-d9fb-11e5-
8b3e-42f2e9ef1641/operations/add-partition HTTP/1.1
x-api-session: 3ty54o1c7961o2jt0jyjm5nm8xqxofys7s302syjoguaycbeo5
content-type: application/json
content-length: 73
{
"partition-uri":"/api/partitions/880c3272-cbeb-11e5-90fe-42f2e9ef1641"
}

Figure 143. Add Partition to Capacity Group: Request

318 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 23 Feb 2016 07:13:42 GMT
<No response body>

Figure 144. Add Partition to Capacity Group: Response

Remove Partition from Capacity Group

The Remove Partition from Capacity Group operation removes a partition from an existing capacity
group.

HTTP method and URI

POST /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}/operations/remove-partition

URI variables:

Name Description
{cpc-id} Object ID of the CPC.
{capacity-group-id} Element ID of the capacity group.

Request body contents

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

Field name Type Rqd/Opt Description

partition-uri String/URI Required The canonical URI of the Partition object to be removed
from the capacity group.

Description
This operation removes a partition from a capacity group identified by the {capacity-group-id}. If the
partition is not currently a member of the capacity group, a status code 409 (Conflict) is returned.

The URI path must designate an existing capacity group, and the API user must have object-access
permission to the CPC object specified by the {cpc-id}. If these conditions are not met, HTTP status code
404 (Not Found) is returned. In addition, the API user must have action/task permission to the Manage
Processor Sharing task; otherwise, HTTP status code 403 (Forbidden) is returned.

On successful execution, the partition is removed from the capacity group and the amount of processing
capacity that could be used by this partition is no longer governed by the absolute proc cap values
defined for this capacity group.

If this operation changes the values of any property for which property-change notifications are due,
those notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the specified CPC.

Chapter 10. Dynamic Partition Manager (DPM) 319

 Level 04a

v Action/task permission to the Manage Processor Sharing 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 139. Remove Partition from Capacity Group: 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 The API user does not have the required action/task permission to the
Manage Processor Sharing task.
404 (Not Found) 1 The CPC identified by {cpc-id} does not exist or the user does not have
object-access permission to the CPC.
2 The partition designated by the partition-uri in the request body does not
exist.
150 The capacity group identified by {capacity-group-id} does not exist.
409 (Conflict) 140 The partition is not currently a member of the capacity group.
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 the 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

POST /api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/1de263e4-d9fb-11e5-
8b3e-42f2e9ef1641/operations/remove-partition HTTP/1.1
x-api-session: 3581gp14ocfmtodeh93ckw1ita2c3k07mrv6xb7ymqgcncjv8k
content-type: application/json
content-length: 73
{
"partition-uri":"/api/partitions/880c3272-cbeb-11e5-90fe-42f2e9ef1641"
}

Figure 145. Remove Partition from Capacity Group: Request

320 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 23 Feb 2016 07:16:00 GMT
<No response body>

Figure 146. Remove Partition from Capacity Group: Response

Update Capacity Group Properties

The Update Capacity Group Properties operation modifies the writable properties of a capacity group.

HTTP method and URI

POST /api/cpcs/{cpc-id}/capacity-groups/{capacity-group-id}

URI variables:

Name Description
{cpc-id} Object ID of the CPC.
{capacity-group-id} Element ID of the capacity group.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined in the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
This operation updates writable properties of the Capacity Group element specified by the
{capacity-group-id}.

The URI path must designate an existing capacity group, and the API user must have object-access
permission to the CPC object specified by the {cpc-id}. If these conditions are not met, HTTP status code
404 (Not Found) is returned. In addition, the API user must have action/task permission to the Manage
Processor Sharing task; otherwise, HTTP status code 403 (Forbidden) is returned.

The request body is validated against the schema described in the “Data model” on page 307. If the
request body is not valid, HTTP status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered. The capacity group must be removed of all partitions first, if the cap
values are updated such that the capacity group starts capping partitions on a different processor type.
Otherwise, a status code 400 (Bad Request) is returned.

The request body does not need to specify a value for all writable properties, but rather can and should
contain fields only for the properties to be updated. Object properties for which no input value is
provided remain unchanged by this operation unless a prerequisite or linked property is changed.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Chapter 10. Dynamic Partition Manager (DPM) 321

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the specified CPC.
v Action/task permission to the Manage Processor Sharing task.

HTTP status and reason codes

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

Otherwise, 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 140. Update Capacity Group 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.
403 (Forbidden) 1 The API user does not have action/task permission to the Manage Processor
Sharing task.
404 (Not Found) 1 The CPC identified by {cpc-id} does not exist or the user does not have
object-access permission to the CPC.
150 The capacity group identified by {capacity-group-id} does not exist.
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.
503 (Service 1 The request could not be processed because the HMC is not currently
Unavailable communicating with the 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

POST /api/cpcs/3baea1ec-76e8-3e42-a111-815a7aee19e0/capacity-groups/1de263e4-d9fb-11e5-
8b3e-42f2e9ef1641 HTTP/1.1
x-api-session: 8rws222hts1w985vhnn5vcne4x5z6b3q143z0gx7kqzmnuqlu
content-type: application/json
content-length: 42
{
"absolute-general-purpose-proc-cap":2.0
}

Figure 147. Update Capacity Group Properties: Request

322 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 23 Feb 2016 07:18:42 GMT
<No response body>

Figure 148. Update Capacity Group Properties: Response

Inventory service data

Information about capacity groups can be optionally included in the inventory data provided by the
Inventory Service.

Inventory entries for the Capacity Group objects are included in the response to the Inventory Service's
Get Inventory operation when the request specifies (explicitly by class, implicitly via a containing
category, or by default) that objects of class "cpc" are to be included. An entry for a particular capacity
group is included only if the API user has access permission to that object as described in the Get
Capacity Group Properties operation.

For each Capacity Group object to be included, the inventory response array includes an entry that is a
JSON object with the same contents as is specified in the response body contents section for “Get
Capacity Group Properties” on page 315. That is, the data provided is the same as would be provided if a
Get Capacity Group Properties operation were requested targeting this object.

| Storage Site object

| A Storage Site object represents a single storage site in the FICON storage configuration associated with a
| DPM-enabled CPC. A storage site describes a location that houses a set of storage switches and storage
| subsystems. A primary site with a default name of "Primary Site", local to the CPC, exists by default and
| cannot be deleted. An alternate site, typically at a remote location, can be created. The Storage Site object
| APIs provide access to the set of storage sites within the FICON configuration associated with a CPC that
| is enabled for DPM. APIs exist to create and delete alternate storage sites, query storage sites, and update
| selected properties of storage sites.

| Data model
| This object includes the properties that are defined in the “Base managed object properties schema” on
| page 60, with the class-specific specializations identified in Table 142 on page 324. The Storage Site object
| does not support the operational status related properties.
| Table 141. Storage Site object properties
| Name Qualifier Type Description of specialization
| object-uri — String/ The canonical URI path of the Storage Site object is of the form
| URI /api/storage-sites/{storage-site-id} where {storage-site-id}
| is the value of the object-id property of the Storage Site object.
| object-id — String (36) The unique identifier for the storage site instance.
| class — String (12) The class of the Storage Site object is "storage-site".
| parent — String/URI The parent of a storage site is conceptually its owning Console, and
| so the parent value is the canonical URI path for the Console.

Chapter 10. Dynamic Partition Manager (DPM) 323

 Level 04a

| Table 141. Storage Site object properties (continued)

| Name Qualifier Type Description of specialization
| name (w)(pc) String The display name specified for the storage site. The length and
| (1-64) character requirements on this property are the same as those of
| the name property described in the “Base managed object
| properties schema” on page 60. Names must be unique to the other
| storage sites within the FICON configuration associated with the
| CPC identified by the URI in the cpc-uris property.
| description (w)(pc) String Arbitrary text providing additional descriptive information about
| (0-1024) the storage site.

| Default value: An empty string

|

| Class specific additional properties

| In addition to the properties defined via included schemas, this object includes the following additional
| class-specific properties:
| Table 142. Storage Site object: class specific properties
| Name Qualifier Type Description
| cpc-uris — Array of The list of CPCs that reside in this storage site. Each element in
| String/ this array is the canonical URI path of a CPC.
| URI
| storage-subsystem-uris (c)(pc) Array of The list of storage subsystems that reside in this storage site. Each
| String/ element in this array is the canonical URI path of a Storage
| URI Subsystem object.

| The value of this property will change, and property change

| notifications will be emitted, when storage subsystem objects are
| defined or undefined.
| storage-switch-uris (c)(pc) Array of The list of storage switches that reside in this storage site. Each
| String/ element in this array is the canonical URI path of a Storage Switch
| URI object.

| The value of this property will change, and property change

| notifications will be emitted, when storage switch objects are
| defined or undefined.
| type — String The type of this storage site. Values:
| Enum v "primary" - The storage site is the primary, typically local,
| location.
| v "alternate" - The storage site is an alternate, typically remote,
| location.
|

| List Storage Sites

| The List Storage Sites operation lists the storage sites known to the target Console.

| HTTP method and URI

| GET /api/storage-sites

| Query parameters:
|| Name Type Rqd/Opt Description
| cpc-uri String/URI Optional Filter string to limit returned objects to those that have a matching
| CPC URI in its cpc-uris property.

324 HMC Web Services API

 Level 04a

| 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.
|

| Response body contents

| On successful completion, the response body is a JSON object with the following fields:
|| Field name Type Description
| storage-sites Array of Array of storage-site-info objects, described in the next table. The returned
| storage- array may be empty.
| site-info
| objects
|

| Each nested storage-site-info object contains the following fields:

|| Field name Type Description
| object-uri String/ Canonical URI path (object-uri) of the Storage Site object.
| URI
| name String The name property of the Storage Site object.
| cpc-uris Array of The cpc-uris property of the Storage Site object.
| String/
| URI
| type String The type property of the Storage Site object.
| Enum
|

| Description

| This operation lists the storage sites that are known to the target Console. The object URI, name, type and
| CPC URI list are provided for each.

| If the name query parameter is specified, the returned list is limited to those storage sites that have a
| name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
| done.

| If the type query parameter is specified, the parameter is validated to ensure it is a valid value for the
| storage site type property according to the data model. If the value is not valid, a 400 (Bad Request) is
| returned. If the value is valid, the returned list is limited to those storage sites that have a type property
| matching the specified value. If the type parameter is omitted, this filtering is not done.

| If the cpc_uri query parameter is specified, the returned list is limited to those storage sites that have a
| matching CPC URI in its cpc-uris property. If the cpc-uri parameter is omitted, this filtering is not done.

| A storage site is included in the list only if the API user has task permission for the Configure Storage –
| System Programmer or Configure Storage – Storage Administrator tasks. If the API user does not have
| permission to a storage site, that object is simply omitted from the list but no error status code results.

| If no storage sites are to be included in the results due to filtering or lack of task permission, an empty
| list is provided and the operation completes successfully.

Chapter 10. Dynamic Partition Manager (DPM) 325

 Level 04a

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 325.

| 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 any associated error message.
| Table 143. List Storage Sites: 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.
| 14 A query parameter defines an invalid value.
|

| 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/storage-sites HTTP/1.1

| x-api-session: 1exubjc30uxq0rpf2gyycx230m9voc6rpuqperj8gdya59d422
|
|
| Figure 149. List Storage Sites: Request

326 HMC Web Services API

 Level 04a

| 200 OK
| server: Hardware management console API web server / 2.0
| cache-control: no-cache
| date: Mon, 30 Jul 2018 20:08:43 GMT
| content-type: application/json;charset=UTF-8
| content-length: 363
| {
| "storage-sites":[
| {
| "cpc-uris":[
| "/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e"
| ],
| "name":"New York",
| "object-uri":"/api/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492",
| "type":"primary"
| },
| {
| "cpc-uris":[
| "/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e"
| ],
| "name":"New Jersey",
| "object-uri":"/api/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492",
| "type":"alternate"
| }
| ]
| }
|
|
| Figure 150. List Storage Sites: Response

| Create Storage Site

| The Create Storage Site operation creates a new alternate Storage Site object.

| HTTP method and URI

| POST /api/storage-sites

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| cpc-uris Array of Required The value to be set as the storage site’s cpc-uris property.
| String/URI Currently, this list must contain a single CPC URI,
| representing the CPC associated with the FICON
| configuration to which this storage site belongs. This
| limitation may change in the future.
| name String Required The value to be set as the storage site's name property.
| (1-64)
| description String Optional The value to be set as the storage site's description
| (0-1024) 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 newly created Storage Site object.
|

Chapter 10. Dynamic Partition Manager (DPM) 327

 Level 04a

| Description

| This operation creates an alternate storage site with the values specified 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.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the
| cpc-uris field in the request body contains a URI that does not identify a CPC object to which the API
| user has object-access permission, a 404 (Not Found) status code is returned. If the FICON configuration
| associated with the CPC identified by the URI in the cpc-uris field in the request body already contains a
| storage site with the specified name, a 400 (Bad Request) status code is returned. If the CPC identified by
| the URI in the cpc-uris field is not enabled for DPM or does not have the dpm-storage-management
| feature enabled, or if its FICON configuration already contains the maximum number of alternate storage
| sites, or the cpc-uris field does not contain exactly one CPC URI, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the storage site is created and its properties are set to their
| corresponding request body content's field's values. The new storage site’s type property is set to
| "alternate". If a field is not found in the request body, its property's value will be defaulted.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object-access permission to each CPC whose object-id is in the cpc-uris list.
| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 327.

| 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 the associated error message.
| Table 144. Create Storage Site: 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 storage site with the name specified in the request body already exists
| within the FICON configuration associated with the CPC identified by the
| URI in the cpc-uris field specified in the request body.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 2 A CPC identified by a URI in the cpc-uris field does not exist on the HMC
| or the API user does not have object-access permission for it.

328 HMC Web Services API

 Level 04a

| Table 144. Create Storage Site: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 409 (Conflict) 5 The CPC identified by the URI in the cpc-uris field is not enabled for DPM.
| 13 A CPC identified by a URI in the cpc-uris field does not support the
| dpm-storage-management feature.
| 329 The operation cannot be performed because the CPC identified by the URI
| in the cpc-uris field is an unmanaged CPC, which is not supported by this
| operation.
| 440 The maximum number of alternate storage sites, defined by the CPC
| maximum-alternate-storage-sites property, already exist within the FICON
| configuration associated with the CPC identified by the URI in the cpc-uris
| field in the request body.
| 451 The cpc-uris field does not contain exactly one CPC URI.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/storage-sites HTTP/1.1

x-api-session: 4htyri6wi6g3tr91kv01hqxdn9aiucykq3e0ne21uvepky34yp
content-type: application/json
content-length: 119
{
"cpc-uris":[
"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e"
],
"description":"Alternate site",
"name":"New Jersey"
}

Figure 151. Create Storage Site: Request

201 Created
server: Hardware management console API web server / 2.0
location: /api/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492
cache-control: no-cache
date: Mon, 30 Jul 2018 20:06:13 GMT
content-type: application/json;charset=UTF-8
content-length: 72
{
"object-uri":"/api/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492"
}

Figure 152. Create Storage Site: Response

| Usage notes

| Each CPC maintains its own view of the physical storage sites. When a list operation is targeted at a
| console, there will likely be multiple storage site instances returned that represent the same physical site –
| one for each CPC to which that physical site is configured. There is no intrinsic storage site property that

Chapter 10. Dynamic Partition Manager (DPM) 329

 Level 04a

| can be used to correlate storage site instances that represent the same physical site. It is therefore
| recommended that API clients adopt a naming convention that ensures storage sites that represent the
| same physical site have the same value of their respective name properties.

| FICON configurations are currently limited to a single alternate storage site. This may change in the
| future, it which case a console could be managing different versions of CPC that have different alternate
| storage site limits. It is recommended that API clients use the maximum-alternate-storage-sites property
| of the CPC object to programmatically determine how many alternate sites can be created.

| Delete Storage Site

| The Delete Storage Site operation deletes an alternate storage site.

| HTTP method and URI

| DELETE /api/storage-sites/{storage-site-id}

| In this request, the URI variable {storage-site-id} is the object ID of the alternate storage site to delete.

| Description

| This operation deletes an alternate storage site. The storage site must be empty; it cannot contain any
| storage switches or storage subsystems. An Inventory Change notification for the deleted storage site is
| emitted asynchronously to this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-site-id} does not identify a storage site object on the
| HMC. If the value of the target storage site’s type property value is "primary", a 400 (Bad Request) status
| code is returned. If the target storage site’s storage-fabric-uris or storage-switch-uris array properties are
| not empty, a 409 (Conflict) status code is returned.

| If the request body contents are valid, the identified storage site is deleted from the Console.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 and associated error message.
| Table 145. Delete Storage Site: 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.
| 440 The storage site object with the object-id {storage-site-id} has a type property
| value of "primary".

330 HMC Web Services API

 Level 04a

| Table 145. Delete Storage Site: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage site with the object-id {storage-site-id} does not exist on the HMC.
| 409 (Conflict) 2 The storage site object with the object-id {storage-site-id} was busy and the
| request timed out.
| 452 The storage site with the object-id {storage-site-id} has a storage-fabric-uris or
| storage-switch-uris property that is not empty.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492 HTTP/1.1

x-api-session: ynux0a1n9betzkcvy6evkzs7aektq3ovdtj7edbanadpobvnn

Figure 153. Delete Storage Site: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 19:14:05 GMT

<No response body>

Figure 154. Delete Storage Site: Response

| Get Storage Site Properties

| The Get Storage Site Properties operation retrieves the properties of a single Storage Site object.

| HTTP method and URI

| GET /api/storage-sites/{storage-site-id}

| In this request, the URI variable {storage-site-id} is the object ID of the storage site object.

| Response body contents

| On successful completion, an HTTP status code 200 (OK) is returned and a JSON object containing the
| current values of the properties for the Storage Site object as defined in the “Data model” on page 323 is
| provided as a response body. Field names and data types in the JSON object are the same as the property
| names and data types that are defined in the data model.

| Description

| Returns the current values of the properties for the storage site object as defined in the “Data model” on
| page 323.

Chapter 10. Dynamic Partition Manager (DPM) 331

 Level 04a

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the object
| ID {storage-site-id} does not identify a storage site object on the HMC, a 404 (Not Found) status code is
| returned.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 146. Get Storage Site 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.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage site with object-id {storage-site-id} does not exist on the HMC.
|

| 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/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492 HTTP/1.1

x-api-session: 46y82ucgax84e1jtyy5w5ugv1l9lvpewu2xp9d865ipz4skwqo

Figure 155. Get Storage Site Properties: Request

332 HMC Web Services API

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:12:31 GMT
content-type: application/json;charset=UTF-8
content-length: 595
{
"class":"storage-site",
"cpc-uris":[
"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e"
],
"description":"Primary site",
"name":"New York",
"object-id":"13ff101c-941f-11e8-a0c0-fa163e27d492",
"object-uri":"/api/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492",
"parent":"/api/console",
"storage-subsystem-uris":[
"/api/storage-subsystems/37af8766-943e-11e8-8ffe-fa163e27d492",
"/api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492"
],
"storage-switch-uris":[
"/api/storage-switches/b65d1aee-9437-11e8-9c43-fa163e27d492",
"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492"
],
"type":"primary"
}

Figure 156. Get Storage Site Properties: Response

| Update Storage Site Properties

| The Update Storage Site Properties operation updates one or more of the writable properties of a storage
| site.

| HTTP method and URI

| POST /api/storage-sites/{storage-site-id}

| In this request, the URI variable {storage-site-id} is the object ID of the Storage Site object.

| Request body contents

| The request body is expected to contain a JSON object that provides the new value of any writable
| property that is to be updated by this operation. Field names and data types in this JSON object are
| expected to match the corresponding property names and data types defined in the “Data model” on
| page 323. The JSON object can and should omit fields for properties whose values are not to be changed
| by this operation.

| Description

| This operation updates a storage site's properties with the values specified.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-site-id} does not identify a Storage Site object on
| the HMC. If the FICON configuration associated with the CPC identified by the URI in the storage site’s
| cpc-uris property already contains a storage site with the specified name, a 400 (Bad Request) status code
| is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

Chapter 10. Dynamic Partition Manager (DPM) 333

 Level 04a

| If the request body contents are valid, the storage site's properties are updated to their corresponding
| request body content's field's values. All fields are optional and may be excluded from the request body;
| if a field is not found in the request body, its property's value will not be modified.

| If the update changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 147. Update Storage Site 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.
| 8 A storage site with the name specified in the request body already exists
| within the FICON configuration associated with the CPC identified by the
| URI in the cpc-uris property of the storage site with the object-id
| {storage-site-id}.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 The storage site with the object-id {storage-site-id} does not exist on the
| HMC.
| 409 (Conflict) 2 The storage site object with the object-id {storage-site-id} was busy and the
| request timed out.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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.

334 HMC Web Services API

 Level 04a

| Example HTTP interaction

|

POST /api/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492 HTTP/1.1

x-api-session: 1uhgm42bm5vbmtbwrvvpqqic5u3ffc4aqz40cjwtsjlcpm042
content-type: application/json
content-length: 51
{
"description":"Primary site",
"name":"New York"
}

Figure 157. Update Storage Site Properties: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 20:08:16 GMT

<No response body>

Figure 158. Update Storage Site Properties: Response

| Inventory service data

| Information about the Storage Sites managed by the HMC can be optionally included in the inventory
| data provided by the Inventory Service.

| Inventory entries for Storage Site objects are included in the response to the Inventory Service's Get
| Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
| by default) that objects of class "storage-site" are to be included. Information for a particular storage site
| is included only if the API user has access permission to that object as described in the Get Storage Site
| Properties operation.

| For each storage site to be included, the inventory response includes an array entry for the Storage Site
| object. This entry is a JSON object with the same contents as is specified in the Response body contents
| section of “Get Storage Site Properties” on page 331. That is, the data provided is the same as would be
| provided if a Get Storage Site Properties operation were requested targeting this object.

| Sample inventory data

| The following fragment is an example of the JSON object that would be included in the Get Inventory
| response to describe a storage site. This object would appear as one array entry in the response array:
|

Chapter 10. Dynamic Partition Manager (DPM) 335

 Level 04a

{
"class":"storage-site",
"cpc-uris":[
"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e"
],
"description":"Primary site",
"name":"New Jersey",
"object-id":"0336a208-9434-11e8-9c43-fa163e27d492",
"object-uri":"/api/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492",
"parent":"/api/console",
"storage-subsystem-uris":[
"/api/storage-subsystems/9b15669a-943e-11e8-8ffe-fa163e27d492",
"/api/storage-subsystems/93791760-943e-11e8-9c43-fa163e27d492"
],
"storage-switch-uris":[
"/api/storage-switches/0e261690-9438-11e8-8ffe-fa163e27d492",
"/api/storage-switches/fdc68064-9437-11e8-8ffe-fa163e27d492"
],
"type":"alternate"
}

Figure 159. Storage Site object: Sample inventory data - Response

|
| Storage Fabric object
| A Storage Fabric object represents a single storage fabric in the FICON configuration associated with a
| DPM-enabled CPC. A storage fabric is a collection of interconnected storage switches. If the storage
| configuration contains multiple storage sites, a storage fabric can, and typically does, span those sites.
| The Storage Fabric object APIs provide access to the set of storage fabrics within the FICON configuration
| associated with a CPC that is enabled for DPM. APIs exist to create and delete storage fabrics, list storage
| fabrics, query storage fabric properties, and update selected properties of storage fabrics.

| Data model
| This object includes the properties that are defined in the “Base managed object properties schema” on
| page 60, with the class-specific specializations identified in Table 149 on page 337. The storage fabric
| object does not support the operational status related properties.
| Table 148. Storage Fabric object properties
| Name Qualifier Type Description of specialization
| object-uri — String/ The canonical URI path of the Storage Fabric object is of the form
| URI /api/storage-fabrics/{storage-fabric-id} where
| {storage-fabric-id} is the value of the object-id property of the
| Storage Fabric object.
| object-id — String (36) The unique identifier for the storage fabric instance.
| class — String (14) The class of the Storage Fabric object is "storage-fabric".
| parent — String/URI The parent of a storage fabric is conceptually its owning Console,
| and so the parent value is the canonical URI path for the Console.
| name (w)(pc) String The display name specified for the storage fabric. The length and
| (1-64) character requirements on this property are the same as those of
| the name property described in the “Base managed object
| properties schema” on page 60. Names must be unique to the other
| storage fabrics within the FICON configuration associated with the
| CPC identified by the URI in the cpc-uris property.

336 HMC Web Services API

 Level 04a

| Table 148. Storage Fabric object properties (continued)

| Name Qualifier Type Description of specialization
| description (w)(pc) String Arbitrary text providing additional descriptive information about
| (0-1024) the storage fabric.

| Default value: An empty string

|

| Class specific additional properties

| In addition to the properties defined via included schemas, this object includes the following additional
| class-specific properties:
| Table 149. Storage Fabric object: class specific properties
| Name Qualifier Type Description
| cpc-uri — String/ The canonical URI path of the CPC object associated with the
| URI FICON configuration in which this storage fabric object resides.
| storage-switch-uris (c)(pc) Array of The list of storage switches that comprise this storage fabric. Each
| String/ element in this array is the canonical URI path of a Storage Switch
| URI object.

| The value of this property will change, and property change

| notifications will be emitted, when storage switch objects are
| defined or undefined.
| high-integrity (w)(pc) Boolean Indicates whether this fabric had been configured as a high
| integrity fabric.

| If this fabric contains switches that exist in different storage sites,

| this value will be true and cannot be written.

| Default value: false

|

| List Storage Fabrics

| The List Storage Fabrics operation lists the storage fabrics known to the target Console.

| HTTP method and URI

| GET /api/storage-fabrics

| Query parameters:
|| Name Type Rqd/Opt Description
| cpc-uri String/URI Optional Filter string to limit returned objects to those that have a matching
| cpc-uri property.
| name String Optional Filter pattern (regular expression) to limit returned objects to those
| that have 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
| storage-fabrics Array of Array of storage-fabric-info objects, described in the next table. The
| storage- returned array may be empty.
| fabric-info
| objects

Chapter 10. Dynamic Partition Manager (DPM) 337

 Level 04a

| Each nested storage-fabric-info object contains the following fields:

|| Field name Type Description
| object-uri String/ Canonical URI path (object-uri) of the Storage Fabric object.
| URI
| name String The name property of the Storage Fabric object.
| cpc-uri String/ The cpc-uri property of the Storage Fabric object.
| URI
|

| Description

| This operation lists the storage fabrics that are known to the target Console. The object URI, name, and
| CPC URI are provided for each.

| If the name query parameter is specified, the returned list is limited to those storage fabrics that have a
| name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
| done.

| If the cpc-uri query parameter is specified, the returned list is limited to those storage fabrics that have a
| matching cpc-uri property. If the cpc-uri parameter is omitted, this filtering is not done.

| A storage fabric is included in the list only if the API user has task permission for the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks. If the API user does not
| have permission to a storage fabric, that object is simply omitted from the list but no error status code
| results.

| If no storage fabrics are to be included in the results due to filtering or lack of task permission, an empty
| list is provided and the operation completes successfully.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 337.

| 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 any associated error message.
| Table 150. List Storage Fabrics: 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.
| 14 A query parameter defines an invalid value.
|

338 HMC Web Services API

 Level 04a

| 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/storage-fabrics HTTP/1.1

| x-api-session: 3tmygsxg76gvwqr4bgf2kpm2aj7z8nrbjb9ffiw6hhxfmjpm9b
|
|
| Figure 160. List Storage Fabrics: Request

| 200 OK
| server: Hardware management console API web server / 2.0
| cache-control: no-cache
| date: Mon, 30 Jul 2018 20:22:26 GMT
| content-type: application/json;charset=UTF-8
| content-length: 325
| {
| "storage-fabrics":[
| {
| "cpc-uri":"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e",
| "name":"Fabric B",
| "object-uri":"/api/storage-fabrics/24c1b2a8-9436-11e8-9c43-fa163e27d492"
| },
| {
| "cpc-uri":"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e",
| "name":"Fabric A",
| "object-uri":"/api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492"
| }
| ]
| }
|
|
| Figure 161. List Storage Fabrics: Response

| Create Storage Fabric

| The Create Storage Fabric operation creates a new Storage Fabric object.

| HTTP method and URI

| POST /api/storage-fabrics

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| cpc-uri String/URI Required The value to be set as the storage fabric’s cpc-uri
| property.
| name String Required The value to be set as the storage fabric's name property.
| (1-64)
| description String Optional The value to be set as the storage fabric's description
| (0-1024) property.
|

Chapter 10. Dynamic Partition Manager (DPM) 339

 Level 04a

| 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 of the newly created Storage Fabric object.
|

| Description

| This operation creates an alternate storage fabric with the values specified 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.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the
| cpc-uri field in the request body contains a URI that does not identify a CPC object to which the API user
| has object-access permission, a 404 (Not Found) status code is returned. If the FICON configuration
| associated with the CPC identified by the cpc-uri field in the request body already contains a storage
| fabric with the specified name, a 400 (Bad Request) status code is returned. If the CPC identified by the
| cpc-uri field is not enabled for DPM or does not have the dpm-storage-management feature enabled, or
| if direct connections between storage subsystems and adapter ports exist, a 409 (Conflict) status code is
| returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the storage fabric is created and its properties are set to their
| corresponding request body content's field's values. If a field is not found in the request body, its
| property's value will be defaulted.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object-access permission to the CPC whose object-id is cpc-uri.
| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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, and the response body is a
| standard error response body providing the reason code indicated and the associated error message.
| Table 151. Create Storage Fabric: 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 storage fabric with the name specified in the request body already exists
| within the FICON configuration associated with the CPC identified by the
| cpc-uri specified in the request body.

340 HMC Web Services API

 Level 04a

| Table 151. Create Storage Fabric: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 2 A CPC identified by the cpc-uri field does not exist on the HMC or the API
| user does not have object-access permission for it.
| 409 (Conflict) 5 The CPC identified by the cpc-uri field is not enabled for DPM.
| 13 The CPC identified by the cpc-uri field does not support the
| dpm-storage-management feature.
| 329 The operation cannot be performed because the CPC identified by the
| cpc-uris field is an unmanaged CPC, which is not supported by this
| operation.
| 455 One or more direct physical connections between a storage subsystem and
| an adapter port exist.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/storage-fabrics HTTP/1.1

x-api-session: 1r6vll1yh6tywdhmm5b7jvgf7zyf1g5r5ofs7tmmwcp6a58sx
content-type: application/json
content-length: 81
{
"cpc-uri":"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e",
"name":"Fabric A"
}

Figure 162. Create Storage Fabric: Request

201 Created
server: Hardware management console API web server / 2.0
location: /api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492
cache-control: no-cache
date: Mon, 30 Jul 2018 20:20:41 GMT
content-type: application/json;charset=UTF-8
content-length: 74
{
"object-uri":"/api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492"
}

Figure 163. Create Storage Fabric: Response

| Usage notes

| Each CPC maintains its own view of the physical storage fabric. When a list operation is targeted at a
| console, there will likely be multiple storage fabric instances returned that represent the same physical
| fabric – one for each CPC to which that physical fabric is configured. There is no intrinsic storage fabric
| property that can be used to correlate storage fabric instances that represent the same physical fabric. It is

Chapter 10. Dynamic Partition Manager (DPM) 341

 Level 04a

| therefore recommended that API clients adopt a naming convention that ensures storage fabrics that
| represent the same physical fabric have the same value of their respective name properties.

| Delete Storage Fabric

| The Delete Storage Fabric operation deletes a storage fabric.

| HTTP method and URI

| DELETE /api/storage-fabrics/{storage-fabric-id}

| In this request, the URI variable {storage-fabric-id} is the object ID of the alternate storage fabric to delete.

| Description

| This operation deletes a storage fabric. The storage fabric must be empty; it cannot contain any storage
| switches. An Inventory Change notification is emitted for the deleted storage fabric asynchronously to
| this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-fabric-id} does not identify a storage fabric object
| on the HMC. If the target storage fabric’s storage-switch-uris array property is not empty, a 409 (Conflict)
| status code is returned.

| If the request body contents are valid, the identified storage fabric is deleted from the Console.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 and associated error message.
| Table 152. Delete Storage Fabric: 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 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage fabric with the object-id {storage-fabric-id} does not exist on the
| HMC.
| 409 (Conflict) 2 The storage fabric object with the object-id {storage-fabric-id} was busy and
| the request timed out.
| 452 The storage fabric with the object-id {storage-site-id} has a storage-switch-uris
| property that is not empty.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the SE needed to perform the requested operation.

342 HMC Web Services API

 Level 04a

| 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/storage-fabrics/24c1b2a8-9436-11e8-9c43-fa163e27d492 HTTP/1.1

x-api-session: ynux0a1n9betzkcvy6evkzs7aektq3ovdtj7edbanadpobvnn

Figure 164. Delete Storage Fabric: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 19:14:05 GMT

<No response body>

Figure 165. Delete Storage Fabric: Response

| Get Storage Fabric Properties

| The Get Storage Fabric Properties operation retrieves the properties of a single Storage Fabric object.

| HTTP method and URI

| GET /api/storage-fabrics/{storage-fabric-id}

| In this request, the URI variable {storage-fabric-id} is the object ID of the storage fabric object.

| Response body contents

| On successful completion, the response body is a JSON object that provides the current values of the
| properties for the Storage Fabric object as defined in the “Data model” on page 336. 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

| Returns the current values of the properties for the Storage Fabric object as defined in the “Data model”
| on page 336.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the object
| ID {storage-fabric-id} does not identify a Storage Fabric object on the HMC, a 404 (Not Found) status code
| is returned.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

Chapter 10. Dynamic Partition Manager (DPM) 343

 Level 04a

| HTTP status and reason codes

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

| Otherwise, 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 153. Get Storage Fabric 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.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage fabric with object-id {storage-fabric-id} does not exist on the HMC.
|

| 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/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492 HTTP/1.1

x-api-session: knksjscdlzcrrh5le46x387k3uqk8qkp1tahyacguhq0p7m0d

Figure 166. Get Storage Fabric Properties: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 21:03:05 GMT
content-type: application/json;charset=UTF-8
content-length: 452
{
"class":"storage-fabric",
"cpc-uri":"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e",
"description":"Storage fabric A",
"high-integrity":true,
"name":"Fabric A",
"object-id":"08ad557c-9436-11e8-9c43-fa163e27d492",
"object-uri":"/api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492",
"parent":"/api/console",
"storage-switch-uris":[
"/api/storage-switches/fdc68064-9437-11e8-8ffe-fa163e27d492",
"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492"
]
}

Figure 167. Get Storage Fabric Properties: Response

| Update Storage Fabric Properties

| The Update Storage Fabric Properties operation updates one or more of the writable properties of a
| storage fabric.

344 HMC Web Services API

 Level 04a

| HTTP method and URI

| POST /api/storage-fabrics/{storage-fabric-id}

| In this request, the URI variable {storage-fabric-id} is the object ID of the Storage Fabric object.

| Request body contents

| The request body is expected to contain a JSON object that provides the new value of any writable
| property that is to be updated by this operation. Field names and data types in this JSON object are
| expected to match the corresponding property names and data types defined in the “Data model” on
| page 336. The JSON object can and should omit fields for properties whose values are not to be changed
| by this operation.

| Description

| This operation updates a storage fabric's properties with the values specified.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-fabric-id} does not identify a Storage Fabric object
| on the HMC. If the FICON configuration associated with the CPC identified by the URI in the storage
| fabric's cpc-uri property already contains a storage fabric with the specified name, a 400 (Bad Request)
| status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the storage fabric's properties are updated to their corresponding
| request body content's field's values. All fields are optional and may be excluded from the request body;
| if a field is not found in the request body, its property's value will not be modified.

| If the update changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 154. Update Storage Fabric 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.
| 8 A storage fabric with the name specified in the request body already exists
| within the FICON configuration associated with the CPC identified by the
| cpc-uri property of the storage fabric with the object-id {storage-fabric-id}.

Chapter 10. Dynamic Partition Manager (DPM) 345

 Level 04a

| Table 154. Update Storage Fabric Properties: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 The storage fabric with the object-id {storage-fabric-id} does not exist on the
| HMC.
| 409 (Conflict) 2 The storage fabric object with the object-id {storage-fabric-id} was busy and
| the request timed out.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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

|

POST /api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492 HTTP/1.1

x-api-session: 3cqqq1phyn2nepyewzvway545dpi8z5tycmowv3gqf5nvbw107
content-type: application/json
content-length: 35
{
"description":"Storage fabric A"
}

Figure 168. Update Storage Fabric Properties: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 20:25:17 GMT

<No response body>

Figure 169. Update Storage Fabric Properties: Response

| Inventory service data

| Information about the Storage Fabrics managed by the HMC can be optionally included in the inventory
| data provided by the Inventory Service.

| Inventory entries for storage fabric objects are included in the response to the Inventory Service's Get
| Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
| by default) that objects of class "storage-fabric" are to be included. Information for a particular storage
| fabric is included only if the API user has access permission to that object as described in the Get Storage
| Fabric Properties operation.

| For each storage fabric to be included, the inventory response includes an array entry for the Storage
| Fabric object. This entry is a JSON object with the same contents as is specified in the Response body
| contents section of “Get Storage Fabric Properties” on page 343. That is, the data provided is the same as
| would be provided if a Get Storage Fabric Properties operation were requested targeting this object.

346 HMC Web Services API

 Level 04a

| Sample inventory data

| The following fragment is an example of the JSON object that would be included in the Get Inventory
| response to describe a storage fabric. This object would appear as one array entry in the response array:
|

| {
| "class":"storage-fabric",
| "cpc-uri":"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e",
| "description":"Storage fabric A",
| "high-integrity":true,
| "name":"Fabric A",
| "object-id":"08ad557c-9436-11e8-9c43-fa163e27d492",
| "object-uri":"/api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492",
| "parent":"/api/console",
| "storage-switch-uris":[
| "/api/storage-switches/fdc68064-9437-11e8-8ffe-fa163e27d492",
| "/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492"
| ]
| }
|
|
| Figure 170. Storage Fabric object: Sample inventory data - Response
|
| Storage Switch object
| A Storage Switch object represents a single storage switch in the FICON configuration associated with a
| DPM-enabled CPC. The Storage Switch object APIs provide access to the set of storage switches in the
| FICON configuration associated with a CPC that is enabled for DPM. APIs exist to define and undefine
| storage switches, list storage switches, query storage switch properties, update selected properties of
| storage switches, and move a storage switch to another storage site or storage fabric.

| Data model
| This object includes the properties that are defined in the “Base managed object properties schema” on
| page 60, with the class-specific specializations identified in Table 156 on page 348. The Storage Switch
| object does not support the operational status related properties.
| Table 155. Storage Switch object: base managed object properties specializations
| Name Qualifier Type Description of specialization
| object-uri — String/ The canonical URI path of the Storage Switch object is of the form
| URI /api/storage-switches/{storage-switch-id} where
| {storage-switch-id} is the value of the object-id property of the
| Storage Switch object.
| object-id — String (36) The unique identifier for the storage switch instance.
| class — String (14) The class of the Storage Switch object is "storage-switch".
| parent — String/URI The parent of a storage site is conceptually its owning Console, and
| so the parent value is the canonical URI path for the Console.
| name (w)(pc) String The display name specified for the storage switch. The length and
| (1-64) character requirements on this property are the same as those of
| the name property described in the “Base managed object
| properties schema” on page 60. Names must be unique to the other
| storage sites within the FICON configuration of its containing
| storage site and storage fabric.

| Default value: Currently of the form "Storage switch {domain-id}",

| where {domain-id} is the value of the domain-id property. This form
| is subject to change in the future.

Chapter 10. Dynamic Partition Manager (DPM) 347

 Level 04a

| Table 155. Storage Switch object: base managed object properties specializations (continued)
| Name Qualifier Type Description of specialization
| description (w)(pc) String Arbitrary text providing additional descriptive information about
| (0-1024) the storage switch.

| Default value: An empty string

|

| Class specific additional properties

| In addition to the properties defined via included schemas, this object includes the following additional
| class-specific properties:
| Table 156. Storage Switch object: class specific properties
| Name Qualifier Type Description
| domain-id (w)(pc) String (2) A two-character lowercase hexadecimal number in the range 01-ef
| that represents the domain identifier assigned to the storage
| switch. Domain identifiers must be unique to the other storage
| switches within the same fabric.
| port-count (w)(pc) Integer The number of ports on the switch.
| (2-256)
| Default value: 256
| storage-fabric-uri (pc) String/ The canonical URI of the storage fabric associated with this storage
| URI switch.

| The value of this property will change, and property change

| notifications will be emitted, when the storage switch is moved
| from one storage fabric to another via the Move Storage Switch to
| Storage Fabric operation
| storage-site-uri (pc) String/ The canonical URI of the storage site associated with this storage
| URI switch.

| The value of this property will change, and property change

| notifications will be emitted, when the storage switch is moved
| from one storage site to another via the Move Storage Switch to
| Storage Site operation.
|

| List Storage Switches of a Storage Site

| The List Storage Switches of a Storage Site operation lists the storage switches associated with the
| storage site with the given identifier.

| HTTP method and URI

| GET /api/storage-sites/{storage-site-id}/storage-switches

| In this request, the URI variable {storage-site-id} is the object-id of the Storage Site object.

| 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.
| domain-id String Optional Filter pattern (regular expression) to limit returned objects to those
| that have a matching domain-id property.
| storage-fabric-uri String/URI Optional Filter string to limit returned objects to those that have a matching
| storage-fabric-uri property.
|
348 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
| storage-switches Array of Array of storage-switch-info objects, described in the next table. The
| storage- returned array may be empty.
| switch-
| info
| objects
|

| Each nested storage-switch-info object contains the following fields:

|| Field name Type Description
| object-uri String/ Canonical URI path (object-uri) of the Storage Switch object.
| URI
| name String The name property of the Storage Switch object.
| domain-id String The domain-id property of the Storage Switch object.
| storage-fabric-uri String/ The storage-fabric-uri property of the Storage Switch object.
| URI
|

| Description

| This operation lists the storage switches that are associated with the identified storage site. The object
| URI, name, domain ID and associated storage fabric are provided for each.

| If the object ID {storage-site-id} does not identify a Storage Site object on the HMC, a 404 (Not Found)
| status code is returned.

| If the name or domain-id query parameters are specified, the returned list is limited to those storage
| switches that have the same-named property matching the specified filter pattern. If any parameter is
| omitted, this filtering on that property is not done.

| If the storage-fabric-uri query parameter is specified, the returned list is limited to those storage switches
| that have a matching storage-fabric-uri property. If the storage-fabric-uri parameter is omitted, this
| filtering is not done.

| A storage switch is included in the list only if the API user has task permission for the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks. If the specified storage site is
| associated with a storage switch but the API user does not have permission to it, that object is simply
| omitted from the list but no error status code results.

| If no storage switches are to be included in the results due to filtering or lack of task permission, an
| empty list is provided and the operation completes successfully.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

Chapter 10. Dynamic Partition Manager (DPM) 349

 Level 04a

| 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 349.

| 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 any associated error message.
| Table 157. List Storage Switches of a Storage Site: 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.
| 14 A query parameter defines an invalid value.
| 404 (Not Found) 1 The storage site with the object ID {storage-site-id} does not exist on the
| HMC.
|

| 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/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492/storage-switches
| HTTP/1.1
| x-api-session: 158gv9ldjh8x0yarl3qjx5o7xhemmtku20ejfi92rtk8hb3yln
|
|
| Figure 171. List Storage Switches of a Storage Site: Request

| 200 OK
| server: Hardware management console API web server / 2.0
| cache-control: no-cache
| date: Mon, 30 Jul 2018 20:39:12 GMT
| content-type: application/json;charset=UTF-8
| content-length: 424
| {
| "storage-switches":[
| {
| "domain-id":"11",
| "name":"Storage switch 11",
| "object-uri":"/api/storage-switches/fdc68064-9437-11e8-8ffe-fa163e27d492",
| "storage-fabric-uri":"/api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492"
| },
| {
| "domain-id":"21",
| "name":"Storage switch 21",
| "object-uri":"/api/storage-switches/0e261690-9438-11e8-8ffe-fa163e27d492",
| "storage-fabric-uri":"/api/storage-fabrics/24c1b2a8-9436-11e8-9c43-fa163e27d492"
| }
| ]
| }
|
|
| Figure 172. List Storage Switches of a Storage Site: Response

350 HMC Web Services API

 Level 04a

| List Storage Switches of a Storage Fabric

| The List Storage Switches of a Storage Fabric operation lists the storage switches associated with the
| storage fabric with the given identifier.

| HTTP method and URI

| GET /api/storage-fabrics/{storage-fabric-id}/storage-switches

| In this request, the URI variable {storage-fabric-id} is the object-id of the Storage Fabric object.

| 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.
| domain-id String Optional Filter pattern (regular expression) to limit returned objects to those
| that have a matching domain-id property.
| storage-site-uri String/URI Optional Filter string to limit returned objects to those that have a matching
| storage-site-uri property.
|

| Response body contents

| On successful completion, the response body is a JSON object with the following fields:
|| Field name Type Description
| storage-switches Array of Array of storage-switch-info objects, described in the next table. Returned
| storage- array may be empty.
| switch-
| info
| objects
|

| Each nested storage-switch-info object contains the following fields:

|| Field name Type Description
| object-uri String/ Canonical URI path (object-uri) of the Storage Switch object.
| URI
| name String The name property of the Storage Switch object.
| domain-id String The domain-id property of the Storage Switch object.
| storage-site-uri String/ The storage-site-uri property of the Storage Switch object.
| URI
|

| Description

| This operation lists the storage switches that are associated with the identified storage fabric. The object
| URI, name, domain ID, and associated site are provided for each.

| If the object ID {storage-fabric-id} does not identify a Storage Fabric object on the HMC, a 404 (Not Found)
| status code is returned.

| If the name or domain-id query parameters are specified, the returned list is limited to those storage
| switches that have the same-named property matching the specified filter pattern. If any parameter is
| omitted, this filtering on that property is not done.

Chapter 10. Dynamic Partition Manager (DPM) 351

 Level 04a

| If the storage-site-uri query parameter is specified, the returned list is limited to those storage sites that
| have a matching storage-site-uri property. If the storage-site-uri parameter is omitted, this filtering is not
| done.

| A storage switch is included in the list only if the API user has task permission for the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks. If the specified storage fabric
| is associated with a storage switch but the API user does not have permission to it, that object is simply
| omitted from the list but no error status code results.

| If no storage switches are to be included in the results due to filtering or lack of task permission, an
| empty list is provided and the operation completes successfully.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 351.

| 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 any associated error message.
| Table 158. List Storage Switches of a Storage Fabric: 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.
| 14 A query parameter defines an invalid value.
| 404 (Not Found) 1 The storage fabric with the object ID {storage-fabric-id} does not exist on the
| HMC.
|

| 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/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492/storage-switches
| HTTP/1.1
| x-api-session: 5iggido8gsjbbun0k77blh9bsfvdxn8swdioyonor0ohpuebfu
|
|
| Figure 173. List Storage Switches of a Storage Fabric: Request

352 HMC Web Services API

 Level 04a

| 200 OK
| server: Hardware management console API web server / 2.0
| cache-control: no-cache
| date: Mon, 30 Jul 2018 21:08:30 GMT
| content-type: application/json;charset=UTF-8
| content-length: 416
| {
| "storage-switches":[
| {
| "domain-id":"11",
| "name":"Storage switch 11",
| "object-uri":"/api/storage-switches/fdc68064-9437-11e8-8ffe-fa163e27d492",
| "storage-site-uri":"/api/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492"
| },
| {
| "domain-id":"10",
| "name":"Storage switch 10",
| "object-uri":"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492",
| "storage-site-uri":"/api/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492"
| }
| ]
| }
|
|
| Figure 174. List Storage Switches of a Storage Fabric: Response

| Define Storage Switch

| The Define Storage Switch operation defines a new Storage Switch object.

| HTTP method and URI

| POST /api/console/operations/define-storage-switch

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| name String Optional The value to be set as the storage switch's name property.
| (1-64)
| description String Optional The value to be set as the storage switch's description
| (0-1024) property.
| domain-id String (2) Required The value to be set as the storage switch's domain-id
| property.
| port-count Integer Optional The value to be set as the storage switch's port-count
| (2-256) property.
| storage-fabric-uri String/URI Required The value to be set as the storage switch's
| storage-fabric-uri property.
| storage-site-uri String/URI Required The value to be set as the storage switch's storage-site-uri
| 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 newly defined Storage Switch object.

Chapter 10. Dynamic Partition Manager (DPM) 353

 Level 04a

| Description

| This operation defines a storage switch with the values specified and then returns its object-uri in the
| response body. An Inventory Change notification and Property Change notifications for the associated
| storage site and storage fabric's storage-switch-uris properties are emitted asynchronously to this
| operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the URI
| specified in the storage-site-uri field does not identify a storage site object on the HMC, or the URI
| specified in the storage-fabric-uri field does not identify a storage fabric on the HMC, a 404 (Not Found)
| status code is returned. If the storage fabric identified by {storage-fabric-id} already contains a storage
| switch with the specified domain-id, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| another storage switch with the specified name exists within the same FICON configuration in which the
| containing storage size and storage fabric exist.

| If the request body contents are valid, the storage switch is defined and its properties are set to their
| corresponding request body content's field's values. If a field is not found in the request body, its
| property's value will be defaulted.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 353.

| 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 the associated error message.
| Table 159. Define Storage Switch: 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 storage switch with the name specified in the request body already exists
| within the same FICON configuration in which the containing storage site
| and storage fabric exist.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 2 A storage site with the URI specified in the storage-site-uri field does not
| exist on the HMC.
| 440 A storage fabric with the URI specified in the storage-fabric-uri field does
| not exist on the HMC.

354 HMC Web Services API

 Level 04a

| Table 159. Define Storage Switch: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 409 (Conflict) 445 A storage switch with the domain-id specified in the request body already
| exists within the storage fabric identified by the storage-fabric-uri field in
| the request body.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/console/operations/define-storage-switch HTTP/1.1

x-api-session: 27u5v0reohtwg2ncuw2xebonfrtxpkbdst3cmc5w12jemo6iet
content-type: application/json
content-length: 181
{
"domain-id":"10",
"storage-fabric-uri":"/api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492",
"storage-site-uri":"/api/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492"
}

Figure 175. Define Storage Switch: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 20:31:45 GMT
content-type: application/json;charset=UTF-8
content-length: 75
{
"object-uri":"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492"
}

Figure 176. Define Storage Switch: Response

| Usage notes

| Each CPC maintains its own view of the physical storage switches. When a list operation is targeted at a
| console, there will likely be multiple storage switch instances returned that represent the same physical
| switch – one for each CPC to which that physical switch is configured. There is no intrinsic storage
| switch property that can be used to correlate storage switch instances that represent the same physical
| switch. It is therefore recommended that API clients adopt a naming convention that ensures storage
| switches that represent the same physical switch have the same value of their respective name and
| domain-id properties.

| Undefine Storage Switch

| The Undefine Storage Switch operation removes a storage switch definition.

| HTTP method and URI

| POST /api/storage-switches/{storage-switch-id}/operations/undefine

Chapter 10. Dynamic Partition Manager (DPM) 355

 Level 04a

| In this request, the URI variable {storage-switch-id} is the object ID of the storage switch that is to be
| undefined.

| Description

| This operation removes a storage switch definition. If the storage switch contains switch ports, they will
| be removed as well. An Inventory Change notification and Property Change notifications for the
| associated storage site’s and storage fabric’s storage-switch-uris properties are emitted asynchronously to
| this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-switch-id} does not identify a storage switch object
| on the HMC.

| If any physical connections from adapters or storage subsystems to the storage switch exist, a 409
| (Conflict) status code is returned.

| If the request body contents are valid, the identified storage switch definition is removed.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 and associated error message.
| Table 160. Undefine Storage Switch: 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 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 2 A storage switch with the object ID {storage-switch-id} does not exist on the
| HMC.
| 409 (Conflict) 2 The storage switch object with the object ID {storage-switch-id} was busy and
| the request timed out.
| 446 An endpoint connection in an adapter or storage subsystem references the
| Storage Switch object with the object ID {storage-switch-id}.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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.

356 HMC Web Services API

 Level 04a

| Example HTTP interaction

|

POST /api/storage-switches/fdc68064-9437-11e8-8ffe-fa163e27d492/operations/undefine
HTTP/1.1
x-api-session: ynux0a1n9betzkcvy6evkzs7aektq3ovdtj7edbanadpobvnn
content-type: application/json

Figure 177. Undefine Storage Switch: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 19:14:05 GMT

<No response body>

Figure 178. Undefine Storage Switch: Response

| Get Storage Switch Properties

| The Get Storage Switch Properties operation retrieves the properties of a single Storage Switch object.

| HTTP method and URI

| GET /api/storage-switches/{storage-switch-id}

| In this request, the URI variable {storage-switch-id} is the object ID of the storage switch object.

| Response body contents

| On successful completion, the response body is a JSON object that provides the current values of the
| properties for the Storage Switch object as defined in the “Data model” on page 347. 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

| Returns the current values of the properties for the Storage Switch object as defined in the “Data model”
| on page 347.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the object
| ID {storage-switch-id} does not identify a storage switch object on the HMC, a 404 (Not Found) status code
| is returned.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

Chapter 10. Dynamic Partition Manager (DPM) 357

 Level 04a

| Otherwise, 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 161. Get Storage Switch 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.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage switch with object-id {storage-switch-id} does not exist on the
| HMC.
|

| 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/storage-switches/90204662-9437-11e8-9c43-fa163e27d492 HTTP/1.1

x-api-session: 5067e2d7z01ujz4o5j106jy255f01248enx0p5wlnr8ti98xld

Figure 179. Get Storage Switch Properties: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 20:55:23 GMT
content-type: application/json;charset=UTF-8
content-length: 411
{
"class":"storage-switch",
"description":"",
"domain-id":"10",
"name":"Storage switch 10",
"object-id":"90204662-9437-11e8-9c43-fa163e27d492",
"object-uri":"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492",
"parent":"/api/console",
"port-count":256,
"storage-fabric-uri":"/api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492",
"storage-site-uri":"/api/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492"
}

Figure 180. Get Storage Switch Properties: Response

| Update Storage Switch Properties

| The Update Storage Switch Properties operation updates one or more of the writable properties of a
| storage switch.

| HTTP method and URI

| POST /api/storage-switches/{storage-switch-id}

| In this request, the URI variable {storage-switch-id} is the object ID of the Storage Switch object.

358 HMC Web Services API

 Level 04a

| Request body contents

| The request body is expected to contain a JSON object that provides the new value of any writable
| property that is to be updated by this operation. Field names and data types in this JSON object are
| expected to match the corresponding property names and data types defined in the “Data model” on
| page 347. The JSON object can and should omit fields for properties whose values are not to be changed
| by this operation.

| Description

| This operation updates a storage switch's properties with the values specified.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-switch-id} does not identify a Storage Switch object
| on the HMC. If the containing storage fabric already contains a storage switch with the specified
| domain-id or the port-count field value does not allow for the currently configured ports, a 409 (Conflict)
| status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| another storage switch with the specified name exists within the same FICON configuration in which the
| containing storage site and storage fabric exist.

| If the request body contents are valid, the storage switch's properties are updated to their corresponding
| request body content's field's values. All fields are optional and may be excluded from the request body;
| if a field is not found in the request body, its property's value will not be modified.

| If the update changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 162. Update Storage Switch 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.
| 8 A storage switch with the name specified in the request body already exists
| within the FICON configuration in which the containing storage site and
| storage fabric exist.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.

Chapter 10. Dynamic Partition Manager (DPM) 359

 Level 04a

| Table 162. Update Storage Switch Properties: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 404 (Not Found) 1 The storage switch with the object-id {storage-switch-id} does not exist on the
| HMC.
| 409 (Conflict) 2 The storage switch object with the object-id {storage-switch-id} was busy and
| the request timed out.
| 441 The value of the port-count field does not allow for the currently configured
| ports on the Storage Switch object with the object-id {storage-switch-id}.
| 445 A storage switch with the domain-id specified in the request body already
| exists within its associated storage fabric.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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

|

POST /api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492 HTTP/1.1

x-api-session: z73khdzsrzllklgo1gbn095ot7bgckt4g6ki1mwggeizean3
content-type: application/json
content-length: 50
{
"description":"Switch 10 in New York, Fabric A"
}

Figure 181. Update Storage Switch Properties: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 20:56:44 GMT

<No response body>

Figure 182. Update Storage Switch Properties: Response

| Move Storage Switch to Storage Site

| The Move Storage Switch to Storage Site operation moves a storage switch from its current storage site
| to a different storage site.

| HTTP method and URI

| POST /api/storage-switches/{storage-switch-id}/operations/move-storage-site

| In this request, the URI variable {storage-switch-id} is the object ID of the storage switch that is to be
| moved.

360 HMC Web Services API

 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
| storage-site-uri String/URI Required The canonical URI path for the storage site to which this
| switch is to be moved.
|

| Description

| This operation moves a storage switch from the storage site to which it is currently associated to a
| different storage site within the same FICON configuration.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-switch-id} does not identify a Storage Switch object
| on the HMC, or the URI specified in the storage-site-uri field does not identify a Storage Site object on
| the HMC. If the storage site specified in the storage-site-uri field already contains the Storage Switch, a
| 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| the new storage site is associated with a different FICON configuration.

| If the request body contents are valid, the storage-site-uri property of the storage switch identified by
| {storage-switch-id} is updated to the value specified in the storage-site-uri field. The storage switch is
| removed from the storage-switch-uris array property of the original storage site and added to the
| storage-switch-uris property of the new storage site.

| Property-change notifications on the switch’s storage-site-uri property and on both the original and new
| storage site’s storage-switch-uris properties are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 163. Move Storage Switch to Storage Site: 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.
| 441 The storage site identified by the storage-site-uri field is associated with a
| different FICON configuration than the current storage site.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.

Chapter 10. Dynamic Partition Manager (DPM) 361

 Level 04a

| Table 163. Move Storage Switch to Storage Site: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 404 (Not Found) 1 The storage switch with the object-id {storage-switch-id} does not exist on the
| HMC.
| 2 The storage site identified by the storage-site-uri field does not exist on the
| HMC.
| 409 (Conflict) 2 The storage switch object with the object-id {storage-switch-id} was busy and
| the request timed out.
| 450 The storage site identified by the storage-site-uri field already contains a
| storage switch with the object-id {storage-switch-id}.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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

|

POST /api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492/operations/move-
storage-site HTTP/1.1
x-api-session: 45bnirh6wcq2qs1a9fqyxnozbufxfv0yzjnnlq0ojtfxgs35mm
content-type: application/json
content-length: 79
{
"storage-site-uri":"/api/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492"
}

Figure 183. Move Storage Switch to Storage Site: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 20:43:09 GMT

<No response body>

Figure 184. Move Storage Switch to Storage Site: Response

| Move Storage Switch to Storage Fabric

| The Move Storage Switch to Storage Fabric operation moves a storage switch from its current storage
| fabric to a different storage fabric.

| HTTP method and URI

| POST /api/storage-switches/{storage-switch-id}/operations/move-storage-fabric

| In this request, the URI variable {storage-switch-id} is the object ID of the storage switch that is to be
| moved.

362 HMC Web Services API

 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
| storage-fabric-uri String/URI Required The canonical URI path for the storage fabric to which
| this switch is to be moved.
|

| Description

| This operation moves a storage switch from the storage fabric to which it is currently associated to a
| different storage fabric within the same FICON configuration.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-switch-id} does not identify a Storage Switch object
| on the HMC, or the URI specified in the storage-fabric-uri field does not identify a Storage Fabric object
| on the HMC. If the storage fabric specified in the storage-fabric-uri field already contains the Storage
| Switch, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| the new storage fabric is associated with a different FICON configuration.

| If the request body contents are valid, the storage-fabric-uri property of the storage switch identified by
| {storage-switch-id} is updated to the value specified in the storage-fabric-uri field. The storage switch is
| removed from the storage-switch-uris array property of the original storage fabric and added to the
| storage-switch-uris property of the new storage fabric.

| Property-change notifications on the switch’s storage-fabric-uri property and on both the original and
| new storage fabric’s storage-switch-uris properties are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 164. Move Storage Switch to Storage Fabric: 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.
| 441 The storage fabric identified by the storage-fabric-uri field is associated with
| a different FICON configuration than the current storage fabric.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.

Chapter 10. Dynamic Partition Manager (DPM) 363

 Level 04a

| Table 164. Move Storage Switch to Storage Fabric: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 404 (Not Found) 1 The storage switch with the object-id {storage-switch-id} does not exist on the
| HMC.
| 2 The storage fabric identified by the storage-fabric-uri field does not exist on
| the HMC.
| 409 (Conflict) 2 The storage switch object with the object-id {storage-switch-id} was busy and
| the request timed out.
| 450 The storage fabric identified by the storage-fabric-uri field already contains a
| storage switch with the object-id {storage-switch-id}.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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

|

POST /api/storage-switches/0e261690-9438-11e8-8ffe-fa163e27d492/operations/move-storage-fabric HTTP/1.1

x-api-session: 3u4lvmbq452l5fjupxm3jjuzua6i1sbqhb7fguq1l3zbha7frp
content-type: application/json
content-length: 83
{
"storage-fabric-uri":"/api/storage-fabrics/08ad557c-9436-11e8-9c43-fa163e27d492"
}

Figure 185. Move Storage Switch to Storage Fabric: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 20:45:56 GMT

<No response body>

Figure 186. Move Storage Switch to Storage Fabric: Response

| Inventory service data

| Information about the Storage Switches managed by the HMC can be optionally included in the
| inventory data provided by the Inventory Service.

| Inventory entries for storage switch objects are included in the response to the Inventory Service's Get
| Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
| by default) that objects of class "storage-switch" are to be included. Information for a particular storage
| switch is included only if the API user has access permission to that object as described in the Get
| Storage Switch Properties operation.

| For each storage switch to be included, the inventory response includes an array entry for the Storage
| Switch object. This entry is a JSON object with the same contents as is specified in the “Response body
| contents” section for “Get Storage Switch Properties” on page 357. That is, the data provided is the same
| as would be provided if a Get Storage Switch Properties operation were requested targeting this object.:

364 HMC Web Services API

 Level 04a

| Sample inventory data

| The following fragment is an example of the JSON object that would be included in the Get Inventory
| response to describe a storage switch. This object would appear as one array entry in the response array:
|

| {
| "class":"storage-switch",
| "description":"",
| "domain-id":"21",
| "name":"Storage switch 21",
| "object-id":"0e261690-9438-11e8-8ffe-fa163e27d492",
| "object-uri":"/api/storage-switches/0e261690-9438-11e8-8ffe-fa163e27d492",
| "parent":"/api/console",
| "port-count":256,
| "storage-fabric-uri":"/api/storage-fabrics/24c1b2a8-9436-11e8-9c43-fa163e27d492",
| "storage-site-uri":"/api/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492"
| }
|
|
| Figure 187. Storage Switch object: Sample inventory data - Response
|
| Storage Subsystem object
| A Storage Subsystem object represents a single storage subsystem in the FICON configuration associated
| with a DPM-enabled CPC. The Storage Subsystem object APIs provide access to the set of storage
| subsystems in the FICON configuration. APIs exist to define and undefine storage subsystems, list
| storage subsystems, query storage subsystem properties, update selected properties of storage
| subsystems, move a storage subsystem to a different site, and to manage a storage subsystem’s endpoint
| connections.

| Data model
| This object includes the properties that are defined in the “Base managed object properties schema” on
| page 60, with the class-specific specializations identified in Table 166 on page 366. The Storage Subsystem
| object does not support the operational status related properties.
| Table 165. Storage Subsystem object: base managed object properties specializations
| Name Qualifier Type Description of specialization
| object-uri — String/ The canonical URI path of the Storage Subsystem object is of the
| URI form /api/storage-subsystems/{storage-subsystem-id} where
| {storage-subsystem-id} is the value of the object-id property of the
| Storage Subsystem object.
| object-id — String (36) The unique identifier for the storage subsystem instance.
| class — String (17) The class of the Storage Subsystem object is "storage-subsystem".
| parent — String/URI The parent of a storage subsystem is conceptually its owning
| Console, and so the parent value is the canonical URI path for the
| Console.
| name (w)(pc) String The display name specified for the storage subsystem. The length
| (1-64) and character requirements on this property are the same as those
| of the name property described in the “Base managed object
| properties schema” on page 60. Names must be unique to the other
| storage subsystems within the FICON configuration of its
| containing storage site.
| description (w)(pc) String Arbitrary text providing additional descriptive information about
| (0-1024) the storage subsystem.

| Default value: An empty string

Chapter 10. Dynamic Partition Manager (DPM) 365

 Level 04a

| Class specific additional properties

| In addition to the properties defined via included schemas, this object includes the following additional
| class-specific properties:
| Table 166. Storage Subsystem object: class specific properties
| Name Qualifier Type Description
| connection-endpoints (c)(pc) Array of Array of subsystem-connection-endpoint objects, described in the
| subsystem- next table. A subsystem connection endpoint describes a switch or
| connection- adapter to which this storage subsystem is physically connected.
| endpoint
| objects There can be at most 64 connection endpoints configured to a
| single storage subsystem.

| The value of this property will change, and property change

| notifications will be emitted, when endpoints are added and
| removed via the Add Connection Endpoint and Remove
| Connection Endpoint operations.
| storage-control-unit-uris (c)(pc) Array of The list of storage control units defined within the storage
| String/ subsystem. Each element in this array is the canonical URI path of
| URI a Storage Control Unit object.

| The value of this property will change, and property change

| notifications will be emitted, when storage control units are
| defined or undefined via the Define Storage Control Unit and
| Undefine Storage Control Unit operations
| storage-site-uri (pc) String/ The canonical URI of the storage site associated with this storage
| URI subsystem.

| The value of this property will change, and property change

| notifications will be emitted, when the storage switch is moved
| from one storage site to another via the Move Storage Subsystem
| to Storage Site operation.
|

| A connection endpoint defines a storage switch or adapter to which a storage subsystem is physically
| connected.
| Table 167. subsystem-connection-endpoint nested object properties
| Name Qualifier Type Description
| endpoint-class — String The class of the object identified by endpoint-uri. Values:
| Enum v "adapter" – The storage subsystem is directly connected to an
| adapter.
| v "storage-switch" – The storage subsystem is connected to a
| storage switch.
| endpoint-uri — String/ The canonical URI path for the Storage Switch or Adapter object to
| URI which this subsystem is connected.
| port-id — String (2) A two-character lowercase hexadecimal number that represents the
| switch port.

| This value will be null if endpoint-uri references an Adapter

| object.
|

| List Storage Subsystems of a Storage Site

| The List Storage Subsystems of a Storage Site operation lists the storage subsystems associated with the
| storage site with the given identifier.
366 HMC Web Services API
 Level 04a

| HTTP method and URI

| GET /api/storage-sites/{storage-site-id}/storage-subsystems

| In this request, the URI variable {storage-site-id} is the object-id of the Storage Site object.

| 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.
|

| Response body contents

| On successful completion, the response body is a JSON object with the following fields:
|| Field name Type Description
| storage-subsystems Array of Array of storage-subsystem-info objects, described in the next table. The
| storage- returned array may be empty.
| subsystem-
| info
| objects
|

| Each nested storage-subsystem-info object contains the following fields:

|| Field name Type Description
| object-uri String/ Canonical URI path (object-uri) of the Storage Subsystem object.
| URI
| name String The name property of the Storage Subsystem object.
|

| Description

| This operation lists the storage subsystems that are associated with the identified storage site. The object
| URI and name are provided for each.

| If the object ID {storage-site-id} does not identify a storage site object on the HMC, a 404 (Not Found)
| status code is returned.

| If the name query parameter is specified, the returned list is limited to those storage subsystems that
| have a name property that matches the specified filter pattern. If the name parameter is omitted, this
| filtering is not done.

| A storage subsystem is included in the list only if the API user has task permission for the Configure
| Storage – System Programmer or Configure Storage – Storage Administrator tasks. If the specified
| storage site is associated with a storage subsystem but the API user does not have permission to it, that
| object is simply omitted from the list but no error status code results.

| If no storage subsystems are to be included in the results due to filtering or lack of task permission, an
| empty list is provided and the operation completes successfully.

| Authorization requirements

| This operation has the following authorization requirement:

Chapter 10. Dynamic Partition Manager (DPM) 367

 Level 04a

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –

| Storage Administrator tasks.

| 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 367.

| 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 any associated error message.
| Table 168. List Storage Subsystems of a Storage Site: 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.
| 14 A query parameter defines an invalid value.
| 404 (Not Found) 1 The storage site with the object ID {storage-site-id} does not exist on the
| HMC.
|

| 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/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492/storage-subsystems
| HTTP/1.1
| x-api-session: 2fdcirhybjv0ogapni5r3z0oo86u7qj87id7rlcons4ce2jfiw
|
|
| Figure 188. List Storage Subsystems of a Storage Site: Request

| 200 OK
| server: Hardware management console API web server / 2.0
| cache-control: no-cache
| date: Mon, 30 Jul 2018 21:29:44 GMT
| content-type: application/json;charset=UTF-8
| content-length: 216
| {
| "storage-subsystems":[
| {
| "name":"DS8886 A",
| "object-uri":"/api/storage-subsystems/37af8766-943e-11e8-8ffe-fa163e27d492"
| },
| {
| "name":"DS8870 A",
| "object-uri":"/api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492"
| }
| ]
| }
|
|
| Figure 189. List Storage Subsystems of a Storage Site: Response

368 HMC Web Services API

 Level 04a

| Define Storage Subsystem

| The Define Storage Subsystem operation defines a new Storage Subsystem object.

| HTTP method and URI

| POST /api/console/operations/define-storage-subsystem

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| name String Required The value to be set as the storage subsystem's name
| (1-64) property.
| description String Optional The value to be set as the storage subsystem's description
| (0-1024) property.
| storage-site-uri String/URI Required The value to be set as the storage subsystem's
| storage-site-uri 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 newly defined Storage Subsystem object.
|

| Description

| This operation defines a storage subsystem with the specified values and then returns its object-uri in the
| response body. An Inventory Change notification and a property-change notification on the associated
| storage site’s storage-subsystem-uris property are emitted asynchronously to this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the URI
| specified in the storage-site-uri field does not identify a storage site object on the HMC, a 404 (Not
| Found) status code is returned. If another storage subsystem with the specified name exists within the
| same FICON configuration in which the containing storage site exists, a 400 (Bad Request) status code is
| returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the storage subsystem is defined and its properties are set to their
| corresponding request body content's field's values. If a field is not found in the request body, its
| property's value will be defaulted.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

Chapter 10. Dynamic Partition Manager (DPM) 369

 Level 04a

| 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 369.

| 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 the associated error message.
| Table 169. Define Storage Subsystem: 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 storage subsystem with the name specified in the request body already
| exists within the same FICON configuration in which the containing storage
| site exists.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 2 A storage site with the URI specified in the storage-site-uri field does not
| exist on the HMC.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/console/operations/define-storage-subsystem HTTP/1.1

x-api-session: 4mmbozhl0i5mvnrlosv8r1r5e5hrfd7gc82pkpzqbm0cv6bepx
content-type: application/json
content-length: 99
{
"name":"DS8870 A",
"storage-site-uri":"/api/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492"
}

Figure 190. Define Storage Subsystem: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 21:21:02 GMT
content-type: application/json;charset=UTF-8
content-length: 77
{
"object-uri":"/api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492"
}

Figure 191. Define Storage Subsystem: Response

370 HMC Web Services API

 Level 04a

| Usage notes

| Each CPC maintains its own view of the physical storage subsystems. When a list operation is targeted at
| a console, there will likely be multiple storage subsystem instances returned that represent the same
| physical subsystem – one for each CPC to which that physical subsystem is configured. There is no
| intrinsic storage subsystem property that can be used to correlate storage subsystem instances that
| represent the same physical subsystems. It is therefore recommended that API clients adopt a naming
| convention that ensures storage subsystems that represent the same physical subsystem have the same
| value of their respective name properties.

| Undefine Storage Subsystem

| The Undefine Storage Subsystem operation removes a storage subsystem definition.

| HTTP method and URI

| POST /api/storage-subsystems/{storage-subsystem-id}/operations/undefine

| In this request, the URI variable {storage-subsystem-id} is the object ID of the storage subsystem that is to
| be undefined.

| Description

| This operation removes a storage subsystem definition. If the storage subsystem contains storage control
| units or connection endpoints, they will be removed as well. Switch or adapter objects referenced by a
| deleted endpoint are not deleted. Inventory Change notifications for the removed storage subsystem and
| for each of its contained storage control units are emitted asynchronously to this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-subsystem-id} does not identify a storage subsystem
| object on the HMC.

| If physical connections from adapters or storage switches to the storage subsystem exist, a 409 (Conflict)
| status code is returned.

| If the request body contents are valid, the identified storage subsystem definition, and all its storage
| control units and connection endpoints, are removed.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 and associated error message.

Chapter 10. Dynamic Partition Manager (DPM) 371

 Level 04a

| Table 170. Undefine Storage Subsystem: 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 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 2 A storage subsystem with the object ID {storage-subsystem-id} does not exist
| on the HMC.
| 409 (Conflict) 2 The storage subsystem object with the object ID {storage-subsystem-id} was
| busy and the request timed out.
| 446 The connection-endpoints property of the Storage Subsystem object with the
| object ID {storage-subsystem-id} is not empty.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492/operations/
undefine HTTP/1.1
x-api-session: 67zvhvf3c5z2uu0euonieit063n2spw26aco76zkvt422iir6a
content-type: application/json

Figure 192. Undefine Storage Subsystem: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 21:20:28 GMT

<No response body>

Figure 193. Undefine Storage Subsystem: Response

| Get Storage Subsystem Properties

| The Get Storage Subsystem Properties operation retrieves the properties of a single Storage Subsystem
| object.

| HTTP method and URI

| GET /api/storage-subsystems/{storage-subsystem-id}

| In this request, the URI variable {storage-subsystem-id} is the object ID of the Storage Subsystem object.

| Response body contents

| On successful completion, the response body is a JSON object that provides the current values of the
| properties for the Storage Subsystem object as defined in the “Data model” on page 365. Field names and

372 HMC Web Services API

 Level 04a

| data types in the JSON object are the same as the property names and data types defined in the data
| model.

| Description

| Returns the current values of the properties for the Storage Subsystem object as defined in the “Data
| model” on page 365.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the object
| ID {storage-subsystem-id} does not identify a storage subsystem object on the HMC, a 404 (Not Found)
| status code is returned.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 171. Get Storage Subsystem 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.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage subsystem with object-id {storage-subsystem-id} does not exist on
| the HMC.
|

| 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/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492 HTTP/1.1

x-api-session: 3fbndln8qdk7d0vshl0ltfg8fxxpx8zqp0emq2xbl8gnuwhrvk

Figure 194. Get Storage Subsystem Properties: Request

Chapter 10. Dynamic Partition Manager (DPM) 373

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:09:00 GMT
content-type: application/json;charset=UTF-8
content-length: 620
{
"class":"storage-subsystem",
"connection-endpoints":[
{
"endpoint-class":"storage-switch",
"endpoint-uri":"/api/storage-switches/b65d1aee-9437-11e8-9c43-fa163e27d492",
"port-id":"00"
},
{
"endpoint-class":"storage-switch",
"endpoint-uri":"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492",
"port-id":"00"
}
],
"description":"DS8870 in New York",
"name":"DS8870 A",
"object-id":"76c30590-943e-11e8-9c43-fa163e27d492",
"object-uri":"/api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492",
"parent":"/api/console",
"storage-control-unit-uris":[],
"storage-site-uri":"/api/storage-sites/13ff101c-941f-11e8-a0c0-fa163e27d492"
}

Figure 195. Get Storage Subsystem Properties: Response

| Update Storage Subsystem Properties

| The Update Storage Subsystem Properties operation updates one or more of the writable properties of a
| storage subsystem.

| HTTP method and URI

| POST /api/storage-subsystems/{storage-subsystem-id}

| In this request, the URI variable {storage-subsystem-id} is the object ID of the Storage Subsystem object.

| Request body contents

| The request body is expected to contain a JSON object that provides the new value of any writable
| property that is to be updated by this operation. Field names and data types in this JSON object are
| expected to match the corresponding property names and data types defined in the “Data model” on
| page 365. The JSON object can and should omit fields for properties whose values are not to be changed
| by this operation.

| Description

| This operation updates a storage subsystem's properties with the values specified.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-subsystem-id} does not identify a Storage Subsystem
| object on the HMC.

374 HMC Web Services API

 Level 04a

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| another storage subsystem with the specified name exists within the same FICON configuration on which
| the containing storage site exists.

| If the request body contents are valid, the storage subsystem's properties are updated to their
| corresponding request body content's field's values. All fields are optional and may be excluded from the
| request body; if a field is not found in the request body, its property's value will not be modified.

| If the update changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 172. Update Storage Subsystem 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.
| 8 A storage subsystem with the name specified in the request body already
| exists within the FICON configuration in which the containing storage site
| exists.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 The storage subsystem with the object-id {storage-subsystem-id} does not exist
| on the HMC.
| 409 (Conflict) 2 The storage subsystem object with the object-id {storage-subsystem-id} was
| busy and the request timed out.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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) 375

 Level 04a

| Example HTTP interaction

|

POST /api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492 HTTP/1.1

x-api-session: 1zwn9re00ctj6qu09fxgu6y28lb8la7dm752gbe60m7uyg5z1m
content-type: application/json
content-length: 37
{
"description":"DS8870 in New York"
}

Figure 196. Update Storage Subsystem Properties: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 21:24:35 GMT

<No response body>

Figure 197. Update Storage Subsystem Properties: Response

| Move Storage Subsystem to Storage Site

| The Move Storage Subsystem to Storage Site operation moves a storage subsystem from its current
| storage site to a different storage site.

| HTTP method and URI

| POST /api/storage-subsystems/{storage-subsystem-id}/operations/move-storage-site

| In this request, the URI variable {storage-subsystem-id} is the object ID of the storage subsystem that is to
| be moved.

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| storage-site-uri String/URI Required The canonical URI path for the storage site to which this
| subsystem is to be moved.
|

| Description

| This operation moves a storage subsystem from the storage site to which it is currently associated to a
| different storage site within the same FICON configuration.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-subsystem-id} does not identify a Storage Subsystem
| object on the HMC, or the URI specified in the storage-site-uri field does not identify a Storage Site
| object on the HMC. If the storage site specified in the storage-site-uri field already contains the Storage
| Subsystem, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| the new storage site is associated with a different FICON configuration.

376 HMC Web Services API

 Level 04a

| If the request body contents are valid, the storage-site-uri property of the storage subsystem identified by
| {storage-subsystem-id} is updated to the value specified in the storage-site-uri field. The storage subsystem
| is removed from the storage-subsystem-uris array property of the original storage site and added to the
| storage-subsystem-uris property of the new storage site.

| Property change notifications on the subsystem’s storage-site-uri property and on both the original and
| new storage site’s storage-subsystem-uris properties are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 173. Move Storage Subsystem to Storage Site: 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.
| 441 The storage site identified by the storage-site-uri field is associated with a
| different FICON configuration than the current storage site.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 The storage subsystem with the object-id {storage-subsystem-id} does not exist
| on the HMC.
| 2 The storage site identified by the storage-site-uri field does not exist on the
| HMC.
| 409 (Conflict) 2 The storage subsystem object with the object-id {storage-subsystem-id} was
| busy and the request timed out.
| 450 The storage site identified by the storage-site-uri field already contains a
| storage subsystem with the object-id {storage-subsystem-id}.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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) 377

 Level 04a

| Example HTTP interaction

|

POST /api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492/operations/
move-storage-site HTTP/1.1
x-api-session: 3uyn7nr37w44fg2j59hytrtc4ogmw46e5khw1mcbi3undieovv
content-type: application/json
content-length: 79
{
"storage-site-uri":"/api/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492"
}

Figure 198. Move Storage Subsystem to Storage Site: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 21:27:40 GMT

<No response body>

Figure 199. Move Storage Subsystem to Storage Site: Response

| Add Connection Endpoint

| The Add Connection Endpoint operation adds a connection endpoint to a storage subsystem.

| HTTP method and URI

| POST /api/storage-subsystems/{storage-subsystem-id}/operations/add-connection-endpoint

| In this request, the URI variable {storage-subsystem-id} is the object ID of the storage subsystem to which a
| connection endpoint is to be added.

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| endpoint-uri String/URI Required The canonical URI path for the Storage Switch or Adapter
| object to which this subsystem is connected.
| port-id String (2) Optional A two-character lowercase hexadecimal number that
| represents the switch port.

| This value is required if endpoint-uri references a Storage

| Switch object and is prohibited if endpoint-uri references
| an Adapter object.
|

| Description

| This operation adds a connection endpoint definition to a storage subsystem. A Property Change
| notification for the storage subsystem’s connection-endpoints property is emitted asynchronously to this
| operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not

378 HMC Web Services API

 Level 04a

| Found) status code is returned if the object ID {storage-subsystem-id} does not identify a storage subsystem
| object on the HMC, or if the endpoint URI does not identify an adapter or storage switch on the HMC.

| If the specified connection endpoint already exists on the storage subsystem, or if the port specified by
| port-id does not exist on the target storage switch, or if there are already 64 endpoints defined for the
| target storage subsystem, or endpoint-uri identifies a switch in a different storage site, or endpoint-uri
| identifies an adapter port when one or more fabrics exists, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| the port-id field is specified for an adapter endpoint.

| If the request body contents are valid, the new connection endpoint is added to the connection-endpoints
| property of the storage subsystem.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 the associated error message.
| Table 174. Add Connection Endpoint: 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.
| 15 The port-id field is present in the request body when the endpoint-uri field
| references an Adapter object
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage subsystem with the object-id {storage-subsystem-id} does not exist
| on the HMC.
| 2 The adapter or storage switch referenced by the endpoint-uri field does not
| exist on the HMC or the API user does not have object-access permission for
| it.

Chapter 10. Dynamic Partition Manager (DPM) 379

 Level 04a

| Table 174. Add Connection Endpoint: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 409 (Conflict) 2 The storage subsystem object with the object-id {storage-subsystem-id} was
| busy and the request timed out.
| 442 The port identified by port-id is not defined on the endpoint switch.
| 443 The specified connection endpoint already exists on the storage subsystem
| object with the object-id {storage-subsystem-id}.
| 455 A new endpoint cannot be created to an adapter port when storage fabrics
| are defined.
| 456 A new endpoint cannot be created to a storage switch that exists in a
| different storage site.
| 486 A new endpoint cannot be created for the storage subsystem with the
| object-id {storage-subsystem-id} because the maximum number of endpoints
| (64) for that storage subsystem are already defined.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492/operations/
add-connection-endpoint HTTP/1.1
x-api-session: 4ksgl9ak7cjeah3fiqwm3arl003hdrqi7uy68bdso7g3z2iopj
content-type: application/json
content-length: 95
{
"endpoint-uri":"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492",
"port-id":"00"
}

Figure 200. Add Connection Endpoint: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 21:44:11 GMT

<No response body>

Figure 201. Add Connection Endpoint: Response

| Remove Connection Endpoint

| The Remove Connection Endpoint operation removes a connection endpoint from a storage subsystem.

| HTTP method and URI

| POST /api/storage-subsystems/{storage-subsystem-id}/operations/remove-connection-endpoint

| In this request, the URI variable {storage-subsystem-id} is the object ID of the storage subsystem from
| which the connection endpoint is to be removed.

380 HMC Web Services API

 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
| endpoint-uri String/URI Required The canonical URI path for the Storage Switch or Adapter
| object from which this subsystem is to be disconnected.
| port-id String (2) Optional A two-character lowercase hexadecimal number that
| represents the switch port.

| This value is required if endpoint-uri references a Storage

| Switch object and is ignored if endpoint-uri references an
| Adapter object.
|

| Description

| This operation removes a connection endpoint definition from a storage subsystem. A Property Change
| notification for the storage subsystem’s connection-endpoints property is emitted asynchronously to this
| operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-subsystem-id} does not identify a storage subsystem
| object on the HMC, or if endpoint-uri does not identify an adapter or storage switch on the HMC.

| If the specified connection endpoint does not exist on the storage subsystem, or the connection endpoint
| is used by a storage path, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the specified connection endpoint is removed from the
| connection-endpoints property of the storage subsystem.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 the associated error message.
| Table 175. Remove Connection Endpoint: 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 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.

Chapter 10. Dynamic Partition Manager (DPM) 381

 Level 04a

| Table 175. Remove Connection Endpoint: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 404 (Not Found) 1 A storage subsystem with the object-id {storage-subsystem-id} does not exist
| on the HMC.
| 2 The adapter or storage switch referenced by the endpoint-uri field does not
| exist on the HMC or the API user does not have object-access permission for
| it.
| 409 (Conflict) 2 The storage subsystem object with the object-id {storage-subsystem-id} was
| busy and the request timed out.
| 444 The specified connection endpoint does not exist on the storage subsystem
| object with the object-id {storage-subsystem-id}.
| 446 The specified connection endpoint is configured in one or more of the
| storage paths defined in the storage subsystem object with the object-id
| {storage-subsystem-id}.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492/operations/
remove-connection-endpoint HTTP/1.1
x-api-session: 1ern4xd5sqegdqh5tlcvwp7quls9q55uuu7ahbc8ue3ywfva0g
content-type: application/json
content-length: 95
{
"endpoint-uri":"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492",
"port-id":"00"
}

Figure 202. Remove Connection Endpoint: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Jul 2018 21:43:47 GMT

<No response body>

Figure 203. Remove Connection Endpoint: Response

| Inventory service data

| Information about the Storage Subsystems managed by the HMC can be optionally included in the
| inventory data provided by the Inventory Service.

| Inventory entries for storage subsystem objects are included in the response to the Inventory Service's Get
| Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or

382 HMC Web Services API

 Level 04a

| by default) that objects of class "storage-subsystem" are to be included. Information for a particular
| storage subsystem is included only if the API user has access permission to that object as described in the
| Get Storage Subsystem Properties operation.

| For each storage subsystem to be included, the inventory response array includes the following:
| v An array entry for the storage subsystem object. This entry is a JSON object with the same contents as
| is specified in the Response body contents section for “Get Storage Subsystem Properties” on page 372.
| That is, the data provided is the same as would be provided if a Get Storage Subsystem Properties
| operation were requested targeting this object.

| Sample inventory data

| The following fragment is an example of the JSON object that would be included in the Get Inventory
| response to describe a storage subsystem. This object would appear as one array entry in the response
| array:
|

{
"class":"storage-subsystem",
"connection-endpoints":[
{
"endpoint-class":"storage-switch",
"endpoint-uri":"/api/storage-switches/0e261690-9438-11e8-8ffe-fa163e27d492",
"port-id":"00"
},
{
"endpoint-class":"storage-switch",
"endpoint-uri":"/api/storage-switches/fdc68064-9437-11e8-8ffe-fa163e27d492",
"port-id":"00"
}
],
"description":"",
"name":"DS8886 B",
"object-id":"9b15669a-943e-11e8-8ffe-fa163e27d492",
"object-uri":"/api/storage-subsystems/9b15669a-943e-11e8-8ffe-fa163e27d492",
"parent":"/api/console",
"storage-control-unit-uris":[],
"storage-site-uri":"/api/storage-sites/0336a208-9434-11e8-9c43-fa163e27d492"
}

Figure 204. Storage Subsystem object: Sample inventory data - Response

|
| Storage Control Unit object
| A Storage Control Unit object represents a single storage control unit in the FICON configuration
| associated with a DPM-enabled CPC. The Storage Control Unit object APIs provide access to the set of
| storage control units within the FICON configuration. APIs exist to define and undefine storage control
| units, list storage control units, query storage control unit properties, update selected properties of
| storage control units, and managed volume ranges. APIs also exist to create, delete, query and update the
| storage path elements of a storage control unit.

| Data model
| This object includes the properties that are defined in the “Base managed object properties schema” on
| page 60, with the class-specific specializations identified in Table 177 on page 384. The Storage Subsystem
| object does not support the operational status related properties.

Chapter 10. Dynamic Partition Manager (DPM) 383

 Level 04a

| Table 176. Storage Control Unit object: base managed object properties specializations
| Name Qualifier Type Description of specialization
| object-uri — String/ The canonical URI path of the Storage Control Unit object is of the
| URI form /api/storage-control-units/{storage-control-unit-id}
| where {storage-control-unit-id} is the value of the object-id property
| of the Storage Control Unit object.
| object-id — String (36) The unique identifier for the storage control unit instance.
| class — String (20) The class of the Storage Control Unit object is "storage-control-
| unit".
| parent — String/URI The parent of a storage control unit is conceptually its owning
| storage subsystem, and so the parent value is the canonical URI
| path for the subsystem.
| name (w)(pc) String The display name specified for the storage control unit. The length
| (1-64) and character requirements on this property are the same as those
| of the name property described in the “Base managed object
| properties schema” on page 60. Names must be unique to the other
| storage control units within the parent storage subsystem.

| Default value: Currently of the form Control unit {logical-address},

| where {logical-address} is the value of the logical-address property.
| This form is subject to change in the future.
| description (w)(pc) String Arbitrary text providing additional descriptive information about
| (0-1024) the storage control unit.

| Default value: An empty string

|

| Class specific additional properties

| In addition to the properties defined via included schemas, this object includes the following additional
| class-specific properties:
| Table 177. Storage Control Unit object: class specific properties
| Name Qualifier Type Description
| logical-address (w)(pc) String (2) A two-character lowercase hexadecimal number that represents the
| logical address that uniquely identifies the storage control unit
| within its parent storage subsystem. Logical addresses must be
| unique to the other storage control units within the parent storage
| subsystem.
| storage-path-uris (c)(pc) Array of The list of paths that connect this storage control unit optionally to
| String/ a port on a storage switch, and ultimately to an adapter. Each
| URI element in this array is the canonical URI path of a Storage Path
| element object, described Table 179 on page 385.

| There can be a maximum of 8 storage paths that Configure a

| single control unit, so the maximum number of entries in this
| array is 8.

| The value of this property will change, and property change

| notifications will be emitted, when storage paths are added and
| removed via the Create Storage Path and Delete Storage Path
| operations.

384 HMC Web Services API

 Level 04a

| Table 177. Storage Control Unit object: class specific properties (continued)
| Name Qualifier Type Description
| volume-ranges (c)(pc) Array of Array of volume-range objects, described in Table 178. A volume
| volume- range describes a contiguous set of storage volume unit addresses
| range that are managed by the storage control unit.
| objects
| The value of this property will change, and property change
| notifications will be emitted, when ports are added and removed
| via the Add Volume Range and Remove Volume Range
| operations.
|

| A volume range defines a contiguous set of base or alias volumes within a storage control unit.
| Table 178. Storage Control Unit object: volume-range nested object properties
| Name Qualifier Type Description
| starting-volume — String (2) A two-character lowercase hexadecimal number that represents the
| first unit address in the volume range.
| ending-volume — String (2) A two-character lowercase hexadecimal number that represents the
| last unit address in the volume range.

| Default value: The ending volume will be the same as the starting
| volume, thus giving a range of one volume.
| type — String The volume type. Values:
| Enum v "base" – The volumes in the range are base volumes.
| v "alias" – The volumes in the range are alias volumes.

| Default value: "base"

|

| Storage Path element object

| A storage path defines a communications path from a storage control unit to an adapter, optionally
| through one or two storage switches.
| Table 179. Storage Control Unit object: storage path element object properties
| Name Qualifier Type Description
| element-uri — String/ The canonical URI path for the storage path element object, of the
| URI form /api/storage-control-units/{storage-control-unit-id}/
| storage-paths/{storage-path-id}, where {storage-control-unit-id} is
| the object-id of the containing storage control unit, and
| {storage-path-id} is the element-id of this storage path.
| element-id — String (36) The unique identifier for the storage path instance.
| class — String (12) The class of a storage path element object is "storage-path".
| parent — String/ The parent of a storage path is its owning storage control unit, so
| URI the parent value is the canonical URI path for the storage control
| unit.
| adapter-port-id (w)(pc) String/ The canonical URI path for the storage adapter port at the
| URI opposite end of the storage path.

Chapter 10. Dynamic Partition Manager (DPM) 385

 Level 04a

| Table 179. Storage Control Unit object: storage path element object properties (continued)
| Name Qualifier Type Description
| exit-switch-uri (w)(pc) String/ The canonical URI path for the exit switch to which the control
| URI unit, and in non-cascaded switch configurations, the adapter, are
| connected.

| The value of this property may be null, which indicates the

| adapter and control unit have a point-to-point connection without
| any intervening switches.

| Default value: null

| exit-port (w)(pc) String (2) A two-character lowercase hexadecimal number that represents the
| port on the exit switch to which the control unit is connected.

| The value of this property will be null when the value of

| exit-switch-uri is null, and non-null when the value of
| exit-switch-uri is non-null.

| Default value: null

|

| List Storage Control Units of a Storage Subsystem

| The List Storage Control Units of a Storage Subsystem operation lists the storage control units managed
| by the storage subsystem with the given identifier.

| HTTP method and URI

| GET /api/storage-subsystems/{storage-subsystem-id}/storage-control-units

| In this request, the URI variable {storage-subsystem-id} is the object-id of the Storage Subsystem object.

| 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.
| logical-address String Optional Filter pattern (regular expression) to limit returned objects to those
| that have a matching logical-address property.
|

| Response body contents

| On successful completion, the response body is a JSON object with the following fields:
|| Field name Type Description
| storage-control-units Array of Array of storage-control-unit-info objects, described in the next table. The
| storage- returned array may be empty.
| control-
| unit-info
| objects
|

| Each nested storage-control-unit-info object contains the following fields:

|| Field name Type Description
| object-uri String/ Canonical URI path (object-uri) of the Storage Control Unit object.
| URI

386 HMC Web Services API

 Level 04a

| Field name Type Description

| name String The name property of the Storage Control Unit object.
| logical-address String The logical-address property of the Storage Control Unit object.
|

| Description

| This operation lists the storage control units that are managed by the identified storage subsystem. The
| object URI, name and logical address are provided for each.

| If the object ID {storage-subsystem-id} does not identify a storage subsystem object on the HMC, a 404 (Not
| Found) status code is returned.

| If the name or logical-address query parameters are specified, the returned list is limited to those storage
| control units that have the same-named property matching the specified filter pattern. If any parameter is
| omitted, this filtering on that property is not done.

| A storage control unit is included in the list only if the API user has task permission for the Configure
| Storage – System Programmer or Configure Storage – Storage Administrator tasks. If the specified
| storage subsystem is the parent of a storage control unit but the API user does not have permission to it,
| that object is simply omitted from the list but no error status code results.

| If no storage control units are to be included in the results due to filtering or lack of task permission, an
| empty list is provided and the operation completes successfully.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 386.

| 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 any associated error message.
| Table 180. List Storage Control Units of a Storage Subsystem: 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.
| 14 A query parameter defines an invalid value.
| 404 (Not Found) 1 The storage subsystem with the object ID {storage-subsystem-id} does not exist
| on the HMC.
|

| 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) 387

 Level 04a

| Example HTTP interaction

|

| GET /api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492/storage-control-units
| HTTP/1.1
| x-api-session: 1eija5xbm9fj0z3bmiwbnw37ks9esycx5tkzc4lz65c6f1ezib
|
|
| Figure 205. List Storage Control Units of a Storage Subsystem: Request

| 200 OK
| server: Hardware management console API web server / 2.0
| cache-control: no-cache
| date: Tue, 31 Jul 2018 15:55:39 GMT
| content-type: application/json;charset=UTF-8
| content-length: 156
| {
| "storage-control-units":[
| {
| "logical-address":"50",
| "name":"Control unit 50",
| "object-uri":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492"
| }
| ]
| }
|
|
| Figure 206. List Storage Control Units of a Storage Subsystem: Response

| Define Storage Control Unit

| The Define Storage Control Unit operation defines a new Storage Control Unit object within a parent
| storage subsystem.

| HTTP method and URI

| POST /api/storage-subsystems/{storage-subsystem-id}/operations/define-storage-control-unit

| In this request, the URI variable {storage-subsystem-id} is the object-id of the Storage Subsystem object on
| which a storage control unit is to be defined.

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| name String Optional The value to be set as the storage control unit's name
| (1-64) property.
| description String Optional The value to be set as the storage control unit's
| (0-1024) description property.
| logical-address String (2) Required The value to be set as the storage control unit's
| logical-address property.
|

388 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
| object-uri String/URI The object-uri property of the newly defined Storage Control Unit object.
|

| Description

| This operation defines a storage control unit with the values specified in the identified storage subsystem
| and then returns its object-uri in the response body. An Inventory Change notification and a Property
| Change notification on the parent storage subsystem’s storage-control-unit-uris property are emitted
| asynchronously to this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the object
| ID {storage-subsystem-id} does not identify a storage subsystem object on the HMC, a 404 (Not Found)
| status code is returned. If the storage subsystem identified by {storage-subsystem-id} already contains a
| storage control unit with the specified name, a 400 (Bad Request) status code is returned. If the storage
| subsystem identified by {storage-subsystem-id} already contains a storage control unit with the specified
| logical-address, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the storage control unit is defined and its properties are set to their
| corresponding request body contents field's values. If a field is not found in the request body, its
| property's value will be defaulted. The new storage control unit's URI is added to the parent storage
| subsystem’s storage-control-unit-uris list property.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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, and the response body is a
| standard error response body providing the reason code indicated and the associated error message.
| Table 181. Define Storage Control Unit: 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 storage control unit with the name specified in the request body already
| exists within the parent storage subsystem with the object-id
| {storage-subsystem-id}.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.

Chapter 10. Dynamic Partition Manager (DPM) 389

 Level 04a

| Table 181. Define Storage Control Unit: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 404 (Not Found) 1 A storage subsystem with the object-id {storage-subsystem-id} does not exist
| on the HMC.
| 409 (Conflict) 447 A storage control unit with the logical-address specified in the request body
| already exists within the parent storage subsystem with the object-id
| {storage-subsystem-id}.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492/operations/
define-storage-control-unit HTTP/1.1
x-api-session: 557u9y6zn6qwei7239zy3roucdrvzkr8ubni9ijykoe6eql2tu
content-type: application/json
content-length: 25
{
"logical-address":"50"
}

Figure 207. Define Storage Control Unit: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:21:54 GMT
content-type: application/json;charset=UTF-8
content-length: 80
{
"object-uri":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492"
}

Figure 208. Define Storage Control Unit: Response

| Undefine Storage Control Unit

| The Undefine Storage Control Unit operation removes a storage control unit definition.

| HTTP method and URI

| POST /api/storage-control-units/{storage-control-unit-id}/operations/undefine

| In this request, the URI variable {storage-control-unit-id} is the object ID of the storage control unit to be
| removed.

| Description

| This operation removes a storage control unit definition. If the storage control unit contains storage paths
| or volume ranges, they will be removed as well. Inventory Change notifications on the removed storage

390 HMC Web Services API

 Level 04a

| control unit and each of its contained storage paths, and a Property Change notification on the parent
| storage subsystem’s storage-control-unit-uris property are emitted asynchronously to this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-control-unit-id} does not identify a storage control
| unit object on the HMC.

| If the storage control unit is mapped to any storage volume, a 409 (Conflict) status code is returned.

| If the request body contents are valid, the identified storage control unit’s storage paths and volume
| ranges are deleted and its URI is removed from the parent storage subsystem’s storage-control-unit-uris
| list property.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 and associated error message.
| Table 182. Undefine Storage Control Unit: 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 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage subsystem with the object-id {storage-subsystem-id} does not exist
| on the HMC.
| 2 A storage control unit with the object ID {storage-control-unit-id} does not
| exist on the HMC.
| 409 (Conflict) 2 The storage control unit with the object-id {storage-control-unit} was busy and
| the request timed out.
| 446 The storage control unit with the object-id {storage-control-unit-id} is mapped
| to one or more volumes in one or more storage groups.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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) 391

 Level 04a

| Example HTTP interaction

|

POST /api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/operations/
undefine HTTP/1.1
x-api-session: 4er4rp2aw9y5mgokxtwb8wz37v1mx4nyyj2iqx5gct66ewhcb4
content-type: application/json

Figure 209. Undefine Storage Control Unit: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:20:54 GMT

<No response body>

Figure 210. Undefine Storage Control Unit: Response

| Get Storage Control Unit Properties

| The Get Storage Control Unit Properties operation retrieves the properties of a single Storage Control
| Unit object.

| HTTP method and URI

| GET /api/storage-control-units/{storage-control-unit-id}

| In this request, the URI variable {storage-control-unit-id} is the object ID of the Storage Control Unit object.

| Response body contents

| On successful completion, the response body is a JSON object that provides the current values of the
| properties for the Storage Control Unit object as defined in the “Data model” on page 383. 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

| Returns the current values of the properties for the Storage Control Unit object as defined in the “Data
| model” on page 383.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the object
| ID {storage-control-unit-id} does not identify a Storage Control Unit object on the HMC, a 404 (Not Found)
| status code is returned.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

392 HMC Web Services API

 Level 04a

| Otherwise, 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 183. Get Storage Control Unit 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.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage control unit with object-id {storage-control-unit-id} does not exist on
| the HMC.
|

| 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/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492 HTTP/1.1

x-api-session: 1skejiyvyiew4b70zzxk6y2s802fh4gpugbkvy4yddsambc5c8

Figure 211. Get Storage Control Unit Properties: Request

Chapter 10. Dynamic Partition Manager (DPM) 393

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:51:56 GMT
content-type: application/json;charset=UTF-8
content-length: 946
{
"class":"storage-control-unit",
"description":"LCU 50 in DS8870 A",
"logical-address":"50",
"name":"Control unit 50",
"object-id":"69bf384a-94d5-11e8-8ffe-fa163e27d492",
"object-uri":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492",
"parent":"/api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492",
"storage-path-uris":[
"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
7f4dc8d0-94d9-11e8-917c-fa163e3fe47d",
"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
7f4eab9c-94d9-11e8-917c-fa163e3fe47d",
"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
7f4f02d6-94d9-11e8-917c-fa163e3fe47d",
"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
8746e9c8-94d8-11e8-a5c5-fa163e3fe47d"
],
"volume-ranges":[
{
"ending-volume":"04",
"starting-volume":"00",
"type":"base"
},
{
"ending-volume":"ff",
"starting-volume":"fc",
"type":"alias"
}
]
}

Figure 212. Get Storage Control Unit Properties: Response

| Update Storage Control Unit Properties

| The Update Storage Control Unit Properties operation updates one or more of the writable properties of
| a storage control unit.

| HTTP method and URI

| POST /api/storage-control-units/{storage-control-unit-id}

| In this request, the URI variable {storage-control-unit-id} is the object ID of the Storage Control Unit object.

| Request body contents

| The request body is expected to contain a JSON object that provides the new value of any writable
| property that is to be updated by this operation. Field names and data types in this JSON object are
| expected to match the corresponding property names and data types defined in the “Data model” on
| page 383. The JSON object can and should omit fields for properties whose values are not to be changed
| by this operation.

| Description

| This operation updates a storage control unit's properties with the values specified.

394 HMC Web Services API

 Level 04a

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-control-unit-id} does not identify a Storage Control
| Unit object on the HMC, or if the specified logical-address already exists within the parent storage
| subsystem, or if the logical-address field is present when target storage control unit is mapped to a
| storage volume.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| the specified name already exists within the parent storage subsystem.

| If the request body contents are valid, the storage subsystem's properties are updated to their
| corresponding request body content's field's values. All fields are optional and may be excluded from the
| request body; if a field is not found in the request body, its property's value will not be modified.

| If the update changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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 184. Update Storage Control Unit 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.
| 8 A storage control unit with the name specified in the request body already
| exists within its parent storage subsystem.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 The storage control unit with the object-id {storage-control-unit-id} does not
| exist on the HMC.
| 409 (Conflict) 2 The Storage Control Unit object with the object-id {storage-control-unit-id}
| was busy and the request timed out.
| 446 The logical-address field is present in the request body when the storage
| control unit with the object-id {storage-control-unit-id} is mapped to one or
| more volumes in a storage group.
| 447 A storage control unit with the logical-address specified in the request body
| already exists within its parent storage subsystem.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the SE needed to perform the requested operation.
|

Chapter 10. Dynamic Partition Manager (DPM) 395

 Level 04a

| 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/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492 HTTP/1.1

x-api-session: 23qo36u6e3csdzyx6uroamwcduxrt2l3hk9phe8t9n763eeszl
content-type: application/json
content-length: 37
{
"description":"LCU 50 in DS8870 A"
}

Figure 213. Update Storage Control Unit Properties: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:23:28 GMT

<No response body>

Figure 214. Update Storage Control Unit Properties: Response

| Add Volume Range

| The Add Volume Range operation adds a volume range to a storage control unit.

| HTTP method and URI

| POST /api/storage-control-units/{storage-control-unit-id}/operations/add-volume-range

| In this request, the URI variable {storage-control-unit-id} is the object ID of the storage control unit to
| which a volume range is to be added.

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| starting-volume String (2) Required The value to be set as the volume range's starting-volume
| property.
| ending-volume String (2) Optional The value to be set as the volume range's ending-volume
| property.
| type String Optional The value to be set as the volume range's type property.
| Enum
|

| Description

| This operation adds a volume range to a storage control unit. A property-change notification for the
| storage control unit’s volume-ranges property is emitted asynchronously to this operation.

396 HMC Web Services API

 Level 04a

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-control-unit-id} does not identify a Storage Control
| Unit object on the HMC.

| If the storage control unit is mapped to any storage volume, or if the volume range overlaps with any
| volume range that already exists on the storage control unit, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the volume range is added to the volume-ranges property of the
| storage control unit.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 the associated error message.
| Table 185. Add Volume Range: 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 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage control unit with the object-id {storage-control-unit-id} does not
| exist on the HMC.
| 409 (Conflict) 2 The Storage Control Unit object with the object-id {storage-control-unit-id}
| was busy and the request timed out.
| 446 The storage control unit with the object-id {storage-control-unit-id} is mapped
| to one or more volumes in a storage group.
| 448 The volume range overlaps with one that already exists on the storage
| control unit object with the object-id {storage-control-unit-id}.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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) 397

 Level 04a

| Example HTTP interaction

|

POST /api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/operations/
add-volume-range HTTP/1.1
x-api-session: 3zu31yqjcjwa7plkqpsceibkye5gmssmmkxbf51ok5ve8kbjnw
content-type: application/json
content-length: 64
{
"ending-volume":"04",
"starting-volume":"00",
"type":"base"
}

Figure 215. Add Volume Range: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:27:41 GMT

<No response body>

Figure 216. Add Volume Range: Response

| Remove Volume Range

| The Remove Volume Range operation removes a volume range from a storage control unit.

| HTTP method and URI

| POST /api/storage-control-units/{storage-control-unit-id}/operations/remove-volume-range

| In this request, the URI variable {storage-control-unit-id} is the object ID of the storage control unit from
| which the volume range is to be removed.

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| starting-volume String (2) Required The starting-volume property value of the volume range
| that is to be removed.
|

| Description

| This operation removes the entire volume range with the specified starting volume from a storage control
| unit. A Property Change notification for the storage control unit’s volume-ranges property is emitted
| asynchronously to this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-control-unit-id} does not identify a storage control
| unit object on the HMC.

| If the storage control unit is mapped to any storage volume, or if a volume range with the specified
| starting-volume value does not exist on the storage control unit, a 409 (Conflict) status code is returned.

398 HMC Web Services API

 Level 04a

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the volume range with the specified starting-volume is removed
| from the volume-ranges property of the storage control unit.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 the associated error message.
| Table 186. Remove Volume Range: 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 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage control unit with the object-id {storage-control-unit-id} does not
| exist on the HMC.
| 409 (Conflict) 2 The Storage Control Unit object with the object-id {storage-control-unit-id}
| was busy and the request timed out.
| 446 The storage control unit with the object-id {storage-control-unit-id} is mapped
| to one or more volumes in a storage group.
| 449 A volume range with the specified starting-volume value does not exist on
| the storage control unit object with the object-id {storage-control-unit-id}.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/operations/
remove-volume-range HTTP/1.1
x-api-session: 2guwrshqajcumqql9zxk5iighh2kxxzb5tkxqnuh9hct4etk30
content-type: application/json
content-length: 25
{
"starting-volume":"00"
}

Figure 217. Remove Volume Range: Request

Chapter 10. Dynamic Partition Manager (DPM) 399

 Level 04a

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:27:21 GMT

<No response body>

Figure 218. Remove Volume Range: Response

| Create Storage Path

| The Create Storage Path operation creates a new Storage Path element object within a parent storage
| control unit.

| HTTP method and URI

| POST /api/storage-control-units/{storage-control-unit-id}/storage-paths

| In this request, the URI variable {storage-control-unit-id} is the object-id of the parent Storage Control Unit
| object of the new storage path.

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| adapter-port-uri String/URI Required The value to be set as the storage path's adapter-port-uri
| property.
| exit-switch-uri String/URI Optional The value to be set as the storage path's exit-switch-uri
| property.
| exit-port String (2) Optional The value to be set as the storage path's exit-port
| property.
|

| Response body contents

| On successful completion, the response body is a JSON object with the following fields:
|| Field name Type Description
| element-uri String/URI The element URI of the newly created Storage Path element object.
|

| Description

| This operation creates a storage path with the values specified on the identified storage control unit and
| then returns its element URI in the response body. The response also includes a Location header that
| provides this URI. An Inventory Change notification and a Property Change notification on the parent
| storage control unit’s storage-path-uris property are emitted asynchronously to this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the object
| ID {storage-control-unit-id} does not identify a storage control unit object on the HMC, or if
| adapter-port-uri or exit-switch-uri do not identify an adapter port or storage switch on the HMC, a 404
| (Not Found) status code is returned. If the storage control unit identified by {storage-control-unit-id}
| already contains a storage path with the same set of property values, a 400 (Bad Request) status code is
| returned. If the storage control unit is mapped to any storage volume, or if the maximum number of

400 HMC Web Services API

 Level 04a

| storage ports is already defined for the control unit, or the specified exit port is not defined on the
| specified switch, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| the exit-port-id field is present when the exit-switch-uri field is omitted, or the exit-port-id field is
| omitted when the exit-switch-uri field is present

| If the request body contents are valid, the storage path is created and its properties are set to their
| corresponding request body content's field's values. If a field is not found in the request body, its
| property's value will be defaulted. The new storage path’s URI is added to the parent storage control
| unit’s storage-path-uris list property.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 400.

| 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 the associated error message.
| Table 187. Create Storage Path: 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 storage path with the same property values as those defaulted or specified
| in the request body already exists within the parent storage control unit with
| the object-id {storage-control-unit-id}.
| 442 A corequisite condition on the presence of the exit-port-id field with respect
| to the presence of the exit-switch-uri field has been violated.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage control unit with the object-id {storage-control-unit-id} does not
| exist on the HMC.
| 2 The adapter port referenced by adapter-port-uri does not exist on the HMC.
| 441 The storage switch referenced by exit-switch-uri does not exist on the HMC.
| 409 (Conflict) 2 The storage control unit object with the object-id {storage-control-unit-id} was
| busy and the request timed out.
| 442 The port identified by exit-port is not defined on the storage switch
| referenced by exit-switch-uri.
| 446 The parent storage control unit with the object-id {storage-control-unit-id} is
| mapped to one or more volumes in a storage group.
| 486 A new storage path cannot be created for the storage control unit with the
| object-id {storage-control-unit-id} because the maximum number of storage
| paths (8) for that control unit are already defined.

Chapter 10. Dynamic Partition Manager (DPM) 401

 Level 04a

| Table 187. Create Storage Path: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths
HTTP/1.1
x-api-session: 5iiqgy1nfzrlgjqlbuz3s06mqr8u2e0d3g5a7xf7kih4jb2cyb
content-type: application/json
content-length: 190
{
"adapter-port-uri":"/api/adapters/20633658-941f-11e8-8625-fa163e27d492/storage-ports
/0",
"exit-port":"00",
"exit-switch-uri":"/api/storage-switches/b65d1aee-9437-11e8-9c43-fa163e27d492"
}

Figure 219. Create Storage Path: Request

201 Created
server: Hardware management console API web server / 2.0
location: /api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
8746e9c8-94d8-11e8-a5c5-fa163e3fe47d
cache-control: no-cache
date: Tue, 31 Jul 2018 15:43:53 GMT
content-type: application/json;charset=UTF-8
content-length: 132
{
"element-uri":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/
storage-paths/8746e9c8-94d8-11e8-a5c5-fa163e3fe47d"
}

Figure 220. Create Storage Path: Response

| Delete Storage Path

| The Delete Storage Path operation deletes a storage path.

| HTTP method and URI

| DELETE /api/storage-control-units/{storage-control-unit-id}/storage-paths/{storage-path-id}

| In this request, the URI variable {storage-control-unit-id} is the object ID of the Storage Control Unit object
| and the URI variable {storage-path-id} is the element ID of the Storage Path element object to delete.

| Description

| This operation deletes a storage path. An Inventory Change notification and a Property Change
| notification on the parent storage control unit’s storage-path-uris property are emitted asynchronously to
| this operation.

402 HMC Web Services API

 Level 04a

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-control-unit-id} does not identify a storage control
| unit object on the HMC, or if the element ID {storage-path-id} does not identify a storage path in the
| storage control unit.

| If the storage control unit is mapped to any storage volume, a 409 (Conflict) status code is returned.

| If the request body contents are valid, the identified storage path is deleted from the parent storage
| control unit’s storage-path-uris list property.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| 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 and associated error message.
| Table 188. Delete Storage Path: 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 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage control unit with the object-id {storage-control-unit-id} does not
| exist on the HMC.
| 5 A storage path with element-id {storage-path-id} does not exist for the storage
| control unit.
| 409 (Conflict) 2 The storage control unit object with the object-id {storage-control-unit-id} was
| busy and the request timed out.
| 446 The parent storage control unit with the object-id {storage-control-unit-id} is
| mapped to one or more volumes in a storage group.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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) 403

 Level 04a

| Example HTTP interaction

|

DELETE /api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
8746e9c8-94d8-11e8-a5c5-fa163e3fe47d HTTP/1.1
x-api-session: 6a7jbbd1iipk5mayxii3p742ujjzawofuthw3yyadlonn33gip

Figure 221. Delete Storage Path: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:40:41 GMT

<No response body>

Figure 222. Delete Storage Path: Response

| Get Storage Path Properties

| The Get Storage Path Properties operation retrieves the properties of a single Storage Path element
| object.

| HTTP method and URI

| GET /api/storage-control-units/{storage-control-unit-id}/storage-paths/{storage-path-id}

| In this request, the URI variable {storage-control-unit-id} is the object ID of the Storage Control Unit object
| and the URI variable {storage-path-id} is the element ID of the Storage Path element object.

| Response body contents

| On successful completion, the response body is a JSON object that provides the current values of the
| properties for the Storage Path object as defined in the “Data model” on page 383. 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

| Returns the current values of the properties for the Storage Path element object as defined in the
| Table 179 on page 385.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. If the object
| ID {storage-control-unit-id} does not identify a Storage Control Unit object on the HMC, or if the element
| ID {storage-path-id} does not identify a storage path in the storage control unit, a 404 (Not Found) status
| code is returned.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

404 HMC Web Services API

 Level 04a

| Otherwise, 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 189. Get Storage Path 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.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 A storage control unit with object-id {storage-control-unit-id} does not exist on
| the HMC.
| 5 A storage path with element-id {storage-path-id} does not exist for the storage
| control unit.
|

| 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/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
8746e9c8-94d8-11e8-a5c5-fa163e3fe47d HTTP/1.1
x-api-session: 2bgudgv3iuzlc6ny30fs9v3pb0w43snsewp9dtt5h0qls29dpt

Figure 223. Get Storage Path Properties: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:44:39 GMT
content-type: application/json;charset=UTF-8
content-length: 466
{
"adapter-port-uri":"/api/adapters/20633658-941f-11e8-8625-fa163e27d492/storage-ports/
0",
"class":"storage-path",
"element-id":"8746e9c8-94d8-11e8-a5c5-fa163e3fe47d",
"element-uri":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/
storage-paths/8746e9c8-94d8-11e8-a5c5-fa163e3fe47d",
"exit-port":"00",
"exit-switch-uri":"/api/storage-switches/b65d1aee-9437-11e8-9c43-fa163e27d492",
"parent":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492"
}

Figure 224. Get Storage Path Properties: Response

| Update Storage Path Properties

| The Update Storage Path Properties operation updates one or more of the writable properties of a
| storage path.

| HTTP method and URI

| POST /api/storage-control-units/{storage-control-unit-id}/storage-paths/{storage-path-id}

Chapter 10. Dynamic Partition Manager (DPM) 405

 Level 04a

| In this request, the URI variable {storage-control-unit-id} is the object ID of the Storage Control Unit object
| and the URI variable {storage-path-id} is the element ID of the Storage Path element object.

| Request body contents

| The request body is expected to contain a JSON object that provides the new value of any writable
| property that is to be updated by this operation. Field names and data types in this JSON object are
| expected to match the corresponding property names and data types defined in the “Data model” on
| page 383. The JSON object can and should omit fields for properties whose values are not to be changed
| by this operation.

| Description

| This operation updates a storage path's properties with the values specified.

| If the API user does not have action/task permission to the Configure Storage – System Programmer or
| Configure Storage – Storage Administrator tasks, a 403 (Forbidden) status code is returned. A 404 (Not
| Found) status code is returned if the object ID {storage-control-unit-id} does not identify a Storage Control
| Unit object on the HMC, or if the element ID {storage-path-id} does not identify a storage path in the
| storage control unit, or if adapter-port-uri or exit-switch-uri do not identify an adapter port or storage
| switch on the HMC.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because
| the exit-port-id field is present when the exit-switch-uri field is omitted and the current value of the
| exit-switch-uri property is null, or the exit-port-id field is omitted and their current property values are
| null when the exit-switch-uri field is present, or because the updated storage path properties would be
| identical to an existing storage port in the parent storage control unit.

| If the storage control unit is mapped to any storage volume, or the specified exit switch or port do not
| exist a 409 (Conflict) status code is returned.

| If the request body contents are valid, the storage path's properties are updated to their corresponding
| request body content's field's values. All fields are optional and may be excluded from the request body;
| if a field is not found in the request body, its property's value will not be modified.

| If the update changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirement:

| v Action/task permission to the Configure Storage – System Programmer or Configure Storage –
| Storage Administrator tasks.

| HTTP status and reason codes

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

| Otherwise, 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.

406 HMC Web Services API

 Level 04a

| Table 190. Update Storage Path 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.
| 8 The update would result in a storage path with the same property values as
| a storage path that already exists within the parent storage control unit with
| the object-id {storage-control-unit-id}.
| 442 The update would put the storage port object into a state that would violate
| a corequisite condition on the presence of the exit-port-id property with
| respect to the presence of the exit-switch-uri property.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer or Configure Storage – Storage Administrator tasks.
| 404 (Not Found) 1 The storage control unit with the object-id {storage-control-unit-id} does not
| exist on the HMC.
| 2 The adapter port referenced by adapter-port-uri does not exist on the HMC.
| 5 A storage path with element-id {storage-path-id} does not exist for the storage
| control unit on HMC.
| 441 The storage switch identified by the exit-switch-uri field does not exist on
| the HMC.
| 442 The port identified by exit-port is not defined on the storage switch
| referenced by exit-switch-uri.
| 409 (Conflict) 2 The Storage Control Unit object with the object-id {storage-control-id} was
| busy and the request timed out.
| 446 The parent storage control unit with the object-id {storage-control-unit-id} is
| mapped to one or more volumes in a storage group.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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

|

POST /api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
8746e9c8-94d8-11e8-a5c5-fa163e3fe47d HTTP/1.1
x-api-session: bucvsrejregx2gv3p5l9rc5ylsupn4mr2o49vtlbuxkp3c3d6
content-type: application/json
content-length: 81
{
"exit-switch-uri":"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492"
}

Figure 225. Update Storage Path Properties: Request

Chapter 10. Dynamic Partition Manager (DPM) 407

 Level 04a

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:48:26 GMT

<No response body>

Figure 226. Update Storage Path Properties: Response

| Inventory service data

| Information about the Storage Control Units managed by the HMC can be optionally included in the
| inventory data provided by the Inventory Service.

| Inventory entries for storage control unit objects are included in the response to the Inventory Service's
| Get Inventory operation when the request specifies (explicitly by class, implicitly via a containing
| category, or by default) that objects of class "storage-control-unit" are to be included. Information for a
| particular storage control unit is included only if the API user has access permission to that object as
| described in the Get Storage Control Unit Properties operation.

| For each storage control unit to be included, the inventory response array includes the following:
| v An array entry for the storage control unit object itself. This entry is a JSON object with the same
| contents as is specified in the Response body contents section for “Get Storage Control Unit Properties”
| on page 392. That is, the data provided is the same as would be provided if a Get Storage Control
| Unit Properties operation were requested targeting this object.
| v An array entry for each storage path associated with the storage control unit. For each such storage
| path, an entry is included that is a JSON object with the same contents as is specified in the Response
| body contents section for “Get Storage Path Properties” on page 404.

| Sample inventory data

| The following fragment is an example of the JSON objects that would be included in the Get Inventory
| response to describe a storage control unit. These objects would appear as multiple array entries in the
| response array:
|

408 HMC Web Services API

 Level 04a

| {
| "class":"storage-control-unit",
| "description":"LCU 50 in DS8870 A",
| "logical-address":"50",
| "name":"Control unit 50",
| "object-id":"69bf384a-94d5-11e8-8ffe-fa163e27d492",
| "object-uri":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492",
| "parent":"/api/storage-subsystems/76c30590-943e-11e8-9c43-fa163e27d492",
| "storage-path-uris":[
| "/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
| 7f4dc8d0-94d9-11e8-917c-fa163e3fe47d",
| "/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
| 7f4eab9c-94d9-11e8-917c-fa163e3fe47d",
| "/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
| 7f4f02d6-94d9-11e8-917c-fa163e3fe47d",
| "/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/storage-paths/
| 8746e9c8-94d8-11e8-a5c5-fa163e3fe47d"
| ],
| "volume-ranges":[
| {
| "ending-volume":"04",
| "starting-volume":"00",
| "type":"base"
| },
| {
| "ending-volume":"ff",
| "starting-volume":"fc",
| "type":"alias"
| }
| ]
| },
| {
| "adapter-port-uri":"/api/adapters/1699fc1a-941f-11e8-8625-fa163e27d492/storage-ports/0",
| "class":"storage-path",
| "element-id":"7f4dc8d0-94d9-11e8-917c-fa163e3fe47d",
| "element-uri":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492/
| storage-paths/7f4dc8d0-94d9-11e8-917c-fa163e3fe47d",
| "exit-port":"00",
| "exit-switch-uri":"/api/storage-switches/90204662-9437-11e8-9c43-fa163e27d492",
| "parent":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492"
| }
|
|
| Figure 227. Storage Control Unit object: Sample inventory data - Response
|
| Storage Group object
| A Storage Group object represents a single storage group associated with a DPM-enabled CPC. Storage
| groups define a set of FCP or FICON storage volume resources that can be attached to partitions. Storage
| group properties that are common to the group are represented by the Storage Group object. Each storage
| volume in the group is represented by the Storage Volume element object. When a storage group is
| attached to a partition, the group’s fulfilled resources are virtualized and the partition’s view of them is
| represented by a set of Virtual Storage Resource element objects. The Storage Group object APIs provide
| access to the set of storage groups that are associated with a CPC that is enabled for DPM. APIs exist to
| create and modify storage groups and their volumes, and delete and query storage group properties.
| APIs also exist to query and fulfill the storage volume elements, and to query and update selected
| properties of the virtual storage resource elements of storage groups.

| A storage group transitions through a number of states in its lifecycle. It is complicated by the fact that
| some of its attributes cannot be realized without changes to the configuration of the Storage Area
| Network (SAN) in which the storage resources defined in the group reside. Creation or modification of a
| storage group by a system administrator requires a subsequent fulfillment action by the SAN

Chapter 10. Dynamic Partition Manager (DPM) 409

 Level 04a

| administrator before the storage resources in that group can be used by a partition. The nature of the
| actions required of the SAN administrator to fulfill a storage request differ depending on whether the
| storage group is defining FCP versus FICON resources. Fulfillment of FCP resources can be
| auto-detected, whereas fulfillment of FICON resources requires the SAN administrator to explicitly map
| the selected ECKD volumes to the requested volumes in the storage group.

| Modifications to a group that require a fulfillment cycle are particularly complex because the new
| property values must be saved in addition to the active values, which are the ones that remain in effect if
| the storage group is currently active or activated before the modifications are fulfilled. To accommodate
| these needs, the storage group class contains two versions of each property that depends on fulfillment: a
| base version that represents the configured value and an active version (identified by an "active-" prefix
| to the property name), which represents the value of those properties for storage groups attached to
| partitions that are currently active, or when they are next activated. In a new group or volume that has
| not yet been fulfilled, the active property values will be null and the base property values will contain
| the values of that properties that were specified, or defaulted, during group creation. Once the resources
| in the group are all fulfilled, the base value will be copied into the active value. If a group or volume is
| modified, the new values specified in the update operation will be placed into the same-named base
| properties. The active values continue to represent the state of the storage in partitions that are currently
| active, or become active before the modifications are fulfilled.

| A storage group has a fulfillment-state property that indicates a storage group's current fulfillment state.
| Storage volumes also have their own fulfillment-state property that indicates the fulfillment state of the
| individual storage volume. The table below lists important steps in a storage group’s lifecycle, and their
| effect on the group’s fulfillment-state and other properties, and on the partitions to which they are
| attached.
|| Lifecycle Step Comment
| A group is created The fulfillment-state property of the group and each volume is set to "pending".
| The base property values will be those specified or defaulted in the create
| operation, and the active property values will be null. An email is sent to the
| SAN administrator requesting fulfillment of the new group’s storage resources.
| The storage group may be attached to a partition, but if activated, the group’s
| storage resources will not be available to the partition.
| The group is fulfilled The fulfillment-state property of the group and each volume is set to "complete".
| The base property values are copied to their corresponding active properties. The
| group’s storage resources are now available to a partition. If the storage group is
| currently attached to an active partition, the resources will be dynamically made
| available to the partition.

| Note that there is no guarantee that all of a storage group’s resource will be
| fulfilled at the same time, so it is possible for a storage group to be in a state of
| partial fulfillment. In that case, some of the properties will have been fulfilled,
| indicated by the base and active property values being equal, and some have not.
| The group’s fulfillment-state property will be updated to "complete" only after
| all its resources have been fulfilled.

410 HMC Web Services API

 Level 04a

| Lifecycle Step Comment

| The group is modified If volumes are added, or any group or volume property for which an active
| property exists is modified, the group fulfillment-state property is set to
| "pending". The base property values will be those specified in the update
| operation. The active property values will remain unchanged. New and deleted
| volumes URIs are added to or remove from the storage-volume-uris property of
| the group. If the storage group is attached to a partition that is currently active or
| subsequently activated, it will continue to see the original storage resources. The
| fulfillment-state property of any new volume, or any volume with a modified
| base property, is set to "pending". If storage volumes are created or deleted, or
| any group or volume property for which an active property exists is modified, an
| email is sent to the SAN administrator requesting fulfillment of the new or
| modified resources.

| The fulfillment state for deleted FCP storage volumes changes to "deleting".
| Deleted FCP volumes are removed from their parent storage group only after the
| system detects that the backing SAN resources have been deconfigured.

| Deleted FICON volumes are removed immediately and do not required action by
| the SAN administrator. Deleted volumes are included in the email to notify the
| SAN administrator that those storage resources may now be recovered.
| The group's new and modified The fulfillment-state property of the group and each volume is set to "complete".
| resources are fulfilled The updated base property values are copied to the active properties. The group's
| new or updated storage resources are now available to a partition. If attached to
| an active partition, its resources will be dynamically changed.
| The group is attached to a If the partition is currently active, the group's storage fulfilled resources are
| partition dynamically added to the partition. A group can be attached to a partition any
| time after it is created.
| The group is detached from a If the partition is currently active, the group's storage resources are dynamically
| partition removed from the partition.
| The group is deleted The group must be detached from all partitions to which it is attached before it
| can be deleted. The delete of the group also deletes all its storage volumes.
|

| Data model
| This object includes the properties that are defined in the “Base managed object properties schema” on
| page 60, with the class-specific specializations identified in Table 192 on page 412. The Storage Group
| object does not support the operational status related properties.
| Table 191. Storage Group object: base managed object properties specializations
| Name Qualifier Type Description of specialization
| object-uri — String/ The canonical URI path of the Storage Group object is of the form
| URI /api/storage-groups/{storage-group-id} where
| {storage-group-id} is the value of the object-id property of the
| Storage Group object.
| object-id — String (36) The unique identifier for the storage group instance.
| parent — String/URI The parent of a storage group is conceptually its owning Console,
| and so the parent value is the canonical URI path for the Console.
| class — String (13) The class of a Storage Group object is "storage-group".
| name (w)(pc) String The display name specified for the storage group. The length and
| (1-64) character requirements on this property are the same as those of
| the name property described in the “Base managed object
| properties schema” on page 60. Names must be unique to the other
| storage groups associated to the same CPC.

Chapter 10. Dynamic Partition Manager (DPM) 411

 Level 04a

| Table 191. Storage Group object: base managed object properties specializations (continued)
| Name Qualifier Type Description of specialization
| description (w)(pc) String Arbitrary text providing additional descriptive information about
| (0-200) the storage group.

| Default value: an empty string.

|

| Class specific additional properties

| In addition to the properties defined via included schema, this object includes the following additional
| class-specific properties:
| Table 192. Storage Group object: class specific properties
| Supported
| Name Qualifier Type Description "type" values
| cpc-uri — String/ The canonical URI path of the CPC object All
| URI associated with this storage group object.
| type — String The type of storage resources managed by the All
| Enum storage group. Values:
| v "fcp" - Fibre Channel Protocol
| v "fc" - Fibre Connection
| shared (w)(pc) Boolean true if this storage group can be attached to more All
| than one partition; false if this storage group is
| dedicated to a single partition.

| This property’s value cannot be changed from true

| to false if the group is attached to more than one
| partition.

| This property’s value must be "false" when the

| value of the max-partitions property is 1.

| Default value: true

412 HMC Web Services API

 Level 04a

| Table 192. Storage Group object: class specific properties (continued)

| Supported
| Name Qualifier Type Description "type" values
| fulfillment-state (pc) String The current fulfillment state of the storage group. All
| Enum Values:
| v "complete" – All resources in this storage group
| have been fulfilled.
| v "pending" – The storage group has been created
| or modified , but has not yet been completely
| fulfilled by the SAN administrator.
| v "pending-with-mismatches" – One or more of
| the volumes of this storage group have a
| fulfillment-state property value of
| "pending-with-mismatches",
| "configuration-error" or "overprovisioned". This
| fulfillment state is only applicable if the type
| property value is "fcp".
| v "checking-migration" – The storage group was
| created automatically when the
| dpm-storage-management feature was enabled
| for the Defined CPC. Volumes that were
| configured for the virtual storage resources
| before the feature enablement are being
| identified. This fulfillment state is only
| applicable if the type property value is "fcp".
| v "incomplete" – The storage group migration is
| complete, but at least one of its storage volumes
| cannot be detected. This fulfillment state is only
| applicable if the type property value is "fcp".

| Default value: "pending"

| storage-volume-uris (c)(pc) Array of The list of storage volumes in this storage group. All
| String/ Each element in this array is the canonical URI
| URI path of a Storage Volume object.

| This value will change as storage volumes are

| added and removed from this storage group via
| the Modify Storage Group Properties operation.

| Default value: An empty array

| virtual-storage- (c)(pc) Array of The list of virtual storage resources for this storage fcp
| resource-uris String/ group. Each element in this array is the canonical
| URI URI path of a Virtual Storage Resource object.

| This value will change, and property change

| notification emitted, when the storage group has
| fulfilled resources and is attached to or detached
| from partitions, or when the storage group is
| already attached to a partition and resources are
| fulfilled again due to a size change.

| Default value: An empty array.

Chapter 10. Dynamic Partition Manager (DPM) 413

 Level 04a

| Table 192. Storage Group object: class specific properties (continued)

| Supported
| Name Qualifier Type Description "type" values
| connectivity (w)(pc) Integer The number of adapters to utilize for this storage All
| (1-64) group.

| A storage group may be created with a

| connectivity value of 1, but to maintain
| redundancy, the connectivity value of an existing
| storage group may not be reduced to 1.

| When the type value is "fc", the maximum value

| for the connectivity property is 8.

| Default value: 2 for storage groups of type "fcp";

| or 8 for storage groups of type "fc".
| active-connectivity (pc) Integer The value of connectivity that applies when the fcp
| (1-64) group is attached to partitions that are currently
| active or when the partitions are next activated. If
| the value of the fulfillment-state property is
| "pending" for newly created storage groups, this
| property value will be null, indicating it is not
| applicable.

| When the type value is "fc", the maximum value

| for the active-connectivity property is 8.

| This value will change to the value of

| connectivity, and property change notifications
| emitted, when the value of the connectivity
| property decreases, or after the value of the
| connectivity property increases and the new or
| modified storage group is fulfilled.
| max-partitions (w)(pc) Integer The maximum number of partitions to which this fcp
| storage group can be attached.

| The value of max-partitions cannot exceed 1 if the

| value of the shared field is false. The value of
| max-partitions must be greater than 1 if the value
| of the shared field is true.

| The value of max-partitions cannot be decreased

| when the storage group is attached to any
| partition.

| The value of max-partitions cannot be decreased

| to a value that is less that the total number of
| partitions to which this storage group is currently
| attached.

| The minimum value for the max-partitions

| property is 1; the maximum is the value of the
| CPC object's maximum-partitions property.

| Default value: 2

414 HMC Web Services API

 Level 04a

| Table 192. Storage Group object: class specific properties (continued)

| Supported
| Name Qualifier Type Description "type" values
| active-max-partitions (pc) Integer When the value of the max-partitions property fcp
| changes, the limit on the number of partitions to
| which the partition can be attached changes
| immediately. However, if the value increases, the
| storage resources for the additional partitions
| require fulfillment. When the storage group is
| attached to more than the active-max-partitions
| number of partitions, the most recently attached
| partitions will not see the storage group's storage
| resources until that fulfillment occurs. If the value
| of the fulfillment-state property is "pending" for
| newly created storage groups, this property value
| will be null, indicating it is not applicable.

| This value will change to the value of

| max-partitions, and property change notifications
| emitted, when the value of the max-partitions
| property decreases, or after the value of the
| max-partitions property increases and the new or
| modified storage group is fulfilled.
| candidate-adapter- (c)(pc) Array of The list of adapter ports that are candidates for use fcp
| port-uris String/ in fulfilling connections to FCP devices. Each
| URI element in this array is an instance of the canonical
| URI path of a storage adapter port.

| This value will change, and property change

| notifications emitted, when candidate adapter port
| are added and removed via the Add Candidate
| Adapter Ports to an FCP Storage Group or
| Remove Candidate Adapter Ports from an FCP
| Storage Group operations.
| direct-connection- (w)(pc) Integer The number of additional virtual storage resource fcp
| count (0-1000) connections for the host that can be directly
| assigned to a guest virtual machine. A value of
| zero indicates this feature is disabled.

| The direct-connection-count property cannot be

| enabled (greater than zero) when the shared
| property is true.

| Default value: 0
| unassigned-world- (c)(pc) Array of The list of information about the World Wide Port fcp
| wide-port-names world- Names (WWPNs) that have been allocated to
| wide- support this FCP storage group, but have not yet
| port- been assigned to a virtual storage resource. Each
| name element in this array is an instance of a
| info world-wide-port-name-info nested object, defined
| in Table 195 on page 423.

| This value will change, and property change

| notifications emitted, when the connectivity or
| max-partitions properties change, when virtual
| storage resources are created or deleted, or when
| the status value of a WWPN in the list changes.

| Default value: An empty array.

|

Chapter 10. Dynamic Partition Manager (DPM) 415

 Level 04a

| Storage Volume element object

| A Storage Volume element object defines the size and usage of a single storage volume within its parent
| storage group.
| Table 193. Storage Volume element object properties
| Supported
| adapter "type"
| Name Qualifier Type Description values
| element-id — String (32) Unique identifier for the storage volume All
| instance
| element-uri — String/URI The canonical URI path for the storage All
| port object, of the form
| /api/storage-groups/{storage-group-
| id}/storage-volumes/{storage-volume-
| id}, where {storage-group-id} is the
| object-id of the containing storage
| group, and {storage-volume-id} is the
| element-id of this storage volume.
| parent — String/URI The parent of a storage volume is All
| conceptually its owning storage group,
| and so the parent value is the canonical
| URI path for the storage group.
| class — String (14) The class of a storage volume element is All
| "storage-volume".
| name (w)(pc) String (1-64) The name of the storage volume. The All
| length and character requirements on
| this property are the same as those of
| the name property described in the
| “Base managed object properties
| schema” on page 60.

| Names must be unique to the other

| storage volumes associated with the
| parent storage group.

| Value: Currently of the form "# GiB

| {usage}{index}", where # is the size of the
| volume, {usage} is the usage, and {index}
| is a number that may or may not be
| present to ensure name uniqueness. This
| form is subject to change in the future.
| description (w)(pc) String (0-100) Arbitrary text providing additional All
| descriptive information about the
| volume.

| Default value: An empty string

416 HMC Web Services API

 Level 04a

| Table 193. Storage Volume element object properties (continued)

| Supported
| adapter "type"
| Name Qualifier Type Description values
| fulfillment-state (pc) String Enum The current fulfillment state of the All
| storage volume. Values:
| v "complete" – The storage volume
| resource has been fulfilled
| v "configuration-error" – A logical unit
| has been sensed on some, but not all,
| of the WWPNs defined to the parent
| storage group. This fulfillment state is
| only applicable if the type property
| value of the parent storage group is
| "fcp".
| v "deleting" – The storage volume has
| been deleted, but the SAN
| administrator has not yet
| unconfigured it logical unit. This
| fulfillment state is only applicable if
| the type property value of the parent
| storage group is "fcp".
| v "incomplete" – Migration for the
| parent storage group is complete, but
| this storage volume cannot be
| detected. This fulfillment state is only
| applicable if the type property value
| of the parent storage group is "fcp".
| v "overprovisioned" -Additional logical
| units have been sensed beyond what
| is required to fulfill this volume. This
| fulfillment state is only applicable if
| the type property value of the parent
| storage group is "fcp".
| v "pending" – The storage volume has
| been created or modified, but has not
| yet been fulfilled by the SAN
| administrator.
| v "pending-with-mismatches" – No
| logical unit with a size that exactly
| matches the size of this volume has
| been sensed. A logical unit with the
| closest size has been selected for this
| volume. This fulfillment state is only
| applicable if the type property value
| of the parent storage group is "fcp".

| If the eckd-type property has a value of

| "alias", the value of the fulfillment-state
| property will be null.

| Default value: "pending"

Chapter 10. Dynamic Partition Manager (DPM) 417

 Level 04a

| Table 193. Storage Volume element object properties (continued)

| Supported
| adapter "type"
| Name Qualifier Type Description values
| size (w)(pc) Float The size in gibibytes (GiB) for this All
| volume. If the value of the eckd-type
| property is "alias", this property value
| will be null, indicating it is not
| applicable, and the property cannot be
| updated.

| For volumes in storage group of type

| "fcp", the size property must be between
| 1.00 and 1,048,576.00.

| For volumes in storage groups of type

| "fc", with a model value other than
| "EAV", the size property is fixed at the
| value specified in the table below and
| cannot be written:
| Model - Maximum size
| "1" - 0.88
| "2" - 1.76
| "3" - 2.64
| "9" - 7.92
| "27" - 25.93
| "54" - 51.86

| For volumes with a model value of

| "EAV", size is writable and must be
| between 0.88 and 212489.20. Note
| however that the maximum is a
| theoretical size that may not be
| supported by an operating system.

| The value of the size property cannot be

| reduced once a storage volume is
| created.

| For volumes in storage groups of type

| "fc", the size value is related to the
| cylinders property. Specifying the size in
| GiB will also define the number of
| cylinders and vice versa. The size and
| cylinders properties cannot be specified
| together as fields in a create or modify
| operation.

418 HMC Web Services API

 Level 04a

| Table 193. Storage Volume element object properties (continued)

| Supported
| adapter "type"
| Name Qualifier Type Description values
| active-size (pc) Float The value of size that applies when the All
| volume is attached to partitions that are
| currently active or when the partitions
| are next activated. If the value of the
| fulfillment-state property is "pending"
| for a newly created volume, or if the
| value of the eckd-type property is
| "alias", this property value will be null,
| indicating it is not applicable.

| For volumes in storage group of type

| "fcp", the active-size property will be
| between 1.00 and 1,048,576.00

| For volumes in storage groups of type

| "fc", with a model value other than
| "EAV", the active-size property is fixed
| at the value specified in the table below
| and cannot be written:
| Model - Maximum size
| "1" - 0.88
| "2" - 1.76
| "3" - 2.64
| "9" - 7.92
| "27" - 25.93
| "54" - 51.86

| For volumes with a model value of

| "EAV", active-size will be between 0.88
| and 212489.20.

| This value will change to the value of

| size, and property change notifications
| emitted, when the new or modified
| storage volume is fulfilled.
| usage (w)(pc) String Enum The usage of the storage volume. Values: All
| v "boot" – this storage volume will
| contain a bootable image.
| v "data" – this storage volume will
| contain data.
| v "not-applicable" – the usage property
| does not apply to this storage volume.
| This value may never be used when
| creating or modifying a storage
| volume, but may appear as the value
| for this property in a response body.

| If the value of the usage property is

| "not-applicable", the property cannot be
| written.

| Default value: "data"

| uuid — String (16, 32) The sensed UUID of an FCP storage fcp
| volume.

Chapter 10. Dynamic Partition Manager (DPM) 419

 Level 04a

| Table 193. Storage Volume element object properties (continued)

| Supported
| adapter "type"
| Name Qualifier Type Description values
| model (w)(pc) String Enum The 3390 model designation for the fc
| storage. If the value of the eckd-type
| property is "alias", this property value
| will be null, indicating it is not
| applicable, and the property cannot be
| written. Values:
| "1" - Model 1
| "2" - Model 2
| "3" - Model 3
| "9" - Model 9
| "27" - Model 27
| "54" - Model 54
| "EAV" - Extended Address Volume

| The value of the model property cannot

| be changed to a smaller size once a
| storage volume is created.
| active-model (pc) String Enum The value of model that applies when fc
| the volume is attached to partitions that
| are currently active or when the
| partitions are next activated. If the value
| of the fulfillment-state property is
| "pending" for a newly created volume,
| or if the value of the eckd-type property
| is "alias", this property value will be
| null, indicating it is not applicable.
| Values:
| "1" - Model 1
| "2" - Model 2
| "3" - Model 3
| "9" - Model 9
| "27" - Model 27
| "54" - Model 54
| "EAV" - Extended Address Volume

| This value will change to the value of

| model, and property change notifications
| emitted, when the new or modified
| storage volume is fulfilled.

420 HMC Web Services API

 Level 04a

| Table 193. Storage Volume element object properties (continued)

| Supported
| adapter "type"
| Name Qualifier Type Description values
| cylinders (w)(pc) Integer The size of the volume in cylinders. If fc
| (1113-268434453) the value of the eckd-type property is
| "alias", this property value will be null,
| indicating it is not applicable, and the
| property cannot be written.

| If the model value is other than "EAV",

| the cylinders property is fixed at the
| value specified in the table below and
| cannot be written:
| Model - Maximum cylinders
| "1" - 1113
| "2" - 2226
| "3" - 3339
| "9" - 10017
| "27" - 32760
| "54" - 65520

| For volumes with a model value of

| “EAV”, cylinders is writable and has a
| maximum value of 268434453. Note
| however that this is a theoretical size
| that may not be supported by an
| operating system.

| The value of the cylinders property

| cannot be reduced once a storage
| volume is created.

| The cylinders value is related to the size

| property. Specifying the size in cylinders
| will also define the size and vice versa.
| The cylinders and size properties cannot
| be specified together as fields in a create
| or modify operation.
| device-number (w)(pc) String (4) A four-byte lower case hexadecimal fc
| string defining the device number that is
| assigned by default when the FICON
| storage group containing this storage
| volume is attached to partitions. This
| value may be null, in which case the
| system auto-assigns a device number.

| Default value: null

Chapter 10. Dynamic Partition Manager (DPM) 421

 Level 04a

| Table 193. Storage Volume element object properties (continued)

| Supported
| adapter "type"
| Name Qualifier Type Description values
| control-unit-uri (pc) String/URI The canonical URI of the logical control fc
| unit (LCU) in which the backing ECKD
| volume is defined.

| The value of this property will be null if

| a new "base" volume has not yet been
| fulfilled.

| This value will change, and property

| change notifications emitted, when the
| storage volume is fulfilled via the Fulfill
| FICON Storage Volume operation.

| Default value: null.

| eckd-type — String Enum The type of the backing ECKD volume. fc
| Values:
| v "base" - The volume is an ECKD base
| volume.
| v "alias" - The volume is an ECKD alias
| volume.

| Default value: "base"

| unit-address (pc) String (2) A two-character lower case hexadecimal fc
| number that represents the unit address
| of the backing ECKD volume within the
| control unit.

| The value of this property will be null if

| a new "base" volume has not yet been
| fulfilled.

| This value will change, and property

| change notifications emitted, when the
| storage volume is fulfilled via the Fulfill
| FICON Storage Volume operation.

| Default value: null

|

| Virtual Storage Resource element object

| A virtual storage resource defines the virtualized view of a storage adapter as seen by a partition.
| Table 194. Virtual Storage Resource element object properties
| Name Qualifier Type Description
| element-id — String (36) The unique identifier for the virtual storage
| resource instance.
| element-uri — String/URI The canonical URI path for the Virtual Storage
| Resource element object, of the form
| /api/storage-groups/{storage-group-id}/
| virtual-storage-resources/{virtual-storage-
| resource-id}, where {storage-group-id} is the
| object-id of the containing storage group, and
| {virtual-storage-resource-id} is the element-id of
| this virtual storage resource.

422 HMC Web Services API

 Level 04a

| Table 194. Virtual Storage Resource element object properties (continued)

| Name Qualifier Type Description
| parent — String/URI The parent of a virtual storage resource is its
| owning storage group, so the parent value is the
| canonical URI path for the storage group.
| class — String (24) The class of a virtual storage resource element
| object is "virtual-storage-resource".
| name (w)(pc) String (1-64) The display name specified for the virtual
| storage resource. The length and character
| requirements on this property are the same as
| those of the name property described in the
| “Base managed object properties schema” on
| page 60. Names must be unique to the other
| virtual storage resources within the parent
| storage group.
| description (w)(pc) String (0-1024) Arbitrary text providing additional descriptive
| information about the virtual storage resource.
| partition-uri — String/URI The canonical URI path of the partition to which
| this virtual storage resource is attached
| device-number (w)(pc) String (4) Device number of the virtual storage resource.

| The value must be a 4-digit lower case

| hexadecimal. The value must be unique across
| the device numbers of all other virtual storage
| resource elements and all NIC elements of type
| "iqd" or "osd" of the partition identified by
| partition-uri.

| Default value: Auto-generated

| adapter-port-uri — String/URI The canonical URI path of the adapter Storage
| Port element to which this virtual storage
| resource is associated.

| The value of this property will be null if a

| candidate adapter has not been discovered to
| back this virtual storage resource.
| world-wide-port-name — String (16) A 16-character lower case hexadecimal string
| that contains the world wide port name of the
| FCP virtual storage resource.
|

| A World Wide Port Name information object defines properties relating to a single World Wide Port
| Name (WWPN).
| Table 195. World Wide Port Name Information nested object: WWPN related properties
| Name Type Description
| world-wide-port-name String (16) A 16-character lower case hexadecimal string that contains a World Wide
| Port Name used to access the FCP storage volumes in the storage group.
| status String Enum The current status of the World Wide Port Name. Values:
| v "validated" - The CPC can sense all the storage volumes defined in the
| storage group using this WWPN.
| v "not-validated" - The CPC is unable to sense one or more of the storage
| volumes using this WWPN.
|

Chapter 10. Dynamic Partition Manager (DPM) 423

 Level 04a

| List Storage Groups

| The List Storage Groups operation lists the storage groups known to the target Console.

| HTTP method and URI

| GET /api/storage-groups

| Query parameters:
|| Name Type Rqd/Opt Description
| cpc-uri String/URI Optional Filter string to limit returned objects to those that have a matching
| cpc-uri property.
| name String Optional Filter pattern (regular expression) to limit returned objects to those
| that have a matching name property.
| fulfillment-state String Optional Filter string to limit returned objects to those that have a matching
| Enum fulfillment-state property.

| Value must be a valid storage group fulfillment-state property

| value.
| type String Optional Filter string to limit returned objects to those that have a matching
| Enum type property value.

| Value must be a valid storage group type property value.

|

| Response body contents

| On successful completion, the response body is a JSON object with the following fields:
|| Field name Type Description
| storage-groups Array of Array of storage-group-info objects, described in the next table. The
| storage- returned array may be empty.
| group-info
| objects
|

| Each nested storage-group-info object contains the following fields:

|| Field name Type Description
| object-uri String/ Canonical URI path (object-uri) of the Storage Group object.
| URI
| cpc-uri String/ The cpc-uris property of the Storage Group object.
| URI
| name String The name property of the Storage Group object.
| fulfillment-state String The fulfillment-state property of the Storage Group object.
| Enum
| type String The type property of the Storage Group object.
| Enum
|

| Description

| This operation lists the storage groups that are known by the target Console. The object URI, name,
| fulfillment state, type and CPC URI are provided for each.

424 HMC Web Services API

 Level 04a

| If the name query parameter is specified, the returned list is limited to those storage groups that have a
| name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
| done.

| If the fulfillment-state or type query parameter is specified, each parameter is validated to ensure it is a
| valid value for the storage group fulfillment-state or type property according to the data model. If the
| value is not valid, a 400 (Bad Request) is returned. If the value is valid, the returned list is limited to
| those storage groups that have a fulfillment-state or type property matching the specified value. If the
| fulfillment-state or type parameter is omitted, this filtering is not done.

| If the cpc_uri query parameter is specified, the returned list is limited to those storage groups that have a
| matching cpc-uri property. If the cpc-uri parameter is omitted, this filtering is not done.

| A storage group is included in the list only if the API user has object-access permission for that object. If
| the API user does not have permission to a storage group, that object is simply omitted from the list but
| no error status code results.

| If no storage groups are to be included in the results due to filtering or lack of object-access permission,
| an empty list is provided and the operation completes successfully.

| Authorization requirements

| This operation has the following authorization requirement:

| v Object-access permission to each Storage Group 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 424.

| 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 any associated error message.
| Table 196. List Storage Groups: 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.
| 14 A query parameter defines an invalid value.
|

| 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/storage-groups HTTP/1.1

| x-api-session: 3or8sd53i1g0swx7g3e29tnhzdc44tss6hzg3fr65bm29h1c3p
|
|
| Figure 228. List Storage Groups: Request

Chapter 10. Dynamic Partition Manager (DPM) 425

 Level 04a

| 200 OK
| server: Hardware management console API web server / 2.0
| cache-control: no-cache
| date: Mon, 06 Aug 2018 15:59:10 GMT
| content-type: application/json;charset=UTF-8
| content-length: 420
| {
| "storage-groups":[
| {
| "cpc-uri":"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e",
| "fulfillment-state":"pending",
| "name":"FCP Storage Group",
| "object-uri":"/api/storage-groups/491e058c-998d-11e8-a345-fa163e27d492",
| "type":"fcp"
| },
| {
| "cpc-uri":"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e",
| "fulfillment-state":"complete",
| "name":"FICON Group",
| "object-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492",
| "type":"fc"
| }
| ]
| }
|
|
| Figure 229. List Storage Groups: Response

| Create Storage Group

| The Create Storage Group operation creates a new storage group object.

| HTTP method and URI

| POST /api/storage-groups

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| cpc-uri String/URI Required The value to be set as the storage group’s cpc-uri
| property.
| name String Required The value to be set as the storage group's name property.
| (1-64)
| description String Optional The value to be set as the storage group's description
| (1-200) property.
| type String Required The value to be set as the storage group's type property.
| Enum
| shared Boolean Optional The value to be set as the storage group's shared
| property.
| connectivity Integer Optional The value to be set as the storage group's connectivity
| (1-64) property.
| max-partitions Integer Optional The value to be set as the storage group's max-partitions
| property.

| The max-partitions field is not allowed in the request

| body unless the type field has a value of "fcp".

426 HMC Web Services API

 Level 04a

| Field name Type Rqd/Opt Description

| direct-connection- Integer Optional The value to be set as the storage group's
| count (0-1000) direct-connection-count property.

| The direct-connection-count field is not allowed in the

| request body unless the type field has a value of "fcp".
| storage-volumes Array of Optional The set of volume properties for each of the storage
| storage- volumes in the group.
| volume-
| request- An array of one or more storage-volume-request-info
| info nested nested objects, where each element defines the new
| objects property values of a storage volume that is to be created.
| The operation field of each nested object element must be
| set to "create".

| For storage groups of type "fc", the storage-volume-

| request-info nested object is defined in Table 200 on page
| 437. For storage groups of type "fcp", the
| storage-volume-request-info nested object is defined in
| Table 201 on page 437.
| email-to-addresses Array of Optional A set of zero or more email addresses for the people that
| String are to be notified via email of the new storage group
| resources that require fulfillment. These email addresses
| will appear in the "to:" address list in the email that is
| sent.

| Default value: null. No email will be sent.

| email-cc-addresses Array of Optional A set of zero or more email addresses for the people that
| String are to be copied on the email notification of the new
| storage group resources that require fulfillment. These
| email addresses will appear in the "cc:" address list in the
| email that is sent.

| The email-cc-addresses field must be null when the

| email-to-addresses field is null.

| Default value: null. No one will be copied on the email.

| email-insert String Optional Text that is to be inserted in the email notification of the
| new storage group resources that require fulfillment. The
| text can include HTML formatting tags.

| The email-insert field must be null when the

| email-to-users field is null.

| Default value: null. An email without a special text insert

| will be sent.
|

| 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 newly created Storage Group object.
| element-uris Array of A list of the URIs for the storage volume elements that are created. The
| String/URI order of the URIs in this list will match the order in which the new volumes
| were specified in the storage-volumes field in the request body.
|

Chapter 10. Dynamic Partition Manager (DPM) 427

 Level 04a

| Description

| This operation creates a storage group with the values specified and then returns its object-uri and the
| element-uris of each storage volume that was created in the response body. The response also includes a
| Location header that provides the new storage group's URI. Inventory Change notifications for the new
| storage group and for each new storage volume identified in the storage-volumes field are emitted
| asynchronously to this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer
| task, a 403 (Forbidden) status code is returned. If the object ID {cpc-id} does not identify a CPC object to
| which the API user has object-access permission, a 404 (Not Found) status code is returned. If the CPC
| identified by the cpc-uri field is already associated with a storage group with the specified name, or if the
| email-insert or email-cc-addresses fields are present in the request body without the email-to-addresses
| field, or if any address in the email-to-addresses or email-cc-addresses fields is not a valid email address,
| a 400 (Bad Request) status code is returned. If the CPC identified by the cpc-uri field is not enabled for
| DPM or does not have the dpm-storage-management feature enabled or is not active, or if restrictions on
| the values of the shared and max-partitions property values, or the shared and direct-connection-count
| property values are violated, or if no adapters are configured to the specified type, a 409 (Conflict) status
| code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because
| the document defines a field that is not supported for the given storage group type, or because both of,
| or neither of, the size and cylinders fields are defined for a new FICON storage volume.

| If the request body contents are valid, the storage group and each of the storage volumes defined in the
| storage-volumes field are created and their properties are set to their corresponding request body
| content's field's values. If a field is not found in the request body, its property's value will be defaulted.
| The group’s and volume’s active property values will be set to null. If at least one storage volume is
| being created, or the storage group being created defines a property with a corresponding active property,
| the create requires action by the SAN administrator and the fulfillment-state property of the storage
| group is set to "pending". Otherwise, the fulfillment-state property of the storage group is set to
| "complete".

| If the new storage group's fulfillment-state is "pending" and the email-to-addresses field is present in
| the request body, an email containing information about the storage group and volume resources that
| require fulfillment is sent to the email addresses specified in the email-to-addresses and
| email-cc-addresses fields in the request body. If the email-insert field is present, its contents will be
| inserted into the email body. If an error occurs when sending the email, a 409 (Conflict) status code is
| returned. This could be because the HMC is not configured to support emails. A failure to send the email
| does not rollback the creation of the storage group. An API client should assume that a storage group
| was created even though the request failed with a 409 (Conflict) status code and 491 reason code. Note
| that a successful completion does not imply that the emails were delivered. Errors could be encountered
| at an email server after the request completes, for example due to an unknown email address. If a send
| failure occurs, emails can be resent using the Request Storage Group Fulfillment request.

| Authorization requirements

| This operation has the following authorization requirement:

| v Object-access permission to the CPC whose object-id is cpc-uri.
| v Action/task permission to the Configure Storage – System Programmer 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” on page 427.

428 HMC Web Services API

 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 the associated error message.
| Table 197. Create Storage Group: 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 storage group with the name specified in the request body is already
| associated with the CPC identified by the cpc-uri specified in the request
| body.
| 15 The type field value is "fc" and an element of the storage-volumes field
| contains both the size and cylinders fields, or neither the size nor cylinders
| fields.
| 18 A supplied property is not valid for a storage group's type.
| 451 The email-cc-addresses or email-insert field is present in the request body
| without the email-to-addresses field.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer task.
| 404 (Not Found) 2 The CPC identified by the cpc-uri field does not exist on the HMC or the
| API user does not have object-access permission for it.
| 409 (Conflict) 1 The state of the CPC is not valid to perform the operation (must be in one of
| the following states: "active", "service-required", "degraded", or
| "exceptions").
| 5 The CPC identified by the cpc-uri field is not enabled for DPM.
| 8 The max-partitions field value conflicts with the shared field value.
| 13 The CPC identified by the cpc-uri field does not support the
| dpm-storage-management feature.
| 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.
| 487 No adapters are configured for the storage protocol need to support a
| storage group with the specified type.
| 491 An error occurred when sending the email. This failure applies only to the
| sending of the email. If this reason code is returned, a new storage group
| will have been created.
| 495 The direct-connection-count field value conflicts with the shared field value.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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) 429

 Level 04a

| Example HTTP interaction

|

POST /api/storage-groups HTTP/1.1

x-api-session: d3dxdh07kglx7sc3wyvefv39ur355eddoghhw190cqc72qa8g
content-type: application/json
content-length: 194
{
"connectivity":4,
"cpc-uri":"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e",
"name":"FICON Group",
"storage-volumes":[
{
"model":"1",
"operation":"create",
"usage":"boot"
}
],
"type":"fc"
}

Figure 230. Create Storage Group: Request

201 Created
server: Hardware management console API web server / 2.0
location: /api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492
cache-control: no-cache
date: Thu, 02 Aug 2018 19:26:13 GMT
content-type: application/json;charset=UTF-8
content-length: 202
{
"element-uris":[
"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
ec738d80-9689-11e8-aa30-fa163e27d492"
],
"object-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492"
}

Figure 231. Create Storage Group: Response

| Delete Storage Group

| The Delete Storage Group operation deletes a storage group.

| HTTP method and URI

| POST /api/storage-groups/{storage-group-id}/operations/delete

| In this request, the URI variable {storage-group-id} is the object ID of the storage group to delete.

430 HMC Web Services API

 Level 04a

| Request body contents

| On successful completion, the response body is a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| email-to-addresses Array of Optional A set of zero or more email addresses for the people that are
| String to be notified via email of the storage group resources that
| are no longer needed. These email addresses will appear in
| the "to:" address list in the email that is sent.

| Default value: null. No email will be sent.

| email-cc-addresses Array of Optional A set of zero or more email addresses for the people that are
| String to be copied on the email notification of the storage group
| resources that are no longer needed. These email addresses
| will appear in the "cc:" address list in the email that is sent.

| The email-cc-addresses field must be null when the

| email-to-addresses field is null.

| Default value: null. No one will be copied on the email.

| email-insert String Optional Text that is to be inserted in the email notification of the
| storage group resources that are no longer needed. The text
| can include HTML formatting tags.

| The email-insert field must be null when the email-to-users

| field is null.

| Default value: null. An email without a special text insert will

| be sent.
|

| Description

| This operation deletes a storage group. The storage group must be detached from all partitions before it
| can be deleted. The storage group’s contained storage volume elements are also deleted. Inventory
| Change notifications for the deleted group and volume element object are emitted asynchronously to this
| operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer
| task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID
| {storage-group-id} does not identify a storage group object to which the API user has object-access
| permission.

| If the email-insert or email-cc-addresses fields are present in the request body without the
| email-to-addresses field, or if any address in the email-to-addresses or email-cc-addresses fields is not a
| valid email address, a 400 (Bad Request) status code is returned. If the storage group is still attached to
| any partition, or if the CPC on which this storage group resource exists is not active, a 409 (Conflict)
| status code is returned. A 409 (Conflict) status code is also returned if there is an error sending the email.
| This could be because the HMC is not configured to send emails.

| If the request body contents are valid, the identified storage group, and all its storage volumes, are
| deleted from the CPC. If the email-to-addresses field is present in the request body, an email containing
| information about the storage group and volume resources that may now be recovered is sent to the
| email addresses specified in the email-to-addresses and email-cc-addresses fields in the request body. If
| the email-insert field is present, its contents will be inserted into the email body. Note that a successful
| completion does not imply that the emails were delivered. A failure to send the email does not rollback
| the deletion of the storage group. An API client should assume that the storage group was deleted even
| though the request failed with a 409 (Conflict) status code and 491 reason code. Errors could be

Chapter 10. Dynamic Partition Manager (DPM) 431

 Level 04a

| encountered at an email server after the request completes, for example due to an unknown email
| address.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object-access permission to the storage group whose object-id is {storage-group-id}.
| v Action/task permission to the Configure Storage – System Programmer 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, and the response body is a
| standard error response body providing the reason code and associated error message.
| Table 198. Delete Storage Group: 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.
| 451 The email-insert or email-cc-addresses field is present in the request body
| without the email-to-addresses field.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer task.
| 404 (Not Found) 1 A storage group with the object-id {storage-group-id} does not exist on the
| HMC or the API user does not have object-access permission for it.
| 409 (Conflict) 1 The state of the CPC is not valid to perform the operation (must be in one of
| the following states: "active", "service-required", "degraded", or
| "exceptions").
| 2 The storage group object with the object-id {storage-group-id} was busy and
| the request timed out.
| 481 The storage group identified by {storage-group-id} is still attached to at least
| one partition.
| 491 An error occurred when sending the email. This failure applies only to the
| sending of the email. If this reason code is returned, the storage group will
| have been deleted.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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.

432 HMC Web Services API

 Level 04a

| Example HTTP interaction

|

POST /api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/operations/delete
HTTP/1.1
x-api-session: 3da1nome5qa8uu9lbikho8ftvkd4lqv1bei7xlla1zcar8cbuq
content-type: application/json
content-length: 50
{
"email-to-addresses":[
"SamStorage@company.com"
]
}

Figure 232. Delete Storage Group: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 31 Jul 2018 15:20:54 GMT

<No response body>

Figure 233. Delete Storage Group: Response

| Get Storage Group Properties

| The Get Storage Group Properties operation retrieves the properties of a single Storage Group object.

| HTTP method and URI

| GET /api/storage-groups/{storage-group-id}

| In this request, the URI variable {storage-group-id} is the object ID of the storage group object.

| Response body contents

| On successful completion, the response body is a JSON object that provides the current values of the
| properties for the Storage Group object as defined in the “Data model” on page 411. 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

| Returns the current values of the properties for the storage group object as defined in the “Data model”
| on page 411.

| If the object ID {storage-group-id} does not identify a storage group object to which the API user has
| object-access permission, a 404 (Not Found) status code is returned.

| Authorization requirements

| This operation has the following authorization requirement:

| v Object access permission to the storage group whose object-id is {storage-group-id}.

Chapter 10. Dynamic Partition Manager (DPM) 433

 Level 04a

| HTTP status and reason codes

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

| Otherwise, 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 199. Get Storage Group 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.
| 404 (Not Found) 1 A storage group with object-id {storage-group-id} does not exist on the HMC
| 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/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492 HTTP/1.1

x-api-session: 2zfl71u0zahnx479crjykbkccjiqxf4rstmhxi56mqgeup7kjs

Figure 234. Get Storage Group Properties: Request

434 HMC Web Services API

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Aug 2018 19:32:02 GMT
content-type: application/json;charset=UTF-8
content-length: 1066
{
"class":"storage-group",
"connectivity":4,
"cpc-uri":"/api/cpcs/e4f159ce-82a2-32a9-b8f2-de66c9b02e7e",
"description":"A sample FCON storage group",
"fulfillment-state":"complete",
"name":"FICON Group",
"object-id":"ec638c1e-9689-11e8-aa30-fa163e27d492",
"object-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492",
"parent":"/api/console",
"shared":true,
"storage-volume-uris":[
"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
ec738d80-9689-11e8-aa30-fa163e27d492",
"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
22de1d40-968a-11e8-a0a5-fa163e27d492",
"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
70322410-968a-11e8-a0a5-fa163e27d492",
"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
703e39c6-968a-11e8-a0a5-fa163e27d492",
"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
704a5e40-968a-11e8-a0a5-fa163e27d492",
"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
705620b8-968a-11e8-a0a5-fa163e27d492"
],
"type":"fc"
}

Figure 235. Get Storage Group Properties: Response

| Modify Storage Group Properties

| The Modify Storage Group Properties operation updates one or more of the writable properties of a
| storage group.

| HTTP method and URI

| POST /api/storage-groups/{storage-group-id}/operations/modify

| In this request, the URI variable {storage-group-id} is the object ID of the Storage Group object.

| Request body contents

| Fields for properties whose values are not to be changed by this operation can and should be omitted
| from the request body.
|| Field name Type Rqd/Opt Description
| name String Optional The value to be set as the storage group's name property.
| (1-64)
| description String Optional The value to be set as the storage group's description
| (0-200) property.
| shared Boolean Optional The value to be set as the storage group's shared
| property.

Chapter 10. Dynamic Partition Manager (DPM) 435

 Level 04a

| Field name Type Rqd/Opt Description

| connectivity Integer Optional The value to be set as the storage group's connectivity
| (1-64) property.

| If the current value of the storage group's type property is

| "fcp", modifying the connectivity property requires
| fulfillment action from the storage administrator. The
| storage group’s fulfillment-state property will change to
| "pending". If the email-to-list is also present in the
| request body, an email will be sent containing the new
| connectivity value.
| max-partitions Integer Optional The value to be set as the storage group’s max-partitions
| property.

| The max-partitions field is not allowed in the request

| body unless the current value of the storage group’s type
| property is "fcp".

| Modifying the max-partitions property requires

| fulfillment action from the storage administrator. The
| storage group's fulfillment-state property will change to
| "pending". If the email-to-list is also present in the
| request body, an email will be sent containing the new
| max-partitions value.
| direct-connection- Integer Optional The value to be set as the storage group's
| count (0-1000) direct-connection-count property.

| The direct-connection-count field is not allowed in the

| request body unless the current value of the storage
| group's type property is "fcp".

| The direct-connection-count field value cannot be greater

| than 0 for shared storage groups.
| storage-volumes Array of Optional An array of storage-volume-request-info nested objects,
| storage- where each element defines the existing storage volumes
| volume- that are to be deleted or the new property values of a
| request- storage volume that is to be created or modified. The
| info nested storage-volume-request-info nested object is defined in the
| objects tables that follow.

| If not specified, the storage group's volumes remain

| unchanged.
| email-to-addresses Array of Optional A set of zero or more email addresses for the people that
| String are to be notified via email of the modified storage group
| resources that require fulfillment. These email addresses
| will appear in the "to:" address list in the email that is
| sent.

| Default value: null. No email will be sent.

| email-cc-addresses Array of Optional A set of zero or more email addresses for the people that
| String are to be copied on the email notification of the modified
| storage group resources that require fulfillment. These
| email addresses will appear in the "cc:" address list in the
| email that is sent.

| The email-cc-addresses field must be null when the

| email-to-addresses field is null.

| Default value: null. No one will be copied on the email.

436 HMC Web Services API

 Level 04a

| Field name Type Rqd/Opt Description

| email-insert String Optional Text that is to be inserted in the email notification of the
| modified storage group resources that require fulfillment.
| The text can include HTML formatting tags.

| The email-insert field must be null when the

| email-cc-users field is null.

| Default value: null. An email without a special text insert

| will be sent.
|

| Each nested storage-volume-request-info object contains the following fields:

| Table 200. storage-volume-request-info nested object for "create" operations on "fc" storage volumes
| Field name Type Rqd/Opt Description
| operation String Required This nested object contains the property values for a new
| Enum storage volume that is to be created.

| Value: "create"
| name String Optional The value to be set as the storage volume's name
| (1-64) property.
| description String Optional The value to be set as the storage volume's description
| (0-100) property.
| size Float Optional The value to be set as the storage volume's size property.
| (0.88-
| 212489.20) If the model is "EAV", the size or cylinders fields (but not
| both) must be specified.

| If the model is not "EAV", the size field may not be

| present in the request body.
| usage String Optional The value to be set as the storage volume's usage
| Enum property.
| model String Required The value to be set as the storage volume's model
| Enum property.
| cylinders Integer Optional The value to be set as the storage volume's cylinders
| (1113- property.
| 268434453)
| If the model is "EAV", the size or cylinders fields (but not
| both) must be specified.

| If the model is not "EAV", the cylinders field may not be

| present in the request body.
| device-number String (4) Optional The value to be set as the storage volume's
| device-number property.
|
| Table 201. storage-volume-request-info nested object for "create" operations on "fcp" storage volumes
| Field name Type Rqd/Opt Description
| operation String Enum Required This nested object contains the property values for a
| new storage volume that is to be created.

| Value: "create"
| name String (1-64) Optional The value to be set as the storage volume's name
| property.

Chapter 10. Dynamic Partition Manager (DPM) 437

 Level 04a

| Table 201. storage-volume-request-info nested object for "create" operations on "fcp" storage volumes (continued)
| Field name Type Rqd/Opt Description
| description String (0-100) Optional The value to be set as the storage volume's description
| property.
| size Float (1.00 Required The value to be set as the storage volume's size
| -1048576.00) property.
| usage String Enum Optional The value to be set as the storage volume's usage
| property.
|
| Table 202. storage-volume-request-info nested object for "modify" operations on "fc" storage volumes
| Field name Type Rqd/Opt Description
| operation String Required This nested object contains the new property values for an
| Enum existing storage volume that is to be modified.

| Value: "modify"
| element-uri String/ Required The canonical URI path for the storage volume element
| URI object that is being updated.
| name String Optional The value to be set as the storage volume's name
| (1-64) property.
| description String Optional The value to be set as the storage volume's description
| (0-100) property.
| size Float Optional The value to be set as the storage volume's size property.
| (0.88-
| 212489.20) The size field is optional but may not be present in the
| request body if the cylinders field is present in the
| request body or if the model value is not "EAV".

| Modifying the size property requires fulfillment action

| from the storage administrator. The volume and parent
| storage group’s fulfillment-state properties will change to
| "pending". If the email-to-addresses is also present in the
| request body, an email will be sent containing the new
| size value.
| usage String Optional The value to be set as the storage volume's usage
| Enum property.
| model String Optional The value to be set as the storage volume's model
| Enum property.

| Modifying the model property requires fulfillment action

| from the storage administrator. The volume and parent
| storage group’s fulfillment-state properties will change to
| "pending". If the email-to-addresses is also present in the
| request body, an email will be sent containing the new
| model value.

438 HMC Web Services API

 Level 04a

| Table 202. storage-volume-request-info nested object for "modify" operations on "fc" storage volumes (continued)
| Field name Type Rqd/Opt Description
| cylinders Integer Optional The value to be set as the storage volume's cylinders
| (1113 property.
| -268434453)
| The cylinders field is optional but may not be preset in
| the request body if the size field is present in the request
| body or if the model value is not "EAV".

| Modifying the cylinders property requires fulfillment

| action from the storage administrator. The volume and
| parent storage group’s fulfillment-state properties will
| change to "pending". If the email-to-addresses is also
| present in the request body, an email will be sent
| containing the new cylinders value.
| device-number String (4) Optional The value to be set as the storage volume's
| device-number property.
|
| Table 203. storage-volume-request-info nested object for "modify" operations on "fcp" storage volumes
| Field name Type Rqd/Opt Description
| operation String Enum Required This nested object contains the new property values for
| an existing storage volume that is to be modified.

| Value: "modify"
| element-uri String/ URI Required The canonical URI path for the storage volume element
| object that is being updated.
| name String (1-64) Optional The value to be set as the storage volume's name
| property.
| description String (0-100) Optional The value to be set as the storage volume's description
| property.
| size Float (1.00 Optional The value to be set as the storage volume's size
| -1048576.00) property.

| Modifying the size property requires fulfillment action

| from the storage administrator. The volume and parent
| storage group’s fulfillment-state properties will change
| to "pending". If the email-to-addresses is also present
| in the request body, an email will be sent containing the
| new size value.
| usage String Enum Optional The value to be set as the storage volume's usage
| property.
|
| Table 204. storage-volume-request-info nested object for "delete" operations on "fc" or "fcp" storage volumes
| Field name Type Rqd/Opt Description
| operation String Required This nested object identifies an existing storage volume
| Enum that is to be deleted.

| Value: "delete"
| element-uri String/ Required The canonical URI path for the storage volume element
| URI object that is being deleted.
|

Chapter 10. Dynamic Partition Manager (DPM) 439

 Level 04a

| Response body contents

| On successful completion, the response body is a JSON object with the following fields:
|| Field name Type Description
| element-uris Array of A list of the URIs for the storage volume elements that are created. The
| String/URI order of the URIs in this list will match the order in which the new
| volumes were specified in the storage-volumes field in the request body.
|

| Description

| This operation updates a storage group's properties with the values specified and then returns the
| element-uris of each storage volume that was created in the response body.

| If the API user does not have action/task permission to the Configure Storage – System Programmer
| task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID
| {storage-group-id} does not identify a Storage Group object to which the API user has object-access
| permission.

| If the group’s fulfillment-state property value is "checking-migration", or if the CPC on which this
| storage group resource exists is not active, or if the change would put the storage group into a state
| where its shared and max-partitions property values or shared and direct-connection-count property
| values conflict, or if the shared property is false for a storage group that is attached to more than one
| partition, or if the a storage volume modification would put the volume into a state where its model, size
| and cylinders property values conflict, or the model, size or cylinders properties are being reduced, a
| 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because
| the document defines a field that is not supported for the given storage group type, or because the parent
| CPC is already associated with a storage group with the specified name, or because both of, or neither of,
| the size and cylinders fields of a FICON storage volume are defined, or because the email-insert or
| email-cc-addresses fields are present in the request body without the email-to-addresses field, or because
| any address in the email-to-addresses or email-cc-addresses fields is not a valid email address.

| If the request body contents are valid, the storage group's properties are updated to their corresponding
| request body content's field's values. All fields are optional and may be excluded from the request body;
| if a field is not found in the request body, its property's value will not be modified. The element URIs of
| each new and deleted storage volume will be added to, or removed from, the storage group's
| storage-volume-uris list property. If at least one property being modified has a corresponding active
| property, the update requires action by the SAN administrator and the fulfillment-state property of the
| storage group is set to "pending". All active property values remain unchanged.

| If the update changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation. This includes a Property Change notification
| for the storage-volume-uris property if the operation creates or deletes storage volumes.

| If the modified storage group’s fulfillment-state is "pending" and the email-to-addresses field is present
| in the request body, an email containing information about the modified storage group and volume
| resources that require fulfillment is sent to the email addresses specified in the email-to-addresses and
| email-cc-addresses fields in the request body. If the email-insert field is present, its contents will be
| inserted into the email body. If an error occurs when sending the email, a 409 (Conflict) status code is
| returned. This could be because the HMC is not configured to support emails. A failure to send the email
| does not rollback the modification of the storage group. An API client should assume that the storage
| group was modified even though the request failed with a 409 (Conflict) status code and 491 reason code.
| Note that a successful completion does not imply that the emails were delivered. Errors could be

440 HMC Web Services API

 Level 04a

| encountered at an email server after the request completes, for example due to an unknown email
| address. If a send failure occurs, emails can be resent using the Request Storage Group Fulfillment
| request.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object access permission to the storage group whose object-id is {storage-group-id}.
| v Action/task permission to the Configure Storage – System Programmer task.

| 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 440.

| Otherwise, 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 205. Modify Storage Group 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.
| 8 A storage group with the name specified in the request body is already
| associated with the CPC identified by the group's cpc-uri property.
| 15 The storage group’s type property value is "fc" and an element of the
| storage-volumes field contains both the size and cylinders fields, or an
| operation value of "create" and neither the size nor cylinders fields.
| 18 A supplied property is not valid for a storage group’s type.
| 450 The storage group’s type property value is "fc" and an element of the
| storage-volumes field has an operation value of "delete" and an element-uri
| value that references a storage volume with an eckd-type property value of
| "alias".
| 451 The email-cc-addresses or email-insert field is present in the request body
| without the email-to-addresses field.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer task.
| 404 (Not Found) 1 A storage group with the object-id {storage-group-id} does not exist on the
| HMC or the API user does not have object-access permission for it.
| 5 An element of the storage-volumes field has an element-uri value that is not
| a member of the storage group’s storage-volume-uris array property value.

Chapter 10. Dynamic Partition Manager (DPM) 441

 Level 04a

| Table 205. Modify Storage Group Properties: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 409 (Conflict) 1 The state of the CPC is not valid to perform the operation (must be in one of
| the following states: "active", "service-required", "degraded", or
| "exceptions").
| 2 The storage group object with the object-id {storage-group-id} was busy and
| the request timed out.
| 8 The operation would result in conflicting values for the max-partitions and
| shared property values.
| 471 The value of the fulfillment-state property for the storage group with the
| object-id {storage-group-id} is "checking-migration".
| 475 The max-partitions field value is less than the number of partitions to which
| this storage group is currently attached, or the shared property is false when
| the number of partitions to which the partition is attached is more than one.
| 490 The storage group’s type property value is "fc" and an element of the
| storage-volumes field would put the storage volume into a state where its
| model, size and cylinders property values conflict.
| 491 An error occurred when sending the email. This failure applies only to the
| sending of the email. If this reason code is returned, the storage group will
| have been modified.
| 494 The size or cylinders field value is less than the storage volume's current
| size or cylinders, or the model field value represents a size that is smaller
| than that of the current model.
| 495 The operation would result in conflicting values for the direct-connection-
| count and shared property values.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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.

442 HMC Web Services API

 Level 04a

| Example HTTP interaction

|

POST /api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/operations/modify HTTP/1.1

x-api-session: 55q0cufbqgz03k1s2bmz98nxnx2ozf4e4sqzygw7q50st3zfqe
content-type: application/json
content-length: 351
{
"description":"A sample FCON storage group",
"storage-volumes":[
{
"description":"A Model 3 FICON data volume",
"model":"3",
"operation":"create"
},
{
"description":"A Model 1 FICON boot volume",
"element-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/
storage-volumes/ec738d80-9689-11e8-aa30-fa163e27d492",
"operation":"modify"
}
]
}

Figure 236. Modify Storage Group Properties: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Aug 2018 19:27:45 GMT
content-type: application/json;charset=UTF-8
content-length: 130
{
"element-uris":[
"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
22de1d40-968a-11e8-a0a5-fa163e27d492"
]
}

Figure 237. Modify Storage Group Properties: Response

| Add Candidate Adapter Ports to an FCP Storage Group

| The Add Candidate Adapter Ports to an FCP Storage Group operation adds a list of storage adapter
| ports to a storage group's candidate adapter ports list.

| HTTP method and URI

| POST /api/storage-groups/{storage-group-id}/operations/add-candidate-adapter-ports

| In this request, the URI variable {storage-group-id} is the object ID of the storage group to which the
| candidate adapter ports are to be added.

Chapter 10. Dynamic Partition Manager (DPM) 443

 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
| adapter-port-uris Array of Required A list of the adapter ports that are to be added to the
| String/URI storage group's candidate adapter ports list. Each element
| in this array is an instance of the canonical URI path of a
| storage adapter port.
|

| Description

| This operation adds a list of storage adapter ports to a storage group’s candidate adapter ports list. These
| adapter ports become candidates for use as backing adapters when creating virtual storage resources
| when the group is attached to a partition. The adapter ports should have connectivity to the Storage Area
| Network (SAN). This operation only applies to storage groups of type "fcp". Change notification for the
| storage group’s candidate-adapter-port-uris property is emitted asynchronously to this operation.

| Candidate adapter port may only be added before the CPC discovers a working communications path,
| indicated by a "validated" status on at least one of the parent storage group’s WWPNs. After that point
| all adapter ports in the group are automatically detected and manually adding them is no longer
| possible.

| If the API user does not have action/task permission to the Configure Storage – System Programmer
| task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID
| {storage-group-id} does not identify a storage group to which the API user has object-access permission,
| or if an element of the adapter-port-uris array does not identify a storage adapter object to which the API
| user has object-access permission, or if the storage group identified by the object ID {storage-group-id} is
| not of type "fcp".

| If any adapter port in the adapter-port-uris list is currently a member of the storage group’s candidate
| adapter ports list, or if at least one WWPN in the group has been discovered, a 409 (Conflict) status code
| is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because an
| adapter referenced in the adapter-port-uris array is not a FICON adapter.

| If the request body contents are valid, the adapter port URIs in the adapter-port-uris list are added to the
| storage group's candidate adapter ports list.

| Authorization requirements

| This operation has the following authorization requirement:

| v Object-access permission to the storage group whose object-id is {storage-group-id}.
| v Object-access permission to each adapter containing the ports identified in the adapter-port-uris array.
| v Action/task permission to the Configure Storage – System Programmer 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, and the response body is a
| standard error response body providing the reason code indicated and the associated error message.

444 HMC Web Services API

 Level 04a

| Table 206. Add Candidate Adapter Ports to an FCP Storage Group: 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 An adapter referenced in the adapter-port-uris list has an adapter-family
| property value other than "ficon".
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer task.
| 404 (Not Found) 1 A storage group with the object-id {storage-group-id} does not exist on the
| HMC or the API user does not have object-access permission for it.
| 2 An adapter containing a port referenced by a URI in the adapter-port-uris
| field does not exist on the HMC or the API user does not have object-access
| permission for it.
| 4 The storage group object with the object-id {storage-group-id} has a type
| value other than "fcp".
| 409 (Conflict) 2 The storage group object with the object-id {storage-group-id} was busy and
| the request timed out.
| 471 The status property of at least one WWPN listed in the world-wide-port-
| names property of the storage group identified by {storage-group-id} has a
| value of "validated".
| 478 A storage adapter port in the adapter-port-uris list is already a current
| member of the candidate-adapter-port-uris list of the storage group object
| with the object-id {storage-group-id}.
| 483 The adapter that contains the port referenced by an element in the
| adapter-port-uris field has a type value other than "fcp".
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/storage-groups/491e058c-998d-11e8-a345-fa163e27d492/operations/add-candidate-
adapter-ports HTTP/1.1
x-api-session: sf2z7yhhiw90fj9rqevt7z3q7up3qfp62a8lraxrstzkkqv10
content-type: application/json
content-length: 93
{
"adapter-port-uris":[
"/api/adapters/13eb6396-941f-11e8-8625-fa163e27d492/storage-ports/0"
]
}

Figure 238. Add Candidate Adapter Ports to an FCP Storage Group: Request

Chapter 10. Dynamic Partition Manager (DPM) 445

 Level 04a

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 06 Aug 2018 16:07:37 GMT

<No response body>

Figure 239. Add Candidate Adapter Ports to an FCP Storage Group: Response

| Remove Candidate Adapter Ports from an FCP Storage Group

| The Remove Candidate Adapter Ports from an FCP Storage Group operation removes a list of storage
| adapter ports from a storage group's candidate adapter ports list.

| HTTP method and URI

| POST /api/storage-groups/{storage-group-id}/operations/remove-candidate-adapter-ports

| In this request, the URI variable {storage-group-id} is the object ID of the storage group from which the
| candidate adapter port is to be removed.

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| adapter-port-uris Array of Required A list of the adapter ports that are to be removed from the
| String/URI storage group's candidate adapter ports list. Each element
| in this array is an instance of the canonical URI path of a
| storage adapter port
|

| Description

| This operation removes a list of storage adapter port from a storage group’s candidate adapter ports list.
| This operation only applies to storage groups of type "fcp". A Property Change notification for the
| storage group’s candidate-adapter-port-uris property is emitted asynchronously to this operation.

| If the API user does not have action/task permission to the Configure Storage – System Programmer
| task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID
| {storage-group-id} does not identify a storage group object to which the API user has object-access
| permission , or if an element of the adapter-port-uris array does not identify a storage adapter object to
| which the API user has object-access permission , or if the storage group identified by the object ID
| {storage-group-id} is not of type "fcp".

| If any adapter port in the adapter-port-uris list is not a current member of the storage group's candidate
| adapter ports list or is referenced by any of the group's virtual storage resources, a 409 (Conflict) status
| code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because an
| adapter referenced in the adapter-port-uris array is not a FICON adapter.

| If the request body contents are valid, the adapter port URIs in the adapter-port-uris list are removed
| from the storage group's candidate adapter ports list.

446 HMC Web Services API

 Level 04a

| Authorization requirements

| This operation has the following authorization requirement:

| v Object-access permission to the storage group whose object-id is {storage-group-id}.
| v Object-access permission to each adapter containing the ports identified in the adapter-port-uris array.
| v Action/task permission to the Configure Storage – System Programmer 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, and the response body is a
| standard error response body providing the reason code indicated and the associated error message.
| Table 207. Remove Candidate Adapter Ports from an FCP Storage Group: 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 An adapter referenced in the adapter-port-uris list has an adapter-family
| property value other than "ficon".
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer task.
| 404 (Not Found) 1 A storage group with the object-id {storage-group-id} does not exist on the
| HMC or the API user does not have object-access permission for it.
| 2 An adapter containing a port referenced by a URI in the adapter-port-uris
| field does not exist on the HMC or the API user does not have object-access
| permission for it.
| 4 The storage group object with the object-id {storage-group-id} has a type
| value other than "fcp".
| 409 (Conflict) 2 The storage group object with the object-id {storage-group-id} was busy and
| the request timed out.
| 479 A storage adapter port in the adapter-port-uris list is not a current member
| of the candidate-adapter-port-uris list of the storage group object with the
| object-id {storage-group-id}.
| 482 A storage adapter port in the adapter-port-uris list is referenced by at least
| one element of the virtual-storage-resource-uris in the storage group object
| with the object-id {storage-group-id}.
| 488 A storage adapter port referenced in the adapter-port-uris field has been
| assigned to a storage volume in the storage group object with the object-id
| {storage-group-id}.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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) 447

 Level 04a

| Example HTTP interaction

|

POST /api/storage-groups/491e058c-998d-11e8-a345-fa163e27d492/operations/remove-
candidate-adapter-ports HTTP/1.1
x-api-session: 4xtwzjxbhelnpvnnl0atkg5ut7cg6rqqnldcvvskvnj3zu8ubz
content-type: application/json
content-length: 93
{
"adapter-port-uris":[
"/api/adapters/13eb6396-941f-11e8-8625-fa163e27d492/storage-ports/0"
]
}

Figure 240. Remove Candidate Adapter Ports from an FCP Storage Group: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 06 Aug 2018 16:07:37 GMT

<No response body>

Figure 241. Remove Candidate Adapter Ports from an FCP Storage Group: Response

| List Storage Volumes of a Storage Group

| The List Storage Volumes of a Storage Group operation lists the storage volumes of the storage group
| with the given identifier.

| HTTP method and URI

| GET /api/storage-groups/{storage-group-id}/storage-volumes

| In this request, the URI variable {storage-group-id} is the object-id of the Storage Group object.

| 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.
| fulfillment-state String Optional Filter string to limit returned objects to those that have a matching
| Enum fulfillment-state property.

| Value must be a valid storage volume fulfillment-state property

| value.
| maximum-size Integer Optional Filter value to limit returned object to those that have a size property
| that is less than or equal to maximum-size.
| minimum-size Integer Optional Filter value to limit returned object to those that have a size property
| that is greater than or equal to minimum-size.
| usage String Required Filter string to limit returned objects to those that have a matching
| Enum usage property.

| Value must be a valid storage volume usage property value.

|

448 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
| storage-volumes Array of Array of storage-volume-response-info nested objects, described in the
| storage- next table. The returned array may be empty.
| volume-
| response-
| info
| objects
|

| Each nested storage-volume-response-info object contains the following fields:

|| Field name Type Description
| element-uri String/ Canonical URI path (element-uri) of the Storage Volume element object.
| URI
| name String The name property of the storage volume element.
| fulfillment-state String The fulfillment-state property of the storage volume element.
| Enum
| size Integer The size property of the storage volume element.
| usage String The usage property of the storage volume element.
| Enum
|

| Description

| This operation lists the storage volumes that are owned by the identified storage group. The element URI,
| name, fulfillment state, size and usage are provided for each.

| If the object ID {storage-group-id} does not identify a storage group object to which the API user has
| object-access permission, a 404 (Not Found) status code is returned

| If the name query parameter is specified, the returned list is limited to those storage volumes that have a
| name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
| done.

| If the fulfillment-state or usage query parameter is specified, each parameter is validated to ensure it is a
| valid value for the storage volume fulfillment-state or usage property according to the data model. If the
| value is not valid, a 400 (Bad Request) is returned. If the value is valid, the returned list is limited to
| those storage volumes that have a fulfillment-state or type property matching the specified value. If the
| fulfillment-state or type parameter is omitted, this filtering is not done for that property name.

| If the minimum-size query parameter is specified, the returned list is limited to those storage volumes
| that have a size parameter that is greater than or equal to the specified value. If the maximum-size query
| parameter is specified, the returned list is limited to those storage volumes that have a size parameter
| that is less than or equal to the specified value. When specified together, the minimum-size and
| maximum-size query parameters define a size range on which the volume is filtered. If either of these
| query parameters are omitted, the size filter is not bounded on one end. If both of these query
| parameters are omitted, no filtering on the size property is done.

| If no storage volumes are to be included in the results due to filtering, an empty list is provided and the
| operation completes successfully.

Chapter 10. Dynamic Partition Manager (DPM) 449

 Level 04a

| Authorization requirements

| This operation has the following authorization requirement:

| v Object access permission to the storage group whose object-id is {storage-group-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” on page 449.

| 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 any associated error message.
| Table 208. List Storage Volumes of a Storage Group: 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.
| 14 A query parameter defines an invalid value.
| 404 (Not Found) 1 The storage group with the object ID {storage-group-id} does not exist on the
| HMC or the API user does not have object-access permission for 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/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes HTTP/1.1

| x-api-session: 3xx8y87o2ajorslkb17weulfnyheic1l87kqvdksngigr1e1r8
|
|
| Figure 242. List Storage Volumes of a Storage Group: Request

450 HMC Web Services API

 Level 04a

| 200 OK
| server: Hardware management console API web server / 2.0
| cache-control: no-cache
| date: Thu, 02 Aug 2018 19:34:09 GMT
| content-type: application/json;charset=UTF-8
| content-length: 1279
| {
| "storage-volumes":[
| {
| "element-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/
| storage-volumes/704a5e40-968a-11e8-a0a5-fa163e27d492",
| "fulfillment-state":"complete",
| "name":"Alias",
| "size":0.0,
| "usage":"not-applicable"
| },
| {
| "element-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/
| storage-volumes/70322410-968a-11e8-a0a5-fa163e27d492",
| "fulfillment-state":"complete",
| "name":"Alias",
| "size":0.0,
| "usage":"not-applicable"
| },
| {
| "element-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/
| storage-volumes/705620b8-968a-11e8-a0a5-fa163e27d492",
| "fulfillment-state":"complete",
| "name":"Alias",
| "size":0.0,
| "usage":"not-applicable"
| },
| {
| "element-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/
| storage-volumes/ec738d80-9689-11e8-aa30-fa163e27d492",
| "fulfillment-state":"complete",
| "name":"0.88 GiB Boot",
| "size":0.88,
| "usage":"boot"
| },
| {
| "element-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/
| storage-volumes/22de1d40-968a-11e8-a0a5-fa163e27d492",
| "fulfillment-state":"complete",
| "name":"2.64 GiB Data",
| "size":2.64,
| "usage":"data"
| },
| {
| "element-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/
| storage-volumes/703e39c6-968a-11e8-a0a5-fa163e27d492",
| "fulfillment-state":"complete",
| "name":"Alias",
| "size":0.0,
| "usage":"not-applicable"
| }
| ]
| }
|
|
| Figure 243. List Storage Volumes of a Storage Group: Response

| Get Storage Volume Properties

| The Get Storage Volume Properties operation retrieves the properties of a single Storage Volume element
| object.
Chapter 10. Dynamic Partition Manager (DPM) 451
 Level 04a

| HTTP method and URI

| GET /api/storage-groups/{storage-group-id}/storage-volumes/{storage-volume-id}

| In this request, the URI variable {storage-group-id} is the object ID of the Storage Group object and the URI
| variable {storage-volume-id} is the element ID of the Storage Volume element object.

| Response body contents

| On successful completion, the response body is a JSON object that provides the current values of the
| properties for the Storage Volume object as defined in the “Data model” on page 411. 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

| Returns the current values of the properties for the storage volume object as defined in the “Storage
| Volume element object” on page 416.

| A 404 (Not Found) status code is returned if the object ID {storage-group-id} does not identify a storage
| group object to which the API user has object-access permission or if the element ID {storage-volume-id}
| does not identify a storage volume in the storage group.

| Authorization requirements

| This operation has the following authorization requirement:

| v Object access permission to the storage group whose object-id is {storage-group-id}.

| HTTP status and reason codes

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

| Otherwise, 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 209. Get Storage Volume 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.
| 404 (Not Found) 1 A storage group with object-id {storage-group-id} does not exist on the HMC
| or the API user does not have object-access permission to it.
| 5 A storage volume with element-id {storage-volume-id} does not exist in the
| storage group on the HMC.
|

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

452 HMC Web Services API

 Level 04a

| Example HTTP interaction

|

GET /api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/
ec738d80-9689-11e8-aa30-fa163e27d492 HTTP/1.1
x-api-session: q2luwppbrz15mdoup5h5lup1gw6idjofrjkxe6mo8oxx3722i

Figure 244. Get Storage Volume Properties: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Aug 2018 19:36:08 GMT
content-type: application/json;charset=UTF-8
content-length: 630
{
"active-model":"1",
"active-size":0.88,
"class":"storage-volume",
"control-unit-uri":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492",
"cylinders":1113,
"description":"A Model 1 FICON boot volume",
"device-number":null,
"eckd-type":"base",
"element-id":"ec738d80-9689-11e8-aa30-fa163e27d492",
"element-uri":"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/
storage-volumes/ec738d80-9689-11e8-aa30-fa163e27d492",
"fulfillment-state":"complete",
"model":"1",
"name":"0.88 GiB Boot",
"parent-storage-group-uris":[
"/api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492"
],
"size":0.88,
"unit-address":"00",
"usage":"boot"
}

Figure 245. Get Storage Volume Properties: Response

| Fulfill FICON Storage Volume

| The Fulfill FICON Storage Volume operation maps the ECKD storage resource that has been configured
| by a SAN administrator to a storage volume that is part of a request for new or modified FICON storage.

| HTTP method and URI

| POST /api/storage-groups/{storage-group-id}/storage-volumes/{storage-volume-id}/operations/
| fulfill-ficon-storage-volume

| In this request, the URI variable {storage-group-id} is the object ID of the Storage Group object and the URI
| variable {storage-volume-id} is the element ID of the storage volume element.

| Request body contents

|| Field name Type Rqd/Opt Description
| control-unit-uri String/URI Required The canonical URI of the storage control unit in which the
| backing ECKD volume is defined.

Chapter 10. Dynamic Partition Manager (DPM) 453

 Level 04a

| Field name Type Rqd/Opt Description

| unit-address String (2) Required A two-character lower case hexadecimal number that
| represents the unit address of the backing ECKD volume
| within the storage control unit.
|

| Description

| This operation provides information about the ECKD storage resource that has been selected by a SAN
| administrator to fulfill a base storage volume that is part of a request for new or modified FICON
| storage. Until this information is provided, the CPC does not have all the data it needs to address and
| connect to that storage resource.

| Once a FICON storage volume has been fulfilled, the storage control unit and unit that has been assigned
| to it cannot be changed. If the size, cylinders or model properties of a volume are modified, the
| fulfillment-state of the volume is changed to "pending", indicating that action may be necessary by the
| storage administrator to adjust the size of the backing ECKD volume. The fulfillment-state of the volume
| is changed back to "complete" by fulfilling the volume again with the exact same control-unit-uri and
| unit-address, indicating that the changes have been completed.

| If the API user does not have action/task permission to the Configure Storage – Storage Administrator
| task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID
| {storage-group-id} does not identify a storage group object to which the API user has object-access
| permission, or the element ID {storage-volume-id} does not identify a storage volume in the storage group,
| or the current value of the group’s type property is not "fc".

| If the storage volume’s fulfillment-state property value is not "pending", or if the CPC on which this
| storage group resource exists is not active, of if the storage group's connectivity property value does not
| equal the number of storage paths configured in the target storage control unit, a 409 (Conflict) status
| code is returned. A 409 (Conflict) status code is also returned if the identified unit address is not defined
| on the identified control unit, or if the backing ECKD volume is an alias volume or has already being
| used to fulfill another storage volume, or if the identified control unit and unit address would remap a
| previously fulfilled storage volume.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the storage volume’s fulfillment-state property is changed to
| "complete". If the fulfillment-state property values for all other storage volumes in the parent storage
| group are also "complete", the parent storage group’s fulfillment-state property will also be set to
| "complete". The storage volume’s control-unit-uri and unit-address properties are set to the same-named
| request body field values. The storage volume’s size and model property values are copied to the
| active-size and active-model properties. Change notifications for the storage volume’s fulfillment-state,
| control-unit-uri, unit-address, active-size, and active-model properties are emitted asynchronously to
| this operation. Change notification for the parent storage group’s fulfillment-state property may be also
| emitted.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object access permission to the storage group whose object-id is {storage-group-id}.
| v Action/task permission to the Configure Storage – Storage Administrator task.

| HTTP status and reason codes

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

454 HMC Web Services API

 Level 04a

| Otherwise, 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 210. Fulfill FICON Storage Volume: 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 The API user does not have action/task permission to the Configure Storage
| – Storage Administrator task.
| 404 (Not Found) 1 A storage group with the object-id {storage-group-id} does not exist on the
| HMC or the API user does not have object-access permission for it.
| 2 The storage control unit identified by control-unit-uri does not exist on the
| HMC or the API user does not have object-access permission for it.
| 4 The storage group object with the object-id {storage-group-id} has a type
| value other than "fc".
| 5 A storage volume with element-id {storage-volume-id} does not exist in the
| storage group on the HMC.
| 409 (Conflict) 1 The state of the CPC is not valid to perform the operation (must be in one of
| the following states: "active", "service-required", "degraded", or
| "exceptions").
| 2 The storage group object with the object-id {storage-group-id} was busy and
| the request timed out.
| 471 The current value of the fulfillment-state property of the storage volume
| identified by {storage-volume-id} is not "pending".
| 473 The storage volume identified by {storage-volume-id} has been previously
| fulfilled, and the values of the control-unit-uri and unit-address fields do
| not exactly match the previous values.
| 484 The unit address identified by unit-address is not a member of a volume
| group on the control unit identified by control-unit-uri.
| 485 The unit address identified by unit-address in the control unit identified by
| control-unit-uri has already been used to fulfill another FICON storage
| volume.
| 486 The unit address identified by unit-address is a member of an alias volume
| group on the control unit identified by control-unit-uri.
| 492 The connectivity property value of the storage volume identified by
| {storage-volume-id} does not equal the number of storage paths configured in
| the storage control unit identified by control-unit-uri.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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) 455

 Level 04a

| Example HTTP interaction

|

POST /api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/storage-volumes/ec738d80-
9689-11e8-aa30-fa163e27d492/operations/fulfill-ficon-storage-volume HTTP/1.1
x-api-session: 4iep1d8dyntia1rmppcfl0pmo8yghd190u1s14fu5133vevc7u
content-type: application/json
content-length: 109
{
"control-unit-uri":"/api/storage-control-units/69bf384a-94d5-11e8-8ffe-fa163e27d492",
"unit-address":"00"
}

Figure 246. Fulfill FICON Storage Volume: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Aug 2018 19:29:56 GMT

<No response body>

Figure 247. Fulfill FICON Storage Volume: Response

| Fulfill FCP Storage Volume

| The Fulfill FCP Storage Volume operation provides information about the storage resource that has been
| selected by a SAN administrator to fulfill a boot storage volume that is part of a request for new FCP
| storage.

| HTTP method and URI

| POST /api/storage-groups/{storage-group-id}/storage-volumes/{storage-volume-id}/operations/
| fulfill-fcp-storage-volume

| In this request, the URI variable {storage-group-id} is the object ID of the Storage Group object and the URI
| variable {storage-volume-id} is the element ID of the storage volume element.

| Request body contents

|| Field name Type Rqd/Opt Description
| world-wide-port- String (16) Required A 16-character lower case hexadecimal string that contains
| name the world wide port name of the FCP storage controller
| containing the SCSI boot device.
| logical-unit- String (16) Required A 16-character lower case hexadecimal string that contains
| number the logical unit number (LUN) of the SCSI boot device.
| adapter-port-uri String/ Required The canonical URI of the storage adapter port that is to be
| URI assigned to the storage volume.
|

| Description

| This operation provides information about the storage resource that has been selected by a SAN
| administrator to fulfill a storage volume that is part of a request for new FCP storage. Until this
| information is provided, the CPC does not have all the data it needs to address and connect to that
| storage resource. Only FCP boot volumes may be manually fulfilled. Other volumes will be automatically
| fulfilled when the CPC detects communication paths to them. FCP volumes may be manually fulfilled

456 HMC Web Services API

 Level 04a

| only before the CPC discovers a working communications path, indicated by a "validated" status on at
| least one of the parent storage group's WWPNs. After that point, all volumes in the group are
| automatically fulfilled and manual fulfillment is no longer possible.

| If the API user does not have action/task permission to the Configure Storage – Storage Administrator
| task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID
| {storage-group-id} does not identify a storage group object to which the API user has object-access
| permission, or the element ID {storage-volume-id} does not identify a storage volume in the group, or the
| adapter-port-uri field does not identify an adapter object to which the API user has object-access
| permission or identifies an adapter with a type value other than "fcp", or the current value of the group’s
| type property is not "fcp", or the current value of the volume’s usage property is not "boot".

| If the status property of at least one WWPN in the parent group’s world-wide-port-names property
| value is "validated", a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned.

| If the request body contents are valid, the storage volume’s fulfillment-state property is changed to
| "complete". Change notification for the storage volume’s fulfillment-state property is emitted
| asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object access permission to the storage group whose object-id is {storage-group-id}.
| v Object access permission to the adapter containing the storage adapter port identified by the
| adapter-port-uri field.
| v Action/task permission to the Configure Storage – Storage Administrator task.

| HTTP status and reason codes

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

| Otherwise, 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 211. Fulfill FCP Storage Volume: 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 The API user does not have action/task permission to the Configure Storage
| – Storage Administrator task.

Chapter 10. Dynamic Partition Manager (DPM) 457

 Level 04a

| Table 211. Fulfill FCP Storage Volume: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 404 (Not Found) 1 A storage group with the object-id {storage-group-id} does not exist on the
| HMC or the API user does not have object-access permission for it.
| 2 The adapter object containing the storage adapter port referenced in the
| adapter-port-uri field does not exist on the HMC, or the API user does not
| have object-access permission to it.
| 4 The storage group object with the object-id {storage-group-id} has a type
| value other than "fcp".
| 5 A storage volume with element-id {storage-volume-id} does not exist in the
| storage group on the HMC.
| 6 The adapter containing the storage adapter port referenced in the
| adapter-port-uri field has a type value other than "fcp".
| 442 The storage volume object with the object-id {storage-group-id} has a usage
| value other than "boot".
| 409 (Conflict) 2 The parent storage group with object-id {storage-group-id} was busy and the
| request timed out.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable communicating with the 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

|

POST /api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/storage-volumes/
2d71eeae-9fe9-11e8-b163-fa163e3c2af4/operations/fulfill-fcp-storage-volume HTTP/1.1
x-api-session: 2315cbdr840lgk09zmkpsfzwykutdinjxz1u1sxqxa0chulv2v
content-type: application/json
content-length: 177
{
"adapter-port-uri":"/api/adapters/f4f1479c-9fe7-11e8-bc9a-fa163e3c2af4/storage-ports/0",
"logical-unit-number":"93e4118a8b42c859",
"world-wide-port-name":"a1b2c3d4e5f60002"
}

Figure 248. Fulfill FCP Storage Volume: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 14 Aug 2018 18:49:28 GMT

<No response body>

Figure 249. Fulfill FCP Storage Volume: Response

| Usage notes

| It is not required to manually fulfill FCP storage volumes. If the Fulfill FCP Storage Volume request is
| not made targeting an FCP boot volume, the WWPN and LUN will be assigned algorithmically when the

458 HMC Web Services API

 Level 04a

| volume is sensed. Manual fulfillment can optionally be performed to speed up the process when the
| WWPN and LUN information is known, for example when the LUN configuration is done automatically.

| List Virtual Storage Resources of a Storage Group

| The List Virtual Storage Resources of a Storage Group operation lists the virtual storage resources of the
| storage group with the given identifier.

| HTTP method and URI

| GET /api/storage-groups/{storage-group-id}/virtual-storage-resources

| In this request, the URI variable {storage-group-id} is the object-id of the Storage Group object.

| 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.
| device-number String Optional Filter pattern (regular expression) to limit returned objects to those
| that have a matching device-number property.
| adapter-port-uri String/URI Optional Filter string to limit returned objects to those that have a matching
| adapter-port-uri property.
| partition-uri String/URI Optional Filter string to limit returned objects to those that have a matching
| partition-uri property.
|

| Response body contents

| On successful completion, the response body is a JSON object with the following fields:
|| Field name Type Description
| virtual-storage-resources Array of Array of virtual-storage-resource-info objects, described in the next table.
| virtual- The returned array may be empty.
| storage-
| resource-
| info
| objects
|

| Each nested virtual-storage-resource-info object contains the following fields:

|| Field name Type Description
| element-uri String/ The canonical URI path (element-uri) of the virtual Storage Resource
| URI element object.
| name String The name property of the virtual storage resource element.
| device-number String The device-number property of the virtual storage resource element.
| adapter-port-uri String/ The adapter-port-uri property of the virtual storage resource element.
| URI
| partition-uri String/ The partition-uri property of the virtual storage resource element.
| URI
|

Chapter 10. Dynamic Partition Manager (DPM) 459

 Level 04a

| Description

| This operation lists the virtual storage resources that are owned by the identified storage group. The
| element URI, name, device number and associated adapter port and partition are provided for each.

| If the object ID {storage-group-id} does not identify a storage group object to which the API user has
| object-access permission, or does not identity an FCP storage group,, a 404 (Not Found) status code is
| returned

| If the name or device-number query parameter is specified, the returned list is limited to those virtual
| storage resources that have a name or device-number property matching the specified filter pattern. If
| the name or device-number parameter is omitted, the filtering on the omitted property name is not done.

| If the adapter-port-uri or partition-uri query parameter is specified, the returned list is limited to those
| virtual storage resources that have a matching adapter-port-uri or partition-uri property. If the
| adapter-port-uri or partition-uri parameter is omitted, the filtering on the omitted property name is not
| done.

| If no virtual storage resources are to be included in the results due to filtering, 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 storage group whose object-id is {storage-group-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” on page 459.

| 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 any associated error message.
| Table 212. List Virtual Storage Resources of a Storage Group: 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.
| 14 A query parameter defines an invalid value.
| 404 (Not Found) 1 The storage group with the object ID {storage-group-id} does not exist on the
| HMC, or is a storage group of the wrong type, or the API user does not
| have object-access permission for it.
|

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

460 HMC Web Services API

 Level 04a

| Example HTTP interaction

|

| GET /api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/virtual-storage-resources
| HTTP/1.1
| x-api-session: 46zfjkryyht0wrf7v8fjxfmza830u42yuob8p0ct727mr2so2x
|
|
| Figure 250. List Virtual Storage Resources of a Storage Group: Request

| 200 OK
| server: Hardware management console API web server / 2.0
| cache-control: no-cache
| date: Tue, 14 Aug 2018 18:50:54 GMT
| content-type: application/json;charset=UTF-8
| content-length: 737
| {
| "virtual-storage-resources":[
| {
| "adapter-port-uri":"/api/adapters/f0f668e8-9fe7-11e8-bc9a-fa163e3c2af4/
| storage-ports/0",
| "device-number":"0000",
| "element-uri":"/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/
| virtual-storage-resources/4ca56526-9fe9-11e8-b6db-fa163e3c2af4",
| "name":"vhba_FCP Storage Group0",
| "partition-uri":"/api/partitions/4bf93d46-9fe9-11e8-b6db-fa163e3c2af4"
| },
| {
| "adapter-port-uri":"/api/adapters/f4f1479c-9fe7-11e8-bc9a-fa163e3c2af4/
| storage-ports/0",
| "device-number":"0001",
| "element-uri":"/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/
| virtual-storage-resources/4ce7feea-9fe9-11e8-b6db-fa163e3c2af4",
| "name":"vhba_FCP Storage Group1",
| "partition-uri":"/api/partitions/4bf93d46-9fe9-11e8-b6db-fa163e3c2af4"
| }
| ]
| }
|
|
| Figure 251. List Virtual Storage Resources of a Storage Group: Response

| Get Virtual Storage Resource Properties

| The Get Virtual Storage Resource Properties operation retrieves the properties of a single Virtual Storage
| Resource element object.

| HTTP method and URI

| GET /api/storage-groups/{storage-group-id}/virtual-storage-resources/{virtual-storage-resource-id}

| In this request, the URI variable {storage-group-id} is the object ID of the storage group object and the URI
| variable {virtual-storage-resource-id} is the element ID of the virtual storage resource element.

| Response body contents

| On successful completion, the response body is a JSON object that provides the current values of the
| properties for the Virtual Storage Resource object as defined in the “Data model” on page 411. Field
| names and data types in the JSON object are the same as the property names and data types defined in
| the data model.

Chapter 10. Dynamic Partition Manager (DPM) 461

 Level 04a

| Description

| Returns the current values of the properties for the virtual storage resource object as defined in “Virtual
| Storage Resource element object” on page 422.

| A 404 (Not Found) status code is returned if the object ID {storage-group-id} does not identify a storage
| group object to which the API user has object-access permission, or does not identity an FCP storage
| group, or if the element ID {virtual-storage-resource-id} does not identify a virtual storage resource in the
| storage group.

| Authorization requirements

| This operation has the following authorization requirement:

| v Object access permission to the storage group whose object-id is {storage-group-id}.

| HTTP status and reason codes

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

| Otherwise, 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 213. Get Virtual Storage Resource 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.
| 404 (Not Found) 1 A storage group with object-id {storage-group-id} does not exist on the HMC,
| or is a storage group of the wrong type, or the API user does not have
| object-access permission to it.
| 5 A virtual storage resource with element-id {virtual-storage-resource-id} does
| not exist in the storage group on the HMC.
|

| 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/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/virtual-storage-resources/
4ce7feea-9fe9-11e8-b6db-fa163e3c2af4 HTTP/1.1
x-api-session: 63naxg5mxrpmugoyatmcwn6nv5zz5lbltb1zf6ga1408yhplxi

Figure 252. Get Virtual Storage Resource Properties: Request

462 HMC Web Services API

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 14 Aug 2018 18:51:56 GMT
content-type: application/json;charset=UTF-8
content-length: 566
{
"adapter-port-uri":"/api/adapters/f4f1479c-9fe7-11e8-bc9a-fa163e3c2af4/storage-ports/
0",
"class":"virtual-storage-resource",
"description":"",
"device-number":"0001",
"element-id":"4ce7feea-9fe9-11e8-b6db-fa163e3c2af4",
"element-uri":"/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/
virtual-storage-resources/4ce7feea-9fe9-11e8-b6db-fa163e3c2af4",
"name":"vhba_FCP Storage Group1",
"parent":"/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4",
"partition-uri":"/api/partitions/4bf93d46-9fe9-11e8-b6db-fa163e3c2af4",
"world-wide-port-name":"a1b2c3d4e5f60003"
}

Figure 253. Get Virtual Storage Resource Properties: Response

| Update Virtual Storage Resource Properties

| The Update Virtual Storage Resource Properties operation updates one or more of the writable
| properties of a virtual storage resource.

| HTTP method and URI

| POST /api/storage-groups/{storage-group-id}/virtual-storage-resources/{virtual-storage-resource-id}

| In this request, the URI variable {storage-group-id} is the object ID of the storage group object and the URI
| variable {virtual-storage-resource-id} is the element ID of the virtual storage resource element.

| Request body contents

| The request body is expected to contain a JSON object that provides the new values of any writable
| property that is to be updated by this operation. Field names and data types in this JSON object are
| expected to match the corresponding property names and data types defined in the “Virtual Storage
| Resource element object” on page 422. The JSON object can and should omit fields for properties whose
| values are not to be changed by this operation.

| Description

| This operation updates a virtual storage resource's properties with the values specified.

| If the API user does not have action/task permission to the Configure Storage – System Programmer
| task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID
| {storage-group-id} does not identify a Storage Group object to which the API user has object-access
| permission, or does not identity an FCP storage group, or if the element ID {virtual-storage-resource-id}
| does not identify a Virtual Storage Resource element object in the storage group. If the CPC on which this
| virtual storage resource exists is not active, a 409 (Conflict) status code is returned.

| If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because
| the document defines a field that is not supported for the parent storage group's type or because the
| parent storage group already contains a virtual storage resource with the specified name.

Chapter 10. Dynamic Partition Manager (DPM) 463

 Level 04a

| If the request body contents are valid, the virtual storage resource's properties are updated to their
| corresponding request body content's field's values. All fields are optional and may be excluded from the
| request body; if a field is not found in the request body, its property's value will not be modified.

| If the update changes the value of any property for which property-change notifications are due, those
| notifications are emitted asynchronously to this operation.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object access permission to the storage group whose object-id is {storage-group-id}.
| v Action/task permission to the Configure Storage – System Programmer task.

| HTTP status and reason codes

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

| Otherwise, 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 214. Update Virtual Storage Resource 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.
| 8 A virtual storage resource with the name specified in the request body
| already exists within the parent storage group.
| 18 A supplied property is not valid for the virtual storage resource’s type.
| 403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage
| – System Programmer task.
| 404 (Not Found) 1 A storage group with object-id {storage-group-id} does not exist on the HMC,
| or is a storage group of the wrong type, or the API user does not have
| object-access permission to it.
| 5 A virtual storage resource with element-id {virtual-storage-resource-id} does
| not exist in the storage group on the HMC.
| 409 (Conflict) 1 The state of the CPC is not valid to perform the operation (must be in one of
| the following states: "active", "service-required", "degraded", or
| "exceptions").
| 2 The parent storage group with object-id {storage-group-id} was busy and the
| request timed out.
| 505 (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.

464 HMC Web Services API

 Level 04a

| Example HTTP interaction

|

POST /api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/virtual-storage-resources/
4ce7feea-9fe9-11e8-b6db-fa163e3c2af4 HTTP/1.1
x-api-session: 3f4ojo8469608kk498sr9e96l05yrsyapyheb1icwn355ws0pd
content-type: application/json
content-length: 44
{
"description":"vHBA in FCP Storage Group"
}

Figure 254. Update Virtual Storage Resource Properties: Request

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Tue, 14 Aug 2018 18:49:28 GMT

<No response body>

Figure 255. Update Virtual Storage Resource Properties: Response

| Get Partitions for a Storage Group

| The Get Partitions for a Storage Group operation lists the partitions to which the storage group with the
| given identifier is attached.

| HTTP method and URI

| GET /api/storage-groups/{storage-group-id}/operations/get-partitions

| In this request, the URI variable {storage-group-id} is the object-id of the Storage Group object.

| Query parameters
|| Name Type Req/Opt Description
| name String Optional Filter pattern (regular expression) to limit returned Partition
| objects to those that have a matching name property
| status String Enum Optional Optional filter string to limit returned Partition objects to those
| that have a matching status property.

| Value must be a valid partition status property value.

|

| Response body contents

| On successful completion, the response body contains a JSON object with the following fields:
|| Field name Type Description
| partitions Array of Array of partition-info objects, described in the next table. The returned
| partition-info array may be empty.
| objects
|

| Each nested partition-info object contains the following fields:

Chapter 10. Dynamic Partition Manager (DPM) 465

 Level 04a

|| Field name Type Description

| object-uri String/URI The canonical URI path (object-uri) of the partition object.
| name String The name property of the object.
| status String Enum The status property of the object.
|

| Description

| This operation lists the partitions to which the identified storage group is attached. The object URI, name
| and status are provided for each.

| If the object ID {storage-group-id} does not identify a storage group object to which the API user has
| object-access permission, a 404 (Not Found) status code is returned

| 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, this filtering is not done.

| If the status query parameter is specified, the parameter is validated to ensure it is a valid value for the
| status property according to the partition data model. If the value is not valid, a 400 (Bad Request) is
| returned. If the value is valid, the returned list is limited to those partitions that have the specified status
| value. If the status parameter is omitted, this filtering is not done.

| A partition is included in the list only if the user has object access permission to it. If no partitions are to
| be included in the results due to filtering or lack of permission, 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 storage group whose object-id is {storage-group-id}.

| HTTP status and reason codes

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

| Otherwise, 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 215. Get Partitions for a Storage Group: 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.
| 14 A query parameter defines an invalid value.
| 404 (Not Found) 1 A storage group with object-id {storage-group-id} does not exist on the HMC
| 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.

466 HMC Web Services API

 Level 04a

| Example HTTP interaction

|

GET /api/storage-groups/ec638c1e-9689-11e8-aa30-fa163e27d492/operations/get-partitions
HTTP/1.1
x-api-session: 40xd7zji2d7manim658hz4ot8r7x7fp3xuk0nyuced9psqubc8

Figure 256. Get Partitions for a Storage Group: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 06 Aug 2018 15:53:46 GMT
content-type: application/json;charset=UTF-8
content-length: 235
{
"partitions":[
{
"name":"Partition 2",
"object-uri":"/api/partitions/8d1ca9a0-998d-11e8-8352-fa163e27d492",
"status":"active"
},
{
"name":"Partition 1",
"object-uri":"/api/partitions/72a0f8b0-998d-11e8-8352-fa163e27d492",
"status":"stopped"
}
]
}

Figure 257. Get Partitions for a Storage Group: Response

| Validate LUN Path

| The Validate LUN Path operation verifies if a LUN is reachable along the path specified. The path is
| specified by the host world wide port name, adapter port, target world wide port name, and the LUN to
| indicate the connections from the CPC to the Storage Subsystem.

| HTTP method and URI

| POST /api/cpcs/{cpc-id}/operations/validate-lun-path

| In this request, the URI variable {cpc-id} is the object ID of the CPC that contains the host world wide
| port name and the adapters.

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| host-world-wide- String (16) Required A 16-character lower-case hexadecimal string that contains
| port-name a WWPN that uniquely identifies a host or initiator device
| in the SAN.
| adapter-port-uri String/ Required The canonical URI path of the Storage Port element object
| URI to be used to validate the LUN configuration.
| target-world-wide- String (16) Required A 16-character lower-case hexadecimal string that contains
| port-name a WWPN that uniquely identifies a target port in one of
| the storage subsystems connected to this CPC.

Chapter 10. Dynamic Partition Manager (DPM) 467

 Level 04a

| Field name Type Rqd/Opt Description

| logical-unit- String Required The lower-case hexadecimal logical unit number (LUN)
| number (1-16) representing the storage device configured in the storage
| controller.
|

| Description

| This operation verifies if a LUN identified by logical-unit-number configured for the

| host-world-wide-port-name through the storage port designated by adapter-port-uri and the target port
| designated by target-world-wide-port-name.

| The adapter-port-uri field in the request body must designate an existing Storage Port of an existing
| adapter, and the API user must have object-access permission to that adapter. If not, 404 (Not Found)
| status code is returned

| If the adapter-port-uri does not designate an existing Storage Port of an existing adapter of type "fcp", a
| 409 (Conflict) status code is returned.

| \If the storage controller does not configure the specified target-world-wide-port-name for the given
| combination of host-world-wide-port-name and adapter-port-uri, a 409 (Conflict) status is returned.

| If the storage controller does not configure the specified logical-unit-number for the given combination
| of host-world-wide-port-name, adapter-port-uri and target-world-wide-port-name, a 409 (Conflict) status
| code is returned.

| If the CPC does not have "dpm-storage-management" feature enabled, a 409 (Conflict) status is returned.

| 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 the adapter containing the port designated by the adapter-port-uri field.
| v Action/task permission to the Configure Storage – System Programmer 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, and the response body is a
| standard error response body providing the reason code indicated and the associated error message.
| Table 216. Validate LUN Path: 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.
| 404 (Not Found) 2 The storage port designated by the adapter-port-uri does not exist on the
| HMC or the API user does not have object-access permission for the adapter
| containing the storage port.

468 HMC Web Services API

 Level 04a

| Table 216. Validate LUN Path: HTTP status and reason codes (continued)
| HTTP error status Reason
| code code Description
| 409 (Conflict) 13 The operation is not supported when the "dpm-storage-management"
| feature is not enabled on the CPC.
| 483 The adapter designated by the adapter-port-uri is not of type "fcp".
| 484 A configuration for the target-world-wide-port-name does not exist in the
| storage controller for the given host-world-wide-port-name and
| adapter-port-uri combination.
| 485 A configuration for thelogical-unit-number does not exist in the storage
| controller for the given host-world-wide-port-name, adapter-port-uri and
| target-world-wide-port-name combination.
| 503 (Service 1 The request could not be processed because the HMC is not currently
| Unavailable) communicating with the 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

|

POST /api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e/operations/validate-lun-path
Request Headers : {
content-type:application/json,
x-api-session:p5e86fr0btfsspy95sal06vkfp4cbkj4tjq27qmlr3fcx71dd
content-length:233,
{
"adapter-port-uri":"/api/adapters/df4d482e-ce2c-11e7-bca6-00106f0d81cb/
storage-ports/0",
"host-world-wide-port-name":"C05076FFE8000002",
"logical-unit-number":"4013402F00000000",
"target-world-wide-port-name":"C05076FFE8001001"
}

Figure 258. Validate LUN Path: Request

204 No Content
cache-control: no-cache,
date:Mon, 30 Jul 2018 17:32:40 GMT,
server:Hardware management console API web server / 2.0,
x-request-id:Sxb597d98c-8bef-11e8-8db3-00106f0d8409.1fca Rxc,
x-wsa-provider-duration-ms:934

<No response body>

Figure 259. Validate LUN Path: Response

| Inventory service data

| Information about the Storage Groups managed by the HMC can be optionally included in the inventory
| data provided by the Inventory Service.

| Inventory entries for storage group objects are included in the response to the Inventory Service's Get
| Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or

Chapter 10. Dynamic Partition Manager (DPM) 469

 Level 04a

| by default) that objects of class "storage-group" are to be included. Information for a particular storage
| group is included only if the API user has object-access permission to that object.

| For each storage group to be included, the inventory response array includes the following:
| v An array entry for the storage group object itself. This entry is a JSON object with the same contents as
| is specified in the Response body contents section for “Get Storage Group Properties” on page 433.
| That is, the data provided is the same as would be provided if a Get Storage Group Properties
| operation were requested targeting this object.
| v An array entry for each storage volume element associated with the storage group. For each such
| storage volume, an entry is included that is a JSON object with the same contents as is specified in the
| Response body contents section for “Get Storage Volume Properties” on page 451.
| v An array entry for each virtual storage resource element associated with the storage group. For each
| such virtual storage resource, an entry is included that is a JSON object with the same contents as is
| specified in the Response body contents section for “Get Virtual Storage Resource Properties” on page
| 461.

| Sample inventory data

| The following fragment is an example of the JSON objects that would be included in the Get Inventory
| response to describe a storage group. These objects would appear as multiple array entries in the
| response array:
|

470 HMC Web Services API

 Level 04a

| {
| "active-connectivity":null,
| "active-max-partitions":null,
| "candidate-adapter-port-uris":[
| "/api/adapters/f0f668e8-9fe7-11e8-bc9a-fa163e3c2af4/storage-ports/0",
| "/api/adapters/f4f1479c-9fe7-11e8-bc9a-fa163e3c2af4/storage-ports/0"
| ],
| "class":"storage-group",
| "connectivity":2,
| "cpc-uri":"/api/cpcs/3aadfe48-128c-3766-8f51-37738f784591",
| "description":"",
| "direct-connection-count":0,
| "fulfillment-state":"pending",
| "max-partitions":2,
| "name":"FCP Group",
| "object-id":"2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4",
| "object-uri":"/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4",
| "parent":"/api/console",
| "shared":true,
| "storage-volume-uris":[
| "/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/storage-volumes/
| 2d6355ba-9fe9-11e8-b163-fa163e3c2af4",
| "/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/storage-volumes/
| 2d71eeae-9fe9-11e8-b163-fa163e3c2af4"
| ],
| "type":"fcp",
| "unassigned-world-wide-port-names":[
| {
| "status":"not-validated",
| "world-wide-port-name":"a1b2c3d4e5f60006"
| },
| {
| "status":"not-validated",
| "world-wide-port-name":"a1b2c3d4e5f60005"
| }
| ],
| "virtual-storage-resource-uris":[
| "/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/virtual-storage-resources/
| 4ca56526-9fe9-11e8-b6db-fa163e3c2af4",
| "/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/virtual-storage-resources/
| 4ce7feea-9fe9-11e8-b6db-fa163e3c2af4"
| ]
| },
| {
| "active-size":null,
| "class":"storage-volume",
| "description":"",
| "element-id":"2d6355ba-9fe9-11e8-b163-fa163e3c2af4",
| "element-uri":"/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/
| storage-volumes/2d6355ba-9fe9-11e8-b163-fa163e3c2af4",
| "fulfillment-state":"pending",
| "name":"1.00 GiB Boot",
| "parent-storage-group-uris":[
| "/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4"
| ],
| "size":1.0,
| "usage":"boot",
| "uuid":"a1b2c3d4e5f6000325d4677ab2320e54"
| },
|
|
| Figure 260. Storage Group object: Sample inventory data - Response (Part 1)

Chapter 10. Dynamic Partition Manager (DPM) 471

 Level 04a

472 HMC Web Services API

 Level 04a

| {
| "adapter-port-uri":"/api/adapters/f0f668e8-9fe7-11e8-bc9a-fa163e3c2af4/storage-ports/0",
| "class":"virtual-storage-resource",
| "description":"",
| "device-number":"0000",
| "element-id":"4ca56526-9fe9-11e8-b6db-fa163e3c2af4",
| "element-uri":"/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4/virtual-storage-
| resources/4ca56526-9fe9-11e8-b6db-fa163e3c2af4",
| "name":"vhba_FCP Group0",
| "parent":"/api/storage-groups/2cbc7c2c-9fe9-11e8-b163-fa163e3c2af4",
| "partition-uri":"/api/partitions/4bf93d46-9fe9-11e8-b6db-fa163e3c2af4",
| "world-wide-port-name":"a1b2c3d4e5f60002"
| }
|
| Figure 261. Storage Group object: Sample inventory data - Response (Part 2)
|
|

Chapter 11. Core IBM Z resources

These APIs provide access to and control of the following Z and LinuxONE HMC/SE objects:
v Console
v Group
v CPC
v Logical Partition

In addition, these APIs provide access to the following CPC-related data items:
v Reset Activation Profiles
v Image Activation Profiles
v Load Activation Profiles
v Group Profiles
v Capacity Records

Operations Summary
Following are the operations summaries for each of the core Z and LinuxONE objects.

Console operations summary

The following table provides an overview of the operations provided for Console objects.
Table 217. Core Z resources - Console: operations summary
Operation name HTTP method and URI path
“Get Console Properties” GET /api/console
on page 488
“Restart Console” on page POST /api/console/operations/restart
492
“Make Console Primary” POST /api/console/operations/make-primary
on page 494
“Shutdown Console” on POST /api/console/operations/shutdown
page 495
“Reorder User Patterns” on POST /api/console/operations/reorder-user-patterns
page 496

© Copyright IBM Corp. 2017, 2018 473

 Level 04a

Table 217. Core Z resources - Console: operations summary (continued)

Operation name HTTP method and URI path
“Get Console Audit Log” GET /api/console/operations/get-audit-log
on page 498
“Get Console Security GET /api/console/operations/get-security-log
Log” on page 501
“List Console Hardware GET /api/console/hardware-messages
Messages” on page 505
“Get Console Hardware GET /api/console/hardware-messages/{hardware-message-id}
Message Properties” on
page 507
“Delete Console Hardware DELETE /api/console/hardware-messages/{hardware-message-id}
Message” on page 509
“List Unmanaged CPCs” GET /api/console/operations/list-unmanaged-cpcs
on page 510
“List Unmanaged zBX GET /api/console/operations/list-unmanaged-zbxs
Nodes” on page 512
“Get Mobile App GET /api/console/operations/get-mobile-app-preferences
Preferences” on page 514
“Set Mobile App POST /api/console/operations/set-mobile-app-preferences
Preferences” on page 516
“Get CPC Notification POST /api/console/operations/get-device-cpc-notification-preferences
Preferences for Device” on
page 517
“Update CPC Notification POST /api/console/operations/update-device-cpc-notification-preferences
Preferences for Device” on
page 521

Table 218. Core Z resources - Console: URI variables

URI variable Description
{hardware-message-id} Element ID of the hardware message object

User operations summary

The following table provides an overview of the operations provided for User objects.
Table 219. Core Z resources - User: operations summary
Operation name HTTP method and URI path
“List Users” on page 535 GET /api/console/users
“Get User Properties” on GET /api/users/{user-id}
page 537
“Update User Properties” POST /api/users/{user-id}
on page 539
“Add User Role to User” POST /api/users/{user-id}/operations/add-user-role
on page 542
“Remove User Role from POST /api/users/{user-id}/operations/remove-user-role
User” on page 544
“Create User” on page 546 POST /api/console/users
“Delete User” on page 549 DELETE /api/users/{user-id}

474 HMC Web Services API

 Level 04a

Table 220. Core Z resources - User: URI variables

URI variable Description
{user-id} Object ID of the User object

User Role operations summary

The following table provides an overview of the operations provided for User Role objects.
Table 221. Core Z resources - User Role: operations summary
Operation name HTTP method and URI path
“List User Roles” on page GET /api/console/user-roles
555
“Get User Role Properties” GET /api/user-roles/{user-role-id}
on page 558
“Update User Role POST /api/user-roles/{user-role-id}
Properties” on page 560
“Add Permission to User POST /api/user-roles/{user-role-id}/operations/add-permission
Role” on page 562
“Remove Permission from POST /api/user-roles/{user-role-id}/operations/remove-permission
User Role” on page 565
“Create User Role” on POST /api/console/user-roles
page 567
“Delete User Role” on DELETE /api/user-roles/{user-role-id}
page 569

Table 222. Core Z resources - User Role: URI variables

URI variable Description
{user-role-id} Object ID of the User Role object

Task operations summary

The following table provides an overview of the operations provided for Task objects.
Table 223. Core Z resources - Task: operations summary
Operation name HTTP method and URI path
“List Tasks” on page 573 GET /api/console/tasks
“Get Task Properties” on GET /api/console/tasks/{task-id}
page 574

Table 224. Core Z resources - Task: URI variables

URI variable Description
{task-id} Element ID of the Task object

Chapter 11. Core IBM Z resources 475

 Level 04a

User Pattern operations summary

The following table provides an overview of the operations provided for User Pattern objects.
Table 225. Core Z resources - User Pattern: operations summary
Operation name HTTP method and URI path
“List User Patterns” on GET /api/console/user-patterns
page 578
“Get User Pattern GET /api/console/user-patterns/{user-pattern-id}
Properties” on page 580
“Update User Pattern POST /api/console/user-patterns/{user-pattern-id}
Properties” on page 582
“Create User Pattern” on POST /api/console/user-patterns
page 584
“Delete User Pattern” on DELETE /api/console/user-patterns/{user-pattern-id}
page 586

Table 226. Core Z resources - User Pattern: URI variables

URI variable Description
{user-pattern-id} Element ID of the User Pattern object

Password Rule operations summary

The following table provides an overview of the operations provided for Password Rule objects.
Table 227. Core Z resources - Password Rule: operations summary
Operation name HTTP method and URI path
“List Password Rules” on GET /api/console/password-rules
page 591
“Get Password Rule GET /api/console/password-rules/{password-rule-id}
Properties” on page 593
“Update Password Rule POST /api/console/password-rules/{password-rule-id}
Properties” on page 595
“Create Password Rule” on POST /api/console/password-rules
page 597
“Delete Password Rule” on DELETE /api/console/password-rules/{password-rule-id}
page 599

Table 228. Core Z resources - Password Rule: URI variables

URI variable Description
{password-rule-id} Element ID of the Password Rule object

LDAP Server Definition operations summary

The following table provides an overview of the operations provided for LDAP Server Definition objects.
Table 229. Core Z resources - LDAP Server Definition: operations summary
Operation name HTTP method and URI path
“List LDAP Server GET /api/console/ldap-server-definitions
Definitions” on page 605

476 HMC Web Services API

 Level 04a

Table 229. Core Z resources - LDAP Server Definition: operations summary (continued)
Operation name HTTP method and URI path
“Get LDAP Server GET /api/console/ldap-server-definitions/{ldap-server-definition-id}
Definition Properties” on
page 607
“Update LDAP Server POST /api/console/ldap-server-definitions/{ldap-server-definition-id}
Definition Properties” on
page 609
“Create LDAP Server POST /api/console/ldap-server-definitions
Definition” on page 611
“Delete LDAP Server DELETE /api/console/ldap-server-definitions/{ldap-server-definition-id}
Definition” on page 613

Table 230. Core Z resources - LDAP Server Definition: URI variables

URI variable Description
{ldap-server-definition-id} Element ID of the LDAP Server Definition object

Group operations summary

The following table provides an overview of the operations provided for Group objects.
Table 231. Core Z resources - Group: operations summary
Operation name HTTP method and URI path
“List Custom Groups” on GET /api/groups
page 617
“Get Custom Group GET /api/groups/{group-id}
Properties” on page 619
“Create Custom Group” on POST /api/groups
page 620
“Delete Custom Group” on DELETE /api/groups/{group-id}
page 622
“List Custom Group GET /api/groups/{group-id}/members
Members” on page 627
“Add Member to Custom POST /api/groups/{group-id}/operations/add-member
Group” on page 623
“Remove Member from POST /api/groups/{group-id}/operations/remove-member
Custom Group” on page
625

Table 232. Core Z resources - Groups: URI variables

URI variable Description
{group-id} Object ID of a Group object

Chapter 11. Core IBM Z resources 477

 Level 04a

CPC operations summary

The following tables provide an overview of the operations provided for CPC objects.
Table 233. Core Z resources - CPC: operations summary
Operation name HTTP method and URI path
“List CPC Objects” on GET /api/cpcs
page 644
“List Ensemble CPC GET /api/ensembles/{ensemble-id}/cpcs
Objects” on page 646
“Get CPC Properties” on GET /api/cpcs/{cpc-id}
page 648
“Update CPC Properties” POST /api/cpcs/{cpc-id}
on page 656
“Start CPC” on page 657 POST /api/cpcs/{cpc-id}/operations/start
“Stop CPC” on page 660 POST /api/cpcs/{cpc-id}/operations/stop
“Activate CPC” on page POST /api/cpcs/{cpc-id}/operations/activate
662
“Deactivate CPC” on page POST /api/cpcs/{cpc-id}/operations/deactivate
664
“Import Profiles” on page POST /api/cpcs/{cpc-id}/operations/import-profiles
666
“Export Profiles” on page POST /api/cpcs/{cpc-id}/operations/export-profiles
668
“Set Auto-Start List” on POST /api/cpcs/{cpc-id}/operations/set-auto-start-list
page 669
“Add Temporary POST /api/cpcs/{cpc-id}/operations/add-temp-capacity
Capacity” on page 671
“Remove Temporary POST /api/cpcs/{cpc-id}/operations/remove-temp-capacity
Capacity” on page 673
“Swap Current Time POST /api/cpcs/{cpc-id}/operations/swap-cts
Server” on page 675
“Set STP Configuration” POST /api/cpcs/{cpc-id}/operations/set-stp-config
on page 676
“Change STP-only POST /api/cpcs/{cpc-id}/operations/change-stponly-ctn
Coordinated Timing
Network” on page 678
“Join STP-only POST /api/cpcs/{cpc-id}/operations/join-stponly-ctn
Coordinated Timing
Network” on page 680
“Leave STP-only POST /api/cpcs/{cpc-id}/operations/leave-stponly-ctn
Coordinated Timing
Network” on page 681
“Get CPC Audit Log” on GET /api/cpcs/{cpc-id}/operations/get-audit-log
page 682
“Get CPC Security Log” on GET /api/cpcs/{cpc-id}/operations/get-security-log
page 684
“List CPC Hardware GET /api/cpcs/{cpc-id}/hardware-messages
Messages” on page 687

478 HMC Web Services API

 Level 04a

Table 233. Core Z resources - CPC: operations summary (continued)

Operation name HTTP method and URI path
“Get CPC Hardware GET /api/cpcs/{cpc-id}/hardware-messages/{hardware-message-id}
Message Properties” on
page 689
“Delete CPC Hardware DELETE /api/cpcs/{cpc-id}/hardware-messages/{hardware-message-id}
Message” on page 691
“Export WWPN List” on POST /api/cpcs/{cpc-id}/operations/export-port-names-list
page 693
| “Import DPM POST /api/cpcs/{cpc-id}/operations/import-dpm-config
| Configuration” on page
| 695

Table 234. Core Z resources - CPC: URI variables

URI variable Description
{cpc-id} Object ID of a CPC object
{ensemble-id} Object ID of an ensemble object
{hardware-message-id} Element ID of the hardware message object

Logical partition operation summary

The following tables provide an overview of the operations provided for Logical Partition objects.
Table 235. Core Z resources - Logical partitions: operations summary
Operation name HTTP method and URI path
“List Logical Partitions of GET /api/cpcs/{cpc-id}/logical-partitions
CPC” on page 720
“List Permitted Logical GET /api/console/operations/list-permitted-logical-partitions
Partitions” on page 722
“Get Logical Partition GET /api/logical-partitions/{logical-partition-id}
Properties” on page 725
“Update Logical Partition POST /api/logical-partitions/{logical-partition-id}
Properties” on page 730
“Activate Logical Partition” POST /api/logical-partitions/{logical-partition-id}/operations/activate
on page 731
“Deactivate Logical POST /api/logical-partitions/{logical-partition-id}/operations/deactivate
Partition” on page 733
“Reset Normal” on page POST /api/logical-partitions/{logical-partition-id}/operations/reset-normal
735
“Reset Clear” on page 737 POST /api/logical-partitions/{logical-partition-id}/operations/reset-clear
“Load Logical Partition” on POST /api/logical-partitions/{logical-partition-id}/operations/load
page 738
“PSW Restart” on page 741 POST /api/logical-partitions/{logical-partition-id}/operations/psw-restart
“Start Logical Partition” on POST /api/logical-partitions/{logical-partition-id}/operations/start
page 742
“Stop Logical Partition” on POST /api/logical-partitions/{logical-partition-id}/operations/stop
page 744
“Send OS Command” on POST /api/logical-partitions/{logical-partition-id}/operations/send-os-cmd
page 746

Chapter 11. Core IBM Z resources 479

 Level 04a

Table 235. Core Z resources - Logical partitions: operations summary (continued)

Operation name HTTP method and URI path
“Open OS Message POST /api/logical-partitions/{logical-partition-id}/operations/open-os-
Channel” on page 747 message-channel
“List OS Messages of a GET /api/logical-partitions/{logical-partition-id}/operations/list-os-messages
Logical Partition” on page
749
“SCSI Load” on page 752 POST /api/logical-partitions/{logical-partition-id}/operations/scsi-load
“SCSI Dump” on page 755 POST /api/logical-partitions/{logical-partition-id}/operations/scsi-dump
“List Managed Virtual GET /api/logical-partitions/{logical-partition-id}/managed-virtual-machines
Machines of a Logical
Partition” on page 757

Table 236. Core Z resources - Logical partitions: URI variables

URI variable Description
{cpc-id} Object ID of a CPC object
{logical-partition-id} Object ID of a Logical Partition object

Activation profile operations summary

The following tables provide an overview of the operations provided for the various types of Activation
Profile objects.
Table 237. Core Z resources - Reset activation profile: operations summary
Operation name HTTP method and URI path
“List Reset Activation GET /api/cpcs/{cpc-id}/reset-activation-profiles
Profiles” on page 761
“Get Reset Activation GET /api/cpcs/{cpc-id}/reset-activation-profiles/{reset-activation-profile-
Profile Properties” on page name}
763
“Update Reset Activation POST /api/cpcs/{cpc-id}/reset-activation-profiles/{reset-activation-profile-
Profile Properties” on page name}
765

Table 238. Core Z resources - Image activation profile: operations summary

Operation name HTTP method and URI path
“List Image Activation GET /api/cpcs/{cpc-id}/image-activation-profiles
Profiles” on page 786
“Get Image Activation GET /api/cpcs/{cpc-id}/image-activation-profiles/{image-activation-profile-
Profile Properties” on page name}
788
“Update Image Activation POST /api/cpcs/{cpc-id}/image-activation-profiles/{image-activation-profile-
Profile Properties” on page name}
792

Table 239. Core Z resources - Load activation profile: operations summary

Operation name HTTP method and URI path
“List Load Activation GET /api/cpcs/{cpc-id}/load-activation-profiles
Profiles” on page 796

480 HMC Web Services API

 Level 04a

Table 239. Core Z resources - Load activation profile: operations summary (continued)
Operation name HTTP method and URI path
“Get Load Activation GET /api/cpcs/{cpc-id}/load-activation-profiles/{load-activation-profile-name}
Profile Properties” on page
798
“Update Load Activation POST /api/cpcs/{cpc-id}/load-activation-profiles/{load-activation-profile-
Profile Properties” on page name}
800

Table 240. Core Z resources - Group profile: operations summary

Operation name HTTP method and URI path
“List Group Profiles” on GET /api/cpcs/{cpc-id}/group-profiles
page 804
“Get Group Profile GET /api/cpcs/{cpc-id}/group-profiles/{group-profile-name}
Properties” on page 806
“Update Group Profile POST /api/cpcs/{cpc-id}/group-profiles/{group-profile-name}
Properties” on page 808

Table 241. Core Z resources - Activation profile: URI variables

URI variable Description
{cpc-id} Object ID of a CPC object
{group-profile-name} Group profile name
{image-activation-profile- Image activation profile name
name}
{load-activation-profile-name} Load activation profile name
{reset-activation-profile-name} Reset activation profile name

Capacity record operations summary

The following tables provide an overview of the operations provided for Capacity Record objects.
Table 242. Core Z resources - Capacity record: operations summary
Operation name HTTP method and URI path
“List Capacity Records” on GET /api/cpcs/{cpc-id}/capacity-records
page 812
“Get Capacity Record GET /api/cpcs/{cpc-id}/capacity-records/{capacity-record-id}
Properties” on page 813

Table 243. Core Z resources - Capacity record: URI variables

URI variable Description
{cpc-id} Object ID of a CPC object
{capacity-record-id} Capacity record identifier

Chapter 11. Core IBM Z resources 481

 Level 04a

Shared nested objects

Some of the Core API objects share common nested objects and are documented here for ease of
reference.
Table 244. ec-mcl-description object
Field name Type Description
actions Array of An optional array of pending action objects. This field is not provided when the
action EC MCL information pertains to the HMC. When the EC MCL information
objects pertains to an SE, this field is only provided when the HMC is communicating
with the CPC's SE, and this field will be null if the information is currently
unavailable or there are no pending actions.
ec Array of ec An optional array of EC objects. When the EC MCL information pertains to an
objects SE, this field is only provided when the HMC is communicating with the CPC's
SE, and this field will be null if the information is currently unavailable.

Table 245. action object

Field name Type Description
type String One of:
Enum v "channel-config" - channels pending a config on/off
v "coupling-facility-reactivation" - at least one coupling facility pending
reactivation
v "power-on-reset-tracking" - there is a need for a power-on-reset
v "zhybrid-blades-activation" - (zHybrid accelerator blades are pending an
activation.
activation String One of:
Enum v "current" - the action is for the current activation
v "next" - the action is for the next install and activation.
pending Boolean Is the action pending (true) or not pending (false)

Table 246. ec object

Field name Type Description
number String (1-6) Engineering Change stream identifier.
part-number String (1-8) Engineering Change stream part number.
type String Engineering Change stream name.
(1-32)
description String Engineering Change stream descriptive text.
(1-65)
mcl Aray of The list of MicroCode Levels for this Engineering Change.
mcl objects

Table 247. mcl object

Field name Type Description
type String One of:
Enum v "retrieved" - a retrieved or staged level
v "activated" - an activated or applied level
v "accepted" - a committed level
v "installable-concurrent" - a non-disruptive apply-able level
v "removable-concurrent" - a non-disruptive reject-able level.
level String (1-3) Microcode level.

482 HMC Web Services API

 Level 04a

Table 247. mcl object (continued)

Field name Type Description
last-update Timestamp Time stamp of the last update, in the number of milliseconds since midnight
January 1, 1970 UTC. A null object is returned if no updates have occurred.

Table 248. stp-config object

Field name Type Description
stp-id String (0-8) If in STP-only or Mixed CTN, the STP identifier. Otherwise, an empty string.
Valid characters are 0-9, a-z, A-Z, underscore(_) and dash(-).
etr-id Integer ETR Identifier, if in ETR mode. If not in ETR mode, a null object is returned.
(0-31)
preferred-time-server stp-node- Describes the Preferred Timer Server. This property is optional, only returned
object on a Get request when the information is set.
backup-time-server stp-node- Describes the Backup Timer Server. This property is optional, only returned on
object a Get request when the information is set.
arbiter stp-node- Describes the arbiter of the CTN. This property is optional, only returned on a
object Get request when the information is set.
current-time-server String Describes the CPC's role in the CTN. One of:
Enum v "preferred" - CPC is the Preferred Time Server
v "backup" - CPC is the Backup Time Server.

This object is used to identify a CPC to the STP services. When used as input on the Set STP
Configuration operation, if the object-uri field is not provided, all other fields are required. If the
object-uri field is provided, all other fields are optional. If all fields are provided, the object-uri field is
ignored.
Table 249. stp-node object
Field name Type Description
object-uri String URI If the CPC is known to the HMC, contains the CPC's object-uri. Otherwise,
contains a null object
type String (0-6) The CPC machine type, right justified and left padded with zeros or a empty
string
model String (0-3) The CPC machine model or a empty string
manuf String (0-3) The CPC manufacturer or a empty string
po-manuf String (0-2) The CPC plant of manufacturer or a empty string
seq-num String The CPC sequence number or a empty string
(0-12)

Table 250. psw-description object

Field name Type Description
psw String Program Status Word (PSW) information for a single processor.
cpid String (2) The hexadecimal processor identifier, right justified and left padded with zeros.

Table 251. zaware-network object

Field name Type Description
chpid String (2) The required network adapter channel path identifier, in hexadecimal characters
0-9,a-f,A-F. The format is two hexadecimal digits (00-FF).

Chapter 11. Core IBM Z resources 483

 Level 04a

Table 251. zaware-network object (continued)

Field name Type Description
ipaddr-type String Indicates how this network adapter's IP address is obtained. One of the
Enum following values:
v "dhcp" - obtains an IP address via DHCP
v "link-local" - obtains a link-local IP address
v "static" - uses the specified IP address information.
vlan-id Integer If this network adapter is attached to a Virtual LAN, this field contains the
(0-4094) VLAN identifier. Otherwise, a null object indicating that this network adapter is
not attached to a Virtual LAN.
static-ip-info network- When ipaddr-type is "static", contains the static IP information. Otherwise,
ip-info contains a null object indicating that a static IP address is not used.
object

Table 252. ssc-network object

Field name Type Description
chpid String (2) The required network adapter channel path identifier, in hexadecimal characters
0-9,a-f,A-F. The format is two hexadecimal digits (00-FF).
port Integer The number of the port on the network adapter identified by chpid.

When the associated Support Element is at Version 2.13.1 or earlier, this

property is not returned on a Get operation, and it cannot be specified on an
Update operation.
ipaddr-type String Indicates how this network adapter's IP address is obtained. One of the
Enum following values:
v "dhcp" - obtains an IP address via DHCP
v "link-local" - obtains a link-local IP address
v "static" - uses the IP address information specified in static-ip-info.
vlan-id Integer If this network adapter is attached to a Virtual LAN, this field contains the
(0-4094) VLAN identifier. Otherwise, a null object indicating that this network adapter is
not attached to a Virtual LAN.
static-ip-info network- When ipaddr-type is "static", contains the static IP information. Otherwise,
ip-info contains a null object indicating that a static IP address is not used.
object

Table 253. ip-info object

Field name Type Description
type String The type of IP address being provided. One of the following values:
Enum v "ipv4" - an IPv4 address is provided
v "ipv6" - an IPv6 address is provided.
ip-address String/ The IP address to be used. The format of the string (IPv4 or IPv6) must be as
IPV4 indicated by the type field.
address or
String/
IPV6
address

Table 254. network-ip-info object

Field name Type Description
type String The type of IP address being provided. One of the following values:
Enum v "ipv4" - an IPv4 address is provided
v "ipv6" - an IPv6 address is provided.

484 HMC Web Services API

 Level 04a

Table 254. network-ip-info object (continued)

Field name Type Description
ip-address String/ The IP address to be used. The format of the string (IPv4 or IPv6) must be as
IPV4 indicated by the type field.
address or
String/
IPV6
address
prefix Integer The number of leading bits of ip-address that represent the network prefix.
v When type is "ipv4" - valid values are 0-32
v When type is "ipv6" - valid values are 0-128.

Table 255. absolute-capping object

Field name Type Description
type String The type of absolute capping. One of the following values:
Enum v "none" - no absolute capping
v "processors" - processor type absolute capping.
value Float When type is "none", value is not specified. When type is "processors", value is
in the range .01...255.00 in increments of .01 and is the limit of usage
independent of priority.

Console object
The Console object represents the single Z Hardware Management Console (HMC) application. The
Console object offers a heterogeneous set of services and capabilities, from basic HMC control operations
to general HMC information.

Object-access to the single Console object representing the local HMC is automatic for all authenticated
users. A Console may (but need not) participate in a { Primary, Alternate } pairing with another Console.
The Console object helps facilitate the management of a HMC's role in such a pairing.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
but does not provide the operational-status-related properties defined in that schema because it does not
maintain the concept of an operational status.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

The following class-specific specializations apply to the other base managed object properties:
Table 256. Console object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/URI The canonical URI path of the Console object, of the form
/api/console
parent — String/URI A Console object has no parent, so this property is always a null
object.
class — String The class of a Console object is "console".
name (ro) String The installation assigned name
description (ro) String This property is not supported, and returned as null.

Chapter 11. Core IBM Z resources 485

 Level 04a

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:
Table 257. Console object: class specific additional properties
Name Qualifier Type Description
version — String (1-8) The version number for the Console object.
paired-role — String Enum An indication ("primary" or "alternate") of how the Console
object functions in a pairing, or an empty string if this
Console object is not paired.
ec-mcl-description — ec-mcl- A nested object that describes the EC (Engineering Change)
description and MCL (Microcode Level) for the Console. Refer to the
object description of the ec-mcl-description object for details.
is-auto-switch-enabled — Boolean Automatic switching between primary and alternate
Hardware Management Consoles is enabled (true), or is not
enabled (false).
network-info — network-info A nested object describing the network information for this
object Hardware Management Console and for any other
Hardware Management console with which this Hardware
Management Console may be paired.
machine-info — machine-info A nested object describing the machine's BIOS
object characteristics.
ip-swapping-available — Boolean Whether the current primary HMC IP addresses will be
moved when making the alternate HMC the new primary
(true) or not (false).
hardware-messages (c)(pc) Array of The complete list of all Console hardware messages, each
hardware- identified by its URI. This list corresponds to the list
message provided by the List Console Hardware Messages
objects operation. If the console has no hardware messages, then an
empty array is provided.

The list of returned hardware messages can change as the

result of the new messages being dynamically added or
removed by the infrastructure or due to hardware messages
being deleted via the Delete Console Hardware Message
operation.
Note: This property is not returned by the Get Console
Properties operation, and only sessions associated with an
HMC user with permission to the Hardware Messages task
will receive a property-change notification for this property.
mobile-app- (p)(pc) mobile-app- The JSON nested object containing the mobile app
preferences preferences preferences, as described in Table 265 on page 488. This
object property can be retrieved through the Get Mobile App
Preferences operation, and modified through the Set
Mobile App Preferences operation.

Table 258. network-info object properties

Name Type Description
this-hmc Array of The collection of network information for the local Hardware
detailed- Management Console. The number of objects returned is a function of
network-info the machine model and type on which the Hardware Management
objects Console is executing. This information is available in the machine-info
property.

486 HMC Web Services API

 Level 04a

Table 258. network-info object properties (continued)

Name Type Description
paired-hmc paired-ip-info Describes the IP information for the paired Hardware Management
object Console known to the local Hardware Management Console

Table 259. detailed-network-info properties

Name Type Description
hmc-name String (1-16) The Hardware Management Console name
interface-name String The network interface name
domain-name String (1-255) The domain name configured for this network interface
is-private Boolean Whether the interface is private (true) or public (false).
mac String (1-12) The MAC address of this network interface.
ipv4-address Array of A collection of nested objects which describe the IPv4 addresses for this
ipv4-info network interface.
objects
ipv6-address Array of A collection of nested objects which describe the IPv6 addresses for this
ipv6-info network interface.
objects

Table 260. paired-ip-info properties

Name Type Description
hmc-name String (1-16) The Hardware Management Console name
ipv4-address Array of A collection of nested objects which describe the IPv4 addresses for this
ipv4-info network interface.
objects
ipv6-address Array of A collection of nested objects which describe the IPv6 addresses for this
ipv6-info network interface.
objects

Table 261. ipv4-info properties

Name Qualifier Type Description
subnet-mask (pc) String (1-15) The IP mask value
ip-address (pc) String IPV4 The IPv4 address
address

Table 262. ipv6-info properties

Name Qualifier Type Description
prefix-length (pc) Integer The number of leading bits of the IPv6 address that represent
the network prefix.
ip-address (pc) String IPV6 The IPv6 address
address

Table 263. machine-info properties

Name Type Description
machine-type String (1-4) The type of machine on which the Hardware Management Console is
executing.

Chapter 11. Core IBM Z resources 487

 Level 04a

Table 263. machine-info properties (continued)

Name Type Description
machine-model String (1-3) The model of machine on which the Hardware Management Console is
executing.
machine-serial String (1-10) The serial number of machine on which the Hardware Management
Console is executing.

Table 264. hardware-message object properties

Name Type Description
element-uri String/URI The canonical URI path of the Console hardware message. The URI is
in the following form: /api/console/hardware-messages/{hardware-
message-id}, where {hardware-message-id} is the value of the element-id
property of the hardware message.
element-id String (36) The unique identifier for the hardware message. The element-id is in
the form of a UUID.
parent String/URI The parent of a console hardware message is the Console object. The
parent value is the canonical URI path for the console.
class String The class of a hardware message object is "hardware-message".
timestamp Timestamp The timestamp represents the date and time when the hardware
message was created.
text String The text of the hardware message.

Table 265. mobile-app-preferences object properties

Name Type Description
app-enabled Boolean True indicates that the mobile app is enabled for this console. False
indicates that the mobile app is disabled and will not be allowed to
access this console.
require-app-password- Boolean True indicates that the mobile app must require its user to set an app
enabled password in order to access the app itself. False indicates the user is
not required to secure the app with a password.
password-caching-enabled Boolean True indicates that the mobile app is permitted to securely store the
user's password on the device for this console. False indicates this is
not permitted, and the user must input the password on every logon to
this console from the app.
actions-enabled Boolean True indicates that the mobile app is permitted to perform actions
against this console and the objects it manages, as permitted by the
user's authority. False indicates that no actions are permitted from the
mobile app to this console, and the app will be used only for
monitoring.
notifications-enabled Boolean True indicates that notifications from this console to the mobile app are
enabled and will flow to any registered devices. False indicates that
notifications will not flow from this console to any device with the
mobile app.

Get Console Properties

The Get Console Properties operation retrieves the properties of the Console object.

HTTP method and URI

GET /api/console

488 HMC Web Services API

 Level 04a

Response body contents

On successful completion, the response body contains an object that provides the current values of the
properties for the Console object as defined in “Data model” on page 485. Field names and data types in
the object are the same as the property names and data types defined in the data model.

Description
This operation returns the current properties for the Console object.

This operation may be targeted to an alternate Hardware Management Console.

On successful execution, HTTP status code 200 (OK) is returned and all of the current properties as
defined by the data model for the Console object are provided 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
“Response body contents.”

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

HTTP error status 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 HTTP/1.1

x-api-session: 6djngfmjus22whw3b5oj670c09rb2izzaafr4t3i1iw60ujmkd

Figure 262. Get Console Properties: Request

Chapter 11. Core IBM Z resources 489

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 16:04:31 GMT
content-type: application/json;charset=UTF-8
content-length: 4250
{
"class": "console",
"description": "R32 Primary/Alternate HMC",
"ec-mcl-description": {
"ec": [
{
"description": "Hardware Management Console Framework",
"mcl": [
{
"last-update": 1422026097000,
"level": "205",
"type": "retrieved"
},
{
"last-update": 1423074018000,
"level": "205",
"type": "activated"
},
{
"last-update": null,
"level": "167",
"type": "accepted"
},
{
"level": "205",
"type": "installable-concurrent"
},
{
"level": "168",
"type": "removable-concurrent"
}
],
"number": "N48180",
"part-number": "45D8928",
"type": "SYSTEM"
},

Figure 263. Get Console Properties: Response (Part 1)

490 HMC Web Services API

 Level 04a

{
"description": "Embedded Operating System",
"mcl": [
{
"level": "000",
"type": "retrieved"
},
{
"level": "000",
"type": "activated"
},
{
"level": "000",
"type": "accepted"
},
{
"level": "000",
"type": "installable-concurrent"
},
{
"level": "000",
"type": "removable-concurrent"
}
],
"number": "N48198",
"part-number": "45D8929",
"type": "OS"
}
]
},
"ip-swapping-available": true,
"is-auto-switch-enabled": true,
"is-locked": false,
"machine-info": {
"machine-model": "PAA",
"machine-serial": "KQZBLKD",
"machine-type": "7327"
},
"name": "HMCR32PRI",
"network-info": {
"paired-hmc": {
"hmc-name": "HMCR32ALT",
"ipv4-address": [
"9.60.15.47",
"9.60.14.47"
],
"ipv6-address": [
"fdd8:673b:d89b:1:221:5eff:fe69:e3f5",
"2002:93c:ffb:1:221:5eff:fe69:e3f5",
"fe80:0:0:0:221:5eff:fe69:e3f5",
"fe80:0:0:0:210:18ff:fe4c:8026"
]
},

Figure 264. Get Console Properties: Response (Part 2)

Chapter 11. Core IBM Z resources 491

 Level 04a

"this-hmc": [
{
"domain-name": "endicott.ibm.com",
"hmc-name": "HMCR32PRI",
"interface-name": "eth0",
"ipv4-address": [
{
"ip-address": "9.60.15.48",
"subnet-mask": "255.255.255.0"
}
],
"ipv6-address": [
{
"ip-address": "fdd8:673b:d89b:1:221:5eff:fe69:dea0",
"prefix-length": 64
},
{
"ip-address": "2002:93c:ffb:1:221:5eff:fe69:dea0",
"prefix-length": 64
},
{
"ip-address": "fe80:0:0:0:221:5eff:fe69:dea0",
"prefix-length": 64
}
],
"is-private": false,
"mac": "00215E69DEA0"
},
{
"domain-name": "endicott.ibm.com",
"hmc-name": "HMCR32PRI",
"interface-name": "eth1",
"ipv4-address": [
{
"ip-address": "9.60.14.48",
"subnet-mask": "255.255.255.0"
}
],
"ipv6-address": [
{
"ip-address": "fe80:0:0:0:210:18ff:fe4c:8334",
"prefix-length": 64
}
],
"is-private": false,
"mac": "0010184C8334"
}
]
},
"object-id": "1e8b3137-85b0-3a06-9269-0b25fc170d44",
"object-uri": "/api/console",
"paired-role": "primary",
"parent": null,
"version": "2.11.1"
}

Figure 265. Get Console Properties: Response (Part 3)

Restart Console
The Restart Console operation restarts the Hardware Management Console.

492 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/console/operations/restart

Request body contents

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

Field name Type Rqd/Opt Description

force Boolean Optional Whether the restart operation is processed when users are connected
(true) or not (false). The default is false.

Description
The Hardware Management Console is restarted. This operation may be targeted to an alternate
Hardware Management Console.

By default, the restart does not occur if one or more users are currently connected to the Hardware
Management Console. This can be overridden by use of the force field in the request body.

On success, HTTP status code 202 (Accepted) is returned.

Authorization
To use Restart Console, you must have the following:
v Action/Task permission to the Shutdown/Restart task
v Remote Restart must be enabled on the Hardware Management Console.

HTTP status and reason codes

On success, HTTP status code 202 (Accepted) 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.
267 The operation is rejected, due to the presence of HMC users. Either wait
until all HMC users have logged off or retry the request with the force field
set to "true".
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform this operation.
269 This operation is currently blocked. The error message will contain
information on the blocking application.
270 The remote restart operation is not enabled on the HMC.
500 (Server Error) 273 An unexpected error occurred during the operation.

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

Chapter 11. Core IBM Z resources 493

 Level 04a

Make Console Primary

Make Console Primary initiates a primary/alternate role switch when directed at a Hardware
Management Console that is currently operating in the alternate role. It is only supported for a Hardware
Management Console participating in a {primary, alternate} pairing.

HTTP method and URI

POST /api/console/operations/make-primary

Description
This operation initiates a primary/alternate role switch when directed at a Hardware Management
Console that is currently operating in the alternate role. As this command will cause both consoles to be
rebooted, any active sessions (GUI based or API based) will be terminated.

If this operation is directed at a Hardware Management Console which does not participate in a {primary,
alternate} pairing, it returns with HTTP status code 400 (Bad Request).

If this operation is directed at a Hardware Management Console whose pair-role is "alternate", it initiates
the role-switch process, and returns with HTTP status code 204 (No Content).

If this operation is directed at a Hardware Management Console whose pair-role is already "primary", it
has no effect, and returns with HTTP status code 204 (No Content).

Authorization
To use Make Console Primary, you must have the following:
v Action/task permission to the Manage Alternate HMC 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, 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.
265 The operation was directed at a Hardware Management Console which is
not participating in a {primary, alternate} pairing, which is not supported.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform this operation.
500 (Server Error) 273 An unexpected error occurred during the operation.

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

Usage notes
When configured as recommended by IBM, the process of recovering from the failure of the primary
HMC by takeover by the alternate HMC includes movement of the IP address of the former primary
HMC to the new primary HMC. When this occurs, explicit redirection of API requests to the newly

494 HMC Web Services API

 Level 04a

designated primary HMC is not needed. However, the IP address swapping may not be possible in
certain network configurations. The address of the alternate HMC is provided to allow applications to
explicitly redirect requests to the other HMC of the pair in these cases.

Shutdown Console
Shutdown Console powers off the Hardware Management Console.

HTTP method and URI

POST /api/console/operations/shutdown

Request body contents

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

Field name Type Rqd/Opt Description

force Boolean Optional Whether the shutdown operation is processed when users are
connected (true) or not (false). The default is false.

Description
The Hardware Management Console is powered off.

This operation may be targeted to an alternate Hardware Management Console.

By default, the shutdown does not occur if one or more users are currently connected to the Hardware
Management Console. This can be overridden by use of the force field in the request body.

The action to shutdown the Hardware Management Console occurs asynchronously. If the request is
accepted, HTTP status code 202 (Accepted) is returned to indicate that the request has been initiated.
However, because this action results in the targeted Hardware Management Console becoming inactive
and powered off at completion, it is not possible to track the completion of this request. Thus no response
body containing an asynchronous job URI is provided, nor is a job completion notification generated
upon completion.

Authorization
To use Shutdown Console, you must have the following:
v Action/task permission to the Shutdown/Restart task.
v Remote Shutdown must be enabled on the Hardware Management Console.

HTTP status and reason codes

On success, HTTP status code 202 (Accepted) is returned but 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.

Chapter 11. Core IBM Z resources 495

 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.
267 The operation is rejected, due to the presence of HMC users. Either wait
until all HMC users have logged off or retry the request with the force field
set to true.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform this operation.
270 The remote restart operation is not enabled on the HMC.
304 This operation is currently blocked. The error message will contain
information on the blocking application.
500 (Server Error) 273 An unexpected error occurred during the operation.

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/console/operations/shutdown HTTP/1.1/

x-api-session: 5dul8zvlwa5s83eobcukaf1vug3s3kgidkyk9e5c5acsekabsl
content-type: application/json
content-length: 16
{
"force": false
}

Figure 266. Shutdown Console: Request

202 Accepted
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Fri, 01 Mar 2013 19:38:25 GMT

<No response body>

Figure 267. Shutdown Console: Response

Reorder User Patterns

The Reorder User Patterns operation changes the search order of the console's User Patterns used when a
user logs on to the console.

HTTP method and URI

POST /api/console/operations/reorder-user-patterns

496 HMC Web Services API

 Level 04a

Request body contents

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

Name Type Rqd/Opt Description

user-pattern- Array of Required Ordered list of User Pattern object element-uri property
uris String/URI values. The order of these URIs in the array defines the new
order of the User Patterns.

Description
This operation reorders the console's User Patterns.

On successful execution of this operation the User Patterns are reordered to match the order of their
element-uri properties in the user-pattern-uris array in the request body.

The request body is validated against the schema described in “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered. If a URI in the request body does not designate an existing User Pattern object, status
code 404 (Not Found) is returned. The array in the request body must include each of the console's
currently defined User Patterns and no others. In addition, the API user must have action/task
permission to the Manage User Patterns task; otherwise, status code 403 (Forbidden) is returned.

Authorization requirement
This operation has the following authorization requirements:
v Action/task permission to the Manage User Patterns 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 266. Reorder User Patterns: HTTP status and reason codes.
HTTP error status code Reason 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 array in the request body is missing an existing User Pattern,
or it contains an entry that designates a User Pattern that is not
one of the console's current User Patterns.
403 (Forbidden) 1 The API user does not have the required permission for this
operation.
404 (Not Found) 2 A URI in the request body does not designate an existing
resource of the correct type.

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

Chapter 11. Core IBM Z resources 497

 Level 04a

Example HTTP interaction

POST /api/console/operations/reorder-user-patterns HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 301
{
"user-pattern-uris":[
"/api/console/user-patterns/497bf4ec-1dbf-11e4-8ceb-1c6f65065a91",
"/api/console/user-patterns/6d897292-3ceb-11e4-9e36-1c6f65065a91",
"/api/console/user-patterns/e40b9ba6-48e0-11e4-82a1-1c6f65065a91",
"/api/console/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91"
]
}

Figure 268. Reorder User Patterns: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT

<No response body>

Figure 269. Reorder User Patterns: Response

Get Console Audit Log

The Get Console Audit Log operation returns the console audit log, filtered according to the query
parameters, if specified.

HTTP method and URI

GET /api/console/operations/get-audit-log

Query Parameters

Name Type Rqd/Opt Description

begin-time Timestamp Optional A timestamp used to filter log entries. Entries created earlier
than this time are omitted from the results. This is specified as
the number of milliseconds since the epoch and must be
greater than or equal to 0. If not specified, then no such
filtering is performed.
end-time Timestamp Optional A timestamp used to filter log entries. Entries created later
than this time are omitted from the results. This is specified as
the number of milliseconds since the epoch and must be
greater than or equal to 0. If not specified, then no such
filtering is performed.

Response body contents

On successful completion, the response body is a JSON array of JSON objects returned using HTTP
chunked transfer encoding. Each array element is a log-entry-info object containing information about a
single log entry. The array elements are in order of increasing timestamp. See Table 267 on page 499 for
more information.

498 HMC Web Services API

 Level 04a

A log-entry-info object contains information about a single log entry and the event which caused the
entry. Each log-entry-info object contains the following fields:
Table 267. log-entry-info object properties
Name Type Description
event-time Timestamp The time when the event occurred.
event-id String The ID number for the event.
event-name String (0-12) The name for the event, or null or an empty string if none.
userid String The user ID of the HMC/SE user associated with the event, or null if
there is no user associated with the event.
user-uri String/URI The canonical URI path of the HMC/SE user associated with the event,
or null is there is no user associated with the event.
event-message String The complete, formatted message for the event.
event-data-items Array of An array of event-data-item-info objects, one for each item of event
objects data associated with the event-message for the event. If there are no
event data items, an empty array is provided. The order of items in
this array is semantically significant and matches the documentation
for this event-id.
event-details Array of An array of event-details-info objects, one for each event detail
objects associated with the event. If there are no event details, an empty array
is provided.

An event-details-info object contains information about a single event detail. Each event-details-info object
contains the following fields:
Table 268. event-details-info object properties
Name Type Description
event-details-message String The complete, formatted details message.
event-details-data-items Array of An array of event-data-item-info objects, one for each item of event
objects details data associated with the event-details-message for the event. If
there are no event details data items, an empty array is provided.

An event-data-item-info object contains information about a single item of event data. Each
event-data-item-info object contains the following fields:
Table 269. event-data-item-info object properties
Name Type Description
data-item-number Integer The number for this data item. This is the 0-based index of this
event-data-item-info object in the event-data-items or
event-details-data-items array in which it is contained. This number
identifies the substitution variable to which this data item corresponds
in the documentation for the event identified by event-id.
data-item-type String Enum Identifies the data type of the data item in the event-data-item field.
Possible values are:
v "long"
v "float"
v "string"
data-item-value Varies. See The data item.
data-item-
type
description

Chapter 11. Core IBM Z resources 499

 Level 04a

Description
This operation returns the console’s audit log in increasing timestamp order, filtered according to the
query parameters, if specified. Each log entry pertains to a specific event that occurred on or to a
managed object or the console itself. The log entries can be limited by specifying explicit filtering criteria
on the request. If the begin-time query parameter is specified, then any entries earlier than that time are
omitted. If the end-time query parameter is specified, then any entries later than that time are omitted.

The API user must have action/task permission to the Audit and Log Management task; otherwise,
status code 403 (Forbidden) is returned.

On successful execution, the response body contains an array of filtered log entries. If the audit log is
empty or there are no entries to be returned after filtering, then an empty array is provided. Each log
entry contains the event ID, event name and event message. If there are data items included in the event
message, they are available separately. The order and meaning of the substitution items for each event ID
are documented in the console help system in the HMC Introduction topic Audit, Event, and Security
Log Messages.

Authorization requirement
This operation has the following authorization requirements:
v Action/task permission to the Audit and Log Management task.

HTTP status and reason codes

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

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

HTTP error status code Reason code Description

400 (Bad Request) Various Errors were detected during common request validation. See
“Common request validation reason codes” 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

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/get-audit-log HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 270. Get Console Audit Log: Request

500 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
transfer-encoding: chunked
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:34 GMT
content-type: application/json;charset=ISO-8859-1
[
{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"GinkgoEnsemble"
}
],
"event-details":[],
"event-id":"1988",
"event-message":"An ensemble was created. The ensemble name is GinkgoEnsemble.",
"event-name":"EnsembleMem",
"event-time":1411405571970,
"user-uri":"/api/users/ae72e844-3dc0-11e4-8dd1-1c6f65065a91",
"userid":"ENSADMIN"
},
{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"Default"
},
{
"data-item-number":1,
"data-item-type":"string",
"data-item-value":"Default"
},
{
"data-item-number":2,
"data-item-type":"string",
"data-item-value":"OPERATOR"
}
],
"event-details":[],
"event-id":"1982",
"event-message":"Availability policy \"Default\" was activated in workload
\"Default\" by user OPERATOR as a result of creating the workload.",
"event-name":"AvlPolActive",
"event-time":1411405588850,
"user-uri":null,
"userid":null
}
]

Figure 271. Get Console Audit Log: Response

Get Console Security Log

The Get Console Security Log operation returns the console security log, filtered according to the query
parameters, if specified.

HTTP method and URI

GET /api/console/operations/get-security-log

Query Parameters

Chapter 11. Core IBM Z resources 501

 Level 04a

Name Type Rqd/Opt Description

begin-time Timestamp Optional A timestamp used to filter log entries. Entries created earlier
than this time are omitted from the results. This is specified as
the number of milliseconds since the epoch and must be
greater than or equal to 0. If not specified, then no such
filtering is performed.
end-time Timestamp Optional A timestamp used to filter log entries. Entries created later
than this time are omitted from the results. This is specified as
the number of milliseconds since the epoch and must be
greater than or equal to 0. If not specified, then no such
filtering is performed.

Response body contents

On successful completion, the response body is a JSON array of JSON objects returned using HTTP
chunked transfer encoding. Each array element is a log-entry-info object containing information about a
single log entry. The array elements are in order of increasing timestamp. See Table 267 on page 499 for
more information.

Description
This operation returns the console’s security log in increasing timestamp order, filtered according to the
query parameters, if specified. Each log entry pertains to a specific event that occurred on or to a
managed object or the console itself. The log entries can be limited by specifying explicit filtering criteria
on the request. If the begin-time query parameter is specified, then any entries earlier than that time are
omitted. If the end-time query parameter is specified, then any entries later than that time are omitted.

The API user must have action/task permission to the View Security Logs task; otherwise, status code
403 (Forbidden) is returned.

On successful execution, the response body contains an array of filtered log entries. If the security log is
empty or there are no entries to be returned after filtering, then an empty array is provided. Each log
entry contains the event ID, event name and event message. If there are data items included in the event
message, they are available separately. The order and meaning of the substitution items for each event ID
are documented in the console help system in the HMC Introduction topic Audit, Event, and Security
Log Messages.

Authorization requirement
This operation has the following authorization requirement:
v Action/task permission to the View Security Logs task.

HTTP status and reason codes

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

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

HTTP error status code Reason code Description

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

502 HMC Web Services API

 Level 04a

HTTP error status code Reason code Description

403 (Forbidden) 1 The API user does not have the required permission for 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/console/operations/get-security-log HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 272. Get Console Security Log: Request

Chapter 11. Core IBM Z resources 503

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
transfer-encoding: chunked
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:34 GMT
content-type: application/json;charset=ISO-8859-1
[
{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"acsadmin"
},
{
"data-item-number":1,
"data-item-type":"string",
"data-item-value":"Sx149"
},
{
"data-item-number":2,
"data-item-type":"string",
"data-item-value":"admin.my.company.com [1.2.3.4]"
}
],
"event-details":[],
"event-id":"1941",
"event-message":"User acsadmin has logged on to Web Services API session
Sx149 from location admin.my.company.com [1.2.3.4]",
"event-name":"WSA Logon",
"event-time":1412285249660,
"user-uri":"/api/users/ae8aed68-3dc0-11e4-8dd1-1c6f65065a91",
"userid":"ACSADMIN"
},
{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"Dept Admin"
}
],
"event-details":[
{
"event-details-data-items":[],
"event-details-message":"Task Role: Dept Admin --Based on role is
null. Permitted tasks:"
}
],
"event-id":"1272",
"event-message":"The task role Dept Admin has been created.",
"event-name":"LOGTROLEADD",
"event-time":1412285252280,
"user-uri":"/api/users/ae8aed68-3dc0-11e4-8dd1-1c6f65065a91",
"userid":"ACSADMIN"
},

Figure 273. Get Console Security Log: Response (Part 1)

504 HMC Web Services API

 Level 04a

{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"Dept Admin"
}
],
"event-details":[
{
"event-details-data-items":[],
"event-details-message":"Task Role: Dept Admin --Based on role is
null. Permitted tasks: ClassId=XVirtualServer"
}
],
"event-id":"1273",
"event-message":"The task role Dept Admin has been changed.",
"event-name":"LOGTROLECHG",
"event-time":1412285253000,
"user-uri":"/api/users/ae8aed68-3dc0-11e4-8dd1-1c6f65065a91",
"userid":"ACSADMIN"
}
]

Figure 274. Get Console Security Log: Response (Part 2)

List Console Hardware Messages

The List Console Hardware Messages operation lists the current set of hardware messages associated
with the console.

HTTP method and URI

GET /api/console/hardware-messages

Query Parameters

Name Type Rqd/Opt Description

begin-time Timestamp Optional A timestamp used to filter hardware messages. Messages
created earlier than this time are omitted from the results. The
value is specified as the number of milliseconds since the
epoch and must be greater than or equal to 0.

If not specified, then no such filtering is performed.

end-time Timestamp Optional A timestamp used to filter hardware messages. Messages
created later than this time are omitted from the results. The
value is specified as the number of milliseconds since the
epoch and must be greater than or equal to 0.

If not specified, then no such filtering is performed.

Chapter 11. Core IBM Z resources 505

 Level 04a

Response body contents

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

Field name Type Description

hardware-messages Array of Array of nested hardware-message-info objects as defined in the next table.
hardware-
message-
info objects

Each nested hardware-message-info object contains the following fields:

Field name Type Description

element-uri String/URI The canonical URI path of the hardware message. The URI is in the
following form: /api/console/hardware-messages/{hardware-message-id}
timestamp Timestamp The date and time the hardware message was created
text String The text of the hardware message.

Description
This operation returns a set of console hardware messages in increasing timestamp order, filtered
according to the query parameters, if specified.

If the begin-time query parameter is specified, then any entries earlier than that time are omitted. If the
end-time query parameter is specified, then any entries later than that time are omitted.

If there are no hardware messages associated with the console, or if no hardware messages are to be
included in the results due to filtering, an empty array is returned and the operation completes
successfully.

The API user must have Action/Task permission to the Hardware Messages task or the Hardware
Messages task in view-only mode; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/Task permission to the Hardware Messages task or the Hardware Messages task in view-only
mode.

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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

506 HMC Web Services API

 Level 04a

Table 270. List Console Hardware Messages: HTTP status and reason codes.
HTTP error status
code Reason 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 begin-time value is greater than the end-time value.
403 (Forbidden) 1 The API user does not have Action/Task permission for the Hardware
Messages task or the Hardware Messages task in view-only mode.

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/hardware-messages HTTP/1.1

x-api-session: 4pw149l9jtzcwohdfe8s9gw5zzv7v73yksomswrg50t7ni4q8r

Figure 275. List Console Hardware Messages: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 06 Oct 2014 17:02:37 GMT
content-type: application/json;charset=UTF-8
content-length: 206
{
"hardware-messages":[
{
"element-uri":"/api/console/hardware-messages/11c5f16a-4d58-11e4-ba8d-
02215e673710",
"text":"Licensed internal code has detected a problem. [Problem # 3]",
"timestamp":1412600137860
}
]
}

Figure 276. List Console Hardware Messages: Response

Get Console Hardware Message Properties

The Get Console Hardware Message Properties operation retrieves the properties of a single console
hardware message.

HTTP method and URI

GET /api/console/hardware-messages/{hardware-message-id}

In this request, the URI variable {hardware-message-id} is the unique identifier of the hardware message to
be retrieved.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the console hardware message object as defined in “Data model” on page 485. Field

Chapter 11. Core IBM Z resources 507

 Level 04a

names and data types in the JSON object are the same as the property names and data types defined in
the data model.

Description
This operation retrieves the properties of a single console hardware message specified by
{hardware-message-id}.

The URI path must designate an existing hardware message; otherwise, status code 404 (Not Found) is
returned. In addition, the API user must have Action/Task permission to the Hardware Messages task or
the Hardware Messages task in view-only mode; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/Task permission to the Hardware Messages task or the Hardware Messages task in view-only
mode.

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 507.

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

HTTP error status

code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See
“Common request validation reason codes” on page 41 for a list of
the possible reason codes.
403 (Forbidden) 1 The API user does not have Action/Task permission for the
Hardware Messages task or the Hardware Messages task in
view-only mode.
404 (Not Found) 322 The element ID in the URI {hardware-message-id} does not designate an
existing console hardware message.

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/hardware-messages/11c5f16a-4d58-11e4-ba8d-02215e673710 HTTP/1.1

x-api-session: 1p5uuz63tskpoczrpjux2ni122ciqeoqrchza1t30jvb9ug09t

Figure 277. Get Console Hardware Message Properties: Request

508 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 06 Oct 2014 17:04:54 GMT
content-type: application/json;charset=UTF-8
content-length: 286
{
"class":"hardware-message",
"element-id":"11c5f16a-4d58-11e4-ba8d-02215e673710",
"element-uri":"/api/console/hardware-messages/11c5f16a-4d58-11e4-ba8d-02215e673710",
"parent":"/api/console",
"text":"Licensed internal code has detected a problem. [Problem # 3]",
"timestamp":1412600137860
}

Figure 278. Get Console Hardware Message Properties: Response

Delete Console Hardware Message

The Delete Console Hardware Message operation deletes a single console hardware message

HTTP method and URI

DELETE /api/console/hardware-messages/{hardware-message-id}

In this request, the URI variable {hardware-message-id} is the unique identifier of the hardware message to
be deleted.

Description
This operation deletes a specific console hardware message. The hardware message to be deleted is
identified by the {hardware-message-id} variable in the URI.

The URI path must designate an existing hardware message; otherwise, status code 404 (Not Found) is
returned. In addition, the API user must have Action/Task permission to the Hardware Messages task;
otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/Task permission to the Hardware Messages task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned with no response body 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

code Reason 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 Action/Task permission for the
Hardware Messages task.

Chapter 11. Core IBM Z resources 509

 Level 04a

HTTP error status

code Reason code Description
404 (Not Found) 322 The element ID in the URI {hardware-message-id} does not designate an
existing console hardware message.

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/console/hardware-messages/6b2d61a4-a1ac-11e4-87ee-5ef3fcae8020 HTTP/1.1

x-api-session: c8un3odpy8yyp150o3poz1ud4gwyfodlwyq495327bpyn2p0z

Figure 279. Delete Console Hardware Message: Request

204 No Content
date: Mon, 09 Feb 2015 20:07:31 GMT
server: zSeries management console API web server / 2.0

<No response body>

Figure 280. Delete Console Hardware Message: Response

List Unmanaged CPCs

The List Unmanaged CPCs operation lists the CPCs that have been discovered by this HMC but are not
configured to be managed by this HMC.

HTTP method and URI

GET /api/console/operations/list-unmanaged-cpcs

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.

Response body contents

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

Field name Type Description

cpcs Array of Array of nested cpc-info objects as described in the next table.
cpc-info
objects

Each nested cpc-info object contains the following fields:

510 HMC Web Services API

 Level 04a

Field name Type Description

object-uri String/URI The canonical URI path for an unmanaged CPC object is of the form
/api/cpcs/{cpc-id} where {cpc-id} is the unique identifier for the
unmanaged CPC instance.
name String The name of the unmanaged CPC.

Description
This operation lists the CPCs that have been discovered by this HMC but are not configured to be
managed by this HMC. Some basic information is provided for each CPC that is included in the
response.

If the name query parameter is specified, the returned list is limited to those unmanaged CPCs whose
names match the specified filter pattern. If the name parameter is omitted, no such filtering is performed.

An unmanaged CPC is included in the list only if the API user has object-access permission to that object.
If there is an unmanaged CPC 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 unmanaged CPCs known to the HMC or if no unmanaged CPCs 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 unmanaged CPC 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 510.

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.
Table 271. List Unmanaged CPCs: HTTP status and reason codes
HTTP error status
code Reason 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.
299 A query parameter has an invalid syntax.

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

Usage Notes
The APIs provide only minimal support for unmanaged CPC objects. There is no data model, and most
of the standard operations are not provided. The List Unmanaged CPCs operation can be used to list
them and to provide their name and object URI. The provided support also allows an API client to
manage access to them through the Add Permission to User Role and Remove Permission from User

Chapter 11. Core IBM Z resources 511

 Level 04a

Role operations. The HMC's Add Object Definition task is used to configure an unmanaged CPC to be
managed by the HMC.

Example HTTP interaction

GET /api/console/operations/list-unmanaged-cpcs HTTP/1.1

x-api-session: 606ay5h8erhjmee80hl7j4rglorqebifiirqnrd4m1ga9xyjv6

Figure 281. List Unmanaged CPCs: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 08 Mar 2016 14:13:05 GMT
content-type: application/json;charset=UTF-8
content-length: 252
{
"cpcs":[
{
"name":"P0LXSM20",
"object-uri":"/api/cpcs/343a56e1-96ed-3191-b092-99a784311e43"
},
{
"name":"D20BUSE",
"object-uri":"/api/cpcs/07cc8420-78e6-3520-840a-ea6ff0074bbc"
},
{
"name":"S202B",
"object-uri":"/api/cpcs/3275e681-fe9b-3c54-ade8-6a08b802f781"
}
]
}

Figure 282. List Unmanaged CPCs: Response

List Unmanaged zBX Nodes

The List Unmanaged zBX Nodes operation lists the zBX nodes that have been discovered by this HMC
but are not configured to be managed by this HMC.

HTTP method and URI

GET /api/console/operations/list-unmanaged-zbxs

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.

512 HMC Web Services API

 Level 04a

Response body contents

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

Field name Type Description

zbxs Array of Array of nested zbx-info objects as described in the next table.
zbx-info
objects

Each nested cpc-info object contains the following fields:

Field name Type Description

object-uri String/URI The canonical URI path for an unmanaged zBX node object is of the form
/api/zbxs/{zbx-id} where {zbx-id} is the unique identifier for the
unmanaged zBX node instance.
name String The name of the unmanaged zBX node.

Description
This operation lists the zBX nodes that have been discovered by this HMC but are not configured to be
managed by this HMC. Some basic information is provided for each zBX node that is included in the
response.

If the name query parameter is specified, the returned list is limited to those unmanaged zBX nodes
whose names match the specified filter pattern. If the name parameter is omitted, no such filtering is
performed.

An unmanaged zBX node is included in the list only if the API user has object-access permission to that
object. If there is an unmanaged zBX node 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 unmanaged zBX nodes known to the HMC or if no unmanaged zBX nodes 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 unmanaged zBX node 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.”

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.
Table 272. List Unmanaged zBX Nodes: HTTP status and reason codes
HTTP error status
code Reason 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 11. Core IBM Z resources 513

 Level 04a

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

Usage Notes
The APIs provide only minimal support for unmanaged zBX node objects. There is no data model, and
most of the standard operations are not provided. The List Unmanaged zBX Nodes operation can be
used to list them and to provide their name and object URI. The provided support also allows an API
client to manage access to them through the Add Permission to User Role and Remove Permission from
User Role operations. The HMC's Add Object Definition task is used to configure an unmanaged zBX
node to be managed by the HMC.

Example HTTP interaction

GET /api/console/operations/list-unmanaged-zbxs HTTP/1.1

x-api-session: 2updjbd49a6wvkx8xieoa2wv1wyovwq9tuu1gjqlxszqgpr7ff

Figure 283. List Unmanaged zBX Nodes: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 08 Mar 2016 19:54:30 GMT
content-type: application/json;charset=UTF-8
content-length: 174
{
"zbxs":[
{
"name":"DEVNOD22",
"object-uri":"/api/zbxs/3a8181b6-7732-37ab-a5a9-77af5747457a"
},
{
"name":"ZBX22MCF",
"object-uri":"/api/zbxs/49a5b8c5-07c7-39b2-bba4-7d4d46aaa0da"
}
]
}

Figure 284. List Unmanaged zBX Nodes: Response

Get Mobile App Preferences

The Get Mobile App Preferences operation provides the current preferences for the mobile app on this
console.

HTTP method and URI

GET /api/console/operations/get-mobile-app-preferences

Response body contents

On successful completion, the response body contains a JSON object that provides the
mobile-app-preferences property of the Console object as defined in “Data model” on page 485.

514 HMC Web Services API

 Level 04a

Description
This operation returns the mobile-app-preferences property of the Console object.

On successful execution, the mobile-app-preferences property is provided in the response body, and
HTTP status code 200 (OK) is returned.

Authorization requirements
This operation has no explicit authorization requirements.

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 514.

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

GET /api/console/operations/get-mobile-app-preferences HTTP/1.1

x-api-session: 60fkxrce96k33vyeuvi7kgl8rs0ng8ujovge1bas8oit7vgvnm

Figure 285. Get Mobile App Preferences: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Fri, 18 Nov 2016 20:41:21 GMT
content-type: application/json;charset=UTF-8
content-length: 170
{
"mobile-app-preferences":{
"actions-enabled":true,
"app-enabled":true,
"notifications-enabled":false,
"password-caching-enabled":false,
"require-app-password-enabled":false
}
}

Figure 286. Get Mobile App Preferences: Response

Chapter 11. Core IBM Z resources 515

 Level 04a

Set Mobile App Preferences

The Set Mobile App Preferences operation sets one or more of the mobile app preferences for this
console.

HTTP method and URI

POST /api/console/operations/set-mobile-app-preferences

Request body contents

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

Name Type Rqd/Opt Description

app-enabled Boolean Optional True indicates that the mobile app is enabled for this
console. False indicates that the mobile app is disabled and
will not be allowed to access this console.
require-app-password- Boolean Optional True indicates that the mobile app must require its user to
enabled set an app password in order to access the app itself. False
indicates the user is not required to secure the app with a
password.
password-caching-enabled Boolean Optional True indicates that the mobile app is permitted to securely
store the user's password on the device for this console.
False indicates this is not permitted, and the user must
input the password on every logon to this console from the
app.
actions-enabled Boolean Optional True indicates that the mobile app is permitted to perform
actions against this console and the objects it manages, as
permitted by the user's authority. False indicates that no
actions are permitted from the mobile app to this console,
and the app will be used only for monitoring.
notifications-enabled Boolean Optional True indicates that notifications from this console to the
mobile app are enabled and will flow to any registered
devices. False indicates that notifications will not flow
from this console to any device with the mobile app.

Description
This operation sets one or more mobile app preferences for this console.

On successful execution, the preferences passed in the request body have been set on this console, and
HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/Task permission to the HMC Mobile Settings task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned.

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.

516 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.
403 (Forbidden) 1 The user does not have access to the HMC Mobile Settings task.

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/console/operations/set-mobile-app-preferences HTTP/1.1

x-api-session: 5aekjhn8t6g2xlc3xery2flewwey1xwxlnsm0ixhn00p81i1da
content-type: application/json
content-length: 81
{
"actions-enabled":true,
"app-enabled":true,
"password-caching-enabled":false
}

Figure 287. Set Mobile App Preferences: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Fri, 18 Nov 2016 20:40:53 GMT

<No response body>

Figure 288. Set Mobile App Preferences: Response

Get CPC Notification Preferences for Device

The Get CPC Notification Preferences for Device operation retrieves the configured mobile app
notification preferences for a CPC to a mobile device.

HTTP method and URI

POST /api/console/operations/get-device-cpc-notification-preferences

Request body contents

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

Name Type Rqd/Opt Description

device-id String Required The unique identifier of the mobile device to which the
preferences being retrieved belong.
cpc-uri String/URI Required The object-uri property of the CPC for which the
notification preferences apply.

Chapter 11. Core IBM Z resources 517

 Level 04a

Response body contents

The response body is a JSON object with the following fields:

Name Type Description

new-hardware-message Boolean True indicates that this console is configured to notify the identified
device of new hardware messages for the identified CPC. False
indicates the device with not be notified.

The default value is false until modified with the Update CPC
Notification Preferences for Device operation.
cpc-acceptable-status- Boolean True indicates that this console is configured to notify the identified
change device when the has-unacceptable-status property changes for the
identified CPC. False indicates the device will not be notified.

The default value is false until modified with the Update CPC
Notification Preferences for Device operation.
new-os-message Array of Array of object-uri values of Partition (for DPM) or Logical
String/URI Partition (for non-DPM) objects for which new operating system
message events should notify the identified device. Any new OS
message on the identified partitions will cause the identified device
to be notified. To limit which OS messages lead to notifications,
refer to new-os-message-filtered. Note that this list of partitions is
mutually exclusive with those identified in new-os-message-
filtered.

The default value is empty until modified with the Update CPC
Notification Preferences for Device operation.
new-os-message-filtered Array of Array of partition-os-message-filter objects defining the Partitions
partition-os- (for DPM) or Logical Partitions (for non-DPM) and the filter
message-filter conditions for which new operating system events should notify
objects the identified device. As opposed to the new-os-message property,
which notifies the device of all OS messages on an identified
partition, this allows notification for only OS messages that pass
the filter conditions. Note that this list of partitions is mutually
exclusive with those listed in new-os-message.

The default value is empty until modified with the Update CPC
Notification Preferences for Device operation.
partition-acceptable- Array of Array of object-uri values of Partition (for DPM) or Logical
status-change String/URI Partition (for non-DPM) objects for which the has-unacceptable-
status property changes should notify the identified device.

The default value is empty until modified with the Update CPC
Notification Preferences for Device operation.

The partition-os-message-filter nested object contains the following fields:

Name Type Description

partition-uri String/URI The object-uri of the Partition (for DPM) or Logical Partition (for
non-DPM) object for which new operating system message events
should notify the identified device when they pass the defined
filters.

518 HMC Web Services API

 Level 04a

Name Type Description

filters Array of Array of os-message-filter objects to be applied to new operating
os-message- system messages on the identified partition. Each filter is
filter objects considered individually against new OS messages, but all
conditions specified within each os-message-filter must be met in
order for the filter to be considered true. In other words, the logical
operation for evaluating a single filter object's conditions is AND,
whereas all filter objects are evaluated together with OR.

The os-message-filter nested object contains the following fields:

Name Type Description

priority Boolean Filter to select messages based on their priority. True indicates that
a new operating system message passes this filter if its is-priority
property is set to true. False indicates that it passes this filter if
is-priority is false. This field is omitted if priority is not to be
considered by this filter.
held Boolean Filter to select messages based on whether they require a response.
True indicates that a new operating system message passes this
filter if its is-held property is set to true. False indicates that it
passes this filter if is-held is false. This field is omitted if a
response requirement is not to be considered by this filter.
message-text String Filter to select messages based on their message text in order to be
notified when an OS emits specific matching messages. It must be
a valid Java regular expression. To pass this filter, the string regular
expression must match the operating system message's
message-text property. This field is omitted if message text is not
to be considered by this filter.

Description
This operation retrieves the mobile app notification preferences of a CPC for a device from this console.
This specifies what notifications are currently being delivered to the mobile app on the identified device
for the CPC. Note that a device-id may be passed for which an Update CPC Notification Preferences for
Device operation has not been performed. In this case, default values will be returned, as defined in the
“Response body contents” on page 518.

On successful execution, the preference properties are provided in the response body, and HTTP status
code 200 (OK) is returned.

Authorization requirements
This operation has no explicit authorization requirements.

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 518.

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.

Chapter 11. Core IBM Z resources 519

 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.
404 (Not Found) 2 The requested cpc-uri is not known to this console.
409 (Conflict) 329 The operation cannot be performed because the CPC designated by the
request body 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

POST /api/console/operations/get-device-cpc-notification-preferences HTTP/1.1

x-api-session: 64rvm5qub8e2viadxuitl1xfustyhz4wl9j2pcebb1hbyfe0pm
content-type: application/json
content-length: 120
{
"cpc-uri":"/api/cpcs/9724bf69-038b-3152-841a-3ceb8ee21515",
"device-id":"dXgLFgPZGMB06nPRB03nFinn17SW:ugACKp8kZfDgR"
}

Figure 289. Get CPC Notification Preferences for Device: Request

520 HMC Web Services API

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Thu, 07 Dec 2017 15:21:52 GMT
content-type: application/json;charset=UTF-8
content-length: 467
{
"cpc-acceptable-status-change":false,
"new-hardware-message":false,
"new-os-message":[
"/api/logical-partitions/1b7d74fd-6de7-3642-93a6-6c3a1a7488b6"
],
"new-os-message-filtered":[
{
"filters":[
{
"held":true
},
{
"priority":true
}
],
"partition-uri":"/api/logical-partitions/26d3ade6-3cc9-3841-bcc0-f9f2d8b46f0a"
}
],
"partition-acceptable-status-change":[
"/api/logical-partitions/1b7d74fd-6de7-3642-93a6-6c3a1a7488b6",
"/api/logical-partitions/26d3ade6-3cc9-3841-bcc0-f9f2d8b46f0a"
]
}

Figure 290. Get CPC Notification Preferences for Device: Response

Update CPC Notification Preferences for Device

The Update CPC Notification Preferences for Device operation updates the configured mobile app
notification preferences for a CPC to a mobile device.

HTTP method and URI

POST /api/console/operations/update-device-cpc-notification-preferences

Request body contents

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

Name Type Rqd/Opt Description

device-id String Required The unique identifier of the mobile device to which the
preferences being updated belong.
cpc-uri String/URI Required The object-uri property of the CPC for which the
notification preferences apply.
new-hardware-message Boolean Optional True indicates that this console will now be configured to
notify the identified device of new hardware messages for
the identified CPC. False indicates the device will not be
notified.

Note that passing true requires object-access permission to

the identified CPC.

Chapter 11. Core IBM Z resources 521

 Level 04a

Name Type Rqd/Opt Description

cpc-acceptable-status- Boolean Optional True indicates that this console will now be configured to
change notify the identified device of has-unacceptable-status
property changes for the identified CPC. False indicates
the device will not be notified.

Not that passing true requires object-access permission to

the identified CPC.
new-os-message Array of Optional Array of object-uri values of Partition (for DPM) or
String/URI Logical Partition (for non-DPM) objects for which new
operating system message events will notify the identified
device. Any new OS messages on the identified partitions
will cause the identified device to be notified. To limit
which OS messages lead to notifications, refer to
new-os-message-filtered. Note that this list of partitions is
mutually exclusive with those identified in
new-os-message-filtered.

Note that object-access permission is required for each

passed object, but not necessarily for the identified parent
CPC. Additionally, each passed partition object must have
the parent identified by the cpc-uri.
new-os-message-filtered Array of Optional Array of partition-os-message-filter objects defining the
partition-os- Partitions (for DPM) or Logical Partitions (for non-DPM)
message- and the filter conditions for which new operating system
filter objects events will notify the identified device. As opposed to the
new-os-message property which notifies the device of all
OS messages on an identified partition, this allows
notification for only OS messages that pass the filter
conditions. Note that this list of partitions is mutually
exclusive with those identified in new-os-message.

Note that object-access permission is required for each

passed object, but not necessarily for the identified parent
CPC. Additionally, each passed Partition object must have
the parent identified by the cpc-uri.
partition-acceptable- Array of Optional Array of object-uri values of Partition (for DPM) or
status-change String/URI Logical Partition (for non-DPM) objects for which
has-unacceptable-status property changes will notify the
identified device.

Note that object-access permission is required for each

passed object, but not necessarily for the identified parent
CPC. Additionally, each passed partition object must have
the parent identified by the cpc-uri.

The partition-os-message-filter nested object contains the following fields:

Name Type Rqd/Opt Description

partition-uri String/URI Required The object-uri of the Partition (for DPM) or Logical
Partition (for non-DPM) object for which new operating
system message events should notify the identified device
when they pass the defined filters.

522 HMC Web Services API

 Level 04a

Name Type Rqd/Opt Description

filters Array of Required Array of os-message-filter objects to be applied to new
os-message- operating system messages on the identified partition.
filter objects Each filter is considered individually against new OS
messages, but all conditions specified within each
os-message-filter must be met in order for the filter to be
considered true. In other words, the logical operation for
evaluating a single filter object's conditions is AND,
whereas all filter objects are evaluated together with OR.

Note that the array must be non-empty.

The os-message-filter nested object contains the following fields:

Name Type Rqd/Opt Description

priority Boolean Optional Filter to select messages based on their priority. True
indicates that a new operating system message passes this
filter if its is-priority property is set to true. False indicates
that it passes this filter if is-priority is false. Omit this field
if priority is not to be considered by this filter.

Note that at least one filter field is required.

held Boolean Optional Filter to select messages based on whether they require a
response. True indicates that a new operating system
message passes this filter if its is-held property is set to
true. False indicates that it passes this filter if is-held is
false. Omit this field if a response requirement is not to be
considered by this filter.

Note that at least one filter field is required.

message-text String Optional Filter to select messages based on their message text in
order to be notified when an OS emits specific matching
messages. It must be a valid Java regular expression. To
pass this filter, the string regular expression must match
the operating system message's message-text property.
Omit this field if message text is not to be considered by
this filter. If specified, the string must be non-empty.

Note that at least one filter field is required.

Description
This operation updates the mobile app notification preferences of a CPC for a device from this console.
This specifies what notifications are to be delivered to the mobile app on the identified device for the
CPC.

Note that object-access permission to the CPC is required only to turn on the new-hardware-message or
cpc-acceptable-status-change notification properties. For any object-uri included in the new-os-message
array or partition-acceptable-status-change array, only object-access permission to that partition or logical
partition is required.

On successful execution, the notification preference properties are updated for the identified device and
CPC from this console, and HTTP status code 204 (No Content) is returned.

Chapter 11. Core IBM Z resources 523

 Level 04a

Authorization requirements
Object-access permission is required to the CPC to enable notifications for its hardware messages and
acceptable status changes. Object-access permission is required to a logical partition or partition to enable
notifications for its operating system messages or acceptable status changes.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned.

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) 2 The requested cpc-uri is not known to this console, or one of the
CPC-specific notification preferences was asked to be enabled but the user
does not have object-access permission to the CPC.
335 One or more of the requested logical partition or partition URIs is not
known to the identified CPC and/or to this console, or the user does not
have object-access permission to it.
409 (Conflict) 329 The operation cannot be performed because the CPC designated by the
request body 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

POST /api/console/operations/update-device-cpc-notification-preferences HTTP/1.1

x-api-session: 2u80csmk000d1mjpgevfavmhodr71eb2ilocsvbvw6weng0ma8
content-type: application/json
content-length: 318
{
"cpc-acceptable-status-change":false,
"cpc-uri":"/api/cpcs/ded1343f-c248-3fc0-afb4-8e54a2ea9647",
"device-id":"f99e434d-6a38-3487-b331",
"new-hardware-message":true,
"new-os-message":[
"/api/logical-partitions/5709de82-63ee-370f-9928-3a1331332acc",
"/api/logical-partitions/5989e5ec-b820-37ae-b5f7-81c476a96885"
]
}

Figure 291. Update CPC Notification Preferences for Device: Request

524 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Fri, 18 Nov 2016 21:12:06 GMT

<No response body>

Figure 292. Update CPC Notification Preferences for Device: Response

Inventory service data

Information about the console can be optionally included in the inventory data provided by the Inventory
Service.

Inventory entries for the Console objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "console" are to be included.

For each Console object to be included, the inventory response array includes an entry that is a JSON
object with the same contents as is specified in the response body contents section for “Get Console
Properties” on page 488. That is, the data provided is the same as would be provided if a Get Console
Properties operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single console. This object would appear as one array entry in the response array:

Chapter 11. Core IBM Z resources 525

 Level 04a

{
"class": "console",
"description": "Endicott Test HMC",
"ec-mcl-description": {
"ec": [
{
"description": "Hardware Management Console Framework",
"mcl": [
{
"last-update": 1422026097000,
"level": "39",
"type": "retrieved"
},
{
"last-update": 1423074018000,
"level": "39",
"type": "activated"
},
{
"last-update": null,
"level": "000",
"type": "accepted"
},
{
"last-update": null,
"level": "39",
"type": "installable-concurrent"
},
{
"last-update": null,
"level": "1",
"type": "removable-concurrent"
}
],
"number": "N98841",
"part-number": "00LY737",
"type": "SYSTEM"
},

Figure 293. Console object: Sample inventory data (Part 1)

526 HMC Web Services API

 Level 04a

{
"description": "Enablement of new features ",
"mcl": [
{
"last-update": null,
"level": "000",
"type": "retrieved"
},
{
"last-update": null,
"level": "000",
"type": "activated"
},
{
"last-update": null,
"level": "000",
"type": "accepted"
},
{
"last-update": null,
"level": "000",
"type": "installable-concurrent"
},
{
"last-update": null,
"level": "000",
"type": "removable-concurrent"
}
],
"number": "N98844",
"part-number": "00LY740",
"type": "ENABLE1"
}
]
},

Figure 294. Console object: Sample inventory data (Part 2)

Chapter 11. Core IBM Z resources 527

 Level 04a

"ip-swapping-available": true,
"is-auto-switch-enabled": true,
"is-locked": false,
"machine-info": {
"machine-model": "PBC",
"machine-serial": "KQ0N5RF",
"machine-type": "7382"
},
"name": "ZFXHMC2",
"network-info": {
"paired-hmc": {
"hmc-name": "ZFXHMC1",
"ipv4-address": [
"9.60.15.110",
"9.60.14.110"
],
"ipv6-address": [
"2002:93c:ffb:1:5ef3:fcff:feaf:deb1",
"fdd8:673b:d89b:1:5ef3:fcff:feaf:deb1",
"fe80:0:0:0:5ef3:fcff:feaf:deb1"
]
},
"this-hmc": [
{
"domain-name": "",
"hmc-name": "ZFXHMC2",
"interface-name": "eth0",
"ipv4-address": [
{
"ip-address": "9.60.15.111",
"subnet-mask": "255.255.255.0"
}
],
"ipv6-address": [
{
"ip-address": "2002:93c:ffb:1:5ef3:fcff:feae:8019",
"prefix-length": 64
},
{
"ip-address": "fdd8:673b:d89b:1:5ef3:fcff:feae:8019",
"prefix-length": 64
},
{
"ip-address": "fe80:0:0:0:5ef3:fcff:feae:8019",
"prefix-length": 64
}
],
"is-private": false,
"mac": "5CF3FCAE8019"
},

Figure 295. Console object: Sample inventory data (Part 3)

528 HMC Web Services API

 Level 04a

{
"domain-name": "",
"hmc-name": "ZFXHMC2",
"interface-name": "eth1",
"ipv4-address": [
{
"ip-address": "9.60.14.111",
"subnet-mask": "255.255.255.0"
}
],
"ipv6-address": [
{
"ip-address": "fe80:0:0:0:5ef3:fcff:feae:801a",
"prefix-length": 64
}
],
"is-private": false,
"mac": "5CF3FCAE801A"
}
]
},
"object-id": "ec982d6c-bcc1-3ae8-b39c-a2efd14734b4",
"object-uri": "/api/console",
"paired-role": "primary",
"parent": null,
"version": "2.13.0"
}

Figure 296. Console object: Sample inventory data (Part 4)

User-related-access permission
An HMC user has access to certain information about their own user account. This information is
contained in their User object and related objects. An API user's access permission to their own User
object and specific related objects is known as user-related-access permission. Through such permission,
those objects will be included in a List <class> operation, unless otherwise filtered out, and the API user
is permitted to issue a Get <class> Properties operation on them, unless specifically prohibited.

The object types included in user-related-access permission are:

v User
v User Role
v User Pattern
v Password Rule
v LDAP Server Definition

User-related-access permission includes the following:

v Permission for an object of the above types to be included in the response body of a List <class>
operation.
v Permission to view properties of objects of the following types through the Get <class> Properties and
Get Inventory operations:
– User
– User Role
– User Pattern
– Password Rule

Chapter 11. Core IBM Z resources 529

 Level 04a

v Permission to update certain properties of the User object. See the “Data model” or the Update User
Properties operation for details.

User object
A User object represents a single Hardware Management Console user. There are different types of
console users. A typical customer-defined user is known as a standard user. A user template defines
certain attributes of a group of users whose user IDs match the expression in a User Pattern; these
definitions are known as template users. When a user logs on with a user ID that matches the expression
in a User Pattern, a pattern-based user is created. There are certain user definitions supplied by the
system; they are known as system-defined users.

All API users are permitted to see their own User object in a List Users response, issue Get User
Properties for their own User object and, with the exception of pattern-based users, issue Update User
Properties to alter certain properties of their own User object. An API user with action/task permission
to the Manage Users task is permitted to view and change any standard or system-defined User object.
An API user with action/task permission to the Manage User Templates task is permitted to view and
change any template User object.

User objects may be replicated to this HMC via its Data Replication facility. If that is the case, the Update
User Properties, Add User Role to User, Remove User Role from User and Delete User operations
should be used with care as they will prevent further replication of the modified or deleted object to this
HMC.

System-defined users
In most respects, system-defined users are indistinguishable from standard users. They can be modified
or even deleted. Most properties of system-defined users may be changed, but certain others are
immutable; the immutable properties are denoted as such in the data model section that follows. While
system-defined users can be deleted and their name reused for a standard user definition, that practice is
discouraged due to the likely confusion such a situation would cause. The typical system-defined users
include the following:
v ACSADMIN
v ADVANCED
v ENSADMIN
v ENSOPERATOR
v OPERATOR
v SERVICE
v SYSPROG
| v STORAGEADMIN

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
but does not provide the operational-status-related properties defined in that schema because it does not
maintain the concept of an operational status.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

The following class-specific specializations apply to the other base managed object properties:

530 HMC Web Services API

 Level 04a

Table 273. User object: base managed object properties specializations

Name Qualifier Type Description of specialization
object-uri — String/URI The canonical URI path of the User object is of the form
/api/users/{user-id}, where {user-id} is the value of the object-id
property (not the name property) of the User object.
parent — String/URI The canonical URI path of the Console object.
class — String The class of a User object is "user".
name (ro) String If type is not "template": the name (console user ID) of the User
object. It must be 4-320 characters in length and consist only of
alphanumeric characters, spaces and the following special
characters: “@<+:#'="&*();-/\,%_>.?”. This name must be unique
among all users whose type is not "template" defined on the
console. While preexisting names may contain a double quote (")
character, it is not permitted in new user names.

If type is "template": the name of the template. While preexisting

template names are virtually unrestricted in terms of length and
characters, new template names must conform to the length and
character requirement of the name property described in the “Base
managed object properties schema” on page 60. This name must be
unique among all template definitions on the console.

For the purpose of verifying uniqueness only, this name is treated

in a case-insensitive fashion when used to create a new User object
of any type.
description (w)(pc) String The description of the User object.
(0-1024)
Default: an empty string

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:

Note: Some properties are only valid for users of a specific type. Such properties are only included in the
User object if the user is of that type, as indicated by its type property. For example, a user with a type of
"standard" includes the disabled property but not the user-pattern-uri property.

Certain properties are only valid when mutable prerequisite properties have specific values. When such
properties are not valid, their value is null. For instance the password-rule-uri is null when the
authentication-type value is "ldap".
Table 274. User object: class specific additional properties
Name Qualifier Type Description
type — String Enum The type of user. Supported values are:
v "standard" - a standard, normal user.
v "template" - a user template.
v "pattern-based" - a user created dynamically from a User
Pattern and its associated template.
v "system-defined" - a user supplied by the system. Certain
properties of system-defined users are immutable.
user-pattern-uri — String/URI The canonical URI path of the User Pattern object upon
which this user is based.

Prerequisite: type is "pattern-based"

Chapter 11. Core IBM Z resources 531

 Level 04a

Table 274. User object: class specific additional properties (continued)

Name Qualifier Type Description
disabled (w)(pc) Boolean Indicates whether the user is currently disabled. When
disabled, the user is prevented from logging on to the
console via either the UI or the Web Services APIs.

Prerequisite: type is not "template".

Default: false
authentication-type (w)(pc) String Enum The type of user ID and password authentication used for
this user, which must be one of the following:
v "local" - the console performs the authentication.
v "ldap" - authentication is delegated to the LDAP server
identified in the ldap-server-definition-uri property.

If type is "template", this must be "ldap".

Note: The value of this property is a prerequisite for certain
other properties. Changing this value requires certain
properties to be included in the same request; see the
Update User Properties operation for details.
password-rule-uri (w)(pc) String/URI The canonical URI path of the Password Rule for this user.

Prerequisite: authentication-type is "local".

password (wo)(pc) String The console logon password for this user. The specific
length, character and other requirements on this password
are controlled by the authentication type and Password Rule
assigned to this user.

Note the (wo) qualifier; this field may be altered via an API,
but it is not included in the response when this object's
properties are retrieved via an API.
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.
force-password- (w)(pc) Boolean Indicates whether the user should be forced to change their
change console logon password the next time they log in.

Prerequisite: authentication-type is "local"

Default: true
ldap-server-definition- (w)(pc) String/URI The canonical URI path of the configuration object for the
uri LDAP server used for authentication of this user.

Prerequisite: authentication-type is "ldap".

userid-on-ldap-server (w)(pc) String (0-32) The user ID for this user on the LDAP server identified in
ldap-server-definition-uri, or null if the user's console user
ID (value of the name property) should be used. See the
LDAP Server Definition object for more information on how
this property is used.

Prerequisite: authentication-type is "ldap" and type is not

"template".

Default: an empty string

532 HMC Web Services API

 Level 04a

Table 274. User object: class specific additional properties (continued)

Name Qualifier Type Description
session-timeout (w)(pc) Integer The session timeout in minutes for this user. This is the
(0-525600) interval over which a user's UI session can run before being
prompted for identity verification. 0 indicates no timeout.

Default: 0
verify-timeout (w)(pc) Integer The verification timeout in minutes for this user. This is the
(0-525600) amount of time allowed for the user to re-enter their
password after being prompted due to a session timeout
(see the session-timeout property). 0 indicates no timeout.

Default: 15
idle-timeout (w)(pc) Integer The idle timeout in minutes for this user. This is the amount
(0-525600) of time the user's UI session can be idle before it is
disconnected. 0 indicates no timeout.

Default: 0
min-pw-change-time (w)(pc) Integer The minimum password change time in minutes for this
(0-525600) user. This is the minimum amount of time that must elapse
between changes to this user's password. 0 indicates no
minimum; that is, the password can be changed
immediately after it has just been changed.

Prerequisite: authentication-type is "local".

Default: 0
max-failed-logins (w)(pc) Integer The maximum number of failed login attempts for this user.
(0-525600) This is maximum number of consecutive failed login
attempts before the user is temporarily disabled for the
amount of time specified in the disable-delay property. 0
indicates that the user is never disabled due to failed login
attempts.

Default: 3
disable-delay (w)(pc) Integer The time in minutes that the user is disabled after exceeding
(0-525600) the maximum number of failed login attempts specified in
the max-failed-logins property. 0 indicates that the user is
not disabled for any period of time after reaching the
maximum number of invalid login attempts.

Default: 1
inactivity-timeout (w)(pc) Integer The inactivity timeout in days for this user. This is the
(0-525600) maximum number of days of inactivity (consecutive days
with no login) before the user is disabled. 0 indicates no
timeout.

Default: 0
disruptive-pw- (w)(pc) Boolean Indicates whether the user's password is required to
required perform disruptive actions via the UI.

Default: true
disruptive-text- (w)(pc) Boolean Indicates whether text input is required to perform
required disruptive actions via the UI.

Default: false

Chapter 11. Core IBM Z resources 533

 Level 04a

Table 274. User object: class specific additional properties (continued)

Name Qualifier Type Description
allow-remote-access (w)(pc) Boolean Indicates whether the user is allowed to access the HMC via
its remote web server interface

Default: false
allow-management- (w)(pc) Boolean Indicates whether the user is allowed access to management
interfaces interfaces. This includes access to the Web Services APIs.

Default: false
max-web-services-api- (w)(pc) Integer The maximum number of simultaneous Web Services API
sessions (0-9999) sessions the user is permitted to have.

Default: 100
web-services-api- (w)(pc) Integer The idle timeout in minutes for Web Services API sessions
session-idle-timeout (1-360) created by this user. This is the amount of time a Web
Services API session can be idle before it is terminated.

Default: 360
user-roles (c)(pc) Array of The list of user roles defined for this user. Each element in
String/URI this array is a canonical URI path for a User Role object. The
roles provided in this list can change as a result of the Add
User Role to User and Remove User Role from User
operations.

This property is immutable if type is "system-defined".

default-group-uri (w)(pc) String/URI The canonical URI path of the user's default group or null if
the user has no default group. Managed objects created by
this user automatically become members of this group. The
user must have object-access permission to this group. This
must be a user-defined group to which the user has
object-access permission.

API users are permitted to change their own default group

designation via the Update User Properties operation.

Default: null
replication-overwrite- — Boolean Indicates whether this object is customizable data that is
possible replicated to this HMC from an HMC configured as a Data
Source in the Data Replication service.
multi-factor- (w)(pc) Boolean Indicates whether the user is required to enter their current
authentication- multi-factor authentication code (time-based one-time
required password) in addition to their logon password during UI
and API logons.

Default: false
force-shared-secret- (w)(pc) Boolean Indicates whether the user is required to establish a new
key-change shared secret key during the next logon. The shared secret
key is used to calculate the user's current multi-factor
authentication code, which is required during logon.

Prerequisite: multi-factor-authentication-required is true

Default: false
| email-address (w)(pc) String (0-254) The user's email address or null if the user has no email
| address. This email address must roughly adhere to Internet
| Engineering Task Force (IETF) RFC 822.

534 HMC Web Services API

 Level 04a

List Users
The List Users operation lists standard, template and system-defined users defined to the console. With
one very specific exception, pattern-based users are never included in the response to the List Users
operation.

HTTP method and URI

GET /api/console/users

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 type
Enum property. Value must be a valid type property value, with the exception
of "pattern-based".

Response body contents

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

Field name Type Description

users Array of Array of nested user-info objects as described in the next table.
objects

Each nested user-info object contains the following fields:

Field name Type Description

object-uri String/URI The object-uri property of the User object.
name String The name property of the User object.
type String The type property of the User object.
Enum

Description
The List Users operation lists users defined to the console. Some basic properties are provided for each
user.

If the name query parameter is specified, the returned list is limited to those users that have a name
property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
performed.

If the type query parameter is specified, the parameter is validated to ensure it is a valid user type
property value for this operation. If the value is not valid, status code 400 (Bad Request) is returned. If
the value is valid, the returned list is limited to those users that have a type property matching the
specified value. If the type parameter is omitted, this filtering is not performed.

A user is included in the list only if the API user has sufficient access permission to that object. The
access permission requirements for User objects vary depending on the type of User object. All API users
have user-related-access permission to their own User object. Action/task permission to the Manage
Users task includes access permission to all non-template Users, and action/task permission to the

Chapter 11. Core IBM Z resources 535

 Level 04a

Manage User Templates task includes access permission to all template users. If there is a User object to
which the API user does not have permission, that object is omitted from the list, but no error status code
results.

A pattern-based user is only included in the response if it meets the filtering criteria and is the User
object for the API user.

If there are no users defined to the console or if no users are to be included in the results 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 User-related-access permission to the User object included in the response body, or, depending on the
type of User object, action/task permission to the Manage Users task or the Manage User Templates
task.

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 535.

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.
Table 275. List Users: 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.

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/users?type=system-defined&name=.*ADMIN HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 297. List Users: Request

536 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:30 GMT
content-type: application/json;charset=UTF-8
content-length: 225
{
"users":[
{
"name":"ACSADMIN",
"object-uri":"/api/users/ae8aed68-3dc0-11e4-8dd1-1c6f65065a91",
"type":"system-defined"
},
{
"name":"ENSADMIN",
"object-uri":"/api/users/ae6bf048-3dc0-11e4-8dd1-1c6f65065a91",
"type":"system-defined"
}
]
}

Figure 298. List Users: Response

Get User Properties

The Get User Properties operation retrieves the properties of a single User object that is designated by its
object ID. With one very specific exception, this operation does not support pattern-based users.

HTTP method and URI

GET /api/users/{user-id}

In this request, the URI variable {user-id} is either the object ID of the User object whose properties are to
be returned or the keyword value "this-user" which designates the API user that issued the request.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the User object as defined in the data model section. Field names and data types in the
JSON object are the same as the property names and data types defined in the “Data model” on page
530.

Description
This operation returns the current properties of a single User object that is designated by {user-id}.

On successful execution, all of the current properties as defined in the data model for the User object,
except those designated as write-only properties, are provided in the response body, and HTTP status
code 200 (OK) is returned.

The URI path must designate an existing User object and the API user must have access permission to it.
All API users have user-related-access permission to their own User object. Action/task permission to the
Manage Users task includes access permission to all non-template Users, and action/task permission to
the Manage User Templates task includes access permission to all template users. If the URI path does
not designate an existing User object or the API user does not have access permission to it, status code
404 (Not Found) is returned.

Chapter 11. Core IBM Z resources 537

 Level 04a

This operation does not support pattern-based users, unless the target of the operation is the User object
for the API user that issued the request.

Authorization requirements
This operation has the following authorization requirement:
v User-related-access permission to the User object specified in the request URI, or, depending on the
type of User object specified in the request URI, action/task permission to the Manage Users task or
the Manage User Templates task.

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 537.

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 request URI does not designate an existing resource of the correct type,
or designates a resource for which the API user does not have the required
authorization.

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/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 299. Get User Properties: Request

538 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
| date: Thu, 02 Aug 2018 21:27:30 GMT
content-type: application/json;charset=UTF-8
| content-length: 1218
{
"allow-management-interfaces":false,
"allow-remote-access":false,
"authentication-type":"local",
"class":"user",
"default-group-uri":null,
"description":"Gabby McRosie - company president",
"disable-delay":1,
"disabled":false,
"disruptive-pw-required":true,
"disruptive-text-required":false,
| "email-address":"finn@example.com",
"force-password-change":true,
"force-shared-secret-key-change":false,
"idle-timeout":0,
"inactivity-timeout":0,
"is-locked":false,
"ldap-server-definition-uri":null,
"max-failed-logins":3,
"max-web-services-api-sessions":100,
"min-pw-change-time":0,
"multi-factor-authentication-required":true,
"name":"Gabby",
"object-id":"e9e8d20a-4a7a-11e4-91ee-1c6f65065a91",
"object-uri":"/api/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91",
"parent":"/api/console",
"password-expires":-1,
"password-rule-uri":"/api/console/password-rules/4a790766-3dbf-11e4-980d-1c6f65065a91",
"replication-overwrite-possible":false,
"session-timeout":0,
"type":"standard",
"user-roles":[
"/api/user-roles/ea6f9b14-4a7a-11e4-affa-1c6f65065a91",
"/api/user-roles/ea41a664-4a7a-11e4-91ee-1c6f65065a91",
"/api/user-roles/ea094df0-4a7a-11e4-8777-1c6f65065a91"
],
"userid-on-ldap-server":null,
"verify-timeout":15,
"web-services-api-session-idle-timeout":360
}

Figure 300. Get User Properties: Response

Update User Properties

The Update User Properties operation updates the properties of a single User object that is designated by
its object ID. This operation is not valid for pattern-based users.

HTTP method and URI

POST /api/users/{user-id}

In this request, the URI variable {user-id} is the object ID of the User object whose properties are to be
updated or the special keyword value "this-user" which designates the API user that issued the request.

Chapter 11. Core IBM Z resources 539

 Level 04a

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
This operation updates writable properties of the User object specified by {user-id}.

The URI path must designate an existing User object and the API user must have permission to update it.
All API users have user-related-access permission to their own User object, which includes permission to
update certain properties. Action/task permission to the Manage Users task includes update permission
to all non-template users, and action/task permission to the Manage User Templates task includes
update permission to all template users. If the URI path does not designate an existing User object, status
code 404 (Not Found) is returned. If the API user does not have user-related-access permission to the
designated User object or action/task permission to the Manage Users or Manage User Templates task,
whichever is appropriate, status code 404 (Not Found) is returned. If the API user does not have
action/task permission to the Manage Users or Manage User Templates task, whichever is appropriate,
an attempt to update any field other than the user's own password or default-group-uri field results in
status code 403 (Forbidden), and specifying a group to which the API user does not have object-access
permission in default-group-uri results in status code 404 (Not Found).

The request body is validated against the schema described in the request body contents section. If the
request body is not valid, status code 400 (Bad Request) or 409 (Conflict) is returned with a reason code
indicating the validation error encountered. The request body validation will fail if it contains a property
that is not valid because a prerequisite is not met (e.g., attempting to set password-rule-uri when the
authentication-type value is "ldap"). An attempt to update a pattern-based user is not valid and fails
with status code 400 (Bad Request).

The request body does not need to specify a value for all writable properties, but rather can and should
contain fields only for the properties to be updated. Object properties for which no input value is
provided and no prerequisite property is changed remain unchanged by this operation. A property's
value is set to its default value if the field is not included in the request body and a prerequisite field is
changed such that the prerequisite condition becomes satisfied (e.g., if authentication-type is changed
from "ldap" to "local", and force-password-change is not defined in the request body,
force-password-change will be defaulted to false). Note however that certain fields must be included in
the request body if the request alters the authentication-type property, because they are required in order
to perform the newly specified type of logon authentication. Specifically, changing authentication-type to
"local" requires that the following properties also be specified in the same request: password,
password-rule-uri. Changing authentication-type to "ldap" requires that the following property also be
specified: ldap-server-definition-uri.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v For a user to update their own password or default-group-uri property, user-related-access permission
to the User object specified in the request URI or action/task permission to the Manage Users task is
required.

540 HMC Web Services API

 Level 04a

v An API user with action/task permission to the Manage Users task or the Manage User Templates
task, depending on the type of User object specified in the request URI, may update any writable
property of that User object.

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.
Table 276. Update User Properties: HTTP status and reason codes.
HTTP error status
code Reason 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.
311 The new password does not conform to the requirements of the password
policy in effect for this user.
314 This operation is not supported for an object of this type. Pattern-based
users may not be updated.
330 The operation is not valid because the API user cannot disable their own
user ID.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type,
or designates a resource for which the API user does not have the required
authorization.
323 The password-rule-uri field in the request body does not designate an
existing Password Rule object.
324 The ldap-server-definition-uri field in the request body does not designate
an existing LDAP Server Definition object.
325 The default-group-uri field in the request body does not designate an
existing resource of the expected type, or designates a resource for which the
user identified by the request URI does not have object-access permission.
409 (Conflict) 8 The request body contains a field whose presence or value is inconsistent
with the current state of the User object.
321 The user's authentication-type property cannot be changed at this time. The
specified user is currently the only locally-authenticated user with
permission to the tasks for managing users and user roles.

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

Chapter 11. Core IBM Z resources 541

 Level 04a

Example HTTP interaction

POST /api/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 145
{
"allow-management-interfaces":true,
"description":"A new and improved description of this User",
"web-services-api-session-idle-timeout":240
}

Figure 301. Update User Properties: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:30 GMT

<No response body>

Figure 302. Update User Properties: Response

Add User Role to User

The Add User Role to User operation adds a specified User Role to a specified user. This operation is not
valid for system-defined or pattern-based users.

HTTP method and URI

POST /api/users/{user-id}/operations/add-user-role

In this request, the URI variable {user-id} is the object ID of the user to which a User Role is to be added
or the special keyword value "this-user" which designates the API user that issued the request.

Request body contents

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

Field name Type Rqd/Opt Description

user-role-uri String/ Required The canonical URI path of the User Role to be added.
URI

Description
This operation adds a User Role to a user.

On successful execution of this operation the User Role specified in the request body has been added to
the user identified in the request URI.

The request body is validated against the schema described in “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered. If the request URI does not designate an existing User object, status code 404 (Not
Found) is returned. If the API user does not have user-related-access permission to the designated User
object or action/task permission to the Manage Users or Manage User Templates task, whichever is
appropriate, status code 404 (Not Found) is returned. If the API user has user-related-access permission to

542 HMC Web Services API

 Level 04a

the designated User object but not action/task permission to the Manage Users or Manage User
Templates task, whichever is appropriate, status code 403 (Forbidden) is returned. If the request body
does not designate an existing User Role, status code 404 (Not Found) is returned. If the specified object
is already in the collection of the user's User Roles, status code 409 (Conflict) is returned. An attempt to
update the User Role collection of a system-defined or pattern-based user is not valid and fails with
status code 400 (Bad Request).

If this operation changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage Users task to modify a standard user or the Manage User
Templates task to modify a template user.

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.
Table 277. Add User Role to User: 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.
314 This operation is not supported for an object of this type. The User Role
collection of system-defined and pattern-based users may not be altered.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
2 A URI in the request body does not designate an existing resource of the
correct type.
409 (Conflict) 315 The object designated by the URI in the request body is already in the user's
collection of User Roles.

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

Chapter 11. Core IBM Z resources 543

 Level 04a

Example HTTP interaction

POST /api/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91/operations/add-user-role HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 73
{
"user-role-uri":"/api/user-roles/eaecdf34-4a7a-11e4-8777-1c6f65065a91"
}

Figure 303. Add User Role to User: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:31 GMT

<No response body>

Figure 304. Add User Role to User: Response

Remove User Role from User

The Remove User Role from User operation removes a specified User Role from a specified user. This
operation is not valid for system-defined or pattern-based users.

HTTP method and URI

POST /api/users/{user-id}/operations/remove-user-role

In this request, the URI variable {user-id} is the object ID of the user from which a User Role is to be
removed or the special keyword value "this-user" which designates the API user that issued the request.

Request body contents

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

Field name Type Rqd/Opt Description

user-role-uri String/ Required The canonical URI path of the User Role to be removed.
URI

Description
This operation removes a User Role from a user.

On successful execution of this operation the User Role specified in the request body has been removed
from the user identified in the request URI.

The request body is validated against the schema described in “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered. If the request URI does not designate an existing User object, status code 404 (Not
Found) is returned. If the API user does not have user-related-access permission to the designated User
object or action/task permission to the Manage Users or Manage User Templates task, whichever is
appropriate, status code 404 (Not Found) is returned. If the API user has user-related-access permission to
the designated User object but not action/task permission to the Manage Users or Manage User

544 HMC Web Services API

 Level 04a

Templates task, whichever is appropriate, status code 403 (Forbidden) is returned. If the specified object
is not in the collection of the user's User Roles, status code 409 (Conflict) is returned. An attempt to
update the User Role collection of a system-defined or pattern-based user is not valid and fails with
status code 400 (Bad Request).

If this operation changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage Users task to modify a standard user or the Manage User
Templates task to modify a template user.

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.
Table 278. Remove User Role from User: 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.
314 This operation is not supported for an object of this type. The User Role
collection of system-defined and pattern-based users may not be altered.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
2 A URI in the request body does not designate an existing resource of the
correct type.
409 (Conflict) 316 The object designated by the URI in the request body is not in the user's
collection of User Roles.
321 The User Role cannot be removed at this time. The user is currently the only
locally-authenticated user with permission to the tasks for managing users
and user roles.
328
The User Role cannot be removed at this time, because doing so would leave
the user without object-access permission to their default group.

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

Chapter 11. Core IBM Z resources 545

 Level 04a

Example HTTP interaction

POST /api/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91/operations/remove-user-role HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 73
{
"user-role-uri":"/api/user-roles/eaecdf34-4a7a-11e4-8777-1c6f65065a91"
}

Figure 305. Remove User Role from User: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:31 GMT

<No response body>

Figure 306. Remove User Role from User: Response

Create User
The Create User operation creates a standard or template User object with the given properties. This
operation is not valid for system-defined or pattern-based users.

HTTP method and URI

POST /api/console/users

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The value to be set as the user's name property.

Note that the length and character requirements that

apply to this field are dependent on the value of the type
field.
description String Optional The value to be set as the user's description property.
type String Required The value to be set as the user's type property. Must be
Enum "standard" or "template".
disabled Boolean Optional The value to be set as the user's disabled property.
authentication- String Required The value to be set as the user's authentication-type
type Enum property.
password-rule-uri String/URI Required if The value to be set as the user's password-rule-uri
authentication-type property.
is "local"
password String Required if The value to be set as the user's password property.
authentication-type
is "local"
force-password- Boolean Optional The value to be set as the user's force-password-change
change property.

546 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

ldap-server- String/URI Required if The value to be set as the user's ldap-server-definition-
definition-uri authentication-type uri property.
is "ldap"
userid-on-ldap- String Optional The value to be set as the user's userid-on-ldap-server
server property.
session-timeout Integer Optional The value to be set as the user's session-timeout property.
verify-timeout Integer Optional The value to be set as the user's verify-timeout property.
idle-timeout Integer Optional The value to be set as the user's idle-timeout property.
min-pw-change-time Integer Optional The value to be set as the user's min-pw-change-time
property.
max-failed-logins Integer Optional The value to be set as the user's max-failed-logins
property.
disable-delay Integer Optional The value to be set as the user's disable-delay property.
inactivity-timeout Integer Optional The value to be set as the user's inactivity-timeout
property.
disruptive-pw- Boolean Optional The value to be set as the users disruptive-pw-required
required property.
disruptive-text- Boolean Optional The value to be set as the user's disruptive-text-required
required property.
allow-remote- Boolean Optional The value to be set as the user's allow-remote-access
access property.
allow-management- Boolean Optional The value to be set as the user's allow-management-
interfaces interfaces property.
max-web-services- Integer Optional The value to be set as the user's max-web-services-api-
api-sessions sessions property.
web-services-api- Integer Optional The value to be set as the user's web-services-api-session-
session-idle- idle-timeout property.
timeout
multi-factor- Boolean Optional The value to be set as the user's multi-factor-
authentication- authentication-required property.
required

Response body contents

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

Field name Type Description

object-uri String/URI Canonical URI path of the new User object.

Description
This operation creates a new console user.

On successful execution of this operation the user is created using the inputs as specified by the request
body. The URI of the new user is provided in the response body and in a Location response header as
well. An Inventory Change notification is emitted asynchronously.

The request body is validated against the schema described in the “Request body contents” on page 546.
If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating

Chapter 11. Core IBM Z resources 547

 Level 04a

the validation error encountered. The request body validation will fail if it contains a property that is not
valid because a prerequisite is not met (e.g., specifying password-rule-uri when the authentication-type
value is "ldap") or the specified name is not unique. If a URI in the request body does not designate an
existing resource of the appropriate type, status code 404 (Not Found) is returned. In addition, the API
user must have action/task permission to the Manage Users task to create a standard user or the
Manage User Templates task to create a template user; otherwise, status code 403 (Forbidden) is
returned.

Certain user names are used internally by the Hardware Management Console and are therefore not
available for use when creating a new user. An attempt to create a user with one of these names results
in status code 400 (Bad Request) indicating that there is already a user with that name. The list of such
names is case-insensitive and includes the following:
v SOOACSADMIN
v SOOSERVICE
v SOOSYSPROG
v SOOADVANCED
v SOOOPERATOR
v SOOENSADMIN
v SOOENSOPERATOR
v SOOSTORAGEADMIN
v PEDEBUG

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage Users task to create a standard user or the Manage User
Templates task to create a template user.

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 547, and the Location response header contains the URI of the
newly created object.

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.
Table 279. Create User: 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 user with the name specified in the request body already exists.
311 The password does not conform to the requirements of the password policy
in effect for this user.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 323 The password-rule-uri field in the request body does not designate an
existing Password Rule object.
324 The ldap-server-definition-uri field in the request body does not designate
an existing LDAP Server Definition object.

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

548 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/console/users HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 234
{
"authentication-type":"local",
"description":"Gabby McRosie - company president",
"name":"Gabby",
"password":"abc123pw",
"password-rule-uri":"/api/console/password-rules/4a790766-3dbf-11e4-980d-1c6f65065a91",
"type":"standard"
}

Figure 307. Create User: Request

201 Created
server: zSeries management console API web server / 2.0
location: /api/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:29 GMT
content-type: application/json;charset=UTF-8
content-length: 64
{
"object-uri":"/api/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91"
}

Figure 308. Create User: Response

Delete User
The Delete User operation deletes a User object designated by its object ID. This operation is not valid
for pattern-based users.

HTTP method and URI

DELETE /api/users/{user-id}

In this request, the URI variable {user-id} is the object ID of the User object to be deleted.

Description
This operation removes a specified user from the console. The user is identified by the {user-id} variable
in the URI.

Upon successfully removing the user, HTTP status code 204 (No Content) is returned and no response
body is provided. An Inventory Change notification is emitted asynchronously.

The URI path must designate an existing User object; otherwise, status code 404 (Not Found) is returned.
If the API user does not have user-related-access permission to the designated User object or action/task
permission to the Manage Users or Manage User Templates task, whichever is appropriate, status code
404 (Not Found) is returned. If the API user has user-related-access permission to the designated User
object but not action/task permission to the Manage Users or Manage User Templates task, whichever is
appropriate, status code 403 (Forbidden) is returned. It is an error for an API user to attempt to delete his
own User object; any attempt to do so results in status code 400 (Bad Request). If the request URI
identifies a template user, and a user or a User Pattern refers to that template user, the request fails and

Chapter 11. Core IBM Z resources 549

 Level 04a

status code 409 (Conflict) is returned. An attempt to delete a pattern-based user is not valid and fails with
status code 400 (Bad Request).

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage Users task to delete a non-template user, or the Manage User
Templates task to delete a template user.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned 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.
Table 280. Delete User: 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.
312 This operation is not supported for an object of this type. Pattern-based
users may not be deleted.
313 The request URI designates the API user's own User object.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
409 (Conflict) 317 The object cannot be deleted at this time. One or more users or User Patterns
refer to this template user.
320 The object cannot be deleted at this time. It is currently identified as the
Automatic Logon ID for the Hardware Management Console.
321 The object cannot be deleted at this time. It is currently the only
locally-authenticated user with permission to the tasks for managing users
and user roles.

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/users/e9e8d20a-4a7a-11e4-91ee-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 309. Delete User: Request

550 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:31 GMT

<No response body>

Figure 310. Delete User: Response

Inventory service data

Information about the users managed by the console can be optionally included in the inventory data
provided by the Inventory Service.

Inventory entries for User objects are included in the response to the Inventory Service's Get Inventory
operation when the request specifies (explicitly by class, implicitly via a containing category, or by
default) that objects of class "user" are to be included. An entry for a particular user is included only if
the API user has access permission to that object as described in the Get User Properties operation.

For each User object to be included, the inventory response array includes an entry that is a JSON object
with the same contents as is specified in the response body contents section for the Get User Properties
operation. That is, the data provided is the same as would be provided if a Get User Properties
operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single user. This object would appear as one array entry in the response array:

Chapter 11. Core IBM Z resources 551

 Level 04a

{
"allow-management-interfaces": false,
"allow-remote-access": false,
"authentication-type": "ldap",
"class": "user",
"default-group-uri": "/api/groups/fc400fc6-54e3-335d-854f-a0a6d10f000b",
"description": "System admnistrator",
"disable-delay": 1,
"disabled": false,
"disruptive-pw-required": true,
"disruptive-text-required": false,
| "email-address":"finn@example.com",
"force-password-change": null,
"force-shared-secret-key-change":false,
"idle-timeout": 0,
"inactivity-timeout": 0,
"is-locked": false,
"ldap-server-definition-uri": "/api/console/ldap-server-definitions/
4927787e-34c4-11e4-a1ea-5ef3fcae8020",
"max-failed-logins": 3,
"max-web-services-api-sessions": 100,
"min-pw-change-time": null,
"multi-factor-authentication-required":true,
"name": "sysadmin",
"object-id": "9069f7a6-34c5-11e4-af4d-5ef3fcae8020",
"object-uri": "/api/users/9069f7a6-34c5-11e4-af4d-5ef3fcae8020",
"parent": "/api/console",
"password-expires": -1,
"password-rule-uri": null,
"replication-overwrite-possible": false,
"session-timeout": 0,
"type": "standard",
"user-roles": [
"/api/user-roles/b39afb87-d915-4070-a22f-91b158c6c01e"
],
"userid-on-ldap-server": "sysadmin",
"verify-timeout": 15,
"web-services-api-session-idle-timeout": 15
}

Figure 311. User object: Sample inventory data

User Role object

A User Role object represents an authority role which can be assigned to one or more console users. A
role may allow access to specific managed objects, classes of managed objects, groups and/or tasks. There
are two types of User Roles: user-defined and system-defined. User-defined User Roles are created by a
console user, whereas the system-defined User Roles are pre-defined, standard User Roles supplied with
the console.

User role objects may be replicated to this HMC via its Data Replication facility. If that is the case, the
Update User Role Properties, Add Permission to User Role, Remove Permission from User Role and
Delete User Role operations should be used with care as they will prevent further replication of the
modified or deleted object to this HMC.

Through user-related-access permission described in “User-related-access permission” on page 529, API

users are permitted to see certain User Role objects in a List User Roles response and issue Get User
Role Properties for those User Role objects. An API user with action/task permission to the Manage
User Roles task is permitted to view any User Role object and change any user-defined User Role object.

552 HMC Web Services API

 Level 04a

System-defined user roles

There are many system-defined User Roles supplied with the console. System-defined roles may not be
modified or deleted. The names assigned to the system-defined roles are enumerated in Appendix C,
“Enum values for the User Role object,” on page 1395.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
but does not provide the operational-status-related properties defined in that schema because it does not
maintain the concept of an operational status.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

The following class-specific specializations apply to the other base managed object properties:
Table 281. User Role object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/URI The canonical URI path of the User Role object is of the form
/api/user-roles/{user-role-id}, where {user-role-id} is the value of the
object-id property of the User Role object.
parent — String/URI The canonical URI path of the console object.
class — String The class of a User Role object is "user-role".
name (ro) String The name of the User Role object. This name must be unique
among all of the console's User Roles with the same type value.
While pre-existing User Role names are virtually unrestricted in
terms of length and characters, new User Role names must
conform to the length and character requirements of the name
property described in the “Base managed object properties
schema” on page 60.

For the purpose of verifying uniqueness, this name is treated in a

case-insensitive fashion when used to create a new User Role
object.

The names of system-defined User Roles are listed in Appendix C,

“Enum values for the User Role object,” on page 1395.
description (w)(pc) String The description of the User Role object.
(0-1024)
Default: an empty string

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:
Table 282. User Role object: class specific additional properties
Name Qualifier Type Description
type — String Enum The type of User Role. Supported values are:
v "user-defined"
v "system-defined"

Chapter 11. Core IBM Z resources 553

 Level 04a

Table 282. User Role object: class specific additional properties (continued)
Name Qualifier Type Description
associated-system- (w)(pc) String/URI Canonical URI path of the system-defined User Role
defined-user-role-uri associated with this User Role. The User Roles which are
valid associated User Roles are identified in Appendix C,
“Enum values for the User Role object,” on page 1395. If
this is a system-defined User Role, this property is null,
because system-defined User Roles do not have an
associated User Role.

Default: the URI path of the Operator Tasks system-defined

User Role.
permissions (c)(pc) Array of The list of permissions included in this User Role. These
objects permissions are identified by permission-info objects, as
defined in the next table. The members provided in this list
can change as a result of the Add Permission to User Role
and Remove Permission from User Role operations. If there
are no permissions in this User Role, an empty array is
provided.

Default: an empty array

is-inheritance-enabled (w)(pc) Boolean Indicates whether User Role inheritance is enabled. When
true, if this User Role permits access to a parent managed
object, then all managed objects that are hosted by the
parent managed object are also permitted by this role. When
false, no such inherited permissions exist.

The supported inheritance relationships are:

Parent managed object:
Hosted managed object:
POWER® processor-based blade
Virtual server
System x blade
Virtual server
zBX BladeCenter
v POWER processor-based blade
v System x blade
v IBM WebSphere® Datapower Integration
Appliance XI50

Default: false.
replication-overwrite- — Boolean Indicates whether this object is customizable data that is
possible replicated to this HMC from an HMC configured as a Data
Source in the Data Replication service.

Each nested permission-info object contains the following fields:

554 HMC Web Services API

 Level 04a

Table 283. permission-info object properties.

Name Type Description
permitted-object String/URI or Canonical URI path or String Enum which identifies the object(s) or
String Enum task to which permission has been granted. Granting permission to a
Task object gives the user action/task permission to the console task
associated with that Task object, and the user is permitted to target any
of their authorized objects with that task. If this identifies a class of
managed objects, a specific managed object or a Group object, then
permission is granted to view the details of the object(s) and target the
object(s) with any authorized task for which it is an appropriate target.
This field is one of the following:
v The identifier for a class of managed objects. This identifier is the
String Enum value for the class from Appendix B, “Enum values for
a type of managed objects within User Roles,” on page 1393.
v The URI of a specific managed object.
v The URI of a Group object.
v The URI of a Task object.
v The well-known URI "/api/system-manual-definition", which
denotes a specific managed object known on the HMC UI as "System
Manual Definition"1

The type of object(s) is indicated by the permitted-object-type

property.
permitted-object-type String Enum Identifies the type of object(s) identified by the permitted-object
property.
v "object" - permitted-object contains a URI that identifies one of the
following:
– A specific managed object
– A Group object
– A Task object.
v "object-class" - permitted-object contains a String Enum value
fromAppendix B, “Enum values for a type of managed objects
within User Roles,” on page 1393.
include-members Boolean Indicates whether the members of a group are included in the User
Role, or if only the group itself is included. True if members are
included; false otherwise.

Prerequisite: the permitted-object field identifies a Group object that

does not use pattern-matching.
view-only-mode Boolean Indicates whether it is a task's view-only version that is in this User
Role. Only certain tasks support a view-only mode. This field is only
provided if the permitted-object field identifies such a Task object. A
User Role cannot have both the view-only version and the
non-view-only version in its set of permissions.

Prerequisite: the permitted-object field identifies a Task object that

supports a view-only mode.
1
The object identified by this special URI does not have full API support. It is only valid as a permitted object
identifier in a User Role object. Thus it may be included in the Get User Role Properties response body, and it is
valid in the request body of the Add Permission to User Role and Remove Permission from User Role operations.

List User Roles

The List User Roles operation lists User Roles defined to the console.

Chapter 11. Core IBM Z resources 555

 Level 04a

HTTP method and URI

GET /api/console/user-roles

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 type
Enum property. Value must be a valid type property value.

Response body contents

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

Field name Type Description

user-roles Array of Array of nested user-role-info objects as described in the next table.
objects

Each nested user-role-info object contains the following fields:

Field name Type Description

object-uri String/URI The object-uri property of the User Role object.
name String The name property of the User Role object.
type String The type property of the User Role object.
Enum

Description
The List User Roles operation lists User Roles defined to the console. Some basic properties are provided
for each user role.

If the name query parameter is specified, the returned list is limited to those User Roles that have a name
property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
performed.

If the type query parameter is specified, the parameter is validated to ensure it is a valid User Role type
property value. If the value is not valid, status code 400 (Bad Request) is returned. If the value is valid,
the returned list is limited to those User Roles that have a type property matching the specified value. If
the type parameter is omitted, this filtering is not performed.

A User Role is included in the list only if the API user has user-related-access permission to that object or
action/task permission to the Manage User Roles task. If there is a User Role 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 User Roles defined to the console or if no User Roles are to be included in the results 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:

556 HMC Web Services API

 Level 04a

v User-related-access permission to the User Role objects included in the response body or action/task
permission to the Manage User Roles task.

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 556.

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.

Usage Notes
While it is intended that system-defined User Roles have a name that begins with “hmc-”, there is no
such guarantee. API clients are cautioned to use the type property rather than name to reliably
distinguish between system-defined and user-defined User Roles.

Example HTTP interaction

GET /api/console/user-roles?name=.*ensemble.*task.* HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 312. List User Roles: Request

Chapter 11. Core IBM Z resources 557

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:32 GMT
content-type: application/json;charset=UTF-8
content-length: 589
{
"user-roles":[
{
"name":"hmc-ensemble-management-facility-administrator-tasks",
"object-uri":"/api/user-roles/ecfae496-40e7-4dd9-aa70-0a4fb299069a",
"type":"system-defined"
},
{
"name":"hmc-ensemble-administrator-tasks",
"object-uri":"/api/user-roles/7d5a8716-6aad-4462-ad47-52cc3f898702",
"type":"system-defined"
},
{
"name":"Company ensemble task subset",
"object-uri":"/api/user-roles/46ad96f0-4a6d-11e4-a1e7-1c6f65065a91",
"type":"user-defined"
},
{
"name":"hmc-ensemble-management-facility-operator-tasks",
"object-uri":"/api/user-roles/84220072-d8a3-4af0-87f6-33eefbda498c",
"type":"system-defined"
}
]
}

Figure 313. List User Roles: Response

Get User Role Properties

The Get User Role Properties operation retrieves the properties of a single User Role object that is
designated by its object ID.

HTTP method and URI

GET /api/user-roles/{user-role-id}

In this request, the URI variable {user-role-id} is the object ID of the User Role object whose properties are
to be retrieved.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the User Role object as defined in the data model section. Field names and data types
in the JSON object are the same as the property names and data types defined in the “Data model” on
page 553.

Description
This operation returns the current properties of a single User Role object that is designated by
{user-role-id}.

On successful execution, all of the current properties as defined in the data model for the User Role
object are provided in the response body, and HTTP status code 200 (OK) is returned.

558 HMC Web Services API

 Level 04a

The URI path must designate an existing User Role object and the API user must have user-related-access
permission to it or action/task permission to the Manage User Roles task. If these conditions are not
met, status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirement:
v User-related-access permission to the User Role object specified in the request URI, or action/task
permission to the Manage User Roles task.

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 558.

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 request URI does not designate an existing resource of the correct type,
or designates a resource for which the API user does not have the required
authorization.

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

Usage Notes
While it is intended that system-defined User Roles have a name that begins with “hmc-”, there is no
such guarantee. API clients are cautioned to use the type property rather than name to reliably
distinguish between system-defined and user-defined User Roles.

Example HTTP interaction

GET /api/user-roles/eb53f840-4a7a-11e4-affa-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 314. Get User Role Properties: Request

Chapter 11. Core IBM Z resources 559

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:32 GMT
content-type: application/json;charset=UTF-8
content-length: 853
{
"associated-se-user-role-uri":null,
"class":"user-role",
"description":"Role for managing department business",
"is-inheritance-enabled":false,
"is-locked":false,
"name":"Dept Admin",
"object-id":"eb53f840-4a7a-11e4-affa-1c6f65065a91",
"object-uri":"/api/user-roles/eb53f840-4a7a-11e4-affa-1c6f65065a91",
"parent":"/api/console",
"permissions":[
{
"permitted-object":"/api/console/tasks/4d5a39f0-c1df-4a2e-9a46-5bf6f6a759f3",
"permitted-object-type":"object",
"view-only-mode":false
},
{
"include-members":true,
"permitted-object":"/api/groups/cafb3a9b-6a34-4475-938f-98c5d60868a5",
"permitted-object-type":"object"
},
{
"permitted-object":"x-virtual-server",
"permitted-object-type":"object-class"
},
{
"permitted-object":"/api/console/tasks/45042443-7202-40b3-8630-b7a563a21d8d",
"permitted-object-type":"object"
}
],
"replication-overwrite-possible":false,
"type":"user-defined"
}

Figure 315. Get User Role Properties: Response

Update User Role Properties

The Update User Role Properties operation updates the properties of a single user-defined User Role
object that is designated by its object ID. System-defined User Roles are immutable; therefore, this
operation is not valid for system-defined User Roles.

HTTP method and URI

POST /api/user-roles/{user-role-id}

In this request, the URI variable {user-role-id} is the object ID of the User Role object whose properties are
to be updated.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the data model for this

560 HMC Web Services API

 Level 04a

object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation

Description
This operation updates writable properties of the User Role object specified by {user-role-id} .

The URI path must designate an existing User Role object; otherwise, status code 404 (Not Found) is
returned. If the user does not have user-related-access permission to the designated User Role object or
action/task permission to the Manage User Roles task, status code 404 (Not Found) is returned. If the
user has user-related-access permission to the designated User Role object but not action/task permission
to the Manage User Roles task, status code 403 (Forbidden) is returned.

The request body is validated against the schema described in the request body contents section. If the
request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered. An attempt to update a system-defined User Role is not valid and fails with
status code 400 (Bad Request).

The request body does not need to specify a value for all writable properties, but rather can and should
contain fields only for the properties to be updated. Object properties for which no input value is
provided remain unchanged by this operation.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage User Roles 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 284. Update User Role 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.
314 This operation is not supported for an object of this type. System-defined
User Roles may not be updated.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
2 A URI in the request body does not designate an existing resource of the
correct type.

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

Chapter 11. Core IBM Z resources 561

 Level 04a

Example HTTP interaction

POST /api/user-roles/eb53f840-4a7a-11e4-affa-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 99
{
"description":"A new and improved description of this User Role",
"is-inheritance-enabled":true
}

Figure 316. Update User Role Properties: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:32 GMT

<No response body>

Figure 317. Update User Role Properties: Response

Add Permission to User Role

The Add Permission to User Role operation adds a specified permission to a specified user-defined User
Role thereby granting that permission to all users that have that User Role. System-defined User Roles
are immutable; therefore, this operation is not valid for system-defined User Roles.

HTTP method and URI

POST /api/user-roles/{user-role-id}/operations/add-permission

In this request, the URI variable {user-role-id} is the object ID of the User Role to which a permission is to
be added.

Request body contents

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

Field name Type Rqd/Opt Description

permitted-object String/ Required
URI or Canonical URI path or String Enum which identifies the object(s) or
String task to which permission is to be granted. See the data model for
Enum more information about permissions. This field is one of the
following:
v The identifier for a class of managed objects. This identifier is the
String Enum value for the class from Appendix B, “Enum values
for a type of managed objects within User Roles,” on page 1393.
v The URI of a specific managed object.
v The URI of a Group object.
v The URI of a Task object.
v The well-known URI "/api/system-manual-definition", which
denotes a specific managed object known on the HMC UI as
"System Manual Definition"

The type of object(s) is indicated by the permitted-object-type field.

562 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

permitted-object-type String Required Identifies the type of object(s) identified by the permitted-object
Enum field. Supported values are:
v "object" - permitted-object contains a URI that identifies one of
the following:
– A specific managed object
– A Group object
– A Task object.
v "object-class" - permitted-object contains a String Enum value
from Appendix B, “Enum values for a type of managed objects
within User Roles,” on page 1393.
include-members Boolean Optional Indicates whether the members of the group are included in the
User Role, or if only the group itself is included. True if members
are included; false otherwise.

Prerequisite: the permitted-object field identifies a Group object that

does not use pattern-matching.

Default: false
view-only-mode Boolean Optional Indicates whether it is the task's view-only version that is being
added to this User Role. Only certain tasks support a view-only
mode. This field is only allowed if the permitted-object field
identifies such a Task object.

Prerequisite: the permitted-object field identifies a Task object that

supports a view-only mode.

Default: true

Description
This operation adds a permission to a User Role

On successful execution of this operation the permission specified in the request body has been added to
the User Role identified in the request URI.

The request body is validated against the schema described in the “Request body contents” on page 562.
If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered. If the request URI does not designate an existing User Role object,
status code 404 (Not Found) is returned. If the user does not have user-related-access permission to the
designated User Role object or action/task permission to the Manage User Roles task, status code 404
(Not Found) is returned. If the user has user-related-access permission to the designated User Role object
but not action/task permission to the Manage User Roles task, status code 403 (Forbidden) is returned. If
the URI in the request body does not designate an existing resource, status code 404 (Not Found) is
returned. An attempt to alter a system-defined User Role is not valid and fails with status code 400 (Bad
Request).

If the specified permission is already in the User Role, or an attempt is made to have both the view-only
and non-view-only versions of a Task in the User Role, status code 409 (Conflict) is returned.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Chapter 11. Core IBM Z resources 563

 Level 04a

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage User Roles 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 285. Add Permission to User Role: 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.
314 This operation is not supported for an object of this type. System-defined
User Roles may not be altered.
315 The permission identified in the request body is already in the User Role.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
2 A URI in the request body does not designate an existing resource of the
correct type.
409 (Conflict) 315 The permission identified in the request body is already in the User Role.
327 The view-only and non-view-only versions of a Task cannot be in the same
User Role. An attempt was made to add one version when the other was
already in the User Role's set of permitted objects.

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/user-roles/eb53f840-4a7a-11e4-affa-1c6f65065a91/operations/
add-permission HTTP/1.1
x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 114
{
"permitted-object":"/api/console/tasks/5d8c9f60-a2b3-4327-9fd4-791df8a60dcc",
"permitted-object-type":"object"
}

Figure 318. Add Permission to User Role: Request

564 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:32 GMT

<No response body>

Figure 319. Add Permission to User Role: Response

Remove Permission from User Role

The Remove Permission from User Role operation removes a specified permission from a specified
user-defined User Role. System-defined User Roles are immutable; therefore, this operation is not valid
for system-defined User Roles.

HTTP method and URI

POST /api/user-roles/{user-role-id}/operations/remove-permission

In this request, the URI variable {user-role-id} is the object ID of the User Role from which a permission is
to be removed.

Request body contents

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

Field name Type Rqd/Opt Description

permitted-object String/ Required Canonical URI path or String Enum which identifies the object(s) or
URI or task to which permission is to be removed. See the data model for
String more information about permissions. This field is one of the
Enum following:
v The identifier for a class of managed object. This identifier is the
String Enum value for the class from Appendix B, “Enum values
for a type of managed objects within User Roles,” on page 1393.
v The URI of a specific managed object.
v The URI of a Group object.
v The URI of a Task object.
v The well-known URI "/api/system-manual-definition", which
denotes a specific managed object known on the HMC UI as
"System Manual Definition"

The type of object(s) is indicated by the permitted-object-type field.

permitted-object- String Required Identifies the type of object(s) identified by the permitted-object
type Enum field. Supported values are:
v "object" - permitted-object contains a URI that identifies one of
the following:
– A specific managed object.
– A Group object.
– A Task object.
v "object-class" - permitted-object contains a String Enum value
from Appendix B, “Enum values for a type of managed objects
within User Roles,” on page 1393.

Chapter 11. Core IBM Z resources 565

 Level 04a

Field name Type Rqd/Opt Description

include-members Boolean Optional Indicates whether the members of the group are included in this
operation, or if only the group itself is included. True if members
are included; false otherwise.

Prerequisite: the permitted-object field identifies a Group object.

Default: false
view-only-mode Boolean Optional Indicates whether it is permission to a task's view-only version that
is to be removed from this User Role. Only certain tasks support a
view-only mode. This field is only allowed if the permitted-object
field identifies such a Task object.

Prerequisite: the permitted-object field identifies a Task object that

supports a view-only mode.

Default: true

Description
This operation removes a permission from a User Role

On successful execution of this operation the permission specified in the request body has been removed
from the User Role identified in the request URI.

The request body is validated against the schema described in “Request body contents” on page 565. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered. If the request URI does not designate an existing User Role object, status
code 404 (Not Found) is returned. If the user does not have user-related-access permission to the
designated User Role object or action/task permission to the Manage User Roles task, status code 404
(Not Found) is returned. If the user has user-related-access permission to the designated User Role object
but not action/task permission to the Manage User Roles task, status code 403 (Forbidden) is returned. If
the URI in the request body does not designate an existing resource, status code 404 (Not Found) is
returned. An attempt to alter a system-defined User Role is not valid and fails with status code 400 (Bad
Request).

If the specified permission is not in the User Role, or if removing it would leave one or more users
without object-access permission to their default group, status code 409 (Conflict) is returned.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage User Roles 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

566 HMC Web Services API

 Level 04a

Table 286. Remove Permission from User Role: 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.
314 This operation is not supported for an object of this type. System-defined
User Roles may not be altered.
316 The permission identified in the request body is not in the User Role.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
2 A URI in the request body does not designate an existing resource of the
correct type.
409 (Conflict) 316 The permission identified in the request body is not in the User Role.
328 The permission cannot be removed at this time, because doing so would
leave one or more users without object-access permission to their default
group.

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/user-roles/eb53f840-4a7a-11e4-affa-1c6f65065a91/operations/
remove-permission HTTP/1.1
x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 114
{
"permitted-object":"/api/console/tasks/5d8c9f60-a2b3-4327-9fd4-791df8a60dcc",
"permitted-object-type":"object"
}

Figure 320. Remove Permission from User Role: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:32 GMT

<No response body>

Figure 321. Remove Permission from User Role: Response

Create User Role

The Create User Role operation creates a user-defined User Role object with the given properties on the
console. This operation is not valid for system-defined User Roles.

HTTP method and URI

POST /api/console/user-roles

Chapter 11. Core IBM Z resources 567

 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

name String Required The value to be set as the User Role's name property.
description String Optional The value to be set as the User Role's description
property.
associated-system- String/URI Optional The value to be set as the User Role's
defined-user-role- associated-system-defined-user-role-uri property.
uri
is-inheritance- Boolean Optional The value to be set as the User Role's
enabled is-inheritance-enabled property.

Response body contents

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

Field name Type Description

object-uri String/URI Canonical URI path of the new User Role object.

Description
This operation creates a new, empty, user-defined User Role.

On successful execution of this operation the User Role is created using the inputs as specified by the
request body. The URI of the new User Role is provided in the response body and in a Location response
header as well. An Inventory Change notification is emitted asynchronously. The Add Permission to User
Role operation can then be used to add permissions to the new User Role.

The request body is validated against the schema described in “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered. If the specified name is not unique, status code 400 (Bad Request) is returned. In
addition, the API user must have action/task permission to the Manage User Roles task; otherwise,
status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage User Roles 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,” and the Location response header contains the URI of the newly created
object.

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.

568 HMC Web Services API

 Level 04a

Table 287. Create User Role: 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 User Role with the name specified in the request body already exists.
403 (Forbidden) 1 The API user does not have the required permission for this operation.

Additional standard status and reason codes can be returned, as described in Chapter 3, “Invoking API
operations,” on page 35 and the Location response header contains the URI of the newly created object.

Example HTTP interaction

POST /api/console/user-roles HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 78
{
"description":"Role for managing department business",
"name":"Dept Admin"
}

Figure 322. Create User Role: Request

201 Created
server: zSeries management console API web server / 2.0
location: /api/user-roles/eb53f840-4a7a-11e4-affa-1c6f65065a91
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:31 GMT
content-type: application/json;charset=UTF-8
content-length: 69
{
"object-uri":"/api/user-roles/eb53f840-4a7a-11e4-affa-1c6f65065a91"
}

Figure 323. Create User Role: Response

Delete User Role

The Delete User Role operation deletes a user-defined User Role object designated by its object ID. This
operation is not valid for system-defined User Roles.

HTTP method and URI

DELETE /api/user-roles/{user-role-id}

In this request, the URI variable {user-role-id} is the object ID of the User Role object to be deleted.

Description
This operation removes a specified User Role from the console. The User Role is identified by the
{user-role-id} variable in the URI.

Chapter 11. Core IBM Z resources 569

 Level 04a

Upon successfully removing the User Role, HTTP status code 204 (No Content) is returned and no
response body is provided. An Inventory Change notification is emitted asynchronously.

The URI path must designate an existing User Role object; otherwise, status code 404 (Not Found) is
returned. If the user does not have user-related-access permission to the designated User Role object or
action/task permission to the Manage User Roles task, status code 404 (Not Found) is returned. If the
user has user-related-access permission to the designated User Role object but not action/task permission
to the Manage User Roles task, status code 403 (Forbidden) is returned. An attempt to delete a
system-defined User Role is not valid and fails with status code 400 (Bad Request). If any user has the
specified User Role, the request fails and status code 409 (Conflict) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage User Roles task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned 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.
Table 288. Delete User Role: 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.
312 This operation is not supported for an object of this type. System-defined
User Roles may not be deleted.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
409 (Conflict) 317 The object cannot be deleted at this time. One or more users have this User
Role.

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/user-roles/eb53f840-4a7a-11e4-affa-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 324. Delete User Role: Request

570 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:32 GMT

<No response body>

Figure 325. Delete User Role: Response

Inventory service data

Information about the User Roles managed by the console can be optionally included in the inventory
data provided by the Inventory Service.

Inventory entries for User Role objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "user-role" are to be included. An entry for a particular User Role is
included only if the API user has access permission to that object as described in the Get User Role
Properties operation.

For each User Role object to be included, the inventory response array includes an entry that is a JSON
object with the same contents as is specified in the response body contents section for the Get User Role
Properties operation. That is, the data provided is the same as would be provided if a Get User Role
Properties operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single User Role. This object would appear as one array entry in the response
array:

Chapter 11. Core IBM Z resources 571

 Level 04a

{
"associated-system-defined-user-role-uri": "/api/user-roles/b39afb87-d915-
4070-a22f-91b158c6c01e",
"class": "user-role",
"description": "Role that allows management of users",
"is-inheritance-enabled": false,
"is-locked": false,
"name": "user_roles_9",
"object-id": "db7f9448-3737-11e4-a5fc-5ef3fcae8020",
"object-uri": "/api/user-roles/db7f9448-3737-11e4-a5fc-5ef3fcae8020",
"parent": "/api/console",
"permissions": [
{
"permitted-object": "/api/console/tasks/f8d653f4-eab2-4547-97c0-
a26f762218ba",
"permitted-object-type": "object"
},
{
"permitted-object": "/api/console/tasks/36e32fb4-7b60-4677-b462-
e786f337ea0f",
"permitted-object-type": "object"
},
{
"permitted-object": "/api/console/tasks/8ef2b7ca-c2d2-4a5b-9d52-
b4d1a28ccb15",
"permitted-object-type": "object"
}
],
"replication-overwrite-possible": false,
"type": "user-defined"
}

Figure 326. User Role object: Sample inventory data

Task object
A Task object is an element of the console object and represents an action that a console user with
appropriate authority can perform. These actions could be available via the console's graphical user
interface, the Web Services APIs or both. Tasks are predefined by the console and cannot be created,
modified or deleted.

All API users have object-access permission to all Tasks and thus are permitted to issue List Tasks and
Get Task Properties for any Task object. Note that this object-access permission to a Task object does not
give an API user action/task permission to the task represented by the Task object.

Data model
The Task object contains the following properties.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.
Table 289. Task object: properties
Name Qualifier Type Description
element-uri — String/URI The canonical URI path of the Task object is of the form
/api/console/tasks/{task-id}, where {task-id} is the value of the
element-id property of the Task object.

572 HMC Web Services API

 Level 04a

Table 289. Task object: properties (continued)

Name Qualifier Type Description
element-id — String (36) The unique identifier for this object.
parent — String/URI The canonical URI path of the console object.
class — String The class of a Task object is "task".
name (ro) String Enum The name of the Task object. The task names are documented in
Appendix D, “Enum values for the Task object,” on page 1397.
description — String The description of the Task object.
(0-1024)
Default: an empty string
view-only-mode- — Boolean Indicates whether this task supports a view-only mode.
supported

List Tasks
The List Tasks operation lists Tasks defined to the console.

HTTP method and URI

GET /api/console/tasks

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.

Response body contents

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

Field name Type Description

tasks Array of Array of nested task-info objects as described in the next table.
objects

Each nested task-info object contains the following fields:

Field name Type Description

element-uri String/URI The element-uri property of the Task object.
name String The name property of the Task object.

Description
This operation lists tasks defined to the console. Some basic properties are provided for each task.

If the name query parameter is specified the returned list is limited to those tasks that have a name
property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
performed.

If no tasks are to be included in the results due to filtering, an empty list is provided and the operation
completes successfully.

Chapter 11. Core IBM Z resources 573

 Level 04a

Authorization requirements
This operation has no explicit authorization requirements.

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 573.

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

GET /api/console/tasks?name=.*blade.* HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 327. List Tasks: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:32 GMT
content-type: application/json;charset=UTF-8
content-length: 219
{
"tasks":[
{
"element-uri":"/api/console/tasks/94bc3309-b2f5-4a56-a1bc-399c60fd9fed",
"name":"zbx-blade-details"
},
{
"element-uri":"/api/console/tasks/99934f93-ab89-49fa-a01d-74412f48ab5d",
"name":"zbx-bladecenter-details"
}
]
}

Figure 328. List Tasks: Response

Get Task Properties

The Get Task Properties operation retrieves the properties of a single Task object that is designated by its
element ID.

HTTP method and URI

GET /api/console/tasks/{task-id}

574 HMC Web Services API

 Level 04a

In this request, the URI variable {task-id} is the element ID of the Task object whose properties are to be
returned.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the Task object as defined in the data model section. Field names and data types in the
JSON object are the same as the property names and data types defined in the “Data model” on page
572.

Description
This operation returns the current properties of a single Task object specified by {task-id} .

On successful execution, all of the current properties as defined in the data model for the Task object are
provided in the response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing Task object; otherwise, status code 404 (Not Found) is returned.

Authorization requirements
This operation has no explicit authorization requirements.

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, 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 request URI does not designate an existing resource of the correct type.

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/tasks/94bc3309-b2f5-4a56-a1bc-399c60fd9fed HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 329. Get Task Properties: Request

Chapter 11. Core IBM Z resources 575

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:32 GMT
content-type: application/json;charset=UTF-8
content-length: 259
{
"class":"task",
"description":"Details for a Blade",
"element-id":"94bc3309-b2f5-4a56-a1bc-399c60fd9fed",
"element-uri":"/api/console/tasks/94bc3309-b2f5-4a56-a1bc-399c60fd9fed",
"name":"zbx-blade-details",
"parent":"/api/console"
}

Figure 330. Get Task Properties: Response

Inventory service data

Information about the tasks managed by the console can be optionally included in the inventory data
provided by the Inventory Service.

Inventory entries for Task objects are included in the response to the Inventory Service's Get Inventory
operation when the request specifies (explicitly by class, implicitly via a containing category, or by
default) that objects of class "console" are to be included.

For each Task object to be included, the inventory response array includes an entry that is a JSON object
with the same contents as is specified in the response body contents section for the Get Task Properties
operation. That is, the data provided is the same as would be provided if a Get Task Properties
operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single Task. This object would appear as one array entry in the response array:

{
"class": "task",
"description": "Customize the Application Programming Interface for the
console",
"element-id": "ee76dca1-9aee-4530-bf66-667ae728ed10",
"element-uri": "/api/console/tasks/ee76dca1-9aee-4530-bf66-667ae728ed10",
"name": "customize-api-settings",
"parent": "/api/console",
"view-only-mode-supported": false
}

Figure 331. Task object: Sample inventory data

User Pattern object

User Patterns and user templates allow a system administrator to define a group of console users at once
whose user IDs all match a certain pattern (for example, a regular expression) and who have a certain set
of attributes. A User Pattern object is an element of the console object and defines a pattern for user IDs
that are not defined to the console but can be verified by an LDAP server for user authentication. Each

576 HMC Web Services API

 Level 04a

pattern identifies a template User object which defines many characteristics of such users. A successful
logon with a user ID that matches a User Pattern results in the creation of a pattern-based user, with
many of its attributes coming from the associated template. User Patterns are searched in a defined order
during logon processing. That order can be customized through the Console object operation “Reorder
User Patterns” on page 496.

Through user-related-access permission described in “User-related-access permission” on page 529, API

users are permitted to see certain User Pattern objects in a List User Patterns response and issue Get
User Pattern Properties for those User Pattern objects. An API user with action/task permission to the
Manage User Patterns task is permitted to view and change any User Pattern object and change the
pattern search order.

User Pattern objects may be replicated to this HMC via its Data Replication facility. If that is the case, the
Update User Pattern Properties and Delete User Pattern operations should be used with care as they
will prevent further replication of the modified or deleted object to this HMC.

Data model
This object contains the following properties. Certain properties are only valid when mutable prerequisite
properties have specific values. When such properties are not valid, their value is null. For instance the
template-name-override is null when the ldap-server-definition-uri value is null.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.
Table 290. User Pattern object: properties
Name Qualifier Type Description
element-uri — String/URI The canonical URI path of the User Pattern object is of the form
/api/console/user-patterns/{user-pattern-id}, where {user-pattern-id}
is the value of the element-id property of the User Pattern object.
element-id — String (36) The unique identifier for this object.
parent — String/URI The canonical URI path of the console object.
class — String The class of a User Pattern object is "user-pattern".
name (w) String The name of the User Pattern object. This name must be unique
among all User Patterns on the console. The length and character
requirements on this property are the same as those of the name
property described in the “Base managed object properties
schema” on page 60.

For the purpose of verifying uniqueness, this name is treated in a

case-insensitive fashion when used to create a new User Pattern
object.
description (w) String The description of the User Pattern object.
(0-1024)
Default: an empty string
pattern (w) String The actual User Pattern expression. The combination of pattern
and type must be unique on the console. Must not be an empty
string.
type (w) String Enum The style in which this pattern is expressed, which is one of the
following values:
v "glob-like" - The pattern may include limited special characters:
an asterisk in the pattern matches zero or more characters in the
user ID, and a question mark in the pattern matches any single
character in the user ID.
v "regular-expression" - The pattern is expressed as a UNIX
regular expression.

Chapter 11. Core IBM Z resources 577

 Level 04a

Table 290. User Pattern object: properties (continued)

Name Qualifier Type Description
search-order-index — Integer A zero-based index position of this User Pattern in the pattern
search order used during logon processing.
retention-time (w) Integer The time in days that the user data for pattern-based users created
(0- based on this pattern will be retained. A value of 0 indicates not to
2147483647) retain the settings.
user-template-uri (w) String/URI The canonical URI path of the User object containing the template
definition that applies when a successful match occurs using this
User Pattern.
ldap-server- (w) String/URI The canonical URI path of the LDAP Server Definition object
definition-uri which identifies the LDAP server to be used to validate the user ID
when processing a logon for a user ID that matches this pattern, or
null if the LDAP server in the template is used.
template-name- (w) String
override The name of the LDAP attribute that contains the name of the user
template definition for the user, or null if there is no such
attribute. When not null, this property overrides the user template
identified in the user-template-uri field, and it must not be an
empty string.

Prerequisite: ldap-server-definition-uri is not null

Default: null
domain-name- (w) String
restrictions The name of the LDAP attribute that contains the information
about which consoles the user is allowed to log onto, or null if
there is no such attribute. Must not be an empty string.

Prerequisite: ldap-server-definition-uri is not null

Default: null
replication- — Boolean Indicates whether this object is customizable data that is replicated
overwrite-possible to this HMC from an HMC configured as a Data Source in the
Data Replication service.

List User Patterns

The List User Patterns operation lists User Patterns defined to the console.

HTTP method and URI

GET /api/console/user-patterns

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 type
Enum property. Value must be a valid type property value.

578 HMC Web Services API

 Level 04a

Response body contents

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

Field name Type Description

user-patterns Array of Array of nested user-pattern-info objects as described in the next table.
objects

Each nested user-pattern-info object contains the following fields:

Field name Type Description

element-uri String/URI The element-uri property of the User Pattern object.
name String The name property of the User Pattern object.
type String The type property of the User Pattern object.
Enum

Description
This operation lists User Patterns defined to the console. Some basic properties are provided for each
User Pattern.

A User Pattern is included in the list only if the API user has user-related-access permission to that object
or action/task permission to the Manage User Patterns task. If there is a User Pattern 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 User Patterns defined to the console or if no User Patterns are to be included in the results
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 User-related-access permission to the User Pattern objects included in the response body or action/task
permission to the Manage User Patterns task.

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, 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.

Chapter 11. Core IBM Z resources 579

 Level 04a

Usage Notes
User Patterns are searched in a defined order during logon processing. That order can be customized
through the Console object operation “Reorder User Patterns” on page 496. The List User Patterns
operation does not specify the order in which the User Pattern URIs appear in the response body, and
there is no guarantee that the order in the response will not change in subsequent invocations. Use the
search-order-index property to determine a pattern's position in the search order.

Example HTTP interaction

GET /api/console/user-patterns?type=regular-expression HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 332. List User Patterns: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT
content-type: application/json;charset=UTF-8
content-length: 314
{
"user-patterns":[
{
"element-uri":"/api/console/user-patterns/497bf4ec-1dbf-11e4-8ceb-1c6f65065a91",
"name":"IBM Intranet User Pattern",
"type":"regular-expression"
},
{
"element-uri":"/api/console/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91",
"name":"Company email pattern",
"type":"regular-expression"
}
]
}

Figure 333. List User Patterns: Response

Get User Pattern Properties

The Get User Pattern Properties operation retrieves the properties of a single User Pattern object that is
designated by its element ID.

HTTP method and URI

GET /api/console/user-patterns/{user-pattern-id}

In this request, the URI variable {user-pattern-id} is the element ID of the User Pattern object whose
properties are to be returned.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the User Pattern object as defined in the “Data model” on page 577. Field names and
data types in the JSON object are the same as the property names and data types defined in the data
model.

580 HMC Web Services API

 Level 04a

Description
This operation returns the current properties of a single User Pattern object specified by {user-pattern-id}.

On successful execution, all of the current properties as defined in the data model for the User Pattern
object are provided in the response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing User Pattern object and the API user must have
user-related-access permission to it or action/task permission to the Manage User Patterns task. If these
conditions are not met, status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirement:
v User-related-access permission to the User Pattern object specified in the request URI or action/task
permission to the Manage User Patterns task

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 580.

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 request URI does not designate an existing resource of the correct type,
or designates a resource for which the API user does not have the required
authorization.

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/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 334. Get User Pattern Properties: Request

Chapter 11. Core IBM Z resources 581

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT
content-type: application/json;charset=UTF-8
content-length: 593
{
"class":"user-pattern",
"description":"User Pattern based on company email addresses",
"domain-name-restrictions":null,
"element-id":"ec5b012a-4a7a-11e4-8777-1c6f65065a91",
"element-uri":"/api/console/user-pattern
s/ec5b012a-4a7a-11e4-8777-1c6f65065a91",
"ldap-server-definition-uri":null,
"name":"Company email pattern",
"parent":"/api/console",
"pattern":".*@our\\.company\\.com",
"replication-overwrite-possible":false,
"retention-time":8,
"search-order-index":3,
"template-name-override":null,
"type":"regular-expression",
"user-template-uri":"/api/users/ec473e56-4a7a-11e4-91ee-1c6f65065a91"
}

Figure 335. Get User Pattern Properties: Response

Update User Pattern Properties

The Update User Pattern Properties operation updates the properties of a single User Pattern object that
is designated by its element ID.

HTTP method and URI

POST /api/console/user-patterns/{user-pattern-id}

In this request, the URI variable {user-pattern-id} is the element ID of the User Pattern object whose
properties are to be updated.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
This operation updates writable properties of the User Pattern object specified by {user-pattern-id} .

The URI path must designate an existing User Pattern object; otherwise, status code 404 (Not Found) is
returned. If the user does not have user-related-access permission to the designated User Pattern object or
action/task permission to the Manage User Patterns task, status code 404 (Not Found) is returned. If the
user has user-related-access permission to the designated User Pattern object but not action/task
permission to the Manage User Patterns task, status code 403 (Forbidden) is returned.

582 HMC Web Services API

 Level 04a

The request body is validated against the schema described in the request body contents section. If the
request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered. The request body validation will fail if it contains a property that is not
valid because a prerequisite is not met (e.g., attempting to set template-name-override when the
ldap-server-definition-uri value is null).

The request body does not need to specify a value for all writable properties, but rather can and should
contain fields only for the properties to be updated. Object properties for which no input value is
provided and no prerequisite property is changed remain unchanged by this operation. A property's
value is set to its default value if the field is not included in the request body and a prerequisite field is
changed such that the prerequisite condition becomes satisfied (e.g., if ldap-server-definition-uri is
changed from non-null tonull, and template-name-override is not defined in the request body,
template-name-override will be defaulted to null).

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage User Patterns 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 291. Update User Pattern 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.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
324 The ldap-server-definition-uri field in the request body does not designate
an existing LDAP Server Definition object.
326 The user-template-uri field in the request body does not designate an
existing template type User object.

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

Chapter 11. Core IBM Z resources 583

 Level 04a

Example HTTP interaction

POST /api/console/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 95
{
"description":"A new and improved description of this User Pattern",
"retention-time":30
}

Figure 336. Update User Pattern Properties: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT

<No response body>

Figure 337. Update User Pattern Properties: Response

Create User Pattern

The Create User Pattern operation creates a User Pattern object with the given properties on the console.

HTTP method and URI

POST /api/console/user-patterns

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The value to be set as the User Pattern's name property.
description String Optional The value to be set as the User Pattern's description
property.
pattern String Required The value to be set as the User Pattern's pattern property.
type String Required The value to be set as the User Pattern's type property.
Enum
retention-time Integer Required The value to be set as the User Pattern's retention-time
property.
user-template-uri String/URI Required The value to be set as the User Pattern's user-template-uri
property.
ldap-server- String/URI Optional The value to be set as the User Pattern's
definition-uri ldap-server-definition-uri property.
template-name- String Optional The value to be set as the User Pattern's
override template-name-override property.
domain-name- String Optional The value to be set as the User Pattern's
restrictions domain-name-restrictions property.

584 HMC Web Services API

 Level 04a

Response body contents

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

Field name Type Description

element-uri String/URI Canonical URI path of the new User Pattern object.

Description
This operation creates a new User Pattern.

On successful execution of this operation the User Pattern is created using the inputs as specified by the
request body. The new User Pattern is placed at the end of the pattern search order used during logon
processing. The URI of the new User Pattern is provided in the response body and in a Location
response header as well.

The request body is validated against the schema described in the “Request body contents” on page 584.
If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered. The request body validation will fail if it contains a property that is not
valid because a prerequisite is not met (e.g., specifying template-name-override when the
ldap-server-definition-uri value is null) or the specified pattern is not unique. If a URI in the request
body does not designate an existing resource of the appropriate type, status code 404 (Not Found) is
returned In addition, the API user must have action/task permission to the Manage User Patterns task;
otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage User Patterns 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,” and the Location response header contains the URI of the newly created
object.

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.
Table 292. Create User Pattern: 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 User Pattern with the pattern specified in the request body already exists.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 324 The ldap-server-definition-uri field in the request body does not designate
an existing LDAP Server Definition object.
326 The user-template-uri field in the request body does not designate an
existing template type User object.

Chapter 11. Core IBM Z resources 585

 Level 04a

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

Usage Notes
User Patterns are searched in a defined order during logon processing. That order can be customized
through the Console object's Reorder User Patterns operation.

Example HTTP interaction

POST /api/console/user-patterns HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 260
{
"description":"User Pattern based on company email addresses",
"name":"Company email pattern",
"pattern":".*@our\\.company\\.com",
"retention-time":8,
"type":"regular-expression",
"user-template-uri":"/api/users/ec473e56-4a7a-11e4-91ee-1c6f65065a91"
}

Figure 338. Create User Pattern: Request

201 Created
server: zSeries management console API web server / 2.0
location: /api/console/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT
content-type: application/json;charset=UTF-8
content-length: 83
{
"element-uri":"/api/console/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91"
}

Figure 339. Create User Pattern: Response

Delete User Pattern

The Delete User Pattern operation deletes a User Pattern object designated by its element ID.

HTTP method and URI

DELETE /api/console/user-patterns/{user-pattern-id}

In this request, the URI variable {user-pattern-id} is the element ID of the User Pattern object to be deleted.

Description
This operation removes a specified User Pattern from the console. The User Pattern is identified by the
{user-pattern-id} variable in the URI.

Upon successfully removing the User Pattern, HTTP status code 204 (No Content) is returned and no
response body is provided.

The URI path must designate an existing User Pattern object; otherwise, status code 404 (Not Found) is
returned. If the user does not have user-related-access permission to the designated User Pattern object or

586 HMC Web Services API

 Level 04a

action/task permission to the Manage User Patterns task, status code 404 (Not Found) is returned. If the
user has user-related-access permission to the designated User Pattern object but not action/task
permission to the Manage User Patterns task, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage User Patterns task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned 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) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.

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

Usage Note
It is permitted to delete a User Pattern even if there is a pattern-based user based on that pattern logged
onto the HMC at the time of the deletion. Note that this will cause certain operations issued with the
value of the user-pattern-uri property in that user's User object to fail, most likely with a 404 (Not
Found) status code.

Example HTTP interaction

DELETE /api/console/user-patterns/ec5b012a-4a7a-11e4-8777-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 340. Delete User Pattern: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT

<No response body>

Figure 341. Delete User Pattern: Response

Chapter 11. Core IBM Z resources 587

 Level 04a

Inventory service data

Information about the User Patterns managed by the console can be optionally included in the inventory
data provided by the Inventory Service.

Inventory entries for User Pattern objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "console" are to be included. An entry for a particular User Pattern is
included only if the API user has access permission to that object as described in the Get User Pattern
Properties operation.

For each User Pattern object to be included, the inventory response array includes an entry that is a JSON
object with the same contents as is specified in the response body contents section for the Get User
Pattern Properties operation. That is, the data provided is the same as would be provided if a Get User
Pattern Properties operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single User Pattern. This object would appear as one array entry in the response
array:

{
"class": "user-pattern",
"description": "",
"domain-name-restrictions": null,
"element-id": "8c1ae17a-34c4-11e4-a30c-5ef3fcae8020",
"element-uri": "/api/console/user-patterns/8c1ae17a-34c4-11e4-a30c-
5ef3fcae8020",
"ldap-server-definition-uri": "/api/console/ldap-server-definitions/
4927787e-34c4-11e4-a1ea-5ef3fcae8020",
"name": "testpattern_inventory",
"parent": "/api/console",
"pattern": "user-*",
"replication-overwrite-possible": false,
"retention-time": 0,
"search-order-index": 0,
"template-name-override": null,
"type": "glob-like",
"user-template-uri": "/api/users/641c7d96-34c4-11e4-b2c2-5ef3fcae8020"
}

Figure 342. User Pattern object: Sample inventory data

Password Rule object

A Password Rule object is an element of the console object and represents a rule which a console user(s)
must follow when creating a console logon password. Each console user using local authentication is
assigned a password rule. There are certain system-defined password rules available for use.

Through user-related-access permission described in “User-related-access permission” on page 529, API

users are permitted to see certain Password Rule objects in a List Password Rules response and issue Get
Password Rule Properties for those Password Rule objects. An API user with action/task permission to
the Manage Password Rules task is permitted to view any Password Rule object and change any
user-defined Password Rule object.

588 HMC Web Services API

 Level 04a

Password rule objects may be replicated to this HMC via its Data Replication facility. If that is the case,
the Update Password Rule Properties and Delete Password Rule operations should be used with care as
they will prevent further replication of the modified or deleted object to this HMC.

System-defined password rules

Unlike user-defined password rules, the system-defined password rules may not be modified. While
system-defined password rules can be deleted and their name reused for a user-defined password rule,
that practice is discouraged due to the likely confusion such a situation would cause. The names of the
typical system-defined password rules include:
v Basic
v Standard
v Strict

Password rule parts

Password rule parts are optional requirements to be applied to individual parts of a password. These
requirements are applied, in order, to the password, from left to right. Each of these requirements must
be met by some part of the password in order for the password to meet all of the requirements of the
Password Rule.

For example, to require a password to consist of 1-3 letters followed by a 4 or 5 digit number, two rule
parts are defined. The first rule part requires from 1 to 3 characters, each of which must be alphabetic;
the second rule part requires from 4 to 5 characters, each of which must be numeric. Passwords such as
“pa1600” and “Hey90210” meet the requirements of both of those rule parts.

Data model
The Password Rule object contains the following properties.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.
Table 293. Password Rule object: properties
Name Qualifier Type Description
element-uri — String/URI The canonical URI path for a Password Rule object is of the form
/api/console/password-rules/{password-rule-id}, where
{password-rule-id} is the value of the element-id property of the
Password Rule object.
element-id — String (36) The unique identifier for this object.
parent — String/URI The canonical URI path of the console object.
class — String The class of a Password Rule object is "password-rule".
name (ro) String The name of the Password Rule object. This name must be unique
among all password rules on the console. While preexisting
Password Rule names are virtually unrestricted in terms of length
and characters, new Password Rule names must conform to the
length and character requirements of the name property described
in the “Base managed object properties schema” on page 60.

For the purpose of verifying uniqueness, this name is treated in a

case-insensitive fashion when used to create a new Password Rule
object.
description (w) String The description of the Password Rule object.
(0-1024)
Default: an empty string

Chapter 11. Core IBM Z resources 589

 Level 04a

Table 293. Password Rule object: properties (continued)

Name Qualifier Type Description
type — String Enum Identifies the type of password rule. It must be one of the
following values:
v "system-defined" - A password rule defined by the system.
System-defined rules may not be modified.
v "user-defined" - A password rule defined by a user.
expiration (w) Integer The total number of days a password is valid before it expires. A
value of 0 indicates that the password never expires.

Default: 0
min-length (w) Integer The minimum required length of the password. Cannot be greater
(1-256) than max-length.

Default: 8
max-length (w) Integer The maximum allowed length of the password. Cannot be less
(1-256) than min-length.

Default: 256
consecutive- (w) Integer The maximum number of characters that are allowed to be
characters repeated in a row. A value of 0 indicates that there is no such limit.

Default: 0
similarity-count (w) Integer The maximum number of consecutive characters in the current
password that can match consecutive characters in the previous
password. A value of 0 indicates that there is no such limit.

Default: 0
history-count (w) Integer The number of previous passwords to which a new password is
compared for uniqueness. A value of 0 indicates that there is no
such comparison.

Default: 0
case-sensitive (w) Boolean Indicates whether the password is case sensitive.

Default: false
character-rules (w) Array of Optional rules to be applied to individual parts of the password.
objects These rules are applied, in order, to the password, from left to
right. Each of these rules must be met by some part of the
password in order for the password to meet the requirements of
this Password Rule. This property is an array of nested
character-rule objects as described in the next table. If there are no
rule parts, an empty array is provided.

Default: <empty array>

replication- — Boolean Indicates whether this object is customizable data that is replicated
overwrite-possible to this HMC from an HMC configured as a Data Source in the
Data Replication service.

Each nested password-rule-part object contains the following fields:

Table 294. character-rule object properties
Name Type Description
min-characters Integer The minimum number of characters required by this password rule
part. Must be at least 1, and cannot be greater than max-characters.

590 HMC Web Services API

 Level 04a

Table 294. character-rule object properties (continued)

Name Type Description
max-characters Integer The maximum number of characters allowed by this password rule
part. Must be at least 1, and cannot be less than min-characters.
alphabetic String Enum This field determines the inclusion of alphabetic characters within this
part of the password. It must be one of the following values:
v "allowed" - There can be alphabetic characters.
v "not-allowed" - There cannot be alphabetic characters.
v "required" - There must be alphabetic characters.
numeric String Enum This field determines the inclusion of numeric characters within this
part of the password. It must be one of the following values:
v "allowed" - There can be numeric characters.
v "not-allowed" - There cannot be numeric characters.
v "required" - There must be numeric characters.
special String Enum This field determines the inclusion of special characters within this part
of the password. It must be one of the following values:
v "allowed" - There can be special characters.
v "not-allowed" - There cannot be special characters.
v "required" - There must be special characters.

Special characters include: greater than (>), less than (<), tilde (~),
exclamation mark (!), at sign (@), number sign (#), question mark (?),
dollar sign ($), vertical bar (|), percent sign (%), caret (^), ampersand
(&), asterisk (*), left and right parentheses ( ), underscore (_), plus sign
(+), hyphen (-), equals sign (=), left and right curly braces ({ }), left and
right square brackets ([ ]), back slash (\), forward slash (/), period (.),
comma (,), colon (:), accent (`), quotation mark ("), semicolon (;), and
apostrophe (').
custom-character-sets Array of Optional specific character requirements for this password part, as
objects specified in an array of nested custom-character-set objects defined in
the next table. This allows the specification of custom character sets
and their inclusion requirement. There can be up to 2 custom character
sets for a rule part. If none are defined, an empty array is provided.

Each nested specific-property object contains the following fields:

Table 295. custom-character-set object properties
Name Type Description
character-set String A string consisting of the characters that comprise this custom
character set.
inclusion String Enum This field determines the inclusion of characters in this character set
within part of the password. It must be one of the following values:
v "allowed" - Characters can be included.
v "not-allowed" - Characters cannot be included.
v "required" - At least one character must be included.

List Password Rules

The List Password Rules operation lists Password Rules defined to the console.

HTTP method and URI

GET /api/console/password-rules

Query Parameters

Chapter 11. Core IBM Z resources 591

 Level 04a

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 type
Enum property. Value must be a valid type property value.

Response body contents

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

Field name Type Description

password-rules Array of Array of nested password-rule-info objects as described in the next table. If
objects no Password Rules are to be returned, an empty array is provided.

Each nested password-rule-info object contains the following fields:

Field name Type Description

element-uri String/URI The element-uri property of the Password Rule object.
name String The name property of the Password Rule object.
type String The type property of the Password Rule object.
Enum

Description
This operation lists Password Rules defined to the console. Some basic properties are provided for each
Password Rule.

If the name query parameter is specified the returned list is limited to those Password Rules that have a
name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
performed.

If the type query parameter is specified, the parameter is validated to ensure it is a valid Password Rule
type property value. If the value is not valid, status code 400 (Bad Request) is returned. If the value is
valid, the returned list is limited to those Password Rules that have a type property matching the
specified value. If the type parameter is omitted, this filtering is not performed.

A Password Rule is included in the list only if the API user has user-related-access permission to that
object or action/task permission to the Manage Password Rules task. If there is a console Password Rule
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 Password Rules defined to the console or if no Password Rules are to be included in the
results 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 User-related-access permission to the Password Rules objects included in the response body or
action/task permission to the Manage Password Rules task.

592 HMC Web Services API

 Level 04a

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 592.

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

GET /api/console/password-rules?type=system-defined HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 343. List Password Rules: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT
content-type: application/json;charset=UTF-8
content-length: 390
{
"password-rules":[
{
"element-uri":"/api/console/password-rules/4a790766-3dbf-11e4-980d-1c6f65065a91",
"name":"Basic",
"type":"system-defined"
},
{
"element-uri":"/api/console/password-rules/4a79360a-3dbf-11e4-980d-1c6f65065a91",
"name":"Standard",
"type":"system-defined"
},
{
"element-uri":"/api/console/password-rules/4a792b24-3dbf-11e4-980d-1c6f65065a91",
"name":"Strict",
"type":"system-defined"
}
]
}

Figure 344. List Password Rules: Response

Get Password Rule Properties

The Get Password Rule Properties operation retrieves the properties of a single Password Rule object
that is designated by its element ID.

Chapter 11. Core IBM Z resources 593

 Level 04a

HTTP method and URI

GET /api/console/password-rules/{password-rule-id}

In this request, the URI variable {password-rule-id} is the element ID of the Password Rule object whose
properties are to be returned.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the Password Rule object as defined in the “Data model” on page 589. 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
This operation returns the current properties of a single Password Rule object that is designated by
{password-rule-id}.

On successful execution, all of the current properties as defined in the data model for the Password Rule
object are provided in the response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing Password Rule object and the API user must have
user-related-access permission to it or action/task permission to the Manage Password Rules task. If
these conditions are not met, status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirement:
v User-related-access permission to the Password Rule object specified in the request URI or action/task
permission to the Manage Password Rules task

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, 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 request URI does not designate an existing resource of the correct type,
or designates a resource for which the API user does not have the required
authorization.

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

594 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/console/password-rules/ecb26fb4-4a7a-11e4-affa-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 345. Get Password Rule Properties: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT
content-type: application/json;charset=UTF-8
content-length: 656
{
"case-sensitive":true,
"character-rules":[
{
"alphabetic":"not-allowed",
"custom-character-sets":[
{
"character-set":"*!^",
"inclusion":"not-allowed"
}
],
"max-characters":256,
"min-characters":8,
"numeric":"not-allowed",
"special":"required"
}
],
"class":"password-rule",
"consecutive-characters":0,
"description":"Password must be very special",
"element-id":"ecb26fb4-4a7a-11e4-affa-1c6f65065a91",
"element-uri":"/api/console/password-rules/ecb26fb4-4a7a-11e4-affa-1c6f65065a91",
"expiration":0,
"history-count":0,
"max-length":256,
"min-length":8,
"name":"All specials",
"parent":"/api/console",
"replication-overwrite-possible":false,
"similarity-count":0,
"type":"user-defined"
}

Figure 346. Get Password Rule Properties: Response

Update Password Rule Properties

The Update Password Rule Properties operation updates the properties of a single user-defined
Password Rule object that is designated by its element ID.

HTTP method and URI

POST /api/console/password-rules/{password-rule-id}

In this request, the URI variable {password-rule-id} is the element ID of the Password Rule object whose
properties are to be updated.

Chapter 11. Core IBM Z resources 595

 Level 04a

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
This operation updates writable properties of the Password Rule object specified by {password-rule-id} .

The URI path must designate an existing Password Rule object; otherwise, status code 404 (Not Found) is
returned. If the user does not have user-related-access permission to the designated Password Rule object
or action/task permission to the Manage Password Rules task, status code 404 (Not Found) is returned.
If the user has user-related-access permission to the designated Password Rule object but not action/task
permission to the Manage Password Rules task, status code 403 (Forbidden) is returned

The request body is validated against the schema described in the request body contents section. If the
request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered. An attempt to update a system-defined password rule is not valid and fails
with status code 400 (Bad Request).

The request body does not need to specify a value for all writable properties, but rather can and should
contain fields only for the properties to be updated. Object properties for which no input value is
provided remain unchanged by this operation.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage Password Rules 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 296. Update Password Rule 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.
314 This operation is not supported for an object of this type. System-defined
password rules may not be updated.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.

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

596 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/console/password-rules/ecb26fb4-4a7a-11e4-affa-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 109
{
"description":"A new and improved description of this Password Rule",
"expiration":90,
"history-count":5
}

Figure 347. Update Password Rule Properties: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT

<No response body>

Figure 348. Update Password Rule Properties: Response

Create Password Rule

The Create Password Rule operation creates a user-defined Password Rule object with the given
properties.

HTTP method and URI

POST /api/console/password-rules

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The value to be set as the Password Rule's name property.
description String Optional The value to be set as the Password Rule's description
property.
expiration Integer Optional The value to be set as the Password Rule's expiration
property.
min-length Integer Optional The value to be set as the Password Rule's min-length
property.
max-length Integer Optional The value to be set as the Password Rule's max-length
property.
consecutive- Integer Optional The value to be set as the Password Rule's
characters consecutive-characters property.
similarity-count Integer Optional The value to be set as the Password Rule's
similarity-count property.
history-count Integer Optional The value to be set as the Password Rule's history-count
property.
case-sensitive Boolean Optional The value to be set as the Password Rule's case-sensitive
property.

Chapter 11. Core IBM Z resources 597

 Level 04a

Field name Type Rqd/Opt Description

character-rules Array of Optional The value to be set as the Password Rule's character-rules
objects property.

Response body contents

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

Field name Type Description

element-uri String/URI Canonical URI path of the new Password Rule object.

Description
This operation creates a new user-defined Password Rule.

On successful execution of this operation the Password Rule is created using the inputs as specified by
the request body. The URI of the new Password Rule is provided in the response body and in a Location
response header as well.

The request body is validated against the schema described in the “Request body contents” on page 597.
If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered. If the specified name is not unique, status code 400 (Bad Request) is
returned. In addition, the API user must have action/task permission to the Manage Password Rules
task; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage Password Rules 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” and the Location response header contains the URI of the newly created
object.

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.
Table 297. Create Password Rule: 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 password rule with the name specified in the request body already exists.
403 (Forbidden) 1 The API user does not have the required permission for this operation.

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

598 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/console/password-rules HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 298
{
"character-rules":[
{
"alphabetic":"not-allowed",
"custom-character-sets":[
{
"character-set":"*!^",
"inclusion":"not-allowed"
}
],
"max-characters":256,
"min-characters":8,
"numeric":"not-allowed",
"special":"required"
}
],
"description":"Password must be very special",
"name":"All specials"
}

Figure 349. Create Password Rule: Request

201 Created
server: zSeries management console API web server / 2.0
location: /api/console/password-rules/ecb26fb4-4a7a-11e4-affa-1c6f65065a91
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT
content-type: application/json;charset=UTF-8
content-length: 82
{
"element-uri":"/api/console/password-rules/ecb26fb4-4a7a-11e4-affa-1c6f65065a91"
}

Figure 350. Create Password Rule: Response

Delete Password Rule

The Delete Password Rule operation deletes a Password Rule object designated by its element ID.

HTTP method and URI

DELETE /api/console/password-rules/{password-rule-id}

In this request, the URI variable {password-rule-id} is the element ID of the Password Rule object to be
deleted.

Description
This operation removes a specified Password Rule from the console. The Password Rule is identified by
the {password-rule-id} variable in the URI.

Upon successfully removing the Password Rule, HTTP status code 204 (No Content) is returned and no
response body is provided.

Chapter 11. Core IBM Z resources 599

 Level 04a

The URI path must designate an existing Password Rule object; otherwise, status code 404 (Not Found) is
returned. If the user does not have user-related-access permission to the designated Password Rule object
or action/task permission to the Manage Password Rules task, status code 404 (Not Found) is returned.
If the user has user-related-access permission to the designated Password Rule object but not action/task
permission to the Manage Password Rules task, status code 403 (Forbidden) is returned. If any user has
the specified Password Rule, the request fails and status code 409 (Conflict) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage Password Rules task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned 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) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
409 (Conflict) 317 The object cannot be deleted at this time. One or more users have this
Password Rule.

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/console/password-rules/ecb26fb4-4a7a-11e4-affa-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 351. Delete Password Rule: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT

<No response body>

Figure 352. Delete Password Rule: Response

Inventory service data

Information about the Password Rules managed by the console can be optionally included in the
inventory data provided by the Inventory Service.

600 HMC Web Services API

 Level 04a

Inventory entries for Password Rule objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "console" are to be included. An entry for a particular Password Rule is
included only if the API user has access permission to that object as described in the Get Password Rule
Properties operation.

For each Password Rule object to be included, the inventory response array includes an entry that is a
JSON object with the same contents as is specified in the response body contents section for the Get
Password Rule Properties operation. That is, the data provided is the same as would be provided if a
Get Password Rule Properties operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single Password Rule. This object would appear as one array entry in the response
array:

Chapter 11. Core IBM Z resources 601

 Level 04a

{
"case-sensitive": false,
"character-rules": [
{
"alphabetic": "required",
"custom-character-sets": [],
"max-characters": 1,
"min-characters": 1,
"numeric": "not-allowed",
"special": "not-allowed"
},
{
"alphabetic": "allowed",
"custom-character-sets": [],
"max-characters": 6,
"min-characters": 4,
"numeric": "required",
"special": "not-allowed"
},
{
"alphabetic": "required",
"custom-character-sets": [],
"max-characters": 1,
"min-characters": 1,
"numeric": "not-allowed",
"special": "not-allowed"
}
],
"class": "password-rule",
"consecutive-characters": 2,
"description": "",
"element-id": "56d11882-eaff-11e2-9ec7-5cf3fcae8019",
"element-uri": "/api/console/password-rules/56d11882-eaff-11e2-
9ec7-5cf3fcae8019",
"expiration": 180,
"history-count": 0,
"max-length": 8,
"min-length": 6,
"name": "Strict",
"parent": "/api/console",
"replication-overwrite-possible": false,
"similarity-count": 0,
"type": "system-defined"
}

Figure 353. Password Rule object: Sample inventory data

LDAP Server Definition object

An LDAP Server Definition object is an element of the console object and contains information about an
LDAP server that may be used for console user authorization purposes. LDAP servers are sometimes
referred to as Enterprise Directory Servers on the zManager user interface and publications.

All API users are permitted to issue List LDAP Server Definitions and retrieve very basic information
for the LDAP Server Definition, if any, that applies to them. That is, they can use that operation to
retrieve very basic information for the LDAP Server Definition identified in their User object. An API user
with action/task permission to the Manage LDAP Server Definitions task is permitted to view and
change any LDAP Server Definition object.

602 HMC Web Services API

 Level 04a

LDAP Server Definition objects may be replicated to this HMC via its Data Replication facility. If that is
the case, the Update LDAP Server Definition Properties and Delete LDAP Server Definition operations
should be used with care as they will prevent further replication of the modified or deleted object to this
HMC.

Data model
This object contains the following properties. Certain properties are only valid when mutable prerequisite
properties have specific values. When such properties are not valid, their value is null. For instance the
search-filter is null when the location-method value is "pattern".

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.
Table 298. LDAP Server Definition object: properties
Name Qualifier Type Description
element-uri — String/URI The canonical URI path for an LDAP Server
Definition object is of the form /api/console/ldap-
server-definitions/{ldap-server-definition-id},
where {ldap-server-definition-id} is the value of the
element-id property of the LDAP Server Definition
object.
element-id — String (36) The unique identifier for this object.
parent — String/URI The canonical URI path of the console object.
class — String The class of an LDAP Server Definition object is
"ldap-server-definition".
name (ro) String The name of the LDAP Server Definition object. This
name must be unique among all LDAP Server
Definition objects defined to the console. While
preexisting LDAP Server Definition names are
virtually unrestricted in terms of length and
characters, new LDAP Server Definition names must
conform to the length and character requirements of
the name property described in the “Base managed
object properties schema” on page 60.

For the purpose of verifying uniqueness, this name is

treated in a case-insensitive fashion when used to
create a new LDAP Server Definition object.
description (w) String (0-1024) The description of the LDAP Server Definition object.

Default: an empty string

primary- (w) String, The host name or IP address of the primary LDAP
hostname-ipaddr String/IPV4 server. It must contain at least 1 non-whitespace
address, or character.
String/IPV6
address
connection-port (w) Integer The TCP port number, which must be greater than 0,
on which the server accepts connections, or null if
the server uses the standard LDAP port appropriate
for the value of the use-ssl property. The standard
LDAP port values are 636 if use-ssl is true and 389 if
use-ssl is false

Default: null

Chapter 11. Core IBM Z resources 603

 Level 04a

Table 298. LDAP Server Definition object: properties (continued)

Name Qualifier Type Description
backup- (w) String, The host name or IP address of the backup LDAP
hostname-ipaddr String/IPV4 server (which must contain at least 1 non-whitespace
address, or character), or null if there is none.
String/IPV6
address Default: null
use-ssl (w) Boolean Indicates whether the server uses SSL for incoming
connections.

Default: false
tolerate- (w) Boolean Indicates whether the server should tolerate
untrusted- self-signed or otherwise untrusted certificates.
certificates
Prerequisite: use-ssl is true

Default: false
bind- (w) String Part of the bind information for the initial
distinguished- connection, if needed: the distinguished name, which
name must contain at least 1 non-whitespace character;
otherwise, null.

Default: null

Prerequisite: Both bind-distinguished-name and

bind-password must be null, or they both must be
non-empty strings.
bind-password (wo) String Part of the bind information for the initial
connection, if needed: the password; otherwise, null

Default: null

Prerequisite: Both bind-distinguished-name and

bind-password must be null, or they both must be
non-empty strings.
location-method (w) String Enum The method this server uses to locate a user's
directory entry. Must be one of the following:
v "pattern" - Use a distinguished name pattern.
v "subtree" - Use a distinguished name subtree.
search- (w) String The distinguished name to use when searching for a
distinguished- user's directory entry.
name
If location-method is "pattern", this is the
distinguished name pattern to use when searching
for a user's directory entry. It must include the string
"{0}", which indicates where in the pattern the user
ID is to be substituted. The user ID is the value of
the userid-on-ldap-server property of the user's User
object, unless it is null, in which case the name
property of the User object is used.

If location-method is "subtree", this is the

distinguished name of the subtree to search for a
user's directory entry.

604 HMC Web Services API

 Level 04a

Table 298. LDAP Server Definition object: properties (continued)

Name Qualifier Type Description
search-scope (w) String Enum Indicates how much of the subtree should be
searched when searching for a user's directory entry
in a subtree. The filter is specified in the search-filter
property. Must be one of the following:
v "all" - Search the entire subtree.
v "one-level" - Search one level only.

Prerequisite: location-method is "subtree"

Default: "all"
search-filter (w) String The LDAP search filter to use when searching for a
user's directory entry in a subtree. It must include
the string "{0}", which indicates where in the filter
the user ID is to be substituted. The user ID is the
value of the userid-on-ldap-server property of the
user's User object, unless it is null, in which case the
name property of the User object is used. The
search-scope property specifies how this filter is
used during the search.

Prerequisite: location-method is "subtree"

replication- — Boolean Indicates whether this object is customizable data
overwrite- that is replicated to this HMC from an HMC
possible configured as a Data Source in the Data Replication
service.

List LDAP Server Definitions

The List LDAP Server Definitions operation lists LDAP Server Definitions defined to the console.

HTTP method and URI

GET /api/console/ldap-server-definitions

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.

Response body contents

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

Field name Type Description

ldap-server- Array of Array of nested ldap-server-definition-info objects as described in the next
definitions objects table.

Each nested ldap-server-definition-info object contains the following fields:

Field name Type Description

element-uri String/URI The element-uri property of the LDAP Server Definition object.
name String The name property of the LDAP Server Definition object.

Chapter 11. Core IBM Z resources 605

 Level 04a

Description
This operation lists LDAP Server Definitions defined to the console. Some basic properties are provided
for each LDAP Server Definition.

If the name query parameter is specified the returned list is limited to those LDAP Server Definitions that
have a name property matching the specified filter pattern. If the name parameter is omitted, this
filtering is not performed.

An LDAP Server Definition is included in the list only if the API user has user-related-access permission
to that object or action/task permission to the Manage LDAP Server Definitions task. If there is an
LDAP Server Definition 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 LDAP Server Definitions defined to the console or if no LDAP Server Definitions are to be
included in the results 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 User-related-access permission to the LDAP Server Definition objects included in the response body or
action/task permission to the Manage LDAP Server Definitions task

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 605.

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

GET /api/console/ldap-server-definitions?name=IBM.*&name=Company.* HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 354. List LDAP Server Definitions: Request

606 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:34 GMT
content-type: application/json;charset=UTF-8
content-length: 276
{
"ldap-server-definitions":[
{
"element-uri":"/api/console/ldap-server-definitions/3ac6550e-1dbb-11e4-9aa4-1c6f65065a91",
"name":"IBM LDAP server"
},
{
"element-uri":"/api/console/ldap-server-definitions/ece481ca-4a7a-11e4-8777-1c6f65065a91",
"name":"Company LDAP server"
}
]
}

Figure 355. List LDAP Server Definitions: Response

Get LDAP Server Definition Properties

The Get LDAP Server Definition Properties operation retrieves the properties of a single LDAP Server
Definition object that is designated by its element ID.

HTTP method and URI

GET /api/console/ldap-server-definitions/{ldap-server-definition-id}

In this request, the URI variable {ldap-server-definition-id} is the element ID of the LDAP Server Definition
object whose properties are to be returned.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the Password Rule object as defined in the “Data model” on page 603. 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
This operation returns the current properties of a single LDAP Server Definition object that is designated
by {ldap-server-definition-id}.

On successful execution, all of the current properties as defined in the data model for the LDAP Server
Definition object, except those designated as write-only properties, are provided in the response body,
and HTTP status code 200 (OK) is returned.

The URI path must designate an existing LDAP Server Definition object; otherwise, status code 404 (Not
Found) is returned. In addition, the API user must have action/task permission to the Manage LDAP
Server Definitions task; otherwise, status code 403 (Forbidden) is returned.

Chapter 11. Core IBM Z resources 607

 Level 04a

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage LDAP Server Definitions task.

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 607.

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 request URI does not designate an existing resource of the correct type
or the API user has no 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/console/ldap-server-definitions/ece481ca-4a7a-11e4-8777-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 356. Get LDAP Server Definition Properties: Request

608 HMC Web Services API

 Level 04a

00 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:34 GMT
content-type: application/json;charset=UTF-8
content-length: 640
{
"backup-hostname-ipaddr":null,
"bind-distinguished-name":null,
"class":"ldap-server-definition",
"connection-port":null,
"description":"Directory server for the company",
"element-id":"ece481ca-4a7a-11e4-8777-1c6f65065a91",
"element-uri":"/api/console/ldap-server-definitions/ece481ca-4a7a-11e4-8777-1c6f65065a91",
"location-method":"subtree",
"name":"Company LDAP server",
"parent":"/api/console",
"primary-hostname-ipaddr":"ldap1.our.company.com",
"replication-overwrite-possible":false,
"search-distinguished-name":"o=our,ou=company.com",
"search-filter":"email={0}",
"search-scope":"all",
"tolerate-untrusted-certificates":false,
"use-ssl":true
}

Figure 357. Get LDAP Server Definition Properties: Response

Update LDAP Server Definition Properties

The Update LDAP Server Definition Properties operation updates the properties of a single LDAP
Server Definition object that is designated by its element ID.

HTTP method and URI

POST /api/console/ldap-server-definitions/{ldap-server-definition-id}

In this request, the URI variable {ldap-server-definition-id} is the element ID of the LDAP Server Definition
object whose properties are to be updated.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
This operation updates writable properties of the LDAP Server Definition object specified by
{ldap-server-definition-id}.

The URI path must designate an existing LDAP Server Definition object; otherwise, status code 404 (Not
Found) is returned. In addition, the API user must have action/task permission to the Manage LDAP
Server Definitions task; otherwise, status code 403 (Forbidden) is returned.

Chapter 11. Core IBM Z resources 609

 Level 04a

The request body is validated against the schema described in the request body contents section. If the
request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered. The request body validation will fail if it contains a property that is not
valid because a prerequisite is not met (e.g., attempting to set search-filter when the location-method
value is "pattern").

The request body does not need to specify a value for all writable properties, but rather can and should
contain fields only for the properties to be updated. Object properties for which no input value is
provided and no prerequisite property is changed remain unchanged by this operation. A property's
value is set to its default value if the field is not included in the request body and a prerequisite field is
changed such that the prerequisite condition becomes satisfied (e.g., if location-method is changed from
"pattern" to "subtree", and search-scope is not defined in the request body, search-scope will be
defaulted to all).

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage LDAP Server Definitions 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, 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 request URI does not designate an existing resource of the correct type
or the API user has no 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

POST /api/console/ldap-server-definitions/ece481ca-4a7a-11e4-8777-1c6f65065a91 HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 133
{
"backup-hostname-ipaddr":"ldap2.my.company.com",
"description":"A new and improved description of this LDAP Server Definition"
}

Figure 358. Update LDAP Server Definition Properties: Request

610 HMC Web Services API

 Level 04a

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:34 GMT

<No response body>

Figure 359. Update LDAP Server Definition Properties: Response

Create LDAP Server Definition

The Create LDAP Server Definition operation creates an LDAP Server Definition object with the given
properties.

HTTP method and URI

POST /api/console/ldap-server-definitions

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The value to be set as the LDAP Server Definition's name
property.
description String Optional The value to be set as the LDAP Server Definition's
description property.
primary-hostname- String Required The value to be set as the LDAP Server Definition's
ipaddr primary-hostname-ipaddr property.
connection-port Integer Optional The value to be set as the LDAP Server Definition's
connection-port property.
backup-hostname- String Optional The value to be set as the LDAP Server Definition's
ipaddr backup-hostname-ipaddr property.
use-ssl Boolean Optional The value to be set as the LDAP Server Definition's use-ssl
property.
tolerate- Boolean Optional The value to be set as the LDAP Server Definition's
untrusted- tolerate-untrusted-certificates property.
certificates
bind- String Optional The value to be set as the LDAP Server Definition's
distinguished-name bind-distinguished-name property.
bind-password String Optional The value to be set as the LDAP Server Definition's
bind-password property.
location-method String Optional The value to be set as the LDAP Server Definition's
Enum location-method property.
search- String Required The value to be set as the LDAP Server Definition's
distinguished-name search-distinguished-name property.
search-scope String Optional The value to be set as the LDAP Server Definition's
Enum search-scope property.
search-filter String Required if The value to be set as the LDAP Server Definition's
location-method search-filter property.
is "subtree"

Chapter 11. Core IBM Z resources 611

 Level 04a

Response body contents

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

Field name Type Description

element-uri String/URI Canonical URI path of the new LDAP Server Definition object.

Description
This operation creates a new LDAP Server Definition.

On successful execution of this operation the LDAP Server Definition is created using the inputs as
specified by the request body. The URI of the new LDAP Server Definition is provided in the response
body and in a Location response header as well

The request body is validated against the schema described in the “Request body contents” on page 611.
If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered. The request body validation will fail if it contains a property that is not
valid because a prerequisite is not met (e.g., specifying search-filter when the location-method value is
"pattern") or the specified name is not unique. In addition, the API user must have action/task
permission to the Manage LDAP Server Definitions task; otherwise, status code 403 (Forbidden) is
returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage LDAP Server Definitions 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,” and the Location response header contains the URI of the newly created
object.

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.
Table 299. Create LDAP Server Definition: 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 An LDAP Server Definition with the name specified in the request body
already exists.
403 (Forbidden) 1 The API user does not have the required permission for this operation.

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

612 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/console/ldap-server-definitions HTTP/1.1

x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c
content-type: application/json
content-length: 264
{
"description":"Directory server for the company",
"location-method":"subtree",
"name":"Company LDAP server",
"primary-hostname-ipaddr":"ldap1.our.company.com",
"search-distinguished-name":"o=our,ou=company.com",
"search-filter":"email={0}",
"use-ssl":true
}

Figure 360. Create LDAP Server Definition: Request

201 Created
server: zSeries management console API web server / 2.0
location: /api/console/ldap-server-definitions/ece481ca-4a7a-11e4-8777-1c6f65065a91
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:33 GMT
content-type: application/json;charset=UTF-8
content-length: 94
{
"element-uri":"/api/console/ldap-server-definitions/ece481ca-4a7a-11e4-8777-1c6f65065a91"
}

Figure 361. Create LDAP Server Definition: Response

Delete LDAP Server Definition

The Delete LDAP Server Definition operation deletes an LDAP Server Definition object designated by
its element ID.

HTTP method and URI

DELETE /api/console/ldap-server-definitions/{ldap-server-definition-id}

In this request, the URI variable {ldap-server-definition-id} is the element ID of the LDAP Server Definition
object to be deleted.

Description
This operation removes a specified LDAP Server Definition from the console. The LDAP Server Definition
is identified by the {ldap-server-definition-id} variable in the URI.

Upon successfully removing the LDAP Server Definition, HTTP status code 204 (No Content) is returned
and no response body is provided.

The URI path must designate an existing LDAP Server Definition object; otherwise, status code 404 (Not
Found) is returned. In addition, the API user must have action/task permission to the Manage LDAP
Server Definitions task; otherwise, status code 403 (Forbidden) is returned. If any user is defined to use
the specified LDAP Server Definition, the request fails and HTTP status code 409 (Conflict) is returned.

Chapter 11. Core IBM Z resources 613

 Level 04a

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Manage LDAP Server Definitions task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned 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) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type
or the API user has no access permission to it.
409 (Conflict) 317 The object cannot be deleted at this time. One or more users have this LDAP
Server Definition.

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/console/ldap-server-definitions/ece481ca-4a7a-11e4-8777-1c6f65065a91
HTTP/1.1
x-api-session: 2t4ixcf8nplr7yersi8i9b953fgxvvqxl8c4r066ge9kcyzr4c

Figure 362. Delete LDAP Server Definition: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 21:27:34 GMT

<No response body>

Figure 363. Delete LDAP Server Definition: Response

Inventory service data

Information about the LDAP Server Definitions managed by the console can be optionally included in the
inventory data provided by the Inventory Service.

Inventory entries for LDAP Server Definition objects are included in the response to the Inventory
Service's Get Inventory operation when the request specifies (explicitly by class, implicitly via a
containing category, or by default) that objects of class "console" are to be included. An entry for a
particular LDAP Server Definition is included only if the API user has access permission to that object as
described in the Get LDAP Server Definition Properties operation.

614 HMC Web Services API

 Level 04a

For each LDAP Server Definition object to be included, the inventory response array includes an entry
that is a JSON object with the same contents as is specified in the response body contents section for the
Get LDAP Server Definition Properties operation. That is, the data provided is the same as would be
provided if a Get LDAP Server Definition Properties operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single LDAP Server Definition. This object would appear as one array entry in the
response array:

{
"backup-hostname-ipaddr": null,
"bind-distinguished-name": null,
"class": "ldap-server-definition",
"connection-port": null,
"description": "",
"element-id": "ffbf71f4-370d-11e4-a5fc-5ef3fcae8020",
"element-uri": "/api/console/ldap-server-definitions/ffbf71f4-370d-11e4-
a5fc-5ef3fcae8020",
"location-method": "pattern",
"name": "Temp_LDAP_13_56ba2f43-98c0-4848-9af8-cdb45b56f082",
"parent": "/api/console",
"primary-hostname-ipaddr": "bluepages.ibm.com",
"replication-overwrite-possible": false,
"search-distinguished-name": "uid={0}744,c=in,ou=bluepages,o=ibm.com",
"search-filter": null,
"search-scope": null,
"tolerate-untrusted-certificates": null,
"use-ssl": false
}

Figure 364. LDAP Server Definition object: Sample inventory data

Group Object
The Hardware Management Console provides a fixed set of system-defined groups to which managed
objects of certain types automatically belong, as members. For example, defined CPCs are automatically
members of the CPC group. By their nature, the members of the system-defined groups are obtainable via
list operations of the appropriate API. For example, all the CPCs managed by a Hardware Management
Console can be obtained via a List CPCs operation. Therefore, list operations for system-defined groups
are unnecessary. By their nature, the existence of a system-defined group and its content (members) is
implicit. Therefore, create/delete operations for system-defined groups are both unnecessary and
inappropriate.

These system-defined groups are distinct from user-defined (“custom”) groups. The latter are explicitly
created by users for their own purposes: for example, it may be convenient for management purposes to
take some proper subset of the members of the system-defined CPC group as a user-defined group of
CPCs. User-defined groups may be homogeneous (all members of the same managed object type, as in
this previous example), but need not be.

A Group object represents one or more managed objects which are called group members. Each member
is of some object type: CPC, Logical Partition, etc. Note that groups may be heterogeneous (with member
objects of differing types), and may even have other groups as members.

Users may define groups in one of two ways:

1. by use of a pattern-match expression to implicitly define membership (pattern-matching group)

Chapter 11. Core IBM Z resources 615

 Level 04a

2. by explicitly choosing members.

This API can be used to view/manage custom groups, and membership within these groups. The latter is
subject to restrictions, based on which of the two fundamentally different means of definition the user
employed:
v If pattern-matching was specified, then group membership is “implicit”. In this case, operations to
add/remove a member are unnecessary (simply create/delete the managed object, itself, using the
appropriate API operation). Accordingly, member-management operations are not supported for groups
using pattern-matching.
v If pattern-matching was not specified, then group membership is “explicit”, and in this case operations
to add/remove group members are both useful and appropriate. Accordingly, for custom groups not
based on pattern-matching, member-management operations are supported. Note that such operations
do not affect the member object itself, only its group membership status.
v When groups are defined using pattern-matching, the types of managed objects to which
pattern-matching is applied must be explicitly specified. Regardless of the POSIX regular expression
specified as the match pattern, managed objects whose names match the pattern but who are not of the
specified object type(s) are not considered to be members of the group.
v Groups are not intrinsically ordered in any way, nor are members within a given group. List-oriented
operations therefore do not return ordered results.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
but does not provide the operational-status-related properties defined in that schema because it does not
maintain the concept of an operational status.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58

The following class-specific specializations apply to the other base managed object properties:
Table 300. Group object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/ The canonical URI path of the Group object, of the form
URI /api/groups/{group-id} where {group-id} is the value of the object-id
property of the Group object.
parent — String This property is always a null object.
class — String The class of a Group object is "group".
name (ro) String The group name specified by the user when the group was created
description (ro) String The description specified by the user when the group was created, or
if none was provided, the IBM provided caption text.
replication- — Boolean Indicates whether this object is replicated to this HMC from an HMC
overwrite-possible configured as a Data Source in the Data Replication service.

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:
Table 301. Group object: class specific additional properties
Name Type Description
match-info match-info A nested object which pertains to pattern-matching groups only, as
object described in the next table. An empty value is returned for groups
which do not use pattern-matching.

616 HMC Web Services API

 Level 04a

The match-info object contains the following fields:

Table 302. match-info object properties
Name Type Description
pattern String A regular expression used to define membership for pattern-matching
groups. This field has no length limitations.
types Array of Specifies the type(s) of objects that are eligible for membership in
String Enum pattern-matching groups. One or more of the following:
v "custom-groups" - zManager API objects of class “group”
v "defined-cpc" - zManager API objects of class “cpc”
v "director-timer-console" - ESCON director and/or Sysplex timer
consoles
v "ibm-fiber-saver" - IBM 2029 fiber optic data transports
v "logical-partition" - zManager API objects of class “logical-partition”
v "zvm-virtual-machines" - zManager API objects of class
“virtual-server”, type of "zvm"
v "blade-center" - zManager API objects of class “bladecenter”
v "data-power-xi50z-blades" - zManager API objects of class “blade”,
type of "dpxi50z"
v "ibm-smart-analytics-optimizer-blades" - zManager API objects of
class “blade”, type of "isaopt"
v "power-blade" - zManager API objects of class “blade”, type of
"power"
v "system-x-blade" - zManager API objects of class “blade”, type of
"x-hyp"
v "power-vm-virtual-server" - zManager API objects of class
“virtual-server”, type of "power-vm"
v "system-x-virtual-server" - zManager API objects of class
“virtual-server”, type of "x-hyp"
v "workload" - zManager API objects of class “workload-resource-
group”.
v "defined-zbx-node" - zManager API objects of class “zbx”, type of
"node".

List Custom Groups

The List Custom Groups operation lists the custom groups which are visible to the API user.

HTTP method and URI

GET /api/groups

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. If matches are found, the response will be an
array with all objects that match. If no match is found, the response
will be an empty array.

Chapter 11. Core IBM Z resources 617

 Level 04a

Response body contents

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

Field name Type Description

groups Array of Array of nested objects which identify groups that are visible to the API
group-info user.
objects

Each nested group-info object contains the following fields:

Field name Type Description

object-uri String/URI The value of the Group object's object-uri property.
name String The value of the Group object's name property.

Description
This operation lists the Group objects which are visible to the API user. Only groups to which the caller
has authorization will be returned.

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in the
response body contents section. If no groups exist, or if no groups are visible to the API user, HTTP
status code 200 (OK) is returned, along with an empty response body.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Group object.

HTTP status and reason codes

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

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

HTTP error status 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.
299 A query parameter has an invalid syntax.

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

618 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/groups HTTP/1.1

x-api-session: 4ipkcgbjpy5kocelt652l3dvb85gi81iqy5bz8yrpt6vtrt8ks

Figure 365. List Custom Groups: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 16:02:42 GMT
content-type: application/json;charset=UTF-8
content-length: 283
{
"groups": [
{
"name": "Finance department CPCs",
"object-uri": "/api/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341"
},
{
"name": "Test Group",
"object-uri": "/api/groups/febde5ab-a4a6-35bf-9e01-83aae59d7e52"
}
]
}

Figure 366. List Custom Groups: Response

Get Custom Group Properties

The Get Custom Group Properties operation retrieves the properties of a single Group object that is
designated by the {group-id}.

HTTP method and URI

GET /api/groups/{group-id}

In this request, the URI variable {group-id} is the object ID of the group.

Response body contents

On success, HTTP status code 200 (OK) is returned and the response body contains an object that
provides the current values of the properties for the Group object as defined in “Data model” on page
616. Field names and data types in the object are the same as the property names and data types defined
in the data model.

Description
This operation returns the current properties for the Group object designated by {group-id}.

The URI path {group-id} must designate an existing Group object.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Group object designated by {group-id}.

Chapter 11. Core IBM Z resources 619

 Level 04a

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 619.

On error, appropriate 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 object-id in the URI ({group-id}) does not designate an existing group, or
the API user does not have sufficient access (as described above).

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/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341 HTTP/1.1

x-api-session: 42r6t4chltipvd6l4l61wi3111tf7fv2hes80hjqjs3invt7cp

Figure 367. Get Custom Group Properties: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 16:45:45 GMT
content-type: application/json;charset=UTF-8
content-length: 250
{
"class": "group",
"description": "Spacely Sprockets Web Servers",
"replication-overwrite-possible": false,
"is-locked": false,
"match-info": {},
"name": "SS-Web-Servers",
"object-id": "ee2782af-dd98-3ec0-bc2d-cfe2e9154341",
"object-uri": "/api/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341",
"parent": null
}

Figure 368. Get Custom Group Properties: Response

Create Custom Group

Use the Create Custom Group operation to create a custom group.

HTTP method and URI

POST /api/groups

620 HMC Web Services API

 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

name String Required The name for the new custom Group object
description String Optional The description for the new custom Group object
match-info match- Optional A nested object describing the pattern match. If not provided, this
info is not a pattern-match custom group. Refer to “Class specific
object additional properties” on page 616 for details.

Response body contents

Field name Type Description
object-uri String The object URI of the new custom group.

Description
Group objects are programmatically identified by object-id and not by name. To avoid the confusion
which might result from allowing redundant names, the name property is required for this operation,
and the (case-sensitive) value supplied for the name property must be distinct from that of all
currently-existing Group objects. In keeping with restrictions imposed by the Hardware Management
Console's Graphical User Interface (GUI), the following set of names is also not allowed:
v the current name of the Hardware Management Console
v the GUI View names {“Groups”, “Exceptions”, “Active Tasks”, “Console Actions”, “Task List”,
“Books”, “Help”, “Ensemble”}

On success, a custom group managed object is created reflecting the Request Body contents and HTTP
status code 201 (Created) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Action/task permission to the Grouping 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.” In addition, the Location response header contains the URI of the newly
created object.

On error, appropriate 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.

Chapter 11. Core IBM Z resources 621

 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.
261 One of the following errors was detected:
v The pattern string specified in match-info is not valid. This must be a
non-empty string which is a valid regular expression.
v One or more of the types specified in match-info is invalid. At least one
type must be specified, and all must be values as documented for the
match-info types property.
290 The requested name is either reserved or already in use.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform this operation.
500 (Server Error) 273 An unexpected error occurred during the operation.

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/groups HTTP/1.1

x-api-session: 42r6t4chltipvd6l4l61wi3111tf7fv2hes80hjqjs3invt7cp
content-type: application/json
content-length: 74
{
"description": "Spacely Sprockets Web Servers",
"name": "SS-Web-Servers"
}

Figure 369. Create Custom Group: Request

201 Created
server: zSeries management console API web server / 1.0
location: /api/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341
cache-control: no-cache
date: Fri, 25 Nov 2011 16:45:44 GMT
content-type: application/json;charset=UTF-8
content-length: 65
{
"object-uri": "/api/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341"
}

Figure 370. Create Custom Group: Response

Delete Custom Group

Use the Delete Custom Group operation to delete a custom group.

HTTP method and URI

DELETE /api/groups/{group-id}

In this request, the URI variable {group-id} is the object ID of the group.

622 HMC Web Services API

 Level 04a

Description
If successful, the custom group managed object designated by {group-id} is deleted.

If {group-id} does not identify an existing custom group, status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the custom group designated by {group-id}
v Action/task permission for the Grouping task.

HTTP status and reason codes

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

On error, appropriate 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 user under which the API request was authenticated does not have the
required authority to perform this operation.
404 (Not Found) 1 The URI's {group-id} does not designate an existing custom Group object, or
the API user does not have object-access to the group.
500 (Server Error) 273 An unexpected error occurred during the 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/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341 HTTP/1.1

x-api-session: 42r6t4chltipvd6l4l61wi3111tf7fv2hes80hjqjs3invt7cp

Figure 371. Delete Custom Group: Request

204 No Content
date: Fri, 25 Nov 2011 16:45:45 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 372. Delete Custom Group: Response

Add Member to Custom Group

Use the Add Member to Custom Group operation to add a member to a custom group.

Chapter 11. Core IBM Z resources 623

 Level 04a

HTTP method and URI

POST /api/groups/{group-id}/operations/add-member

In this request, the URI variable {group-id} is the object ID of the group.

Request body contents

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

Field name Type Rqd/Opt Description

object-uri String Required The object URI of the object to be added to the group

Description
If successful, the managed object designated in the request body attains membership in the custom group
identified by {group-id}.

The operation is subject to the following restrictions:

v The designated managed object must exist and must not already be a member of the group identified
by {group-id}
v The group identified by {group-id} must be a custom group defined without a pattern-matching
specification.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the custom Group object designated by {group-id}
v Object-access permission to the object designated by the request body
v Action/task permission for the Grouping task.

HTTP status and reason codes

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

On error, appropriate 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.
291 The designated managed object is already a member of the custom group
identified by {group-id}.
294 The group identified by {group-id} was defined using pattern-matching.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform this operation.
293 The addition of the member to the custom group designated by the URI
({group-id}) would introduce a circular reference, which is not permitted.
404 (Not Found) 1 The URI's {group-id} does not designate an existing custom Group object, or
the API user does not have object-access to the group.
2 The request body does not designate an existing managed object, or the API
user does not have sufficient access to the managed object.

624 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
500 (Server Error) 273 An unexpected error occurred during the operation.

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/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341/operations/add-member HTTP/1.1

x-api-session: 42r6t4chltipvd6l4l61wi3111tf7fv2hes80hjqjs3invt7cp
content-type: application/json
content-length: 75
{
"object-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af"
}

Figure 373. Add Member to Custom Group: Request

204 No Content
date: Fri, 25 Nov 2011 16:45:44 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 374. Add Member to Custom Group: Response

Remove Member from Custom Group

Use the Remove Member from Custom Group operation to remove a member from a custom group.

HTTP method and URI

POST /api/groups/{group-id}/operations/remove-member

In this request, the URI variable {group-id} is the object ID of the group

Request body contents

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

Field name Type Rqd/Opt Description

object-uri String Required The object URI of the object to be removed from the group

Description
The managed object designated in the request body relinquishes its membership in the custom group
identified by {group-id}.

The operation is subject to the following restrictions:

v The managed object designated in the request body must currently be a member of the group
identified by {group-id}.

Chapter 11. Core IBM Z resources 625

 Level 04a

v The group identified by {group-id} must be a custom group defined without a pattern-matching
specification

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the custom Group object designated by {group-id}
v Object-access permission to the object designated by the request body
v Action/task permission for the Grouping task.

HTTP status and reason codes

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

On error, appropriate 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.
291 The designated managed object is not a member of the custom group
identified by {group-id}.
294 The group identified by {group-id} was defined using pattern-matching.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform this operation.
404 (Not Found) 1 The URI's {group-id} does not designate an existing custom Group object, or
the API user does not have object-access to the group.
2 The request body does not designate an existing managed object, or the API
user does not have sufficient access to the managed object.
500 (Server Error) 273 An unexpected error occurred during the operation.

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/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341/operations/remove-member HTTP/1.1

x-api-session: 42r6t4chltipvd6l4l61wi3111tf7fv2hes80hjqjs3invt7cp
content-type: application/json
content-length: 75
{
"object-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af"
}

Figure 375. Remove Member from Custom Group: Request

626 HMC Web Services API

 Level 04a

204 No Content
date: Fri, 25 Nov 2011 16:45:45 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 376. Remove Member from Custom Group: Response

List Custom Group Members

Use the List Custom Group Members operation to list custom group members.

HTTP method and URI

GET /api/groups/{group-id}/members

In this request, the URI variable {group-id} is the object ID of the group.

Response body contents

Field name Type Description
members Array of Array of nested objects which identify members of the group designated by
nested {group-id}.
objects

Each nested member object contains the following fields:

Field name Type Description

object-uri String/URI The value of the member object's object-uri property.
name String The value of the member object's name property.

Description
This operation lists the members of the Group object designated by {group-id}. The results of this
operation only include references to member objects for which the API user has object-access authority.

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in the
response body contents section. If the group currently has no members, HTTP status code 200 (OK) is
returned, along with an empty response body.

On error, appropriate 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.

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

Chapter 11. Core IBM Z resources 627

 Level 04a

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 627.

On error, appropriate 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 group designated by the URI ({group-id}) does not exist, or the API user
does not have sufficient access (as described above).

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/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341/members HTTP/1.1

x-api-session: 42r6t4chltipvd6l4l61wi3111tf7fv2hes80hjqjs3invt7cp

Figure 377. List Custom Group Members: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 16:45:45 GMT
content-type: application/json;charset=UTF-8
content-length: 207
{
"members": [
{
"name": "SS-Web-Svr-1",
"object-uri": "/api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af"
},
{
"name": "SS-Web-Svr-2",
"object-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af"
}
]
}

Figure 378. List Custom Group Members: Response

Inventory service data

Information about custom groups can be optionally included in the inventory data provided by the
Inventory Service.

Inventory entries for the Group objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or

628 HMC Web Services API

 Level 04a

by default) that objects of the class "group" are to be included. An entry for a particular group is
included only if the API user has access permission to that object as described in the Get Custom Group
Properties operation.

For each Group object to be included, the inventory response array includes an entry that is a JSON
object with the same contents as is specified in the response body contents section for “Get Custom
Group Properties” on page 619. That is, the data provided is the same as would be provided if a Get
Custom Group Properties operation were requested targeting this object.

CPC object
A CPC object represents a single Central Processor Complex (CPC) that is being managed by an HMC.

Data model
For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

This object includes the properties defined in the “Base managed object properties schema” on page 60,
with the following class-specific specialization:
Table 303. CPC object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/ The canonical URI path of the CPC object, of the form
URI /api/cpcs/{cpc-id} where {cpc-id} is the value of the object-id
property of the CPC object.
parent (pc) String/ If the CPC is a member of an ensemble, the parent is the canonical
URI URI path for the ensemble object. Otherwise, this property contains a
null object.
class — String The class of a CPC object is "cpc".
name (ro) String (1-8) The CPC name
description (ro) if String The descriptive text associated with this CPC object. This property is a
dpm- (0-1024) writable, user-supplied value only when this CPC is enabled for DPM.
enabled is
false

or

(w)(pc) if
dpm-
enabled is
true

Chapter 11. Core IBM Z resources 629

 Level 04a

Table 303. CPC object: base managed object properties specializations (continued)
Name Qualifier Type Description of specialization
status (sc) String The current operational status of the CPC object. One of:
Enum v "active" - the CPC is active. This status is applicable only when
dpm-enabled is true.
v "operating" the CPC is operational. This status is applicable only
when dpm-enabled is false.
v "not-communicating" - the CPC is not communicating with the
HMC. With the exceptions of object-uri, parent, class, name, and
status, the values of CPC properties are unpredictable unless stated
otherwise in this data model.
v "exceptions" - the CPC has one or more unusual conditions
v "status-check" - the SE is not communicating with the CPC
v "service" - the CPC has been placed in service mode
v "not-operating" - the CPC is not operational
v "no-power" - the CPC has no power
v "service-required" - the CPC is operating on the last redundant part
of a particular type
v "degraded" - one or more of the CPC elements are degraded.
acceptable-status (w)(pc) Array of The set of operational status values in which the CPC object can exist
String and be considered in an acceptable (not alert causing) state. One or
Enum more of the values listed for the status property.

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties.
Table 304. CPC object: class specific additional properties
Name Qualifier Type Description
se-version (pc) String (1-8) The current release level of the primary SE internal code. For
example, “2.11.1”. Note that the alternate SE is normally at
the same level, except when installing new internal code
levels.
has-hardware- (pc) Boolean The CPC object has hardware messages (true), or does not
messages have hardware messages (false).
is-ensemble-member (pc) Boolean Whether the CPC is currently part of an ensemble (true) or
not (false).
iml-mode (pc) String Enum The Initial Microcode Load (IML) mode type of the CPC
object. One of:
v "not-set" - the CPC is not IMLed or the CPC is not
communicating with the HMC.
v "esa390" - the CPC is in ESA/390 mode
v "lpar" - the CPC is in logical partition mode
v "esa390-tpf" - the CPC is in ESA/390 TPF mode
v "dpm" - the CPC is in DPM mode
dpm-enabled — Boolean The CPC is enabled for DPM (true) or not (false).

630 HMC Web Services API

 Level 04a

Table 304. CPC object: class specific additional properties (continued)

Name Qualifier Type Description
auto-start-list (pc) Array of The array of nested auto-start-entry objects in sequence, each
objects representing a single partition or a group of partitions that
are automatically started when this CPC is started. This is an
ordered array. The partitions or partition groups that are
earlier in the array are started before those that are later in
the array. The order in which the individual partitions within
a given partition group are started is not specified. An empty
array indicates that no partitions are automatically started.
The auto-start list is specified via the Set Auto-Start List
operation.

This property is only present when dpm-enabled is true.

is-cpacf-enabled — Boolean Whether Central Processor Assist for Cryptographic
Functions (CPACF) is enabled (true) for the CPC or not
(false).
next-activation-profile- (w)(pc) String (1-16) For a CPC that is not enabled for DPM, the name of the
name activation profile to be used on the next activation of the
CPC.
Note: This property is not returned on a Get CPC Properties
operation when the CPC is enabled for DPM.
Note: This property is not permitted on an Update CPC
Properties operation when the CPC is enabled for DPM.
last-used-activation- (pc) String (0-16) For a CPC that is not enabled for DPM, the name of the
profile activation profile used on the last activation of the CPC or an
empty string.
Note: This property is not returned on a Get CPC Properties
operation when the CPC is enabled for DPM.
last-used-iocds (pc) String (0-3) For a CPC that is not enabled for DPM, the name of the
IOCDS most recently used by the CPC or an empty string if
the CPC has not been IMLed.
Note: This property is not returned on a Get CPC Properties
operation when the CPC is enabled for DPM.
machine-model (pc) String (1-3) The model of the machine containing this CPC. For example,
“M15”.
machine-type (pc) String (1-4) The type of the machine containing this CPC. For example,
“2817”.
machine-serial-number (pc) String (1-12) The serial number of the machine containing this CPC. For
example, “00 - SP1D92B”.
cpc-serial-number — String (1-12) The serial number of the CPC. For example,
“00000SP1D92B”.
cpc-node-descriptor (pc) String (2) The hexadecimal number mapped to the device location of
the CPC. This property identifies the CPC's relative order
among other CPCs, if any, in the machine. For example, “00”.
is-cbu-installed — Boolean The Capacity Backup Upgrade (CBU) facility is installed
(true), or not installed (false). Note: if status is
"not-communicating", a null object is returned. Refer to the
Capacity On Demand User's Guide for details.
is-cbu-enabled — Boolean CBU is enabled (true), or is not enabled (false). Note: if status
is "not-communicating", a null object is returned. Refer to
the Capacity On Demand User's Guide for details.

Chapter 11. Core IBM Z resources 631

 Level 04a

Table 304. CPC object: class specific additional properties (continued)

Name Qualifier Type Description
is-cbu-activated — Boolean CBU is activated (true), or is not activated (false). Note: if
status is "not-communicating", a null object is returned.
Refer to the Capacity On Demand User's Guide for details.
is-real-cbu-available — Boolean Real CBU is available (true), or not available (false). Note: if
status is "not-communicating", a null object is returned.
Refer to the Capacity On Demand User's Guide for details.
cbu-activation-date — Timestamp The date of CBU activation. Note: if status is
"not-communicating", a null object is returned. Refer to the
Capacity On Demand User's Guide for details.
cbu-expiration-date — Timestamp The date of CBU expiration. Note: if status is
"not-communicating", a null object is returned. Refer to the
Capacity On Demand User's Guide for details.
cbu-number-of-tests- — Integer The number of CBU tests left. Note: if status is
left "not-communicating", a null object is returned. Refer to the
Capacity On Demand User's Guide for details.
is-service-required — Boolean Whether the CPC is operating using the last redundant part
of a particular type (true) or not (false). If true, repairs
should be made before additional parts fail that would make
this CPC non-operational.

Support Element (Version 2.12.1 and newer) information can

be found on console help system. For information about
earlier versions of the Support Element, see the Support
Element Operations Guide.
degraded-status (pc) Array of The set of degraded status values. If the CPC is not
String Enum degraded, this property contains “not-degraded” as the only
value. Otherwise, this property contains one or more of the
following:
v "memory" - loss of memory
v "io" - loss of I/O channels
v "node" - one or more books are no longer functioning
v "ring" - the ring connecting the book is open
v "cbu" - CBU resources have expired
v "mru" - cycle time reduction due to an MRU problem
v "ambient-temp" - cycle time reduction due to a
temperature problem
v "iml" - CPC was IMLed during cycle time reduction.
processor-running- (w) String Enum For a CPC that is not enabled for DPM, denotes how the
time-type processor-running-time property value was determined. One
of:
v "system-determined" - the processor running time is
dynamically determined by the system
v "user-determined" - the processor running time is set to a
constant value.
Note: If iml-mode is not "lpar", a null object is returned.
Note: This property is not returned on a Get CPC Properties
operation when the CPC is enabled for DPM.
Note: This property is not permitted on an Update CPC
Properties operation when the CPC is enabled for DPM.

632 HMC Web Services API

 Level 04a

Table 304. CPC object: class specific additional properties (continued)

Name Qualifier Type Description
processor-running- (w) Integer For a CPC that is not enabled for DPM, the amount of
time continuous time, in milliseconds, allowed for logical
processors to perform jobs on shared processors for the CPC
object. Note: a null object is returned if the iml-mode is not
"lpar" or processor-running-time-type is "system-
determined".
Note: This property is not returned on a Get CPC Properties
operation when the CPC is enabled for DPM.
Note: This property is not permitted on an Update CPC
Properties operation when the CPC is enabled for DPM.
does-wait-state-end- (w) or — if Boolean For a CPC that is not enabled for DPM, Logical Partitions of
time-slice se-version is the CPC should lose their share of running time when they
"2.14.0" or enter a wait state (true), or should not lose their share of
later running time when they enter a wait state (false). Note: a
null object is returned if the iml-mode is not "lpar" or
processor-running-time-type is "system-determined".
Note: This property is not returned on a Get CPC Properties
operation when the CPC is enabled for DPM.
Note: This property is not permitted on an Update CPC
Properties operation when the CPC is enabled for DPM.
Note: When se-version is "2.14.0" or later, this property is
not permitted on an Update CPC Properties operation, and
its value is always false.
is-on-off-cod-installed — Boolean On/Off Capacity on Demand is installed for the CPC object
(true), or is not installed (false). Note: if status is
"not-communicating", a null object is returned. Refer to the
Capacity On Demand User's Guide for details.
is-on-off-cod-enabled — Boolean On/Off CoD is enabled (true), or is not enabled (false). Note:
if status is "not-communicating", a null object is returned.
Refer to the Capacity On Demand User's Guide for details.
is-on-off-cod-activated — Boolean On/Off CoD is currently activated for the CPC object (true),
or is not currently activated (false). Note: if status is
"not-communicating", a null object is returned. Refer to the
Capacity On Demand User's Guide for details.
on-off-cod-activation- — Timestamp The date when On/Off CoD was activated. Note: if status is
date "not-communicating", a null object is returned. Refer to the
Capacity On Demand User's Guide for details.
software-model- (pc) String (1-3) The software model based on the permanent processors. For
permanent example, “700”.
software-model- (pc) String (1-3) The software model based on the permanent plus billable
permanent-plus- processors. For example, “700”.
billable
software-model- (pc) String (1-3) The software model based on the permanent plus all
permanent-plus- temporary processors. For example, “700”.
temporary
msu-permanent — Integer The MSU value associated with the software model based on
the permanent processors.
msu-permanent-plus- — Integer The MSU value associated with the software model based on
billable the permanent plus billable processors.
msu-permanent-plus- — Integer The MSU value associated with the software model based on
temporary the permanent plus all temporary processors.

Chapter 11. Core IBM Z resources 633

 Level 04a

Table 304. CPC object: class specific additional properties (continued)

Name Qualifier Type Description
processor-count- — Integer The count of active general purpose processors.
general-purpose
processor-count- — Integer The count of active service assist processors.
service-assist
processor-count-aap — Integer The count of active IBM zEnterprise Application Assist
Processor (zAAP) processors.
processor-count-ifl — Integer The count of active Integrated Facility for Linux (IFL)
processors.
processor-count-icf — Integer The count of active Internal Coupling Facility (ICF)
processors.
processor-count-iip — Integer The count of active IBM z Integrated Information Processor
(zIIP) processors.
| processor-count-cbp2 — Integer The count of active Container Based Processors (CBP).
processor-count- — Integer The count of defective processors. Includes all processor
defective types.
processor-count-spare — Integer The count of spare processors. Includes all processor types.
processor-count- — Integer The combined number of processors that will become active,
pending when more processors are made available by adding new
hardware or by deactivating capacity records.
processor-count- — Integer The number of general purpose processors that will become
pending-general- active, when more processors are made available by adding
purpose new hardware or by deactivating capacity records. Note: if
status is "not-communicating", a null object is returned.
processor-count- — Integer The number of service assist processors that will become
pending-service-assist active, when more processors are made available by adding
new hardware or by deactivating capacity records. Note: if
status is "not-communicating", a null object is returned.
processor-count- — Integer The number of Application Assist processors that will
pending-aap become active, when more processors are made available by
adding new hardware or by deactivating capacity records.
Note: if status is "not-communicating", a null object is
returned.
processor-count- — Integer The number of Integrated Facility for Linux processors that
pending-ifl will become active, when more processors are made available
by adding new hardware or by deactivating capacity records.
Note: if status is "not-communicating", a null object is
returned.
processor-count- — Integer The number of Integrated Coupling Facility processors that
pending-icf will become active, when more processors are made available
by adding new hardware or by deactivating capacity records.
Note: if status is "not-communicating", a null object is
returned.
processor-count- — Integer The number of z Integrated Information Processors that will
pending-iip become active, when more processors are made available by
adding new hardware or by deactivating capacity records.
Note: if status is "not-communicating", a null object is
returned.

634 HMC Web Services API

 Level 04a

Table 304. CPC object: class specific additional properties (continued)

Name Qualifier Type Description
| processor-count- — Integer The number of Container Based Processors that will become
| pending-cbp2 active, when more processors are made available by adding
| new hardware or by deactivating capacity records.
| Note: If status is "not-communicating", a null object is
| returned.
has-temporary- — Boolean Whether API applications are allowed to make changes to
capacity-change- temporary capacity (true), or not (false).
allowed
ec-mcl-description — ec-mcl- Describes the Engineering Change (EC) and MicroCode Level
description (MCL) for the CPC object. An empty object is returned if the
object information is unavailable from the SE. Refer to the
description of the ec-mcl-description object for details.
has-automatic-se- — Boolean Automatic switching between primary and alternate Support
switch-enabled Elements is enabled for the CPC object (true), or is not
enabled (false).

Support Element (Version 2.12.1 and newer) information can

be found on console help system. For information about
earlier versions of the Support Element, see the Support
Element Operations Guide.
stp-configuration — stp-config Describes the Server Time Protocol (STP) configuration. Refer
object to the description of the stp-config object for details. Note: if
the required feature(s) are not installed, the property is not
returned.
lan-interface1-type (pc) String Enum The adapter type of the Support Element's LAN interface 1.
One of the following:
v "ethernet"
v "token-ring"
v "unknown"
lan-interface1-address (pc) String (1-12) The MAC address of the Support Element's LAN interface 1.
lan-interface2-type (pc) String Enum The adapter type of the Support Element's LAN interface 2.
One of the following:
v "ethernet"
v "token-ring"
v "unknown"
lan-interface2-address (pc) String (1-12) The MAC address of the Support Element's LAN interface 2.
network1-ipv4-mask (pc) String (1-15) The network IP mask value.
network1-ipv4-pri- (pc) String IPV4 The primary IPv4 address or a null object if not configured.
ipaddr address
network1-ipv4-alt- (pc) String IPV4 The alternate IPv4 address or a null object if not configured.
ipaddr address
network1-ipv6-info — Array of A list of objects describing the Support Element's IPv6
ipv6-info network connections. If no IPv6 connections are defined, an
objects empty list is returned.
network2-ipv4-mask (pc) String (1-15) The network IP mask value.
network2-ipv4-pri- (pc) String IPV4 The primary IPv4 address or a null object if not configured.
ipaddr address
network2-ipv4-alt- (pc) String IPV4 The alternate IPv4 address or a null object if not configured.
ipaddr address

Chapter 11. Core IBM Z resources 635

 Level 04a

Table 304. CPC object: class specific additional properties (continued)

Name Qualifier Type Description
network2-ipv6-info — Array of A list of objects describing the Support Element's IPv6
ipv6-info network connections. If no IPv6 connections are defined, an
objects empty list is returned.
hardware-messages (c)(pc) Array of The complete list of all CPC hardware messages, each
hardware- identified by its URI. This list corresponds to the list
message provided by the List CPC Hardware Messages operation. If
objects the CPC has no hardware messages, then an empty array is
provided.

The list of returned hardware messages can change as a

result of new messages being dynamically added or removed
by the infrastructure or due to hardware messages being
deleted via the Delete CPC Hardware Message operation.
Note: This property is not returned by the Get CPC
Properties operation, and only sessions associated with an
HMC user with permission to the Hardware Messages task
will receive a property-change notification for this property.
management- (pc) String Enum The zManager management enablement level for this system.
enablement-level The management-enablement-level values of an ensemble's
nodes determine the ensemble's management-enablement-
level, which determines the zManager advanced
management functions that are available for use.

All ensemble nodes must have the same

management-enablement-level. A CPC with a
management-enablement-level of "automate" may be added
to an ensemble with a management-enablement-level of
"manage", but this will downgrade the system's
management-enablement-level until all ensemble nodes are
upgraded to "automate".

Note: if status is "not-communicating", or if the target CPC

is not in an Ensemble, a null object is returned.

Values:
v "manage" - provides the controls for managing an
ensemble. It includes HMC operational controls for zBX,
change management of firmware across the ensemble,
energy monitoring, virtual networking with automated
provisioning, virtual server management, and a base level
of performance management.
v "automate" - Provides more leverage from the ensemble by
managing workloads and energy. This level of support
includes power capping, power savings mode, and
platform performance management.
storage-total-installed — Long Amount of installed storage, in megabytes.
storage-hardware- — Long Amount of storage, in megabytes, reserved for the base
system-area hardware system area (HSA).
storage-customer — Long Amount of storage, in megabytes, for use by the customer.
storage-customer- — Long Amount of storage, in megabytes, which is the central
central storage in use across the active partitions.
storage-customer- — Long Amount of storage, in megabytes, which is the expanded
expanded storage in use across the active partitions.

When the iml-mode is "dpm" this property will be set to 0.

636 HMC Web Services API

 Level 04a

Table 304. CPC object: class specific additional properties (continued)

Name Qualifier Type Description
storage-customer- — Long Amount of storage, in megabytes, which is not in use.
available
storage-vfm-increment- — Long The increment size of any IBM Virtual Flash Memory (VFM)
size1 storage property, in gigabytes (GB), on this CPC and its
logical partitions or partitions.
storage-vfm-total1 — Long The total amount of VFM storage, in gigabytes (GB), installed
on this CPC. The valid value should be a multiple of the
value indicated on the storage-vfm-increment-size property
for this CPC.
maximum-hipersockets — Integer The maximum number of HiperSocket adapters that may be
created for the CPC when the CPC is enabled for DPM.

This property will be omitted if dpm-enabled is false.

maximum-alternate- — Integer The maximum number of alternate storage-site instances that
storage-sites may be added to the FICON configuration associated with
this CPC.

This property will be omitted if dpm-enabled is false.

| available-features-list — Array of The list of optional features or behavior supported by this
| cpc-feature- CPC. If the CPC has no optional features, then an empty
| info objects array is provided.
| maximum-partitions — Integer The maximum number of partitions that this CPC supports.

| This property will be omitted if dpm-enabled is false.

Notes:
1. On a Get request, this property is returned only when the SE version is 2.14.0 or later.
| 2. On a Get request, this property is returned only when the associated SE version is 2.14.0 with the suitable MCL
| bundle, or a later SE version.

Table 305. ipv6-info object properties

Name Type Description
type String Enum The IPv6 scope. One of the following values:
v "link-local"
v "static"
v "auto"
prefix Integer The number of leading bits of the IPv6 address that represent the
network prefix
pri-ip-address String IPV6 The primary IPv6 address
address
alt-ip-address String IPV6 The alternate IPv6 address or a null object if not configured
address

Table 306. hardware-message object properties

Name Type Description
element-uri String/URI The canonical URI path of the CPC hardware message. The URI is in
the following form: /api/cpcs/{cpc-id}/hardware-messages/
{hardware-message-id}, where {hardware-message-id} is the value of the
element-id property of the hardware message.
element-id String (36) The unique identifier for the hardware message. The element-id is in
the form of a UUID.

Chapter 11. Core IBM Z resources 637

 Level 04a

Table 306. hardware-message object properties (continued)

Name Type Description
parent String/URI The parent of a CPC hardware message is the CPC object. The parent
value is the canonical URI path for the CPC.
class String The class of a hardware message object is "hardware-message".
timestamp Timestamp The timestamp represents the date and time when the hardware
message was created.
text String The text of the hardware message.

| Table 307. cpc-feature-info object properties

| Name Type Description
| name String Enum The name of the feature. One of:
| v "dpm-storage-management" - Indicates that the CPC
| supports Storage Groups and FICON storage resources. FCP
| and FICON storage resources are defined in Storage Groups,
| which are then attached to this CPC's partitions. If the CPC
| does not have this feature, FCP storage resources are
| represented by HBAs, which must be directly attached to this
| CPC's Partitions. This feature is applicable only for CPCs
| enabled for DPM.

| 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 CPC.
|

auto-start-entry object

An auto-start-entry object specifies either a partition or a group of partitions that are automatically
started when the CPC is started. Every auto-start-entry object contains the following base properties in
addition to the type-specific properties:
Table 308. auto-start-entry object base properties
Name Type Description
post-start-delay Integer Amount of time, in seconds, to wait before starting the next
partition or group of partitions. Must be greater than or equal
to 0.
type String Enum The type of auto-start-entry. One of
v "partition" - this entry identifies a single partition.
v "partition-group" - this entry identifies a partition group.

An auto-start-entry object with a type value of "partition" identifies a single partition. In addition to the
base properties, it contains the following type-specific properties:
Table 309. auto-start-entry object type-specific properties when type value is "partition"
Name Type Description
partition-uri String/URI The URI of the partition to start.

An auto-start-entry object with a type value of "partition-group" identifies a group of partitions. In

addition to the base properties, it contains the following type-specific properties:

638 HMC Web Services API

 Level 04a

Table 310. auto-start-entry object type-specific properties when type value is "partition-group"
Name Type Description
name String (1-64) The name of this partition group. This name must be unique
among all partition groups of this CPC. The length and
character requirements on this property are the same as those
of the name property described in the “Base managed object
properties schema” on page 60.
description String (0-1024) The Description for this partition group.
partition-uris Array of String/URI The list of one or more partitions to start, represented by their
URIs. This list is unordered. The partitions in a group can be
started in any order or simultaneously by the system.

Energy management related additional properties

In addition to the properties defined in “Class specific additional properties” on page 630, this object
includes the following additional class-specific properties related to energy management. For further
explanation of the various states involved, please see “Special states” on page 819.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.
Table 311. CPC object: energy management related additional properties
Name Qualifier Type Description
cpc-power-rating — Integer Specifies the maximum power draw in watts (W) of this CPC.
This is a calculated value as indicated by the electrical rating
labels or system rating plates of the CPC components.
cpc-power- (mg) Integer Specifies the current power consumption in watts (W) for this
consumption CPC. The CPC power consumption includes the power
consumption of the zCPC and BladeCenters. The BladeCenter
power consumption includes the power consumption of the
blades contained within the BladeCenter. If the system does not
include a BladeCenter, the CPC power consumption will be
equal to the zCPC power consumption.
cpc-power-saving — String Enum Specifies the current power saving setting of the CPC. Power
saving is used to reduce the energy consumption of a system
and can be managed in the Set Power Saving operation. The
possible settings include:
v "high-performance" - The power consumption and
performance of the CPC are not reduced. This is the default
setting.
v "low-power" - All components of the CPC enabled for power
saving will have reduced performance to allow for low power
consumption.
v "custom" - Custom mode indicates that some, but not all,
components of the CPC are in the Low power setting.
v "not-supported" - Power saving is not supported for this
CPC.
v "not-available" - Specifies that cpc-power-saving property
could not be read from this CPC.
v "not-entitled" - The server is not entitled for Power saving.

Chapter 11. Core IBM Z resources 639

 Level 04a

Table 311. CPC object: energy management related additional properties (continued)
Name Qualifier Type Description
cpc-power-saving- — String Enum Specifies the power saving setting of the CPC set by the user.
state Please note that this property indicates the user setting and may
not match the real state of the hardware compared to the
cpc-power-saving property. For more information, see “Group
power saving” on page 820. The possible settings include:
v "high-performance" - Specifies not reducing the power
consumption and performance of the CPC.
v "low-power" - Specifies low power consumption for all
components of the CPC enabled for power saving.
v "custom" - Specifies that the CPC does not control the
children. This is the default setting.
v "not-supported" - Specifies that power saving is not
supported for this CPC.
v "not-entitled" - Specifies that the server is not entitled to
power saving.
cpc-power-save- — String Enum Should be used to determine if a call of the power save
allowed operation is currently allowed. If a value other than "allowed"
is returned the caller may reckon that the power save operation
will fail.

The possible settings include:

v "allowed" - Alter power save setting is allowed for this CPC
v "unknown" - Unknown reason
v "not-supported" - Power saving is not supported for this
CPC.
v "not-entitled" - Specifies the server is not entitled to power
capping.
cpc-power-capping- — String Enum Specifies the current power capping setting of the CPC. Power
state capping is used to limit peak power consumption of a system
and can be managed in the Set Power Cap operation. The
possible settings include:
v "disabled" - The power cap of the CPC is not set and the
peak power consumption is not limited. This is the default
setting.
v "enabled" - All components of the CPC available for power
capping will be capped to limit the peak power consumption
of the CPC.
v "custom" - The components of the CPC can be individually
configured for power capping.
v "not-supported" - Power capping is not supported for this
CPC.
v "not-entitled" - The server is not entitled for Power capping.
cpc-power-cap- — Integer Specifies the minimum value for the CPC cap value in watts
minimum (W). This is a sum of the component minimum cap values. If
the cpc-power-cap-allowed property value is "not-entitled", the
value is null. For more information on entitlement, see
Chapter 12, “Energy management,” on page 817
cpc-power-cap- — Integer Specifies the maximum value for the CPC cap value in watts
maximum (W). This is a sum of the component maximum cap values. If
the cpc-power-cap-allowed property value is "not-entitled", the
value is null. For more information on entitlement, see
Chapter 12, “Energy management,” on page 817

640 HMC Web Services API

 Level 04a

Table 311. CPC object: energy management related additional properties (continued)
Name Qualifier Type Description
cpc-power-cap- — Integer Specifies the current cap value for the CPC in watts (W). The
current current cap value indicates the power budget for the CPC and
is the sum of the component Cap values. If the
cpc-power-cap-allowed property value is "not-entitled", the
value is null. For more information on entitlement, see
Chapter 12, “Energy management,” on page 817
cpc-power-cap- — String Enum Should be used to determine if a call of the power capping
allowed operation is currently allowed. If a value other than "allowed"
is returned the caller may reckon that the power capping
operation will fail.

The possible settings include:

v "allowed"- Alter power capping setting is allowed for this
CPC
v "unknown" - Unknown reason
v "not-supported" - Power capping is not supported for this
CPC.
v "not-entitled" - Specifies the server is not entitled to power
capping.
zcpc-power-rating — Integer Specifies the maximum power draw in watts (W) of this zCPC.
This is a calculated value as indicated by the electrical rating
labels or system rating plates of the zCPC components.
zcpc-power- (mg) Integer Specifies the current power consumption of the zCPC in watts
consumption (W).
zcpc-power-saving — String Enum Specifies the current power saving setting of the zCPC. Power
saving is used to reduce the energy consumption of a system
and can be managed in the Set Power Saving operation. The
possible settings include:
v "high-performance" - The power consumption and
performance of the zCPC are not reduced. This is the default
setting.
v "low-power" - The performance of the zCPC is reduced to
allow for low power consumption.
v "not-supported" - Power saving is not supported for this
zCPC.
v "not-available" - Specifies that zcpc-power-saving property
could not be read for this zCPC.
v "not-entitled" - The server is not entitled for Power saving.
zcpc-power-saving- — String Enum Specifies the power saving setting of the zCPC set by the user.
state Please note that this property indicates the user setting and may
not match the real state of the hardware compared to the
zcpc-power-saving property. For more information, see “Group
power saving” on page 820. The possible settings include:
v "high-performance" - Specifies not reducing the power
consumption and performance of the zCPC. This is the
default setting.
v "low-power" - Specifies low power consumption for all
components of the zCPC enabled for power saving.
v "not-supported" - Specifies that power saving is not
supported for this zCPC.
v "not-entitled" - Specifies that the server is not entitled to
power saving.

Chapter 11. Core IBM Z resources 641

 Level 04a

Table 311. CPC object: energy management related additional properties (continued)
Name Qualifier Type Description
zcpc-power-save- — String Enum Should be used to determine if a call of the power save
allowed operation is currently allowed. If a value other than "allowed"
is returned the caller may reckon that the power save operation
will fail.

The possible settings include:

v "allowed" - Alter power save is allowed for this zCPC
v "unknown" - Unknown reason
v "not-entitled" - Specifies the server is not entitled to power
save.
v "under-group-control" - The zCPC is under group control
and cannot be individually altered.
v "not-supported" - Power saving is not supported for this
zCPC.
v "once-a-day-exceeded" - Power saving mode has been entered
at some point during the day and will not be allowed again
until the next calendar day.
zcpc-power- String Enum Specifies the current power capping setting of the zCPC. Power
capping-state capping is used to limit peak power consumption of a system
and can be managed in the Set Power Cap operation. The
possible settings include:
v "disabled" - The power cap of the zCPC is not set and the
peak power consumption is not limited. This is the default
setting.
v "enabled" - The peak power consumption of the zCPC is
limited to the Current cap value.
v "custom" - The components of the CPC can be individually
configured for power capping.
v "not-supported" - Power capping is not supported for this
zCPC.
v "not-entitled" - The server is not entitled for Power capping.
zcpc-power-cap- — Integer Specifies the minimum value for the zCPC cap value in watts
minimum (W). If the zcpc-power-cap-allowed property value is
"not-entitled", the value is null. For more information on
entitlement, see Chapter 12, “Energy management,” on page 817
zcpc-power-cap- — Integer Specifies the maximum value for the zCPC cap value in watts
maximum (W). If the zcpc-power-cap-allowed property value is
"not-entitled", the value is null. For more information on
entitlement, see Chapter 12, “Energy management,” on page 817
zcpc-power-cap- — Integer Specifies the current cap value for the CPC in watts (W). The
current current cap value indicates the power budget for the zCPC. If
the zcpc-power-cap-allowed property value is "not-entitled",
the value is null. For more information on entitlement, see
Chapter 12, “Energy management,” on page 817

642 HMC Web Services API

 Level 04a

Table 311. CPC object: energy management related additional properties (continued)
Name Qualifier Type Description
zcpc-power-cap- — String Enum Should be used to determine if a call of the power capping
allowed operation is currently allowed. If a value other than "allowed"
is returned the caller may reckon that the power capping
operation will fail.

The possible settings include:

v "allowed" - Alter power capping is allowed for this zCPC
v "unknown" - Unknown reason
v "not-entitled" - Specifies the server is not entitled to power
cap.
v "not-supported" - Power capping is not supported for this
zCPC.
v "under-group-control" - Power capping is under group
control
zcpc-ambient- (mg) Float Specifies the input air temperature in degrees Celsius (ºC) as
temperature measured by the system.
zcpc-exhaust- — Float Specifies the exhaust air temperature in degrees Celsius (ºC) as
temperature calculated by the system. This is useful in determining potential
hot spots in the data center.
zcpc-humidity (mg) Integer Specifies the amount of water vapor in the air as measured by
the system. The humidity sensor gives a reading of the relative
humidity of the air entering the system. The recommended
long-term relative humidity for a system with an altitude from
sea level to 900 meters (2953 feet) is 60%. The range of
acceptable relative humidity is 8% - 80%.

For more information, see the chapter related to environmental

specifications in the Installation Manual for Physical Planning.
zcpc-dew-point (mg) Float Specifies the air temperature in degrees Celsius (ºC) at which
water vapor will condense into water. This is a calculated value
based on the current temperature and relative humidity. Cooling
the server to the dew point can result in condensation on
critical internal parts, leading to equipment failure, unless the
computer room environment is adequately maintained to
prevent it.

For more information, see the chapter related to environmental

specifications in the Installation Manual for Physical Planning.
zcpc-heat-load (mg) Integer Specifies the amount of heat in Btu/hr. removed from the
system.
zcpc-heat-load- — Integer Specifies the amount of heat in Btu/hr. removed from the
forced-air system by forced-air.
zcpc-heat-load- — Integer Specifies the amount of heat in Btu/hr. removed from the
water system by chilled water. The value is always 0 on an air cooled
system.
zcpc-maximum- — Integer Specifies the maximum potential power consumption of a
potential-power system in watts (W). This value is based on the configuration of
the system and can be used for power and cooling planning.
zcpc-maximum- — Integer Specifies the maximum potential heat load of a system in
potential-heat-load Btu/hr. This value is based on the configuration of the system
and can be used for power and cooling planning.

Chapter 11. Core IBM Z resources 643

 Level 04a

Table 311. CPC object: energy management related additional properties (continued)
Name Qualifier Type Description
last-energy-advice- (pc) Timestamp The timestamp of the most recent change to the energy
time optimization advice for the CPC or null if the timestamp is not
available. A value of -1 indicates that no advice has been
generated for this CPC. This property is only provided when
the associated SE is at version 2.13.1 or later.

List CPC Objects

The List CPC Objects operation returns a list of the zManager Web Services API capable CPCs managed
by an HMC.

HTTP method and URI

GET /api/cpcs

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. If matches are found, the response will be an
array with all objects that match. If no match is found, the response
will be an empty array.

Response body contents

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

Field name Type Description

cpcs Array of Array of nested cpc-info objects (described in the next table). If no matching
cpc-info CPC objects are found, an empty array is returned.
objects

Each nested cpc-info object contains the following fields:

Field name Type Description

object-uri String/URI Canonical URI path of the CPC object
name String The name of the CPC object
status String The current status of the CPC object
Enum
has-unacceptable- Boolean The has-acceptable-status property of the CPC object.
status
dpm-enabled Boolean True if the CPC is enabled for DPM; false otherwise.
se-version String The se-version property of the CPC object.

Description
This operation lists the zManager Web Services API capable CPC objects that are managed by this HMC.
The object URI, object ID and display name are provided for each CPC returned. CPCs that are not
zManager Web Services API capable are not returned.

644 HMC Web Services API

 Level 04a

If the name query parameter is specified, the returned list is limited to those CPC objects that have a
name property matching the specified filter pattern. If the name parameter is omitted, no such filtering is
performed.

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 the
response body contents section.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to any CPC 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 644.

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.
299 A query parameter has an invalid syntax.

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 HTTP/1.1

x-api-session: 2jm2h7j25d1e1g5wbygmfriyjiit8tp4iqiw8h09j8kz68i0k6

Figure 379. List CPC Objects: Request

Chapter 11. Core IBM Z resources 645

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2016 07:18:42 GMT
content-type: application/json;charset=UTF-8
content-length: 725
{
"cpcs": [
{
"dpm-enabled": true,
"has-unacceptable-status": true,
"name": "P0LXSMOZ",
"object-uri": "/api/cpcs/e8753ff5-8ea6-35d9-b047-83c2624ba8da",
"se-version": "2.13.1"
"status": "not-operating"
},
{
"dpm-enabled": true,
"has-unacceptable-status": false,
"name": "R32",
"object-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"se-version": "2.14.0"
"status": "operating"
},
{
"dpm-enabled": false,
"has-unacceptable-status": true,
"name": "ICHABOD",
"object-uri": "/api/cpcs/ac15c987-90c6-3526-854e-4c612939260d",
"se-version": "2.13.1"
"status": "not-operating"
}
]
}

Figure 380. List CPC Objects: Response

List Ensemble CPC Objects

The List Ensemble CPC Objects operation returns a list of the CPCs associated with an ensemble.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/cpcs

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

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. If matches are found, the response will be an
array with all objects that match. If no match is found, the response
will be an empty array.

646 HMC Web Services API

 Level 04a

Response body contents

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

Field name Type Description

cpcs Array of Array of nested cpc-info objects (described in the next table). If no matching
cpc-info CPC objects are found, an empty array is returned.
objects

Each nested cpc-info object contains the following fields:

Field name Type Description

object-uri String/URI Canonical URI path of the CPC object
name String The name of the CPC object
status String The current status of the CPC object
Enum

Description
This operation lists the CPC objects that are associated with the ensemble identified in the request URI.
The object URI, object ID and display name are provided for each CPC returned. In contrast, the List
Ensemble Nodes operation lists objects of any type that are associated with an ensemble.

If the name query parameter is specified, the returned list is limited to those CPC objects that have a
name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
done.

A CPC object is only included in the list if the API user has object-access permission for that CPC object.

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in the
response body contents section.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object designated by {ensemble-id}
v Object-access permission to any CPC 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.”

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 11. Core IBM Z resources 647

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object ID in the URI ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.

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/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334/cpcs HTTP/1.1

x-api-session: 2jm2h7j25d1e1g5wbygmfriyjiit8tp4iqiw8h09j8kz68i0k6

Figure 381. List Ensemble CPC Objects: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 07:18:42 GMT
content-type: application/json;charset=UTF-8
content-length: 214
{
"cpcs": [
{
"name": "R32",
"object-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"status": "operating"
},
{
"name": "ICHABOD",
"object-uri": "/api/cpcs/ac15c987-90c6-3526-854e-4c612939260d",
"status": "not-operating"
}
]
}

Figure 382. List Ensemble CPC Objects: Response

Get CPC Properties

The Get CPC Properties operation retrieves the properties of a single CPC object designated by {cpc-id}.

HTTP method and URI

GET /api/cpcs/{cpc-id}

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Query parameters:

Name Type Rqd/Opt Description

properties List of String Optional Filter string to limit returned properties to those that are
Enum identified here. This is a list of comma-separated strings where
each string is a property name defined in the CPC object's
data model.

648 HMC Web Services API

 Level 04a

Name Type Rqd/Opt Description

cached-acceptable Boolean Optional Indicates whether cached values are acceptable for the
returned properties. Valid values are true and false. The
default is false.

Response body contents

On successful completion, the response body provides the current values of the properties for the CPC
object as defined in “Data model” on page 629.

Description
Some CPC properties are only available if the HMC is communicating with the SE, and are returned as
null objects if the HMC is not communicating with the SE. With the exceptions of object-uri, parent,
class, name, and status, the values of CPC properties are unpredictable unless stated otherwise in the
“Data model” on page 629.

If the properties query parameter is specified, the response body contains only the requested properties.
The presence and value of each requested property is the same as it is when the properties query
parameter is not specified. That is, it may be omitted or contain a special value, such as null, -1, or an
empty string, if a prerequisite condition is not met. If the properties parameter is omitted, no such
filtering is performed.

Some of this object's property values are periodically fetched from the Support Element and cached on
the HMC for quick access by the APIs. Due to the nature of this caching support, the HMC's cached
value of a property may differ from the value on the Support Element at any point in time. While the
HMC strives to keep the cache reasonably current, there are no guarantees about the latency of the cache,
nor is there any latency or other cache information available to the API user. If the cached-acceptable
query parameter is specified as true and a property's value is currently present in the cache, the value
from the cache is returned; otherwise, the current, non-cached value is returned.

On successful execution, HTTP status code 200 (OK) is returned and the response body contains all of the
current properties as defined “Data model” on page 629.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-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, 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 object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.

Chapter 11. Core IBM Z resources 649

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 272 Unable to obtain Server Time Protocol (STP) configuration. Retry the request
later.
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/37c6f8a9-8d5e-3e5d-8466-be79e49dd340 HTTP/1.1

x-api-session: 65aw2jahugn1wop51hsq0c6aldkkx773dz9ulirrvg2z853m4u

Figure 383. Get CPC Properties: Request

650 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
| date: Fri, 10 Aug 2018 16:58:36 GMT
content-type: application/json;charset=UTF-8
| content-length: 9437
{
"acceptable-status": [
"operating"
],
"additional-status": "",
| "available-features-list":[],
"cbu-activation-date": 0,
"cbu-expiration-date": 0,
"cbu-number-of-tests-left": 0,
"class": "cpc",
"cpc-node-descriptor": "00",
"cpc-power-cap-allowed": "allowed",
"cpc-power-cap-current": 90000,
"cpc-power-cap-maximum": 106936,
"cpc-power-cap-minimum": 16019,
"cpc-power-capping-state": "enabled",
"cpc-power-consumption": 8160,
"cpc-power-rating": 46522,
"cpc-power-save-allowed": "allowed",
"cpc-power-saving": "high-performance",
"cpc-serial-number": "000020076D25",
"degraded-status": [
"not-degraded"
],
"description": "Central Processing Complex (CPC)",
"does-wait-state-end-time-slice": null,
"dpm-enabled": false,
"ec-mcl-description": {
"action": [
{
"activation": "current",
"pending": false,
"type": "channel-config"
},
{
"activation": "current",
"pending": false,
"type": "coupling-facility-reactivation"
},
{
"activation": "current",
"pending": false,
"type": "power-on-reset-tracking"
},

Figure 384. Get CPC Properties: Response (Part 1)

Chapter 11. Core IBM Z resources 651

 Level 04a

{
"activation": "current",
"pending": true,
"type": "zhybrid-blades-activation"
},
{
"activation": "next",
"pending": false,
"type": "channel-config"
},
{
"activation": "next",
"pending": false,
"type": "coupling-facility-reactivation"
},
{
"activation": "next",
"pending": false,
"type": "power-on-reset-tracking"
},
{
"activation": "next",
"pending": false,
"type": "zhybrid-blades-activation"
}
],
"ec": [
{
"description": "SE Framework",
"mcl": [
{
"last-update": 1321019308748,
"level": "216",
"type": "retrieved"
},
{
"last-update": 1321019499749,
"level": "216",
"type": "activated"
},
{
"last-update": 1320675688749,
"level": "179",
"type": "accepted"
},
{
"last-update": 943938000748,
"level": "216",
"type": "installable-concurrent"
},

Figure 385. Get CPC Properties: Response (Part 2)

652 HMC Web Services API

 Level 04a

{
"last-update": 943938000749,
"level": "180",
"type": "removable-concurrent"
}
],
"number": "N48168",
"part-number": "45D8918",
"type": "Base EC"
},
{
"description": "IBM x86 Blade Concurrent Components",
"mcl": [
{
"last-update": 1321019296651,
"level": "022",
"type": "retrieved"
},
{
"last-update": 1320675685652,
"level": "009",
"type": "accepted"
},
{
"last-update": 943938000652,
"level": "022",
"type": "installable-concurrent"
},
{
"last-update": 943938000652,
"level": "010",
"type": "removable-concurrent"
}
],
"number": "N48140",
"part-number": "41U8008",
"type": "Other Optional EC"
},
{
"description": "Embedded Operating System T5xx Series",
"mcl": [
{
"last-update": 1321018125779,
"level": "001",
"type": "retrieved"
},
{
"last-update": 1321018167779,
"level": "001",
"type": "activated"
},
{
"last-update": null,
"level": "000",
"type": "accepted"
},

Figure 386. Get CPC Properties: Response (Part 3)

Chapter 11. Core IBM Z resources 653

 Level 04a

{
"last-update": 943938000779,
"level": "001",
"type": "installable-concurrent"
},
{
"last-update": 943938000779,
"level": "001",
"type": "removable-concurrent"
}
],
"number": "N48197",
"part-number": "45D8919",
"type": "Base EC"
}
]
},
"has-automatic-se-switch-enabled": true,
"has-hardware-messages": true,
"has-temporary-capacity-change-allowed": false,
"has-unacceptable-status": false,
"iml-mode": "lpar",
"is-cbu-activated": false,
"is-cbu-enabled": true,
"is-cbu-installed": false,
"is-ensemble-member": true,
"is-locked": false,
"is-on-off-cod-activated": false,
"available-features-list":[
{
"state":true,
"name":"dpm-storage-management",
"description":"The DPM storage management approach in which FCP and FICON storage
resources are defined in Storage Groups, which are attached to Partitions."
}
],
"is-on-off-cod-enabled": true,
"is-on-off-cod-installed": false,
"is-real-cbu-available": false,
"is-service-required": false,
"lan-interface1-address": "f0def14b63af",
"lan-interface1-type": "ethernet",
"lan-interface2-address": "f0def14b63af",
"lan-interface2-type": "ethernet",
"last-used-activation-profile": "DEFAULT ",
"last-used-iocds": "A0",
"machine-model": "M15",
"machine-serial-number": "000020076D25",
"machine-type": "2817",
"management-enablement-level": "automate",
"msu-permanent": 1091,
"msu-permanent-plus-billable": 1091,
"msu-permanent-plus-temporary": 1091,
"name": "R32",
"network1-ipv4-alt-ipaddr": "9.60.15.6",
"network1-ipv4-mask": "255.255.255.0",
"network1-ipv4-pri-ipaddr": "9.60.15.5",
"network1-ipv6-info": [

Figure 387. Get CPC Properties: Response (Part 4)

654 HMC Web Services API

 Level 04a

{
"alt-ip-address": "fdd8:673b:d89b:1:f2de:f1ff:fe52:d359",
"prefix": 64,
"pri-ip-address": "fdd8:673b:d89b:1:f2de:f1ff:fe4b:63af",
"type": "auto"
},
{
"alt-ip-address": "fe80::f2de:f1ff:fe52:d359%eth0",
"prefix": 64,
"pri-ip-address": "fe80::f2de:f1ff:fe4b:63af%eth0",
"type": "link-local"
}
],
"network2-ipv4-alt-ipaddr": "9.60.14.6",
"network2-ipv4-mask": "255.255.255.0",
"network2-ipv4-pri-ipaddr": "9.60.14.5",
"network2-ipv6-info": [
{
"alt-ip-address": "fe80::f2de:f1ff:fe52:d359%eth1",
"prefix": 64,
"pri-ip-address": "fe80::f2de:f1ff:fe4b:63af%eth1",
"type": "link-local"
}
],
"next-activation-profile-name": "TESTCDU",
"object-id": "37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"object-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"on-off-cod-activation-date": 0,
"parent": "/api/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334",
"processor-count-aap": 1, "processor-count-cbp": 1,
"processor-count-defective": 0,
"processor-count-general-purpose": 9,
"processor-count-icf": 2,
"processor-count-ifl": 2,
"processor-count-iip": 1,
"processor-count-pending": 0,
"processor-count-pending-aap": 0, "processor-count-pending-cbp": 0,
"processor-count-pending-general-purpose": 0,
"processor-count-pending-icf": 0,
"processor-count-pending-ifl": 0,
"processor-count-pending-iip": 0,
"processor-count-pending-service-assist": 0,
"processor-count-service-assist": 3,
"processor-count-spare": 0,
"processor-running-time": null,
"processor-running-time-type": "system-determined",
"se-version": "2.11.1",
"software-model-permanent": "709",
"software-model-permanent-plus-billable": "709",
"software-model-permanent-plus-temporary": "709",
"status": "operating", "storage-total-installed": 393216,
"storage-hardware-system-area": 32768,
"storage-customer": 360448,
"storage-customer-central": 4096,
"storage-customer-expanded": 512,
"storage-customer-available": 355840

Figure 388. Get CPC Properties: Response (Part 5)

Chapter 11. Core IBM Z resources 655

 Level 04a

"storage-vfm-increment-size": 16,
"storage-vfm-total": 1024,
"stp-configuration": {
"current-time-server": "preferred",
"etr-id": null,
"stp-id": "12345678"
},
"zcpc-ambient-temperature": 25.399999618530273,
"zcpc-dew-point": 2.4000000953674316,
"zcpc-exhaust-temperature": 34.0,
"zcpc-heat-load": 20293,
"zcpc-heat-load-forced-air": 20293,
"zcpc-heat-load-water": 0,
"zcpc-humidity": 22,
"zcpc-maximum-potential-heat-load": 26571,
"zcpc-maximum-potential-power": 7782,
"zcpc-power-cap-allowed": "under-group-control",
"zcpc-power-cap-current": 23745,
"zcpc-power-cap-maximum": 27400,
"zcpc-power-cap-minimum": 7782,
"zcpc-power-capping-state": "enabled",
"zcpc-power-consumption": 5943,
"zcpc-power-rating": 27400,
"zcpc-power-save-allowed": "under-group-control",
"zcpc-power-saving": "high-performance"
}

Figure 389. Get CPC Properties: Response (Part 6)

Update CPC Properties

The Update CPC Properties operation updates one or more writable properties of the CPC object
designated by {cpc-id}.

HTTP method and URI

POST /api/cpcs/{cpc-id}

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Request body contents

The request body is expected to contain one or more field names representing writable CPC 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 CPC 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.

656 HMC Web Services API

 Level 04a

When this operation changes the value of any property for which property-change notifications are due,
those notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission for the CPC 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, 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.
19 The request body contains a field whose corresponding data model property
is not writable on this HMC and/or SE version.
268 The requested update requires that the processor-running-time-type
property already contain "user-determined" or that the request body also
requests an update of the processor-running-time-type property to
"user-determined".
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
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.

Start CPC
The Start CPC operation starts the CPC object designated by {cpc-id}. The target CPC object must be
enabled for DPM.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/start

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

job-uri String/URI URI that may be queried to retrieve start status updates.

Chapter 11. Core IBM Z resources 657

 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 659. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Description
Start CPC is a process that makes a CPC operational, which means either:
v The CPC is ready to have a control program or operating system loaded, or
v The CPC has loaded and is running a control program or operating system.

Start CPC makes a CPC operational by:

v Using predefined information to set the operational capabilities and characteristics of the CPC
v Checking the current status of the CPC, and then performing only the operations necessary to make it
operational.

So, using Start CPC is not limited to starting the system. Using Start CPC is recommended whenever
you want to make the CPC or its partition objects operational.

A complete start starts the CPC and its partition objects completely in a single step. The result of a
complete start is an operational CPC with partition objects loaded and running operating systems. The
current status of the CPC and its partition objects determines which operations are performed during the
start to make them operational. The start may include:
1. Turning CPC power on.
2. Performing a power-on reset, this includes allocating system resources to the CPC.
3. Then starting partition objects to support multiple images. Starting each partition object includes:
a. Initializing it.
b. Allocating system resources to it.
c. Loading it with a control program or operating system.

Because the status of the CPC and its partition objects determines which operations must be performed
during the start to make them operational, one or more operations listed above may not be performed
during the start. For example:
v Starting the CPC does not perform a power-on reset if the CPC has already been power-on reset and
the desired applicable settings, such as the operating mode and active input/output configuration data
set (IOCDS), are already in effect.
v Starting the CPC does not perform any operations if the CPC is already operational and all desired
settings are already in effect.

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

658 HMC Web Services API

 Level 04a

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.”

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission for the Start 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 657.

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 ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 5 The operation cannot be performed because the CPC object designated by
{cpc-id} is currently not enabled for DPM.
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.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

Job reason
Job status code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed or was rejected due to the current CPC status. The CPC
status is unknown. Refer to the message parameter in the error response
body for details.

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

Chapter 11. Core IBM Z resources 659

 Level 04a

Usage note
This operation starts a CPC that is enabled for DPM only. If the targeted CPC object is not enabled for
DPM, the Activate CPC operation may be used instead. Refer to “Activate CPC” on page 662 for details.

Stop CPC
The Stop CPC operation stops the CPC object designated by {cpc-id}. The target CPC object must be
enabled for DPM.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/stop

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

job-uri String/URI URI that may be queried to retrieve stop 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 661. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Description
Stop CPC is an orderly process for shutting down and turning off the CPC.

Shutting down and turning off the CPC, referred to also as stopping the CPC, includes:
v Ending hardware and software activity
v Clearing, releasing, and de-allocating hardware resources
v Turning off power.

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 seen in “Job status and reason codes” on page 661.

660 HMC Web Services API

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission for the Stop 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 660.

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 ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 5 The operation cannot be performed because the CPC object designated by
{cpc-id} is currently not enabled for DPM.
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.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

Job reason
Job status code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed or was rejected due to the current CPC status. The CPC
status is unknown. Refer to the message parameter in the error response
body for details.

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

Usage note
This operation stops a CPC object that is enabled for DPM only. If the targeted CPC object is not enabled
for DPM, the Deactivate CPC operation may be used instead. Refer to “Deactivate CPC” on page 664 for
details.

Chapter 11. Core IBM Z resources 661

 Level 04a

Activate CPC
The Activate CPC operation activates the CPC object designated by {cpc-id}. This operation is not
permitted when the CPC is enabled for DPM.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/activate

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Request body contents

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

Field name Type Rqd/Opt Description

activation-profile- String Optional The name of the activation profile to be used for the request. If not
name (1-16) provided, the request uses the profile name specified in the
next-activation-profile-name property for the CPC object.
force Boolean Optional Whether this operation is permitted when the CPC is in "operating"
status (true) or not (false). The default is false.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

job-uri String/URI URI that may be queried to retrieve activation 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 664. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Description
Activation is a process that makes a CPC operational, which means either:
v The CPC is ready to have a control program or operating system loaded, or
v The CPC has loaded and is running a control program or operating system.

Activation makes a CPC operational by:

662 HMC Web Services API

 Level 04a

v Using predefined information, referred to as an activation profile, to set the operational capabilities and
characteristics of the CPC
v Checking the current status of the CPC, and then performing only the operations necessary to make it
operational as specified in the activation profile.

So, using activation is not limited to starting the system. Using activation is recommended whenever you
want to make the CPC or its logical partitions operational.

A complete activation activates the CPC and its logical partitions completely in a single step. The result
of a complete activation is an operational CPC with logical partitions loaded and running operating
systems. The current status of the CPC and its logical partitions determines which operations are
performed during activation to make them operational. Activation may include:
1. Turning CPC power on.
2. Performing a power-on reset, this includes allocating system resources to the CPC.
3. Then activating logical partitions to support multiple images. Activating each logical partition
includes:
a. Initializing it.
b. Allocating system resources to it.
c. Loading it with a control program or operating system.

Because the status of the CPC and its logical partitions determines which operations must be performed
during activation to make them operational, one or more operations listed above may not be performed
during activation. For example:
v Activating the CPC does not perform a power-on reset if the CPC has already been power-on reset and
the applicable settings in its assigned activation profile, such as the operating mode and active
input/output configuration data set (IOCDS), are already in effect.
v Activating the CPC does not perform any operations if the CPC is already operational and all settings
in its assigned activation profile are already in effect.

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
664.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission for the Activate 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 662.

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 11. Core IBM Z resources 663

 Level 04a

HTTP error status Reason

code code Description
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 4 The operation cannot be performed because the CPC object designated by
{cpc-id} is currently enabled for DPM, which is not supported in this
operation.
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.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

Job reason
Job status code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed or was rejected due to the current CPC status and use of
the force=false parameter. If rejected due to force=false, the CPC status is
unchanged. If the operation failed, the CPC status is unknown. Refer to the
message parameter in the error response body for details.

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

Usage note
This operation activates a CPC object that is not enabled for DPM. If the targeted CPC object is enabled
for DPM, the Start CPC operation may be used instead. Refer to “Start CPC” on page 657 for details.

Deactivate CPC
The Deactivate CPC operation deactivates the CPC object designated by {cpc-id}. This operation is not
permitted when the CPC is enabled for DPM.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/deactivate

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

664 HMC Web Services API

 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

force Boolean Optional Whether this operation is permitted when the CPC is in "operating"
status (true) or not (false). The default is false.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

job-uri String/URI URI that may be queried to retrieve activation 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 666. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Description
Deactivation is an orderly process for shutting down and turning off the CPC.

Shutting down and turning off the CPC, referred to also as deactivating the CPC, includes:
v Ending hardware and software activity
v Clearing, releasing, and de-allocating hardware resources
v Turning off power.

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 seen in “Job status and reason codes” on page 666.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission for the Deactivate task.

Chapter 11. Core IBM Z resources 665

 Level 04a

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 665.

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 ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 4 The operation cannot be preformed because the CPC object designated by
{cpc-id} is currently enabled for DPM, which is not supported in this
operation.
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.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

Job reason
Job status code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed or was rejected due to the current CPC status and use of
the force=false parameter. If rejected due to force=false, the CPC status is
unchanged. If the operation failed, the CPC status is unknown. Refer to the
message parameter in the error response body for details.

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

Usage note
This operation deactivates a CPC object that is not enabled for DPM. If the targeted CPC object is enabled
for DPM, the Stop CPC operation may be used instead. Refer to “Stop CPC” on page 660 for details.

Import Profiles
The Import Profiles operation imports activation profiles and/or system activity profiles for the CPC
from the SE hard drive into the CPC object designated by {cpc-id}. This operation is not permitted when
the CPC is enabled for DPM.

666 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/import-profiles

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Request body contents

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

Field name Type Rqd/Opt Description

profile-area Integer Required The numbered hard drive area from which the profiles are
(1-4) imported. Use the profile-area value specified on the prior Export
Profiles operation.

Description
The Support Element provides four reusable areas on its hard drive from which the data save by a prior
Export Profiles can be read.

Exporting and importing profiles is necessary only when you intend to have your current system and
Support Element replaced with a new system and Support Element. Support Element (Version 2.12.1 and
newer) information can be found on console help system. For information about earlier versions of the
Support Element, see the Support Element Operations Guide.

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the CIM Actions ExportSettingsData 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, 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 ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 4 This operation cannot be preformed because the CPC designated by the
request URI is enabled for DPM.
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.
500 (Server Error) 279 An unexpected error occurred during the operation.

Chapter 11. Core IBM Z resources 667

 Level 04a

HTTP error status Reason

code code Description
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Export Profiles
The Export Profiles operation exports activation profiles and/or system activity profiles from the CPC
object designated by {cpc-id} to the SE hard drive. This operation is not permitted when the CPC is
enabled for DPM.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/export-profiles

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Request body contents

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

Field name Type Rqd/Opt Description

profile-area Integer Required The numbered hard drive area to which the profiles are exported.
(1-4) Any existing data is overwritten.

Description
The Support Element provides four reusable areas on its hard drive that can be used as temporary save
areas. The choice of save area is up to the caller.

Exporting and importing profiles is necessary only when you intend to have your current system and
Support Element replaced with a new system and Support Element. Support Element (Version 2.12.1 and
newer) information can be found on the console help system. For information about earlier versions of
the Support Element, see the Support Element Operations Guide.

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the CIM Actions ExportSettingsData 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

668 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.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 4 The operation cannot be performed because the CPC designated by the
request URI is enabled for DPM.
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.
500 (Server Error) 279 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Set Auto-Start List

The Set Auto-Start List operation identifies a CPC's partitions that are automatically started when the
CPC is started. It also specifies the order in which they are started. The target CPC object is designated
by {cpc-id} and must be enabled for DPM.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/set-auto-start-list

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Request body contents

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

Field name Type Rqd/Opt Description

auto-start-list Array of Required An array of auto-start-entry objects in sequence, each representing a
objects single partition or a group of partitions that are automatically
started when this CPC is started. The format of that object is
described in the “Class specific additional properties” on page 630.

Description
This operation defines the CPC's partition auto-start list. The auto-start list is an ordered list of partitions
and/or groups of partitions that are automatically started when the CPC is started. See the “Class specific
additional properties” on page 630 for the format of the entries in this list. Each partition or partition
group is started before those that are later than it in the list. The order in which partitions within a
partition group are started is not specified. An empty auto-start list indicates that no partitions are to be
automatically started.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

Chapter 11. Core IBM Z resources 669

 Level 04a

The URI path must designate an existing CPC, and the API user must have object-access permission to it,
otherwise, status code 404 (Not Found) is returned. Each Partition URI in the request body must
designate an existing partition, and the API user must have object-access permission to it, otherwise,
status code 404 (Not found) is returned. If the auto-start list contains duplicate partition group names or
a partition is listed multiple times in the list or an empty partition group is specified, HTTP status code
400 (Bad Request) is returned.

If the CPC object designated by {cpc-id} is not enabled for DPM, HTTP status code 409 (Conflict) is
returned.

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the CPC Details task.
v Object-access permission to all partitions specified in the request body.

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.
Table 312. Set Auto-Start List: 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 Two or more of the partition group names specified in the auto-start-list in
the request body are duplicates.
333 One or more of the partition URIs specified in the auto-start-list in the
request body does not designate a partition object of the CPC object
designated by {cpc-id}.
334 Two or more of the partition URIs specified in the auto-start-list in the
request body are duplicates.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
2 One or more of the partition URIs specified in the auto-start-list in the
request body does not designate an existing partition object, or the API user
does not have object access permission to the object.
409 (Conflict) 5 The operation cannot be performed because the CPC designated by {cpc-id} is
currently not enabled for DPM.
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 communicating
Unavailable) with the SE needed to perform the requested operation.

670 HMC Web Services API

 Level 04a

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/cpcs/e5ae3ab6-ac8d-33bc-9739-eb142d89804d/operations/set-auto-start-
list HTTP/1.1
x-api-session: 2kk848szmu8mo00lkj4c19254fiejeanyv316j0d5d4uppgp8t
content-type: application/json
content-length: 384
{
"auto-start-list":[
{
"partition-uri":"/api/partitions/0589baec-d599-11e5-8959-42f2e9105e9b",
"post-start-delay":15,
"type":"partition"
},
{
"description":"description for group1",
"name":"group1",
"partition-uris":[
"/api/partitions/39daff36-b51e-11e5-9710-42f2e9105e9b",
"/api/partitions/8c6e48a2-ce91-11e5-98b3-42f2e9105e9b"
],
"post-start-delay":0,
"type":"partition-group"
}
]
}

Figure 390. Set Auto-Start List: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Wed, 17 Feb 2016 20:54:12 GMT

<No response body>

Figure 391. Set Auto-Start List: Response

Add Temporary Capacity

The Add Temporary Capacity operation adds temporary processors or increases temporary model
capacity to the CPC object designated by {cpc-id}.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/add-temp-capacity

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Request body contents

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

Field name Type Rqd/Opt Description

record-id String Required Identifies the capacity record to be used for this request
(1-8)

Chapter 11. Core IBM Z resources 671

 Level 04a

Field name Type Rqd/Opt Description

software-model String Optional The target software model. This value must be one of the software
(1-3) models defined within the capacity record. Implicit in this value is
the number of general processors added. If not provided, the
current software model is not changed.
processor-info Array of Optional A nested object that defines the number of specialty processors to be
processor- added. If not provided, the number of specialty processors is not
info changed.
objects
force Boolean Optional Whether the operation proceeds if not enough processors are
available (true) or not (false). The default is false.
test Boolean Required Whether the request should activate real or test resources for the
capacity record. Set true if test or set to false if real. This is mainly
used for Capacity Backup Upgrade (CBU) activations. See the
Capacity on Demand User's Guide, SC28-6943. For most records, field
should be set to false.

processor-info object

Field name Type Rqd/Opt Description

processor-type String Required Identifies the type of specialty processors to be affected. One of:
Enum v "aap" - Application Assist Processor
v "ifl" - Integrated Facility for Linux processor
v "icf" - Internal Coupling Facility processor
v "iip" - z Integrated Information Processors
v "sap" - System Assist Processor
| v "cbp" - Container Based Processor1
num-processor-steps Integer Optional The delta to the current number of processors. If not provided, the
number of processors is not changed.
1
| This property can be included in the request body only when the associated SE version is 2.14.0 with the suitable
| MCL bundle, or a later SE version.

Description
Removal of these temporary resources can be performed manually via the Remove Temporary Capacity
operation or automatically upon expiration of the capacity record.

Refer to the Capacity on Demand User's Guide for details on temporary capacity changes.

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the CIM Actions Activate 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

672 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.
271 A duplicate processor-type entry was found in the processor-info array,
remove the duplicate entry.
275 The test value does not match the value stored in the capacity record.
276 Either the request specifies more resources than available or the requested
software model specifies fewer resources than the current software model.
277 A temporary capacity record is already active. It must be deactivated before
a new capacity record can be activated.
278 The software-model value was not found in the capacity record. Only
software models as defined in the target capacity record can be specified.
298 The operation parameters conflict with the capacity record type:
v force=true is permitted only for CBU, CPE and loaner capacity records.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
274 The requested capacity record does not exist.
409 (Conflict) 1 The operation is unavailable in the current CPC state:
v The SE is not configured to allow temporary capacity changes via an API
v The CPC status property is not "operating" or the CPC iml-mode property
is not "lpar"
v No physical processors are operating
v The CPC is IMLed in a test or debug mode
v An IML is required
2 The operation was rejected by the Support Element (SE), because the SE is
currently performing processing that requires exclusive control of the SE.
Retry the operation at a later time.
297 Some, but not all, of the requested resources were added.
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.
500 (Server Error) 275 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Remove Temporary Capacity

The Remove Temporary Capacity operation removes temporary processors or decreases temporary
model capacity from the CPC object designated by {cpc-id}.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/remove-temp-capacity

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Chapter 11. Core IBM Z resources 673

 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

record-id String Required Identifies the capacity record to be used for this request
(1-8)
software-model String Optional The target software model. This value must be one of the software
(1-3) models defined within the capacity record. Implicit in this value is
the number of general processors removed. If not provided, the
current software model is not changed.
processor-info Array of Optional A nested object that defines the number of specialty processors to be
processor- removed. If not provided, the number of specialty processors is not
info changed. Refer to “Request body contents” on page 671 of the Add
objects Temporary Capacity operation for details.

Description
When you are finished using all or part of a capacity upgrade, you can remove processors or decrease
model capacity using this operation. You can only remove activated resources for the specific offering.
You cannot remove dedicated engines or the last processor of a processor type.

If you remove resources back to the base configuration, the capacity record activation is completed. That
is, if you remove the last temporary processor, your capacity record is deactivated. For a CBU and
On/Off CoD record, to add resources again, you must use another Add Temporary Capacity operation.
For an On/Off CoD test or CPE record, once the record is deactivated, it is no longer available for use.
You can then delete the record.

After removal of the resources, the capacity record remains as an installed record. If you want a record
deleted, you must manually select the record on the Installed Records page and click Delete.

Refer to the Capacity on Demand User's Guide for details on temporary capacity changes.

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the CIM Actions Deactivate 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

674 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.
271 A duplicate processor-type entry was found in the processor-info array,
remove the duplicate entry.
276 Either the request specifies more resources than are currently active or the
requested software model specifies more resources than the current software
model.
278 The software-model value was not found in the capacity record. Only
software models as defined in the target capacity record can be specified.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
274 The requested capacity record does not exist.
409 (Conflict) 1 The operation is unavailable in the current CPC state:
v The SE is not configured to allow temporary capacity changes via an API
v The CPC status property is not "operating" or the CPC iml-mode
property is not "lpar".
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.
500 (Server Error) 275 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Swap Current Time Server

The Swap Current Time Server operation changes the role of the CPC object designated by {cpc-id} to the
Current Time Server (CTS).

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/swap-cts

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Request body contents

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

Field name Type Rqd/Opt Description

stp-id String Required Identifies the STP. Can contain 0-9, a-z, A-Z, underline (_) and dash
(1-8) (-).

Chapter 11. Core IBM Z resources 675

 Level 04a

Description
This operation changes the role of the CPC object designated by {cpc-id} to the Current Time Server (CTS).

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the Manage System Time and Modify Assigned Server Roles tasks.

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.
285 The CPC targeted by this operation is already the Preferred Time Server.
286 The operation was rejected for one of the following reasons:
v The stp-id field value does not match the current CTN identifier
v The operation is not permitted for a mixed CTN.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 1 The requested operation cannot be performed, due to the state of the object:
v Server Time Protocol is not enabled on this CPC
v an ETR reverse migration is in progress
v no alternate is active
v this CPC is not the backup time server
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.
500 (Server Error) 272 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Set STP Configuration

The Set STP Configuration operation updates the configuration for an STP-only Coordinated Timing
Network.

676 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/set-stp-config

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Request body contents

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

Field name Type Rqd/Opt Description

stp-id String Required The current STP identifier for the CTN, used to verify that the CPC
(1-8) is a member of the correct CTN. Can contain 0-9, a-z, A-Z, underline
(_) and dash (-).
new-stp-id String Optional If provided, the new STP identifier for the CTN, Can contain 0-9,
(1-8) a-z, A-Z, underline (_) and dash (-).
force Boolean Required Whether a disruptive operation is allowed (true) or rejected (false)
preferred-time- stp-node Required Identifies the CPC object to be the Preferred Time Server. Refer to
server object Table 249 on page 483 for details.
backup-time-server stp-node Optional Identifies the CPC object to be the Backup Time Server. If not
object provided, the STP has no Backup Time Server. Refer to Table 249 on
page 483 for details.
arbiter stp-node Optional Identifies the CPC object to be the Arbiter for the CTN. If not
object provided, the STP has no Arbiter. Refer to Table 249 on page 483 for
details.
current-time-server String Required Identifies the role of the Current Time Server (CTS). One of:
Enum v "preferred" - the Preferred Time Server is the CTS
v "backup" - the Backup Time Server is the CTS.

Description
The CPC object designated by {cpc-id} must be the system that becomes the Current Time Server (CTS).

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the Manage System Time and Modify Assigned Server Roles tasks.

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.

Chapter 11. Core IBM Z resources 677

 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.
282 The operation was rejected, due to an incomplete preferred, backup or
arbiter nested object specification. Refer to Table 249 on page 483 for details.
284 This operation does not target the Current Time Server CPC.
285 The operation was rejected, due to one of the following configuration errors:
v A backup-time-server object is required when providing an arbiter object
v A backup-time-server object is required when current-time-server is
backup
v The preferred-time-server, backup-time-server and arbiter objects do not
reference different CPCs
286 The operation was rejected for one of the following reasons:
v The stp-id field value does not match the current CTN identifier
v The operation is not permitted for a mixed CTN
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
2 An object URI in one of the stp-node objects in the request body does not
designate an existing CPC object, or the API user does not have object-access
permission to the object.
409 (Conflict) 1 The requested operation cannot be performed, due to the state of the object:
v Server Time Protocol is not enabled on this CPC
v an ETR reverse migration is in progress
v no alternate is active
v the operation is not permitted for a mixed-CTN.
287 The provided configuration can only be set by specifying force=true.
288 No communication path between preferred-time-server and
backup-time-server.
289 No communication path to the arbiter.
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.
500 (Server Error) 272 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Change STP-only Coordinated Timing Network

The Change STP-only Coordinated Timing Network operation, sent to the CPC object designated by
{cpc-id} with the role of Current Time Server (CTS) in an STP-only Coordinated Timing Network (CTN),
changes the STP ID portion of the CTN ID for the entire STP-only CTN.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/change-stponly-ctn

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

678 HMC Web Services API

 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

stp-id String Required The new STP identifier. Can contain 0-9, a-z, A-Z, underline (_) and
(1-8) dash (-).

Description
This operation, sent to the CPC object designated by {cpc-id} with the role of Current Time Server (CTS)
in an STP-only Coordinated Timing Network (CTN), changes the STP ID portion of the CTN ID for the
entire STP-only CTN.

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the Manage System Time and Rename CTN tasks.

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.
284 The CPC targeted by the operation is not the Current Time Server. Retry the
operation using the object-uri for the Current Time Server CPC.
286 The operation is not permitted for a mixed CTN.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 1 The requested operation cannot be performed, due to the state of the object:
v Server Time Protocol is not enabled on this CPC
v an ETR reverse migration is in progress
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.
500 (Server Error) 272 An unexpected error occurred during processing of the Server Time Protocol
operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the SE needed to perform the requested operation.

Chapter 11. Core IBM Z resources 679

 Level 04a

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

Join STP-only Coordinated Timing Network

The Join STP-only Coordinated Timing Network operation allows a CPC object designated by {cpc-id} to
join an STP-only Coordinated Timing Network (CTN).

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/join-stponly-ctn

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Request body contents

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

Field name Type Rqd/Opt Description

stp-id String Required Identifies the STP to be joined. Can contain 0-9, a-z, A-Z, underline
(1-8) (_) and dash (-).

Description
If the CPC object is already participating in a different STP-only CTN and is the Current Time Server
(CTS), the operation is rejected. Otherwise, the CPC object is removed from its current CTN and joins the
specified CTN.

If the CPC object has an ETR ID, the ETR ID is removed.

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the Manage System Time and Add Systems to CTN tasks.

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) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.

680 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 1 The requested operation cannot be performed, due to the state of the object:
v Server Time Protocol is not enabled on this CPC
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.
500 (Server Error) 272 An unexpected error occurred during processing of the Server Time Protocol
operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Leave STP-only Coordinated Timing Network

The Leave STP-only Coordinated Timing Network operation allows a CPC object designated by {cpc-id}
to leave the STP-only Coordinated Timing Network (CTN) in which it currently participates.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/leave-stponly-ctn

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Description
The CPC object cannot be the Current Time Server (CTS) in the CTN in which it is currently
participating.

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission to the Manage System Time and Remove Systems from CTN tasks.

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.
286 The operation is not permitted for a mixed CTN.
403 (Forbidden) 1 The API user does not have the required permission for this operation.

Chapter 11. Core IBM Z resources 681

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 1 The requested operation cannot be performed, due to the state of the object:
v Server Time Protocol is not enabled on this CPC
v this CPC is not a member of a CTN
v this CPC is the Current Time Server.
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.
500 (Server Error) 272 An unexpected error occurred during processing of the Server Time Protocol
operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Get CPC Audit Log

The Get CPC Audit Log operation returns the CPC's audit log, filtered according to the query
parameters, if specified.

HTTP method and URI

GET /api/cpcs/{cpc-id}/operations/get-audit-log

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Query parameters:

Name Type Rqd/Opt Description

begin-time Timestamp Optional A timestamp used to filter log entries. Entries created earlier
than this time are omitted from the results. This is specified as
the number of milliseconds since the epoch and must be
greater than or equal to 0. If not specified, then no such
filtering is performed.
end-time Timestamp Optional A timestamp used to filter log entries. Entries created later
than this time are omitted from the results. This is specified as
the number of milliseconds since the epoch and must be
greater than or equal to 0. If not specified, then no such
filtering is performed.

Response body contents

On successful completion, the response body is a JSON array of JSON objects returned using HTTP
chunked transfer encoding. Each array element is a log-entry-info object containing information about a
single log entry. The array elements are in order of increasing timestamp. See Table 267 on page 499 for
more information.

Description
This operation returns the CPC’s audit log in increasing timestamp order, filtered according to the query
parameters, if specified. Each log entry pertains to a specific event that occurred on or to a managed
682 HMC Web Services API
 Level 04a

object or the CPC itself. If the begin-time query parameter is specified, then any entries earlier than that
time are omitted. If the end-time query parameter is specified, then any entries later than that time are
omitted.

The URI path must designate an existing CPC object, the API user must have object-access permission to
it, and that CPC must be at a release level that supports this operation. If any of these conditions is not
met, status code 404 (Not Found) is returned. In addition, the API user must have action/task permission
to the Audit and Log Management task; otherwise, status code 403 (Forbidden) is returned.

On successful execution, the response body contains an array of filtered log entries. If the audit log is
empty or there are no entries to be returned after filtering, then an empty array is provided. Each log
entry contains the event ID, event name and event message. If there are data items included in the event
message, they are available separately. The order and meaning of the substitution items for each event ID
are documented on console help system in the HMC Introduction topic Audit, Event, and Security Log
Messages.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object specified in the request URI
v Action/task permission to the Audit and Log Management task.

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 682.

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.
Table 313. Get CPC Audit Log: 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 The API user does not have the required permission for this operation.
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.
4 The CPC designated by the request URI does not support this operation.
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.
500 (Server Error) 307 The request timed out while attempting to communicate with the SE or
while attempting to get the log data.
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 11. Core IBM Z resources 683

 Level 04a

Example HTTP interaction

GET /api/cpcs/1946e00f-401b-3aa6-84a3-5e49614743ec/operations/get-audit-log
HTTP/1.1
x-api-session: 1ui4gmb59aunfkk8of69nrpks5mtnq5xjc613rdxjq53iv0e1j

Figure 392. Get CPC Audit Log: Request

200 OK
server: zSeries management console API web server / 2.0
transfer-encoding: chunked
cache-control: no-cache
date: Fri, 03 Oct 2014 00:10:35 GMT
content-type: application/json;charset=ISO-8859-1
[
{
"event-data-items":[],
"event-details":[
{
"event-details-data-items":[],
"event-details-message":"S32 - Disabled"
}
],
"event-id":"1809",
"event-message":"Power Cap settings have changed.",
"event-name":"POWERCAP",
"event-time":1412202863030,
"user-uri":null,
"userid":null
},
{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"HMCCHGM(1.2.3.5)"
},
{
"data-item-number":1,
"data-item-type":"string",
"data-item-value":"S32"
}
],
"event-details":[],
"event-id":"734",
"event-message":"Remote support call generated on S32 is being handled by
call-home server HMCCHGM(1.2.3.5).",
"event-name":"TRSF_OFFER",
"event-time":1412262459470,
"user-uri":null,
"userid":null
}
]

Figure 393. Get CPC Audit Log: Response

Get CPC Security Log

The Get CPC Security Log operation returns the CPC's security log, filtered according to the query
parameters, if specified.

684 HMC Web Services API

 Level 04a

HTTP method and URI

GET /api/cpcs/{cpc-id}/operations/get-security-log

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Query parameters:

Name Type Rqd/Opt Description

begin-time Timestamp Optional A timestamp used to filter log entries. Entries created earlier
than this time are omitted from the results. This is specified as
the number of milliseconds since the epoch and must be
greater than or equal to 0. If not specified, then no such
filtering is performed.
end-time Timestamp Optional A timestamp used to filter log entries. Entries created later
than this time are omitted from the results. This is specified as
the number of milliseconds since the epoch and must be
greater than or equal to 0. If not specified, then no such
filtering is performed.

Response body contents

On successful completion, the response body is a JSON array of JSON objects returned using HTTP
chunked transfer encoding. Each array element is a log-entry-info object containing information about a
single log entry. The array elements are in order of increasing timestamp. See Table 267 on page 499 for
more information.

Description
This operation returns the CPC’s security log in increasing timestamp order, filtered according to the
query parameters, if specified. Each log entry pertains to a specific event that occurred on or to a
managed object or the CPC itself. If the begin-time query parameter is specified, then any entries earlier
than that time are omitted. If the end-time query parameter is specified, then any entries later than that
time are omitted.

The URI path must designate an existing CPC object, the API user must have object-access permission to
it, and that CPC must be at a release level that supports this operation. If either of these conditions is not
met, status code 404 (Not Found) is returned. In addition, the API user must have action/task permission
to the View Security Logs task; otherwise, status code 403 (Forbidden) is returned.

On successful execution, the response body contains an array of filtered log entries. If the security log is
empty or there are no entries to be returned after filtering, then an empty array is provided. Each log
entry contains the event ID, event name and event message. If there are data items included in the event
message, they are available separately. The order and meaning of the substitution items for each event ID
are documented on console help system in the HMC Introduction topic Audit, Event, and Security Log
Messages.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object specified in the request URI
v Action/task permission to the View Security Logs task.

Chapter 11. Core IBM Z resources 685

 Level 04a

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 685.

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.
Table 314. Get CPC Security Log: 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 The API user does not have the required permission for this operation.
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.
4 The CPC designated by the request URI does not support this operation.
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.
500 (Server Error) 307 The request timed out while attempting to communicate with the SE or
while attempting to get the log data.
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

GET /api/cpcs/1946e00f-401b-3aa6-84a3-5e49614743ec/operations/get-security-log
HTTP/1.1
x-api-session: 1ui4gmb59aunfkk8of69nrpks5mtnq5xjc613rdxjq53iv0e1j

Figure 394. Get CPC Security Log: Request

686 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
transfer-encoding: chunked
cache-control: no-cache
date: Fri, 03 Oct 2014 00:10:35 GMT
content-type: application/json;charset=ISO-8859-1
[
{
"event-data-items":[],
"event-details":[],
"event-id":"778",
"event-message":"Mirroring data from the primary Support Element to the
alternate Support Element started.",
"event-name":"ASEMIRRST",
"event-time":1412258403480,
"user-uri":null,
"userid":null
},
{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"Communications to the Alternate SE was not
active."
}
],
"event-details":[],
"event-id":"779",
"event-message":"Mirroring data from the primary Support Element to the
alternate Support Element failed. Communications to the Alternate SE was not
active.",
"event-name":"ASEMIRRNO",
"event-time":1412258414110,
"user-uri":null,
"userid":null
}
]

Figure 395. Get CPC Security Log: Response

List CPC Hardware Messages

The List CPC Hardware Messages operation lists the current set of hardware messages associated with
the CPC.

HTTP method and URI

GET /api/cpcs/{cpc-id}/hardware-messages

In this request, the URI variable {cpc-id} is the object ID of a CPC object for which hardware messages are
to be listed.

Chapter 11. Core IBM Z resources 687

 Level 04a

Response body contents

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

Field name Type Description

hardware-messages Array of Array of nested hardware-message-info objects as defined in the next table.
hardware-
message-
info objects

Each nested hardware-message-info object contains the following fields:

Field name Type Description

element-uri String/URI The canonical URI path of the hardware message. The URI is in the
following form: /api/cpcs/{cpc-id}hardware-messages/{hardware-message-
id}
timestamp Timestamp The date and time the hardware message was created
text String The text of the hardware message.

Description
This operation returns a set of CPC hardware messages in increasing timestamp order, filtered according
to the query parameters, if specified. Each hardware message describes an event or notification that may
require the operator's attention. The list of hardware messages can be limited by specifying explicit
filtering criteria on he request.

If the begin-time query parameter is specified, then any entries earlier than that time are omitted. If the
end-time query parameter is specified, then any entries later than that time are omitted.

If there are no hardware messages associated with the CPC, or if no hardware messages are to be
included in the results due to filtering, an empty array is returned and the operation completes
successfully.

The URI path must designate an existing CPC and the API user must have object-access permission to it;
otherwise, status code 404 (Not Found) is returned. In addition, the API user must have Action/Task
permission to the Hardware Messages task or the Hardware Messages task in view-only mode;
otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}.
v Action/Task permission to the Hardware Messages task or the Hardware Messages task in view-only
mode.

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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

688 HMC Web Services API

 Level 04a

Table 315. List CPC Hardware Messages: HTTP status and reason codes.
HTTP error status
code Reason 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 begin-time value is greater than the end-time value.
403 (Forbidden) 1 The API user does not have Action/Task permission for the Hardware
Messages task or the Hardware Messages task in view-only mode.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
4 The CPC designated by the request URI does not support this operation.
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/1946e00f-401b-3aa6-84a3-5e49614743ec/hardware-messages HTTP/1.1

x-api-session: 35rr3x40qbnou8zwmx8ad80ldp8koes4f2abcl6m1fg5jm4tug

Figure 396. List CPC Hardware Messages: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 06 Oct 2014 17:08:58 GMT
content-type: application/json;charset=UTF-8
content-length: 242
{
"hardware-messages":[
{
"element-uri":"/api/cpcs/1946e00f-401b-3aa6-84a3-5e49614743ec/hardware-messages/
43a2922a-4d6b-11e4-972f-42f2e9ccd169",
"text":"Licensed internal code has detected a problem. [Problem # 49]",
"timestamp":1412608381950
}
]
}

Figure 397. List CPC Hardware Messages: Response

Get CPC Hardware Message Properties

The Get CPC Hardware Message Properties operation retrieves the properties of a single CPC hardware
message.

Chapter 11. Core IBM Z resources 689

 Level 04a

HTTP method and URI

GET /api/cpcs/{cpc-id}/hardware-messages/{hardware-message-id}

URI Variables:

Variable Description
{cpc-id} Object ID of the CPC object.
{hardware-message-id} Element ID of the hardware message to retrieve.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the CPC hardware message object as defined in “Data model” on page 629. 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
This operation retrieves the properties of a single CPC hardware message specified by
{hardware-message-id}.

The URI path must designate an existing CPC, and the API user must have object access permission to it;
otherwise, status code 404 (Not Found) is returned.

The URI path must designate an existing hardware message; otherwise status code 404 (Not Found) is
returned. In addition, the API user must have Action/Task permission to the Hardware Messages task or
the Hardware Messages task in view-only mode; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}.
v Action/Task permission to the Hardware Messages task or the Hardware Messages task in view-only
mode.

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, and the response body is a
standard error response body providing the reason code indicated and associated error message.
Table 316. Get CPC Hardware Message Properties: HTTP status and reason codes.
HTTP error status
code Reason 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 Action/Task permission for the
Hardware Messages task or the Hardware Messages task in
view-only mode.

690 HMC Web Services API

 Level 04a

Table 316. Get CPC Hardware Message Properties: HTTP status and reason codes (continued).
HTTP error status
code Reason code Description
404 (Not Found) 1 The object ID in the URI {cpc-id} does not designate an existing CPC
object, or the API user does not have object-access permission to the
object.
4 The CPC designated by the request URI does not support this
operation.
322 The element ID in the URI {hardware-message-id} does not designate an
existing CPC hardware message.
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/1946e00f-401b-3aa6-84a3-5e49614743ec/hardware-messages/
43a2922a-4d6b-11e4-972f-42f2e9ccd169 HTTP/1.1
x-api-session: 5w3ci8h0ptx0lzjy3gdeiuzolkzksdpfzs77dic5wi0ejzikh3

Figure 398. Get CPC Hardware Message Properties: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 06 Oct 2014 17:10:17 GMT
content-type: application/json;charset=UTF-8
content-length: 355
{
"class":"hardware-message",
"element-id":"43a2922a-4d6b-11e4-972f-42f2e9ccd169",
"element-uri":"/api/cpcs/1946e00f-401b-3aa6-84a3-5e49614743ec/hardware-messages/
43a2922a-4d6b-11e4-972f-42f2e9ccd169",
"parent":"/api/cpcs/1946e00f-401b-3aa6-84a3-5e49614743ec",
"text":"Licensed internal code has detected a problem. [Problem # 49]",
"timestamp":1412608381950
}

Figure 399. Get CPC Hardware Message Properties: Response

Delete CPC Hardware Message

The Delete CPC Hardware Message operation deletes a single CPC hardware message

HTTP method and URI

DELETE /api/cpcs/{cpc-id}/hardware-messages/{hardware-message-id}

URI Variables:

Variable Description
{cpc-id} Object ID of the CPC object.

Chapter 11. Core IBM Z resources 691

 Level 04a

Variable Description
{hardware-message-id} Element ID of the hardware message to delete.

Description
This operation deletes a specific CPC hardware message. The hardware message to be deleted is
identified by the {hardware-message-id} variable in the URI.

The URI path must designate an existing CPC and the API user must have object-access permission to it;
otherwise status code 404 (Not Found) is returned.

The URI path must designate an existing hardware message; otherwise, status code 404 (Not Found) is
returned. In addition, the API user must have Action/Task permission to the Hardware Messages task;
otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}.
v Action/Task permission to the Hardware Messages task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned with no response body 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.
Table 317. Delete CPC Hardware Message: HTTP status and reason codes.
HTTP error status
code Reason 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 Action/Task permission for the
Hardware Messages task.
404 (Not Found) 1 The object ID in the URI {cpc-id} does not designate an existing CPC
object, or the API user does not have Object-access permission to the
object.
4 The CPC designated by the request URI does not support this
operation.
322 The element ID in the URI {hardware-message-id} does not designate an
existing CPC hardware message.
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.

692 HMC Web Services API

 Level 04a

Example HTTP interaction

DELETE /api/cpcs/0fdde999-5957-3129-99aa-b6f4bfbbc071/hardware-messages/
d5591a80-43f8-11e4-ac52-42f2e910664b HTTP/1.1
x-api-session: c8un3odpy8yyp150o3poz1ud4gwyfodlwyq495327bpyn2p0z

Figure 400. Delete CPC Hardware Message: Request

204 No Content
date: Mon, 09 Feb 2015 20:07:31 GMT
server: zSeries management console API web server / 2.0

<No response body>

Figure 401. Delete CPC Hardware Message: Response

Export WWPN List

The Export WWPN List operation exports the world wide port names (WWPNs) of the HBAs of the
specified partitions.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/export-port-names-list

In this request, the URI variable {cpc-id} is the object ID of the CPC that contains all the specified
partitions.

Request body contents

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

Field name Type Rqd/Opt Description

partitions Array of Required Array of canonical URI paths, one for each partition whose list of
String/ WWPNs is to be exported.
URI

Response body contents

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

Field name Type Description

wwpn-list String The comma separated list contains the WWPNs along with each associated
partition name, adapter-id, and device-number.

Description
The Export WWPN List operation returns the list of host port WWPNs of the partitions specified by the
partitions field of the request body. These partitions must be part of the CPC specified by {cpc-id}. The list
is provided in a JSON object as a single string in Comma-Separated Values (CSV) format. Each line in the
string will be represented as: Partition name,Adapter ID,device-number,WWPN.

On successful execution, the WWPN list for all the HBAs defined in the specified partitions are provided
in the response body, and HTTP status code 200 (OK) is returned.

Chapter 11. Core IBM Z resources 693

 Level 04a

The request URI path must designate an existing CPC 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. If the
array of partition URIs is empty, status code 400 (Bad Request) is returned. The URIs in the request body
must designate existing Partition objects and API user must have object-access permission to them;
otherwise, status code 404 (Not Found) is returned. The partitions must be part of the specified CPC;
otherwise, status code 400 (Bad Request) is returned. In addition, the API user must have action access
permission to the Export WWPNs task; otherwise, status code 403 (Forbidden) is returned.

The request body is validated against the schema described in “Request body contents” on page 693. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

| If the CPC has the "dpm-storage-management" feature enabled, 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object specified in the request URI.
v Object-access permission to the partition objects specified in the request body.
v Action/task permission to the Export WWPNs task.

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 693

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.
Table 318. Export WWPN List: HTTP status and reason codes
HTTP error status Reason
code code Description
400 (Bad Request) Various Errors were detected during common request validation.
149 The partitions array is empty.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
2 The object ID {partition-id} does not designate an existing Partition object, or
the API user does not have object-access permission to it.
| 409 (Conflict) 12 The operation is not supported when the "dpm-storage-management"
| feature is enabled on the CPC.
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.

694 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/cpcs/51342eec-1ba0-3866-b639-a99860807b89/operations/export-port-names-
list HTTP/1.1
x-api-session: 3ud8oxm0p8d8um2r3y2pjhbws8ishkf4r4vqqocrsrb1e0h0y2
content-type: application/json
content-length: 72
{
"partitions":[
"/api/partitions/4e12c87e-c8b2-11e5-97e4-020000000192"
]
}

Figure 402. Export WWPN List: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 01 Feb 2016 09:59:04 GMT
content-type: application/json;charset=UTF-8
content-length: 312
{
"wwpn-list":"#Version: 1\r\n#Partition Name,AdapterPortId,DeviceNumber,WWPN\r
\nMyPartition_1,159,1007,0000000000000009\r\nMyPartition_1,158,1002,
0000000000000006\r\nMyPartition_1,159,1001,0000000000000005\r\nMyPartition_
1,158,1003,0000000000000007\r\nMyPartition_1,159,1005,000000000000000A\r\n"
}

Figure 403. Export WWPN List: Response

| Import DPM Configuration

| The Import DPM Configuration operation imports DPM objects such as partitions, NICs, HBAs, virtual
| functions, and their properties. It also restores DPM-specific CPC properties, like the description,
| auto-start partition list and capacity groups.

| HTTP method and URI

| POST /api/cpcs/{cpc-id}/operations/import-dpm-config

| In this request, the URI variable {cpc-id} is the object ID of the CPC.

| Request body contents

| The request body is expected to contain a JSON object with the following fields:
|| Field name Type Rqd/Opt Description
| cpc-properties cpc-info Optional An object containing the names of CPC properties and the values to
| object which each of those properties is to be set. This is a very limited set
| of CPC properties relevant to CPCs enabled for DPM mode.
| se-version String Required The internal code release level of the primary SE on the machine
| (1-8) from which the configuration was exported.
| available-features- Array of Required The list of optional features or behaviors supported by the CPC on
| list cpc- the machine from which the configuration was exported. If the CPC
| feature- has no optional features, then the array must be empty.
| info
| objects

Chapter 11. Core IBM Z resources 695

 Level 04a

| Field name Type Rqd/Opt Description

| adapter-mapping Array of Optional Array of adapter mapping information objects. Required when the
| adapter- I/O adapter configuration on this machine differs from that of the
| mapping- machine from which the configuration was exported.
| info
| objects
| partitions Array of Required Array of objects containing the properties of the Partitions to be
| objects imported. Each element of this array is expected to be the
| equivalent of a response body from a Get Partition Properties
| operation issued when the configuration information was exported.
| nics Array of Optional Array of objects containing the properties of the NICs to be
| objects imported. Each element of this array is expected to be the
| equivalent of a response body from a Get NIC Properties operation
| issued when the configuration information was exported.
| hbas Array of Optional Array of objects containing the properties of the HBAs to be
| objects imported. Each element of this array is expected to be the
| equivalent of a response body from a Get HBA Properties operation
| issued when the configuration information was exported.
| virtual-functions Array of Optional Array of objects containing the properties of the Virtual Functions to
| objects be imported. Each element of this array is expected to be the
| equivalent of a response body from a Get Virtual Function
| Properties operation issued when the configuration information was
| exported.
| adapters Array of Required Array of objects containing the properties of the Adapters in the
| objects exported configuration. Each element of this array is expected to be
| the equivalent of a response body from a Get Adapter Properties
| operation issued when the configuration information was exported.
| This will not recreate any Adapters; it is used for internal purposes
| only.
| virtual-switches Array of Optional Array of objects containing the properties of the Virtual Switches in
| objects the exported configuration. Each element of this array is expected to
| be the equivalent of a response body from a Get Virtual Switch
| Properties operation issued when the configuration information was
| exported. This will not recreate any Virtual Switches; it is used for
| internal purposes only.
| capacity-groups Array of Optional Array of objects containing the properties of the Capacity Groups to
| objects be imported. Each element of this array is expected to be the
| equivalent of a response body from a Get Capacity Group
| Properties operation issued when the configuration information was
| exported.
|

| The cpc-info nested object contains the following fields:

| Table 319. cpc-info nested object
| Name Type Description
| description String The descriptive text associated with this CPC object
| (1-1024)
| auto-start-list Array of An array of auto-start-entry objects in sequence, each representing a single
| auto-start- partition or a group of partitions that are automatically started when this
| entry objects CPC is started. The format of that object is described in the “Class specific
| additional properties” on page 630.
|

| The adapter-mapping-info nested object contains the following fields:

696 HMC Web Services API

 Level 04a

| Table 320. adapter-mapping-info nested object

| Name Type Description
| new-adapter-id String (3) The hexadecimal value of the adapter ID (PCHID) on this machine
| old-adapter-id String (3) The hexadecimal value of the adapter ID (PCHID) on the old machine
|

| Description

| This operation restores a full DPM configuration with all its artifacts like partitions, HBAs, NICs,
| Accelerators, and Crypto devices. Unique identifiers like Object IDs and WWPNs are preserved. This task
| is mainly for migrating a DPM configuration from a z13 to a z14 machine. The operation will attempt to
| restore all provided objects, and stop on the first error. The request body may contain the same set of
| properties as generated by the Get Inventory operation.

| Authorization requirements

| This operation has the following authorization requirements:

| v Object-access permission to the CPC object designated by {cpc-id}
| v Action/task permission to the Import Dynamic Partition Manager Configuration 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, 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.
| 7 A hipersocket adapter failed to recreate. An adapter with the same name, but
| different adapter-id already exists.

| The provided adapter mapping contained invalid adapter-id values.

| 100 The provided se-version is not supported for the import operation of this
| CPC
| 403 (Forbidden) 1 The API user does not have the required permission for this operation.
| 404 (Not Found) 1 The object ID in the URI {cpc-id} does not designate an existing CPC object,
| or the API user does not have object access permission to it.
| 4 The SE associated with the CPC designated by the request URI is not on the
| required code level to support this operation.
| 409 (Conflict) 1 The state of the CPC is not valid to perform the operation (must be in one of
| the following states: "active", "service-required", "degraded", or "exceptions"
| 5 The operation cannot be performed because the CPC designated by the URI
| is not in DPM mode.
| 8 An object with the same URI as one in the request body already exists.
| 503 (Service 1 The request could not be processed because the HMC is not communicating
| Unavailable) with the SE needed to perform the requested operation.
|

Chapter 11. Core IBM Z resources 697

 Level 04a

| 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/cpcs/46a42974-59b1-3574-bade-0d2cc3e2f12c/operations/import-dpm-config HTTP/1.1

x-api-session: 1bj062lh2pj8kjinq9sntoytdimuli2edkwwom7vpw0cntdh8j
content-type: application/json
content-length: 5791
{
"adapter-mapping":[
{
"new-adapter-id":"1dd",
"old-adapter-id":"100"
}
],
"adapters":[
{
"adapter-family":"hipersockets",
"adapter-id":"7c0",
"allowed-capacity":12288,
"channel-path-id":"09",
"class":"adapter",
"configured-capacity":81,
"description":"",
"detected-card-type":"hipersockets",
"maximum-total-capacity":12288,
"maximum-transmission-unit-size":8,
"name":"hipersocket",
"network-port-uris":[
"/api/adapters/bc5c79e6-354f-11e7-911e-00106f0d81cb/network-ports/0"
],
"object-id":"bc5c79e6-354f-11e7-911e-00106f0d81cb",
"object-uri":"/api/adapters/bc5c79e6-354f-11e7-911e-00106f0d81cb",
"parent":"/api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e",
"physical-channel-status":"operating",
"port-count":1,
"state":"online",
"status":"active",
"type":"hipersockets",
"used-capacity":27
},

Figure 404. Import DPM Configuration: Request (Part 1)

698 HMC Web Services API

 Level 04a

{
"adapter-family":"ficon",
"adapter-id":"100",
"allowed-capacity":64,
"card-location":"Z22B-D101-J.01",
"channel-path-id":"0d",
"class":"adapter",
"configured-capacity":10,
"description":"",
"detected-card-type":"ficon-express-16s-plus",
"maximum-total-capacity":254,
"name":"FCP 0100 Z22B-01",
"object-id":"a44e2648-0a42-11e7-88d2-00106f0d81cb",
"object-uri":"/api/adapters/a44e2648-0a42-11e7-88d2-00106f0d81cb",
"parent":"/api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e",
"physical-channel-status":"operating",
"port-count":1,
"state":"online",
"status":"active",
"storage-port-uris":[
"/api/adapters/a44e2648-0a42-11e7-88d2-00106f0d81cb/storage-ports/0"
],
"type":"fcp",
"used-capacity":6
}
],
"available-features-list":[],
"cpc-properties":{
"description":"CPC description "
},
"hbas":[
{
"adapter-port-uri":"/api/adapters/a44e2648-0a42-11e7-88d2-00106f0d81cb/
storage-ports/0",
"class":"hba",
"description":"Systemplatte",
"device-number":"0150",
"element-id":"633219d0-5ff6-11e7-92e8-00106f0d81cb",
"element-uri":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/hbas/
633219d0-5ff6-11e7-92e8-00106f0d81cb",
"name":"Bootadapter",
"parent":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb",
"wwpn":"C05076FFE80006A6"
}
],

Figure 405. Import DPM Configuration: Request (Part 2)

Chapter 11. Core IBM Z resources 699

 Level 04a

"nics":[
{
"class":"nic",
"description":"Device fuer die freie Welt.",
"device-number":"0001",
"element-id":"5d0caee6-5ff4-11e7-90cf-00106f0d81cb",
"element-uri":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/nics/
5d0caee6-5ff4-11e7-90cf-00106f0d81cb",
"mac-address":"02:ff:e8:00:2f:31",
"name":"Netzwerk_Aussen",
"parent":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb",
"ssc-ip-address":null,
"ssc-ip-address-type":null,
"ssc-management-nic":false,
"ssc-mask-prefix":null,
"type":"iqd",
"virtual-switch-uri":"/api/virtual-switches/bc6d7ce6-354f-11e7-a1a3-
00106f0d81cb",
"vlan-id":null,
"vlan-type":null
}
],
"partitions":[
{
"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,
"boot-configuration-selector":0,
"boot-device":"test-operating-system",
"boot-ftp-host":null,
"boot-ftp-insfile":null,
"boot-ftp-username":null,

Figure 406. Import DPM Configuration: Request (Part 3)

700 HMC Web Services API

 Level 04a

"boot-iso-image-name":null,
"boot-iso-ins-file":null,
"boot-logical-unit-number":"0001000000000000",
"boot-network-device":null,
"boot-os-specific-parameters":"",
"boot-record-lba":"",
"boot-removable-media":null,
"boot-removable-media-type":null,
"boot-storage-device":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/
hbas/633219d0-5ff6-11e7-92e8-00106f0d81cb",
"boot-timeout":60,
"boot-world-wide-port-name":"50050763070306A6",
"class":"partition",
"cp-absolute-processor-capping":false,
"cp-absolute-processor-capping-value":1.0,
"cp-processing-weight-capped":false,
"cp-processors":6,
"crypto-configuration":null,
"current-cp-processing-weight":1,
"current-ifl-processing-weight":1,
"degraded-adapters":[],
"description":"Ihno legt eine LPAR an.",
"has-unacceptable-status":true,
"hba-uris":[
"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/hbas/633219d0-
5ff6-11e7-92e8-00106f0d81cb"
],

Figure 407. Import DPM Configuration: Request (Part 4)

Chapter 11. Core IBM Z resources 701

 Level 04a

"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":12288,
"is-locked":false,
"maximum-cp-processing-weight":999,
"maximum-ifl-processing-weight":999,
"maximum-memory":12288,
"minimum-cp-processing-weight":1,
"minimum-ifl-processing-weight":1,
"name":"SUSE_Test",
"nic-uris":[
"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb/nics/5d0caee6-
5ff4-11e7-90cf-00106f0d81cb"
],
"object-id":"9d1826c4-5ff3-11e7-b4a6-00106f0d81cb",
"object-uri":"/api/partitions/9d1826c4-5ff3-11e7-b4a6-00106f0d81cb",
"os-name":"",
"os-type":"",
"os-version":"",
"parent":"/api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e",
"partition-id":null,
"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":"SUSETEST",
"status":"stopped",
"threads-per-processor":0,
"type":"linux",
"virtual-function-uris":[]
}
],
"se-version":"2.13.1",
"virtual-switches":[
{
"backing-adapter-uri":"/api/adapters/bc5c79e6-354f-11e7-911e-00106f0d81cb",
"class":"virtual-switch",
"description":"",
"name":"7C0.P0.IQD",
"object-id":"bc6d7ce6-354f-11e7-a1a3-00106f0d81cb",
"object-uri":"/api/virtual-switches/bc6d7ce6-354f-11e7-a1a3-00106f0d81cb",
"parent":"/api/cpcs/f8242e42-c99d-3765-892e-5ddebb74bd2e",
"port":0,
"type":"hipersockets"
}
]
}

Figure 408. Import DPM Configuration: Request (Part 5)

702 HMC Web Services API

 Level 04a

204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 11 Jun 2018 10:36:04 GMT

<No response body>

Figure 409. Import DPM Configuration: Response

| Usage notes
| v There is a sample script (exportDpmResourcesToFile.py) to assist in creating the request body for this
| operation. It is available at http://www.ibm.com/servers/resourcelink. Select Services, then select
| IBM Z APIs, and select Web Services export DPM configuration script. This script is intended to be
| run against the z13 system whose DPM configuration is to be imported to a z14 system with this
| operation.
| v By default, only the SERVICE user ID on the HMC has the required task permission for this operation,
| and that user ID is not enabled for Web Services APIs by default.

| Inventory service data

Information about CPCs can be optionally included in the inventory data provided by the Inventory
Service.

Inventory entries for the CPC objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "cpc" are to be included. An entry for a particular CPC is included only if
the API user has access permission to that object as described in the Get CPC Properties operation.

For each CPC object to be included, the inventory response array includes an entry that is a JSON object
with the same contents as is specified in the response body contents section for “Get CPC Properties” on
page 648. That is, the data provided is the same as would be provided if a Get CPC Properties operation
were requested targeting this object.

Logical Partition object

The Processor Resource/Systems Manager (PR/SM) is a feature of IBM mainframes that enables logical
partitioning of the CEC. A logical partition (LPAR) is a virtual machine at the hardware level. Each LPAR
operates as an independent server running its own operating environment. Each LPAR runs its own
operating system, which can be any mainframe operating system.

Objects of this class are not provided when the CPC is enabled for DPM.

Data model
For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

This object includes the properties defined in “Base managed object properties schema” on page 60, with
the following class-specific specialization:

Chapter 11. Core IBM Z resources 703

 Level 04a

Table 321. Logical Partition object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/ The canonical URI path of the Logical Partition object, of the form
URI /api/logical-partitions/{logical-partition-id} where
{logical-partition-id} is the value of the object-id property of the Logical
Partition object.
parent — String/ The canonical URI path of the associated CPC object.
URI
class — String The class of a Logical Partition object is "logical-partition".
name (ro) String (1-8) The name of the logical partition
description (ro) String The descriptive text associated with this object.
(0-1024)
status (sc) String One of the following values:
Enum v "operating" - the logical partition has a active control program
v "not-operating" - the logical partition's CPC is non operational
v "not-activated" - the logical partition does not have an active
control program
v "exceptions" - the logical partition's CPC has one or more unusual
conditions
acceptable-status (w)(pc) Array of An array of one or more status strings that determine an acceptable
String status for a logical partition. When a logical partition's status property
Enum contains one of the specified acceptable-status values, the
has-unacceptable-status property contains false.

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties. Refer to the Processor Resource/Systems Manager Planning Guide for more detailed
explanations of the various properties.

There are additional notes throughout the table. Please refer to the note list at the end of the table.
Table 322. Logical Partition object: class specific additional properties
Name Qualifier Type Description
1
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, an empty string is returned.
os-type1 (pc) String (0-8) A human readable form of the operating system provided
value for the type of the operating system active in this
logical partition. If not provided, an empty string is returned.
os-level1 (pc) String (0-32) A human readable form of the operating system provided
value for the level of the operating system active in this
logical partition. If not provided, an empty string is returned.
sysplex-name1 (pc) String (1-8) Applicable only for z/OS® or when os-type is "CFCC", the
name of the sysplex of which this logical partition is a
member, or an empty string if the logical partition is not a
member of a sysplex. For a logical partition that is not z/OS
and os-type is not "CFCC", a null object is returned.
has-operating-system- — Boolean If true, object has operating system messages. If false, object
messages1 does not have operating system messages.

704 HMC Web Services API

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
activation-mode (pc) String Enum One of the following values:
v "general" - the logical partition is in general mode
v "esa390" - the logical partition is in ESA/390 mode
v "esa390tpf" - the logical partition is in ESA/390 TPF mode
v "coupling-facility" - the logical partition is running as a
coupling facility
v "linux" - the logical partition is in Linux mode
v "zvm" - the logical partition is in z/VM mode
v "zaware" - the logical partition is in IBM zAware mode
v "ssc" - the logical partition is in IBM Secure Service
Container mode
v "not-set" - the logical partition is not activated.
next-activation-profile- (w)(pc) String (1-16) Image activation profile name or load activation profile name
name to be used on the next activate.
last-used-activation- (pc) String (0-16) The last used activation profile name or an empty string.
profile
last-used-load-address1 — String (5) The load address most recently used by the logical partition
or null if the value is not available. The load address is a
hexadecimal string of the form cdddd where c is the channel
subsystem ID and dddd is the device address of the I/O
device that was loaded. If the logical partition has not been
loaded, or was loaded from device 0 of channel subsystem 0,
a value of "00000" is returned.
last-used-load- — String (0-8) The load parameter most recently used by the logical
parameter1 partition or null if the value is not available. If the logical
partition has not been loaded, an empty string is returned.
initial-processing- (w) Integer The relative amount of shared general purpose processor
| weight1, 2, 3, 9 (1-999) resources allocated to the logical partition.
initial-processing- (w) Boolean Whether the initial processing weight for general purpose
weight-capped1, 2, 3, 4 processors is a limit or a target.
True
Indicates that the initial general purpose processor
processing weight for the logical partition is capped. It
represents the logical partition's maximum share of
general purpose processor resources.
False
Indicates that the initial general purpose processor
processing weight for the logical partition is not capped.
It represents the share of general purpose processor
resources guaranteed to a logical partition when all
general purpose processor resources are in use.
Otherwise, when excess general purpose processor
resources are available, the logical partition can use them
if necessary.

Chapter 11. Core IBM Z resources 705

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
minimum-processing- (w) Integer The minimum relative amount of shared general purpose
| weight1, 2, 3, 9 processor resources allocated to the logical partition.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared
general purpose processor resources allocated to the
logical partition.

Update:
0 There is no minimum value for the processing weight.
1-999
Define the minimum relative amount of shared general
purpose processor resources allocated to the logical
partition. The value must be less than or equal to the
initial-processing-weight property.
maximum-processing- (w) Integer The maximum relative amount of shared general purpose
| weight1, 2, 3, 9 processor resources allocated to the logical partition.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared
general purpose processor resources allocated to the
logical partition.

Update:
0 There is no maximum value for the processing weight.
1-999
Defines the maximum relative amount of shared general
purpose processor resources allocated to the logical
partition. The value must be greater than or equal to the
initial-processing-weight property.
current-processing- — Integer The relative amount of shared general purpose processor
weight1, 3 (1-999) resources currently allocated to the logical partition.
current-processing- — Boolean Whether the current general purpose processing weight is a
weight-capped1, 2, 3 limit or a target.
True
Indicates that the current general purpose processing
weight for the logical partition is capped. It represents
the logical partition's maximum share of resources,
regardless of the availability of excess processor
resources.
False
Indicates that the current general purpose processing
weight for the logical partition is not capped. It
represents the share of resources guaranteed to a logical
partition when all processor resources are in use.
Otherwise, when excess processor resources are available,
the logical partition can use them if necessary.

706 HMC Web Services API

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
workload-manager- (w) Boolean Whether or not z/OS Workload Manager is allowed to
| enabled1, 5, 9 change processing weight related properties.
True
Indicates that z/OS Workload Manager is allowed to
change processing weight related properties for this
logical partition.
False
Indicates that z/OS Workload Manager is not allowed to
change processing weight related properties for this
logical partition.
absolute-processing- (w) absolute- The amount of absolute capping applied to the general
capping capping purpose processor.
object Note: Absolute capping does not apply to image profiles
where the processors are dedicated to the partition. Absolute
capping only applies to partitions using shared processors.
defined-capacity1 (w) Integer The defined capacity expressed in terms of Millions of Service
Units (MSU)s per hour. MSU is a measure of processor
resource consumption. The amount of MSUs a logical
partition consumes is dependent on the model, the number of
logical processors available to the partition, and the amount
of time the logical partition is dispatched. The defined
capacity value specifies how much capacity the logical
partition is to be managed to by z/OS Workload Manager for
the purpose of software pricing.
0 No defined capacity is specified for this logical partition.
1-nnnn
Represents the amount of defined capacity specified for
this logical partition.
cluster-name1 (pc) String (0-8) LPAR cluster name, which identifies membership in a group
of logical partitions that are members of the same z/OS
Parallel Sysplex®.
partition-number1 (pc) String (2) The partition number for the logical partition, in hexadecimal.
1
partition-identifier (pc) String (2) The partition identifier for the logical partition, in
hexadecimal.
initial-aap-processing- (w) Integer The relative amount of shared Application Assist Processor
| weight1, 2, 3, 9 (1-999) (zAAP) processor resources allocated to the logical partition.

Chapter 11. Core IBM Z resources 707

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
initial-aap-processing- (w) Boolean Whether the initial processing weight for Application Assist
| weight-capped1, 2, 3, 4 Processor (zAAP) processors is a limit or a target.
True
Indicates that the initial Application Assist Processor
(zAAP) processor processing weight for the logical
partition is capped. It represents the logical partition's
maximum share of Application Assist Processor (zAAP)
processor resources, regardless of the availability of
excess Application Assist Processor (zAAP) processor
resources.
False
Indicates that the initial Application Assist Processor
(zAAP) processor processing weight for the logical
partition is not capped. It represents the share of
Application Assist Processor (zAAP) processor resources
guaranteed to a logical partition when all Application
Assist Processor (zAAP) processor resources are in use.
Otherwise, when excess Application Assist Processor
(zAAP) processor resources are available, the logical
partition can use them if necessary.
minimum-aap- (w) Integer The minimum relative amount of shared Application Assist
| processing-weight1, 2, 3, 9 Processor (zAAP) processor resources allocated to the logical
partition.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared
Application Assist Processor (zAAP) processor resources
allocated to the logical partition.

Update:
0 No minimum value for the processing weight.
1-999
Define the minimum relative amount of shared
Application Assist Processor (zAAP) processor resources
allocated to the logical partition.

708 HMC Web Services API

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
maximum-aap- (w) Integer The maximum relative amount of shared Application Assist
| processing-weight1, 2, 3, 9 Processor (zAAP) processor resources allocated to the logical
partition.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared
Application Assist Processor (zAAP) processor resources
initially allocated to the logical partition.

Update:
0 There is no maximum value for the processing weight.
1-999
Define the maximum relative amount of shared
Application Assist Processor (zAAP) processor resources
allocated to the logical partition.
current-aap-processing- — Integer The current relative amount of shared Application Assist
weight1, 3 (1-999) Processor (zAAP) processor resources allocated to the logical
partition.
current-aap-processing- — Boolean Whether the current Application Assist Processor (zAAP)
| weight-capped1, 3 processing weight is a limit or a target.
True
Indicates that the current Application Assist Processor
(zAAP) processing weight for the logical partition is
capped. It represents the logical partition's maximum
share of resources, regardless of the availability of excess
processor resources.
False
Indicates that the current Application Assist Processor
(zAAP) processing weight for the logical partition is not
capped. It represents the share of resources guaranteed to
a logical partition when all processor resources are in
use. Otherwise, when excess processor resources are
available, the logical partition can use them if necessary.
absolute-aap-capping (w) absolute- The amount of absolute capping applied to the Application
capping Assist Processor (zAAP).
object Note: Absolute capping does not apply to image profiles
where the processors are dedicated to the partition. Absolute
capping only applies to partitions using shared processors.
initial-ifl-processing- (w) Integer The relative amount of shared Integrated Facility for Linux
| weight1, 2, 3, 9 (1-999) (IFL) processor resources allocated to the logical partition.

Chapter 11. Core IBM Z resources 709

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
initial-ifl-processing- (w) Boolean Whether the initial processing weight for Integrated Facility
| weight-capped1, 2, 3, 4 for Linux (IFL) processors is a limit or a target.
True
Indicates that the initial Integrated Facility for Linux
(IFL) processor processing weight for the logical partition
is capped. It represents the logical partition's maximum
share of Integrated Facility for Linux (IFL) processor
resources, regardless of the availability of excess
Integrated Facility for Linux (IFL) processor resources
False
Indicates that the initial Integrated Facility for Linux
(IFL) processor processing weight for the logical partition
is not capped. It represents the share of Integrated
Facility for Linux (IFL) processor resources guaranteed to
a logical partition when all Integrated Facility for Linux
(IFL) processor resources are in use. Otherwise, when
excess Integrated Facility for Linux (IFL) processor
resources are available, the logical partition can use them
if necessary.
minimum-ifl- (w) Integer The minimum relative amount of shared Integrated Facility
| processing-weight1, 2, 3, 9 for Linux (IFL) processor resources allocated to the logical
partition.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared
Integrated Facility for Linux (IFL) processor resources
allocated to the logical partition.

Update:
0 There is no minimum value for the processing weight.
1-999
Define the minimum relative amount of shared
Integrated Facility for Linux (IFL) processor resources
allocated to the logical partition.

710 HMC Web Services API

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
maximum-ifl- (w) Integer The maximum relative amount of shared Integrated Facility
| processing-weight1, 2, 3, 9 for Linux (IFL) processor resources allocated to the logical
partition.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared
Integrated Facility for Linux (IFL) processor resources
initially allocated to the logical partition.

Update:
0 There is no maximum value for the processing weight.
1-999
Define the maximum relative amount of shared
Integrated Facility for Linux (IFL) processor resources
allocated to the logical partition.
current-ifl-processing- — Integer The current relative amount of shared Integrated Facility for
weight1, 3 (1-999) Linux (IFL) processor resources allocated to the logical
partition.
current-ifl-processing- — Boolean Whether the current Integrated Facility for Linux (IFL)
| weight-capped1, 3 processing weight is a limit or a target.
True
Indicates that the current Integrated Facility for Linux
(IFL) processing weight for the logical partition is
capped. It represents the logical partition's maximum
share of resources, regardless of the availability of excess
processor resources.
False
Indicates that the current Integrated Facility for Linux
(IFL) processing weight for the logical partition is not
capped. It represents the share of resources guaranteed to
a logical partition when all processor resources are in
use. Otherwise, when excess processor resources are
available, the logical partition can use them if necessary.
absolute-ifl-capping (w) absolute- The amount of absolute capping applied to the Integrated
capping Facility for Linux (IFL) processor.
object Note: Absolute capping does not apply to image profiles
where the processors are dedicated to the partition. Absolute
capping only applies to partitions using shared processors.
| initial-cbp-processing- (w) Integer The relative amount of shared Container Based Processor
| weight1, 2, 3, 9, 10 (1-999) (CBP) resources allocated to the logical partition.

Chapter 11. Core IBM Z resources 711

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
| initial-cbp-processing- (w) Boolean Whether the initial processing weight for Container Based
| weight-capped1, 2, 3, 4, 10 Processors (CBP) is a limit or a target.
| True
| Indicates that the initial Container Based Processor's
| (CBP) processing weight for the logical partition is
| capped. It represents the logical partition's maximum
| share of Container Based Processor (CBP) resources,
| regardless of the availability of excess Container Based
| Processor (CBP) resources.
| False
| Indicates that the initial Container Based Processor's
| (CBP) processing weight for the logical partition is not
| capped. It represents the share of Container Based
| Processor (CBP) resources guaranteed to a logical
| partition when all Container Based Processor (CBP)
| resources are in use. Otherwise, when excess Container
| Based Processor (CBP) resources are available, the logical
| partition can use them if necessary.
| minimum-cbp- (w) Integer The minimum relative amount of shared Container Based
| processing-weight1, 2, 3, Processor (CBP) resources allocated to the logical partition.
| 9, 10
| Get:
| 0 There is no minimum value for the processing weight.
| 1-999
| Represents the minimum relative amount of shared
| Container Based Processor (CBP) resources allocated to
| the logical partition.

| Update:
| 0 There is no minimum value for the processing weight.
| 1-999
| Define the minimum relative amount of shared Container
| Based Processor (CBP) resources allocated to the logical
| partition.
| maximum-cbp- (w) Integer The maximum relative amount of shared Container Based
| processing-weight1, 2, 3, Processor (CBP) resources allocated to the logical partition.
| 9, 10
| Get:
| 0 There is no maximum value for the processing weight.
| 1-999
| Represents the maximum relative amount of shared
| Container Based Processor (CBP) resources allocated to
| the logical partition.

| Update:
| 0 There is no maximum value for the processing weight.
| 1-999
| Define the maximum relative amount of shared
| Container Based Processor (CBP) resources allocated to
| the logical partition.

712 HMC Web Services API

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
| current-cbp- — Integer The current relative amount of shared Container Based
| processing-weight1, 3, 10 Processor (CBP) resources allocated to the logical partition.
| current-cbp- — Boolean Whether the current Container Based Processor's (CBP)
| processing-weight- processing weight is a limit or a target.
| capped1, 2, 3, 10
| True
| Indicates that the current Container Based Processor's
| (CBP) processing weight for the logical partition is
| capped. It represents the logical partition's maximum
| share of resources, regardless of the availability of excess
| processor resources.
| False
| Indicates that the current Container Based Processor's
| (CBP) processing weight for the logical partition is not
| capped. It represents the share of resources guaranteed to
| a logical partition when all processor resources are in
| use. Otherwise, when excess processor resources are
| available, the logical partition can use them if necessary.
| absolute-cbp-capping10 (w) absolute- The amount of absolute capping applied to the Container
capping- Based Processor's (CBP).
object Note: Absolute capping does not apply to image profiles
where the processors are dedicated to the partition. Absolute
| capping only applies to partitions using shared processors.
initial-ziip-processing- (w) Integer The relative amount of shared z Integrated Information
| weight1, 2, 3, 9 (1-999) Processors (zIIP) processor resources allocated to the logical
partition.
initial-ziip-processing- (w) Boolean Whether the initial processing weight for z Integrated
| weight-capped1, 2, 3, 4 Information Processors (zIIP) processors is a limit or a target.
True
Indicates that the initial z Integrated Information
Processors (zIIP) processor processing weight for the
logical partition is capped. It represents the logical
partition's maximum share of z Integrated Information
Processors (zIIP) processor resources, regardless of the
availability of excess z Integrated Information Processors
(zIIP) processor resources.
False
Indicates that the initial z Integrated Information
Processors (zIIP) processor processing weight for the
logical partition is not capped. It represents the share of z
Integrated Information Processors (zIIP) processor
resources guaranteed to a logical partition when all z
Integrated Information Processors (zIIP) processor
resources are in use. Otherwise, when excess z Integrated
Information Processors (zIIP) processor resources are
available, the logical partition can use them if necessary.

Chapter 11. Core IBM Z resources 713

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
minimum-ziip- (w) Integer The minimum relative amount of shared z Integrated
| processing-weight1, 2, 3, 9 Information Processors (zIIP) processor resources allocated to
the logical partition.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared z
Integrated Information Processors (zIIP) processor
resources allocated to the logical partition.

Update:
0 There is no minimum value for the processing weight.
1-999
Define the minimum relative amount of shared z
Integrated Information Processors (zIIP) processor
resources allocated to the logical partition.
maximum-ziip- (w) Integer The maximum relative amount of shared z Integrated
| processing-weight1, 2, 3, 9 Information Processors (zIIP) processor resources allocated to
the logical partition.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared z
Integrated Information Processors (zIIP) processor
resources allocated to the logical partition.

Update:
0 There is no maximum value for the processing weight.
1-999
Define the maximum relative amount of shared z
Integrated Information Processors (zIIP) processor
resources allocated to the logical partition.
current-ziip- — Integer The current relative amount of shared z Integrated
processing-weight1, 3 (1-999) Information Processors (zIIP) processor resources allocated to
the logical partition.

714 HMC Web Services API

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
current-ziip- — Boolean Whether the current z Integrated Information Processors
processing-weight- (zIIP) processing weight is a limit or a target.
| capped1, 3
True
Indicates that the current z Integrated Information
Processors (zIIP) processing weight for the logical
partition is capped. It represents the logical partition's
maximum share of resources, regardless of the
availability of excess processor resources.
False
Indicates that the current z Integrated Information
Processors (zIIP) processing weight for the logical
partition is not capped. It represents the share of
resources guaranteed to a logical partition when all
processor resources are in use. Otherwise, when excess
processor resources are available, the logical partition can
use them if necessary.
absolute-ziip-capping (w) absolute- The amount of absolute capping applied to the z Integrated
capping Information Processors (zIIP) processor.
object Note: Absolute capping does not apply to image profiles
where the processors are dedicated to the partition. Absolute
capping only applies to partitions using shared processors.
initial-cf-processing- (w) Integer The relative amount of shared Internal Coupling Facility (ICF)
| weight1, 2, 3, 9 (1-999) processor resources allocated to the Logical Partition object.
initial-cf-processing- (w) Boolean Indicates whether the initial processing weight for Internal
| weight-capped1, 2, 3, 4 Coupling Facility (ICF) processors is a limit or a target.
True
Indicates that the initial Internal Coupling Facility (ICF)
processor processing weight for the Logical Partition
object is capped. It represents the logical partition's
maximum share of Internal Coupling Facility (ICF)
processor resources, regardless of the availability of
excess Internal Coupling Facility (ICF) processor
resources.
False
Indicates that the initial Internal Coupling Facility (ICF)
processor processing weight for the Logical Partition is
not capped. It represents the share of Internal Coupling
Facility (ICF) processor resources guaranteed to a logical
partition when all Internal Coupling Facility (ICF)
processor resources are in use. Otherwise, when excess
Internal Coupling Facility (ICF) processor resources are
available, the logical partition can use them if necessary.

Chapter 11. Core IBM Z resources 715

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
minimum-cf- (w) Integer The minimum relative amount of shared Internal Coupling
| processing-weight1, 2, 3, 9 Facility (ICF) processor resources allocated to the Logical
Partition object.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared
Internal Coupling Facility (ICF) processor resources
allocated to the Logical Partition object.

Update:
1-999
The minimum relative amount of shared Internal
Coupling Facility (ICF) processor resources allocated to
the Logical Partition object.
maximum-cf- (w) Integer The maximum relative amount of shared Internal Coupling
| processing-weight1, 2, 3, 9 Facility (ICF) processor resources allocated to the Logical
Partition object.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared
Internal Coupling Facility (ICF) processor resources
allocated to the Logical Partition object.

Update:
0 There is no maximum value for the processing weight.
1-999
Define the maximum relative amount of shared Internal
Coupling Facility (ICF) processor resources allocated to
the Logical Partition object.
current-cf-processing- — Integer The current relative amount of shared Internal Coupling
weight1, 3 (1-999) Facility (ICF) processor resources allocated to the Logical
Partition object.
current-cf-processing- — Boolean Indicates whether the current Internal Coupling Facility (ICF)
| weight-capped1, 3 processing weight is a limit or a target.
True
Indicates that the current Internal Coupling Facility (ICF)
processing weight for the Logical Partition object is
capped. It represents the logical partition's maximum
share of resources, regardless of the availability of excess
processor resources.
False
Indicates that the current Internal Coupling Facility (ICF)
processing weight for the Logical Partition is not capped.
It represents the share of resources guaranteed to a
logical partition when all processor resources are in use.
Otherwise, when excess processor resources are available,
the logical partition can use them if necessary.

716 HMC Web Services API

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
absolute-cf-capping (w) absolute- The amount of absolute capping applied to the Internal
capping Coupling Facility (ICF) processor.
object Note: Absolute capping does not apply to image profiles
where the processors are dedicated to the partition. Absolute
capping only applies to partitions using shared processors.
program-status-word- — Array of Describes the current PSW information for each CP associated
information1 psw- with the logical partition. The information is obtained on each
description Get Logical Partition Properties request and is not cached.
objects Refer to the description of the psw-description object for
details.
| initial-vfm-storage8 — Long The initial amount of Virtual Flash Memory (VFM) storage, in
gigabytes (GB), to be allocated to this logical partition at
activation. The valid range is 0 to the value indicated on the
storage-vfm-total property in a multiple of the value
indicated on the storage-vfm-increment-size property for the
associated CPC.
| maximum-vfm-storage8 — Long The maximum amount of VFM storage, in gigabytes (GB),
that can be allocated to this logical partition while it is
running. The valid range is 0 to the value indicated on the
storage-vfm-total property in a multiple of the value
indicated on the storage-vfm-increment-size property for the
associated CPC.
| current-vfm-storage8 — Long The current amount of VFM storage, in gigabytes (GB), that is
allocated to this logical partition. The valid range is 0 to the
value indicated on the storage-vfm-total property in a
multiple of the value indicated on the storage-vfm-
increment-size property for the associated CPC.
os-ipl-token1 (pc) String (1-16) Applicable only to z/OS, a value provided when z/OS is
IPLed that uniquely identifies the instance of the operating
system. Used by z/OS to obtain knowledge about the status
of another system in the sysplex, and upon the demise of the
system, potentially partition the system out of the sysplex
immediately and reset the demised system. The value is a
string of hexadecimal characters (0-9,A-Z), left justified.
group-profile-capacity1 — Integer The current value of the effective-capacity property of the
Group Profile with which the logical partition is associated. A
null object is returned if the logical partition is not assigned
to an LPAR group.
group-profile-uri1 — String/URI The canonical URI of the Group Profile associated with the
logical partition. A null object is returned if the logical
partition is not assigned to an LPAR group.
| zaware-host-name6 (w) String (1-64) The IBM zAware host name. Valid characters are: a-z,A-Z,0-9,
period(.), minus(-) and colon(:)
| zaware-master-userid6 (w) String (1-32) The IBM zAware master userid. Valid characters are:
a-z,A-Z,0-9, period(.), minus(-) and underscore (_)
| zaware-master-pw6 (wo) String The IBM zAware master password. Valid characters are:
(8-256) a-z,A-Z,0-9 and !@#$%^&*()_+{}|<>?-=

This property is not returned on a Get request, it can only be

specified on an Update request.

Chapter 11. Core IBM Z resources 717

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
6
| zaware-network-info (w) Array of The set of networks available to IBM zAware. A minimum of
zaware- 1 network and a maximum of 100 networks are permitted.
network
objects On an Update request, this property fully replaces the
existing set.
| zaware-gateway-info6 (w) ip-info The default gateway IP address information. A null object
object indicates no default gateway IP address is specified.
| zaware-dns-info6 (w) Array of The DNS IP address information. A minimum of 0 entries and
ip-info a maximum of 2 entries are permitted.
objects
On an Update request, this property fully replaces the
existing set.
| ssc-host-name7 (w) or — if String (1-64) The Secure Service Container name. Valid characters are: a-z,
se-version is A-Z, 0-9, period(.), minus(-), and colon(:).
"2.14.0" or
later
| ssc-master-userid7 (w) or — if String (1-32) The Secure Service Container master user ID. Valid characters
se-version is are: a-z, A-Z, 0-9, period(.), minus(-), and underscore(_).
"2.14.0" or
later
| ssc-master-pw7 (wo) or — if String The Secure Service Container master user password. Valid
se-version is (8-256) characters are: a-z, A-Z, 0-9, and !@#$%^&*()_+{}|<>?-=.
"2.14.0" or
later This property is not returned on a Get request; it can be
specified on an Update request.
| ssc-network-info7 (w) or — if Array of The set of networks available to the Secure Service Container.
se-version is ssc-network A minimum of 1 network and a maximum of 100 networks
"2.14.0" or objects are permitted.
later
On an Update request, this property fully replaces the
existing set.
| ssc-gateway-info7 (w) or — if ip-info The default gateway IP address information for the Secure
se-version is object Service Container. A null object indicates no default gateway
"2.14.0" or IP address is specified. Only IPv4 address types are
later supported.
| ssc-dns-info7 (w) or — if Array of The DNS IP address information for the Secure Service
se-version is ip-info Container. A minimum of 0 entries and a maximum of 2
"2.14.0" or objects entries are permitted
later
On an Update request, this property fully replaces the
existing set.
storage-central- — Array of A nested object that details the central storage allocated to the
allocation central- logical partition. Refer to Table 323 on page 719 for details. If
storage- there are no central-storage-allocation objects, a null object is
allocation returned.
objects
storage-expanded- — Array of A nested object that details the expanded storage allocated to
allocation expanded- the logical partition. Refer to Table 324 on page 719 for
storage- details. If there are no expanded-storage-allocation objects, a
allocation null object is returned.
objects

718 HMC Web Services API

 Level 04a

Table 322. Logical Partition object: class specific additional properties (continued)
Name Qualifier Type Description
Notes:
1. If the logical partition status property is "not-activated", a null object is returned instead of the documented
field type.
| 2. An Update of this property is only valid for an object-id that represents a logical partition with at least one
| shared processor of the corresponding type.
3. The value returned from a Get request is a null object for an object-id that does not represent a logical
| partition with at least one shared processor of the corresponding type.
4. This property and the workload-manager-enabled property are mutually exclusive and cannot both be enabled
at the same time. Therefore in order to enable this property it might be necessary to first disable the
workload-manager-enabled property.
5. This property and the various capping properties are mutually exclusive and cannot be enabled at the same
time. Therefore in order to enable this property it may be necessary to first disable any capping property that is
currently enabled.
6. On a Get request, this property is returned only when activation-mode is "zaware". On an Update request, this
property can be updated only when activation-mode is "zaware".
7. On a Get request, this property is returned only when activation-mode is "ssc". On an Update request, this
property can be updated only when activation-mode is "ssc".
8. On a Get request, this property is returned only when the SE version is 2.14.0 or later.
9. On an Update request, when workload-manager-enabled is true, the initial processing weight must be greater
than or equal to the minimum processing weight, and less than or equal to the maximum processing weight
within the same processor type.
| 10. On a Get request, this property is returned only when the associated SE version is 2.14.0 with the suitable MCL
| bundle, or a later SE version. On an Update request, this property can be included in the request body only
| when the associated SE version is 2.14.0 with the suitable MCL bundle, or a later SE version.

Table 323. central-storage-allocation nested object properties

Name Qualifier Type Description
origin — Long The origin in megabytes of central storage in memory or null
if the value is not available.
initial — Long The initial amount of central storage in megabytes that is
allocated or null if the value is not available.
current — Long The current amount of central storage in megabytes that is
allocated or null if the value is not available.
maximum — Long The maximum amount of central storage in megabytes that is
allocated or null if the value is not available.
gap — Long The gap in megabytes from this partition's central storage to
the start of the next partition's central storage, or null if the
value is not available.
storage-element-type — String Enum Type of storage element. Valid values are:
v "central" - central storage
v "initial" - initial expanded storage that is used as central
storage
v "reserved" - reserved expanded storage that is used as
central storage.

Table 324. expanded-storage-allocation nested object properties

Name Qualifier Type Description
origin — Long The origin in megabytes of expanded storage in memory.
initial — Long The initial amount of expanded storage in megabytes that is
allocated.

Chapter 11. Core IBM Z resources 719

 Level 04a

Table 324. expanded-storage-allocation nested object properties (continued)

Name Qualifier Type Description
current — Long The current amount of expanded storage in megabytes that is
allocated.
maximum — Long The maximum amount of expanded storage in megabytes
that is allocated.
gap — Long The gap in megabytes from this partition's expanded storage
to the start of the next partition's expanded storage.

List Logical Partitions of CPC

The List Logical Partitions of CPC operation lists the logical partitions of a CPC.

HTTP method and URI

GET /api/cpcs/{cpc-id}/logical-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. If matches are found, the response will be an
array with all objects that match. If no match is found, the response
will be an empty array.

Response body contents

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

Field name Type Description

logical-partitions Array of Array of nested logical-partition-info objects (described in the next table)
logical-
partition-
info objects

Each nested logical-partition-info object contains the following fields:

Field name Type Description

object-uri String/URI Canonical URI path of the Logical Partition object
name String The name of the Logical Partition object
status String The current status of the Logical Partition object
Enum

Description
This operation lists the Logical Partition objects that belong to a CPC. The object URI, display name, and
status are provided for each.

720 HMC Web Services API

 Level 04a

If the name query parameter is specified, the returned list is limited to those Logical Partition objects that
have a name property matching the specified filter pattern. If the name parameter is omitted, this
filtering is not 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” on page 720.

If the CPC is in DPM mode, or there are no logical partitions defined to the CPC, or no logical 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 Logical 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” on page 720.

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.
299 A query parameter has an invalid syntax.
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/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/logical-partitions HTTP/1.1

x-api-session: 65aw2jahugn1wop51hsq0c6aldkkx773dz9ulirrvg2z853m4u

Figure 410. List Logical Partitions of CPC: Request

Chapter 11. Core IBM Z resources 721

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 16:58:36 GMT
content-type: application/json;charset=UTF-8
content-length: 374
{
"logical-partitions": [
{
"name": "APIVM1",
"object-uri": "/api/logical-partitions/c7eb8134-826e-3a71-8d1a-00d706c874e9",
"status": "operating"
},
{
"name": "ZOS",
"object-uri": "/api/logical-partitions/458e44e1-b0c2-391b-83ff-ecfd847295bd",
"status": "not-operating"
}
]
}

Figure 411. List Logical Partitions of CPC: Response

List Permitted Logical Partitions

The List Permitted Logical Partitions operation lists logical partitions to which the API user has
object-access permission.

HTTP method and URI

GET /api/console/operation/list-permitted-logical-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.
activation-mode String Optional Filter string to limit returned objects to those that have a matching
Enum activation-mode property. Value must be a valid logical partition
activation-mode 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 logical 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.
cpc-name String Optional Filter pattern (regular expression) to limit returned objects to those
whose parent CPC has a matching name property.

722 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

logical-partitions Array of Array of nested logical-partition-info objects as described in the next table.
logical-
partition-
info
objects

Each nested logical-partition-info object contains the following fields:

Field name Type Description

name String The name property of the Logical Partition object.
object-uri String/ The object-uri property of the Logical Partition object.
URI
activation-mode String The activation-mode property of the Logical Partition object.
Enum
status String The status property of the Logical Partition object.
Enum
has-unacceptable-status Boolean The has-unacceptable-status property of the Logical Partition object.
cpc-name String The name property of the Logical Partition's parent CPC object.
cpc-object-uri String/ The object-uri property of the Logical Partition's parent CPC object.
URI

Description
This operation lists the Logical Partition objects to which the API user has object-access permission. Some
basic properties are provided for each logical partition that is included in the response.

If the name query parameter is specified, the returned list is limited to those logical partitions that have a
name property matching the specified filter pattern. If the name parameter is omitted, no such filtering is
performed.

If the activation-mode query parameter is specified, the parameter is validated to ensure it is a valid
logical partition activation-mode 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 logical partitions that have
an activation-mode property matching the specified value. If the activation-mode 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 logical
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 logical 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 logical
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.

If the cpc-name query parameter is specified, the returned list is limited to those logical partitions whose
parent CPC's name property matches the specified filter pattern. If the cpc-name parameter is omitted, no
such filtering is performed.

Chapter 11. Core IBM Z resources 723

 Level 04a

A logical partition is included in the list only if the API user has object-access permission to that object. If
there is a logical 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 logical partitions known to the HMC or if no logical 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 Logical 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 723.

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-logical-partitions HTTP/1.1

x-api-session: 3y0qwkkon9m03c5o81oo2fz7ozezkinczcdwwr4gauzgogb5xq

Figure 412. List Permitted Logical Partitions: Request

724 HMC Web Services API

 Level 04a

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 28 Aug 2017 18:07:25 GMT
content-type: application/json;charset=UTF-8
content-length: 794
{
"logical-partitions":[
{
"activation-mode":"general",
"cpc-name":"M87",
"cpc-object-uri":"/api/cpcs/f2eb7e56-0c87-3646-887e-ec735b3844cd",
"has-unacceptable-status":false,
"name":"S50",
"object-uri":"/api/logical-partitions/d39347d9-855a-3199-9ef6-a1701b7b17b4",
"status":"operating"
},
{
"activation-mode":"esa390",
"cpc-name":"S15",
"cpc-object-uri":"/api/cpcs/f6f629ca-f2c5-3f71-a80f-d9b91a492549",
"has-unacceptable-status":false,
"name":"APIVM2",
"object-uri":"/api/logical-partitions/c53c7aa7-444b-3f05-87b4-fb94802240b8",
"status":"operating"
},
{
"activation-mode":"not-set",
"cpc-name":"S15",
"cpc-object-uri":"/api/cpcs/f6f629ca-f2c5-3f71-a80f-d9b91a492549",
"has-unacceptable-status":true,
"name":"ZOS",
"object-uri":"/api/logical-partitions/17c4bc30-96b5-327e-8b7d-59e1b4b7261e",
"status":"not-activated"
}
]
}

Figure 413. List Permitted Logical 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 logical 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.

Get Logical Partition Properties

The Get Logical Partition Properties operation retrieves the properties of a single Logical Partition object
designated by {logical-partition-id}.

HTTP method and URI

GET /api/logical-partitions/{logical-partition-id}

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Query parameters:

Chapter 11. Core IBM Z resources 725

 Level 04a

Name Type Rqd/Opt Description

properties List of String Optional Filter string to limit returned properties to those that are
Enum identified here. This is a list of comma-separated strings where
each string is a property name defined in the Logical Partition
object's data model.
cached-acceptable Boolean Optional Indicates whether cached values are acceptable for the
returned properties. Valid values are true and false.

Response body contents

On successful completion, HTTP status code 200 (OK) is returned and the response body provides the
current values of the properties for the Logical Partition object as defined in “Data model” on page 703.

Description
The URI path must designate an existing Logical 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.

If the properties query parameter is specified, the response body contains only the requested properties.
The presence and value of each requested property is the same as it is when the properties query
parameter is not specified. That is, it may be omitted or contain a special value, such as null, -1, or an
empty string, if a prerequisite condition is not met. If the properties parameter is omitted, no such
filtering is performed.

Some logical partition property values are periodically fetched from the Support Element and cached on
the HMC for quick access by the APIs. Due to the nature of this caching support, the HMC's cached
value of a property may differ from the value on the Support Element at any point in time. While the
HMC strives to keep the cache reasonably current, there are no guarantees about the latency of the cache,
nor is there any latency information available to the API user. If the cached-acceptable query parameter
is specified as true and a property's value is currently present in the cache, the value from the cache is
returned; otherwise, the current, non-cached value 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 “Data model” on page 703.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}.
v Object-access permission to the logical partition's parent CPC object.

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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

726 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.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.

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/logical-partitions/c7eb8134-826e-3a71-8d1a-00d706c874e9 HTTP/1.1

x-api-session: 5obf0hwsfv1sg9kr5f93cph3zt6o5cptb6lcl538wuyebdyzu4

Figure 414. Get Logical Partition Properties: Request

Chapter 11. Core IBM Z resources 727

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 17:16:16 GMT
content-type: application/json;charset=UTF-8
content-length: 2440
{
"absolute-aap-capping":{"type": "none"},
| "absolute-cbp-capping":{"type": "none"},
"absolute-cf-capping":{"value": 88.52, "type": "processors"},
"absolute-ifl-capping":{"type": "none"}
"absolute-processing-capping":{"value": 0.01, "type": "processors"},
"absolute-ziip-capping":{"value": 2.01, "type": "processors"},
"acceptable-status": [
"operating"
],
"activation-mode": "esa390",
"additional-status": "",
"class": "logical-partition",
"cluster-name": "",
"current-aap-processing-weight": null,
"current-aap-processing-weight-capped": null,
| "current-cbp-processing-weight": null,
| "current-cbp-processing-weight-capped": null,
"current-cf-processing-weight": null,
"current-cf-processing-weight-capped": null,
"current-ifl-processing-weight": null,
"current-ifl-processing-weight-capped": null,
"current-processing-weight": 100,
"current-processing-weight-capped": false,
"current-vfm-storage": 256,
"current-ziip-processing-weight": null,
"current-ziip-processing-weight-capped": null,
"defined-capacity": 0,
"description": "LPAR Image",
"group-profile-capacity": null,
"group-profile-uri": null,
"has-operating-system-messages": false,
"has-unacceptable-status": false,
"initial-aap-processing-weight": null,
"initial-aap-processing-weight-capped": null,
| "initial-cbp-processing-weight": null,
| "initial-cbp-processing-weight-capped": null,
"initial-cf-processing-weight": null,
"initial-cf-processing-weight-capped": null,
"initial-ifl-processing-weight": null,
"initial-ifl-processing-weight-capped": null,
"initial-processing-weight": 100,
"initial-processing-weight-capped": false,
"initial-vfm-storage": 64,
"initial-ziip-processing-weight": null,
"initial-ziip-processing-weight-capped": null,
"is-locked": false,
"last-used-activation-profile": "APIVM1",
"last-used-load-address": "05402",
"last-used-load-parameter": "TESTMODE",
"maximum-aap-processing-weight": null,
| "maximum-cbp-processing-weight": null,
"maximum-cf-processing-weight": null,
"maximum-ifl-processing-weight": null,

Figure 415. Get Logical Partition Properties: Response (Part 1)

728 HMC Web Services API

 Level 04a

"maximum-processing-weight": 200,
"maximum-vfm-storage": 512,
"maximum-ziip-processing-weight": null,
"minimum-aap-processing-weight": null,
| "minimum-cbp-processing-weight": null,
"minimum-cf-processing-weight": null,
"minimum-ifl-processing-weight": null,
"minimum-processing-weight": 50,
"minimum-ziip-processing-weight": null,
"name": "APIVM1",
"next-activation-profile-name": "APIVM1",
"object-id": "c7eb8134-826e-3a71-8d1a-00d706c874e9",
"object-uri": "/api/logical-partitions/c7eb8134-826e-3a71-8d1a-00d706c874e9",
"os-ipl-token": "0000000000000000",
"os-level": "6.2.0",
"os-name": "APIVM1",
"os-type": "z/VM",
"parent": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"partition-number": 1,
"program-status-word-information": [
{
"cpid": "00",
"psw": "07064000800000000000000000000000"
},
{
"cpid": "01",
"psw": "07064000800000000000000000000000"
}
],
"status": "operating",
"storage-central-allocation": [
{
"origin": 16697344,
"initial": 1024,
"current": 1024,
"maximum": 1024,
"gap": 1024,
"storage-element-type": "central"
},
{
"origin": 16696832,
"initial": null,
"current": 512,
"maximum": null,
"gap": 0,
"storage-element-type": "initial"
}
],
"storage-expanded-allocation": [
{
"origin": 16776704,
"initial": 512,
"current": 512,
"maximum": 512,
"gap": 0
}
],
"sysplex-name": "SSICAPI1",
"workload-manager-enabled": true
}

Figure 416. Get Logical Partition Properties: Response (Part 2)

Chapter 11. Core IBM Z resources 729

 Level 04a

Update Logical Partition Properties

The Update Logical Partition Properties operation updates one or more writable properties of the Logical
Partition object designated by {logical-partition-id}.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

The request body is expected to contain one or more field names representing writable logical 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 Logical 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.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Change Object Definition task.
v Object-access permission to the logical partition's parent CPC object.
v For a logical partition whose activation-mode is "zaware", action/task permission for the Firmware
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, 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 ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.

730 HMC Web Services API

 Level 04a

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

Activate Logical Partition

The Activate Logical Partition operation activates the Logical Partition object designated by
{logical-partition-id}.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/activate

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

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

Field name Type Rqd/Opt Description

activation-profile- String Optional The name of the activation profile to be used for the request. If not
name (1-16) provided, the request uses the profile name specified in the
next-activation-profile-name property for the Logical Partition
object.
force Boolean Optional Whether this operation is permitted when the logical partition is in
"operating" status (true) or not (false). The default is false.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 733. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Chapter 11. Core IBM Z resources 731

 Level 04a

Description
Activation is a process that makes a logical partition operational, which means either:
v The logical partition is ready to have a control program or operating system loaded, or
v The logical partition has loaded and is running a control program or operating system.

Activating a logical partition includes:

v Initializing the logical partition
v Allocating system resources to the logical partition
v Loading the logical partition with a control program or operating system.

Since the status of the logical partition determines which operations must be performed during activation
to make the logical partition operational, one or more operations listed above may not be performed
during activation.

If planning to load the z/VM operating system in this logical partition, refer to Chapter 15,
“Virtualization management,” on page 985 for details on the activation of virtual servers.

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. See “Job status and reason codes” on page 733.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Activate task.
v Object-access permission to the logical partition's parent CPC object.

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 731.

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 object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

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

732 HMC Web Services API

 Level 04a

Job status and reason codes

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed or was rejected due to the current logical partition status
and use of the force=false parameter. If rejected due to force=false, the
logical partition status is unchanged. If the operation failed, the logical
partition status is unknown. Refer to the message parameter in the error
response body for details.

Deactivate Logical Partition

The Deactivate Logical Partition operation deactivates the Logical Partition object designated by
{logical-partition-id}.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/deactivate

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

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

Field name Type Rqd/Opt Description

force Boolean Optional Whether this operation is permitted when the logical partition is in
"operating" status (true) or not (false). The default is false.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 734. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Chapter 11. Core IBM Z resources 733

 Level 04a

Description
Deactivation is an orderly process for terminating a logical partition.

Deactivating a logical partition includes:

v Unloading the logical partition's control program or operating system
v Freeing system resources allocated to the logical partition.

After the logical partition is deactivated, the logical partition is no longer operational

If this logical partition currently has the z/VM operating system loaded, refer to Chapter 15,
“Virtualization management,” on page 985 for the details on deactivation of virtual servers.

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. See “Job status and reason codes.”

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Deactivate task.
v Object-access permission to the logical partition's parent CPC object.

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 733.

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 object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

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

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.

734 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
500 (Server Error) 263 Operation failed or was rejected due to the current logical partition status
and use of the force=false parameter. If rejected due to force=false, the
logical partition status is unchanged. If the operation failed, the logical
partition status is unknown. Refer to the message parameter in the error
response body for details.

Reset Normal
The Reset Normal operation initializes a system or logical partition by clearing its pending interruptions,
resetting its channel subsystem and resetting its processors. A reset prepares a system or logical partition
for loading it with an operating system.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/reset-normal

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

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

Field name Type Rqd/Opt Description

force Boolean Optional Whether this operation is permitted when the logical partition is in
"operating" status (true) or not (false). The default is false.
os-ipl-token String Optional Applicable only to z/OS, this parameter requests that this operation
(1-16) only be performed if the provided value matches the current value
of the os-ipl-token property. This ensures that this operation is
targeting the same IPL instance as when the os-ipl-token property
was retrieved. IBM recommends that this parameter only be
provided by callers that fully understand how the os-ipl-token
parameter is managed by z/OS. The value is a string of
hexadecimal characters (0-9, A-Z), left justified.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 736. The job-results field is null when this operation
is successful. When it is partially successful or not successful, the job-results field contains an object with
the following field:
Chapter 11. Core IBM Z resources 735
 Level 04a

Field name Type Description

message String The message text describing the detailed error that occurred when the
operation was partially successful or not successful.

Description
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. See “Job status and reason codes.”

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Reset Normal task.
v Object-access permission to the logical partition's parent CPC object.

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 735.

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.
264 The specified IPL Token value does not match the current IPL Token value.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

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

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed or was rejected due to the current logical partition status
and use of the force=false parameter. If rejected due to force=false, the
logical partition status is unchanged. If the operation failed, the logical
partition status is unknown. Refer to the message parameter in the error
response body for details.

736 HMC Web Services API

 Level 04a

Reset Clear
The Reset Clear operation initializes system or logical partition by clearing its pending interruptions,
resetting its channel subsystem and resetting its processors. A reset prepares a system or logical partition
for loading it with an operating system and clears main memory of the system or logical partition.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/reset-clear

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

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

Field name Type Rqd/Opt Description

force Boolean Optional Whether this operation is permitted when the logical partition is in
"operating" status (true) or not (false). The default is false.
os-ipl-token String Optional Applicable only to z/OS, this parameter requests that this operation
(1-16) only be performed if the provided value matches the current value
of the os-ipl-token property. This ensures that this operation is
targeting the same IPL instance as when the os-ipl-token property
was retrieved. IBM recommends that this parameter only be
provided by callers that fully understand how the os-ipl-token
parameter is managed by z/OS. The value is a string of
hexadecimal characters (0-9,A-Z), left justified.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 738. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Chapter 11. Core IBM Z resources 737

 Level 04a

Description
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. See “Job status and reason codes.”

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Reset Clear task.
v Object-access permission to the logical partition's parent CPC object.

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 737.

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.
264 The specified IPL Token value does not match the current IPL Token value.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

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

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed or was rejected due to the current logical partition status
and use of the force=false parameter. If rejected due to force=false, the
logical partition status is unchanged. If the operation failed, the logical
partition status is unknown. Refer to the message parameter in the error
response body for details.

Load Logical Partition

The Load Logical Partition operation resets a logical partition, to prepare it for loading an operating
system, and loads the operating system.

738 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/load

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

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

Field name Type Rqd/Opt Description

load-address String Optional The hexadecimal address of an I/O device that provides access to
(1-5) the control program to be loaded. The input value is right justified
and padded with zeros to 5 characters.

Valid values are in the range "00000" to "nFFFF" where "n" is the
number of subchannel sets provided by the CPC minus 1. So, for
example, on a CPC that provides 3 subchannel sets, the valid range
is "00000" to "2FFFF".

When load-address is not supplied, the operation will try to load

using the address used in the last load.
load-parameter String Optional Some control programs support the use of this property to provide
(1-8) additional control over the outcome of a Load operation. Refer to
the configuration documentation for the control program to be
loaded to see if this parameter is supported and if so, what values
and format is supported. Omitting this field indicates that the value
for this field is to be retrieved from the current IOCDS. Valid
characters are 0-9, A-Z, blank and period. Three additional
characters, (@, $, #) are also allowed when the se-version property
of the associated CPC is "2.14.0" or later.
clear-indicator Boolean Optional Whether memory should be cleared before performing the Load
(true) or not cleared (false). The default value is true.
timeout Integer Optional Amount of time, in seconds, to wait for the Load to complete. The
(60-600) default timeout value is 60 seconds.
store-status- Boolean Optional Whether status should be stored before performing the Load (true)
indicator or not stored (false). The default is false.
force Boolean Optional Whether this operation is permitted when the logical partition is in
"operating" status (true) or not (false). The default is false.
os-ipl-token String Optional Applicable only to z/OS, this parameter requests that this operation
(1-16) only be performed if the provided value matches the current value
of the os-ipl-token property. This ensures that this operation is
targeting the same IPL instance as when the os-ipl-token property
was retrieved. IBM recommends that this parameter only be
provided by callers that fully understand how the os-ipl-token
parameter is managed by z/OS. The value is a string of
hexadecimal characters (0-9, A-Z), left justified.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

Chapter 11. Core IBM Z resources 739

 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 741. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Description
This operation is not permitted for a logical partition whose activation-mode property is "zaware" or
"ssc".

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. See “Job status and reason codes” on page 741.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Load task.
v Object-access permission to the logical partition's parent CPC object.

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 739.

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.
264 The specified IPL Token value does not match the current IPL Token value.
306 This operation is not valid in the current activation mode.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

740 HMC Web Services API

 Level 04a

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

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed or was rejected due to the current logical partition status
and use of the force=false parameter. If rejected due to force=false, the
logical partition status is unchanged. If the operation failed, the logical
partition status is unknown. Refer to the message parameter in the error
response body for details.

PSW Restart
The PSW Restart operation restarts the first available processor of the Logical Partition object designated
by {logical-partition-id}.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/psw-restart

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 742. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Description
Information about PSW Restart can be found on console help system.

Chapter 11. Core IBM Z resources 741

 Level 04a

This operation is not permitted for a logical partition whose activation-mode property is "zaware" or
"ssc".

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. See “Job status and reason codes.”

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the PSW Restart task.
v Object-access permission to the logical partition's parent CPC object.

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 741.

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.
306 This operation is not valid in the current activation mode.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

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

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed.

Start Logical Partition

The Start Logical Partition operation starts the processors to process instructions of the Logical Partition
object designated by {logical-partition-id}.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/start

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.
742 HMC Web Services API
 Level 04a

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 744. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Description
This operation is not permitted for a logical partition whose activation-mode property is "zaware" or
"ssc".

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. See “Job status and reason codes” on page 744.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Start task.
v Object-access permission to the logical partition's parent CPC object.

HTTP status and reason codes

On success, HTTP status code 202 (Accepted) is returned and the response body is provided as described
in “Response body contents.”

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

Chapter 11. Core IBM Z resources 743

 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.
306 This operation is not valid in the current activation mode.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

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

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed.

Stop Logical Partition

The Stop Logical Partition operation stops the processors from processing instructions of the Logical
Partition object designated by {logical-partition-id}.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/stop

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 745. The job-results field is null when this operation
is successful. When it is partially successful or not successful, the job-results field contains an object with
the following field:

744 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 partially successful or not successful.

Description
This operation is not permitted for a logical partition whose activation-mode property is "zaware" or
"ssc".

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. See “Job status and reason codes.”

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Stop task.
v Object-access permission to the logical partition's parent CPC object.

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 744.

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.
306 This operation is not valid in the current activation mode.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

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

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed.

Chapter 11. Core IBM Z resources 745

 Level 04a

Send OS Command
The Send OS Command operation sends a command to the operating system running in a logical
partition.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/send-os-cmd

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

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

Field name Type Rqd/Opt Description

is-priority Boolean Optional An indication of whether this is a priority operating
system command. Set to true for priority operating
system commands or false for non-priority operating
system commands. The default is false.
operating-system- String (1-200) Required The text of the operating system command.
command-text

Description
This operation sends a command to the operating system running in the Logical Partition targeted by the
request URI.

The URI path must designate an existing Logical 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. In addition to having object-access permission to the Logical Partition, the API user must also
have permission to the Operating System Messages task, otherwise status code 403 (Forbidden) is
returned. Status code 409 (Conflict) is returned when the message interface for the operating system
running in the target logical partition is not available. Some examples are when the Logical Partition is
not active, there is no operating system running in the partition, or when the operating system is not
enabled for console integration.

On successful execution, the command is sent to the operating system running in the target Logical
Partition object and status code 204 (No Content) is returned without supplying a response body.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Operating System Messages 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

746 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.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform this operation.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designated an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
409 (Conflict) 332 The messages interface is not available.
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

POST /api/logical-partitions/c7eb8134-826e-3a71-8d1a-00d706c874e9/operations/send-os-cmd HTTP/1.1

x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4qymqa8ktzjep7dbyrll0k
content-type: application/json
content-length: 69
{
“is-priority”: false,
“operating-system-command-text”: “help”
}

Figure 417. Send OS Command: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 01 Feb 2016 09:57:18 GMT

<No response body>

Figure 418. Send OS Command: Response

Open OS Message Channel

The Open OS Message Channel operation opens a message channel to the operating system running in
a logical partition.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/open-os-message-channel

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Chapter 11. Core IBM Z resources 747

 Level 04a

Request body contents

An optional request body can be specified as a JSON object with the following field:

Field name Type Rqd/Opt Description

include-refresh- Boolean Optional An indication of whether refresh operating system
messages messages should be sent. Set to true to receive refresh
messages, or false to prevent refresh messages. The
default is true.

Response body contents

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

Field name Type Description

topic-name String The name of the os-message-notification topic.
(1-128)

Description
This operation opens a message channel to the operating system running in the Logical Partition targeted
by the request URI. The message channel is implemented as a JMS topic, specifically as an
os-message-notification topic. See Chapter 4, “Asynchronous notification,” on page 47 for information on
JMS usage on the HMC. The API user can connect to this topic to start the flow of new (and refreshed)
operating system messages.

The URI path must designate an existing Logical 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. In addition to having object-access permission to the Logical Partition, the API user must also
have permission to the Operating System Messages task or the Operating System Messages task in
view-only mode, otherwise status code 403 (Forbidden) is returned. Status code 409 (Conflict) is returned
when the message interface for the operating system running in the target logical partition is not
available. Some examples are when the Logical Partition is not active, there is no operating system
running in the partition, or when the operating system is not enabled for console integration.

If an os-message-notification topic already exists for this logical partition for the current API session, the
operation fails.

On successful execution, the message channel is opened and the os-message-notification topic name is
returned in the response body.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Operating System Messages task, or the Operating System Messages
task in view-only mode.

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.”

748 HMC Web Services API

 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.
Table 325. Open OS Message Channel: 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 The user under which the API request was authenticated does not have the
required authority to perform this operation.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
409 (Conflict) 331 An os-message-notification topic already exists for this logical partition for
the current API session. Use the Get Notification Topics operation to
determine the topic name.
332 The messages interface is not available.

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/logical-partitions/c7eb8134-826e-3a71-8d1a-00d706c874e9/operations/
open-os-message-channel HTTP/1.1
x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4qymqa8ktzjep7dbyrll0k
content-type: application/json
content-length: 37
{ “include-refresh-messages”: true }

Figure 419. Open OS Message Channel: 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
{ “topic-name”: “mikeuser.1osmsg.cpc1.lpar1” }

Figure 420. Open OS Message Channel: Response

List OS Messages of a Logical Partition

The List OS Messages of a Logical Partition operation lists all currently available operating system (OS)
messages for a logical partition.

HTTP method and URI

GET /api/logical-partitions/{logical-partition-id}/operations/list-os-messages

In this request, the URI variable {logical-partition-id} is the object ID of the target logical partition.

Query parameters:

Chapter 11. Core IBM Z resources 749

 Level 04a

Name Type Rqd/Opt Description

begin-sequence- Long Optional A message sequence number to limit returned messages. OS
number messages with a sequence number less than this are omitted from
the results. If not specified, then no such filtering is performed.
end-sequence- Long Optional A message sequence number to limit returned messages. OS
number messages with a sequence number greater than this are omitted from
the results. If not specified, then no such filtering is performed.

Response body contents

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

Field name Type Description

os-messages Array of Array of nested os-message-info objects as described in the next table. The
os- array elements are in order of increasing sequence number, unless that
message- number has wrapped back around to 0 in which case the element with
info sequence number 0 follows the element with the highest sequence
objects number, thus maintaining the temporal order of the messages.

Each nested os-message-info object contains the following fields:

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. It can be used for
filtering purposes.
message-text String The text of the operating system message.
message-id String The message identifier of the operating system message.
timestamp Timestamp The time when the operating system message was created or -1 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.
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 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
logical partition in which the operating system is running.

750 HMC Web Services API

 Level 04a

Description
This operation lists the currently available messages from the operating system running in the specified
logical partition. Only a certain amount of OS message data from each logical partition is preserved by
the HMC for retrieval by this operation. If the OS produces more than that amount, the oldest non-held,
non-priority OS messages are no longer available. A gap in the sequence numbers indicates a loss of
messages. A loss may be due to that space limitation, or it may be due to the deletion of messages by a
console user or the OS.

If the request URI does not identify a Logical Partition object to which the API user has object-access
permission, HTTP status code 404 (Not Found) is returned. In addition to having object-access permission
to the logical partition, the API user must also have permission to the Operating System Messages task
or the Operating System Messages task in view-only mode, otherwise status code 403 (Forbidden) is
returned. Status code 409 (Conflict) is returned when the message interface for the operating system
running in the target logical partition is not available. Some examples are when the logical partition is not
active, there is no operating system running in the logical partition, or when the operating system is not
enabled for console integration.

If the begin-sequence-number query parameter is specified, then any OS messages with a

sequence-number less than that are omitted from the response. If the end-sequence-number query
parameter is specified, then any OS messages with a sequence-number greater than that are omitted
from the response

If there are no available OS messages for the specified logical partition or if no OS messages are to be
included in the response due to filtering, 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 Logical Partition object designated by {logical-partition-id}.
v Action/task permission for the Operating System Messages task, or the Operating System Messages
task in view-only mode.

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 750.

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.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
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) 332 The messages interface is not available.

Chapter 11. Core IBM Z resources 751

 Level 04a

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/logical-partitions/d39347d9-855a-3199-9ef6-a1701b7b17b4/operations/
list-os-messages HTTP/1.1
x-api-session: 2cckypxdonb44w6n8dvyly3vpw9hekwr2soasrhax41oetlbni

Figure 421. List OS Messages of a Logical Partition: Request

200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 28 Aug 2017 19:59:00 GMT
content-type: application/json;charset=UTF-8
content-length: 665
{
"os-messages":[
{
"is-held":true,
"is-priority":false,
"message-id":69166,
"message-text":"*IOS002A AB4D,NO PATHS AVAILABLE\n",
"os-name":"S50 ",
"prompt-text":"",
"sequence-number":10541,
"sound-alarm":false,
"timestamp":1503926847000
},
{
"is-held":true,
"is-priority":false,
"message-id":69167,
"message-text":"*IOS002A AB11,NO PATHS AVAILABLE\n",
"os-name":"S50 ",
"prompt-text":"",
"sequence-number":10542,
"sound-alarm":false,
"timestamp":1503926847000
},
{
"is-held":true,
"is-priority":false,
"message-id":69169,
"message-text":"*IOS002A AB42,NO PATHS AVAILABLE\n",
"os-name":"S50 ",
"prompt-text":"",
"sequence-number":10543,
"sound-alarm":false,
"timestamp":1503926847000
}
]
}

Figure 422. List OS Messages of a Logical Partition: Response

SCSI Load
The SCSI Load operation clears main storage, to prepare the logical partition for loading an operating
system, and loads the operating system from the designated SCSI device.

752 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/scsi-load

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

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

Field name Type Rqd/Opt Description

load-address String Required The hexadecimal address of an I/O device that provides access to
(1-5) the control program to be loaded. The input value is right justified
and padded with zeros to 5 characters.

Valid values are in the range "00000" to "nFFFF" where "n" is the
number of subchannel sets provided by the CPC minus 1. So, for
example, on a CPC that provides 3 subchannel sets, the valid range
is "00000" to "2FFFF".
load-parameter String Optional Some control programs support the use of this property to provide
(1-8) additional control over the outcome of a Load operation. Refer to
the configuration documentation for the control program to be
loaded to see if this parameter is supported and if so, what values
and format is supported. Omitting this field indicates that the value
for this field is to be retrieved from the current IOCDS. Valid
characters are 0-9, A-Z, blank and period. Three additional
characters, (@, $, #) are also allowed when the se-version property
of the associated CPC is "2.14.0" or later.
world-wide-port- String Required The worldwide port name (WWPN) of the target SCSI device to be
name (1-16) used for this operation, in hexadecimal.
logical-unit-number String Required The hexadecimal logical unit number (LUN) to be used for the SCSI
(1-16) Load.
disk-partition-id Integer Optional The disk-partition-id (also called the boot program selector) to be
(0-30) used for the SCSI Load. The default value is 0.
operating-system- String Optional The operating system specific load parameters to be used for the
specific-load- (1-256) SCSI Load. The default value is an empty string.
parameters
boot-record- String Optional The hexadecimal boot record logical block address to be used for
logical-block- (1-16) the SCSI Load. The default value is hex zeros.
address
force Boolean Optional Whether this operation is permitted when the logical partition is in
"operating" status (true) or not (false). The default is false.
os-ipl-token String Optional Applicable only to z/OS, this parameter requests that this operation
(1-16) only be performed if the provided value matches the current value
of the os-ipl-token property. This ensures that this operation is
targeting the same IPL instance as when the os-ipl-token property
was retrieved. IBM recommends that this parameter only be
provided by callers that fully understand how the os-ipl-token
parameter is managed by z/OS. The value is a string of
hexadecimal characters (0-9, A-F), left justified.

Chapter 11. Core IBM Z resources 753

 Level 04a

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 755. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Description
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. See “Job status and reason codes” on page 755.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Load task.
v Object-access permission to the logical partition's parent CPC object.

HTTP status and reason codes

On success, HTTP status code 202 (Accepted) is returned and the response body is provided as described
in “Response body contents.”

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

HTTP error status 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 ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.

754 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

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

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed.

SCSI Dump
The SCSI Dump operation loads a standalone dump program from a designated SCSI device.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/scsi-dump

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

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

Field name Type Rqd/Opt Description

load-address String Required The hexadecimal address of an I/O device that provides access to
(1-5) the control program to be loaded. The input value is right justified
and padded with zeros to 5 characters.

Valid values are in the range "00000" to "nFFFF" where "n" is the
number of subchannel sets provided by the CPC minus 1. So, for
example, on a CPC that provides 3 subchannel sets, the valid range
is "00000" to "2FFFF".
load-parameter String Optional Some control programs support the use of this property to provide
(1-8) additional control over the outcome of a Load operation. Refer to
the configuration documentation for the control program to be
loaded to see if this parameter is supported and if so, what values
and format is supported. Omitting this field indicates that the value
for this field is to be retrieved from the current IOCDS. Valid
characters are 0-9, A-Z, blank and period. Three additional
characters, (@, $, #) are also allowed when the se-version property
of the associated CPC is "2.14.0" or later.
world-wide-port- String Required The worldwide port name (WWPN) of the target SCSI device to be
name (1-16) used for this operation, in hexadecimal.
logical-unit-number String Required The hexadecimal logical unit number (LUN) to be used for the SCSI
(1-16) Load.
disk-partition-id Integer Optional The disk-partition-id (also called the boot program selector) to be
(0-30) used for the SCSI Load. The default value is 0.

Chapter 11. Core IBM Z resources 755

 Level 04a

Field name Type Rqd/Opt Description

operating-system- String Optional The operating system specific load parameters to be used for the
specific-load- (1-256) SCSI Load. The default value is an empty string.
parameters
boot-record- String Optional The hexadecimal boot record logical block address to be used for
logical-block- (1-16) the SCSI Load. The default value is hex zeros.
address
os-ipl-token String Optional Applicable only to z/OS, this parameter requests that this operation
(1-16) only be performed if the provided value matches the current value
of the os-ipl-token property. This ensures that this operation is
targeting the same IPL instance as when the os-ipl-token property
was retrieved. IBM recommends that this parameter only be
provided by callers that fully understand how the os-ipl-token
parameter is managed by z/OS. The value is a string of
hexadecimal characters (0-9, A-Z), left justified.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description

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

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 757. The job-results field is null when this operation
is successful. When it is partially successful or 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 partially successful or not successful.

Description
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. See “Job status and reason codes” on page 757.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Logical Partition object designated by {logical-partition-id}
v Action/task permission for the Load task.
v Object-access permission to the logical partition's parent CPC object.

756 HMC Web Services API

 Level 04a

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 756.

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 object ID in the URI ({logical-partition-id}) does not designate an existing
Logical Partition object, or the API user does not have object-access
permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous
request.

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

HTTP error status Reason
code code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed.

List Managed Virtual Machines of a Logical Partition

The List Managed Virtual Machines of a Logical Partition operation lists the Managed Virtual Machines
hosted by the z/VM system running in a specified logical partition.

HTTP method and URI

GET /api/logical-partitions/{logical-partition-id}/managed-virtual-machines

In this request, the URI variable {logical-partition-id} is the object ID of the logical partition whose
Managed Virtual Machines are to be listed.

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.

Chapter 11. Core IBM Z resources 757

 Level 04a

Response body contents

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

Field name Type Description

managed-virtual- Array of Array of nested managed-virtual-machine-info objects as described in the
machines managed- next table.
virtual-
machine-
info objects

Each nested managed-virtual-machine-info object contains the following fields:

Field name Type Description

object-uri String/ URI Canonical URI path of the Managed Virtual Machine object is of the form
/api/managed-virtual-machines/cpc{cpc_serial}-{lpar_name}-{mvm_name}
where:
v {cpc_serial} - is the serial number of the CPC containing the logical
partition running the z/VM system containing the Managed Virtual
Machine.
v {lpar_name} - is the name of the logical partition running the z/VM system
containing the Managed Virtual Machine.
v {mvm_name} - is the name of the Managed Virtual Machine.
name String The name of the Managed Virtual Machine.

Description
This operation lists the Managed Virtual Machines hosted by the z/VM system running in the specified
logical partition. Some basic information is provided for each Managed Virtual Machine that is included
in the response.

If the request URI does not identify a Logical Partition object to which the API user has object-access
permission, HTTP status code 404 (Not Found) is returned.

If the name query parameter is specified, the returned list is limited to those Managed Virtual Machines
whose name matches the specified filter pattern. If the name parameter is omitted, no such filtering is
performed.

A Managed Virtual Machine is included in the list only if the API user has object-access permission to
that object. If there is a Managed Virtual Machine 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 Managed Virtual Machines hosted by the z/VM system running in the specified logical
partition or if no Managed Virtual Machines 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 Logical Partition object identified in the request URI.
v Object-access permission to the Managed Virtual Machine objects included in the response body.

758 HMC Web Services API

 Level 04a

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 758.

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.
Table 326. List Managed Virtual Machines of a Logical 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.
404 (Not Found) 1 The request URI does not designate an existing logical partition, or it
designates one for which the API user does not have object-access
permission.

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

Usage Notes
The APIs provide only minimal support for Managed Virtual Machine objects. There is no data model,
and most of the standard operations are not provided. The List Managed Virtual Machines of a Logical
Partition operation can be used to list them and to provide their name and object URI. The provided
support also allows an API client to manage access to them through the Add Permission to User Role
and Remove Permission from User Role operations.

Example HTTP interaction

GET /api/logical-partitions/6ed3d9e6-fc2d-3458-8804-fee9d44369c7/managed-
virtual-machines HTTP/1.1
x-api-session: 6clrf8lcmc4tzcpt02a9iz04h5y91qpc8v6mjdbm1lz4pywd0a

Figure 423. List Managed Virtual Machines of a Logical Partition: Request

Chapter 11. Core IBM Z resources 759

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 14 Dec 2015 19:44:21 GMT
content-type: application/json;charset=UTF-8
content-length: 210
{
"managed-virtual-machines":[
{
"name":"TEST1",
"object-uri":"/api/managed-virtual-machines/cpc0000200E9EB6-VMALT1-TEST1"
},
{
"name":"EREP",
"object-uri":"/api/managed-virtual-machines/cpc0000200E9EB6-VMALT1-EREP"
}
]
}

Figure 424. List Managed Virtual Machines of a Logical Partition: Response

Inventory service data

Information about logical partitions can be optionally included in the inventory data provided by the
Inventory Service.

Inventory entries for the Logical Partition objects are included in the response to the Inventory Service's
Get Inventory operation when the request specifies (explicitly by class, implicitly via a containing
category, or by default) that objects of class "logical-partition" are to be included. An entry for a
particular logical partition is included only if the API user has access permission to that object as
described in the Get Logical Partition Properties operation.

For each Logical Partition object to be included, the inventory response array includes an entry that is a
JSON object with the same contents as is specified in the response body contents section for “Get Logical
Partition Properties” on page 725. That is, the data provided is the same as would be provided if a Get
Logical Partition Properties operation were requested targeting this object.

Reset activation profile

A Reset activation profile is used by a CPC Activate operation to control the activation of a CPC and, if
properly configured with one or more image activation profiles, a set of Logical Partition(s).

An activation profile can only be created or deleted from the Hardware Management Console or the
Support Element.

For information on customizing activation profiles, Support Element (Version 2.12.1 and newer)
information can be found on console help system. For information from earlier versions of the Support
Element, see the Support Element Operations Guide.

Objects of this class are not provided when the CPC is enabled for DPM.

Data model
For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

760 HMC Web Services API

 Level 04a

This element includes the following properties.

Table 327. Reset activation profile: properties
Name Qualifier Type Description
element-uri — String/ The canonical URI path of the Reset Activation Profile object, of the
URI form /api/cpcs/{cpc-id}/reset-activation-profiles/{reset-
activation-profile-name} where {reset-activation-profile-name} is the
value of the name property (Reset Activation Profile name).
parent — String/ The canonical URI path of the associated CPC object.
URI
class — String The class of a Reset Activation Profile object is "reset-activation-
profile".
name — String The activation profile name, which uniquely identifies this profile
(1-16) within the set of activation profiles for the CPC object designated by
{cpc-id}.
description (w) String The reset profile description
(1-50)
iocds-name (w) String (0-2) The Input/Output Configuration Data Set name, in hexadecimal. An
empty string indicates that the currently active IOCDS will be used.
The active IOCDS is the one from the most recent power-on-reset of
the CPC or, if using dynamic I/O configuration, the one last activated.
processor- (w) String Defines whether the processor running time is determined
running-time-type Enum dynamically or set manually for the CPC (see processor-running-time
in this table). One of:
v "system-determined"
v "user-determined"
processor- (w) Integer Amount of continuous time, in milliseconds, for logical processors to
running-time (0-100) perform jobs on shared processors for the CPC, if
processor-running-time-type is set to "user-determined". If
processor-running-time-type is "system-determined", this property's
value will always be returned as 0.
end-timeslice-on- (w) or — if Boolean If true and if processor-running-time-type is set to "user-determined",
wait se-version CPC Logical Partitions lose their share of running time when they
is "2.14.0" enter a wait state. If processor-running-time-type is
or later. "system-determined", this property's value will always be returned as
false.
Note: When the se-version property of the associated CPC is "2.14.0"
or later, this property is not permitted on an Update Reset Activation
Profile Properties operation, and its value is always false.

List Reset Activation Profiles

The List Reset Activation Profiles operation lists the Reset Activation Profiles associated with a
particular CPC.

HTTP method and URI

GET /api/cpcs/{cpc-id}/reset-activation-profiles

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Query parameters:

Chapter 11. Core IBM Z resources 761

 Level 04a

Name Type Rqd/Opt Description

name String Optional A regular expression used to limit returned objects to those that
have a matching name property. If matches are found, the response
will be an array with all objects that match. If no match is found,
the response will be an empty array.

Response body contents

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

Field name Type Description

reset-activation- Array of Array of nested objects (described in the following table).
profiles reset-
actprof-info
objects

Each reset-actprof-info object contains the following fields:

Field name Type Description

element-uri String/URI Canonical URI path of the Reset Activation Profile object.
name String The name of the Reset Activation Profile.

Description
This operation lists the Reset Activation Profiles associated with a particular CPC.

If the name query parameter is specified, the returned list is limited to those Reset Activation Profiles
that have a name property matching the specified filter pattern. If the name parameter is omitted, this
filtering is not done.

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

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-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, 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.
299 A query parameter has an invalid syntax.

762 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
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.
500 (Server Error) 281 An unexpected error occurred during the collection of the list of activation
profiles.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

GET /api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/reset-activation-profiles HTTP/1.1

x-api-session: 5obf0hwsfv1sg9kr5f93cph3zt6o5cptb6lcl538wuyebdyzu4

Figure 425. List Reset Activation Profiles: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 17:16:16 GMT
content-type: application/json;charset=UTF-8
content-length: 372
{
"reset-activation-profiles": [
{
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/reset-activation-profiles/
DEFAULT",
"name": "DEFAULT"
},
{
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/reset-activation-profiles/
POWER_ON_RESET",
"name": "POWER_ON_RESET"
}
]
}

Figure 426. List Reset Activation Profiles: Response

Get Reset Activation Profile Properties

The Get Reset Activation Profile Properties operation retrieves the properties of a single Reset
Activation Profile designated by {reset-activation-profile-name}.

HTTP method and URI

GET /api/cpcs/{cpc-id}/reset-activation-profiles/{reset-activation-profile-name}

URI variables:

Chapter 11. Core IBM Z resources 763

 Level 04a

Variable Description
{cpc-id} Object ID of the target CPC object.
{reset-activation-profile-name} Reset Activation Profile name

Query parameters:

Name Type Rqd/Opt Description

cached-acceptable Boolean Optional Indicates whether cached values are acceptable for the
returned properties. Valid values are true and false. The
default is false.

Response body contents

On successful completion, the response body provides the current values of the properties for the Reset
Activation Profile as defined in the “Data model” on page 760.

Description
The URI path must designate an existing Reset Activation Profile and the API user must have
object-access permission to the CPC. If either of these conditions is not met, status code 404 (Not Found)
is returned.

Some of this object's property values are periodically fetched from the Support Element and cached on
the HMC for quick access by the APIs. Due to the nature of this caching support, the HMC's cached
value of a property may differ from the value on the Support Element at any point in time. While the
HMC strives to keep the cache reasonably current, there are no guarantees about the latency of the cache,
nor is there any latency or other cache information available to the API user. If the cached-acceptable
query parameter is specified as true and a property's value is currently present in the cache, the value
from the cache is returned; otherwise, the current, non-cached value is returned.

On successful execution, HTTP status code 200 (OK) is returned and the response body contains all of the
current properties as defined by the data model for the Reset Activation Profile object.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-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, 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.

764 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
260 The activation profile name in the URI ({reset-activation-profile-name}) does not
designate an existing activation profile.
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.
500 (Server Error) 281 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

GET /api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/reset-activation-profiles/DEFAULT HTTP/1.1

x-api-session: 5obf0hwsfv1sg9kr5f93cph3zt6o5cptb6lcl538wuyebdyzu4

Figure 427. Get Reset Activation Profile Properties: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 17:16:18 GMT
content-type: application/json;charset=UTF-8
content-length: 384
{
"class": "reset-activation-profile",
"description": "This is the default Reset profile.",
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/reset-activation-profiles/
DEFAULT",
"end-timeslice-on-wait": false,
"iocds-name": "a0",
"name": "DEFAULT",
"parent": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"processor-running-time": 0,
"processor-running-time-type": "system-determined"
}

Figure 428. Get Reset Activation Profile Properties: Response

Update Reset Activation Profile Properties

The Update Reset Activation Profile Properties operation updates one or more writable properties of the
Reset Activation Profile designated by {reset-activation-profile-name}.

HTTP method and URI

POST /api/cpcs/{cpc-id}/reset-activation-profiles/{reset-activation-profile-name}

URI variables:

Chapter 11. Core IBM Z resources 765

 Level 04a

Variable Description
{cpc-id} Object ID of the target CPC object.
{reset-activation-profile-name} Reset Activation Profile name

Request body contents

The request body is expected to contain one or more field names representing writable Reset Activation
Profile 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 Reset Activation Profile 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 Reset Activation Profile 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.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission for the Customize/Delete Activation Profiles 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, 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.
19 The request body contains a field whose corresponding data model property
is not writable on this HMC and/or SE version.
300 The provided update values would result in an illegal state. Verify that the
values are both internally consistent and consistent with the current state of
the profile.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
260 The activation profile name in the URI ({reset-activation-profile-name}) does not
designate an existing activation profile.

766 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 2 The operation was rejected by the Support Element (SE), because the SE is
currently performing processing that requires exclusive control of the SE.
Retry the operation at a later time.
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.
500 (Server Error) 281 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Inventory service data

Information about reset activation profiles can be optionally included in the inventory data provided by
the Inventory Service.

Inventory entries for the Reset Activation Profile objects are included in the response to the Inventory
Service's Get Inventory operation when the request specifies (explicitly by class, implicitly via a
containing category, or by default) that objects of class "cpc" are to be included. An entry for a particular
reset activation profile is included only if the API user has access permission to that object as described in
the Get Reset Activation Profile Properties operation.

For each Reset Activation Profile object to be included, the inventory response array includes an entry
that is a JSON object with the same contents as is specified in the response body contents section for “Get
Reset Activation Profile Properties” on page 763. That is, the data provided is the same as would be
provided if a Get Reset Activation Profile Properties operation were requested targeting this object.

Image activation profile

An Image activation profile is used by an Activate operation to activate a logical partition of a previously
activated CPC.

An activation profile can only be created or deleted from the Hardware Management Console or the
Support Element.

For information on customizing activation profiles, Support Element (Version 2.12.1 and newer)
information can be found on console help system. For information from earlier versions of the Support
Element, see the Support Element Operations Guide.

Objects of this class are not provided when the CPC is enabled for DPM.

Data model
For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

This element includes the following properties. Some properties have additional notes associated with
them. Refer to the table notes at the end of this table.

Chapter 11. Core IBM Z resources 767

 Level 04a

Table 328. Image activation profile: properties.

Name Qualifier Type Description
element-uri — String/URI The canonical URI path of the Image Activation Profile
object, of the form /api/cpcs/{cpc-id}/image-activation-
profiles/{image-activation-profile-name} where
{image-activation-profile-name} is the value of the name
property (Image Activation Profile name).
parent — String/URI The canonical URI path of the associated CPC object.
class — String The class of an Image Activation Profile object is
"image-activation-profile".
name — String (0-16) The activation profile name, which uniquely identifies this
profile within the set of activation profiles for the CPC object
designated by {cpc-id}.
description (w) String (0-50) The activation profile description
15
ipl-address (w) String (0-5) The hexadecimal address of an I/O device that provides
access to the control program to be loaded. The input value
will be right justified and padded with zeros to 5 characters.
An empty string indicates that the value for this property is
to be retrieved from the IOCDS used during a subsequent
Load operation.

Valid values are in the range "00000" to "nFFFF" where "n" is

the number of subchannel sets provided by the CPC minus
1. So, for example, on a CPC that provides 3 subchannel sets,
the valid range is "00000" to "2FFFF".
ipl-parameter (w) String (0-8) Some control programs support the use of this property to
provide additional control over the outcome of a Load
operation. Refer to the configuration documentation for the
control program to be loaded to see if this parameter is
supported and if so, what values and format is supported.
An empty string indicates that the value for this property is
to be retrieved from the IOCDS used during a subsequent
Load operation. Valid characters are 0-9, A-Z, blank and
period. Three additional characters, (@, $, #) are also allowed
when the se-version property of the associated CPC is
"2.14.0" or later. On an Update, a non-empty string is left
justified and right padded with blanks to 8 characters.
initial-processing- (w) Integer The relative amount of shared general purpose processor
weight1 resources allocated to the logical partition.

Get:
0 The Image Activation Profile does not represent a logical
partition with at least one shared general purpose
processor.
1-999
Represents the relative amount of shared general
purpose processor resources initially allocated to the
logical partition.

Update:
1-999
Define the relative amount of shared general purpose
processor resources allocated to the logical partition.

768 HMC Web Services API

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
initial-processing- (w) Boolean Whether the initial processing weight for general purpose
weight-capped1, 2, 3 processors is a limit or a target.
True:
Indicates that the initial general purpose processor
processing weight for the logical partition is capped. It
represents the logical partition's maximum share of
general purpose processor resources.
False:
Indicates that the initial general purpose processor
processing weight for the logical partition is not capped.
It represents the share of general purpose processor
resources guaranteed to a logical partition when all
general purpose processor resources are in use.
Otherwise, when excess general purpose processor
resources are available, the logical partition can use
them if necessary.
minimum-processing- (w) Integer The minimum relative amount of shared general purpose
weight1 processor resources allocated to the logical partition.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared
general purpose processor resources allocated to the
logical partition.

Update:
0 There is no minimum value for the processing weight.
1-999
Define the minimum relative amount of shared general
purpose processor resources allocated to the logical
partition. The value must be less than or equal to the
initial-processing-weight property.
maximum-processing- (w) Integer The maximum relative amount of shared general purpose
weight1 processor resources allocated to the logical partition.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared
general purpose processor resources allocated to the
logical partition.

Update:
0 There is no maximum value for the processing weight.
1-999
Defines the maximum relative amount of shared general
purpose processor resources allocated to the logical
partition. Must be greater than or equal to the
initial-processing-weight property.

Chapter 11. Core IBM Z resources 769

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
absolute-general- (w) absolute- The amount of absolute capping applied to the general
purpose-capping22 capping purpose processor.
object
workload-manager- (w) Boolean Whether or not z/OS Workload Manager is allowed to
enabled4 change processing weight related properties.
True:
Indicates that z/OS Workload Manager is allowed to
change processing weight related properties for this
logical partition.
False:
Indicates that z/OS Workload Manager is not allowed to
change processing weight related properties for this
logical partition.
defined-capacity (w) Integer The defined capacity expressed in terms of Millions of
Service Units (MSU)s per hour. MSU is a measure of
processor resource consumption. The amount of MSUs a
logical partition consumes is dependent on the model, the
number of logical processors available to the partition, and
the amount of time the logical partition is dispatched. The
defined capacity value specifies how much capacity the
logical partition is to be managed to by z/OS Workload
Manager for the purpose of software pricing.
0: No defined capacity is specified for this logical partition.
1-nnnn:
Represents the amount of defined capacity specified for
this logical partition
ipl-type (w) String One of:
Enum v "ipltype-standard" - This image activation profile is used
to perform a standard load.
v "ipltype-scsi" - This image activation profile is used to
perform a SCSI load.
v "ipltype-scsidump" - This image activation profile is used
to perform a SCSI dump.
worldwide-port- (w) String (1-16) Worldwide port name of the target SCSI device, used for a
name15 SCSI load or SCSI dump, in hexadecimal.
disk-partition-id (w) Integer The disk partition number (also called the boot program
(0-30) selector) for the activation profile, used for a SCSI load or
SCSI dump.
logical-unit-number15 (w) String (1-16) Logical unit number value for the activation profile, used for
a SCSI load or SCSI dump, in hexadecimal.
boot-record-lba15 (w) String (1-16) Boot record logical block address for the activation profile,
used for a SCSI load or SCSI dump, in hexadecimal.
os-specific-load- (w) String Operating system-specific load parameters for the activation
parameters (0-256) profile, used for a SCSI load or SCSI dump. On an Update,
value is left justified and right padded with blanks to 256
characters.

770 HMC Web Services API

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
initial-aap-processing- (w) Integer The relative amount of shared Application Assist Processor
weight5, 21 (zAAP) processor resources allocated to the logical partition
at activation.

Get:
0 The Image Activation Profile does not represent a logical
partition with at least one shared Application Assist
Processor (zAAP) processor.
1-999
Represents the relative amount of shared Application
Assist Processor (zAAP) processor resources initially
allocated to the logical partition.

Update:
1-999
Define the relative amount of shared Application Assist
Processor (zAAP) processor resources allocated to the
logical partition.
initial-aap-processing- (w) Boolean Whether the initial processing weight for Application Assist
weight-capped3, 5, 6, 21 Processor (zAAP) processors is a limit or a target.
True:
Indicates that the initial Application Assist Processor
(zAAP) processor processing weight for the logical
partition is capped. It represents the logical partition's
maximum share of Application Assist Processor (zAAP)
processor resources, regardless of the availability of
excess Application Assist Processor (zAAP) processor
resources.
False:
Indicates that the initial Application Assist Processor
(zAAP) processor processing weight for the logical
partition is not capped. It represents the share of
Application Assist Processor (zAAP) processor resources
guaranteed to a logical partition when all Application
Assist Processor (zAAP) processor resources are in use.
Otherwise, when excess Application Assist Processor
(zAAP) processor resources are available, the logical
partition can use them if necessary.

Chapter 11. Core IBM Z resources 771

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
minimum-aap- (w) Integer The minimum relative amount of shared Application Assist
processing-weight5, 21 Processor (zAAP) processor resources allocated to the logical
partition.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared
Application Assist Processor (zAAP) processor resources
initially allocated to the logical partition.

Update:
0 No minimum value for the processing weight.
1-999
Define the minimum relative amount of shared
Application Assist Processor (zAAP) processor resources
allocated to the logical partition.
maximum-aap- (w) Integer The maximum relative amount of shared Application Assist
processing-weight5, 21 Processor (zAAP) processor resources allocated to the logical
partition.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared
Application Assist Processor (zAAP) processor resources
initially allocated to the logical partition.

Update:
0 There is no maximum value for the processing weight.
1-999
Define the maximum relative amount of shared
Application Assist Processor (zAAP) processor resources
allocated to the logical partition.
absolute-aap- (w) absolute- The amount of absolute capping applied to the Application
capping21, 22 capping Assist Processor (zAAP).
object

772 HMC Web Services API

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
initial-ifl-processing- (w) Integer The relative amount of shared Integrated Facility for Linux
weight7 (IFL) processor resources allocated to the logical partition at
activation.

Get:
0 The Image Activation Profile does not represent a logical
partition with at least one shared Integrated Facility for
Linux (IFL) processor.
1-999
Represents the relative amount of shared Integrated
Facility for Linux (IFL) processor resources initially
allocated to the logical partition.

Update:
1-999
Define the relative amount of shared Integrated Facility
for Linux (IFL) processor resources allocated to the
logical partition.
initial-ifl-processing- (w) Boolean Whether the initial processing weight for Integrated Facility
weight-capped3, 7, 8 for Linux (IFL) processors is a limit or a target.
True:
Indicates that the initial Integrated Facility for Linux
(IFL) processor processing weight for the logical
partition is capped. It represents the logical partition's
maximum share of Integrated Facility for Linux (IFL)
processor resources, regardless of the availability of
excess Integrated Facility for Linux (IFL) processor
resources.
False:
Indicates that the initial Integrated Facility for Linux
(IFL) processor processing weight for the logical
partition is not capped. It represents the share of
Integrated Facility for Linux (IFL) processor resources
guaranteed to a logical partition when all Integrated
Facility for Linux (IFL) processor resources are in use.
Otherwise, when excess Integrated Facility for Linux
(IFL) processor resources are available, the logical
partition can use them if necessary.

Chapter 11. Core IBM Z resources 773

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
minimum-ifl- (w) Integer The minimum relative amount of shared Integrated Facility
processing-weight7 for Linux (IFL) processor resources allocated to the logical
partition.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared
Integrated Facility for Linux (IFL) processor resources
initially allocated to the logical partition.

Update:
0 There is no minimum value for the processing weight.
1-999
Define the minimum relative amount of shared
Integrated Facility for Linux (IFL) processor resources
allocated to the logical partition.
maximum-ifl- (w) Integer The maximum relative amount of shared Integrated Facility
processing-weight7 for Linux (IFL) processor resources allocated to the logical
partition.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared
Integrated Facility for Linux (IFL) processor resources
initially allocated to the logical partition.

Update:
0 There is no maximum value for the processing weight.
1-999
Define the maximum relative amount of shared
Integrated Facility for Linux (IFL) processor resources
allocated to the logical partition.
absolute-ifl-capping22 (w) absolute- The amount of absolute capping applied to the Integrated
capping Facility for Linux (IFL) processor.
object

774 HMC Web Services API

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
initial-internal-cf- (w) Integer The relative amount of shared Internal Coupling Facility
processing-weight9 (ICF) processor resources allocated to the logical partition at
activation.

Get:
0 The Image Activation Profile does not represent a logical
partition with at least one shared Internal Coupling
Facility (ICF) processor.
1-999
Represents the relative amount of shared Internal
Coupling Facility (ICF) processor resources initially
allocated to the logical partition.

Update:
1-999
Define the relative amount of shared Internal Coupling
Facility (ICF) processor resources allocated to the logical
partition.
initial-internal-cf- (w) Boolean Indicates whether the initial processing weight for Internal
processing-weight- Coupling Facility (ICF) processors is a limit or a target.
capped3, 9, 10
True:
Indicates that the initial Internal Coupling Facility (ICF)
processor processing weight for the Image associated
with the logical partition is capped. It represents the
logical partition's maximum share of Internal Coupling
Facility (ICF) processor resources, regardless of the
availability of excess Internal Coupling Facility (ICF)
processor resources.
False:
Indicates that the initial Internal Coupling Facility (ICF)
processor processing weight for the logical partition is
not capped. It represents the share of Internal Coupling
Facility (ICF) processor resources guaranteed to a logical
partition when all Internal Coupling Facility (ICF)
processor resources are in use. Otherwise, when excess
Internal Coupling Facility (ICF) processor resources are
available, the logical partition can use them if necessary.
minimum-internal-cf- (w) Integer The minimum relative amount of shared Internal Coupling
processing-weight9 Facility (ICF) processor resources allocated to the logical
partition at activation.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared
Internal Coupling Facility (ICF) processor resources
initially allocated to the logical partition.

Update:
1-999
Define the minimum relative amount of shared Internal
Coupling Facility (ICF) processor resources allocated to
the logical partition.

Chapter 11. Core IBM Z resources 775

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
maximum-internal-cf- (w) Integer The maximum relative amount of shared Internal Coupling
processing-weight9 Facility (ICF) processor resources allocated to the logical
partition.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared
Internal Coupling Facility (ICF) processor resources
initially allocated to the logical partition.

Update:
0 There is no maximum value for the processing weight.
1-999
Define the maximum relative amount of shared Internal
Coupling Facility (ICF) processor resources allocated to
the logical partition.
absolute-icf-capping22 (w) absolute- The amount of absolute capping applied to the Internal
capping Coupling Facility (ICF) processor.
object
| initial-cbp-processing- (w) Integer The relative amount of shared Container Based Processor
| weight23, 24 (CBP) resources allocated to the logical partition at
| activation.

| Get:
| 0 The Image Activation Profile does not represent a logical
| partition with at least one shared Container Based
| Processor (CBP).
| 1-999
| Represents the relative amount of shared Container
| Based Processor (CBP) resources initially allocated to the
| logical partition.

| Update:
| 1-999
| Defines the relative amount of shared Container Based
| Processor (CBP) resources allocated to the logical
| partition.

776 HMC Web Services API

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
| initial-cbp-processing- (w) Boolean Whether the initial processing weight for Container Based
| weight-capped23, 24, 25 Processors (CBP) is a limit or a target.
| True:
| Indicates that the initial Container Based Processor's
| (CBP) processing weight for the logical partition is
| capped. It represents the logical partition's maximum
| share of Container Based Processor (CBP) resources,
| regardless of the availability of excess Container Based
| Processor (CBP) resources.
| False:
| Indicates that the initial Container Based Processor's
| (CBP) processing weight for the logical partition is not
| capped. It represents the share of Container Based
| Processor (CBP) resources guaranteed to a logical
| partition when all Container Based Processor (CBP)
| resources are in use. Otherwise, when excess Container
| Based Processor (CBP) resources are available, the
| logical partition can use them if necessary.
| minimum-cbp- (w) Integer The minimum relative amount of shared Container Based
| processing-weight23, 24 Processor (CBP) resources allocated to the logical partition.

| Get:
| 0 There is no minimum value for the processing weight.
| 1-999
| Represents the minimum relative amount of shared
| Container Based Processor (CBP) resources initially
| allocated to the logical partition.

| Update:
| 0 There is no minimum value for the processing weight.
| 1-999
| Defines the minimum relative amount of shared
| Container Based Processor (CBP) resources allocated to
| the logical partition.
| maximum-cbp- (w) Integer The maximum relative amount of shared Container Based
| processing-weight23, 24 Processor (CBP) resources allocated to the logical partition.

| Get:
| 0 There is no maximum value for the processing weight.
| 1-999
| Represents the maximum relative amount of shared
| Container Based Processor (CBP) resources initially
| allocated to the logical partition.

| Update:
| 0 There is no maximum value for the processing weight.
| 1-999
| Defines the maximum relative amount of shared
| Container Based Processor (CBP) resources allocated to
| the logical partition.

Chapter 11. Core IBM Z resources 777

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
| absolute-cbp- (w) absolute- The amount of absolute capping applied to the Container
| capping22, 23 capping- Based Processor (CBP).
| object
initial-ziip- (w) Integer The relative amount of shared z Integrated Information
processing-weight11 Processors (zIIP) processor resources allocated to the logical
partition at activation.

Get:
0 The Image Activation Profile does not represent a logical
partition with at least one shared z Integrated
Information Processors (zIIP) processor.
1-999
Represents the relative amount of shared z Integrated
Information Processors (zIIP) processor resources
initially allocated to the logical partition.

Update:
1-999
Define the relative amount of shared z Integrated
Information Processors (zIIP) processor resources
allocated to the logical partition.
initial-ziip- (w) Boolean Whether the initial processing weight for z Integrated
processing-weight- Information Processors (zIIP) processors is a limit or a target.
capped3, 11, 12
True:
Indicates that the initial z Integrated Information
Processors (zIIP) processor processing weight for the
logical partition is capped. It represents the logical
partition's maximum share of z Integrated Information
Processors (zIIP) processor resources, regardless of the
availability of excess z Integrated Information Processors
(zIIP) processor resources.
False:
Indicates that the initial z Integrated Information
Processors (zIIP) processor processing weight for the
logical partition is not capped. It represents the share of
z Integrated Information Processors (zIIP) processor
resources guaranteed to a logical partition when all z
Integrated Information Processors (zIIP) processor
resources are in use. Otherwise, when excess z
Integrated Information Processors (zIIP) processor
resources are available, the logical partition can use
them if necessary.

778 HMC Web Services API

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
minimum-ziip- (w) Integer The minimum relative amount of shared z Integrated
processing-weight11 Information Processors (zIIP) processor resources allocated to
the logical partition.

Get:
0 There is no minimum value for the processing weight.
1-999
Represents the minimum relative amount of shared z
Integrated Information Processors (zIIP) processor
resources initially allocated to the logical partition.

Update:
0 There is no minimum value for the processing weight.
1-999
Define the minimum relative amount of shared z
Integrated Information Processors (zIIP) processor
resources allocated to the logical partition.
maximum-ziip- (w) Integer The maximum relative amount of shared z Integrated
processing-weight11 Information Processors (zIIP) processor resources allocated to
the logical partition.

Get:
0 There is no maximum value for the processing weight.
1-999
Represents the maximum relative amount of shared z
Integrated Information Processors (zIIP) processor
resources initially allocated to the logical partition.

Update:
0 There is no maximum value for the processing weight.
1-999
Define the maximum relative amount of shared z
Integrated Information Processors (zIIP) processor
resources allocated to the logical partition.
absolute-ziip- (w) absolute- The amount of absolute capping applied to the z Integrated
capping22 capping Information Processors (zIIP) processor.
object
group-profile-uri (w) String/ URI The canonical URI of the Group profile to be used for the
logical partition activated by this profile, which provides the
group capacity value. On a Get, a null object is returned if
no Group profile is associated with this activation profile. On
an Update, a null object indicates that no Group profile is to
be associated with this activation profile.
load-at-activation (w) Boolean If true, the logical partition will be loaded at the end of the
activation.
central-storage (w) Integer Defines the amount of central storage, measured in
megabytes (MB), to be allocated for the logical partition's
exclusive use at activation. This value must be a multiple of
the storage granularity value.

Chapter 11. Core IBM Z resources 779

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
reserved-central- (w) Integer Defines the amount of central storage, measured in
storage megabytes (MB), dynamically reconfigurable to the logical
partition after activation. This value must be a multiple of
the storage granularity value.
expanded-storage (w) Integer Defines the amount of expanded storage, measured in
megabytes (MB), to be allocated for the logical partition's
exclusive use at activation. This value must be a multiple of
the storage granularity value.
reserved-expanded- (w) Integer Defines the amount of expanded storage, measured in
storage megabytes (MB), dynamically reconfigurable to the logical
partition after activation. This value must be a multiple of
the storage granularity value.
initial-vfm-storage18 (w) Long Defines the amount of Virtual Flash Memory (VFM) storage,
measured in gigabytes (GB), to be allocated for the logical
partition's exclusive use at activation. The valid range is 0 to
the value indicated on the storage-vfm-total property in a
multiple of the value indicated on the storage-vfm-
increment-size property for the associated CPC. This value
must not be greater than the value specified in the
maximum-vfm-storage property in this Image Activation
Profile.
maximum-vfm- (w) Long Defines the maximum amount of VFM storage, measured in
storage18 gigabytes (GB), that can be allocated to the logical partition
while it is running. The valid range is 0 to the value
indicated on the storage-vfm-total property in a multiple of
the value indicated on the storage-vfm-increment-size
property for the associated CPC. This value must not be
smaller than the value specified in the initial-vfm-storage
property in this Image Activation Profile.
processor-usage (w) String Defines how processors are allocated to the logical partition.
Enum One of the following values:
v "dedicated" - all processor types in the logical partition are
to be exclusively available to this specific logical partition.
v "shared" - all processors types in the logical partition are
to be shareable across logical partitions.
number-dedicated- (w) Integer Defines the number of general purpose processors to be
general-purpose- allocated for the logical partition's exclusive use at activation.
processors13
number-reserved- (w) Integer Defines the number of dedicated general purpose processors
dedicated-general- to be reserved for the logical partition, which can be
purpose-processors13 dynamically configured after activation.
number-dedicated- (w) Integer Defines the number of Application Assist Processor (zAAP)
aap-processors13, 21 processors to be allocated for the logical partition's exclusive
use at activation.
number-reserved- (w) Integer Defines the number of dedicated Application Assist
dedicated-aap- Processor (zAAP) processors to be reserved for the logical
processors13, 21 partition, which can be dynamically configured after
activation.
number-dedicated-ifl- (w) Integer Defines the number of Integrated Facility for Linux (IFL)
processors13 processors to be allocated for the logical partition's exclusive
use at activation.

780 HMC Web Services API

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
number-reserved- (w) Integer Defines the number of dedicated Integrated Facility for
dedicated-ifl- Linux (IFL) processors to be reserved for the logical
processors13 partition, which can be dynamically configured after
activation.
number-dedicated-icf- (w) Integer Defines the number of Integrated Coupling Facility (ICF)
processors13 processors to be allocated for the logical partition's exclusive
use at activation.
number-reserved- (w) Integer Defines the number of dedicated Integrated Coupling
dedicated-icf- Facility (ICF) processors to be reserved for the logical
processors13 partition, which can be dynamically configured after
activation.
| number-dedicated- (w) Integer Defines the number of Container Based Processors (CBP) to
| cbp-processors13, 23 be allocated for the local partition's exclusive use at
| activation.
| number-reserved- (w) Integer Defines the number of dedicated Container Based Processors
| dedicated-cbp- (CBP) to be reserved for the logical partition, which can be
| processors13, 23 dynamically configured after activation.
number-dedicated- (w) Integer Defines the number of z Integrated Information Processors
ziip-processors13 (zIIP) processors to be allocated for the logical partition's
exclusive use at activation.
number-reserved- (w) Integer Defines the number of dedicated z Integrated Information
dedicated-ziip- Processors (zIIP) processors to be reserved for the logical
processors13 partition, which can be dynamically configured after
activation.
number-shared- (w) Integer Defines the number of shared general purpose processors to
general-purpose- be allocated for the logical partition at activation.
processors14
number-reserved- (w) Integer Defines the number of shared general purpose processors to
shared-general- be reserved for the logical partition, which can be
purpose-processors14 dynamically configured after activation.
number-shared-aap- (w) Integer Defines the number of shared Application Assist Processor
processors14, 21 (zAAP) processors to be allocated for the logical partition at
activation.
number-reserved- (w) Integer Defines the number of shared Application Assist Processor
shared-aap- (zAAP) processors to be reserved for the logical partition,
processors14, 21 which can be dynamically configured after activation.
number-shared-ifl- (w) Integer Defines the number of shared Integrated Facility for Linux
processors14 (IFL) processors to be allocated for the logical partition at
activation.
number-reserved- (w) Integer Defines the number of shared Integrated Facility for Linux
shared-ifl-processors14 (IFL) processors to be reserved for the logical partition,
which can be dynamically configured after activation.
number-shared-icf- (w) Integer Defines the number of shared Integrated Coupling Facility
processors14 (ICF) processors to be allocated for the logical partition at
activation.
number-reserved- (w) Integer Defines the number of shared Integrated Coupling Facility
shared-icf-processors14 (ICF) processors to be reserved for the logical partition,
which can be dynamically configured after activation.
| number-shared-cbp- (w) Integer Defines the number of shared Container Based Processors
| processors14, 23 (CBP) to be allocated for the logical partition at activation.

Chapter 11. Core IBM Z resources 781

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
| number-reserved- (w) Integer Defines the number of shared Container Based Processors
| shared-cbp- (CBP) to be reserved for the logical partition, which can be
| processors14, 23 dynamically configured after activation.
number-shared-ziip- (w) Integer Defines the number of shared z Integrated Information
processors14 Processors (zIIP) processors to be allocated for the logical
partition at activation.
number-reserved- (w) Integer Defines the number of shared z Integrated Information
shared-ziip- Processors (zIIP) processors to be reserved for the logical
processors14 partition, which can be dynamically configured after
activation.
basic-cpu-counter- (w) Boolean If true, the basic CPU counter facility for the logical partition
authorization-control is enabled.
problem-state-cpu- (w) Boolean If true, the problem state CPU counter facility for the logical
counter-authorization- partition is enabled.
control
crypto-activity-cpu- (w) Boolean If true, the crypto activity CPU counter facility for the logical
counter-authorization- partition is enabled.
control
extended-cpu-counter- (w) Boolean If true, the extended CPU counter facility for the logical
authorization-control partition is enabled.
coprocessor-cpu- (w) Boolean If true, the coprocessor group CPU counter facility for the
counter-authorization- logical partition is enabled.
control
basic-cpu-sampling- (w) Boolean If true, the basic CPU sampling facility for the logical
authorization-control partition is enabled.
permit-aes-key- (w) Boolean If true, importing of AES keys for the logical partition is
import-functions enabled.
permit-des-key- (w) Boolean If true, importing of DES keys for the logical partition is
import-functions enabled.
liccc-validation- (w) Boolean If true, ensure that the image profile data conforms to the
enabled current maximum Licensed Internal Code Configuration
Control (LICCC) configuration.
global-performance- (w) Boolean If true, the logical partition can be used to view the
data-authorization- processing unit activity data for all other logical partitions
control activated on the same CPC.
io-configuration- (w) Boolean If true, the logical partition can be used to read and write
authorization-control any Input/Output Configuration Data Set (IOCDS) in the
configuration.
cross-partition- — Boolean If true, the logical partition can be used to issue control
authority- program instructions that reset or deactivate other logical
authorization-control partitions.
logical-partition- (w) Boolean If true, reconfigurable channel paths assigned to the logical
isolation-control partition are reserved for its exclusive use.

782 HMC Web Services API

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
operating-mode (w) String The operating mode for the logical partition:
Enum v "general"
v "esa390"
v "esa390-tpf"
v "coupling-facility"
v "linux-only"
v "zvm"
v "zaware"
v "ssc"
For an Update operation, "ssc" is only valid when the
associated Support Element is at version 2.13.1 or later and
"zaware" is only valid when the associated Support Element
is at version 2.13.0 or earlier.

For an Update operation, "general" is only valid when the

associated Support Element is at version 2.14.0 or later and
"esa390" or "esa390-tpf" is only valid when the associated
Support Element is at version 2.13.1 or earlier.
clock-type (w) String One of:
Enum v "standard" – Set the logical partition's clock is set to the
same time set for the CPC's time source.
v "lpar" - Set the logical partition's clock using an offset
from the External Time Source's time of day.
time-offset-days (w) Integer The number of days the logical partition's clock is to be
(0-999) offset from the External Time Source's time of day.
time-offset-hours (w) Integer The number of hours the logical partition's clock is to be
(0-23) offset from the External Time Source's time of day.
time-offset-minutes (w) Integer The number of minutes the logical partition”s clock is to be
Enum offset from the External Time Source's time of day. Allowable
values are 0, 15, 30 or 45.
time-offset-increase- (w) String One of:
decrease Enum v "increase" – Set the logical partition's clock ahead of the
External Time Source's time of day.
v "decrease" – Set the logical partition's clock back from the
External Time Source's time of day.
zaware-host-name19 (w) String (1-64) The IBM zAware host name. Valid characters are:
a-z,A-Z,0-9, period(.), minus(-) and colon(:)
zaware-master- (w) String (1-32) The IBM zAware master userid. Valid characters are:
userid19 a-z,A-Z,0-9, period(.), minus(-) and underscore (_)
zaware-master-pw19 (wo) String The IBM zAware master password. Valid characters are:
(8-256) a-z,A-Z,0-9 and !@#$%^&*()_+{}|<>?-=

This property is not returned on a Get request, it can only be

specified on an Update request.
zaware-network-info19 (w) Array of The set of networks available to IBM zAware. A minimum of
zaware- 1 network and a maximum of 100 networks are permitted.
network
objects On an Update request, this property fully replaces the
existing set.

Chapter 11. Core IBM Z resources 783

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description
16
zaware-gateway-info (w) ip-info The default gateway IP address information. A null object
object indicates no default gateway IP address is specified.
zaware-dns-info16 (w) Array of The DNS IP address information. A minimum of 0 entries
ip-info and a maximum of 2 entries are permitted.
objects
On an Update request, this property fully replaces the
existing set.
ssc-host-name20 (w) String (1-64) The Secure Service Container host name. Valid characters
are: a-z, A-Z, 0-9, period(.), minus(-) and colon(:).
ssc-master-userid20 (w) String (1-32) The Secure Service Container master user ID. Valid
characters are: a-z, A-Z, 0-9, period(.), minus(-) and
underscore(_).
ssc-master-pw20 (wo) String The Secure Service Container master password. Valid
(8-256) characters are: a-z, A-Z, 0-9, and !@#$%^&*()_+{}|<>?-=.

This property is not returned on a Get request; it can be

specified on an Update request.
ssc-network-info20 (w) Array of The set of networks available to the Secure Service
ssc-network Container. A minimum of 1 network and a maximum of 100
objects networks are permitted.

On an Update request, this property fully replaces the

existing set.
ssc-gateway-info17 (w) ip-info The IPv4 default gateway IP address information for the
objects Secure Service Container. A null object indicates no IPv4
default gateway IP address is specified.
ssc-gateway-ipv6- (w) ip-info The IPv6 default gateway IP address information for the
info17, 18 objects Secure Service Container. A null object indicates no IPv6
default gateway IP address is specified.
ssc-dns-info17 (w) Array of The DNS IP address information for the Secure Service
ip-info Container. A minimum of 0 entries and a maximum of 2
objects entries are permitted.

On an Update request, this property fully replaces the

existing set.
ssc-boot-selection20 (w) String Indicates whether to run the Secure Service Container
Enum 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" - Reload the most recently installed Secure
Service Container appliance and resume its execution from
where it was when the image was deactivated.

784 HMC Web Services API

 Level 04a

Table 328. Image activation profile: properties (continued).

Name Qualifier Type Description

Notes:
1. An Update of this property is only valid for an Image Activation Profile that represents a logical partition with
at least one shared general purpose processor.
2. The value returned for a Get request is always false when the Image Activation Profile does not represent a
logical partition or the Image Activation Profile does not represent a logical partition with at least one shared
general purpose processor.
3. This property and the workload-manager-enabled property are mutually exclusive and cannot both be enabled
at the same time. Therefore in order to enable this property it might be necessary to first disable the
workload-manager-enabled property.
4. This property and the various capping properties are mutually exclusive and cannot be enabled at the same
time. Therefore in order to enable this property it may be necessary to first disable any capping property that is
currently enabled.
5. An Update of this property is only valid for an Image Activation Profile that represents a logical partition with
at least one shared Application Assist Processor (zAAP) processor.
6. The value returned for a Get request is always false when the Image Activation Profile does not represent a
logical partition with at least one shared Application Assist Processor (zAAP) processor.
7. An Update of this property is only valid for an Image Activation Profile that represents a logical partition with
at least one shared Integrated Facility for Linux (IFL) processor.
8. The value returned for a Get request is always false when the Image Activation Profile does not represent a
logical partition with at least one shared Integrated Facility for Linux (IFL) processor.
9. An Update of this property is only valid for an Image Activation Profile that represents a logical partition with
at least one shared Internal Coupling Facility (ICF) processor.
10. The value returned for a Get request is always false when the Image Activation Profile does not represent a
logical partition with at least one shared Internal Coupling Facility (ICF) processor.
11. An Update of this property is only valid for an Image Activation Profile that represents a logical partition with
at least one shared z Integrated Information Processors (zIIP) processor.
12. The value returned for a GET request is always false when the Image Activation profile does not represent a
logical partition with at least one shared z Integrated Information Processors (zIIP) processor.
13. The value of this property is a null object if the processor-usage property is "shared"
14. The value of this property is a null object if the processor-usage property is "dedicated"
15. An Update request accepts any mixture of [a-f,A-F,0-9], however the original string value is not saved and a
subsequent Get request may not return the exact same set of lower/upper case letters.
16. On a Get request, this property is returned only when operating-mode is "zaware". On an Update request, this
property can be specified only when operating-mode is "zaware".
17. On a Get request, this property is returned only when operating-mode is "ssc". On an Update request, this
property can be specified only when operating-mode is "ssc".
18. On a Get request, this property is returned only when the SE version is 2.14.0 or later. On an Update request,
this property is allowed only when the SE version is 2.14.0 or later.
19. On an Update request, this property can be specified only when operating-mode is set to "zaware" in the same
request.
20. On an Update request, this property can be specified only when operating-mode is set to "ssc" in the same
request.
21. On a Get request, this property is not returned when the SE version is 2.13.0 or later. On an Update request,
this property is ignored when the SE version is 2.13.0 or later.
22. On a Get request, this property is not returned for a profile whose processor-usage property is "dedicated". On
an Update request, this property is not allowed for a profile whose processor-usage property is "dedicated".
| 23. On a Get request, this property is returned only when the associated SE version is 2.14.0 with the suitable MCL
| bundle, or a later SE version. On an Update request, this property can be included in the request body only
| when the associated SE version is 2.14.0 with the suitable MCL bundle, or a later SE version.
| 24. An Update of this property is only valid for an Image Activation Profile that represents a logical partition with
| at least one Container Based Processor (CBP).
| 25. The value returned for a Get request is always false when the Image Activation Profile does not represent a
| logical partition with at least one Container Based Processor (CBP).

Chapter 11. Core IBM Z resources 785

 Level 04a

List Image Activation Profiles

The List Image Activation Profiles operation lists the Image Activation Profiles for the associated CPC
object.

HTTP method and URI

GET /api/cpcs/{cpc-id}/image-activation-profiles

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

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. If matches are found, the response
will be an array with all objects that match. If no match is found,
the response will be an empty array.

Response body contents

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

Field name Type Description

image-activation- Array of Array of nested objects (described in the following table).
profiles image-
actprof-info
objects

Each image-actprof-info object contains the following fields:

Field name Type Description

element-uri String/URI Canonical URI path of the Image Activation Profile object.
name String The name of the Image Activation Profile.

Description
This operation lists the Image Activation Profiles associated with a particular CPC.

If the name query parameter is specified, the returned list is limited to those Image Activation Profiles
that have a name property matching the specified filter pattern. If the name parameter is omitted, this
filtering is not done.

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

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-id}, or object-access permission to the
same named logical partition of that CPC, for each object to be included in the response.

786 HMC Web Services API

 Level 04a

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 786.

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.
299 A query parameter has an invalid syntax.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the CPC or any of
its logical partitions.
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.
500 (Server Error) 281 An unexpected error occurred during the collection of the list of activation
profiles.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

GET /api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/image-activation-profiles HTTP/1.1

x-api-session: 5obf0hwsfv1sg9kr5f93cph3zt6o5cptb6lcl538wuyebdyzu4

Figure 429. List Image Activation Profiles: Request

Chapter 11. Core IBM Z resources 787

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 17:16:18 GMT
content-type: application/json;charset=UTF-8
content-length: 506
{
"image-activation-profiles": [
{
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/image-activation-profiles/
APIVM1",
"name": "APIVM1"
},
{
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/image-activation-profiles/
DEFAULT",
"name": "DEFAULT"
},
{
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/image-activation-profiles/
ZOS1",
"name": "ZOS1"
}
]
}

Figure 430. List Image Activation Profiles: Response

Usage Note
An API user without object-access permission to the CPC cannot obtain the CPC's URI via the List CPC
Objects operation. Instead, such a user may use either the List Permitted Logical Partitions operation or
the Get Inventory operation to obtain the properties of a Logical Partition object to which the user has
object-access permission. The parent CPC's URI is included in the response body of those operations.

Get Image Activation Profile Properties

The Get Image Activation Profile Properties operation retrieves the properties of a single Image
Activation Profile designated by {image-activation-profile-name}.

HTTP method and URI

GET /api/cpcs/{cpc-id}/image-activation-profiles/{image-activation-profile-name}

URI variables:

Variable Description
{cpc-id} Object ID of the target CPC object.
{image-activation-profile- Image Activation Profile name
name}

Query parameters:

Name Type Rqd/Opt Description

cached-acceptable Boolean Optional Indicates whether cached values are acceptable for the
returned properties. Valid values are true and false. The
default is false.

788 HMC Web Services API

 Level 04a

Response body contents

On successful completion, the response body provides the current values of the properties for the Image
Activation Profile as defined in the “Data model” on page 767.

Description
The URI path must designate an existing Image Activation Profile and the API user must have
object-access permission to the associated CPC object. If either of these conditions is not met, HTTP status
code 404 (Not Found) is returned.

Some of this object's property values are periodically fetched from the Support Element and cached on
the HMC for quick access by the APIs. Due to the nature of this caching support, the HMC's cached
value of a property may differ from the value on the Support Element at any point in time. While the
HMC strives to keep the cache reasonably current, there are no guarantees about the latency of the cache,
nor is there any latency or other cache information available to the API user. If the cached-acceptable
query parameter is specified as true and a property's value is currently present in the cache, the value
from the cache is returned; otherwise, the current, non-cached value is returned.

On successful execution, HTTP status code 200 (OK) is returned and the response body contains all of the
current properties as defined by the data model for the Image Activation Profile object.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-id}, or object-access permission to the
same named Logical Partition of that CPC.

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, 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 object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the CPC or any of
its logical partitions.
260 The activation profile name in the URI ({image-activation-profile-name}) does
not designate an existing activation profile.
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.
500 (Server Error) 281 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the SE needed to perform the requested operation.

Chapter 11. Core IBM Z resources 789

 Level 04a

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/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/image-activation-profiles/ZOS HTTP/1.1

x-api-session: 5obf0hwsfv1sg9kr5f93cph3zt6o5cptb6lcl538wuyebdyzu4

Figure 431. Get Image Activation Profile Properties: Request

790 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 17:16:18 GMT
content-type: application/json;charset=UTF-8
content-length: 3352
{
"basic-cpu-counter-authorization-control": false,
"basic-cpu-sampling-authorization-control": false,
"boot-record-lba": "0",
"central-storage": 4096,
"class": "image-activation-profile",
"clock-type": "standard",
"coprocessor-cpu-counter-authorization-control": false,
"cross-partition-authority-authorization-control": false,
"crypto-activity-cpu-counter-authorization-control": false,
"defined-capacity": 0,
"description": "This is the ZOS Image profile.",
"disk-partition-id": 0,
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/image-activation-profiles/ZOS",
"expanded-storage": 0,
"extended-cpu-counter-authorization-control": false,
"global-performance-data-authorization-control": true,
"group-profile-uri": null,
"initial-aap-processing-weight": 0,
"initial-aap-processing-weight-capped": false,
| "initial-cbp-processing-weight": 0,
| "initial-cbp-processing-weight-capped": false,
"initial-ifl-processing-weight": 0,
"initial-ifl-processing-weight-capped": false,
"initial-internal-cf-processing-weight": 0,
"initial-internal-cf-processing-weight-capped": false,
"initial-processing-weight": 44,
"initial-processing-weight-capped": false,
"initial-vfm-storage": 64,
"initial-ziip-processing-weight": 0,
"initial-ziip-processing-weight-capped": false,
"io-configuration-authorization-control": true,
"ipl-address": "00000",
"ipl-parameter": " ",
"ipl-type": "ipltype-standard",
"liccc-validation-enabled": true,
"load-at-activation": false,
"logical-partition-isolation-control": false,
"logical-unit-number": "0",
"maximum-aap-processing-weight": 0,
| "maximum-cbp-processing-weight": 0,
"maximum-ifl-processing-weight": 0,
"maximum-internal-cf-processing-weight": 0,
"maximum-processing-weight": 44,
"maximum-vfm-storage": 512,
"absolute-aap-capping": {"type": "processors", "value": 67.95},
| "absolute-cbp-capping": {"type": "none"},
"absolute-icf-capping": {"type": "none"},
"absolute-ifl-capping": {"type": "none"},
"absolute-general-purpose-capping": {"type": "processors", "value": 3.03},
"absolute-ziip-capping": {"type": "processors", "value": 95.95},

Figure 432. Get Image Activation Profile Properties: Response (Part 1)

Chapter 11. Core IBM Z resources 791

 Level 04a

"maximum-ziip-processing-weight": 0,
"minimum-aap-processing-weight": 0,
| "minimum-cbp-processing-weight": 0,
"minimum-ifl-processing-weight": 0,
"minimum-internal-cf-processing-weight": 0,
"minimum-processing-weight": 44,
"minimum-ziip-processing-weight": 0,
"name": "ZOS",
"number-dedicated-aap-processors": null,
| "number-dedicated-cbp-processors": null,
"number-dedicated-general-purpose-processors": null,
"number-dedicated-icf-processors": null,
"number-dedicated-ifl-processors": null,
"number-dedicated-ziip-processors": null,
"number-reserved-dedicated-aap-processors": null,
| "number-reserved-dedicated-cbp-processors": null,
"number-reserved-dedicated-general-purpose-processors": null,
"number-reserved-dedicated-icf-processors": null,
"number-reserved-dedicated-ifl-processors": null,
"number-reserved-dedicated-ziip-processors": null,
"number-reserved-shared-aap-processors": 0,
| "number-reserved-shared-cbp-processors": 0,
"number-reserved-shared-general-purpose-processors": 0,
"number-reserved-shared-icf-processors": 0,
"number-reserved-shared-ifl-processors": 0,
"number-reserved-shared-ziip-processors": 0,
"number-shared-aap-processors": 0,
| "number-shared-cbp-processors": 0,
"number-shared-general-purpose-processors": 1,
"number-shared-icf-processors": 0,
"number-shared-ifl-processors": 0,
"number-shared-ziip-processors": 0,
"operating-mode": "esa390",
"os-specific-load-parameters": " ",
"parent": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"permit-aes-key-import-functions": true,
"permit-des-key-import-functions": true,
"problem-state-cpu-counter-authorization-control": false,
"processor-usage": "shared",
"reserved-central-storage": 0,
"reserved-expanded-storage": 0,
"time-offset-days": 0,
"time-offset-hours": 0,
"time-offset-increase-decrease": "decrease",
"time-offset-minutes": 0,
"workload-manager-enabled": false,
"worldwide-port-name": "0"
}

Figure 433. Get Image Activation Profile Properties: Response (Part 2)

Usage Note
An API user without object-access permission to the CPC cannot obtain the CPC's URI via the List CPC
Objects operation. Instead, such a user may use either the List Permitted Logical Partitions operation or
the Get Inventory operation to obtain the properties of a Logical Partition object to which the user has
object-access permission. The parent CPC's URI is included in the response body of those operations.

Update Image Activation Profile Properties

The Update Image Activation Profile Properties operation updates one or more writable properties of
the Image Activation Profile designated by {image-activation-profile-name}.

792 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/cpcs/{cpc-id}/image-activation-profiles/{image-activation-profile-name}

URI variables:

Variable Description
{cpc-id} Object ID of the target CPC object.
{image-activation-profile- Image Activation Profile name
name}

Request body contents

The request body is expected to contain one or more field names representing writable Image Activation
Profile 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 Image Activation Profile 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, HTTP 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 Image Activation Profile is
updated with the value provided by the input field, and HTTP 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.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission for the Customize/Delete Activation Profiles 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, 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.
300 The provided update values would result in an illegal state. Verify that the
values are both internally consistent and consistent with the current state of
the profile.
306 One or more of the provided update values would result in an illegal state
involving the operating-mode property.

Chapter 11. Core IBM Z resources 793

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
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.
260 The activation profile name in the URI ({image-activation-profile-name}) does
not designate an existing activation profile.
409 (Conflict) 2 The operation was rejected by the Support Element (SE), because the SE is
currently performing processing that requires exclusive control of the SE.
Retry the operation at a later time.
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.
500 (Server Error) 281 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Inventory service data

Information about image activation profiles can be optionally included in the inventory data provided by
the Inventory Service.

Inventory entries for the Image Activation Profile objects are included in the response to the Inventory
Service's Get Inventory operation when the request specifies (explicitly by class, implicitly via a
containing category, or by default) that objects of class "cpc" are to be included. An entry for a particular
image activation profile is included only if the API user has access permission to that object as described
in the Get Image Activation Profile Properties operation.

For each Image Activation Profile object to be included, the inventory response array includes an entry
that is a JSON object with the same contents as is specified in the response body contents section for “Get
Image Activation Profile Properties” on page 788. That is, the data provided is the same as would be
provided if a Get Image Activation Profile Properties operation were requested targeting this object.

Load activation profile

A Load activation profile is used to load a previously activated logical partition with a control program
or operating system.

An activation profile can only be created or deleted from the Hardware Management Console or the
Support Element.

For information on customizing activation profiles, Support Element (Version 2.12.1 and newer)
information can be found on console help system. For information from earlier versions of the Support
Element, see the Support Element Operations Guide.

Objects of this class are not provided when the CPC is enabled for DPM.

794 HMC Web Services API

 Level 04a

Data model
For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

This element includes the following properties.

Table 329. Load activation profile: properties
Name Qualifier Type Description
element-uri — String/ The canonical URI path of the Load Activation Profile object, of the
URI form /api/cpcs/{cpc-id}/load-activation-profiles/{load-
activation-profile-name} where {load-activation-profile-name} is the
value of the name property (Load Activation Profile name).
parent — String/ The canonical URI path of the associated CPC object
URI
class — String The class of a Load Activation Profile object is "load-activation-
profile".
name — String The activation profile name, which uniquely identifies this profile
(1-16) within the set of activation profiles for the CPC object designated by
{cpc-id}.
description (w) String The load profile description
(1-50)
ipl-address (w) String (0-5) The hexadecimal address of an I/O device that provides access to the
control program to be loaded. The input value will be right justified
and padded with zeros to 5 characters. An empty string indicates that
the value for this property is to be retrieved from the IOCDS used
during a subsequent Load operation.

Valid values are in the range "00000" to "nFFFF" where "n" is the
number of subchannel sets provided by the CPC minus 1. So, for
example, on a CPC that provides 3 subchannel sets, the valid range is
"00000" to "2FFFF".
ipl-parameter1 (w) String (0-8) Some control programs support the use of this property to provide
additional control over the outcome of a Load operation. Refer to the
configuration documentation for the control program to be loaded to
see if this parameter is supported and if so, what values and format is
supported. An empty string indicates that the value for this property
is to be retrieved from the IOCDS used during a subsequent Load
operation. Valid characters are 0-9, A-Z, blank, and period. Three
additional characters, (@, $, #) are also allowed when the se-version
property of the associated CPC is "2.14.0" or later. On an Update, a
non-empty string is left justified and right padded with blanks to 8
characters.
ipl-type (w) String One of:
Enum v "ipltype-standard" - Associated image activation profile is used to
perform a standard load.
v "ipltype-scsi" - Associated image activation profile is used to
perform a SCSI load.
v "ipltype-scsidump" - Associated image activation profile is used to
perform a SCSI dump.
worldwide-port- (w) String Worldwide port name value for the activation profile, used for SCIS
name1 (1-16) load and SCSI dump, in hexadecimal.
disk-partition-id (w) Integer Disk partition number (also called the boot program selector) for the
(0-30) activation profile, used for SCIS load and SCSI dump.
logical-unit- (w) String Logical unit number value for the activation profile, used for SCIS
number1 (1-16) load and SCSI dump, in hexadecimal.

Chapter 11. Core IBM Z resources 795

 Level 04a

Table 329. Load activation profile: properties (continued)

Name Qualifier Type Description
1
boot-record-lba (w) String Boot record logical block address for the activation profile, used for
(1-16) SCSI load and SCSI dump, in hexadecimal.
os-specific-load- (w) String Operating system-specific load parameters for the activation profile,
parameters (0-256) used for SCIS load and SCSI dump.
clear-indicator (w) Boolean Whether memory should be cleared before performing the Load (true)
or not cleared (false). The default is to clear memory before
performing the Load. This property cannot be set to false when the
ipl-type is SCSI load or SCSI dump.
store-status- (w) Boolean Whether the store status function should be invoked before
indicator performing the Load (true) or not (false). The default is not to store
status before performing the Load. The store status function stores the
current values of the processing unit timer, the clock comparator, the
program status word, and the contents of the processor registers in
their assigned absolute storage locations. This property cannot be set
to true when the ipl-type is SCSI load or SCSI dump, or when the
ipl-type is "ipltype-standard" and clear-indicator is true.

1. An Update request accepts any mixture of [a-f, A-F, 0-9], however the original string value is not saved and a
subsequent Get request may not return the exact same set of lower/upper case letters.

List Load Activation Profiles

The List Load Activation Profiles operation lists the Load Activation Profiles for the associated CPC
object.

HTTP method and URI

GET /api/cpcs/{cpc-id}/load-activation-profiles

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

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. If matches are found, the response
will be an array with all objects that match. If no match is found,
the response will be an empty array.

Response body contents

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

Field name Type Description

load-activation- Array of Array of nested objects (described in the next table).
profiles load-
actprof-info
objects

Each load-actprof-info object contains the following fields:

796 HMC Web Services API

 Level 04a

Field name Type Description

element-uri String/URI Canonical URI path of the Load Activation Profile object.
name String The name of the Load Activation Profile.

Description
This operation lists the Load Activation Profiles for the associated CPC object.

If the name query parameter is specified, the returned list is limited to those Load Activation Profiles that
have a name property matching the specified filter pattern. If the name parameter is omitted, this
filtering is not done.

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

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-id}, or object-access permission to at least
one Logical Partition of that CPC.

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 796.

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.
299 A query parameter has an invalid syntax.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the CPC or any of
its logical partitions.
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.
500 (Server Error) 281 An unexpected error occurred during the collection of the list of activation
profiles.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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 11. Core IBM Z resources 797

 Level 04a

Example HTTP interaction

GET /api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/load-activation-profiles HTTP/1.1

x-api-session: 5obf0hwsfv1sg9kr5f93cph3zt6o5cptb6lcl538wuyebdyzu4

Figure 434. List Load Activation Profiles: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 17:16:19 GMT
content-type: application/json;charset=UTF-8
content-length: 363
{
"load-activation-profiles": [
{
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/load-activation-profiles/
DEFAULTLOAD",
"name": "DEFAULTLOAD"
},
{
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/load-activation-profiles/
MODIFYL",
"name": "MODIFYL"
}
]
}

Figure 435. List Load Activation Profiles: Response

Usage Note
An API user without object-access permission to the CPC cannot obtain the CPC's URI via the List CPC
Objects operation. Instead, such a user may use either the List Permitted Logical Partitions operation or
the Get Inventory operation to obtain the properties of a Logical Partition object to which the user has
object-access permission. The parent CPC's URI is included in the response body of those operations.

Get Load Activation Profile Properties

The Get Load Activation Profile Properties operation retrieves the properties of a single Load Activation
Profile designated by {load-activation-profile-name}.

HTTP method and URI

GET /api/cpcs/{cpc-id}/load-activation-profiles/{load-activation-profile-name}

URI variables

Variable Description
{cpc-id} Object ID of the target CPC object.
{load-activation-profile- Load Activation Profile name.
name}

Query parameters:

798 HMC Web Services API

 Level 04a

Name Type Rqd/Opt Description

cached-acceptable Boolean Optional Indicates whether cached values are acceptable for the
returned properties. Valid values are true and false. The
default is false.

Response body contents

On successful completion, the response body provides the current values of the properties for the Load
Activation Profile as defined in the “Data model” on page 795.

Description
The URI path must designate an existing Load Activation Profile and the API user must have
object-access permission to the associated CPC object or at least one of its logical partitions. If either of
these conditions is not met, status code 404 (Not Found) is returned.

Some of this object's property values are periodically fetched from the Support Element and cached on
the HMC for quick access by the APIs. Due to the nature of this caching support, the HMC's cached
value of a property may differ from the value on the Support Element at any point in time. While the
HMC strives to keep the cache reasonably current, there are no guarantees about the latency of the cache,
nor is there any latency or other cache information available to the API user. If the cached-acceptable
query parameter is specified as true and a property's value is currently present in the cache, the value
from the cache is returned; otherwise, the current, non-cached value is returned.

On successful execution, HTTP status code 200 (OK) is returned and the response body contains all of the
current properties as defined by the data model for Load Activation Profiles.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-id}, or object-access permission to at least
one Logical Partition of that CPC.

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, 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 object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the CPC or any of
its logical partitions.
260 The activation profile name in the URI ({load-activation-profile-name}) does not
designate an existing activation profile.
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.

Chapter 11. Core IBM Z resources 799

 Level 04a

HTTP error status Reason

code code Description
500 (Server Error) 281 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

GET /api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/load-activation-profiles/DEFAULTLOAD HTTP/1.1

x-api-session: 5obf0hwsfv1sg9kr5f93cph3zt6o5cptb6lcl538wuyebdyzu4

Figure 436. Get Load Activation Profile Properties: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 17:16:19 GMT
content-type: application/json;charset=UTF-8
content-length: 793
{
"boot-record-lba": "abcdef0123456789",
"class": "load-activation-profile",
"clear-indicator": true,
"description": "This is the default Load profile.",
"disk-partition-id": 0,
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/load-activation-profiles/
DEFAULTLOAD",
"ipl-address": "00D00",
"ipl-parameter": " ",
"ipl-type": "ipltype-scsi",
"logical-unit-number": "0",
"name": "DEFAULTLOAD",
"os-specific-load-parameters": "
",
"parent": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"store-status-indicator": false,
"worldwide-port-name": "0"
}

Figure 437. Get Load Activation Profile Properties: Response

Usage Note
An API user without object-access permission to the CPC cannot obtain the CPC's URI via the List CPC
Objects operation. Instead, such a user may use either the List Permitted Logical Partitions operation or
the Get Inventory operation to obtain the properties of a Logical Partition object to which the user has
object-access permission. The parent CPC's URI is included in the response body of those operations.

Update Load Activation Profile Properties

The Update Load Activation Profile Properties operation updates one or more writable properties of the
Load Activation Profile designated by {load-activation-profile-name}.

800 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/cpcs/{cpc-id}/load-activation-profiles/{load-activation-profile-name}

URI variables

Variable Description
{cpc-id} Object ID of the target CPC object.
{load-activation-profile- Load Activation Profile name.
name}

Request body contents

The request body is expected to contain one or more field names representing writable Load Activation
Profile 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 Load Activation Profile 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, HTTP 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 Load Activation Profile is
updated with the value provided by the input field, and HTTP 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.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission for the Customize/Delete Activation Profiles 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, 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.
300 The provided update values would result in an illegal state. Verify that the
values are both internally consistent and consistent with the current state of
the profile.

Chapter 11. Core IBM Z resources 801

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
260 The activation profile name in the URI ({load-activation-profile-name}) does not
designate an existing activation profile.
409 (Conflict) 2 The operation was rejected by the Support Element (SE), because the SE is
currently performing processing that requires exclusive control of the SE.
Retry the operation at a later time.
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.
500 (Server Error) 281 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Inventory service data

Information about load activation profiles can be optionally included in the inventory data provided by
the Inventory Service.

Inventory entries for the Load Activation Profile objects are included in the response to the Inventory
Service's Get Inventory operation when the request specifies (explicitly by class, implicitly via a
containing category, or by default) that objects of class "cpc" are to be included. An entry for a particular
load activation profile is included only if the API user has access permission to that object as described in
the Get Load Activation Profile Properties operation.

For each Load Activation Profile object to be included, the inventory response array includes an entry
that is a JSON object with the same contents as is specified in the response body contents section for “Get
Load Activation Profile Properties” on page 798. That is, the data provided is the same as would be
provided if a Get Load Activation Profile Properties operation were requested targeting this object.

Group profile
A Group profile is used to define the group capacity value for all logical partitions belonging to that
group.

A logical partition becomes a member of a group profile by placing the group profile's URI in the image
activation profile used to activate the logical partition.

A group profile can only be created or deleted from the Hardware Management Console or the Support
Element.

For information on customizing activation profiles, Support Element (Version 2.12.1 and newer)
information can be found on console help system. For information from earlier versions of the Support
Element, see the Support Element Operations Guide.

The Group Profile object's data model includes effective properties, denoted by the (e) qualifier. Those
properties are applicable when at least one of the member logical partitions is currently activated; the
effective-properties-apply property has a value of true when that is the case. Changing the value of an
effective property updates the corresponding characteristic of currently active logical partitions in the

802 HMC Web Services API

 Level 04a

group, and the updated value applies to subsequently activated logical partitions in the group. Once the
last active logical partition in the group has been deactivated, all changes to effective properties will be
discarded and the effective properties return to their base value.

Objects of this class are not provided when the CPC is enabled for DPM.

Data model
For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

This element includes the following properties.

Table 330. Group profile: properties
Name Qualifier Type Description
element-uri — String/URI The canonical URI path of the group profile object, of the form
/api/cpcs/{cpc-id}/group-profiles/{group-profile-name} where
{group-profile-name} is the value of the name property (group profile
name).
parent — String/URI The canonical URI path of the associated CPC object
class — String The class of a Group Profile object is "group-profile".
name — String (1-16) The group profile name, which uniquely identifies this profile
within the set of activation profiles for the CPC object designated
by {cpc-id}
description (w) String (1-50) The group profile description
capacity (w) Integer The upper bound, in MSUs, beyond which the rolling 4-hour
average CPU utilization cannot exceed for the group. A value of 0
indicates the setting is unused.
effective-capacity (e)(w) Integer The effective value of the capacity property.
absolute-icf- (w) absolute- The amount of absolute capping applied to the Internal Coupling
capping1 capping- Facility (ICF) processor.
object
effective- (e)(w) absolute- The effective value of the absolute-icf-capping property.
absolute-icf- capping-
capping1 object
absolute-ifl- (w) absolute- The amount of absolute capping applied to the Integrated Facility
capping1 capping- for Linux (IFL) processor.
object
effective- (e)(w) absolute- The effective value of the absolute-ifl-capping property.
absolute-ifl- capping-
capping1 object
absolute-general- (w) absolute- The amount of absolute capping applied to the general purpose
purpose-capping1 capping- processor.
object
effective- (e)(w) absolute- The effective value of the absolute-general-purpose-capping
absolute-general- capping- property.
purpose-capping1 object
| absolute-cbp- (w) absolute- The amount of absolute capping applied to the Container Based
| capping2 capping- Processor (CBP).
| object
| effective- (e)(w) absolute- The effective value of the absolute-cbp-capping property.
| absolute-cbp- capping-
| capping2 object

Chapter 11. Core IBM Z resources 803

 Level 04a

Table 330. Group profile: properties (continued)

Name Qualifier Type Description
absolute-ziip- (w) absolute- The amount of absolute capping applied to the z Integrated
capping1 capping- Information Processors (zIIP) processor.
object
effective- (e)(w) absolute- The effective value of the absolute-ziip-capping property.
absolute-ziip- capping-
capping1 object
effective- — Boolean Indicates whether the object is currently in a state in which
properties-apply effective properties are applicable (true). Otherwise, the value is
false.
Notes:
1. This property is only provided when the associated SE is at version 2.13.1 or later.
| 2. On a Get request, this property is returned only when the associated SE version is 2.14.0 with the suitable MCL
| bundle, or a later SE version. On an Update request, this property can be included in the request body only
| when the associated SE version is 2.14.0 with the suitable MCL bundle, or a later SE version.

List Group Profiles

The List Group Profiles operation lists the Group Profiles for the associated CPC object.

HTTP method and URI

GET /api/cpcs/{cpc-id}/group-profiles

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

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. If matches are found, the response
will be an array with all objects that match. If no match is found,
the response will be an empty array.

Response body contents

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

Field name Type Description

group-profiles Array of Array of nested objects (described in the next table).
group-
actprof-info
objects

Each group-actprof-info object contains the following fields:

Field name Type Description

element-uri String/URI Canonical URI path of the Group Profile object.
name String The name of the Group Profile.

804 HMC Web Services API

 Level 04a

Description
This operation lists the Group Profiles for the associated CPC object.

If the name query parameter is specified, the returned list is limited to those Group Profiles that have a
name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
done.

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in the
response body contents section.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-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” on page 804.

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.
299 A query parameter has an invalid syntax.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
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.
500 (Server Error) 281 An unexpected error occurred during the collection of the list of group
profiles.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

GET /api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/group-profiles HTTP/1.1

x-api-session: 5obf0hwsfv1sg9kr5f93cph3zt6o5cptb6lcl538wuyebdyzu4

Figure 438. List Group Profiles: Request

Chapter 11. Core IBM Z resources 805

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 17:16:19 GMT
content-type: application/json;charset=UTF-8
content-length: 182
{
"group-profiles": [
{
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/group-profiles/DEFAULT",
"name": "DEFAULT"
}
]
}

Figure 439. List Group Profiles: Response

Get Group Profile Properties

The Get Group Profile Properties operation retrieves the properties of a single Group Profile designated
by {group-profile-name}.

HTTP method and URI

GET /api/cpcs/{cpc-id}/group-profiles/{group-profile-name}

URI variables

Variable Description
{cpc-id} Object ID of the target CPC object.
{group-profile-name} Group Profile name.

Response body contents

On successful completion, the response body provides the current values of the properties for the Group
Profile as defined in the “Data model” on page 803.

Description
The URI path must designate an existing Group Profile and the API user must have object-access
permission to the associated CPC object. If either of these conditions is not met, HTTP 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 by the data model for the Group Profile.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-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.”

806 HMC Web Services API

 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 object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
260 The group profile name in the URI ({group-profile-name}) does not designate
an existing group profile.
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.
500 (Server Error) 281 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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

GET /api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/group-profiles/DEFAULT HTTP/1.1

x-api-session: 5obf0hwsfv1sg9kr5f93cph3zt6o5cptb6lcl538wuyebdyzu4

Figure 440. Get Group Profile Properties: Request

Chapter 11. Core IBM Z resources 807

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 17:16:20 GMT
content-type: application/json;charset=UTF-8
content-length: 250
| { "absolute-cbp-capping": {"type": "none"},
| "absolute-icf-capping": {"type": "none"},
"absolute-ifl-capping": {"value": 98.23, "type": "processors"},
"absolute-general-purpose-capping": {"value": 1.05, "type": "processors"},
"absolute-ziip-capping": {"type": "none"},
"capacity": 0,
"class": "group-profile",
"description": "This is the default Group profile.",
| "effective-absolute-cbp-capping": {"type": "none"},
| "effective-absolute-icf-capping": {"value": 55.86, "type": "processors"},
"effective-absolute-ifl-capping": {"value": 98.23, "type": "processors"},
"effective-absolute-general-purpose-capping": {"type": "none"},
"effective-absolute-ziip-capping": {"type": "none"},
"effective-capacity": 1,
"effective-properties-apply": true,
"element-uri": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/group-profiles/DEFAULT",
"name": "DEFAULT",
"parent": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340"
}

Figure 441. Get Group Profile Properties: Response

Update Group Profile Properties

The Update Group Profile Properties operation updates one or more writable properties of the Group
Profile object designated by {group-profile-name}.

HTTP method and URI

POST /api/cpcs/{cpc-id}/group-profiles/{group-profile-name}

URI variables

Variable Description
{cpc-id} Object ID of the target CPC object.
{group-profile-name} Group Profile name.

Request body contents

The request body is expected to contain one or more field names representing writable Group Profile
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 Group Profile 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, HTTP status code 400 (Bad Request) is returned with a reason code
indicating the validation error encountered.
808 HMC Web Services API
 Level 04a

On successful execution, the value of each corresponding property of the Group Profile is updated with
the value provided by the input field, and HTTP 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.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by {cpc-id}
v Action/task permission for the Customize/Delete Activation Profiles 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, 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.
300 The provided update values would result in an illegal state. Verify that the
values are both internally consistent and consistent with the current state of
the profile.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
260 The group profile name in the URI ({group-profile-name}) does not designate
an existing group profile.
409 (Conflict) 2 The operation was rejected by the Support Element (SE), because the SE is
currently performing processing that requires exclusive control of the SE.
Retry the operation at a later time.
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 value is
false.
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.
500 (Server Error) 281 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Inventory service data

Information about group profiles can be optionally included in the inventory data provided by the
Inventory Service.

Chapter 11. Core IBM Z resources 809

 Level 04a

Inventory entries for the Group Profile objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "cpc" are to be included. An entry for a particular group profile is
included only if the API user has access permission to that object as described in the Get Group Profile
Properties operation.

For each Group Profile object to be included, the inventory response array includes an entry that is a
JSON object with the same contents as is specified in the response body contents section for “Get Group
Profile Properties” on page 806. That is, the data provided is the same as would be provided if a Get
Group Profile Properties operation were requested targeting this object.

Capacity records
A capacity record represents a temporary upgrade that can be applied to a CPC.

These upgrades are provided through the following offerings:

v On/Off Capacity on Demand (On/Off CoD) - This offering allows you to temporarily add additional
capacity or specialty engines due to seasonal activities, period-end requirements, peaks in workload, or
application testing.
v Capacity Backup (CBU) - This offering allows you to replace model capacity or specialty engines to a
backup server in the event of an unforeseen loss of server capacity because of an emergency.
v Capacity for Planned Events (CPE) - This offering allows you to replace model capacity or specialty
engines due to a relocation of workload during system migrations or a data center move.

Data model
For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

This element includes the following class-specific properties.

Table 331. Capacity records: class-specific properties
Name Type Description
element-uri String/ The canonical URI path of the capacity record object, of the form
URI /api/cpcs/{cpc-id}/capacity-records/{capacity-record-id} where
{cpc-id} is the value of the object-id property of the CPC object and
{capacity-record-id} is the value of the record-identifier property of the
Capacity Record object.
parent String/ The canonical URI path for the associated CPC object
URI
class String The class of a capacity record object is "capacity-record".
record-identifier String (1-8) The identifier for the capacity record.
record-type String The type of capacity record. One of:
Enum v "unknown" - the record does not specify a record-type
v "cbu" - a Capacity Backup Upgrade record
v "oocod" - an On/Off Capacity on Demand record
v "planned-event" - a Capacity for Planned Events record
v "loaner" - resources loaned to the installation.

810 HMC Web Services API

 Level 04a

Table 331. Capacity records: class-specific properties (continued)

Name Type Description
activation-status String An indication if any of the resources defined for the record are currently
Enum activated. One of:
v "unknown" - the activation status of the record is not known
v "not-activated" - the record is not currently active
v "real" - the record is either active or pending activation, via an Add
Temporary Capacity operation with a test=false option
v "test" - the record is either active or pending activation via an Add
Temporary Capacity operation with a test=true option
v "can-be-activated" - the record is available for activation, but not
currently active.
activation-date Timestamp Defines the time stamp for when additional capacity for the record was
activated.
record-expiration-date Timestamp Defines the time stamp for when the capacity record will expire.
activation-expiration-date Timestamp Defines the time stamp for when the additional capacity activated for the
record will expire and no longer be active.
maximum-real-days Integer Defines the maximum days that real additional capacity can be activated
for the record. A value of -1 indicates that the number of days is
unlimited.
maximum-test-days Integer Defines the maximum days that test additional capacity can be activated
for the record. A value of -1 indicates that the number of days is
unlimited.
remaining-real-days Integer Defines the remaining number of days that additional real capacity can be
active for the record. A value of -1 indicates that the number of days is
unlimited.
remaining-test-days Integer Defines the remaining number of days that additional test capacity can be
active for the record. A value of -1 indicates that the number of days is
unlimited.
remaining-number-of-real- Integer Defines the number of times that real additional capacity can be activated
activations for the record. A value of -1 indicates that activation count is unlimited.
remaining-number-of-test- Integer Defines the number of times that test additional capacity can be activated
activations for the record. A value of -1 indicates that activation count is unlimited.
processor-info Array of A nested object describing the processor capacities available with this
caprec- capacity record.
proc-info
objects
available-targets Array of A nested object describing the set of possible activation and deactivation
caprec- targets contained within this capacity record. One of these targets is
target chosen via the software-model request body field on the Add Temporary
objects Capacity or Remove Temporary Capacity operations.

Table 332. caprec-proc-info object

Name Type Description
type String Identifies the type of specialty processor represented. One of:
Enum v "cp" - central processor
v "aap" - Application Assist Processor
v "ifl" - Integrated Facility for Linux processor
v "icf" - Internal Coupling Facility processor
v "iip" - z Integrated Information Processors processor
v "sap" - System Assist Processor
| v "cbp" - Container Based Processor.
processor-step Integer The number of processors steps available

Chapter 11. Core IBM Z resources 811

 Level 04a

Table 332. caprec-proc-info object (continued)

Name Type Description
speed-step Integer The CP processor speed activation step. A null object is returned for all
other processor types.
max-number-processors Integer The maximum number of processors available for this processor type. A
value of -1 indicates an unlimited number of processors.
remaining-processor-days Integer The remaining processor days for this processor type. A value of -1
indicates an unlimited number of days.
remaining-msu-days Integer The remaining MSU days for this processor type. A value of -1 indicates
an unlimited number of days. A null object is returned for processor types
where this field is not meaningful.

Table 333. caprec-target object

Name Type Description
processor-step Integer The CPU processor step. This is the incremental delta CPUs compared to
the current activation level. The returned value may be negative.
speed-step Integer The CPU processor speed activation step. This is the incremental delta
speed steps compared to current activation level. The returned value may
be negative.
software-model String (1-3) The software model that this target represents
billable-msu-cost Integer The overall billable MSU cost for this target
billable-msu-delta Integer The change in billable MSU cost by activating this target. The value may
be negative.

List Capacity Records

The List Capacity Records operation lists the capacity record for a given CPC that are managed by this
HMC.

HTTP method and URI

GET /api/cpcs/{cpc-id}/capacity-records

In this request, the URI variable {cpc-id} is the object ID of the target CPC object.

Response body contents

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

Field name Type Description

capacity-record Array of Array of nested objects (described in the next table).
objects

Each nested object contains the following fields:

Field name Type Description

element-uri String/URI Canonical URI path of the Capacity Record object.
record-identifier String The record identifier of the Capacity Record

812 HMC Web Services API

 Level 04a

Description
This operation lists the capacity record for a given CPC that are managed by this HMC.

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in the
response body contents section.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-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” on page 812.

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 object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
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.
500 (Server Error) 275 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Get Capacity Record Properties

The Get Capacity Record Properties operation retrieves the properties of a single Capacity Record
designated by {capacity-record-id} from the CPC object designated by {cpc-id}.

HTTP method and URI

GET /api/cpcs/{cpc-id}/capacity-records/{capacity-record-id}

URI variables

Variable Description
{cpc-id} Object ID of the target CPC object.
{capacity-record-id} Capacity Record identifier, returned by a previous List Capacity Records operation

Chapter 11. Core IBM Z resources 813

 Level 04a

Response body contents

On successful completion, HTTP status code 200 (OK) is returned and the response body provides the
current values of the properties for the Capacity Record as defined in “Data model” on page 810.

Description
The URI path must designate an existing Capacity Record and the API user must have object-access
permission to the associated CPC object. 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 by the data model for the Capacity Record object.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object designated by {cpc-id}.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in the
response body contents section.

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.
276 The capacity record has expired, it can be deleted from the SE.
302 The capacity record identifier in the URI ({capacity-record-id}) must be 1 to 8
characters.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
274 The capacity record identifier in the URI ({capacity-record-id}) does not
designate an existing capacity record.
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.
500 (Server Error) 275 An unexpected error occurred during the operation.
503 (Service 1 The request could not be processed because the HMC is not communicating
Unavailable) with the 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.

Inventory service data

Information about capacity records can be optionally included in the inventory data provided by the
Inventory Service.

814 HMC Web Services API

 Level 04a

Inventory entries for the Capacity Record objects are included in the response to the Inventory Service's
Get Inventory operation when the request specifies (explicitly by class, implicitly via a containing
category, or by default) that objects of class "cpc" are to be included. An entry for a particular capacity
record is included only if the API user has access permission to that object as described in the Get
Capacity Record Properties operation.

For each Capacity Record object to be included, the inventory response array includes an entry that is a
JSON object with the same contents as is specified in the response body contents section for “Get
Capacity Record Properties” on page 813. That is, the data provided is the same as would be provided if
a Get Capacity Record Properties operation were requested targeting this object.

Chapter 11. Core IBM Z resources 815

 Level 04a

816 HMC Web Services API

 Level 04a

Chapter 12. Energy management

Energy Management is a management task that is pervasive and spread across several components in the
systems management stack. Each layer in the stack needs to implement two key functions:
v A set of management functions appropriate for this level at the stack. Energy management functions
provided by lower layers can be used to implement these functions.
v Management interfaces are provided that allows management layers above to configure and control the
energy management functions.

Figure 442. Energy management as applied throughout layers of enterprise management

To achieve this several pieces are needed:

Power and thermal monitoring
"You can't improve what you don't measure" is a trivial engineering paradigm. Measuring energy
consumption and the thermal environment is key for management. Energy Monitoring for Z was
initially introduced with z9®. Starting with zEnterprise 196 the power consumption of attached
BladeCenters is made available and factored into the presented system level power consumption.
Energy control
Based on the measurement data - either for an individual system or aggregated for a group of
servers or even a complete data center - analytics can be implemented. These can keep a watch
on given limits or can identify optimizing potentials. At a system level energy control
mechanisms will be provided to allow for changing energy consumption of a system. These
energy controls can be categorized into two groups:
v Power saving - Power saving mechanisms are used to reduce the average energy consumption
of a system. Through powering off components or reducing performance the power saving is

© Copyright IBM Corp. 2017, 2018 817

 Level 04a

typically achieved. For zEnterprise 196 the Static Power Savings Mode is implemented that
reduces processor frequency and voltage for power saving purposes.
v Power capping - Power capping is a means to limit peak power consumption of a system. This
is especially important in constraint data center environments. Today power and cooling
allocation in data centers is usually done via the label power. This typically leads to a
significant over-provisioning. Through power capping the power allocation for a system can be
adjusted better to the real power consumption of a system and therefore more servers can be
deployed within the same physical limits of their data center.

Groups
A group is composed of an object that contains groups or another object and the object or objects it
contains. For example, a group might be a zBX node that contains a BladeCenter with blades, as
illustrated in Figure 443

zBX Node

BladeCenter

Blade

Figure 443. Example of a zBX node group that contains a BladeCenter with blades

Figure 444 represents a CPC that contains a zCPC.

CPC

zCPC

Figure 444. Example of a CPC group that contains a zCPC

Another example of a group might be a CPC (Ensemble) that contains a zCPC and BladeCenter, as shown
in Figure 445 on page 819.

818 HMC Web Services API

 Level 04a

CPC
(Ensemble Node)

V V

zCPC BladeCenter

Blade

Figure 445. Example of a CPC (Ensemble) group that contains a zCPC and a BladeCenter

A fourth example is a CPC (Ensemble) that contains a zCPC as shown in Figure 446

CPC
(Ensemble Node)

zCPC

Figure 446. Example of a CPC (Ensemble) group that contains a zCPC

Special states
In this chapter, the following states are used but the reasoning behind the states isn't always clear. So
they are explained here in more detail:
"custom"
Occurs only on groups and indicates that the group does not control the children. Clients are able
to alter the children of a group individually.
"under-group-control"
Occurs only on children and indicates that a group controls the state. When clients want to alter
the state, the group must be set to "custom" first.
"not-supported"
Indicates that the feature (either power saving or power capping) is currently not supported,
possible reasons can be:
v Hardware does not support it → permanent
v Firmware level does not support it → can change after a firmware update
v The hardware is not powered on → can change after the device is powered on.

Chapter 12. Energy management 819

 Level 04a

"not-available"
Couldn't read the state of the underlying hardware.
"not-entitled"
Indicates that the automate feature is not installed and so power saving and power capping is not
allowed.

Power saving
Power saving is a function that reduces the energy consumption of a system. Please note that power
saving is only available if the Automate management enablement feature is installed. The possible
settings include:
High performance
The power consumption and performance of the object are not reduced. This is the default
setting.
Low power
The performance of the object is reduced to allow for low power consumption. When this setting
is selected for CPC and BladeCenter objects, all components of the object enabled for power
saving have reduced performance to allow for low power consumption. Use this setting to enable
group power saving.

Note: You can only set the power saving setting of the zCPC to Low power one time per
calendar day in an air cooled system. This power save property is set to Not Supported if the
current zCPC power saving setting is High performance but the zCPC has already entered Low
power once within the calendar day.
Custom
Use Custom to disable group power saving and individually configure the components of the
object for power saving.

Note: This setting is available only for CPC and BladeCenter objects.

Group power saving

The following are important concepts regarding group power saving:
v Group power saving settings replace individual object settings--that is, the Power Saving setting of a
CPC or BladeCenter supersede the Power Saving setting of any object contained within the CPC or
BladeCenter.
v You can enable group power saving by setting the Power Saving setting of the CPC or BladeCenter to
Low power or High performance.
v You can change individual Power Saving settings only if the object is not under group power saving
control.
v To disable group power saving without changing the individual Power Saving settings of the group
members, change the Power Saving setting of the CPC or BladeCenter to Custom.

Power capping
Please note that power capping is only available if the Automate management enablement feature is
installed.

Group capping
The following are important concepts regarding group power capping:
v Group caps replace individual object caps—that is, the Cap Value of a CPC or BladeCenter supersede
the power cap of any object contained within the CPC or BladeCenter.
v You can enable group capping by setting the Power Capping setting of the CPC or BladeCenter to
Enabled.

820 HMC Web Services API

 Level 04a

v You can change individual Cap Values if the object is not under group capping control.
v If a CPC or BladeCenter contains an object that does not support power capping, the Power Rating is
used in calculating the minimum power cap value for the group. The Power Rating can be found on
the details window for an object.
v The maximum Cap Value for a group is the sum of the Power Rating of all Group objects.
v When a group component is powered off or removed, the group cap is redistributed to the remaining
group components.
v To disable group capping without changing the individual power caps of the group members, change
the Power Capping setting of the CPC or BladeCenter to Custom.

Energy management operations summary

The following tables provide an overview of the operations provided. All POST operation were executed
asynchronously and provide a query URI where the result of the request can be queried.

Note: The zCPC is not modeled as a full entity like CPC, BladeCenters or blades, because only energy
management needs the zCPC to represent only Z hardware without zBX. That is the reason why all zCPC
related operations are tied to the CPC.
Table 334. Energy management: operations summary
Operation name HTTP method and URI path
“Set zBX (Node) Power Save” POST /api/zbxs/{zbx-id}/operations/set-power-save
on page 822
“Set zBX (Node) Power POST /api/zbxs/{zbx-id}/operations/set-power-capping
Capping” on page 824
“Set CPC Power Save” on page POST /api/cpcs/{cpc-id}/operations/set-cpc-power-save
827
“Set CPC Power Capping” on POST /api/cpcs/{cpc-id}/operations/set-cpc-power-capping
page 829
“Get CPC Energy Management GET /api/cpcs/{cpc-id}/energy-management-data
Data” on page 836
“Set zCPC Power Save” on POST /api/cpcs/{cpc-id}/operations/set-zcpc-power-save
page 832
“Set zCPC Power Capping” on POST /api/cpcs/{cpc-id}/operations/set-zcpc-power-capping
page 834
“Set BladeCenter Power Save” POST /api/bladecenters/{bladecenter-id}/operations/set-power-save
on page 848
“Set BladeCenter Power POST /api/bladecenters/{bladecenter-id}/operations/set-power-capping
Capping” on page 851
“Set Blade Power Save” on POST /api/blades/{blade-id}/operations/set-power-save
page 853
“Set Blade Power Capping” on POST /api/blades/{blade-id}/operations/set-power-capping
page 855
“Get Energy Optimization GET /api/cpcs/{cpc-id}/operations/get-energy-optimization-advice-summary
Advice Summary” on page 837
“Get Energy Optimization GET /api/cpcs/{cpc-id}/operations/get-energy-optimization-advice-details
Advice Details” on page 843

Table 335. Energy management: URI variables

Variable Description
{zbx-id} Object ID of a zBX node

Chapter 12. Energy management 821

 Level 04a

Table 335. Energy management: URI variables (continued)

Variable Description
{cpc-id} Object ID of a CPC
{bladecenter-id} Object ID of a BladeCenter
{blade-id} Object ID of a blade

Energy Management for zBX (Node) object

Data model
The data model for a zBX object includes some properties related to energy management when that zBX
object represents a zBX node. These properties are described under the data model for the zBX object:
“Energy Management Related Additional Properties” on page 889.

Operations
Set zBX (Node) Power Save
Use the Set zBX (Node) Power Save operation to set the power save setting of a zBX node.

HTTP method and URI

POST /api/zbxs/{zbx-id}/operations/set-power-save

In this request, the URI variable {zbx-id} is the object ID of the zBX node.

Request body contents

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

Name Type Rqd/Opt Description

power-saving String Required The possible settings are:
Enum v "high-performance" - The power consumption and performance of
the components of the zBX node are not reduced. This is the
default setting.
v "low-power" - All components of the zBX node enabled for power
saving.
v "custom" - Components may have their own settings changed
individually. No component settings are actually changed when
this mode is entered.

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

822 HMC Web Services API

 Level 04a

Description
Use this operation to control the average energy consumption of a zBX node object designated by {zbx-id},
or to remove a power consumption limit for this object. You can closely manage power allocations within
the physical limits of your data center.

This operation will always fail if the designated zBX node is under group control (see “Group capping”
on page 820) or the power-saving property of the zBX node is set to "not-supported" or "not-entitled".
(See “Energy Management Related Additional Properties” on page 889 for details on this property.) In
addition, this operation is only available if the ensemble is functioning at the Automate management
enablement level.

The action to change the power-saving settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job
has completed, an asynchronous result message is sent, with Job status and reason codes described in
“HTTP status and reason codes.” After completion, the Query Job Status operation may be used to
retrieve the completion results.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to blade, BladeCenter, and zBX objects
v Action/task permission to the Power Save 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 822.

Otherwise, 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.
240 The object ID in the URI {zbx-id} designates a zBX object that is not a zBX
node (that is, does not have a type of "node").
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({zbx-id}) does not designate an existing zBX object,
or the API user does not have object-access permission to the object.
409 (Conflict) 1 The operation cannot be performed because the object designated by the
request URI is not in the correct state.
244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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.

Chapter 12. Energy management 823

 Level 04a

Job status and reason codes

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the zBX
hardware
162 Communication error occurred while trying to access the zBX hardware
163 An error occurred at one or more children

If the job reason code is 163, the job-results field provided by the Query Job Status operation will
contain an object with the following fields:

Field name Type Description

errors Object array A list of error objects, containing detailed error information about errors
occurred on children
at-least-one- Boolean True indicates that the operation was successful for at least one child.
operation-succeed

Each error object has this structure:

Job reason
Job status codes code Description
object-uri String URI The canonical URI path for a specific object where the error occurred
reason-code Integer Specify the specific error type, possible values are:
v 160 - A firmware error occurred while executing the operation
v 161 - A hardware error occurred while performing the energy
management operation
v 162 - Communication error occurred while trying to access the hardware
message String A non-localized message provided for development purposes only. Client
applications should not display this message directly to the user.

Set zBX (Node) Power Capping

Use the Set zBX (Node) Power Capping operation to set the power capping settings of a zBX node.

HTTP method and URI

POST /api/zbxs/{zbx-id}/operations/set-power-capping

In this request, the URI variable {zbx-id} is the object ID of the zBX node.

824 HMC Web Services API

 Level 04a

Request body contents

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

Field name Type Rqd/Opt Description

power-capping- String Required The possible settings are:
state Enum v "disabled" - The power cap of the zBX node is not set and the peak
power consumption is not limited. This is the default setting.
v "enabled" - The peak power consumption of the zBX node is
limited to the current cap value.
v "custom" - Individually configure the components of the zBX node
for power capping. No component settings are actually changed
when this mode is entered.
power-cap-current Integer Optional Specifies the current cap value for the zBX node in watts (W). The
current cap value indicates the power budget for the zBX node.

This field is only required if the power-capping-state field is set to

"enabled". The power-cap-current must be between
power-cap-minimum and power-cap-maximum:

power-cap-minimum <= value <= power-cap-maximum

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

Description
Use this operation to limit the peak power consumption of a zBX node object designated by {zbx-id}, or to
remove a power consumption limit for this object. You can closely manage power allocations within the
physical limits of your data center.

This operation will always fail if the designated zBX is under group control (see “Group capping” on
page 820) or the power-capping-state property of the zBX is set to "not-supported" or "not-entitled". (See
“Energy Management Related Additional Properties” on page 889 for details on this property.) In
addition, this operation is only available if the ensemble is functioning at the Automate management
enablement level.

The action to change the power-capping settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job
has completed, an asynchronous result message is sent, with Job status and reason codes described in
“HTTP status and reason codes” on page 826. After completion, the Query Job Status operation may be
used to retrieve the completion results.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to blade, BladeCenters, and zBX bjects
v Action/task permission to the Power Capping task.

Chapter 12. Energy management 825

 Level 04a

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 825.

Otherwise, 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.
240 The object ID in the URI {zbx-id} designates a zBX object that is not a zBX
node (that is, does not have a type of "node").
400 (Bad Request) 5 The power-cap-current field is not set, but power-capping-state field is set to
"enabled".
7 The power-cap-current field contains a value that is not in the range
power-cap-minimum ... power-cap-maximum
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({zbx-id}) does not designate an existing zBX object,
or the API user does not have object-access permission to the object.
409 (Conflict) 1 The operation cannot be performed because the object designated by the
request URI is not in the correct state.
244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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.

Job status and reason codes

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the zBX
hardware
162 Communication error occurred while trying to access the zBX hardware
163 An error occurred at one or more children

If the job reason code is 163, the job-results field provided by the Query Job Status operation will
contain an object with the following fields:

Field name Type Description

errors Object array A list of error objects, containing detailed error information about errors
occurred on children

826 HMC Web Services API

 Level 04a

Field name Type Description

at-least-one- Boolean True indicates that the operation was successful for at least one child.
operation-succeed

Each error object has this structure:

Job reason
Job status codes code Description
object-uri String URI The canonical URI path for a specific object where the error occurred
reason-code Integer Specify the specific error type, possible values are:
v 160 - A firmware error occurred while executing the operation
v 161 - A hardware error occurred while performing the energy
management operation
v 162 - Communication error occurred while trying to access the hardware
message String A non localized message provided for development purposes only. Client
applications should not display this message directly to the user.

Energy Management for CPC object

The energy management for the CPC object represents all energy management for the CPC.

Data model
The data model for a CPC object includes some properties related to energy management. These
properties are described in “Energy management related additional properties” on page 639.

Operations
Set CPC Power Save
Use the Set CPC Power Save operation to set the power save setting of a CPC.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/set-cpc-power-save

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:

Name Type Rqd/Opt Description

power-saving String Required The possible settings are:
Enum v "high-performance" - The power consumption and performance of
the CPC are not reduced. This is the default setting.
v "low-power" - Low power consumption for all components of the
CPC enabled for power saving.
v "custom" - Components may have their own settings changed
individually. No component settings are actually changed when
this mode is entered.

Chapter 12. Energy management 827

 Level 04a

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

Description
Use this operation to control the average energy consumption of a CPC object designated by {cpc-id}, or
to remove a power consumption limit for this object. You can closely manage power allocations within
the physical limits of your data center.

This operation will always fail if the designated CPC is under group control (see “Group capping” on
page 820) or the cpc-power-saving property of the CPC is set to "not-supported" or "not-entitled". (See
“Energy management related additional properties” on page 639 for details on this property.) In addition,
this operation is only available if the ensemble is functioning at the Automate management enablement
level.

The action to change the power-saving settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job
has completed, an asynchronous result message is sent, with Job status and reason codes described in
“HTTP status and reason codes.” After completion, the Query Job Status operation may be used to
retrieve the completion results.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to all blade, BladeCenter, CPC and zCPC objects
v Action/task permission to the Power Save 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.”

Otherwise, 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.
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.

828 HMC Web Services API

 Level 04a

HTTP error status Reason

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.
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.

Job status and reason codes

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the blade or Z
hardware
162 Communication error occurred while trying to access the blade or Z
hardware
163 An error occurred at one or more children

If the job reason code is 163, the job-results field provided by the Query Job Status operation will
contain an object with the following fields:

Field name Type Description

errors Object array A list of error objects, containing detailed error information about errors
occurred on children
at-least-one- Boolean True indicates that the operation was successful for at least one child.
operation-succeed

Each error object has this structure:

Job reason
Job status codes code Description
object-uri String URI The canonical URI path for a specific object where the error occurred
reason-code Integer Specify the specific error type, possible values are:
v 160 - A firmware error occurred while executing the operation
v 161 - A hardware error occurred while performing the energy
management operation
v 162 - Communication error occurred while trying to access the hardware
message String A non-localized message provided for development purposes only. Client
applications should not display this message directly to the user.

Set CPC Power Capping

Use the Set CPC Power Capping operation to set the power capping settings of a CPC.

Chapter 12. Energy management 829

 Level 04a

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/set-cpc-power-capping

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

power-capping- String Required The possible settings are:
state Enum v "disabled" - The power cap of the CPC is not set and the peak
power consumption is not limited. This is the default setting.
v "enabled" - The peak power consumption of the CPC is limited to
the current cap value.
v "custom" - Individually configure the components of the
BladeCenter for power capping. No component settings are
actually changed when this mode is entered.
power-cap-current Integer Optional Specifies the current cap value for the CPC in watts (W). The current
cap value indicates the power budget for the CPC.

This field is only required if the power-capping-state field is set to

"enabled". The power-cap-current must be between
cpc-power-cap-minimum and cpc-power-cap-maximum:

cpc-power-cap-minimum <= value <= cpc-power-cap-maximum

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

Description
Use this operation to limit the peak power consumption of a CPC object designated by {cpc-id}, or to
remove a power consumption limit for this object. You can closely manage power allocations within the
physical limits of your data center.

This operation will always fail if the designated CPC is under group control (see “Group capping” on
page 820) or the cpc-power-capping-state property of the CPC is set to "not-supported" or "not-entitled".
(See “Energy management related additional properties” on page 639 for details on this property.) In
addition, this operation is only available if the ensemble is functioning at the Automate management
enablement level.

The action to change the power-capping settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job
has completed, an asynchronous result message is sent, with Job status and reason codes described in
“HTTP status and reason codes” on page 831. After completion, the Query Job Status operation may be
used to retrieve the completion results.

830 HMC Web Services API

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to all blade, BladeCenter, CPC and zCPC objects
v Action/task permission to the Power Capping 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 830.

Otherwise, 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.
400 (Bad Request) 7 The power-cap-current field contains a value that is not in the range
cpc-power-cap-minimum ... cpc-power-cap-maximum
5 The power-cap-current field is not set, but power-capping-state field is set to
"enabled".
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 1 The operation cannot be performed because the object designated by the
request URI is not in the correct state.
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.

Job status and reason codes

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the blade or Z
hardware
162 Communication error occurred while trying to access the blade or Z
hardware
163 An error occurred at one or more children

If the job reason code is 163, the job-results field provided by the Query Job Status operation will
contain an object with the following fields:

Chapter 12. Energy management 831

 Level 04a

Field name Type Description

errors Object array A list of error objects, containing detailed error information about errors
occurred on children
at-least-one- Boolean True indicates that the operation was successful for at least one child.
operation-succeed

Each error object has this structure:

Job reason
Job status codes code Description
object-uri String URI The canonical URI path for a specific object where the error occurred
reason-code Integer Specify the specific error type, possible values are:
v 160 - A firmware error occurred while executing the operation
v 161 - A hardware error occurred while performing the energy
management operation
v 162 - Communication error occurred while trying to access the hardware
message String A non localized message provided for development purposes only. Client
applications should not display this message directly to the user.

Set zCPC Power Save

Use the Set zCPC Power Save operation to set the power save settings of the zCPC portion of a CPC.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/set-zcpc-power-save

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

power-saving String Required The possible settings are:
Enum v "high-performance" - The power consumption and performance of
the zCPC are not reduced. This is the default setting.
v "low-power" - Low power consumption for all components of the
zCPC enabled for power saving.

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

Description
Use this operation to control the average energy consumption of a zCPC portion of the CPC {cpc-id}, or to
remove a power consumption limit for this object. You can closely manage power allocations within the
physical limits of your data center.

832 HMC Web Services API

 Level 04a

This operation will always fail if the designated zCPC is under group control (see “Group capping” on
page 820) or the zcpc-power-saving property of the zCPC is set to "not-supported" or "not-entitled". (See
“Energy management related additional properties” on page 639 for details on this property.) In addition,
this operation is only available if the ensemble is functioning at the Automate management enablement
level.

The action to change the power-saving settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job
has completed, an asynchronous result message is sent, with Job status and reason codes described in
“HTTP status and reason codes.” After completion, the Query Job Status operation may be used to
retrieve the completion results.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to all blade, BladeCenter, CPC and zCPC objects
v Action/task permission to the Power Save 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 832.

Otherwise, 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.
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 1 The operation cannot be performed because the object designated by the
request URI is not in the correct state.
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.

Job status and reason codes

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully

Chapter 12. Energy management 833

 Level 04a

Job reason
Job status codes code Description
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the Z
hardware
162 Communication error occurred while trying to access the Z hardware

Set zCPC Power Capping

Use the Set zCPC Power Capping operation to set the power capping settings of the zCPC portion of a
CPC.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/set-zcpc-power-capping

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

power-capping- String Required The possible settings are:
state Enum v "disabled" - The power cap of the zCPC is not set and the peak
power consumption is not limited. This is the default setting.
v "enabled" - The peak power consumption of the zCPC is limited to
the current cap value.
power-cap-current Integer Optional Specifies the current cap value for the zCPC in watts (W). The current
cap value indicates the power budget for the zCPC.

This field is only required if the power-capping-state field is set to

"enabled". The power-cap-current must be between
zcpc-power-cap-minimum and zcpc-power-cap-maximum:

zcpc-power-cap-minimum <= value <= zcpc-power-cap-maximum

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

Description
Use this operation to limit the peak power consumption of a zCPC object designated by {cpc-id}, or to
remove a power consumption limit for this object. You can closely manage power allocations within the
physical limits of your data center.

This operation will always fail if the designated zCPC is under group control (see “Group capping” on
page 820) or the zcpc-power-capping-state property of the zCPC is set to "not-supported" or

834 HMC Web Services API

 Level 04a

"not-entitled". (See “Energy management related additional properties” on page 639 for details on this
property.) In addition, this operation is only available if the ensemble is functioning at the Automate
management enablement level.

The action to change the power-capping settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job
has completed, an asynchronous result message is sent, with Job status and reason codes described below.
After completion, the Query Job Status operation may be used to retrieve the completion results.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to all blade, BladeCenter, CPC and zCPC objects
v Action/task permission to the Power Capping 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 834.

Otherwise, 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.
400 (Bad Request) 7 The power-cap-current field contains a value that is not in the range
zcpc-power-cap-minimum ... zcpc-power-cap-maximum
5 The power-cap-current field is not set, but power-capping-state field is set to
"enabled".
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
409 (Conflict) 1 The operation cannot be performed because the object designated by the
request URI is not in the correct state.
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.

Job status and reason codes

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully

Chapter 12. Energy management 835

 Level 04a

Job reason
Job status codes code Description
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the Z
hardware
162 Communication error occurred while trying to access the Z hardware

Get CPC Energy Management Data

Use the Get CPC Energy Management Data operation to retrieve all energy management related data in
one single call.

HTTP method and URI

GET /api/cpcs/{cpc-id}/energy-management-data

In this request, the URI variable {cpc-id} is the object ID of the CPC.

Response body contents

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

Field name Type Description

objects Array of An array of nested em-data objects containing the energy management data.
objects The format of each nested object is given in the next table.

Each nested em-data object contains the following fields:

Field name Type Description

object-uri String/ URI The canonical URI path of the specific object to which this em-data object
pertains.
object-id String Object-id property of the specific object to which this em-data object
pertains.
class String The type of the specific object to which this em-data object pertains.
properties Object Nested object containing the energy management properties for the object
identified by the object-uri field, as described in the data model section for
objects of the type indicated by the class field.
error-occurred Boolean If true, indicates that an error occurred while querying the data for the
object specified by the object-uri. As a consequence the property could be
null or incomplete.

Description
The Get CPC Energy Management Data is a convenience operation to allow a client to retrieve all
energy management related data for a CPC in a single request rather than invoking several requests to
retrieve this data.

Note that this operation returns data for a child object of the designated CPC only if the API user has
object-access permission to that object. Children objects for which the API user does not have access are
omitted from the response and no error is indicated.

836 HMC Web Services API

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object designated by the request, and for any children objects for
which data is to be returned.

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 836.

Otherwise, 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 ({cpc-id}) does not designate an existing CPC object,
or the API user does not have object-access permission to the object.
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.

Get Energy Optimization Advice Summary

The Get Energy Optimization Advice Summary operation provides a summary of all currently available
energy optimization advice for a CPC.

HTTP method and URI

GET /api/cpcs/{cpc-id}/operations/get-energy-optimization-advice-summary

In this request, the URI variable {cpc-id} is the object ID of the CPC whose energy optimization advice
summary is to be returned.

Response body contents

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

Field name Type Description

advice Array of A summary of all energy optimization advice available for the CPC. It is an
energy- array of nested energy-optimization-advice-summary objects as described in
optimization- the next table.
advice-
summary
objects

Each nested energy-optimization-advice-summary object contains the following fields:

Chapter 12. Energy management 837

 Level 04a

Field name Type Description

type String Identifies the advice type. Valid values are:
Enum v "environmental" - Advice about environmental aspects of energy
management such as air temperature.
v "processor-utilization" - Advice related to the amount of processor
utilization in the CPC.
timestamp Timestamp The time when this advice was created or updated. This field and the
last-energy-advice-time property of the CPC are updated each time the
status field is updated.
summary String Human readable description of the status field.
(0-153)
status String The current status of the parameters factored into this advice. The valid
Enum values for this field depend on the value of the type field.

When type is "environmental":

v "optimal" - Parameters related to this advice are currently at optimal
values; no changes are recommended at this time.
v "above-threshold" - One or more of the parameters is above its threshold;
changes are recommended.

When type is "processor-utilization":

v "low-utilization" - System utilization is low. If static power save is
enabled, power consumption can be reduced.
v "low-utilization-power-save" - System utilization is low, but static power
save is enabled.
v "high-utilization" - System utilization is high and the system is configured
optimally.
v "high-utilization-power-save" - System utilization is high, but static
power save is enabled. Performance can be increased by disabling static
power save on the system.

Description
This operation returns summary information about the current energy optimization advice for the CPC
object specified by {cpc-id}.

On successful execution, the energy optimization advice summary for each type of advice for which there
is available data for the CPC is provided in the response body, and HTTP status code 200 (OK) is
returned.

If the request URI does not identify a CPC object to which the API user has object-access permission,
HTTP status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object identified in the request URI.
v Action/task permission to the Energy Optimization Advisor task.

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 837.

Otherwise, 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.

838 HMC Web Services API

 Level 04a

Table 336. Get Energy Optimization Advice Summary: 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 The user under which the API request was authenticated does not have the
required authority to perform the requested action.
404 (Not Found) 1 The request URI does not designate an existing CPC, or it designates a CPC
for which the API user does not have object-access permission.
4 The object designated by the request URI does not support the requested
operation.
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.
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

POST /api/cpcs/a44d8ab8-e68e-3a07-9bff-e484a62ca00d/operations/get-energy-optimization-
advice-details HTTP/1.1
x-api-session: 2szwxczuje9cttj01145ozlab65x9osmpvvdibob5w0nvgwm80
content-type: application/json
content-length: 52
{
"timescale":"four-hours",
"type":"environmental"
}

Figure 447. Get Energy Optimization Advice Summary: Request

Chapter 12. Energy management 839

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 08 Mar 2016 19:32:27 GMT
content-type: application/json;charset=UTF-8
content-length: 2683
{
"ambient-temperature":24.200000762939453,
"power-saving":126,
"status":"above-threshold",
"summary":"The ambient temperature is above the current threshold of 23.0\u00b0C
(73.4\u00b0F). If the ambient temperature is lowered below the identified threshold,
the system power consumption will be reduced by approximately 126 W.",
"temperature-graph":[
{
"data":23.80500030517578,
"timestamp":1457451614605
},
{
"data":23.577499389648438,
"timestamp":1457452214606
},
{
"data":23.645000457763672,
"timestamp":1457452814605
},
{
"data":24.00749969482422,
"timestamp":1457453414605
},
{
"data":23.850000381469727,
"timestamp":1457454014605
},
{
"data":23.697500228881836,
"timestamp":1457454614605
},
{
"data":23.704999923706055,
"timestamp":1457455214605
},
{
"data":23.825000762939453,
"timestamp":1457455814605
},
{
"data":23.704999923706055,
"timestamp":1457456414605
},
{
"data":23.75,
"timestamp":1457457014605
},

Figure 448. Get Energy Optimization Advice Summary: Response (Part 1)

840 HMC Web Services API

 Level 04a

{
"data":23.704999923706055,
"timestamp":1457457614605
},
{
"data":23.7450008392334,
"timestamp":1457458214605
},
{
"data":23.78499984741211,
"timestamp":1457458814606
},
{
"data":23.834999084472656,
"timestamp":1457459414607
},
{
"data":23.795000076293945,
"timestamp":1457460014606
},
{
"data":23.912500381469727,
"timestamp":1457460614604
},
{
"data":23.80500030517578,
"timestamp":1457461214606
},
{
"data":23.6875,
"timestamp":1457461814606
},
{
"data":23.799999237060547,
"timestamp":1457462414604
},
{
"data":23.889999389648438,
"timestamp":1457463014605
},
{
"data":23.907499313354492,
"timestamp":1457463614604
},
{
"data":23.877500534057617,
"timestamp":1457464214614
},
{
"data":24.012500762939453,
"timestamp":1457464814605
},

Figure 449. Get Energy Optimization Advice Summary: Response (Part 2)

Chapter 12. Energy management 841

 Level 04a

{
"data":24.200000762939453,
"timestamp":1457465414604
}
],
"temperature-threshold":23.0,
"timestamp":1457031003347,
"type":"environmental",
"wattage":6952,
"wattage-graph":[
{
"data":6957,
"timestamp":1457451614605
},
{
"data":6970,
"timestamp":1457452214606
},
{
"data":6968,
"timestamp":1457452814605
},
{
"data":6970,
"timestamp":1457453414605
},
{
"data":6965,
"timestamp":1457454014605
},
{
"data":6970,
"timestamp":1457454614605
},
{
"data":6965,
"timestamp":1457455214605
},
{
"data":6963,
"timestamp":1457455814605
},
{
"data":6958,
"timestamp":1457456414605
},
{
"data":6969,
"timestamp":1457457014605
},
{
"data":6963,
"timestamp":1457457614605
},

Figure 450. Get Energy Optimization Advice Summary: Response (Part 3)

842 HMC Web Services API

 Level 04a

{
"data":6963,
"timestamp":1457458214605
},
{
"data":6967,
"timestamp":1457458814606
},
{
"data":6961,
"timestamp":1457459414607
},
{
"data":6967,
"timestamp":1457460014606
},
{
"data":6963,
"timestamp":1457460614604
},
{
"data":6968,
"timestamp":1457461214606
},
{
"data":6969,
"timestamp":1457461814606
},
{
"data":6964,
"timestamp":1457462414604
},
{
"data":6963,
"timestamp":1457463014605
},
{
"data":6951,
"timestamp":1457463614604
},
{
"data":6941,
"timestamp":1457464214614
},
{
"data":6947,
"timestamp":1457464814605
},
{
"data":6955,
"timestamp":1457465414604
}
]
}

Figure 451. Get Energy Optimization Advice Summary: Response (Part 4)

Get Energy Optimization Advice Details

The Get Energy Optimization Advice Details operation returns detailed information about currently
available energy optimization advice for a CPC.

Chapter 12. Energy management 843

 Level 04a

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/get-energy-optimizaton-advice-details

In this request, the URI variable {cpc-id} is the object ID of the CPC whose energy optimization advice
details are to be returned.

Request body contents

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

Field name Type Rqd/ Opt Description

timescale String Optional Timescale for the advice graph data points. This is the amount of
Enum time to be covered by the data points in the graph. Valid values
are:
v "four-hours"
v "one-day"
v "three-days"
v "one-week"

If not specified, the default is "one-day".

type String Required The type of advice details to return. Valid values are:
Enum v "environmental" - Advice about environmental aspects of energy
management such as air temperature.
v "processor-utilization" - Advice related to the processor
utilization in the CPC.

Response body contents

On successful completion, the response body contains a JSON object that provides the values of the
specific energy optimization advice object requested from the CPC. The advice object contains a set of
fields common to all types of advice, and a set of additional fields that differ based on the advice type.

The common fields provided for all types of advice are defined in the following table:

Field name Type Description

type String Identifies the advice type. Valid values are:
Enum v "environmental" - Advice about environmental aspects of energy
management such as air temperature.
v "processor-utilization" - Advice related to the processor utilization in the
CPC.
timestamp Timestamp The time when this advice was created or updated. This field and the
last-energy-advice-time property of the CPC are updated each time the
status field is updated.
summary String Human readable description of the status field.
(0-153)

844 HMC Web Services API

 Level 04a

Field name Type Description

status String The current status of the parameters factored into this advice. The valid
Enum values for this field depend on the value of the type field.

When type is "environmental":

v "optimal" - Parameters related to this advice are currently at optimal
values; no changes are recommended at this time.
v "above-threshold" - One or more of the parameters is above its threshold;
changes are recommended.

When type is "processor-utilization":

v "low-utilization" - System utilization is low. If static power save is
enabled, power consumption can be reduced by the amount specified in
the power-saving field.
v "low-utilization-power-save" - System utilization is low, but static power
save is enabled.
v "high-utilization" - System utilization is high and the system is configured
optimally.
v "high-utilization-power-save" - System utilization is high, but static
power save is enabled. Performance can be increased by disabling static
power save on the system.

When the type field contains "environmental", the response body also contains the following additional
type-specific fields:

Field name Type Description

ambient-temperature Float The ambient temperature when this advice was generated, in degrees
Celsius.
wattage Integer The electrical power usage when this advice was generated, in Watts.
temperature-threshold Float The temperature threshold that causes an increase of the system power
consumption, in degrees Celsius.
power-saving Integer The amount of electrical power that can be saved when following this
advice, in Watts.
temperature-graph Array of An ordered collection of temperature data points, in descending time order,
float-data- beginning with the most recent, covering as much of the requested time
point period as is available. Each element of this array is a float-data-point object
objects representing the ambient environment temperature in degrees Celsius at a
specific point in time. The interval is implicit given by the timestamps of the
individual data points.
wattage-graph Array of An ordered collection of electrical power data points, in descending time
integer- order, beginning with the most recent, covering as much of the requested
data-point time period as is available. Each element of this array is an
objects integer-data-point object representing the total system power, in Watts, at a
specific point in time. The interval is implicit, given by the timestamps of the
individual data points.

When the type field contains "processor-utilization", the response body also contains the following
additional type-specific fields:

Field name Type Description

wattage Integer The electrical power usage when this advice was generated, in Watts.
power-saving Integer The amount of electrical power that will be saved by following this advice,
in Watts.

Chapter 12. Energy management 845

 Level 04a

Field name Type Description

utilization-threshold Integer The threshold in percentage. The threshold is used to calculate the current
(0-100) system status. If system utilization is below the threshold, enabling static
power save should be considered.
utilization Array of List of all processor types installed in the CPC and their percent utilization
type- at the time this advice was created.
utilization
objects
static-power-save- Boolean Indicates whether enabling static power save is recommended. True if
recommended recommended; false otherwise.
utilization-graphs Array of A collection of processor utilization graphs. Each element of this array
type- contains the utilization graph of a processor type available in the system.
utilization-
graph
objects

Each nested float-data-point object contains the following fields:

Field name Type Description

data Float Floating point data value.
timestamp Timestamp The time when this data point was taken

Each nested integer-data-point object contains the following fields.

Field name Type Description

data Integer Integer data value.
timestamp Timestamp The time when this data point was taken.

Each type-utilization-graph object contains the following fields:

Field name Type Description

type String The processor type. Valid values are:
Enum v "cp" - Central (general purpose) processor.
v "icf" - Internal Coupling Facility processor.
v "ifl" - Integrated Facility for Linux processor.
v "sap" - Service assist processor.
v "sys" - Total system utilization. (Used for threshold monitoring).
utilization-graph Array of An ordered collection of utilization data points, in descending time order,
integer- beginning with the most recent, covering as much of the requested time
data-point period as is available. Each element of this array is an integer-data-point
objects object representing the utilization of the processor type in percentage at a
specific point in time. The interval is implicit, given by the timestamps of the
individual data points.

Each nested type-utilization object contains the following fields:

846 HMC Web Services API

 Level 04a

Field name Type Description

type String The processor type. Valid values are:
Enum v "cp" - Central (general purpose) processor.
v "icf" - Internal Coupling Facility processor.
v "ifl" - Integrated Facility for Linux processor.
v "sap" - Service assist processor.
v "sys" - Total system utilization. (Used for threshold monitoring).
utilization Integer The current utilization in percentage for the given processor type.
(0-100)

Description
This operation returns detailed information about the requested type of energy optimization advice for
the CPC object specified by {cpc-id}.

On successful execution, the energy optimization advice details for the requested type of advice for the
CPC are provided in the response body, and HTTP status code 200 (OK) is returned. The details cover as
much of the requested time period as is available.

If the request URI does not identify a CPC object to which the API user has object-access permission,
HTTP status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC object identified in the request URI.
v Action/task permission to the Energy Optimization Advisor task.

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 844.

Otherwise, 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 337. Get Energy Optimization Advice Details: 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 The user under which the API request was authenticated does not have the
required authority to perform the requested action.
404 (Not Found) 1 The request URI does not designate an existing CPC, or it designates a CPC
for which the API user does not have object-access permission.
4 The object designated by the request URI does not support the requested
operation.
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.
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.

Chapter 12. Energy management 847

 Level 04a

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/a44d8ab8-e68e-3a07-9bff-e484a62ca00d/operations/get-energy-optimization-
advice-summary HTTP/1.1
x-api-session: 2z7xak1rm55fqu2o48h5btjsu5rwqtexyuxrmvcn51rzbsxi6w

Figure 452. Get Energy Optimization Advice Details: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 08 Mar 2016 19:30:21 GMT
content-type: application/json;charset=UTF-8
content-length: 511
{
"advice":[
{
"status":"above-threshold",
"summary":"The ambient temperature is above the current threshold of 23.0\u00b0C
(73.4\u00b0F). If the ambient temperature is lowered below the identified
threshold, the system power consumption will be reduced by approximately 126 W.",
"timestamp":1457031003347,
"type":"environmental"
},
{
"status":"high-utilization",
"summary":"Based on processor utilization there are no system power consumption
recommendations.",
"timestamp":1448991133600,
"type":"processor-utilization"
}
]
}

Figure 453. Get Energy Optimization Advice Details: Response

Energy Management for BladeCenter object

Data model
The data model for a BladeCenter object includes some properties related to energy management. These
properties are described in Chapter 14, “zBX infrastructure elements,” on page 881, under the data model
for the BladeCenter object: “Energy Management Related Additional Properties” on page 944.

Operations
Set BladeCenter Power Save
Use the Set BladeCenter Power Save operation to set the power save setting of a BladeCenter.

HTTP method and URI

POST /api/bladecenters/{bladecenter-id}/operations/set-power-save

In this request, the URI variable {bladecenter-id} is the object ID of the BladeCenter.

848 HMC Web Services API

 Level 04a

Request body contents

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

Field name Type Rqd/Opt Description

power-saving String Required The possible settings are:
Enum v "high-performance" - The power consumption and performance of
the BladeCenter are not reduced. This is the default setting.
v "low-power" - Low power consumption for all components of the
BladeCenter enabled for power saving.
v "custom" - Components may have their own settings changed
individually. No component settings are actually changed when
this mode is entered.

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

Description
Use this operation to control the average energy consumption of a BladeCenter object designated by
{bladecenter-id}, or to remove a power consumption limit for this object. You can closely manage power
allocations within the physical limits of your data center.

This operation will always fail if the designated BladeCenter is under group control (see “Group
capping” on page 820) or the power-saving property of the BladeCenter is set to "not-supported"or
"not-entitled". (See “Energy Management Related Additional Properties” on page 944 for details on this
property.) In addition, this operation is only available if the ensemble is functioning at the Automate
management enablement level.

The action to change the power-saving settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job
has completed, an asynchronous result message is sent, with Job status and reason codes described in
“HTTP status and reason codes.” After completion, the Query Job Status operation may be used to
retrieve the completion results.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to all blade, BladeCenter, CPC and zCPC objects
v Action/task permission to the Power Save 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.”

Otherwise, 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 12. Energy management 849

 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.
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({bladecenter-id}) does not designate an existing
BladeCenter object, or the API user does not have object-access permission to
the object.
409 (Conflict) 1 The operation cannot be performed because the object designated by the
request URI is not in the correct state.

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

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the
BladeCenter hardware
162 Communication error occurred while trying to access the BladeCenter
hardware
163 An error occurred at one or more children

If the job reason code is 163, the job-results field provided by the Query Job Status operation will
contain an object with the following fields:

Field name Type Description

errors Object array A list of error objects, containing detailed error information about errors
occurred on children
at-least-one- Boolean True indicates that the operation was successful for at least one child.
operation-succeed

Each error object has this structure:

Job reason
Job status codes code Description
object-uri String URI The canonical URI path for a specific object where the error occurred
reason-code Integer Specify the specific error type, possible values are:
v 160 - A firmware error occurred while executing the operation
v 161 - A hardware error occurred while performing the energy
management operation
v 162 - Communication error occurred while trying to access the hardware
message String A non localized message provided for development purposes only. Client
applications should not display this message directly to the user.

850 HMC Web Services API

 Level 04a

Set BladeCenter Power Capping

Use the Set BladeCenter Power Capping operation to set the power capping settings of a BladeCenter.

HTTP method and URI

POST /api/bladecenters/{bladecenter-id}/operations/set-power-capping

In this request, the URI variable {bladecenter-id} is the object ID of the BladeCenter.

Request body contents

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

Field name Type Rqd/Opt Description

power-capping- String Required The possible settings are:
state Enum v "disabled" - The power cap of the BladeCenter is not set and the
peak power consumption is not limited. This is the default setting.
v "enabled" - Capping all components of the BladeCenter available
for power capping to limit the peak power consumption of the
BladeCenter.
v "custom" - Individually configure the components of the
BladeCenter for power capping. No component settings are
actually changed when this mode is entered.
power-cap-current Integer Optional Specifies the current cap value for the BladeCenter in watts (W). The
current cap value indicates the power budget for the BladeCenter.

This field is only required if the power-capping-state field is set to

"enabled". The power-cap-current must be between
power-cap-minimum and power-cap-maximum:

power-cap-minimum <= value <= power-cap-maximum

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

Description
Use this operation to limit the peak power consumption of a BladeCenter object designated by
{bladecenter-id}, or to remove a power consumption limit for this object. You can closely manage power
allocations within the physical limits of your data center.

This operation will always fail if the designated BladeCenter is under group control (see “Group
capping” on page 820) or the power-capping-state property of the BladeCenter is set to "not-supported"
or "not-entitled". (See “Energy Management Related Additional Properties” on page 944 for details on
this property.) In addition, this operation is only available if the ensemble is functioning at the Automate
management enablement level.

The action to change the power-capping settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job

Chapter 12. Energy management 851

 Level 04a

has completed, an asynchronous result message is sent, with Job status and reason codes described in
“HTTP status and reason codes.” After completion, the Query Job Status operation may be used to
retrieve the completion results.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to all blade, BladeCenter, CPC and zCPC objects
v Action/task permission to the Power Capping 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 851.

Otherwise, 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.
400 (Bad Request) 7 The power-cap-current field contains a value that is not in the range
power-cap-minimum ... power-cap-maximum
5 The power-cap-current field is not set, but power-capping-state field is set to
"enabled".
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({bladecenter-id}) does not designate an existing
BladeCenter object, or the API user does not have object-access permission to
the object.
409 (Conflict) 1 The operation cannot be performed because the object designated by the
request URI is not in the correct state.

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

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the
BladeCenter hardware
162 Communication error occurred while trying to access the BladeCenter
hardware
163 An error occurred at one or more children

If the job reason code is 163, the job-results field provided by the Query Job Status operation will
contain an object with the following fields:
852 HMC Web Services API
 Level 04a

Field name Type Description

errors Object array A list of error objects, containing detailed error information about errors
occurred on children
at-least-one- Boolean True indicates that the operation was successful for at least one child.
operation-succeed

Each error object has this structure:

Job reason
Job status codes code Description
object-uri String URI The canonical URI path for a specific object where the error occurred
reason-code Integer Specify the specific error type, possible values are:
v 160 - A firmware error occurred while executing the operation
v 161 - A hardware error occurred while performing the energy
management operation
v 162 - Communication error occurred while trying to access the hardware
message String A non localized message provided for development purposes only. Client
applications should not display this message directly to the user.

Energy Management for Blade object

Data model
The data model for a Blade object includes some properties related to energy management. These
properties are described in Chapter 14, “zBX infrastructure elements,” on page 881, under the data model
for the Blade object: “Energy management related additional properties” on page 961.

Operations
Set Blade Power Save
Use the Set Blade Power Save operation to set the power save setting of a blade.

HTTP method and URI

POST /api/blades/{blade-id}/operations/set-power-save

In this request, the URI variable {blade-id} is the object ID of the blade.

Request body contents

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

Field name Type Rqd/Opt Description

power-saving String Required The possible settings are:
Enum v "high-performance" - The power consumption and performance of
the blade are not reduced. This is the default setting.
v "low-power" - Low power consumption for all components of the
blade enabled for power saving.

Chapter 12. Energy management 853

 Level 04a

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

Description
Use this operation to control the average energy consumption of a Blade object designated by {blade-id},
or to remove a power consumption limit for this object. You can closely manage power allocations within
the physical limits of your data center.

This operation will always fail if the designated blade is under group control (see “Group capping” on
page 820) or the power-saving property of the blade is set to "not-supported" or "not-entitled". (See
“Energy management related additional properties” on page 961 for details on this property.) In addition,
this operation is only available if the ensemble is functioning at the Automate management enablement
level.

The action to change the power-saving settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job
has completed, an asynchronous result message is sent, with Job status and reason codes described below.
After completion, the Query Job Status operation may be used to retrieve the completion results.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to all blade, BladeCenter, CPC and zCPC objects
v Action/task permission to the Power Save 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.”

Otherwise, 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.
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({blade-id}) does not designate an existing Blade
object, or the API user does not have object-access permission to the object.
409 (Conflict) 1 The operation cannot be performed because the object designated by the
request URI is not in the correct state.

854 HMC Web Services API

 Level 04a

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

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the blade
hardware
162 Communication error occurred while trying to access the blade hardware

Set Blade Power Capping

Use the Set Blade Power Capping operation to set the power capping settings of a blade.

HTTP method and URI

POST /api/blades/{blade-id}/operations/set-power-capping

In this request, the URI variable {blade-id} is the object ID of the blade.

Request body contents

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

Field name Type Rqd/Opt Description

power-capping- String Required The possible settings are:
state Enum v "disabled" - The power cap of the blade is not set and the peak
power consumption is not limited. This is the default setting.
v "enabled" - Capping all components of the blade available for
power capping to limit the peak power consumption of the blade.
power-cap-current Integer Optional Specifies the current cap value for the blade in watts (W). The current
cap value indicates the power budget for the blade.

This field is only required if the power-capping-state field is set to

"enabled". The power-cap-current must be between
power-cap-minimum and power-cap-maximum:

power-cap-minimum <= value <= power-cap-maximum

Response body contents

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

Field name Type Description

job-uri String URI of the asynchronous job that may be queried to retrieve status updates
for action initiated by this operation.

Chapter 12. Energy management 855

 Level 04a

Description
Use this operation to limit the peak power consumption of a Blade object designated by {bladecenter-id}, or
to remove a power consumption limit for this object. You can closely manage power allocations within
the physical limits of your data center.

This operation will always fail if the designated blade is under group control (see “Group capping” on
page 820) or the power-capping-state property of the blade is set to "not-supported" or "not-entitled".
(See “Energy management related additional properties” on page 961 for details on this property.) In
addition, this operation is only available if the ensemble is functioning at the Automate management
enablement level.

The action to change the power-capping settings occurs asynchronously. If the request is accepted, an
asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body
includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of
the Query Job Status operation for information on how to query job status. When the asynchronous job
has completed, an asynchronous result message is sent, with Job status and reason codes described below.
After completion, the Query Job Status operation may be used to retrieve the completion results.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to all blade, BladeCenter, CPC and zCPC objects
v Action/task permission to the Power Capping 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 855.

Otherwise, 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.
400 (Bad Request) 7 The power-cap-current field contains a value that is not in the range
power-cap-minimum ... power-cap-maximum
5 The power-cap-current field is not set, but power-capping-state field is set to
"enabled".
403 (Forbidden) 1 The user is not authorized to access the object or perform this task.
3 The server is not entitled to perform energy management.
404 (Not Found) 1 The object ID in the URI ({blade-id}) does not designate an existing Blade
object, or the API user does not have object-access permission to the object.
409 (Conflict) 1 The operation cannot be performed because the object designated by the
request URI is not in the correct state.

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

856 HMC Web Services API

 Level 04a

Job status and reason codes

Job reason
Job status codes code Description
200 (OK) N/A Operation executed successfully
500 (Server Error) 160 A firmware error occurred while executing the operation
161 A hardware error occurred while performing the operation on the blade
hardware
162 Communication error occurred while trying to access the blade hardware

Chapter 12. Energy management 857

 Level 04a

858 HMC Web Services API

 Level 04a

Part 4. Ensemble and zBX management

Topics in this part describe ensemble and zBX management.

Topics covered in this part are:

v Chapter 13, “Ensemble composition,” on page 861
v Chapter 14, “zBX infrastructure elements,” on page 881
v Chapter 15, “Virtualization management,” on page 985
v Chapter 16, “Storage management,” on page 1139
v Chapter 17, “Virtual network management,” on page 1199
v Chapter 18, “Workload resource group management,” on page 1215

© Copyright IBM Corp. 2017, 2018 859

 Level 04a

860 HMC Web Services API

 Level 04a

Chapter 13. Ensemble composition

An ensemble is a grouping of one or more computing systems, referred to as nodes, that are managed in
a coordinated way for purposes of virtualization and workload management. Currently, the ensemble can
be comprised of zEnterprise (or later) Central Processing Complex (CPC) nodes and their associated
system resources or zBX nodes. Each CPC node consists of the traditional Z elements (processors,
memory, I/O, LPARs) along with an optional CPC-attached processor feature termed an IBM zEnterprise
BladeCenter Extension (zBX) (model 003 or earlier) that provides blade-based computing resources.
Starting with IBM z BladeCenter Extension (zBX) Model 004, rather than being treated as part of a CPC
node, a zBX instead appears as a distinct ensemble node of its own that provides those blade-based
resources. In addition to the per-member resources, the ensemble also encompasses certain
ensemble-wide resources that are shared by all of the members of the ensemble, including a secure,
platform-managed data network.

An ensemble will typically consist of at least one node. However, when initially created, an ensemble
starts out with no nodes, so an empty ensemble is a legitimate configuration that may sometimes exist.
CPCs or zBX nodes are explicitly added as nodes to, or removed from, an ensemble using operations
provided in the API or using management tasks on the HMC UI.

Not all models of Z processors support ensembles and ensemble-based management. Platform support
for ensembles and ensemble-based management was first delivered with the zEnterprise family.

For purposes of controlling the configuration and operational state of the elements of an ensemble, each
ensemble is managed from a customer-designated primary/alternate pair of Hardware Management
Consoles (HMC) that is referred to as the ensemble HMCs for that ensemble. At any one point in time,
only one HMC of the pair is in an active primary role, with the second of the pair acting strictly as a
passive backup or alternate. The primary ensemble HMC may manage at most one ensemble. The
primary ensemble HMC is the component that provides the main administrative user interface for the
ensemble, and it is the component that acts as the access point for the majority of the Web Services API.
However, a selected set of API function is also available from the alternate HMC.

For purposes of this definition, it is usually sufficient to focus on the primary ensemble HMC only, except
when specifically considering aspects that pertain to the setup of the primary/alternate pair or handling
the failover mechanism. Therefore, use of the term “ensemble HMC” without further primary or alternate
qualification should be interpreted as indicating the primary ensemble HMC.

Note: Properties related to the identity and addressing of the alternate HMC for the ensemble managed
by the current HMC are provided as part of the data model for the Console object.

Ensemble composition operations summary

The following tables provide an overview of the ensemble composition operations provided.
Table 338. Ensemble composition: operations summary
Operation name HTTP method and URI path
“List Ensembles” on GET /api/ensembles
page 865
“Get Ensemble GET /api/ensembles/{ensemble-id}
Properties” on page
867

© Copyright IBM Corp. 2017, 2018 861

 Level 04a

Table 338. Ensemble composition: operations summary (continued)

Operation name HTTP method and URI path
“Update Ensemble POST /api/ensembles/{ensemble-id}
Properties” on page
869
“List Ensemble GET /api/ensembles/{ensemble-id}/nodes
Nodes” on page 871
“Get Node Properties” GET /api/ensembles/{ensemble-id}/nodes/{node-id}
on page 873
“Add Node to POST /api/ensembles/{ensemble-id}/nodes
Ensemble” on page
875
“Remove Node from DELETE /api/ensembles/{ensemble-id}/nodes/{node-id}
Ensemble” on page
878

Table 339. Ensemble composition: URI variables

Variable Description
{ensemble-id} Object ID (UUID) of an Ensemble object
{node-id} Element ID of a node of an Ensemble.

Ensemble object
An ensemble object represents a single ensemble.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
including the operational-status properties, with the following class-specific specialization:
Table 340. Ensemble object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/ The canonical URI path for an ensemble object is of the form
URI /api/ensembles/{ensemble-id} where {ensemble-id} is the value of the
object-id property of the ensemble object.
parent — String/ An ensemble object is conceptually a root object and has no parent, so
URI this property is always null.
class — String The class of an ensemble object is "ensemble".
name (w)(pc) String The display name specified for the ensemble. Alphanumeric, space, or
(1-16) any of “+<=>%&*\"'(),_-./:;?” are valid characters.
description (w)(pc) String Text describing the Ensemble. Alphanumeric, space, or any of
(0-128) “+<=>%&*\"'(),_-./:;?” are valid characters.
status (sc) String The status of the ensemble representing the current communication
Enum status between the primary and alternate HMC:
v "alternate-communicating" – The primary is communicating to the
alternate
v "alternate-not-communicating" - The primary is not communicating
to the alternate
additional-status — String An ensemble object has no additional-status.
Enum

862 HMC Web Services API

 Level 04a

Class specific additional properties

In addition to the properties defined in included schemas, this object includes the following additional
class-specific properties:
Table 341. Ensemble object: class specific properties
Name Qualifier Type Description
management- (pc) String The zManager management enablement level for this ensemble.
enablement-level Enum The level determines which zManager advanced management
functions are available for use. Values:
v "manage"- Gives you the basics for managing an ensemble. It
includes HMC operational controls for zBX, change management
of firmware across the ensemble, energy monitoring, virtual
networking with automated provisioning, virtual server
management, and a base level of performance management.
v "automate"- Provides more leverage from the ensemble by
managing workloads and energy. This level of support includes
power capping, power savings mode, and platform performance
management.
cpu-perf-mgmt- (w)(pc) Boolean If true, management of processor performance is enabled for x
enabled-x-hyp Hyp virtualization hosts. Management of processor performance is
also available for virtual servers.

Performance management properties may be updated if the

ensemble management-enablement-level is "automate".
cpu-perf-mgmt- (w)(pc) Boolean If true, management of processor performance is enabled for
enabled-power-vm PowerVM virtualization hosts. Management of processor
performance is also available for virtual servers.

Performance management properties may be updated if the

ensemble management-enablement-level is "automate".
cpu-perf-mgmt- (w)(pc) Boolean If true, management of processor performance is enabled for z/VM
enabled-zvm virtualization hosts. Management of processor performance is also
available for virtual servers.

Performance management properties may be updated if the

ensemble management-enablement-level is "automate".
unique-local-unified- (pc) String Unique local address (ULA) prefix applied to addresses used for
prefix management communication between virtual servers and their
virtualization hosts.

The ULA prefix of the form fdXX:XXXX:XXXX::/48 is formed by

substituting the X's with a pseudo-random 40-bit global ID using
the algorithm defined in RFC 4193.

The prefix may not be updated through the API.

load-balancing- (w)(pc) Boolean If true, Load Balancing is enabled for this ensemble.
enabled
Load Balancing properties may be updated if the ensemble
management-enablement-level is "automate".
load-balancing-port (w)(pc) Integer The Load Balancing port value in the range 1024-65534. The
(1024- default port is 3860.
65535)
Load Balancing properties may be updated if the ensemble
management-enablement-level is "automate".

Chapter 13. Ensemble composition 863

 Level 04a

Table 341. Ensemble object: class specific properties (continued)

Name Qualifier Type Description
load-balancing-ip- (w)(pc) Array of The IPV4 address or IPV6 addresses of Load Balancers allowed
addresses String access to the Load Balancing function.

The strings are in dotted-decimal form (“nnn.nnn.nnn.nnn”) for

IPV4 addresses.

The strings are in eight groups of four hexadecimal digits

separated by colons (e.g.
2001:0db8:85a3:0000:0000:8a2e:0370:7334), for IPV6 addresses.

Load Balancing properties may be updated if the ensemble

management-enablement-level is "automate".
mac-prefix (pc) String (2) The Prefix Address xx:00:00:00:00:00/8 is the ensemble mac prefix.
All Mac addresses dynamically generated by zManager will be
within the ensemble mac prefix. xx defaults to 02.

The MAC prefix may not be updated through the API.

reserved-mac-address- (pc) Array of The list of reserved MAC address prefixes. Each reserved MAC
prefixes objects address prefix will be an object in the form of a MAC address
prefix nested object, as described in “MAC address prefix nested
object.”

MAC address prefixes may not be updated through the API.

max-nodes — Integer The maximum number of nodes allowed in the ensemble.
max-cpc-nodes — Integer The maximum number of CPC nodes allowed in the ensemble.
max-zbx-nodes — Integer The maximum number of BXs (either CPC-attached or nodes)
allowed in the ensemble.

Energy management related additional properties: In addition to the properties defined above, this
object includes the following additional class-specific properties related to energy management. For
further explanation of the various states involved, please see “Special states” on page 819,
Table 342. Ensemble composition: energy management related additional properties
Name Qualifier Type Description
power-rating — Integer Specifies the maximum power usage in watts (W) of this ensemble. This
is a calculated value as indicated by the electrical rating labels or system
rating plates of the ensemble components.
power- (mg) Integer Specifies the current power consumption in watts (W) for this ensemble.
consumption

MAC address prefix nested object: A MAC address prefix object is a nested object of an ensemble
object. An ensemble may contain zero or more MAC address prefixes. MAC address prefix properties
may not be updated through the API.

The following properties are supported:

Table 343. Ensemble composition: MAC address prefix nested object related additional properties
Field name Type Description
mac-address String The MAC address represented as 6 groups of two hexadecimal digits separated by
colons, e.g. 01:23:45:67:89:ab. The MAC address uses the ensemble prefix.

864 HMC Web Services API

 Level 04a

Table 343. Ensemble composition: MAC address prefix nested object related additional properties (continued)
Field name Type Description
prefix-length Integer The bit length of the MAC address prefix. This is a 2-digit value with these
parameters in the range 12-44.

Node object
A node is an element of the ensemble object that represents a system that is currently a member of the
ensemble. Each node contains the following properties:
Table 344. Ensemble composition: node properties
Field name Type Description
element-uri String/ The URI path for a node of an ensemble is of the form /api/ensembles/{ensemble-
URI id}/nodes/{node-id} where {ensemble-id} is the value of the object-id property of the
ensemble, and {node-id} is a locally unique element ID for the node.

For nodes of type "cpc", {node-id} is the value of the object-id property of the CPC
that is represented by the node.

For nodes of type "zbx", {node-id} is the value of the object-id property of the zBX
node that is represented by the node.
parent String/ The canonical URI path of the ensemble containing this node.
URI
class String (4) The value "node".
type String This is the type of node. Nodes have the following types:
Enum v "cpc"
v "zbx"
member String/ The canonical URI path of the system element that is represented as a member of the
URI ensemble by this object.

For nodes of type "cpc", this is the URI path of the CPC object.

For nodes of type "zbx", this is the URI path of the zBX node object.

Operations
List Ensembles
The List Ensembles operation lists the ensembles managed by the HMC.

HTTP method and URI

GET /api/ensembles

Query parameters

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) used to limit returned objects. If
matches are found, the response will be an array with all ensembles
that match. If no match is found, the response will be an empty
array.

Chapter 13. Ensemble composition 865

 Level 04a

Response body contents

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

Field name Type Description

ensembles Array of Array of nested ensemble-info objects (described in the next table). If the
objects HMC is not a primary HMC, an empty array is provided.

Each nested ensemble-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the Ensemble object, in the form /api/ensembles/
URI {ensemble-id}.
name String Display name of the Ensemble object.
status String The status property of the Ensemble object.
Enum

Description
This operation lists the ensembles that are managed by this HMC. The object URI, display name, and
status are provided for each.

If the name query parameter is specified, the returned list is limited to those ensembles that have a name
property matching the specified filter pattern. If the name parameter is omitted, this filtering is not done.

An ensemble is included in the list only if the API user has object-access permission for that object. If an
HMC is a manager of an ensemble but the API user does not have permission to it, that object is simply
omitted from the list but no error status code results.

If the HMC does not manage any ensembles, an empty list is provided and the operation completes
successfully.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to any ensemble 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.”

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.

866 HMC Web Services API

 Level 04a

Usage notes
This operation, as well as other aspects of the Web Services API, has been structured to allow for the
possibility that an HMC might be the manager of multiple ensembles. However, in the current
implementation, an HMC can be the manager of at most one ensemble, so the resulting list of ensembles
will contain either zero or one entries.

Example HTTP interaction

GET /api/ensembles HTTP/1.1

x-api-session: 1f2g70m2e9b4sawt53ydp1oc9nzzs4sduc2wr2bzgmy5dhs7pz

Figure 454. List Ensembles: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 20 Jul 2011 18:41:03 GMT
content-type: application/json;charset=UTF-8
content-length: 207
{
"ensembles": [
{
"name": "R32Ensemble",
"object-uri": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026",
"status": "alternate-communicating"
}
]
}

Figure 455. List Ensembles: Response

Get Ensemble Properties

The Get Ensemble Properties operation retrieves the properties of a single Ensemble object that is
designated by its object ID.

HTTP method and URI

GET /api/ensembles/{ensemble-id}

In this request, the URI variable {ensemble-id} is the object ID of the Ensemble object for which properties
are to be obtained.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the ensemble object as defined in the data model section above. 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 operation returns the current properties for the ensemble object specified by {ensemble-id}.

On successful execution, all of the current properties as defined by the data model for the Ensemble
object are provided in the response body, and HTTP status code 200 (OK) is returned.

Chapter 13. Ensemble composition 867

 Level 04a

The URI path must designate an existing ensemble 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.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Ensemble object designated by {ensemble-id}.

HTTP status and reason codes

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

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 object-id in the URI ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.

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/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026 HTTP/1.1

x-api-session: 1f2g70m2e9b4sawt53ydp1oc9nzzs4sduc2wr2bzgmy5dhs7pz

Figure 456. Get Ensemble Properties: Request

868 HMC Web Services API

 Level 04a

200 OK
x-request-id: Sx3a Rx1
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 20 Jul 2011 18:41:03 GMT
content-type: application/json;charset=UTF-8
content-length: 959
{
"acceptable-status": [
"alternate-communicating"
],
"class": "ensemble",
"cpu-perf-mgmt-enabled-power-vm": true,
"cpu-perf-mgmt-enabled-zvm": true,
"description": "",
"has-unacceptable-status": false,
"is-locked": false,
"load-balancing-enabled": true,
"load-balancing-ip-addresses": [
"1.1.1.1"
],
"load-balancing-port": 9876,
"mac-prefix": "02:00:00:00:00:00",
"management-enablement-level": "automate",
"name": "R32Ensemble",
"object-id": "87d73ffc-75b2-11e0-9ba3-0010184c8026",
"object-uri": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026",
"parent": null,
"power-consumption": 8311,
"power-rating": 46522,
"reserved-mac-address-prefixes": [
{
"mac-address": "02:c1:00:00:00:00",
"prefix-lenght": 16
}
],
"status": "alternate-communicating",
"unique-local-unified-prefix": "fd07:8c9:1ba3:0:0:0:0:0"
}

Figure 457. Get Ensemble Properties: Response

Update Ensemble Properties

The Update Ensemble Properties operation modifies simple writable properties of an ensemble object.

HTTP method and URI

POST /api/ensembles/{ensemble-id}

In this request, the URI variable {ensemble-id} is the object ID of the Ensemble object for which properties
are to be updated.

Request body contents

The request body is expected to contain a JSON object with one or more of the following fields. Only
fields that are being changed are necessary to supply.

Chapter 13. Ensemble composition 869

 Level 04a

Field name Type Description

name String (1-16) The new name to give the ensemble, as described in “Data model” on page
862.
description String The new description to give the ensemble, as described in “Data model” on
(0-128) page 862.
cpu-perf-mgmt- Boolean The PowerVM virtualization host processor performance management
enabled-power-vm enablement setting, as described in “Data model” on page 862.
cpu-perf-mgmt- Boolean The z/VM virtualization host processor performance management
enabled-zvm enablement setting, as described in “Data model” on page 862.
load-balancing- Boolean The Load Balancing enablement setting for this ensemble, as described in
enabled “Data model” on page 862.
load-balancing-port Integer The Load Balancing port for this ensemble, as described in “Data model” on
page 862.
load-balancing-ip- Array of The Load Balancing ip addresses, as described in “Data model” on page 862.
address Strings

Description
This operation updates one or more simple writable properties of the ensemble object identified by
{ensemble-id}.

On successful execution, the ensemble object has been updated with the supplied property values and
status code 204 (No Content) is returned without supplying a response body.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

The URI path must designate an ensemble 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. In addition, the API
user must also have permission to the Ensemble Details task as well, otherwise status code 403
(Forbidden) is returned.

The request body is validated against the schema described in the request body contents section. If the
request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Ensemble object designated by {ensemble-id}
v Action/task permission to the Ensemble 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

870 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.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
228 The ensemble's management-enablement-level property does not allow the
updating of a property specified in the request body.
404 (Not Found) 1 The object ID in the URI ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.
409 (Conflict) 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.

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/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334 HTTP/1.1

x-api-session: 297n8iun1251svgcju9tvsai0rrew4ieawx97ykucbxy69bwr2
content-type: application/json
content-length: 34
{
"name": "SS-Ensemble-1"
}

Figure 458. Update Ensemble Properties: Request

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

<No response body>

Figure 459. Update Ensemble Properties: Response

List Ensemble Nodes

The List Ensemble Nodes operation lists the nodes of an ensemble managed by the HMC.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/nodes

In this request, the URI variable {ensemble-id} is the object ID of the Ensemble object for which nodes are
to be listed.

Chapter 13. Ensemble composition 871

 Level 04a

Response body contents

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

Field name Type Description

nodes Array of Array of nested node-info objects (described in the next table). If the
objects ensemble has no nodes, an empty array is provided.

Each nested node-info object contains the following fields:

Field name Type Description

element-uri String/URI URI path of the ensemble node object, in the form /api/ensembles/
{ensemble-id}/nodes/{node-id}.

For a node of type "cpc", the node object represents a CPC as a member of
the ensemble, and the {node-id} component of this URI path is the object-id
property of the underlying CPC object.

For a node of type "zbx", the node object represents a zBX node as a
member of the ensemble, and the {node-id} component of this URI path is the
object-id property of the underlying zBX node object.
type String The type property of the underlying object that is represented by the node.
Enum
name String The name property of the underlying object that is represented by the node
status String The status property of the underlying object that is represented by the node
Enum

Description
This operation lists the nodes of an ensemble specified by its {ensemble-id}. The element URI and type are
provided for each.

A node is included in the list only if the API user has object-access permission to the underlying object
that is represented by the node. For a node of type "cpc", the underlying object is a CPC. For a node of
type "zbx", the underlying object is a BX node. If an ensemble contains a node but the API user does not
have permission to the related object, that object is simply omitted from the list but no error status code
results.

If the ensemble is empty (has no nodes), 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 ensemble designated in the request URI
v Object-access permission to the underlying object that is represented by a node included in the result.
For nodes of type "cpc", the underlying object is a CPC. For nodes of type "zbx", the underlying object
is a zBX node.

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.”

872 HMC Web Services API

 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 object ID in the URI ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.

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/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes HTTP/1.1

x-api-session: 1f2g70m2e9b4sawt53ydp1oc9nzzs4sduc2wr2bzgmy5dhs7pz

Figure 460. List Ensemble Nodes: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 20 Jul 2011 18:41:03 GMT
content-type: application/json;charset=UTF-8
content-length: 250
{
"nodes": [
{
"element-uri": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-
8466- be79e49dd340",
"name": "R32",
"status": "operating",
"type": "cpc"
}
]
}

Figure 461. List Ensemble Nodes: Response

Get Node Properties

The Get Node Properties operation retrieves the properties of a single Node object.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/nodes/{node-id}

URI variables

Variable Description
{ensemble-id} Object ID of the ensemble containing the node for which properties are to be obtained.
{node-id} Element ID of the node which for which properties are to be obtained.

Chapter 13. Ensemble composition 873

 Level 04a

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the node object as defined in “Data model” on page 862. 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 operation returns the current properties for the node object specified by the request URI.

On successful execution, all of the current properties as defined by the data model for the Ensemble
object are provided in the response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing node 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.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble designated in the request URI
v Object-access permission to the underlying object that is represented by a node included in the result.
For nodes of type "cpc", the underlying object is a CPC.

HTTP status and reason codes

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

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

HTTP error status 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 ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.
225 The element-id in the URI ({node-id}) does not designate an existing node of
the ensemble designed by {ensemble-id}.
227 The element-id in the URI ({node-id}) does not designate an existing object, or
the API user does not have access permission to it.

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

874 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-e79e49dd340 HTTP/1.1

x-api-session: 1f2g70m2e9b4sawt53ydp1oc9nzzs4sduc2wr2bzgmy5dhs7pz

Figure 462. Get Node Properties: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 20 Jul 2011 18:41:03 GMT
content-type: application/json;charset=UTF-8
content-length: 295
{
"class": "node",
"element-uri": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-
be79e49dd340",
"member": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026",
"type": "cpc"
}

Figure 463. Get Node Properties: Response

Add Node to Ensemble

The Add Node to Ensemble operation adds a CPC or zBX node to an ensemble, creating a new Node
object to represent the membership as a result.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/nodes

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object to which the CPC or
zBX node is to be added as a node.

Request body contents

The request body is a JSON object requiring exactly one of the following fields:

Field name Type Description

cpc String/URI The canonical URI path identifying the CPC to be added to the targeted
ensemble as a new node. If this field is provided, the member field is not
allowed.
member String/URI The canonical URI path of the system element that is represented as a
member of the ensemble by this object.

If a CPC is to be added, this is the URI path of a CPC object. If a zBX node
is to be added, this is the URI path of a zBX object that has a type property
with value "node". If this field is provided, the cpc field is not allowed.

Response body contents

Field name Type Description
node-uri String/URI The canonical URI path identifying the node that was created in the targeted
ensemble, in the form /api/ensembles/{ensemble-id}/nodes/{node-id}.

Chapter 13. Ensemble composition 875

 Level 04a

Description
This operation adds a CPC or zBX node to the ensemble targeted by the request URI and creates a new
Node object to represent the membership. Refer to the Ensemble Planning Guide for details on managing
members of an ensemble.

All ensemble nodes must have the same management-enablement-level. A node with a
management-enablement-level of "automate" may be added to an ensemble with a management-
enablement-level of "manage", but the node (not the ensemble) will be downgraded to a
management-enablement-level of "manage". To later upgrade a downgraded node, all the other nodes in
the ensemble must have their management-enablement-level upgraded to "automate" (achieved by
installing the appropriate LICCC records on the nodes).

Upon successful completion, HTTP status code 201 (Created) is returned and the response body includes
the URI of the node that was created to represent the membership. This URI is also provided as the value
of the Location header in the response.

If the CPC is already a node of an ensemble (either the targeted ensemble or another one) HTTP status
code 400 (Bad Request) is returned with associated reason code 224.

The URI path must designate an existing ensemble 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. In addition, the API
user must also have action/task permission to the Add Member to Ensemble task as well, otherwise
status code 403 (Forbidden) is returned. Additionally if the CPC or zBX node is ineligible to be added to
the ensemble a status code 409 (Conflict) is returned.

The request body is validated against the schema described in “Request body contents” on page 875. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI
v Object-access permission to the CPC or zBX node object passed in the request body.
v Action/task permission to the Add Member to Ensemble 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” on page 875.

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.

876 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.
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).
221 The operation cannot be performed because the CPC or zBX node to be
added as a member is not an eligible machine model.
222 The operation cannot be performed because the CPC does not have the
Ensemble without zBX Feature or the zBX Feature installed.
224 The operation cannot be performed because the CPCor zBX node is a
member of another ensemble or already a member of the ensemble targeted
in the request URI.
229 The operation cannot be performed because the maximum number of CPCs
would be exceeded for the ensemble.
230 A CPC or zBX node may be added to an Ensemble only if the LICCC QoS
value of the CPC or zBX node is the same as or is higher than the
aggregated QoS of the Ensemble.
232 The operation cannot be performed because the maximum number of zBXs
would be exceeded for the ensemble.
233 The operation cannot be performed because the maximum number of nodes
would be exceeded for the ensemble.
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 ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.
227 The object-id in the URI of the CPC or zBX node object in the request body
does not designate an existing object, or the API user does not have access
permission to it.
409 (Conflict) 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.
220 The operation cannot be performed because the CPC or zBX node to be
added as a member is currently busy performing some other operation.
223 The operation cannot be performed because the CPC or zBX node to be
added as a member is not in the correct state to be added to the ensemble.
The CPC cannot be added if the CPC or zBX node operational status is
"not-communicating".
226 The operation cannot be performed because the CPC or zBX node object to
be added as a member is currently locked to prevent disruptive changes
from being made.

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

Chapter 13. Ensemble composition 877

 Level 04a

Usage notes
v This operation continues to support the "cpc" input field for compatibility when adding a CPC to an
ensemble. However, you should use the "member" input field for a more general approach to add
either a CPC or zBX node to an ensemble.
v When a node's management-enablement-level is downgraded to "manage", management functions
requiring a higher management-enablement-level can no longer be executed. Such functions, like
Energy Management, will no longer be available.

Remove Node from Ensemble

The Remove Node from Ensemble operation removes a node from an ensemble.

HTTP method and URI

DELETE /api/ensembles/{ensemble-id}/nodes/{node-id}

URI variables

Variable Description
{ensemble-id} Object ID of the ensemble from which the targeted node is to be removed as a member.
{node-id} Element ID of the node which is to be removed from the targeted ensemble.

Description
This operation removes a specified node from the specified ensemble. The node is identified by the
{node-id} variable in the URI, and the ensemble is identified by the {ensemble-id} variable in the request
URI.

Refer to the Ensemble Planning Guide for details on managing members of an ensemble.

Upon successfully removing the node as a member, HTTP status code 204 (No Content) is returned.

The URI path must designate an existing ensemble object and the API user must have object-access
permission to it. Furthermore, the URI path must designate an existing node element. If any of these
conditions is not met, status code 404 (Not Found) is returned. In addition, the API user must also have
Remove Member from Ensemble action/task permission as well, otherwise status code 403 (Forbidden) is
returned. Additionally if the CPC or zBX node is ineligible to be removed from the ensemble a status
code 409 (Conflict) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI
v Object-access permission to the system element represented by the node element. For nodes of type
"cpc", this is a CPC object. For nodes of type "zbx", this is a zBX node object.
v Action/task permission to the Remove Member from Ensemble 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

878 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.
225 The operation cannot be performed because the node ({node-id}) to be
removed is not a member of the ensemble ({ensemble-id}) designated by the
request URI.
231 The operation cannot be performed because the node ({node-id}) to be
removed has entitled blades.
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 ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.
227 The element-id in the URI ({node-id}) does not designate an existing object, or
the API user does not have access permission to it.
409 (Conflict) 2 The operation cannot be performed because the object ({ensemble-id})
designated by the request URI is currently busy performing some other
operation.
3 The operation cannot be performed because the object ({ensemble-id})
designated by the request URI is currently locked to prevent disruptive
changes from being made.
220 The operation cannot be performed because the node ({node-id}) to be
removed as a member is currently busy performing some other operation.
223 The operation cannot be performed because the node ({node-id}) to be
removed as a member is not in the correct state to be removed from the
ensemble. The node cannot be removed if the operational status is
"not-communicating".
226 The operation cannot be performed because the node to be removed as a
member is currently locked to prevent disruptive changes from being made.

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

Inventory service data

Information about the Ensembles managed by the HMC and the associated nodes can be optionally
included in the inventory data provided by the Inventory Service.

Inventory entries for ensemble and node objects are included in the response to the Inventory Service's
Get Inventory operation when the request specifies (explicitly by class, implicitly via a containing
category, or by default) that objects of class "ensemble" are to be included. Information for a particular
ensemble (and associated node) is included only if the API user has object-access permission to that
object.

For each ensemble to be included, the inventory response array includes the following:
v An array entry for the ensemble object itself. This entry is a JSON object with the same contents as is
specified in the response body contents section for the Get Ensemble Properties operation. That is, the
data provided is the same as would be provided if a Get Ensemble Properties operation were
requested targeting this object.
v An array entry for each node associated with the ensemble. For each such node, an entry is included
that is a JSON object with the same contents as specified in the response body contents section of the

Chapter 13. Ensemble composition 879

 Level 04a

Get Ensemble Properties operation. As a result, the data provided is the same as would be obtained if
a Get Node Properties operation were requested for each node listed by a List Ensemble Nodes
operation targeting the ensemble.

The array entry for an ensemble object will appear in the results array before entries for associated nodes.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe an ensemble (named "R32Ensemble") with a single node as member. These objects
would appear as a sequence of array entries in the response array:

{
"acceptable-status": [
"alternate-communicating"
],
"class": "ensemble",
"cpu-perf-mgmt-enabled-power-vm": false,
"cpu-perf-mgmt-enabled-zvm": true,
"description": "FVT Test",
"has-unacceptable-status": false,
"is-locked": false,
"load-balancing-enabled": true,
"load-balancing-ip-addresses": [
"1.1.1.1"
],
"load-balancing-port": 9876,
"mac-prefix": "02:00:00:00:00:00",
"management-enablement-level": "automate",
"name": "R32Ensemble",
"object-id": "87d73ffc-75b2-11e0-9ba3-0010184c8026",
"object-uri": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026",
"parent": null,
"power-consumption": 8298,
"power-rating": 46288,
"reserved-mac-address-prefixes": [],
"status": "alternate-communicating",
"unique-local-unified-prefix": "fd07:8c9:1ba3:0:0:0:0:0"
},
{
"class": "node",
"element-uri": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-
be79e49dd340",
"member": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026",
"type": "cpc"
}

Figure 464. Ensemble object: Sample inventory data

Usage notes
When configured as recommended by IBM, the process of recovering from the failure of the primary
ensemble-management HMC by takeover by the alternate HMC includes movement of the IP address of
the former primary to the new primary. When this occurs, explicit redirection of API requests to the
newly designated primary HMC is not needed. However, the IP address swapping may not be possible
in certain network configurations. The address of the alternate ensemble-management HMC for the
current Ensemble is provided as properties of the Console object (representing the current HMC) to allow
applications to explicitly redirect requests to the other HMC of the pair in these cases.

880 HMC Web Services API

 Level 04a

Chapter 14. zBX infrastructure elements

An ensemble is a grouping of one or more CPC nodes and optional IBM z BladeCenter Extension (zBX)
Model 004 nodes that are managed together in a coordinated way for purposes of virtualization and
workload management. CPC members of the ensemble may also have optional CPC-attached IBM
zEnterprise BladeCenter Extension (zBX) Model 002 or 003 features if supported by the processor model.

A zBX, in either Model 004 node form, or the Model 002 or 003 CPC-attached or node form, has as its
key components one or more BladeCenter chassis, one or more Blades and VLAN-capable switches all
mounted in dedicated racks. Each zBX is connected to other members of the ensemble through a
dedicated and integrated data network. In addition, the components of a zBX are connected to their
controlling Support Element (either in the associated CPC for a zBX Model 002 or 003, or within the zBX
node itself for a zBX Model 004) through a dedicated and integrated management network.

Within the ensemble, advanced management capabilities are provided for the blades housed within the
zBX. The zBX components are configured, managed and serviced in the same way as the other
components of a CPC. Management of the zBX is provided onlyvia the controlling Support Element when
the CPC or zBX node is a member of an ensemble.

zBX physical network overview

The zBX contains physical network switches that provide the connectivity between the blades and CPCs
in the Intra-Ensemble 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) – A pair of ESMs reside in each BladeCenter chassis and connect the
blades in the zBX to the IEDN and provide the links to the TORs.

The initial configuration and setup of the physical switches are provided by zManager. The ESMs are not
accessible for configuration changes through the Web Services API, however, performance metrics are
provided through the Metrics Service. Some TOR management will typically be required by an external
administrator; therefore, when managing virtual networks, administrators must consider requirements for
configuring the Top-of-Rack switch ports. Only certain types of TOR ports support configuration by the
zManager user, these are:
v External - Ports that connect to a customer's external network.
v Internal - Ports are internal ports that extend to the ESMs which connect to the blades. The
configuration of this type of port is intended only to support the ISAOPT Coordinator. In this case,
VLAN- tagging is required to allow traffic from ISAOPT to Z to be tagged with the proper VLAN ID.

The configuration properties supported by these ports are:

v Virtual networks - The following port types can be configured to a virtual network:
– External
– Internal
v MAC Filters – The following port types support MAC filters:
– External

© Copyright IBM Corp. 2017, 2018 881

 Level 04a

zBX infrastructure operations summary

The following tables provide an overview of the operations provided.
Table 345. zBX infrastructure: operations summary
Operation name HTTP method and URI path
“List zBXs of a CPC” on page GET /api/cpcs/{cpc-id}/zbxs
891
“List zBXs of an Ensemble” GET /api/ensembles/{ensemble-id}/zbxs
on page 894
“Get zBX Properties” on page GET /api/zbxs/{zbx-id}
896
“Get EC/MCL Description of GET /api/zbxs/{zbx-id}/operations/get-ec-mcl-description
zBX (Node)” on page 899
“Activate zBX (Node)” on POST /api/zbxs/{zbx-id}/operations/activate
page 902
“Deactivate zBX (Node)” on POST /api/zbxs/{zbx-id}/operations/deactivate
page 905
“Get zBX (Node) Audit Log” GET /api/zbxs/{zbx-id}/operations/get-audit-log
on page 907
“Get zBX (Node) Security GET /api/zbxs/{zbx-id}/operations/get-security-log
Log” on page 909
“List zBX (Node) Hardware GET /api/zbxs/{zbx-id}/hardware-messages
Messages” on page 912
“Get zBX (Node) Hardware GET /api/zbxs/{zbx-id}/hardware-messages/{hardware-message-id}
Message Properties” on page
915
“Delete zBX (Node) DELETE /api/zbxs/{zbx-id}/hardware-messages/{hardware-message-id}
Hardware Message” on page
917
“List Top-of-Rack Switches of GET /api/zbxs/{zbx-id}/top-of-rack-switches
a zBX” on page 921
“Get Top-of-Rack Switch GET /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}
Properties” on page 924
“Get Top-of-Rack Switch Port GET /api/zbxs/{zbx_id}/top-of-rack-switches/{tor-id}/ports/{port-id}
Details” on page 926
“Update Top-of-Rack Switch POST/api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}
Port Properties” on page 928
“Add MAC Filters to POST /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}/
Top-of-Rack Switch Port” on operations/add-mac-filters
page 930
“Remove MAC Filters from POST /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}/
Top-of-Rack Switch Port” on operations/remove-mac-filters
page 932
“Add Top-of-Rack Switch POST /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}/
Port to Virtual Networks” on operations/add-virtual-networks
page 934
“Remove Top-of-Rack Switch POST /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}/
Port from the Virtual operations/remove-virtual-networks
Networks” on page 936

882 HMC Web Services API

 Level 04a

Table 345. zBX infrastructure: operations summary (continued)

Operation name HTTP method and URI path
“List Racks of a zBX” on GET /api/zbxs/{zbx-id}/racks
page 939
“Get Rack Properties” on GET /api/racks/{rack-id}
page 941
“List BladeCenters in a Rack” GET /api/racks/{rack-id}/bladecenters
on page 947
“List BladeCenters in a zBX” GET /api/zbxs/{zbx-id}/bladecenters
on page 949
“Get BladeCenter Properties” GET /api/bladecenters/{bladecenter-id}
on page 951
“Activate BladeCenter” on POST /api/bladecenters/{bladecenter-id}/operations/activate
page 953
“Deactivate BladeCenter” on POST /api/bladecenters/{bladecenter-id}/operations/deactivate
page 956
“List Blades in a GET /api/bladecenters/{bladecenter-id}/blades
BladeCenter” on page 964
“List Blades in a zBX” on GET /api/zbxs/{zbx-id}/blades
page 966
“Get Blade Properties” on GET /api/blades/{blade-id}
page 969
“Activate a Blade” on page POST /api/blades/{blade-id}/operations/activate
973
“Deactivate a Blade” on page POST /api/blades/{blade-id}/operations/deactivate
975
“Create IEDN Interface for a POST /api/blades/{blade-id}/iedn-interfaces
DataPower XI50z Blade” on
page 977
“Delete IEDN Interface for a DELETE /api/blades/{blade-id}/iedn-interfaces/{iedn-interface-id}
DataPower XI50z Blade” on
page 980

Table 346. zBX infrastructure: URI variables

Variable Description
{cpc-id} Object ID of a CPC
{zbx-id} Object ID of a zBX
{tor-id} Element ID of a TOR object
{port-id} Element ID of a TOR port
{rack-id} Object ID of a Rack
{bladecenter-id} Object ID of a BladeCenter
{blade-id} Object ID of a Blade
{iedn-interface-id} Element ID of an IEDN Interface

zBX object
A zBX object represents a zBX. The zBX may be a zBX Model 004 ensemble node (referred to as a zBX
node), or a CPC-attached zBX Model 003 or earlier.

Chapter 14. zBX infrastructure elements 883

 Level 04a

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
including the operational-status properties when representing a zBX node, with the following
class-specific specialization:
Table 347. zBX object: base managed object properties specializations
Name Qualifier Type Description of specialization
name (ro) String The name of the ZBX. If the value of the type property is
(1-64) "cpc-attached", the name is assigned by zManager as 21 characters
of the form <machine type>-<machine model>-<machine serial
number> of the zBX object.1

If the value of the type property is "node", the name of the zBX is
assigned during installation.
description — String The description property of the zBX object.
object-uri — String/ The canonical URI path for a zBX object is of the form
URI /api/zbxs/{zbx-id}, where {zbx-id} is the value of the object-id
property of the zBX object.
parent — String/ The URI path of the parent of this zBX.
URI
It the value of the type property is "cpc-attached", this property
provides the canonical URI path of the parent CPC object.

If the value of the type property is "node":

v If the zBX is a member of an ensemble, this property contains the
canonical URI path for the Ensemble object.
v Otherwise, the value of this property is null.
class — String The class of a zBX object has the value "zbx".
status (sc) String The current operational status of the zBX object. One of:
Enum v "operating" – all blades and all BladeCenter chassis of the zBX
have a status of "operating". A blade with a status of "no-power"
state results in zBX status of "exceptions". A blade with a status of
"service" is excluded from summarized status for the zBX which
would not affect the zBX having a status of "operating".
v "not-communicating" - the HMC is not communicating with the
Support Element of the zBX.
v "exceptions" – at least one blade or BladeCenter chassis has a
status not equal to 'operating'. Objects with a status of "service"
are excluded.
v "status-check" - the Primary SE is not communicating with the
zBX (or all blades and all BladeCenter chassis have a status of
"status-check").
v "service" – the zBX has been placed in service mode.
v "no-power" - all blades in all BladeCenter chassis of the zBX have
a status of "no-power". The power state of each BladeCenter
chassis is not part of this summary status.
v "service-required" – service is required for the zBX. It is operating
on the last redundant part of a particular type.

This property is provided only if the value of the type property is

"node", otherwise it is omitted.
acceptable-status (w)(pc) Array of The set of operational status values in which the zBX object can exist
String and be considered in an acceptable (not alert causing) state. One or
Enum more of the values listed for the status property.

This property is provided only if the value of the type property is

"node", otherwise it is omitted.

884 HMC Web Services API

 Level 04a

Table 347. zBX object: base managed object properties specializations (continued)
Name Qualifier Type Description of specialization
1
Note: This name property for a CPC-attached zBX is currently assigned by zManager and is not writable.
However, it is possible that the API could be extended to allow this property to be writable, in which case an API
or User-Interface user could change the name to contain arbitrary data. Therefore, API client applications should not
rely on the contents and format of the name property always being in the form of the zManager-assigned name.

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties (regardless of the value of the type property):
Table 348. zBX object: class specific properties
Name Qualifier Type Description
type — String The type of the zBX:
Enum v "cpc-attached"
v "node"
machine-type — String (4) The type of the zBX. For example, 2458.
machine-model — String (3) The model of the zBX. For example, 004.
machine-serial — String (12) The serial number of the zBX. For example, 000002001234.
current-isaopt- — Integer Number of blades entitled as ISAOPT blades.
entitlements
max-isaopt- — Integer Maximum licensed to be entitled as ISAOPT blades.
entitlements
current-power- — Integer Number of blades entitled as POWER7® blades.
entitlements
max-power- — Integer Maximum licensed to be entitled as POWER7 blades.
entitlements
current-systemx- — Integer Number of blades entitled as System x IBM blades.
entitlements
max-systemx- — Integer Maximum licensed to be entitled as System x blades.
entitlements
current-dpxi50z- — Integer Number of blades entitled as DataPower XI50z blades.
entitlements
max-dpxi50z- — Integer Maximum licensed to be entitled as DataPower XI50z blades.
entitlements

In addition to the properties defined in the previous table, if the value of the type property of the zBX is
"node", the zBX object also includes the following additional class-specific properties:
Table 349. zBX object: class specific additional properties (for zBX node)
Name Qualifier Type Description
se-version (pc) (String 1-8) The current release level of the primary SE licensed internal
code. For example, "2.13.0". Note that the alternate SE is
usually at the same level, except when installing new licensed
internal code levels.
has-hardware- (pc) Boolean The zBX node object has hardware messages (true), or does
messages not have hardware messages (false).
is-ensemble-member (pc) Boolean Whether the zBX node is currently part of an ensemble (true)
or not (false).

Chapter 14. zBX infrastructure elements 885

 Level 04a

Table 349. zBX object: class specific additional properties (for zBX node) (continued)
Name Qualifier Type Description
is-service-required — Boolean Whether the zBX node is operating using the last redundant
part of a particular type (true) or not (false). If true, repairs
should be made before additional parts fail that would make
this zBX node non-operational.
ec-mcl-description — ec-mcl-
description Describes the Engineering Change (EC) and MicroCode Level
object (MCL) for the zBX node. Refer to the description of
ec-mcl-description for details.

It may take a significant amount of time for the HMC API to

provide this information when requested. Because of this, and
because of the specialized nature of this information, the
EC/MCL information is omitted from the response to Get zBX
Properties and from inventory data for the zBX, and instead
the value of this property is null for those operations. Clients
can use the Get EC/MCL Description of zBX (Node)
operation to obtain the value of this property when required.
has-automatic-se- — Boolean Automatic switching between primary and alternate Support
switch-enabled Elements is enabled for the zBX node object (true), or is not
enabled (false).

Support Element (Version 2.12.1 and newer) information can

be found on console help system. For information about
earlier versions of the Support Element, see the Support
Element Operations Guide.
lan-interface1-type (pc) String Enum The adapter type of the Support Element's LAN interface 1.
One of the following:
v "ethernet"
v "token-ring"
v "unknown"
lan-interface1- (pc) String (12) The MAC address of the Support Element's LAN interface 1.
address The address is provided without any embedded colon
separators (example: "f0def14b63af").
lan-interface2-type (pc) String Enum The adapter type of the Support Element's LAN interface 2.
One of the following:
v "ethernet"
v "token-ring"
v "unknown"
lan-interface2- (pc) String (12) The MAC address of the Support Element's LAN interface 2.
address The address is provided without any embedded colon
separators (example: "f0def14b63af").
network1-ipv4-mask (pc) String (1-15) The network IP mask value.
network1-ipv4-pri- (pc) String IPV4 The primary IPv4 address or a null object if not configured.
ipaddr address
network1-ipv4-alt- (pc) String IPV4 The alternate IPv4 address or a null object if not configured.
ipaddr address
network1-ipv6-info — Array of A list of objects describing the Support Element's IPv6
ipv6-info network connections. If no IPv6 connections are defined, an
objects empty list is returned.
network2-ipv4-mask (pc) String (1-15) The network IP mask value.
network2-ipv4-pri- (pc) String IPV4 The primary IPv4 address or a null object if not configured.
ipaddr address

886 HMC Web Services API

 Level 04a

Table 349. zBX object: class specific additional properties (for zBX node) (continued)
Name Qualifier Type Description
network2-ipv4-alt- (pc) String IPV4 The alternate IPv4 address or a null object if not configured.
ipaddr address
network2-ipv6-info — Array of A list of objects describing the Support Element's IPv6
ipv6-info network connections. If no IPv6 connections are defined, an
objects empty list is returned.
management- (pc) String Enum The zManager management enablement level for this zBX
enablement-level node. The management-enablement-level values of an
ensemble's CPC and zBX node members of the ensemble
determine the ensemble's management-enablement-level,
which determines the zManager advanced management
functions that are available for use.

All ensemble nodes must have the same management-

enablement-level. A CPC or zBX node with a
management-enablement-level of "automate" may be added
to an ensemble with a management-enablement-level of
"manage", but this will downgrade the system's
management-enablement-level until all ensemble nodes are
upgraded to "automate".

Note: if status is "not-communicating", or if the target zBX

node is not in an Ensemble, a null object is returned.

Values:
v "manage" - Provides the basic capabilities for managing an
ensemble. It includes HMC operational controls for change
management of firmware across the ensemble, energy
monitoring, virtual networking with automated
provisioning, virtual server management, and a base level of
performance management.
v "automate" - Provides more leverage from the ensemble by
managing workloads and energy. This level of support
includes power capping, power savings mode, and platform
performance management.
hardware-messages (c)(pc) Array of The complete list of all zBX node hardware messages, each
hardware- identified by its URI. This list corresponds to the list provided
message by the List zBX (Node) Hardware Messages operation. If the
objects zBX node has no hardware messages, then an empty array is
provided.

The list of returned hardware messages can change as a result

of the new messages being dynamically added or removed by
the infrastructure or due to hardware messages being deleted
via the Delete zBX (Node) Hardware Message operation.
Note: This property is not returned by the Get zBX Properties
operation or included in Inventory Service results for the zBX
object, and only sessions associated with an HMC user with
permission to the Hardware Messages task will receive a
property-change notification for this property.

Each ec-mcl-description nested object and its related action, ec and mcl nested objects have the properties
shown in the following tables:

Chapter 14. zBX infrastructure elements 887

 Level 04a

Table 350. zBX object: ec-mcl-description nested object properties (for zBX node)
Name Type Description
action Array of An optional array of pending action objects. This field is only provided
action objects when the HMC is communicating with the zBX node's SE.
ec Array of ec An optional array of EC objects. This field is only provided when the
objects HMC is communicating with the zBX node's SE.

Table 351. zBX object: action nested object properties (for zBX node)
Name Type Description
type String Enum Valid values are:
v "zhybrid-blades-activation" - zHybrid accelerator blades are pending
an activation.
v "channel-config" - Channels are currently pending a Config On/Off.
v "coupling-facility-reactivation" - There is at least one coupling
facility pending reactivation.
v "power-on-reset-tracking" - There is a need to perform a
power-on-reset.
activation String Enum One of:
v "current" - The action is for the current activation.
v "next" - The action is for the next install and activation.
pending Boolean Indicates whether the action is pending (true) or not pending (false).

Table 352. zBX object: ec nested object properties (for zBX node)
Name Type Description
number String (1-6) Engineering Change stream identifier.
part-number String (1-8) Engineering Change stream part number.
type String (1-32) Engineering Change stream name.
description String (1-65) Engineering Change stream descriptive text.
mcl Array of mcl The list of MicroCode Levels for this Engineering Change.
objects

Table 353. zBX object:mcl nested object properties (for zBX node)
Name Type Description
type String Enum One of:
v "retrieved" - A retrieved or staged level.
v "activated" - An activated or applied level.
v "accepted" - A committed level.
v "installable-concurrent" - A non-disruptive apply-able level.
v "removable-concurrent" - A non-disruptive reject-able level.
level String (1-3) MicroCode Level.
last-update Timestamp Time stamp of the last update, in the number of milliseconds since
midnight January 1, 1970 UTC. A null object is returned if no updates
have occurred.

Each ipv6-info nested object has the following properties:

888 HMC Web Services API

 Level 04a

Table 354. zBX object: ipv6-info properties (for zBX node)

Name Type Description
type String Enum The IPv6 scope. One of the following values:
v "link-local"
v "static"
v "auto"
prefix Integer The number of leading bits of the IPv6 address that represent the
network prefix.
pri-ip-address String IPv6 The primary IPv6 address.
address
alt-ip-address String IPV6 The alternate IPv6 address or a null object if not configured.
address

Each hardware-message nested object has the following properties:

Table 355. zBX object: hardware-message object properties (for zBX node)
Name Type Description
element-uri String/URI The canonical URI path of the zBX node hardware message.
The URI is in the following form: /api/zbxs/{zbx-id}/
hardware-messages/{hardware-message-id}, where
{hardware-message-id} is the value of the element-id property
of the hardware message.
element-id String (36) The unique identifier for the hardware message. The
element-id is in the form of a UUID.
parent String/URI The parent of a zBX (Node) hardware message is the zBX
Node object. The parent value is the canonical URI path for
the zBX (Node).
class String The class of a hardware-message object is
"hardware-message".
timestamp Timestamp The timestamp represents the date and time when the
hardware message was created.
text String The text of the hardware message.

Energy Management Related Additional Properties

In addition to the class-specific additional properties defined in the previous section, if the value of the
type property is “node”, the zBX object also includes the following additional class-specific properties
related to energy management. For further explanation of the various states involved, see Chapter 12,
“Energy management,” on page 817.
Table 356. zBX object: energy management related additional properties (for zBX node)
Name Qualifier Type Description
power-rating — Integer Specifies the maximum power usage of this zBX node in watts (W).
This value is a calculated value, as indicated by the electrical rating
labels or system rating plates of the zBX node components.
power- (mg) Integer Specifies the current power consumption in watts (W) of this zBX
consumption node. The zBX power consumption includes the power consumption
of the blades contained within all BladeCenter chassis and the shared
infrastructure.

Chapter 14. zBX infrastructure elements 889

 Level 04a

Table 356. zBX object: energy management related additional properties (for zBX node) (continued)
Name Qualifier Type Description
power-saving — String Specifies the current power saving setting of the zBX node. Power
Enum saving reduces the energy consumption of a system, and can be
managed it using the Set Power Saving operation. The possible
settings include:
v "high-performance" - Specifies not reducing the power
consumption and performance of the zBX node. This is the default
setting.
v "low-power" - Specifies low power consumption for all components
of the zBX node enabled for power saving.
v "custom" - Specifies that some, but not all, components of the zBX
node are in the Low power setting.
v "not-supported" - Specifies that power saving is not supported for
this zBX node.
v "not-available" - Specifies that power-saving property could not be
read from this zBX node.
v "not-entitled' - Specifies that the server is not entitled to power
saving.
power-saving-state — String Specifies whether power saving is supported and entitled for the zBX
Enum node set by the user. Note that this property indicates the user setting
and may not match the real state of the hardware compared to the
power-saving property. For more information, see “Group power
saving” on page 820. The possible settings include:
v "high-performance" - Specifies not reducing the power
consumption and performance of the zBX node. This setting will be
applied to all children.
v "low-power" - Specifies low power consumption for all components
of the zBX node enabled for power saving.
v "custom" - Specifies that the zBX node does not control the
children. This is the default setting.
v "not-supported" - Specifies that power saving is not supported for
this zBX node.
v "not-entitled' - Specifies that the server is not entitled to power
saving.
power-save- — String Should be used to determine if a call of the power save operation is
allowed Enum currently allowed. If a value other than "allowed" is returned the
caller may reckon that the power save operation will fail.

The possible settings include:

v "allowed" - Alter power save setting is allowed for this zBX node
v "unknown" - Unknown reason
v "not-entitled" - Specifies the server is not entitled to power saving.
v "not-supported" - Specifies that power saving is not supported for
this zBX node.

890 HMC Web Services API

 Level 04a

Table 356. zBX object: energy management related additional properties (for zBX node) (continued)
Name Qualifier Type Description
power-capping- — String Specifies the current power capping setting of the zBX node. Power
state Enum capping limits peak power consumption of a system, and you can
manage it by using the Set Power Cap operation. The possible
settings include:
v "disabled" - Specifies not setting the power cap of the zBX node
and not limiting the peak power consumption. This is the default
setting.
v "enabled" - Specifies capping all components of the zBX node
available for power capping to limit the peak power consumption
of the zBX node.
v "custom" - The components of the zBX node can be individually
configured for power capping.
v "not-supported" - Specifies that power capping is not supported for
this zBX node.
v "not-entitled" - Specifies that the server is not entitled to power
capping.
power-cap- — Integer Specifies the minimum value for the zBX node cap value in watts
minimum (W). This is a sum of the component minimum cap values.
power-cap- — Integer Specifies the maximum value for the zBX node cap value in watts
maximum (W). This is a sum of the component maximum cap values.
power-cap-current — Integer Specifies the current cap value for the zBX node in watts (W). The
current cap value indicates the power budget for the zBX node and is
the sum of the component Cap values.
power-cap- — String Should be used to determine if a call of the power capping operation
allowed Enum is currently allowed. If a value other than "allowed" is returned the
caller may reckon that the power capping operation will fail.

The possible settings include:

v "allowed" - Alter power capping setting is allowed for this zBX
node
v "unknown" - Unknown reason
v "not-entitled" - Specifies the server is not entitled to power
capping.
v "not-supported" - Specifies that power capping is not supported for
this zBX node.
ambient- (mg) Float Specifies the input air temperature in degrees Celsius (ºC) as
temperature measured by the system.
exhaust- — Float Specifies the exhaust air temperature in degrees Celsius (ºC) as
temperature calculated by the system. This is useful in determining potential hot
spots in the data center.

Operations
List zBXs of a CPC
The List zBXs of a CPC operation lists the CPC-attached zBXs associated with the CPC. The CPC must
be a member of an ensemble.

Chapter 14. zBX infrastructure elements 891

 Level 04a

HTTP method and URI

GET /api/cpcs/{cpc-id}/zbxs

In this request, the URI variable {cpc-id} is the object ID of the CPC object whose zBXs are to be obtained.

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) used to limit returned objects

Response body contents

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

Field name Type Description

zbxs Array of Array of nested zbx-info objects, described in the next table. If no zBXs
objects are returned, an empty array is provided.

Each nested zbx-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the zBX object in the form /api/zbxs/{zbx-id}.
URI
name String The name property of the zBX object (based on its machine type, machine
model, and machine serial number).
type String The type property of the zBX object.
Enum

Description
The List zBXs of a CPC operation lists the CPC-attached zBXs that are associated with this CPC. The
object URI and name are provided for each zBX.

If the name query parameter is specified, then a zBX is included in the list only if the name pattern
matches the name property of the object.

A zBX is included in the list only if the API user has object-access permission for the CPC with which the
zBX is associated. If the HMC is a manager of a zBX, but the API user does not have permission to it,
that object is omitted from the list, but no error status code results.

If the CPC does not have a zBX, an empty list is provided and the operation completes successfully. Note
that if the CPC is not a member of an ensemble, it cannot have a zBX. Therefore, an empty list is
provided.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the CPC object specified by the request URI.

892 HMC Web Services API

 Level 04a

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 892.

Otherwise, 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.
241 CPC object ({cpc-id}) is not a member of an ensemble.
404 (Not Found) 1 The object ID {cpc-id} does not designate an existing CPC object, or the API
user does not have object-access permission to it.
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.

Usage notes
v This operation has been structured to allow for the possibility that multiple CPC-attached zBXs might
be associated with a CPC. However, in the current implementation, each CPC can have at most one
zBX. Therefore, the resulting list of zBXs will contain either zero or one entry.

Example HTTP interaction

GET /api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/zbxs HTTP/1.1

x-api-session: 5q07hx6jgp2ngn2cypq1zxot76sfwnzky0ih8nddd5hz6bpiue

Figure 465. List zBXs of a CPC: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 21 Jul 2011 17:48:58 GMT
content-type: application/json;charset=UTF-8
content-length: 160
{
"zbxs": [
{
"name": "2458-002-0000000ZBX26",
"object-uri": "/api/zbxs/54a9716c-a326-11e0-9469-001f163805d8"
}
]
}

Figure 466. List zBXs of a CPC: Response

Chapter 14. zBX infrastructure elements 893

 Level 04a

List zBXs of an Ensemble

The List zBXs of an Ensemble operation lists the zBXs, which are associated with each CPC in the
ensemble.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/zbxs

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object whose zBXs are to be
obtained.

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) used to limit returned objects
type String Optional Filter string used to limit returned objects to those that have a
Enum matching type property. Value must be a valid zBX type property
value.

Response body contents

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

Field name Type Description

zbxs Array of Array of nested zbx-info objects, described in the next table. If the
objects Ensemble does not have any CPCs or zBXs associated with it, an empty
array is provided.

Each nested zbx-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the zBX object in the form /api/zbxs/{zbx-id}.
URI
name String The name property of the zBX object.
type String Type of the zBX object.
Enum
status String The status property of the zBX object. This field is provided only if the
Enum value of the type property is "node"; otherwise, it is omitted.

Description
The List zBXs of an Ensemble operation lists the zBXs that are part of the ensemble. The object URI,
name, and type are provided for each zBX.

If the name query parameter is specified, then a zBX is included in the list only if the name pattern
matches the name property of the object.

If the type query parameter is specified, the parameter is validated to ensure it is a valid zBX type
property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid, the
returned list is limited to those zBXs that have a type property matching a specified type value. If the
type parameter is omitted, this filtering is not done.

894 HMC Web Services API

 Level 04a

A CPC-attached zBX is included in the list only if the API user has object-access permission for the CPC
object with which it is associated. A zBX node is included in the list only if the API user has object-access
permission to that object. If the HMC is a manager of a zBX, but the API user does not have this access
permission to it, that object is omitted from the list, but no error status code results.

If the HMC does not manage any zBXs, 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 Ensemble object passed in the request URI
v Object-access permission to the CPC objects with which a zBX is associated (for CPC-attached zBX
objects).
v Object-access permission to the zBX object (for zBX node objects).

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 894.

Otherwise, 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 {ensemble-id} does not designate an existing ensemble 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/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/zbxs HTTP/1.1

x-api-session: 5q07hx6jgp2ngn2cypq1zxot76sfwnzky0ih8nddd5hz6bpiue

Figure 467. List zBXs of an Ensemble: Request

Chapter 14. zBX infrastructure elements 895

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 21 Jul 2011 17:48:58 GMT
content-type: application/json;charset=UTF-8
content-length: 175
{
"zbxs": [
{
"name": "2458-002-0000000ZBX26",
"object-uri": "/api/zbxs/54a9716c-a326-11e0-9469-001f163805d8",
"type": "cpc-attached"
}
]
}

Figure 468. List zBXs of an Ensemble: Response

Get zBX Properties

The Get zBX Properties operation retrieves the properties of a single zBX object that is designated by its
object ID.

HTTP method and URI

GET /api/zbxs/{zbx-id}

In this request, the URI variable {zbx-id} is the object ID of the zBX object for which properties are to be
obtained.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the zBX object as defined in the “Data model” on page 884. 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 zBX Properties operation returns the current properties for the zBX object specified by {zbx-id}.

On successful execution, all of the current properties as defined in “Data model” on page 884 for the zBX
object are provided in the response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing zBX object. If the URI path designates a CPC-attached zBX, the
API user must have object-access permission to the CPC with which the zBX is associated. If the URI
path designates a zBX node, the API user must have object-access permission to that object. If these
conditions are not met, status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC objects with which the zBX is associated (for CPC-attached zBX
objects).
v Object-access permission to the zBX object (for zBX node objects).

896 HMC Web Services API

 Level 04a

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 896.

Otherwise, 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 {zbx-id} does not designate an existing zBX object, or the API
user does not have object-access permission to the CPC with which the zBX
is associated.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408 HTTP/1.1

x-api-session: 65815bpxckw5ejih51h67bt5zygjwrh8v34u33s9o5dg4atnnz

Figure 469. Get zBX Properties: Request

Chapter 14. zBX infrastructure elements 897

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 08 Sep 2014 17:28:10 GMT
content-type: application/json;charset=UTF-8
content-length: 2066
{
"acceptable-status": [
"operating"
],
"class": "zbx",
"current-dpxi50z-entitlements": 0,
"current-isaopt-entitlements": 0,
"current-power-entitlements": 0,
"current-systemx-entitlements": 0,
"description": "Defined zBX Node",
"ec-mcl-description": null,
"has-automatic-se-switch-enabled": false,
"has-hardware-messages": true,
"has-unacceptable-status": true,
"is-ensemble-member": true,
"is-service-required": false,
"lan-interface1-address": "40f2e910664e",
"lan-interface1-type": "ethernet",
"lan-interface2-address": "40f2e910664f",
"lan-interface2-type": "ethernet",
"machine-model": "004",
"machine-serial": "000002560057",
"machine-type": "2458",
"management-enablement-level": "manage",
"max-dpxi50z-entitlements": 7,
"max-isaopt-entitlements": 0,
"max-power-entitlements": 0,
"max-systemx-entitlements": 0,
"name": "P2560057",
"network1-ipv4-alt-ipaddr": "9.60.14.99",
"network1-ipv4-mask": "255.255.255.0",
"network1-ipv4-pri-ipaddr": "9.60.14.98",
"network1-ipv6-info": [
{
"alt-ip-address": "2002:93c:ffb:1:42f2:e9ff:fe10:708f",
"prefix": 64,
"pri-ip-address": "2002:93c:ffb:1:42f2:e9ff:fe10:664f",
"type": "auto"
},
{
"alt-ip-address": "fdd8:673b:d89b:1:42f2:e9ff:fe10:708f",
"prefix": 64,
"pri-ip-address": "fdd8:673b:d89b:1:42f2:e9ff:fe10:664f",
"type": "auto"
},
{
"alt-ip-address": "fe80::42f2:e9ff:fe10:708f%eth0",
"prefix": 64,
"pri-ip-address": "fe80::42f2:e9ff:fe10:664f%eth0",
"type": "link-local"
}
],

Figure 470. Get zBX Properties: Response (Part 1)

898 HMC Web Services API

 Level 04a

"network2-ipv4-alt-ipaddr": "9.60.15.99",
"network2-ipv4-mask": "255.255.255.0",
"network2-ipv4-pri-ipaddr": "9.60.15.98",
"network2-ipv6-info": [
{
"alt-ip-address": "fe80::42f2:e9ff:fe10:708e%eth1",
"prefix": 64,
"pri-ip-address": "fe80::42f2:e9ff:fe10:664e%eth1",
"type": "link-local"
}
],
"object-id": "ace3f861-3421-33d5-bcf4-f61f9057d408",
"object-uri": "/api/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408",
"parent": "/api/ensembles/2d6677f8-4b9e-11e3-96d7-42f2e90d2883",
"power-cap-allowed": "not-entitled",
"power-capping-state": "disabled",
"power-consumption": null,
"power-rating": null,
"power-save-allowed": "not-entitled",
"power-saving": "not-entitled",
"power-saving-state": "not-entitled",
"se-version": "2.13.0",
"status": "service",
"type": "node"
}

Figure 471. Get zBX Properties: Response (Part 2)

Get EC/MCL Description of zBX (Node)

The Get EC/MCL Description of zBX (Node) operation retrieves the value of the ec-mcl-description
property of a zBX node that is designated by its object ID.

HTTP method and URI

GET /api/zbxs/{zbx-id}/operations/get-ec-mcl-description

In this request, the URI variable {zbx-id} is the object ID of the zBX node for which EC/MCL information
is to be retrieved.

Response body contents

On successful completion, the response body is a JSON object that provides the current value of the
ec-mcl-description property for the zBX object. The response body object contains a single field named
ec-mcl-description with a value that is in the format described for the same-named property in the “Data
model” on page 884.

Description
The Get EC/MCL Description of zBX (Node) operation returns the current value of the
ec-mcl-description property for the zBX node object specified by {zbx-id}.

On successful execution, the value of the property as defined in “Data model” on page 884 is provided in
the response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing zBX node object and the API user must have object-access
permission to that object.

Chapter 14. zBX infrastructure elements 899

 Level 04a

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the zBX node object designated in the URI.

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 899.

Otherwise, 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 357. Get EC/MCL Description of zBX (Node): 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.
240 The object ID {zbx-id} designates a zBX object that is not a zBX node (that is,
does not have a type of "node").
404 (Not Found) 1 The object ID {zbx-id} does not designate an existing zBX node, or the API
user does not have object-access permission to the object.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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/zbxs/8dac6a58-935e-352c-996e-ded17dbf92c0/operations/get-ec-mcl-description HTTP/1.1

x-api-session: 470bbm7331p8nkpu5x1qasezo8apxyvclifznclktr07jej8x1

Figure 472. Get EC/MCL Description of zBX (Node): Request

900 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Thu, 02 Oct 2014 16:19:25 GMT
content-type: application/json;charset=UTF-8
content-length: 2473
{
"ec-mcl-description": {
"action": [
{
"activation": "current",
"pending": true,
"type": "zhybrid-blades-activation"
},
{
"activation": "next",
"pending": false,
"type": "zhybrid-blades-activation"
}
],
"ec": [
{
"description": "SE Framework",
"mcl": [
{
"last-update": null,
"level": "000",
"type": "retrieved"
},
{
"last-update": null,
"level": "000",
"type": "activated"
},
{
"last-update": null,
"level": "000",
"type": "accepted"
},
{
"last-update": null,
"level": "000",
"type": "installable-concurrent"
},
{
"last-update": null,
"level": "000",
"type": "removable-concurrent"
}
],
"number": "N98205",
"part-number": "00LY716",
"type": "Base EC"
},

Figure 473. Get EC/MCL Description of zBX (Node): Response (Part 1)

Chapter 14. zBX infrastructure elements 901

 Level 04a

{
"description": "BladeCenter Components",
"mcl": [
{
"last-update": null,
"level": "000",
"type": "retrieved"
},
{
"last-update": null,
"level": "000",
"type": "activated"
},
{
"last-update": null,
"level": "000",
"type": "accepted"
},
{
"last-update": null,
"level": "000",
"type": "installable-concurrent"
},
{
"last-update": null,
"level": "000",
"type": "removable-concurrent"
}
],
"number": "N98209",
"part-number": "00LY720",
"type": "Other Optional EC"
}
]
}
}

Figure 474. Get EC/MCL Description of zBX (Node): Response (Part 2)

Activate zBX (Node)

The Activate zBX (Node) operation activates all blades in all BladeCenter chassis in the zBX node
designated by its object ID. This operation is asynchronous.

HTTP method and URI

POST /api/zbxs/{zbx-id}/operations/activate

In this request, the URI variable {zbx-id} is the object ID of the zBX node object to activate.

Response body contents

Once the activation request is accepted, the response body contains a JSON object with the following
field:

Field name Type Description

job-uri String/ URI that may be queried to retrieve activation status updates. The
URI canonical URI path for zBX activation status updates is of the form
/api/jobs/{job-id}.

902 HMC Web Services API

 Level 04a

Asynchronous result description

Once the activation job 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 Activate zBX (Node) request.

The result document returned by the Query Job Status operation is specified in the description for the
Query Job Status operation. (For more information, see “Query Job Status” on page 80. 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) that are set. (See the description that follows.) The job-results field
is null for asynchronous zBX activation jobs.

Description
The Activate zBX (Node) operation activates all blades in all chassis in the zBX node object specified by
{zbx-id}. Activation brings blades into a state of "operating". If a blade is already powered on when the
activation operation is requested, the blade is powered off and then brought to a state of "operating". The
order in which the blades of the zBX are activated is unspecified. If the blade is a host to a virtualization
application, then this application is activated also. See “Activating a Virtualization Host” on page 1032 for
more information.

The URI path must designate an existing zBX 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. The zBX designated
by the URI path must be a zBX node (that is, have a type of "node") otherwise status code 400 (Bad
Request) is returned. In addition to having object-access permission to the zBX, the API user must also
have permission to the Activate task, otherwise status code 403 (Forbidden) is returned. The zBX must be
in the correct state to perform the activate action, otherwise status code 409 (Conflict) is returned.

When the zBX node activation job 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 activation job. See “Query Job
Status” on page 80 for information on how to query job status. When the activate job has completed, an
asynchronous result message is sent, with “Job status and reason codes” on page 904.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the zBX node object designated by {zbx-id} and all its BladeCenter chassis
and blades.
v Object-access permission to the Activate task.

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 902.

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.

Chapter 14. zBX infrastructure elements 903

 Level 04a

Table 358. Activate zBX (Node): 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.
240 The object ID {zbx-id} designates a zBX object that is not a zBX node (that is,
does not have a type of "node").
403 (Forbidden) 0 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID {zbx-id} does not designate an existing zBX object, or the API
user does not have object-access permission to it.
409 (Conflict) 1 The object ID {zbx-id} designates a zBX object that is not in the correct state
(status) for performing the requested operation.
244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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.

Job status and reason codes

Table 359. Activate zBX (Node): Job status and reason codes.
HTTP error status Reason
code code Description
200 (OK) N/A Activation completed successfully.
500 (Server Error) 100 zBX activation failed.
101 The zBX activation job timed out.

Example HTTP interaction

POST /api/zbxs/5e5b9b5e-3c76-3fac-8f82-d9b0055773fc/operations/activate HTTP/1.1

x-api-session: 1gtnlpz3ukld3es07mdnbsnsnrgss2xupmai32nkgvaysm5434

Figure 475. Activate zBX (Node): Request

202 Accepted
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Wed, 10 Sep 2014 18:14:40 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri": "/api/jobs/54e8e598-3916-11e4-8e38-02c00001303e"
}

Figure 476. Activate zBX (Node): Response

904 HMC Web Services API

 Level 04a

Deactivate zBX (Node)

The Deactivate zBX (Node) operation deactivates all blades in all BladeCenter chassis in the zBX node
specified by its object ID. This operation is asynchronous.

HTTP method and URI

POST /api/zbxs/{zbx-id}/operations/deactivate

In this request, the URI variable {zbx-id} is the object ID of the zBX node object to deactivate.

Response body contents

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

Field name Type Description

job-uri String/ URI that may be queried to retrieve deactivation status updates. The
URI canonical URI path for zBX deactivation status updates is of the form
/api/jobs/{job-id}.

Asynchronous result description

Once the deactivation job 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 Deactivate zBX (Node) request.

The result document returned by the Query Job Status operation is specified in the description for the
Query Job Status operation. (For more information, see “Query Job Status” on page 80. 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) that are set. (See the description that follows.) The job-results field
is null for asynchronous zBX deactivation jobs.

Description
The Deactivate zBX (Node) operation deactivates all blades in all BladeCenter chassis in the zBX node
object specified by {zbx-id}. Deactivation powers off all blades after an orderly shutdown of any hardware
and software activity running on the blades. The order in which the blades of the zBX are deactivated is
unspecified. If the blade is a host to a virtualization application, then this application is deactivated also.
See “Deactivating a Virtualization Host” on page 1033 for more information.

The URI path must designate an existing zBX 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. The zBX designated
by the URI path must be a zBX node (that is, have a type of "node") otherwise status code 400 (Bad
Request) is returned. In addition to having object-access permission to the zBX, the API user must also
have permission to the Deactivate task, otherwise status code 403 (Forbidden) is returned. The zBX must
be in the correct state to perform the deactivate action, otherwise status code 409 (Conflict) is returned.

When the zBX node deactivation job 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 deactivation job. See “Query Job
Status” on page 80 for information on how to query job status. When the deactivate job has completed,
an asynchronous result message is sent, with “Job status and reason codes” on page 906.

Authorization requirements
This operation has the following authorization requirement:

Chapter 14. zBX infrastructure elements 905

 Level 04a

v Object-access permission to the zBX node object specified by {zbx-id} and all its BladeCenter chassis and
blades.
v Object-access permission to the Deactivate task.

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 905.

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.
Table 360. Deactivate zBX (Node): 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.
240 The object ID {zbx-id} designates a zBX object that is not a zBX node (that is,
does not have a type of "node").
403 (Forbidden) 0 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID {zbx-id} does not designate an existing zBX object, or the API
user does not have object-access permission to it.
409 (Conflict) 1 The object ID {zbx-id} designates a zBX object that is not in the correct state
(status) for performing the requested operation.
244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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.

Job status and reason codes

Table 361. Dectivate zBX (Node): Job status and reason codes.
HTTP error status Reason
code code Description
200 (OK) N/A Deactivation completed successfully.
500 (Server Error) 100 zBX deactivation failed.
101 The zBX deactivation job timed out.

Example HTTP interaction

POST /api/zbxs/5e5b9b5e-3c76-3fac-8f82-d9b0055773fc/operations/deactivate HTTP/1.1

x-api-session: 5upqikkhel1vhasloh25bnhelekvemvnmhutc4kfegav9571zx

Figure 477. Deactivate zBX (Node): Request

906 HMC Web Services API

 Level 04a

202 Accepted
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Wed, 10 Sep 2014 18:12:50 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri": "/api/jobs/13308ef8-3916-11e4-bb52-02c00001303e"
}

Figure 478. Deactivate zBX (Node): Response

Get zBX (Node) Audit Log

The Get zBX (Node) Audit Log operation returns the zBX node's audit log, filtered according to the
query parameters, if specified.

HTTP method and URI

GET /api/zbxs/{zbx-id}/operations/get-audit-log

In this request, the URI variable {zbx-id} is the object ID of the target zBX node object.

Query parameters:

Name Type Req/Opt Description

begin-time Timestamp Optional A timestamp used to filter log entries. Entries created earlier than
this time are omitted from the results. This is specified as the
number of milliseconds since the epoch and must be greater than or
equal to 0. If not specified, then no such filtering is performed.
end-time Timestamp Optional A timestamp used to filter log entries. Entries created later than this
time are omitted from the results. This is specified as the number of
milliseconds since the epoch and must be greater than or equal to 0.
If not specified, then no such filtering is performed.

Response body contents

On successful completion, the response body is a JSON array of JSON objects returned using HTTP
chunked transfer encoding. Each array element is a log-entry-info object containing information about a
single log entry. The array elements are in order of increasing timestamp. See Table 267 on page 499 for
more information.

Description
This operation returns the zBX node's audit log in increasing timestamp order, filtered according to the
query parameters, if specified. Each log entry pertains to a specific event that occurred on or to a
managed object or the zBX node itself. The log entries can be limited by specifying explicit filtering
criteria on the request. If the begin-time query parameter is specified, then any entries earlier than that
time are omitted. If the end-time query parameter is specified, then any entries later than that time are
omitted.

The URI path must designate an existing zBX 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. The zBX must be a

Chapter 14. zBX infrastructure elements 907

 Level 04a

zBX node (that is, have a type of "node"); otherwise, status code 400 (Bad Request) is returned. In
addition, the API user must have action/task permission to the Audit and Log Management task;
otherwise, status code 403 (Forbidden) is returned.

On successful execution, the response body contains an array of filtered log entries. If the audit log is
empty or there are no entries to be returned after filtering, then an empty array is provided. Each log
entry contains the event ID, event name and event message. If there are data items included in the event
message, they are available separately. The order and meaning of the substitution items for each event ID
are documented on console help system in the HMC Introduction topic Audit, Event, and Security Log
Messages.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the zBX node object specified in the request URI.
v Action/task permission to the Audit and Log Management task.

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 907.

Otherwise, 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 362. Get zBX (Node) Audit Log: 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.
240 The request URI designates a zBX object that is not a zBX node (that is, does
not have a type of "node").
403 (Forbidden) 1 The API user does not have the required permission for this operation.
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.
4 The zBX node designated by the request URI does not support this
operation.
409 (Conflict 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.
500 (Server Error 307 The request timed out while attempting to communicate with the SE or
while attempting to get the log data.
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.

908 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408/operations/get-audit-log
HTTP/1.1
x-api-session: bp66qdtmjnofktpyw0f6hvsipo7skdv22vlaov70ecngc2kvn

Figure 479. Get zBX (Node) Audit Log: Request

200 OK
server: zSeries management console API web server / 2.0
transfer-encoding: chunked
cache-control: no-cache
date: Fri, 03 Oct 2014 01:19:54 GMT
content-type: application/json;charset=ISO-8859-1
[
{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"B.2.01"
}
],
"event-details":[],
"event-id":"3296",
"event-message":"Stop of hypervisor B.2.01 was triggered.",
"event-name":"HV-STOP",
"event-time":1411619111020,
"user-uri":"/api/users/146c44a0-a3fd-11e3-bfca-df30ad17ee78",
"userid":"HVADMIN"
},
{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"B.2.01"
}
],
"event-details":[],
"event-id":"3298",
"event-message":"Stop of hypervisor B.2.01 was successful.",
"event-name":"HV-STOP",
"event-time":1411619111970,
"user-uri":"/api/users/146c44a0-a3fd-11e3-bfca-df30ad17ee78",
"userid":"HVADMIN"
}
]

Figure 480. Get zBX (Node) Audit Log: Response

Get zBX (Node) Security Log

The Get zBX (Node) Security Log operation returns the zBX node's security log, filtered according to the
query parameters, if specified.

HTTP method and URI

GET /api/zbxs/{zbx-id}/operations/get-security-log

In this request, the URI variable {zbx-id} is the object ID of the target zBX node object.

Chapter 14. zBX infrastructure elements 909

 Level 04a

Query parameters:

Name Type Req/Opt Description

begin-time Timestamp Optional A timestamp used to filter log entries. Entries created
earlier than this time are omitted from the results. This is
specified as the number of milliseconds since the epoch
and must be greater than or equal to 0. If not specified,
then no such filtering is performed.
end-time Timestamp Optional A timestamp used to filter log entries. Entries created later
than this time are omitted from the results. This is
specified as the number of milliseconds since the epoch
and must be greater than or equal to 0. If not specified,
then no such filtering is performed.

Response body contents

On successful completion, the response body is a JSON array of JSON objects returned using HTTP
chunked transfer encoding. Each array element is a log-entry-info object containing information about a
single log entry. The array elements are in order of increasing timestamp. See Table 267 on page 499 for
more information.

Description
This operation returns the zBX node's security log in increasing timestamp order, filtered according to the
query parameters, if specified. Each log entry pertains to a specific event that occurred on or to a
managed object or the zBX node itself. The log entries can be limited by specifying explicit filtering
criteria on the request. If the begin-time query parameter is specified, then any entries earlier than that
time are omitted. If the end-time query parameter is specified, then any entries later than that time are
omitted.

The URI path must designate an existing zBX 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. The zBX must be a
zBX node (that is, have a type of "node"); otherwise, status code 400 (Bad Request) is returned. In
addition, the API user must have action/task permission to the View Security Logs task; otherwise,
status code 403 (Forbidden) is returned.

On successful execution, the response body contains an array of filtered log entries. If the security log is
empty or there are no entries to be returned after filtering, then an empty array is provided. Each log
entry contains the event ID, event name and event message. If there are data items included in the event
message, they are available separately. The order and meaning of the substitution items for each event ID
are documented on console help system in the HMC Introduction topic Audit, Event, and Security Log
Messages.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the zBX node object specified in the request URI.
v Action/task permission to the View Security Logs task.

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.”

910 HMC Web Services API

 Level 04a

Otherwise, 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 363. Get zBX (Node) Security Log: 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.
240 The request URI designates a zBX object that is not a zBX node (that is, does
not have a type of "node").
403 (Forbidden) 1 The API user does not have the required permission for this operation.
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.
4 The zBX node designated by the request URI does not support this
operation.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.
500 (Server Error) 307 The request timed out while attempting to communicate with the SE or
while attempting to get the log data.
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

GET /api/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408/operations/get-security-log
HTTP/1.1
x-api-session: bp66qdtmjnofktpyw0f6hvsipo7skdv22vlaov70ecngc2kvn

Figure 481. Get zBX (Node) Security Log: Request

Chapter 14. zBX infrastructure elements 911

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
transfer-encoding: chunked
cache-control: no-cache
date: Fri, 03 Oct 2014 01:19:56 GMT
content-type: application/json;charset=ISO-8859-1
[
{
"event-data-items":[],
"event-details":[],
"event-id":"778",
"event-message":"Mirroring data from the primary Support Element to the
alternate Support Element started.",
"event-name":"ASEMIRRST",
"event-time":1412265359190,
"user-uri":null,
"userid":null
},
{
"event-data-items":[
{
"data-item-number":0,
"data-item-type":"string",
"data-item-value":"Service Status is active."
}
],
"event-details":[],
"event-id":"779",
"event-message":"Mirroring data from the primary Support Element to the
alternate Support Element failed. Service Status is active.",
"event-name":"ASEMIRRNO",
"event-time":1412265360460,
"user-uri":null,
"userid":null
}
]

Figure 482. Get zBX (Node) Security Log: Response

List zBX (Node) Hardware Messages

The List zBX (Node) Hardware Messages operation lists the current set of hardware messages associated
with the zBX (Node).

HTTP method and URI

GET /api/zbxs/{zbx-id}/hardware-messages

In this request, the URI variable {zbx-id} is the object ID of a zBX Node object for which hardware
messages are to be listed.

912 HMC Web Services API

 Level 04a

Response body contents

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

Field name Type Description

hardware-messages Array of Array of nested hardware-message-info objects as defined in the next table.
hardware-
message-
info objects

Each nested hardware-message-info object contains the following fields:

Field name Type Description

element-uri String/URI The canonical URI path of the hardware message. The URI is in the
following form: /api/zbxs/{zbx-id}hardware-messages/{hardware-message-
id}
timestamp Timestamp The date and time the hardware message was created
text String The text of the hardware message.

Description
This operation returns a set of zBX (Node) hardware messages in increasing timestamp order, filtered
according to the query parameters, if specified. Each hardware message describes an event or notification
that may require the operator's attention. The list of hardware messages can be limited by specifying
explicit filtering criteria on he request.

If the begin-time query parameter is specified, then any entries earlier than that time are omitted. If the
end-time query parameter is specified, then any entries later than that time are omitted.

If there are no hardware messages associated with the zBX (Node), or if no hardware messages are to be
included in the results due to filtering, an empty array is returned and the operation completes
successfully.

The URI path must designate an existing zBX (Node) and the API user must have object-access
permission to it; otherwise, status code 404 (Not Found) is returned. In addition, the API user must have
Action/Task permission to the Hardware Messages task or the Hardware Messages task in view-only
mode; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the zBX Node object designated by {zbx-id}.
v Action/Task permission to the Hardware Messages task or the Hardware Messages task in view-only
mode.

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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

Chapter 14. zBX infrastructure elements 913

 Level 04a

Table 364. List zBX (Node) Hardware Messages: HTTP status and reason codes.
HTTP error status
code Reason 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 begin-time value is greater than the end-time value.
240 The request URI designates a zBX object that is not a zBX node (that is, does
not have a type of "node").
403 (Forbidden) 1 The API user does not have Action/Task permission for the Hardware
Messages task or the Hardware Messages task in view-only mode.
404 (Not Found) 1 The object ID in the URI ({zbx-id}) does not designate an existing zBX Node
object, or the API user does not have object-access permission to the object.
4 The zBX node designated by the request URI does not support this
operation.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408/hardware-messages HTTP/1.1

x-api-session: 31lhjzy0a4o0wrt3zmzn3d0zxw9z5pj8sxuy46xufut63ncs9

Figure 483. List zBX (Node) Hardware Messages: Request

914 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 08 Sep 2014 18:38:49 GMT
content-type: application/json;charset=UTF-8
content-length: 2421
{
"hardware-messages": [
{
"element-uri": "/api/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408/hardware-messages/
0d3f86aa-3765-11e4-9a39-42f2e910664b",
"text": "Licensed internal code has detected a problem. [Problem # 5]",
"timestamp": 1410186788140
},
{
"element-uri": "/api/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408/hardware-
messages/73f58498-3509-11e4-93e5-42f2e910664b",
"text": "You can no longer modify the default users roles. Your changes
have been saved and copied to a new user ID identified in the User
Profiles task.",
"timestamp": 1409927544430
}
]
}

Figure 484. List zBX (Node) Hardware Messages: Response

Get zBX (Node) Hardware Message Properties

The Get zBX (Node) Hardware Message Properties operation retrieves the properties of a single zBX
(Node) hardware message.

HTTP method and URI

GET /api/zbxs/{zbx-id}/hardware-messages/{hardware-message-id}

URI Variables:

Variable Description
{zbx-id} Object ID of the zBX Node object.
{hardware-message-id} Element ID of the hardware message to retrieve.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the zBX (Node) hardware message object as defined in “Data model” on page 884.
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
This operation retrieves the properties of a single zBX (Node) hardware message specified by
{hardware-message-id}.

The URI path must designate an existing zBX (Node), and the API user must have object-access
permission to it; otherwise, status code 404 (Not Found) is returned.

Chapter 14. zBX infrastructure elements 915

 Level 04a

The URI path must designate an existing hardware message; otherwise status code 404 (Not Found) is
returned. In addition, the API user must have Action/Task permission to the Hardware Messages task or
the Hardware Messages task in view-only mode; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the zBX (Node) object designated by {zbx-id}.
v Action/Task permission to the Hardware Messages task or the Hardware Messages task in view-only
mode.

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 915.

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.
Table 365. Get zBX (Node) Hardware Message Properties: HTTP status and reason codes.
HTTP error status
code Reason 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.
240 The request URI designates a zBX object that is not a zBX node (that
is, does not have a type of "node").
403 (Forbidden) 1 The API user does not have Action/Task permission for the
Hardware Messages task or the Hardware Messages task in
view-only mode.
404 (Not Found) 1 The object ID in the URI {zbx-id} does not designate an existing zBX
Node object, or the API user does not have object-access permission
to the object.
4 The zBX node designated by the request URI does not support this
operation.
322 The element ID in the URI {hardware-message-id} does not designate an
existing zBX (Node) hardware message.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated
by the request URI is an unmanaged zBX node, 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/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408/
hardware-messages/0d3f86aa-3765-11e4-9a39-42f2e910664b HTTP/1.1
x-api-session: 31lhjzy0a4o0wrt3zmzn3d0zxw9z5pj8sxuy46xufut63ncs9

Figure 485. Get zBX (Node) Hardware Message Properties: Request

916 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 08 Sep 2014 18:38:49 GMT
content-type: application/json;charset=UTF-8
content-length: 354
{
"class": "hardware-message",
"element-id": "0d3f86aa-3765-11e4-9a39-42f2e910664b",
"element-uri": "/api/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408/hardware-messages/
0d3f86aa-3765-11e4-9a39-42f2e910664b",
"parent": "/api/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408",
"text": "Licensed internal code has detected a problem. [Problem # 5]",
"timestamp": 1410186788140
}

Figure 486. Get zBX (Node) Hardware Message Properties: Response

Delete zBX (Node) Hardware Message

The Delete zBX (Node) Hardware Message operation deletes a single zBX (Node) hardware message

HTTP method and URI

DELETE /api/zbxs/{zbx-id}/hardware-messages/{hardware-message-id}

URI Variables:

Variable Description
{zbx-id} Object ID of the zBX Node object.
{hardware-message-id} Element ID of the hardware message to delete.

Description
This operation deletes a specific zBX (Node) hardware message. The hardware message to be deleted is
identified by the {hardware-message-id} variable in the URI.

The URI path must designate an existing zBX (Node) and the API user must have object-access
permission to it; otherwise status code 404 (Not Found) is returned.

The URI path must designate an existing hardware message; otherwise, status code 404 (Not Found) is
returned. In addition, the API user must have Action/Task permission to the Hardware Messages task;
otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the zBX (Node) object designated by {zbx-id}.
v Action/Task permission to the Hardware Messages task.

HTTP status and reason codes

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

Chapter 14. zBX infrastructure elements 917

 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.
Table 366. Delete zBX (Node) Hardware Message: HTTP status and reason codes.
HTTP error status
code Reason 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.
240 The request URI designates a zBX object that is not a zBX node (that
is, does not have a type of "node").
403 (Forbidden) 1 The API user does not have Action/Task permission for the
Hardware Messages task.
404 (Not Found) 1 The object ID in the URI {zbx-id} does not designate an existing zBX
Node object, or the API user does not have Object-access permission
to the object.
4 The zBX node designated by the request URI does not support this
operation.
322 The element ID in the URI {hardware-message-id} does not designate an
existing zBX (Node) hardware message.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated
by the request URI is an unmanaged zBX node, 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

DELETE /api/zbxs/ace3f861-3421-33d5-bcf4-f61f9057d408/
hardware-messages/0d3f86aa-3765-11e4-9a39-42f2e910664b HTTP/1.1
x-api-session: 31lhjzy0a4o0wrt3zmzn3d0zxw9z5pj8sxuy46xufut63ncs9

Figure 487. Delete zBX (Node) Hardware Message: Request

204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 08 Sep 2014 18:38:49 GMT

<No response body>

Figure 488. Delete zBX (Node) Hardware Message: Response

Inventory service data

Information about the zBXs managed by the HMC can be optionally included in the inventory data
provided by the Web Services API Inventory Service.

Inventory entries for zBX objects are included in the response to the Inventory Service's Get Inventory
operation when the request specifies (explicitly by class, implicitly via a containing category, or by
default) that objects of class "zbx" are to be included. An entry for a particular CPC-attached zBX is

918 HMC Web Services API

 Level 04a

included only if the API user has object-access permission to the CPC with which that object is
associated. An entry for a particular zBX node is included only if the API user has object-access
permission for that zBX node object.

For each zBX object to be included, the inventory response array includes entry that is a JSON object with
the same contents as is specified in the response body contents section for “Get zBX Properties” on page
896. That is, the data provided is the same as would be provided if a Get zBX Properties operation were
requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single zBX (that has a type of "node"). This object would appear as one array entry
in the response array:

{
"class": "zbx",
"current-dpxi50z-entitlements": 2,
"current-isaopt-entitlements": 0,
"current-power-entitlements": 4,
"current-systemx-entitlements": 2,
"description": "Represents one zBX",
"is-locked": false,
"machine-model": "004",
"machine-serial": "0000020ZBX26",
"machine-type": "2458",
"max-dpxi50z-entitlements": 28,
"max-isaopt-entitlements": 0,
"max-power-entitlements": 28,
"max-systemx-entitlements": 28,
"name": "ZBX001",
"object-id": "28ba8930-7bc4-11e0-a905-001f163803de",
"object-uri": "/api/zbxs/28ba8930-7bc4-11e0-a905-001f163803de",
"parent": "/api/ensembles/37c6f8a9-8d5e-3e5d-8466-be79e49dd340"
"type": "node"
}

Figure 489. zBX object: Sample inventory data

zBX Top-of-Rack switches

A Top-of-Rack Switch element of a zBX represents one of the VLAN-capable switches provided by the
zBX to serve as the network infrastructure of the Intra-Ensemble Data Network (IEDN). (Note that the
Top-of-Rack switches used for management purposes are considered internal components of zManager
and are not surfaced to API clients as TOR objects.)

Data model
The Top-of-Rack switch object provides the following properties:
Table 367. zBX Top-of-Rack switches: properties
Name Qualifier Type Description
element-uri — String/ The canonical URI path for a TOR object is of the form
URI /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id} where {tor-id}
is the value of the element-id property of the Top-of-Rack switch
object.
element-id — String The element ID of the TOR.

Chapter 14. zBX infrastructure elements 919

 Level 04a

Table 367. zBX Top-of-Rack switches: properties (continued)

Name Qualifier Type Description
parent — String/ The canonical URI path of the zBX that is the parent of the TOR.
URI
class — String The class of a TOR object is "top-of-rack-switch".
name — String (32) The name of the TOR. This name cannot be changed.
tor-ports-list — Array of Array of nested tor-port-info objects (described in the next table),
tor-port- each entry of which describes one port on the TOR switch.
info
objects

The following tor-port-info nested object describes the properties of a single TOR port:
Table 368. zBX Top-of-Rack switches: tor-port-info nested object properties
Name Qualifier Type Description
element-uri — String/ Canonical URI of the port for this TOR: /api/zbxs/{zbx-id}/top-of-
URI rack-switches/{tor-id}/ports/{port-id} when {port-id} is the value
of the port-num property of the port.
port-num — String (3) The TOR port number, as a string of 1 to 3 numeric digits.
type — String This is the type of port. TOR ports have the following types:
Enum v "internal" - Provides connectivity to an ISAOPT coordinator
blade.
v "external" - Provides connectivity to networks external to the
IEDN.
port-access (w) String This describes the port access mode associated with this TOR port.
Enum Possible values:
v "trunk"
v "access"
all-virtual-networks (w) Boolean If true then all defined virtual networks in the ensemble can be used
with this TOR port. When true, the virtual-networks-list property
value will be an empty array.

This property can have the value true only if the type property has
the value "internal" and the port-access-mode property has the
value "trunk". That is, only internal ports configured in trunk mode
can be configured to allow access to all defined virtual networks.

If true, attempts to invoke the Add Top-of-Rack Switch Port to

Virtual Networks or Remove Top-of-Rack Switch Port from Virtual
Networks operations will result in errors.

Changing this property from false to true will remove all virtual
networks from the current virtual-networks-list.

920 HMC Web Services API

 Level 04a

Table 368. zBX Top-of-Rack switches: tor-port-info nested object properties (continued)
Name Qualifier Type Description
virtual-networks-list — Array of This is the list of virtual network URIs that represent the virtual
URI networks that can be used for this port. There can be more than one
virtual network URI in this list only if the port-access property has
the value "trunk".

If the all-virtual-networks property is false, the Add Top-of-Rack

Switch Port to Virtual Networks and Remove Top-of-Rack Switch
Port from Virtual Networks operations may be used to modify this
list.

Changing the all-virtual-networks property from false to true will

remove all virtual networks from this list.
allow-all-macs (w) Boolean If true, all MAC addresses are allowed to access this port and the
mac-filter-list array will be empty.

If false, only those MAC addresses listed in the mac-filter-list

property are permitted to access this port. Network traffic from all
other MAC addresses is filtered out.

If true, attempts to invoke the Add MAC Filter to Top-of-Rack

Switch Port and Remove MAC Filter from Top-of-Rack Switch
Port operations will result in errors.

Changing the value from false to true will remove all MAC filters
from the current mac-filter-list property.

This property is writable only for TOR ports with a type value of
"external". The value of this property is always false for TOR ports
with a type value of "internal".
mac-filter-list — Array of The list of MAC addresses to allow (permit) for this port. Each entry
String (17) in the list is a MAC address. A MAC address is represented as a
string of length 17 consisting of 6 groups of two lower-case
hexadecimal digits separated by colons ( : ), e.g. “01:23:45:67:89:ab”.

If the allow-all-macs property is true, this list is empty. If the

allow-all-macs property is false, the Add MAC Filter to
Top-of-Rack Switch Port and Remove MAC Filter from
Top-of-Rack Switch Port operations may be used to modify this list.

Changing the allow-all-macs property from false to true will remove

all MAC addresses from this list.

This property is only applicable to TOR ports with a type value of

"external". The value of this property is always an empty array of
TOR ports with a type value of "internal".

Operations
List Top-of-Rack Switches of a zBX
The List Top-of-Rack Switches of a zBX operation returns a list of the Top-of-Rack (TOR) switches for a
zBX managed by the HMC.

HTTP method and URI

GET /api/zbxs/{zbx-id}/top-of-rack-switches

Chapter 14. zBX infrastructure elements 921

 Level 04a

In this request, the URI variable {zbx-id} is the object ID of a zBX object for which top-of-rack switches are
to be listed.

Response body contents

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

Field name Type Description

tors-list Array of Array of nested objects where each element in the array is a TOR-info
objects object, described in the next table.

Each TOR-info object contains the following fields:

Field name Type Description

element-uri String/ Canonical URI path of the TOR object.
URI
element-id String Object ID of the TOR object.
name String Display name of the TOR object.

Description
On successful completion, this operation obtains a list of URIs that represent the Top-of-Rack (TOR)
switches for the zBX designated by {zbx-id}. If no TORs are present, then the response body is provided
and contains an empty tors-list array.

A TOR switch within a CPC-attached zBX is included in the list only if the API user has object-access
permission to the CPC associated with the zBX that contains the TOR switch. A TOR switch within a zBX
node is included in the list only if the API user has object-access permission to the zBX node object that
contains the TOR switch. If the ensemble contains a TOR switch but the API user does not have
permission to it, that object is simply omitted from the list but no error status code results.

If the Ensemble does not contain any TOR switches, 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 associated with the zBX containing TOR switches to be listed in
the result (for CPC-attached zBX objects)
v Object-access permission to the zBX node containing TOR switches to be listed in the result (for
CPC-attached zBX objects)
v Action/task permission to Configure Top-of-Rack Switch task.

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, and the response body is a
standard error response body providing the reason code indicated and associated error message:

922 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.
403 (Forbidden) 0 The user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Configure Top of Rack
Switch task is required.
404 (Not Found) 1 The object-id in the URI ({zbx-id}) does not designate an existing resource, or
designates a resource for which the API user does not have object-access
permission.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable) request.

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/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches HTTP/1.1

x-api-session: sqernk0lqu0s49oul0drld6ifcb1cplf902og86d9apesqjsl

Figure 490. List Top-of-Rack Switches: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 23 Nov 2011 20:57:48 GMT
content-type: application/json;charset=UTF-8
content-length: 409
{
"tors-list": [
{
"element-id": "189ad58d-c19f-4cdc-8dc8-639f3ccd4f49",
"element-uri": "/api/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
189ad58d-c19f-4cdc-8dc8-639f3ccd4f49",
"name": "GG0210487100"
},
{
"element-id": "fea63433-e03d-4ea1-a5da-6a2fc7abe844",
"element-uri": "/api/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844",
"name": "GG0210487101"
}
]
}

Figure 491. List Top-of-Rack Switches: Response

Chapter 14. zBX infrastructure elements 923

 Level 04a

Get Top-of-Rack Switch Properties

The Get Top-of-Rack Switch Properties operation obtains the properties of the TOR specified by the
{tor-id} managed object.

HTTP method and URI

GET /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}

URI variables:

Variable Description
{zbx-id} Object ID of the zBX object containing the TOR switch.
{tor-id} Element ID of the TOR object.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the TOR object as defined in the“Data model” on page 919. 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
On successful completion, the Get Top-of-Rack Switch Properties operation obtains the properties of the
TOR specified by {tor-id}.

The URI path must designate an existing TOR switch object. If the TOR switch is within a CPC-attached
zBX, the API user must have object-access permission to the CPC associated with the zBX. If the TOR
switch is within a zBX node, the API user must have object-access permission to the zBX node. If these
conditions are not met, status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC associated with the zBX containing the TOR switch (for
CPC-attached zBX objects)
v Object-access permission to the zBX node containing the TOR switch (for zBX node objects)
v Action/task permission to Configure Top-of-Rack Switch task.

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, 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 user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Configure Top of Rack
Switch task is required.

924 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object-id in the URI ({zbx-id}) does not designate an existing resource, or
designates a resource for which the API user does not have object-access
permission.
360 The TOR element ID in the URI ({tor-id}) does not designate an existing top
of rack switch.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable) request.

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/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844 HTTP/1.1
x-api-session: sqernk0lqu0s49oul0drld6ifcb1cplf902og86d9apesqjsl

Figure 492. Get Top-of-Rack Switch Properties: Request

Chapter 14. zBX infrastructure elements 925

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 23 Nov 2011 20:57:53 GMT
content-type: application/json;charset=UTF-8
content-length: 1314
{
"class": "top-of-rack-switch",
"element-id": "fea63433-e03d-4ea1-a5da-6a2fc7abe844",
"element-uri": "/api/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844",
"name": "GG0210487101",
"parent": "/api/zbxs/da5d7720-a337-11e0-9555-00262df332b3",
"tor-ports-list": [
{
"all-virtual-networks": false,
"allow-all-macs": true,
"element-uri": "/api/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844/ports/8",
"mac-filter-list": [],
"port-access": "access",
"port-num": "8",
"type": "internal",
"virtual-networks-list": [
"/api/virtual-networks/4ccb3c0c-a703-11df-a6fc-00215ef9b504"
]
},
{
"all-virtual-networks": false,
"allow-all-macs": true,
"element-uri": "/api/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844/ports/34",
"mac-filter-list": [],
"port-access": "trunk",
"port-num": "34",
"type": "external",
"virtual-networks-list": [
"/api/virtual-networks/4ccb3c0c-a703-11df-a6fc-00215ef9b504"
]
}
]
}

Figure 493. Get Top-of-Rack Switch Properties: Response

Get Top-of-Rack Switch Port Details

The Get Top-of-Rack Switch Port Details operation obtains the properties of the designated TOR port
specified by the {port-id} identifier.

HTTP method and URI

GET /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}

URI variables:

Variable Description
{zbx-id} Object ID of the zBX object containing the TOR switch.
{tor-id} Element ID of the TOR object.
{port-id} Port number of the TOR port.

926 HMC Web Services API

 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 designated TOR port defined in the “Data model” on page 919 by tor-port-info. 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
On successful completion, the Get Top-of-Rack Switch Port Details operation obtains the properties of
the TOR port specified by {port-id}.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC associated with the zBX containing the TOR switch (for
CPC-attached zBX objects)
v Object-access permission to the zBX node containing the TOR switch (for zBX node objects)
v Action/task permission to Configure Top-of-Rack Switch task.

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, 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 user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Configure Top-of-Rack
Switch task is required.
404 (Not Found) 1 The object-id in the URI ({zbx-id}) does not designate an existing resource, or
designates a resource for which the API user does not have object-access
permission.
360 The TOR element ID in the URI ({tor-id}) does not designate an existing top
of rack switch.
361 The port ID the URI ({port-id}) does not designate an existing port.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable) request.

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

Chapter 14. zBX infrastructure elements 927

 Level 04a

Example HTTP interaction

GET /api/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844/ports/34 HTTP/1.1
x-api-session: sqernk0lqu0s49oul0drld6ifcb1cplf902og86d9apesqjsl

Figure 494. Get Top-of-Rack Switch Port Details: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 23 Nov 2011 20:58:19 GMT
content-type: application/json;charset=UTF-8
content-length: 427
{
"all-virtual-networks": false,
"allow-all-macs": false,
"element-uri": "/api/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844/ports/34",
"mac-filter-list": [
"00:24:7e:e0:ea:9e"
],
"port-access": "trunk",
"port-num": "34",
"type": "external",
"virtual-networks-list": [
"/api/virtual-networks/4ccb3c0c-a703-11df-a6fc-00215ef9b504",
"/api/virtual-networks/cd42c1c0-1615-11e1-817f-00215e6a0c26"
]
}

Figure 495. Get Top-of-Rack Switch Port Details: Response

Update Top-of-Rack Switch Port Properties

The Update Top-of-Rack Switch Port Properties operation updates selected properties of the specified
TOR port.

HTTP method and URI

POST /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}

URI variables:

Variable Description
{zbx-id} Object ID of the zBX object containing the TOR switch.
{tor-id} Element ID of the TOR object.
{port-id} Port number of the TOR port.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the “Data model” on
page 919. The JSON object can and should omit fields for properties whose values are not to be changed
by this operation.

928 HMC Web Services API

 Level 04a

Description
This operation updates writable properties of the TOR port specified by {port-id}.

The request body does not need to specify a value for all writable properties, but rather can and should
contain fields for the properties to be updated. Object properties for which no input value is provided
remain unchanged by this operation.

The request body is validated against the schema described in the “Request body contents” on page 928.
If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered. In addition to occurring for common validation reasons, status code 400
is returned when the requested changes are not valid considering the port's type, or for inconsistencies in
the request and the port-access-mode setting.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC associated with the zBX containing the TOR switch (for
CPC-attached zBX objects)
v Object-access permission to the zBX node containing the TOR switch (for zBX node objects)
v Action/task permission to Configure Top-of-Rack Switch 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, 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.
133 The port's port-access setting is not valid for the update. A change from
"trunk" to "access" mode is not allowed if more than one virtual network is
defined to the port.
134 The port's type does not support MAC filters. Only ports that have a type of
"external" support MAC filters.
139 The port's type does not support the all-virtual-networks setting.
403 (Forbidden) 0 The user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Configure Top-of-Rack
Switch task is required.
404 (Not Found) 1 The object-id in the URI ({zbx-id}) does not designate an existing resource, or
designates a resource for which the API user does not have object-access
permission.
360 The TOR element ID in the URI ({tor-id}) does not designate an existing top
of rack switch.
361 The port ID the URI ({port-id}) does not designate an existing port.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable) request.

Chapter 14. zBX infrastructure elements 929

 Level 04a

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/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844/ports/34 HTTP/1.1
x-api-session: sqernk0lqu0s49oul0drld6ifcb1cplf902og86d9apesqjsl
content-type: application/json
content-length: 49
{
"allow-all-macs": false,
"port-access": "trunk"
}

Figure 496. Update Top-of-Rack Switch Port Properties: Request

204 No Content
date: Wed, 23 Nov 2011 20:57:59 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 497. Update Top-of-Rack Switch Port Properties: Response

Add MAC Filters to Top-of-Rack Switch Port

The Add MAC Filters to Top-of-Rack Switch Port operation adds MAC address filters to the designated
Top-of-Rack Switch port to permit a list of MAC addresses to connect to this TOR port.

HTTP method and URI

POST /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}/operations/add-mac-filters

URI variables:

Variable Description
{zbx-id} Object ID of the zBX object containing the TOR switch.
{tor-id} Element ID of the TOR object.
{port-id} Port number of the TOR port.

Request body contents

The request body is expected to contain a JSON object that provides the following:

Field name Type Rqd/Opt Description

mac-address-list Array of Required Array of MAC addresses to add to the mac-filter-list for the
String specified TOR port. If successful, these MAC addresses will be
permitted to access the TOR port. This operation will fail if the TOR
port's allow-all-macs is true.

930 HMC Web Services API

 Level 04a

Description
On successful execution, this operation adds the MAC provided in the mac-address-list field to the TOR
port's mac-filter-list. If the inputs contain addresses that are already in the list, these will be accepted
without error. These MAC addresses will be permitted to access the specified TOR port.

The request body is validated against the schema described in “Request body contents” on page 930. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered. Consider the following to prevent bad requests:
v Ensure the type of the target port supports the setting of MAC filters
v The allow-all-macs property must be false
v Ensure that the MAC address is valid.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC associated with the zBX containing the TOR switch (for
CPC-attached zBX objects)
v Object-access permission to the zBX node containing the TOR switch (for zBX node objects)
v Action/task permission to Configure Top-of-Rack Switch 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, 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.
134 The port's type does not support MAC filters. Only ports that have a type
value of "external" support MAC filters.
135 This operation cannot be performed when the allow-all-macs property of the
TOR port is true.
136 The MAC address is invalid.
403 (Forbidden) 0 The user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Configure
Top-of-Rack-Switch task is required.
404 (Not Found) 1 The object-id in the URI ({zbx-id}) does not designate an existing resource, or
designates a resource for which the API user does not have object-access
permission.
360 The TOR element ID in the URI ({tor-id}) does not designate an existing top
of rack switch.
361 The port ID the URI ({port-id}) does not designate an existing port.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable) request.

Chapter 14. zBX infrastructure elements 931

 Level 04a

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/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
63433-e03d-4ea1-a5da-6a2fc7abe844/ports/34/operations/add-mac-filters HTTP/1.1
x-api-session: sqernk0lqu0s49oul0drld6ifcb1cplf902og86d9apesqjsl
content-type: application/json
content-length: 43
{
"mac-address-list": [
"00:24:7E:E0:EA:9E"
]
}

Figure 498. Add MAC Filters to Top-of-Rack Switch Port: Request

204 No Content
date: Wed, 23 Nov 2011 20:58:07 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 499. Add MAC Filters to Top-of-Rack Switch Port: Response

Remove MAC Filters from Top-of-Rack Switch Port

The Remove MAC Filters from Top-of-Rack Switch Port operation removes MAC address filters from
the designated Top-of-Rack Switch port.

HTTP method and URI

POST /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}/operations/remove-mac-filters

URI variables:

Variable Description
{zbx-id} Object ID of the zBX object containing the TOR switch.
{tor-id} Element ID of the TOR object.
{port-id} Port number of the TOR port.

Request body contents

The request body is expected to contain a JSON object that provides the following:

Field name Type Rqd/Opt Description

mac-address-list Array of Required This is an array of the MAC addresses to remove from the MAC
String mac-filter-list for the specified TOR port.

932 HMC Web Services API

 Level 04a

Description
On successful execution, this operation removes the MAC provided in the mac-address-list field to the
TOR port's mac-filter-list. If a MAC address input is not currently in the mac-filter-list, it will be ignored
without resulting in an error.

The request body is validated against the schema described in “Request body contents” on page 932. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered. Consider the following to prevent bad requests:
v Ensure the type of the target port supports the setting of MAC filters
v The allow-all-macs property must be false
v Ensure that the MAC address is valid.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC associated with the zBX containing the TOR switch (for
CPC-attached zBX objects)
v Object-access permission to the zBX node containing the TOR switch (for zBX node objects)
v Action/task permission to Configure Top-of-Rack Switch 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, 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.
134 The port's type does not support MAC filters. Only ports that have a type
value of "external" support MAC filters.
135 This operation cannot be performed when the allow-all-macs property of the
TOR port is true.
136 The MAC address is invalid.
403 (Forbidden) 0 The user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Configure Top-of-Rack
Switch task is required.
404 (Not Found) 1 The object-id in the URI ({zbx-id}) does not designate an existing resource, or
designates a resource for which the API user does not have object-access
permission.
360 The TOR element ID in the URI ({tor-id}) does not designate an existing top
of rack switch.
361 The port ID the URI ({port-id}) does not designate an existing port.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable) request.

Chapter 14. zBX infrastructure elements 933

 Level 04a

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/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844/ports/34/operations/remove-mac-filters HTTP/1.1
x-api-session: sqernk0lqu0s49oul0drld6ifcb1cplf902og86d9apesqjsl
content-type: application/json
content-length: 43
{
"mac-address-list": [
"00:24:7E:E0:EA:9E"
]
}

Figure 500. Remove MAC Filters from Top-of-Rack Switch Port: Request

204 No Content
date: Wed, 23 Nov 2011 20:58:40 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 501. Remove Mac Filters from Top-of-Rack Switch Port: Response

Add Top-of-Rack Switch Port to Virtual Networks

The Add Top-of-Rack Switch Port to Virtual Networks operation adds Top-of-Rack switch port to the
specified list of virtual networks.

HTTP method and URI

POST /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}/operations/add-virtual-networks

URI variables:

Variable Description
{zbx-id} Object ID of the zBX object containing the TOR switch.
{tor-id} Element ID of the TOR object.
{port-id} Port number of the TOR port.

Request body contents

The request body is expected to contain a JSON object that provides the following:

Field name Type Rqd/Opt Description

add-virtual- Array of Required Array of virtual network URIs that define the virtual networks that
networks String/ can be used for the specified TOR port.
URI

934 HMC Web Services API

 Level 04a

Description
On successful execution, this operation adds the specified virtual networks to the TOR port's
virtual-networks-list array. If the inputs contain virtual networks that are already in the list, these will be
accepted without error. Traffic for VLAN IDs representing these virtual networks will now be able to be
used on the specified TOR port.

The request body is validated against the schema described in “Request body contents” on page 934. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered. Consider the following to prevent bad requests:
v Ensure the type of the target port supports the setting of virtual networks
v The target TOR port's all-virtual-networks property must be false when issuing this request
v If the port's port-mode property is "access", then it only supports one virtual network.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC associated with the zBX containing the TOR switch (for
CPC-attached zBX objects)
v Object-access permission to the zBX node containing the TOR switch (for zBX node objects)
v Action/task permission to Configure Top-of-Rack Switch 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, 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.
137 The port-access property is "access", therefore, only one virtual network is
allowed in the TOR port's virtual-networks-list.
138 This operation cannot be performed when the all-virtual-networks property
of the TOR port is true.
403 (Forbidden) 0 The user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Configure Top-of-Rack
Switch task is required.
404 (Not Found) 1 The object-id in the URI ({zbx-id}) does not designate an existing resource, or
designates a resource for which the API user does not have object-access
permission.
360 The TOR element ID in the URI ({tor-id}) does not designate an existing top
of rack switch.
361 The port ID the URI ({port-id}) does not designate an existing port.
362 A URI in the add-virtual-networks field of the request body does not
designate an existing virtual network.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.

Chapter 14. zBX infrastructure elements 935

 Level 04a

HTTP error status Reason

code code Description
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable) request.

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/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844/ports/34/operations/add-virtual-networks HTTP/1.1
x-api-session: sqernk0lqu0s49oul0drld6ifcb1cplf902og86d9apesqjsl
content-type: application/json
content-length: 88
{
"add-virtual-networks": [
"/api/virtual-networks/cd42c1c0-1615-11e1-817f-00215e6a0c26"
]
}

Figure 502. Add Top-of-Rack Switch Port to Virtual Networks: Request

204 No Content
date: Wed, 23 Nov 2011 20:58:18 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 503. Add Top-of-Rack Switch Port to Virtual Networks: Response

Remove Top-of-Rack Switch Port from the Virtual Networks

The Remove Top-of-Rack Switch Port from the Virtual Networks operation removes the Top-of-Rack
Switch port from the specified virtual networks.

HTTP method and URI

POST /api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}/operations/remove-virtual-networks

URI variables:

Variable Description
{zbx-id} Object ID of the zBX object containing the TOR switch.
{tor-id} Element ID of the TOR object.
{port-id} Port number of the TOR port.

936 HMC Web Services API

 Level 04a

Request body contents

The request body is expected to contain a JSON object that provides the following:

Field name Type Rqd/Opt Description

remove-virtual- Array of Required List of virtual network URIs to remove from the
networks String/ virtual-network-list array for the specified TOR port.
URI

Description
On successful execution, this operation removes the specified virtual networks from the TOR port's
virtual-networks-list array. If a virtual network in the input is not currently in the virtual-networks-list,
it will be ignored without resulting in an error.

The request body is validated against the schema described in “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered. Consider the following to prevent bad requests:
v Ensure the type of the target port supports the setting of virtual networks
v The target TOR port's all-virtual-networks property must be false when issuing this request.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC associated with the zBX containing the TOR switch (for
CPC-attached zBX objects)
v Object-access permission to the zBX node containing the TOR switch (for zBX node objects)
v Action/task permission to Configure Top-of-Rack Switch 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, 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.
138 This operation cannot be performed when the all-virtual-networks property
of the TOR port is true.
403 (Forbidden) 0 The user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Configure Top-of-Rack
Switch task is required.

Chapter 14. zBX infrastructure elements 937

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object-id in the URI ({zbx-id}) does not designate an existing resource, or
designates a resource for which the API user does not have object-access
permission.
360 The TOR element ID in the URI ({tor-id}) does not designate an existing top
of rack switch.
361 The port ID in the URI ({port-id}) does not designate an existing port.
362 A URI in the remove-virtual-networks field of the request body does not
designate an existing virtual network.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, which is not supported by this
operation.
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable) request.

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/zbxs/da5d7720-a337-11e0-9555-00262df332b3/top-of-rack-switches/
fea63433-e03d-4ea1-a5da-6a2fc7abe844/ports/34/operations/remove-virtual-networks HTTP/1.1
x-api-session: sqernk0lqu0s49oul0drld6ifcb1cplf902og86d9apesqjsl
content-type: application/json
content-length: 91
{
"remove-virtual-networks": [
"/api/virtual-networks/cd42c1c0-1615-11e1-817f-00215e6a0c26"
]
}

Figure 504. Remove Top-of-Rack Switch Port from the Virtual Networks: Request

204 No Content
date: Wed, 23 Nov 2011 20:58:32 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 505. Remove Top-of-Rack Switch Port from the Virtual Networks: Response

Rack object
A Rack object represents a rack that houses the zBX components.

There is at least one Rack object for each zBX, designated as the rack in location B. This rack houses the
top of rack (TOR) switches for the zBX, the Support Elements (for a zBX node), and one or two
BladeCenter chassis. Rack B is the first rack to be populated when installing a zBX. Additional racks are
added for larger configurations that contain more than two BladeCenter chassis in the zBX. The
additional racks, each containing one to two chassis, are designated with consecutive location codes (C,
D, E).

938 HMC Web Services API

 Level 04a

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
but does not provide the operational-status-related properties defined in that schema because it does not
maintain the concept of an operational status.

The following class-specific specializations apply to the other base managed object properties:
Table 369. Rack object: base managed object properties specializations
Name Qualifier Type Description of specialization
name (ro) String The name of the object. Currently, this is assigned by zManager
(1-64) based on the rack's location (has the same value as the location
property).1
description (ro) String The zManager-provided description of the Rack object.
object-uri — String/ The canonical URI path for a Rack object is of the form
URI /api/racks/{rack-id}.
parent — String/ The canonical URI path of the parent zBX object, of the form
URI /api/zbxs/{zbx-id}.
class — String The value "rack".
Note:
1. This name property is currently assigned based on the location of the rack and thus has the same value as the
location property. However, it is possible that the API could be extended to allow this property to be writable, in
which case an API or User-Interface user could change the name to contain arbitrary data. Therefore, API client
applications that are interested in determining the location of the rack should not rely on the contents and
format of the name property, but rather obtain location information from the location property.

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:
Table 370. Rack object: class specific properties
Name Type Description
serial-number String The 12 character serial number of the rack.
location String The zManager assigned location code for the rack, as an uppercase alphabetic
character starting with “B” for the first rack of the zBX and with subsequent
racks being designated by consecutive letters.

Operations
List Racks of a zBX
The List Racks of a zBX operation lists the racks where the zBX components are mounted.

HTTP method and URI

GET /api/zbxs/{zbx-id}/racks

In this request, the URI variable {zbx-id} is the object ID of the zBX object whose racks are to be obtained.

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) used to limit returned objects

Chapter 14. zBX infrastructure elements 939

 Level 04a

Response body contents

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

Field name Type Description

racks Array of Array of nested rack-info objects, described in the next table
objects

Each nested rack-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the Rack object in the form /api/racks/{rack-id}
URI
name String The name property of the Rack object

Description
The List Racks of a zBX operation lists the racks where the zBX components are mounted. BladeCenters
are plugged into the rack, and the blades are plugged into the BladeCenters. The object URI and name
are provided for each rack.

If the name query parameter is specified, then a rack is included in the list only if the name pattern
matches the name property of the object.

If the HMC does not manage any racks, 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 with which the zBX and Rack objects are associated (for a
CPC-attached zBX).
v Object-access permission to the zBX object (for a zBX node).

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.”

Otherwise, 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

code Reason 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 {zbx-id} does not designate a zBX object, or the API
user does not have object-access permission to the CPC with
which it is associated.
409 (Conflict) 244 The operation cannot be performed because the zBX node
designated by the request URI is an unmanaged zBX node, which
is not supported by this operation.

940 HMC Web Services API

 Level 04a

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/zbxs/54a9716c-a326-11e0-9469-001f163805d8/racks HTTP/1.1

x-api-session: 5q07hx6jgp2ngn2cypq1zxot76sfwnzky0ih8nddd5hz6bpiue

Figure 506. List Racks of a zBX: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 21 Jul 2011 17:49:01 GMT
content-type: application/json;charset=UTF-8
content-length: 142
{
"racks": [
{
"name": "B",
"object-uri": "/api/racks/b434398a-a328-11e0-9b4a-001f163805d8"
}
]
}

Figure 507. List Racks of a zBX: Response

Get Rack Properties

The Get Rack Properties operation retrieves the properties of a single Rack object that is designated by
its object ID.

HTTP method and URI

GET /api/racks/{rack-id}

In this request, the URI variable {rack-id} is the object ID of the Rack object for which properties are to be
obtained.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Rack object as defined in the “Data model” on page 939. 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 Rack Properties operation returns the current properties for the Rack object specified by
{rack-id}.

On successful execution, all of the current properties as defined in “Data model” on page 939 for the
Rack object are provided in the response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing Rack object. If the URI path designates a rack within a
CPC-attached zBX, the API user must have object-access permission to the CPC with which the zBX is
associated. If the URI path designates a rack within a zBX node, the API user must have object-access

Chapter 14. zBX infrastructure elements 941

 Level 04a

permission to the zBX node object. If these conditions are not met, status code 404 (Not Found) is
returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the CPC associated with the zBX within which the rack object designated
by {rack-id} is contained (for racks within a CPC-attached zBX).
v Object-access permission to the zBX within which the rack object designated by {rack-id} is contained
(for racks within a zBX node).

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 941.

Otherwise, 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 {rack-id} does not designate an existing Rack object, or the API
user does not have object-access permission to the CPC with which the rack
is associated.

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/racks/04419e1e-a9db-11e0-8077-f0def1610d20 HTTP/1.1

x-api-session: 5wksmtktms30ajeohh0bn411fdzusmklld4jyddd1des5t78aq

Figure 508. Get Rack Properties: Request

942 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2011 14:22:52 GMT
content-type: application/json;charset=UTF-8
content-length: 272
{
"class": "rack",
"description": "Rack",
"is-locked": false,
"location": "C",
"name": "C",
"object-id": "04419e1e-a9db-11e0-8077-f0def1610d20",
"object-uri": "/api/racks/04419e1e-a9db-11e0-8077-f0def1610d20",
"parent": "/api/zbxs/291e385e-a9cd-11e0-8650-f0def1610d20",
"serial-number": "12345"
}

Figure 509. Get Rack Properties: Response

Inventory service data

Information about the zBX racks managed by the HMC can be optionally included in the inventory data
provided by the Web Services API Inventory Service.

Inventory entries for Rack objects are included in the response to the Inventory Service's Get Inventory
operation when the request specifies (explicitly by class, implicitly via a containing category, or by
default) that objects of class "rack" are to be included. An entry for a particular Rack is included only if
the API user has object-access permission to the CPC with which that object is associated.

For each Rack object to be included, the inventory response array includes an entry that is a JSON object
with the same contents as is specified in the response body contents section for “Get Rack Properties” on
page 941. That is, the data provided is the same as would be provided if a Get Rack Properties operation
were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single rack. This object would appear as one array entry in the response array:

{
"class": "rack",
"description": "Rack",
"is-locked": false,
"location": "B",
"name": "B",
"object-id": "28bc03c8-7bc4-11e0-a905-001f163803de",
"object-uri": "/api/racks/28bc03c8-7bc4-11e0-a905-001f163803de",
"parent": "/api/zbxs/28ba8930-7bc4-11e0-a905-001f163803de",
"serial-number": "123456123456"
}

Figure 510. Rack object: Sample inventory data

Chapter 14. zBX infrastructure elements 943

 Level 04a

BladeCenter object
A BladeCenter object represents a single BladeCenter of the zBX.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
including the operational-status properties, with the following class-specific specialization:
Table 371. BladeCenter object: base managed object properties specializations
Name Qualifier Type Description of specialization
name (ro) String The zManager-assigned name of the zBX BladeCenter.1
(1-64)
description — String This property is not provided.
object-uri — String/URI The canonical URI path for a zBX BladeCenter object is of the form
/api/bladecenters/{bladecenter-id}
parent — String/URI The canonical URI path of the parent Rack object, of the form
/api/racks/{rack-id}
class — String The value "bladecenter"
status (sc) String The status of the blade center. Values:
Enum v "no-power"
v "operating"
additional-status — String This property is not provided.
Enum
Note:
1. This name property is currently assigned based on the location of the BladeCenter and is of the form
RackName.BladecenterName (e.g. B.1). However, it is possible that the API could be extended to allow this
property to be writable, in which case an API or User-Interface user could change the name to contain arbitrary
data. Therefore, API client applications that are interested in determining the location of the BladeCenter should
not rely on the contents and format of the name property, but rather obtain location information from the
location property.

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:
Table 372. BladeCenter object: class specific properties
Name Qualifier Type Description
machine-type — String 4 characters
machine-model — String 3 characters
machine-serial — String 7 characters
location — String (4) 4 Characters (RxxB)

RxxB – BladeCenter vertical position in rack R

has-hardware- (pc) Boolean The BladeCenter has a hardware message (true) or the
messages BladeCenter does not have a hardware message (false).

Energy Management Related Additional Properties

In addition to the properties defined above, this object includes the following additional class-specific
properties related to energy management. For further explanation of the various states involved, please
see the "Overview" section in the "Energy Management" chapter of this document.

944 HMC Web Services API

 Level 04a

Table 373. BladeCenter object: energy management related additional properties

Name Qualifier Type Description
power-rating — Integer Specifies the maximum power usage of this BladeCenter in watts (W).
This value is a calculated value, as indicated by the electrical rating
labels or system rating plates of the BladeCenter components.
power- (mg) Integer Specifies the current power consumption in watts (W) of this
consumption BladeCenter. The BladeCenter power consumption includes the power
consumption of the Blades contained within the BladeCenter and the
shared infrastructure.
power-saving — String Specifies the current power saving setting of the BladeCenter. Power
Enum saving reduces the energy consumption of a system, and can be
managed it using the Set Power Saving operation. The possible
settings include:
v "high-performance" - Specifies not reducing the power
consumption and performance of the BladeCenter. This is the
default setting.
v "low-power" - Specifies low power consumption for all components
of the BladeCenter enabled for power saving.
v "custom" - Specifies that some, but not all, components of the
BladeCenter are in the Low power setting.
v "not-supported" - Specifies that power saving is not supported for
this BladeCenter.
v "not-available" - Specifies that power-saving property could not be
read from this BladeCenter.
v "not-entitled' - Specifies that the server is not entitled to power
saving.
power-saving-state — String Specifies the power saving setting of the BladeCenter set by the user.
Enum Note that this property indicates the user setting and may not match
the real state of the hardware compared to the power-saving
property. For more information, see “Group power saving” on page
820. The possible settings include:
v "high-performance" - Specifies not reducing the power
consumption and performance of the BladeCenter. This setting will
be applied to all children.
v "low-power" - Specifies low power consumption for all components
of the BladeCenter enabled for power saving.
v "custom" - Specifies that the BladeCenter does not control the
children. This is the default setting.
v "not-supported" - Specifies that power saving is not supported for
this BladeCenter.
v "not-entitled' - Specifies that the server is not entitled to power
saving.

Chapter 14. zBX infrastructure elements 945

 Level 04a

Table 373. BladeCenter object: energy management related additional properties (continued)
Name Qualifier Type Description
power-save- — String Should be used to determine if a call of the power save operation is
allowed Enum currently allowed. If a value other that "allowed" is returned the
caller may reckon that the power save operation will fail.

The possible settings include:

v "allowed" - Alter power save setting is allowed for this
BladeCenter
v "unknown" - Unknown reason
v "not-entitled" - Specifies the server is not entitled to power saving.
v "not-supported" - Specifies that power saving is not supported for
this BladeCenter.
v "under-group-control" - The BladeCenter is under group control
and cannot be individually altered.
power-capping- — String Specifies the current power capping setting of the BladeCenter. Power
state Enum capping limits peak power consumption of a system, and you can
manage it by using the Set Power Cap operation. The possible
settings include:
v "disabled" - Specifies not setting the power cap of the BladeCenter
and not limiting the peak power consumption. This is the default
setting.
v "enabled" - Specifies capping all components of the BladeCenter
available for power capping to limit the peak power consumption
of the BladeCenter.
v "custom" - Specifies individually configuring the components of the
BladeCenter for power capping.
v "not-supported" - Specifies that power capping is not supported for
this BladeCenter.
v "not-entitled" - Specifies that the server is not entitled to power
capping.
power-cap- — Integer Specifies the minimum value for the BladeCenter cap value in watts
minimum (W). This is a sum of the component minimum cap values.
power-cap- — Integer Specifies the maximum value for the BladeCenter cap value in watts
maximum (W). This is a sum of the component maximum cap values.
power-cap-current — Integer Specifies the current cap value for the BladeCenter in watts (W). The
current cap value indicates the power budget for the BladeCenter and
is the sum of the component Cap values.
power-cap- — String Should be used to determine if a call of the power capping operation
allowed Enum is currently allowed. If a value other that "allowed" is returned the
caller may reckon that the power capping operation will fail.

The possible settings include:

v "allowed" - Alter power capping setting is allowed for this
BladeCenter
v "unknown" - Unknown reason
v "not-entitled" - Specifies the server is not entitled to power
capping.
v "not-supported" - Specifies that power capping is not supported for
this BladeCenter.
v "under-group-control" - The BladeCenter is under group control
and cannot be individually altered.

946 HMC Web Services API

 Level 04a

Table 373. BladeCenter object: energy management related additional properties (continued)
Name Qualifier Type Description
ambient- (mg) Float Specifies the input air temperature in degrees Celsius (ºC) as
temperature measured by the system.
exhaust- — Float Specifies the exhaust air temperature in degrees Celsius (ºC) as
temperature calculated by the system. This is useful in determining potential hot
spots in the data center.

Operations
List BladeCenters in a Rack
The List BladeCenters in a Rack operation lists the BladeCenters that are mounted into the rack.

HTTP method and URI

GET /api/racks/{rack-id}/bladecenters

In this request, the URI variable {rack-id} is the object ID of the Rack object whose BladeCenters are to be
obtained.

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) used to limit returned objects

Response body contents

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

Field name Type Description

blade-centers Array of Array of nested BladeCenter-info objects, described in the next table. If the
objects rack does not have any BladeCenters mounted in it, an empty array is
provided.

Each nested BladeCenter-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the BladeCenter object in the form
URI /api/bladecenters/{bladecenter-id}
name String The name property of the BladeCenter object (for example, B.1)
status String The status property of the BladeCenter object
Enum

Description
The List BladeCenters in a Rack operation lists the BladeCenters that are mounted in the rack. The object
URI, name, and status are provided for each BladeCenter.

If the name query parameter is specified, then a BladeCenter is included in the list only if the name
pattern matches the name property of the object.

Chapter 14. zBX infrastructure elements 947

 Level 04a

A BladeCenter is included in the list only if the API user has object-access permission for that object. If
the HMC is a manager of a BladeCenter, but the API user does not have permission to it, that object is
omitted from the list, but no error status code results.

If the HMC does not manage any BladeCenters, 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 associated with the zBX in which the rack specified by the URI is
contained (for a CPC-attached zBX).
v Object-access permission to the zBX in which the rack specified by the URI is contained (for a zBX
node).
v Object-access permission to any BladeCenter object which is 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 947.

Otherwise, 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 {rack-id} does not designate a Rack 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/racks/04419e1e-a9db-11e0-8077-f0def1610d20/bladecenters HTTP/1.1

x-api-session: 5wksmtktms30ajeohh0bn411fdzusmklld4jyddd1des5t78aq

Figure 511. List BladeCenters in a Rack: Request

948 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2011 14:22:52 GMT
content-type: application/json;charset=UTF-8
content-length: 231
{
"blade-centers": [
{
"name": "C.1",
"object-uri": "/api/bladecenters/22e79848-3957-35dc-b88e-c661f9c8b680",
"status": "operating"
},
{
"name": "C.2",
"object-uri": "/api/bladecenters/e3ee0adc-27c0-355e-93b9-ace8a3d2da15",
"status": "operating"
}
]
}

Figure 512. List BladeCenters in a Rack: Response

List BladeCenters in a zBX

The List BladeCenters in a zBX operation lists the BladeCenters in a zBX.

HTTP method and URI

GET /api/zbxs/{zbx-id}/bladecenters

In this request, the URI variable {zbx-id} is the object ID of the zBX object whose BladeCenters are to be
obtained.

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) used to limit returned objects

Response body contents

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

Field name Type Description

blade-centers Array of Array of nested BladeCenter-info objects, described in the next table. If the
objects zBX does not have any BladeCenters, an empty array is provided.

Each nested BladeCenter-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the BladeCenter object in the form
URI /api/bladecenters/{bladecenter-id}
name String The name property of the BladeCenter object (for example, B.1)

Chapter 14. zBX infrastructure elements 949

 Level 04a

Field name Type Description

status String The status property of the BladeCenter object
Enum

Description
The List BladeCenters in a zBX operation lists the BladeCenters in the zBX. The object URI, name, and
status are provided for each BladeCenter.

If the name query parameter is specified, then a BladeCenter is included in the list only if the name
pattern matches the name property of the object.

A BladeCenter is included in the list only if the API user has object-access permission for that object. If
the HMC is a manager of a BladeCenter, but the API user does not have permission to it, that object is
omitted from the list, but no error status code results.

If the HMC does not manage any BladeCenters, 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 CPC to which the zBX specified by the URI is attached (for a
CPC-attached zBX).
v Object-access permission to the zBX specified by the URI (for a zBX node).
v Object-access permission to any BladeCenter object which is 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 949.

Otherwise, 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 {zbx-id} does not designate a zBX object, or the API user does
not have object-access permission to the CPC with which it is associated.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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.

950 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/zbxs/291e385e-a9cd-11e0-8650-f0def1610d20/bladecenters HTTP/1.1

x-api-session: 5wksmtktms30ajeohh0bn411fdzusmklld4jyddd1des5t78aq

Figure 513. List BladeCenters in a zBX: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2011 14:22:52 GMT
content-type: application/json;charset=UTF-8
content-length: 443
{
"blade-centers": [
{
"name": "C.1",
"object-uri": "/api/bladecenters/22e79848-3957-35dc-b88e-c661f9c8b680",
"status": "operating"
},
{
"name": "B.1",
"object-uri": "/api/bladecenters/2ae200b3-fa8e-3db7-b34a-ec08780aaac6",
"status": "operating"
},
{
"name": "C.2",
"object-uri": "/api/bladecenters/e3ee0adc-27c0-355e-93b9-ace8a3d2da15",
"status": "operating"
},
{
"name": "B.2",
"object-uri": "/api/bladecenters/f5bca837-bc0d-34e6-bcef-766411287439",
"status": "operating"
}
]
}

Figure 514. List BladeCenters in a zBX: Response

Get BladeCenter Properties

The Get BladeCenter Properties operation retrieves the properties of a single BladeCenter object that is
designated by its object ID.

HTTP method and URI

GET /api/bladecenters/{bladecenter-id}

In this request, the URI variable {bladecenter-id} is the object ID of the BladeCenter object for which
properties are to be obtained.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Rack object as defined in the “Data model” on page 944. Field names and data types in
the JSON object are the same as the property names and data types defined in the data model.

Chapter 14. zBX infrastructure elements 951

 Level 04a

Description
The Get BladeCenter Properties operation returns the current properties for the BladeCenter object
specified by {bladecenter-id}.

On successful execution, all of the current properties as defined in “Data model” on page 944 for the
BladeCenter object are provided in the response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing BladeCenter 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.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the BladeCenter object specified by {bladecenter-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” on page 951.

Otherwise, 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 {bladecenter-id} does not designate an existing BladeCenter
object, or the API user does not have object-access permission to the object.

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/bladecenters/ECEC1940F05B39EA9B3AEA5C1600AB1E HTTP/1.1

x-api-session: 5q07hx6jgp2ngn2cypq1zxot76sfwnzky0ih8nddd5hz6bpiue

Figure 515. Get BladeCenter Properties: Request

952 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 21 Jul 2011 17:49:02 GMT
content-type: application/json;charset=UTF-8
content-length: 948
{
"acceptable-status": [
"operating"
],
"ambient-temperature": 18.0,
"class": "bladecenter",
"description": "Represents one BladeCenter",
"exhaust-temperature": 25.5,
"has-hardware-messages": false,
"has-unacceptable-status": false,
"is-locked": false,
"location": "B01B",
"machine-model": "HC1",
"machine-serial": "KQZZXLF",
"machine-type": "8852",
"name": "B.2",
"object-id": "ECEC1940F05B39EA9B3AEA5C1600AB1E",
"object-uri": "/api/bladecenters/ECEC1940F05B39EA9B3AEA5C1600AB1E",
"parent": "/api/racks/b434398a-a328-11e0-9b4a-001f163805d8",
"power-cap-allowed": "allowed",
"power-cap-current": 9561,
"power-cap-maximum": 9561,
"power-cap-minimum": 3473,
"power-capping-state": "custom",
"power-consumption": 1876,
"power-rating": 9561,
"power-save-allowed": "allowed",
"power-saving": "high-performance",
"status": "operating"
}

Figure 516. Get BladeCenter Properties: Response

Activate BladeCenter
The Activate BladeCenter operation activates all blades in the BladeCenter chassis designated by its
object ID. The BladeCenter chassis must be contained within a zBX node. This operation is asynchronous.

HTTP method and URI

POST /api/bladecenters/{bladecenter-id}/operations/activate

In this request, the URI variable {bladecenter-id} is the object ID of the BladeCenter object to activate.

Response body contents

Once the activation request is accepted, the response body contains a JSON object with the following
field:

Field name Type Description

job-uri String/ URI that may be queried to retrieve activation status updates. The
URI canonical URI path for BladeCenter activation status updates is of the
form /api/jobs/{job-id}.

Chapter 14. zBX infrastructure elements 953

 Level 04a

Asynchronous result description

Once the activation job 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 Activate BladeCenter request.

The result document returned by the Query Job Status operation is specified in the description for the
Query Job Status operation. (For more information, see “Query Job Status” on page 80. 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) that are set. (See the description that follows.) The job-results field
is null for asynchronous BladeCenter activation jobs.

Description
The Activate BladeCenter operation activates all blades in the BladeCenter object specified by
{bladecenter-id}. Activation brings blades into a state of "operating". If a blade is already powered on when
the activation operation is requested, the blade is powered off and then brought to a state of "operating".
The order in which the blades of the BladeCenter are activated is unspecified. If the blade is a host to a
virtualization application, then this application is activated also. See “Activating a Virtualization Host” on
page 1032 for more information.

The URI path must designate an existing BladeCenter 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. The
BladeCenter designated by the URI path must be contained within a zBX node (that is, a zBX that has a
type of "node") otherwise status code 400 (Bad Request) is returned. In addition to having object-access
permission to the BladeCenter, the API user must also have permission to the Activate task, otherwise
status code 403 (Forbidden) is returned. The BladeCenter must be in the correct state to perform the
activate action, otherwise status code 409 (Conflict) is returned.

When the BladeCenter activation job 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 activation job. See “Query Job
Status” on page 80 for information on how to query job status. When the activate job has completed, an
asynchronous result message is sent, with “Job status and reason codes” on page 955.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the BladeCenter object designated by {bladecenter-id} and all its blades.
v Action/task permission to the Activate task.

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 953.

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.

954 HMC Web Services API

 Level 04a

Table 374. Activate BladeCenter: 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.
240 The object ID {bladecenter-id} designates a BladeCenter object that is not
contained within a zBX node (that is, it contained within a zBX that does not
have a type of "node").
403 (Forbidden) 0 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID {bladecenter-id} does not designate an existing BladeCenter
object, or the API user does not have object-access permission to it.
409 (Conflict) 1 The object ID {bladecenter-id} designates a BladeCenter object that is not in
the correct state (status) for performing 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 375. Activate BladeCenter: Job status and reason codes.
HTTP error status Reason
code code Description
200 (OK) N/A Activation completed successfully.
500 (Server Error) 100 BladeCenter activation failed.
101 The BladeCenter activation job timed out.

Example HTTP interaction

POST /api/bladecenters/bc000101-0000-0000-0000-000000000000/
operations/activate HTTP/1.1
x-api-session: 2cdh1xvxjwhl1wks636npd16nkvldhij2ptku8une68o3ypep2

Figure 517. Activate BladeCenter: Request

202 Accepted
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Wed, 10 Sep 2014 19:20:02 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri": "/api/jobs/76c88c00-391f-11e4-8e38-02c00001303e"
}

Figure 518. Activate BladeCenter: Response

Chapter 14. zBX infrastructure elements 955

 Level 04a

Deactivate BladeCenter
The Deactivate BladeCenter operation deactivates a BladeCenter chassis specified by its object ID and all
of its blades. The BladeCenter chassis must be contained within a zBX node. This operation is
asynchronous.

HTTP method and URI

POST /api/bladecenters/{bladecenter-id}/operations/deactivate

In this request, the URI variable {bladecenter-id} is the object ID of the BladeCenter chassis object to
deactivate.

Response body contents

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

Field name Type Description

job-uri String/ URI that may be queried to retrieve deactivation status updates. The
URI canonical URI path for BladeCenter deactivation status updates is of the
form /api/jobs/{job-id}.

Asynchronous result description

Once the deactivation job 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 Deactivate BladeCenter)
request.

The result document returned by the Query Job Status operation is specified in the description for the
Query Job Status operation. (For more information, see “Query Job Status” on page 80. 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) that are set. (See the description that follows.) The job-results field
is null for asynchronous BladeCenter deactivation jobs.

Description
The Deactivate BladeCenter operation deactivates the BladeCenter object specified by {bladecenter-id} and
all of its blades. Deactivation powers off all blades after an orderly shutdown of any hardware and
software activity running on the blades. The order in which the blades of the BladeCenter are deactivated
is unspecified. If the blade is a host to a virtualization application, then this application is deactivated
also. See “Deactivating a Virtualization Host” on page 1033 for more information.

The URI path must designate an existing BladeCenter 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. The
BladeCenter designated by the URI path must be contained within a zBX node (that is, a zBX that has a
type of "node") otherwise status code 400 (Bad Request) is returned. In addition to having object-access
permission to the BladeCenter, the API user must also have permission to the Deactivate task, otherwise
status code 403 (Forbidden) is returned. The BladeCenter must be in the correct state to perform the
deactivate action, otherwise status code 409 (Conflict) is returned.

When the BladeCenter deactivation job 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 deactivation job. See “Query Job
Status” on page 80 for information on how to query job status. When the deactivate job has completed,
an asynchronous result message is sent, with “Job status and reason codes” on page 957.

956 HMC Web Services API

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the BladeCenter object specified by {bladecenter-id} and all its blades.
v Action/task permission to the Deactivate task.

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 956.

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.
Table 376. Activate BladeCenter: 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.
240 The object ID {bladecenter-id} designates a BladeCenter object that is not
contained within a zBX node (that is, is contained within a zBX that does not
have a type of "node").
403 (Forbidden) 0 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID {bladecenter-id} does not designate an existing BladeCenter
object, or the API user does not have object-access permission to it.
409 (Conflict) 1 The object ID {bladecenter-id} designates a BladeCenter object that is not in
the correct state (status) for performing 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 377. Deactivate BladeCenter: Job status and reason codes.
HTTP error status Reason
code code Description
200 (OK) N/A Deactivation completed successfully.
500 (Server Error) 100 BladeCenter deactivation failed.
101 The BladeCenter deactivation job timed out.

Example HTTP interaction

POST /api/bladecenters/bc000101-0000-0000-0000-000000000000/
operations/deactivate HTTP/1.1
x-api-session: 48sppzb4o6vnnllj4eguvj4vp8cm7z8oyyfdnz63loy6074vb9

Figure 519. Deactivate BladeCenter: Request

Chapter 14. zBX infrastructure elements 957

 Level 04a

202 Accepted
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Wed, 10 Sep 2014 19:18:22 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri": "/api/jobs/3b52ea4e-391f-11e4-bb52-02c00001303e"
}

Figure 520. Deactivate BladeCenter: Response

Inventory service data

Information about the BladeCenter chassis managed by the HMC can be optionally included in the
inventory data provided by the Inventory Service.

Inventory entries for BladeCenter objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "bladecenter" are to be included. An entry for a particular BladeCenter is
included only if the API user has object-access permission to that object.

For each BladeCenter object to be included, the inventory response array includes an entry that is a JSON
object with the same contents as is specified in the response body contents section for “Get BladeCenter
Properties” on page 951. That is, the data provided is the same as would be provided if a Get
BladeCenter Properties operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single BladeCenter. This object would appear as one array entry in the response
array:

958 HMC Web Services API

 Level 04a

{
"acceptable-status": [
"operating"
],
"additional-status": "unknown",
"ambient-temperature": 18.5,
"class": "bladecenter",
"description": "Represents one BladeCenter",
"exhaust-temperature": 24.5,
"has-hardware-messages": false,
"has-unacceptable-status": false,
"is-locked": false,
"location": "B10B",
"machine-model": "HC1",
"machine-serial": "KQZZXLF",
"machine-type": "8852",
"name": "B.1",
"object-id": "ECEC1940F05B39EA9B3AEA5C1600AB1E",
"object-uri": "/api/bladecenters/ECEC1940F05B39EA9B3AEA5C1600AB1E",
"parent": "/api/racks/28bc03c8-7bc4-11e0-a905-001f163803de",
"power-cap-allowed": "under-group-control",
"power-cap-current": 9444,
"power-cap-maximum": 9444,
"power-cap-minimum": 4042,
"power-capping-state": "disabled",
"power-consumption": 1875,
"power-rating": 9444,
"power-save-allowed": "allowed",
"power-saving": "high-performance",
"status": "operating"
}

Figure 521. BladeCenter object: Sample inventory data

Blade object
A Blade object represents a single blade in the zBX.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
including the operational-status properties, with the following class-specific specialization:
Table 378. Blade object: base managed object properties specializations
Name Qualifier Type Description of specialization
name (ro) String The zManager assigned name of the blade1, 2

(1-64)
description — String This property is not provided.
object-uri — String/URI The canonical URI path for a zBX Blade object is of the form
/api/blades/{blade-id}.
parent — String/URI The canonical URI path for a parent BladeCenter object, in the form
/api/bladecenters/{bladecenter-id}.2
class — String The value "blade".

Chapter 14. zBX infrastructure elements 959

 Level 04a

Table 378. Blade object: base managed object properties specializations (continued)
Name Qualifier Type Description of specialization
status (sc) String The status of the Blade object. Possible values:
Enum v "no-power" - the blade is powered off
v "status-check" - the blade and the console are not communicating
v "not-operating" - the blade is powered on and communicating
with the console but is not running work
v "stopped" - operations on the blade are quiesced
v "definition-error" - an error has occurred when loading the blade
with the firmware
v "operating" - blade is operating normally.
v "service" - The blade has been placed in service mode.
additional-status — String This property is not provided.
Enum
Notes:
1. This name property is currently assigned based on the location of the Blade and is of the form
RackName.BladecenterName.BladeSlot (e.g. B.1.01). However, it is possible that the API could be extended to
allow this property to be writable, in which case an API or User-Interface user could change the name to contain
arbitrary data. Therefore, API client applications that are interested in determining the location of the blade
should not rely on the contents and format of the name property, but rather obtain location information from the
location property.
2. The location of a blade can be moved from slot to slot within a zBX. When a blade is moved to a different slot,
the original URI of this blade is retained. Because the blade name, parent and location is based on the slot
location of the blade, these three properties can change for a given URI when the blade is moved within the
zBX. The relocation of a blade generates an inventory change notification to report the removal of the blade,
then an inventory change notification to report the addition of the blade. Upon addition of the blade, expect the
values of these properties to differ.

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:
Table 379. Blade object: class specific properties
Supported
“type”
Name Qualifier Type Description values
type — String Type of the blade. Values: All
Enum v "power" – the POWER7 blade
v "system-x" – the System x blade
v "isaopt" – the IBM Smart Analytics Optimizer blade
v "dpxi50z" – the DataPower XI50z blade.
processors — Integer number of zBX blade processors. All
cores-per- — Integer The number of processing cores provided by each processor of All
processor the zBX blade.
memory-size — Integer memory size of the zBX blade specified in MB. All
machine-type — String 4 characters. All
machine-model — String 3 characters. All
machine-serial — String 12 characters. All

960 HMC Web Services API

 Level 04a

Table 379. Blade object: class specific properties (continued)

Supported
“type”
Name Qualifier Type Description values
location — String 8 Characters (RxxBBSyy)1 All
v RxxB – BladeCenter vertical position in rack R
v BSyy – physical slot of Blade Server
isaopt-mode (pc) String The mode of the ISAOPT blade. Values: isaopt
Enum v "worker"
v "coordinator"
virtualization- — String/ The canonical URI path for the virtualization host being hosted power,
host URI by the blade. system-x
has-hardware- (pc) Boolean The blade has a hardware message (true) or the blade does not All
messages have a hardware message (false).
licensed- — String The Features that this DPXI50Z blade is licensed for. Each dpxi50z
features licensed feature in the string is delimited with commas (,). The
blade must be Operating to retrieve this property; if it is not,
null is returned instead.
iedn-interfaces (pc) Array of Complex object defining the IEDN Interfaces configured to this dpxi50z
iedn- DPXI50Z blade. The blade must be Operating to retrieve this
interface property; if it is not, null is returned instead.
Objects
Note: 1The location of a blade can be moved from slot to slot within a zBX. When a blade is moved to a different
slot, the original URI of this blade is retained. Because the blade name, parent and location is based on the slot
location of the blade, these three properties can change for a given URI when the blade is moved within the zBX.
The relocation of a blade generates an inventory change notification to report the removal of the blade, then an
inventory change notification to report the addition of the blade. Upon addition of the blade, expect the values of
these properties to differ.

Energy management related additional properties: In addition to the properties defined above, this
object includes the following additional class-specific properties related to energy management. For
further explanation of the various states involved, see Chapter 12, “Energy management,” on page 817.
Table 380. Blade object: energy management related additional properties
Name Qualifier Type Description
power-rating — Integer Specifies the maximum power usage in watts (W) of this blade. This is
a calculated value, as indicated by the electrical rating label or system
rating plate of the blade.
power- (mg) Integer Specifies the current power consumption in watts (W) for this blade.
consumption

Chapter 14. zBX infrastructure elements 961

 Level 04a

Table 380. Blade object: energy management related additional properties (continued)
Name Qualifier Type Description
power-saving — String Specifies the current power saving setting of the blade. Power saving
Enum is used to reduce the energy consumption of a system and can be
managed in the Set Power Saving operation. The possible settings
include:
v "high-performance" - Specifies not reducing the power
consumption of the blade. This is the default setting.
v "low-power" - Specifies reducing the performance of the blade to
allow for low power consumption.
v "not-supported" - Specifies power saving is not supported for this
blade.
v "not-available" - Specifies power-saving property could not be read
from this blade.
v "not-entitled" - Specifies the server is not entitled to power saving.

Additional power savings modes may be introduced as zManager is

extended to support additional power saving capabilities.
power-saving-state — String Specifies the power saving setting of the Blade set by the user. Please
Enum note that this property indicates the user setting and may not match
the real state of the hardware compared to the power-saving property.
The possible settings include:
v "high-performance" - Specifies not reducing the power
consumption of the blade. This is the default setting.
v "low-power" - Specifies low power consumption for all components
of the blade enabled for power saving.
v "not-supported" - Specifies power saving is not supported for this
blade.
v "not-entitled" - Specifies the server is not entitled to power saving.
power-save- — String Should be used to determine if a call of the power save operation is
allowed Enum currently allowed. If a value other than "allowed" is returned the
caller may reckon that the power save operation will fail.

The possible settings include:

v "allowed" - Alter power save setting is allowed for this blade
v "unknown" - Unknown reason
v "not-entitled" - Specifies the server is not entitled to power saving.
v "not-supported" - Specifies power saving is not supported for this
blade.
v "under-group-control" - The blade is under group control and
cannot be individually altered.
power-capping- — String Specifies the current power capping setting of the blade. Power
state Enum capping limits peak power consumption of a system, and you can
manage it with the Set Power Cap operation. The possible settings
include:
v "disabled" - Specifies not setting the power cap of the blade and
not limiting the peak power consumption. This is the default
setting.
v "enabled" - Specifies limiting the peak power consumption of the
blade to the current cap value.
v "not-supported" - Specifies that power capping is not supported for
this blade.
v "not-entitled" - Specifies that the server is not entitled to power
capping.

962 HMC Web Services API

 Level 04a

Table 380. Blade object: energy management related additional properties (continued)
Name Qualifier Type Description
power-cap- — Integer Specifies the minimum value for the blade cap value in watts (W).
minimum
power-cap- — Integer Specifies the maximum value for the blade cap value in watts (W).
maximum
power-cap-current — Integer Specifies the current cap value for the blade in watts (W). The current
cap value indicates the power budget for the blade.
power-cap- — String Should be used to determine if a call of the power capping operation
allowed Enum is currently allowed. If a value other than "allowed" is returned the
caller may reckon that the power capping operation will fail.

The possible settings include:

v "allowed" - Alter power capping setting is allowed for this blade
v "unknown" - Unknown reason
v "not-entitled" - Specifies the server is not entitled to power
capping.
v "not-supported" - Specifies power capping is not supported for this
blade.
v "under-group-control" - The blade is under group control and
cannot be individually altered.

IEDN interface nested object: The IEDN (Intraensemble Data network) Interface object defines the VLan
sub-interface on the DPXI50Z blade:
Table 381. Blade object: IEDN interface nested object properties
Name Type Description
name String (1-64) Display name of the IEDN Interface. Valid characters are: a->z, A->Z, 0->9,
underscore, dash and period. Periods can not be consecutive.
is-active Boolean Administrative State of the IEDN Interface configuration. Values:
v True – Enabled means that the Op-State of the IEDN interface will be up if
there are no errors in the configuration.
v False – Disabled means that the Op-State of the IEDN interface will
always be down.
network-uri String/URI The canonical URI of the virtual network to which this IEDN interface is
connected.

The combination of the virtual network with the Ethernet Interface must be
unique per blade. That is, each interface is associated with one virtual
network, and the virtual network associated with one interface cannot also
be associated with another.
ethernet-interface String Enum The physical Ethernet network interface, either "eth7" or "eth9".

The combination of the virtual network with the Ethernet Interface must be
unique per blade.
ip-address String IP Address in either IPv4 or IPv6 format.

No default value is provided.

net-mask String Network Mask associated with the IP Address in either IPv4 or IPv6 format.

If an ipv4 ip-address is provided, valid values are 0-32, the default is 32.

If an ipv6 ip-address is provided, valid values are 0-128, the default is 128.

Chapter 14. zBX infrastructure elements 963

 Level 04a

Table 381. Blade object: IEDN interface nested object properties (continued)
Name Type Description
secondary-ip-address Array of List of secondary IP Addresses of either IPv4 or IPv6 format.
Strings
No default value is provided.
secondary-net-mask Array of List of secondary Network Masks associated with the Secondary IP
Strings Addresses of either IPv4 or IPv6 format.

If a secondary ipv4 ip-address is provided, valid values are 0-32, the default
is 32.

If a secondary ipv6 ip-address is provided, valid values are 0-128, the default
is 128.
ipv4-gateway String The IPv4 address to use for the default IPv4 gateway. No default value is
provided.
ipv6-gateway String The IPv6 address to use for the default IPv6 gateway. No default value is
provided.
is-ipv6-auto-config- Boolean True if the IPv6 Auto configuration is enabled. Otherwise, false. When
enabled enabled, the interface is configured with a link-local secondary address.
When disabled, uses the defined primary address.

Default is false.
is-slaac Boolean IPv6 Auto configuration must be enabled to utilize this option.

True if IPv6 Stateless Address is enabled. Otherwise, false. When enabled,

the IPv6 address is obtained when connected to the network. When disabled,
the interface uses the defined primary address.

Default is false.
dad-transmit Integer IPv6 Auto configuration must be enabled to utilize this option.

Specify the number of duplicate address detection (DAD) attempts to

perform.

Default is 1.
dad-transmit-delay Integer IPv6 Auto configuration must be enabled to utilize this option.

When the number of duplicate address detection (DAD) attempts is greater

than 1, specify the delay between attempts in milliseconds.

Default is 1000.
mac-address String (17) The MAC address represented as 6 groups of two lower-case hexadecimal
digits separated by colons, e.g. “01:23:45:67:89:ab”. Length is 17 characters.
The MAC address uses the ensemble prefix.

Operations
List Blades in a BladeCenter
The List Blades in a BladeCenter operation lists all the blades in a BladeCenter.

HTTP method and URI

GET /api/bladecenters/{bladecenter-id}/blades

In this request, the URI variable {bladecenter-id} is the object ID of the BladeCenter object whose blades are
to be obtained.

964 HMC Web Services API

 Level 04a

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) used to limit returned objects

Response body contents

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

Field name Type Description

blades Array of Array of nested blade-info objects, described in the next table. If the
objects BladeCenter does not have any blades mounted in it, an empty array is
provided.

Each nested blade-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the Blade object in the form /api/blades/{blade-id}
URI
name String The name property of the Blade object (for example, B.1.01)
status String The status property of the Blade object
Enum
type String The type of the blade.
Enum

Description
The List Blades in a BladeCenter operation lists the blades that are in the BladeCenter. The object URI,
name, status, and type are provided for each blade.

If the name query parameter is specified, then a blade is included in the list only if the name pattern
matches the name property of the object.

A blade is included in the list only if the API user has object-access permission for that object. If the
HMC is a manager of a blade, but the API user does not have permission to it, that object is omitted
from the list, but no error status code results.

If the HMC does not manage any blades, 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 BladeCenter object specified by the URI
v Object-access permission to any Blade object that is 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 14. zBX infrastructure elements 965

 Level 04a

Otherwise, 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 {bladecenter-id} does not designate a BladeCenter 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/bladecenters/ECEC1940F05B39EA9B3AEA5C1600AB1E/blades HTTP/1.1

x-api-session: 5q07hx6jgp2ngn2cypq1zxot76sfwnzky0ih8nddd5hz6bpiue

Figure 522. List Blades in a BladeCenter: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 21 Jul 2011 17:49:02 GMT
content-type: application/json;charset=UTF-8
content-length: 386
{
"blades": [
{
"name": "B.2.02",
"object-uri": "/api/blades/938706AC3FF111D78B5600215EC0330E",
"status": "operating",
"type": "power"
},
{
"name": "B.2.03",
"object-uri": "/api/blades/B8210BC02D1E11E0AE81E41F13FE1430",
"status": "operating",
"type": "system-x"
}
]
}

Figure 523. List Blades in a BladeCenter: Response

List Blades in a zBX

The List Blades in a zBX operation lists all the blades in all the BladeCenters in a zBX. This operation
has an optional parameter to specify the blade type to return in the list. If this parameter is omitted, all
blades of all blade types are returned.

HTTP method and URI

GET /api/zbxs/{zbx-id}/blades

966 HMC Web Services API

 Level 04a

In this request, the URI variable {zbx-id} is the object ID of the zBX object whose blades are to be
obtained.

Query parameters:

Name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) used to limit returned objects
based on matching the objects name property
type String Optional Filter string used to limit returned objects to those that have a
matching type property. Value must be a valid blade type property
value. To request that the results include blades of multiple types,
specify this parameter multiple times. For example
“type=power&type=isaopt”.

Response body contents

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

Field name Type Description

blades Array of Array of nested blade-info objects, described the next table. If the zBX
objects does not have any blades, an empty array is provided.

Each nested blade-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the Blade object in the form /api/blades/{blade-id}
URI
name String The name property of the Blade object (for example, B.1.01)
status String The status property of the Blade object
Enum
type String The type of the blade
Enum

Description
The List Blades in a zBX operation lists the blades in the zBX. The object URI, name, status, and type are
provided for each blade.

A blade is included in the list only if the API user has object-access permission for that object. If the
HMC is a manager of a blade, but the API user does not have permission to it, that object is omitted
from the list, but no error status code results.

If the name query parameter is specified, the returned list is limited to those blades that have a name
property matching at least one specified name filter pattern. If the name parameter is omitted, this
filtering is not done.

If the type query parameter is specified, the parameter is validated to ensure it is a valid blade type
property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid, the
returned list is limited to those blades that have a type property matching a specified type value. If the
type parameter is omitted, this filtering is not done.

Chapter 14. zBX infrastructure elements 967

 Level 04a

If both the name and type query parameters are specified, a blade is included in the list only if it passes
both the name and type filtering criteria.

If the HMC does not manage any blades, 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 to which the zBX specified by the URI is attached (for a
CPC-attached zBX).
v Object-access permission to the zBX specified by the URI (for a zBX node).
v Object-access permission to any Blade object which is 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 967.

Otherwise, 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 {zbx-id} does not designate a zBX object, or the API user does
not have object-access permission to it.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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/zbxs/54a9716c-a326-11e0-9469-001f163805d8/blades HTTP/1.1

x-api-session: 5q07hx6jgp2ngn2cypq1zxot76sfwnzky0ih8nddd5hz6bpiue

Figure 524. List Blades in a zBX: Request

968 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 21 Jul 2011 17:49:02 GMT
content-type: application/json;charset=UTF-8
content-length: 386
{
"blades": [
{
"name": "B.2.02",
"object-uri": "/api/blades/938706AC3FF111D78B5600215EC0330E",
"status": "operating",
"type": "power"
},
{
"name": "B.2.03",
"object-uri": "/api/blades/B8210BC02D1E11E0AE81E41F13FE1430",
"status": "operating",
"type": "system-x"
}
]
}

Figure 525. List Blades in a zBX: Response

Get Blade Properties

The Get Blade Properties operation retrieves the properties of a single Blade object that is designated by
its object ID.

HTTP method and URI

GET /api/blades/{blade-id}

In this request, the URI variable {blade-id} is the object ID of the Blade object for which properties are to
be obtained.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Rack object as defined in the “Data model” on page 944. 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 Blade Properties operation returns the current properties for the Blade object specified by
{blade-id}.

On successful execution, all of the current properties as defined in“Data model” on page 959 for the
Blade object are provided in the response body, and HTTP status code 200 (OK) is returned. If the blade
is a DPXI50z blade and its current status is not "operating", then null is returned as the value of the
licensed-features and iedn-interfaces properties, but the operation otherwise succeeds.

The URI path must designate an existing Blade 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.

Chapter 14. zBX infrastructure elements 969

 Level 04a

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Blade object specified by {blade-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” on page 969.

Otherwise, 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 {blade-id} does not designate an existing Blade object, the object
ID designates a Blade object that is not of the correct type, or the API user
does not have object-access permission to the object.

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/blades/B8210BC02D1E11E0AE81E41F13FE1430 HTTP/1.1

x-api-session: 5q07hx6jgp2ngn2cypq1zxot76sfwnzky0ih8nddd5hz6bpiue

Figure 526. Get Blade Properties: Request

970 HMC Web Services API

 Level 04a

server: zSeries management console API web server / 1.0

cache-control: no-cache
date: Thu, 21 Jul 2011 17:49:03 GMT
content-type: application/json;charset=UTF-8
content-length: 989
{
"acceptable-status": [
"operating"
],
"class": "blade",
"cores-per-processor": 8,
"has-hardware-messages": false,
"has-unacceptable-status": false,
"is-locked": false,
"location": "B01BBS03",
"machine-model": "AC1",
"machine-serial": "06NL721",
"machine-type": "7872",
"memory-size": 131072,
"name": "B.2.03",
"object-id": "B8210BC02D1E11E0AE81E41F13FE1430",
"object-uri": "/api/blades/B8210BC02D1E11E0AE81E41F13FE1430",
"parent": "/api/bladecenters/ECEC1940F05B39EA9B3AEA5C1600AB1E",
"power-cap-allowed": "allowed",
"power-cap-current": 268,
"power-cap-maximum": 500,
"power-cap-minimum": 268,
"power-capping-state": "enabled",
"power-consumption": 241,
"power-rating": 500,
"power-save-allowed": "unknown",
"power-saving": "not-supported",
"processors": 2,
"status": "operating",
"type": "system-x",
"virtualization-host": "/api/virtualization-hosts/931b25d6-82e1-11e0-b9e4-f0def10bff8d"
}

Figure 527. Get Blade Properties: Response for blade of type "system-x" (similar for type "power")

Chapter 14. zBX infrastructure elements 971

 Level 04a

200 OK
x-request-id: Sx3 Rx13
x-client-correlator: 21
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2011 14:22:55 GMT
content-type: application/json;charset=UTF-8
content-length: 899
{
"acceptable-status": [
"operating"
],
"class": "blade",
"cores-per-processor": 8,
"has-hardware-messages": false,
"has-unacceptable-status": false,
"iedn-interfaces": [],
"is-locked": false,
"licensed-features": " MQ, TAM, DataGlue, JAXP-API, PKCS7-SMIME, SQL-ODBC,
WebSphere-JMS, RaidVolume, iSCSI, LocateLED, AppOpt, zBX",
"location": "C01BBS01",
"machine-model": "4BX",
"machine-serial": "6800442",
"machine-type": "4195",
"memory-size": 12288,
"name": "C.2.01",
"object-id": "eadb0be8-6fdb-11df-8f6a-e41f137a29e4",
"object-uri": "/api/blades/eadb0be8-6fdb-11df-8f6a-e41f137a29e4",
"parent": "/api/bladecenters/e3ee0adc-27c0-355e-93b9-ace8a3d2da15",
"power-cap-allowed": "under-group-control",
"power-cap-current": 444,
"power-cap-maximum": 444,
"power-cap-minimum": 144,
"power-capping-state": "disabled",
"power-consumption": 115,
"power-rating": 444,
"power-save-allowed": "unknown",
"power-saving": "not-supported",
"processors": 2,
"status": "operating",
"type": "dpxi50z"
}

Figure 528. Get Blade Properties: Response for blade of type "dpx150z":

972 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2011 14:22:55 GMT
content-type: application/json;charset=UTF-8
content-length: 773
{
"acceptable-status": [
"operating"
],
"class": "blade",
"cores-per-processor": 8,
"has-hardware-messages": false,
"has-unacceptable-status": false,
"is-locked": false,
"isaopt-mode": "coordinator",
"location": "B10BBS01",
"machine-model": "PEL",
"machine-serial": "KQWZTNG",
"machine-type": "7870",
"memory-size": 49152,
"name": "B.1.01",
"object-id": "fa8d1eea-95ab-33cf-bf86-a03cc1346222",
"object-uri": "/api/blades/fa8d1eea-95ab-33cf-bf86-a03cc1346222",
"parent": "/api/bladecenters/2ae200b3-fa8e-3db7-b34a-ec08780aaac6",
"power-cap-allowed": "under-group-control",
"power-cap-current": 515,
"power-cap-maximum": 500,
"power-cap-minimum": 220,
"power-capping-state": "disabled",
"power-consumption": 181,
"power-rating": 500,
"power-save-allowed": "unknown",
"power-saving": "not-supported",
"processors": 2,
"status": "operating",
"type": "isaopt"
}

Figure 529. Get Blade Properties: Response for blade of type "isaopt":

Activate a Blade
The Activate a Blade operation activates a Blade object designated by its object ID. This operation is
asynchronous.

HTTP method and URI

POST /api/blades/{blade-id}/operations/activate

In this request, the URI variable {blade-id} is the object ID of the Blade object to activate.

Response body contents

Once the activation request is accepted, the response body is a JSON object with the following fields:

Field name Type Description

job-uri String/ URI that may be queried to retrieve activation status updates.
URI

Chapter 14. zBX infrastructure elements 973

 Level 04a

Asynchronous result description

Once the activation job 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 Activate a Blade operation.

The result document returned by the Query Job Status operation is specified in the description for the
Query Job Status operation. (For more information, see “Query Job Status” on page 80.) 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) that are set. (See the description that follows.) The job-results field
is null for asynchronous blade activation jobs.

Description
The Activate a Blade operation activates the Blade object specified by {blade-id}. Activation brings the
blade into a state of “operating”. If the blade is already powered on when the activation operation is
requested, the blade is powered off and then brought to a state of “operating”. If the blade is a host to a
virtualization application, then this application is activated also. See the “Activating a Virtualization
Host” on page 1032 for more information.

The URI path must designate an existing Blade 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. In
addition, the API user must have action access permission to the Activate task; otherwise, status code 403
(Forbidden) is returned.

When the blade activation job 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 activation job. See “Query Job Status” on
page 80 for information on how to query job status. When the activate job has completed, an
asynchronous result message is sent with job status and reason codes described in “Job status and reason
codes” on page 975.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Blade object specified by {blade-id}
v Action/task permission to the Activate 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 973.

Otherwise, 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.
403 (Forbidden) 0 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID {blade-id} does not designate an existing Blade object, or the
API user does not have object-access permission to it.
409 (Conflict) 1 The object ID {blade-id} designates a Blade object that is not in the correct
state (status) for performing the requested operation.

974 HMC Web Services API

 Level 04a

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

Reason
Job status code code Description
200 (OK) N/A Activation completed successfully.
500 (Server Error) 100 Blade activation failed.
500 (Server Error) 101 Blade activation job timed out.

Example HTTP interaction

POST /api/blades/62f508a6-2d21-11e0-813b-e41f13fe15a8/operations/activate HTTP/1.1

x-api-session: 6c6s3b1p02v9x9az6brcic9q9dk34jjhxwllw0sqegu0ktia5k

Figure 530. Activate a Blade: Request

202 Accepted
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 05:45:45 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri": "/api/jobs/b8824300-1728-11e1-aea4-0010184c8334"
}

Figure 531. Activate a Blade: Response

Deactivate a Blade
The Deactivate a Blade operation deactivates a Blade object designated by its object ID. This operation is
asynchronous.

HTTP method and URI

POST /api/blades/{blade-id}/operations/deactivate

In this request, the URI variable {blade-id} is the object ID of the Blade object to deactivate.

Response body contents

Once the activation request is accepted, the response body is a JSON object with the following fields:

Field name Type Description

job-uri String/ URI that may be queried to retrieve deactivation status updates.
URI

Chapter 14. zBX infrastructure elements 975

 Level 04a

Asynchronous result description

Once the deactivation job 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 Deactivate a Blade operation.

The result document returned by the Query Job Status operation is specified in the description for the
Query Job Status operation. (For more information, see “Query Job Status” on page 80). 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) that are set. (See the description that follows.) The job-results field
is null for asynchronous blade deactivation jobs.

Description
The Deactivate a Blade operation activates the Blade object specified by {blade-id}. Deactivation powers
off the blade after an orderly shutdown of any hardware and software activity running on the blade. If
the blade is a host to a virtualization application, then this application is deactivated also. See the
“Deactivating a Virtualization Host” on page 1033 for more information.

The URI path must designate an existing Blade 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. In
addition, the API user must have action access permission to the Deactivate task; otherwise, status code
403 (Forbidden) is returned. If the blade is not in the correct state to perform the deactivate, a status code
of 409 (Conflict) is returned.

When the blade deactivation job 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 deactivation job. See “Query Job Status”
on page 80 for information on how to query job status. When the activate job has completed, an
asynchronous result message is sent with job status and reason codes described in “Job status and reason
codes” on page 977.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Blade object specified by {blade-id}
v Action/task permission to the Deactivate 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 975.

Otherwise, 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.
403 (Forbidden) 0 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID {blade-id} does not designate an existing Blade object, or the
API user does not have object-access permission to it.
409 (Conflict) 1 The object ID {blade-id} designates a Blade object that is not in the correct
state (status) for performing the requested operation.

976 HMC Web Services API

 Level 04a

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

Reason
Job status code code Description
200 (OK) N/A Deactivation completed successfully.
500 (Server Error) 100 Blade deactivation failed.
500 (Server Error) 101 Blade deactivation job timed out.

Example HTTP interaction

POST /api/blades/62f508a6-2d21-11e0-813b-e41f13fe15a8/operations/deactivate HTTP/1.1

x-api-session: 6c6s3b1p02v9x9az6brcic9q9dk34jjhxwllw0sqegu0ktia5k

Figure 532. Deactivate a Blade: Request

202 Accepted
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 05:45:04 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri": "/api/jobs/a0247864-1728-11e1-aea4-0010184c8334"
}

Figure 533. Deactivate a Blade: Response

Create IEDN Interface for a DataPower XI50z Blade

The Create IEDN Interface for a DataPower XI50z Blade operation adds an IEDN interface with the
designated properties to the DataPower XI50z blade configuration.

HTTP method and URI

POST /api/blades/{blade-id}/iedn-interfaces

In this request, the URI variable {blade-id} is the object ID of the DPXI50Z Blade object to which the IEDN
interface is to be added.

Request body contents

The request body contains the following writable IEDN interface properties of the DPXI50Z Blade object
that will be used to create the IEDN interface:

Field name Type Rqd/Opt Description

name String Required The name of the IEDN interface. Valid characters are: a-z, A-Z, 0-9,
(1-64) underscore, dash and period. Periods cannot be consecutive.

Must be unique per blade.

Chapter 14. zBX infrastructure elements 977

 Level 04a

Field name Type Rqd/Opt Description

is-active Boolean Required Administrative state of the IEDN interface configuration. Values:
v True – Enabled means that the Op-State of the IEDN interface will
be up if there are no errors in the configuration
v False – Disabled means that Op-State of the IEDN interface will
always be down
network-uri String/URI Required The canonical URI of the virtual network to which this IEDN
interface is connected.

The combination of the virtual network with the Ethernet interface

must be unique per blade. That is, each interface is associated with
one virtual network, and the virtual network associated with one
interface cannot be associated with another.
ethernet-interface String Required The physical Ethernet network interface – either "eth7" or "eth9".
Enum
The combination of the virtual network with the Ethernet interface
must be unique per blade.
ip-address String Optional An IP address in either IPv4 or IPv6 format.

No default value is provided.

net-mask String Optional The network mask associated with the IP address in either IPv4 or
IPv6 format.

If an IPv4 ip-address is provided, valid values are 0-32; the default is

32.

If an IPv6 ip-address is provided, valid values are 0-128; the default

is 128.
secondary-ip- List of Optional A list of secondary IP addresses in either IPv4 or IPv6 format.
address Strings
No default value is provided.
secondary-net-mask List of Optional A list of secondary network masks associated with the secondary IP
Strings addresses in either IPv4 or IPv6 format.

If a secondary IPv4 ip-address is provided, valid values are 0-32, the

default is 32.

If a secondary IPv6 ip-address is provided, valid values are 0-128,

the default is 128
ipv4-gateway String Optional The IPv4 address to use for the default IPv4 gateway.

No default value is provided.

ipv6-gateway String Optional The IPv6 address to use for the default IPv6 gateway

No default value is provided.

is-ipv6-auto- Boolean Optional True if the IPv6 auto configuration is enabled. Otherwise, false.
config-enabled
When enabled, the interface is configured with a link-local secondary
address. When disabled, the interface uses the defined primary
address.

Default is false.

978 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

is-slaac Boolean Optional IPv6 auto configuration must be enabled to utilize this option.

True if IPv6 stateless address is enabled. Otherwise, false.

When enabled, the IPv6 address is obtained when connected to the

network. When disabled, the interface uses the defined primary
address.

Default is false.
dad-transmit Integer Optional IPv6 auto configuration must be enabled to utilize this option.

The number of duplicate address detection (DAD) attempts to

perform.

Default is 1.
dad-transmit-delay Integer Optional IPv6 auto configuration must be enabled to utilize this option.

When the number of duplicate address detection (DAD) attempts is

greater than 1, the delay between attempts in milliseconds.

Default is 1000.

Response body contents

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

Field name Type Description

element-uri String/ Canonical URI path of the IEDN interface object, in the form
URI /api/blades/{blade-id}/iedn-interfaces/{iedn-interface-id}, where
{iedn-interface-id} is the value of the name property.

Description
The Create IEDN Interface for a DataPower XI50z Blade operation creates the IEDN interface for the
DataPower XI50z blade as specified by the given properties. The DPXI50Z blade must be operating to
perform this operation. 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.

The add of the IEDN interface is permitted if the API user has object-access permission for that
DataPower XI50z blade.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the DPXI50z Blade object specified by {blade-id}
v Action/task permission to the zBX Blade Details task.
v Object-access permission to the CPC associated with the zBX containing the DPXI50z Blade object
specified by the URI variable {blade-id} (for CPC-attached zBX objects).
v Object-access permission to the zBX node containing the DPXI50z Blade object specified by the URI
variable {blade-id} (for zBX node objects).
v Object-access permission to the Virtual Network object specified by the network-uri field.

Chapter 14. zBX infrastructure elements 979

 Level 04a

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 979

Otherwise, 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.
403 (Forbidden) 0 The API user does not have task access authority to the zBX Blade Details
task.
404 (Not Found) 1 The object ID {blade-id} does not designate an existing Blade object, or the
API user does not have object-access permission to it.
409 (Conflict) 1 The object ID {blade-id} designates a Blade object that is not in the correct
state (status) for performing the requested operation. The blade must be
operating to perform this operation.

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

Delete IEDN Interface for a DataPower XI50z Blade

The Delete IEDN Interface for a DataPower XI50z Blade operation removes the specified IEDN interface
for a DataPower XI50z blade.

HTTP method and URI

DELETE /api/blades/{blade-id}/iedn-interfaces/{iedn-interface-id}

URI variables

Variable Description
{iedn-interface-id} Element ID of the IEDN interface
{blade-id} Object ID of the blade

Description
The Delete IEDN Interface for a DataPower XI50z Blade operation deletes the IEDN interface that is
defined for the DataPower XI50z blade. The DPXI50Z blade must be operating to perform this operation.

The IEDN interface is removed only if the API user has object-access permission for that DataPower
XI50z blade.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the DPXI50z Blade object specified by {blade-id}
v Action/task permission to the zBX Blade Details task.
v Object-access permission to the CPC associated with the zBX containing the DPXI50z Blade object
specified by the URI variable {blade-id} (for CPC-attached zBX objects).

980 HMC Web Services API

 Level 04a

v Object-access permission to the zBX node containing the DPXI50z Blade object specified by the URI
variable {blade-id} (for zBX node objects).

HTTP status and reason codes

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

Otherwise, 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 {blade-id} does not designate an existing Blade object, or the
API user does not have object-access permission to it.
2 The object ID {iedn-interface-id} does not exist on the HMC.
409 (Conflict) 1 The object ID {blade-id} designates a Blade object that is not in the correct
state (status) for performing the requested operation. The blade must be
operating to perform this operation.

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

Inventory service data

Information about the blades managed by the HMC can be optionally included in the inventory data
provided by the Inventory Service.

Inventory entries for Blade objects are included in the response to the Inventory Service's Get Inventory
operation when the request specifies (explicitly by inventory class, implicitly via a containing category, or
by default) that objects of the various blade type-specific inventory classes are to be included. An entry
for a particular blade is included only if the API user has object-access permission to that blade and the
applicable type-specific inventory class has been specified, as described in the following table:

Inventory class Includes blades with “type” value

power-blade power
system-x-blade system-x
dpxi50z-blade dpxi50z
isaopt-blade isaopt

For each Blade object to be included, the inventory response array includes an entry that is a JSON object
with the same contents as is specified in the response body contents section for “Get Blade Properties” on
page 969. That is, the data provided is the same as would be provided if a Get Blade Properties
operation were requested targeting this object.

Sample inventory data

The following fragments are examples of the JSON objects that would be included in the Get Inventory
response to describe a single Blade object of a particular type. These objects would appear as array
entries in the response array.

Chapter 14. zBX infrastructure elements 981

 Level 04a

{
"acceptable-status": [
"operating"
],
"class": "blade",
"cores-per-processor": 8,
"has-hardware-messages": false,
"has-unacceptable-status": true,
"is-locked": false,
"location": "B10BBS13",
"machine-model": "71Y",
"machine-serial": "06C9FDA",
"machine-type": "8406",
"memory-size": 32768,
"name": "B.1.13",
"object-uri": "/api/blades/D5C5CB8A3F5511D78B5600215EC03866",
"parent": "/api/bladecenters/ECEC1940F05B39EA9B3AEA5C1600AB1E",
"power-cap-allowed": "under-group-control",
"power-cap-current": 277,
"power-cap-maximum": 382,
"power-cap-minimum": 277,
"power-capping-state": "disabled",
"power-consumption": 151,
"power-rating": 382,
"power-save-allowed": "under-group-control",
"power-saving": "high-performance",
"processors": 8,
"status": "status-check",
"type": "power",
"virtualization-host": "/api/virtualization-hosts/baa17718-2990-11e0-8d5b-001f163803de"
}

Figure 534. Sample inventory data for a blade of type "power"

982 HMC Web Services API

 Level 04a

{
"acceptable-status": [
"operating"
],
"class": "blade",
"cores-per-processor": 8,
"has-hardware-messages": false,
"has-unacceptable-status": true,
"is-locked": false,
"location": "B10BBS12",
"machine-model": "AC1",
"machine-serial": "06NL728",
"machine-type": "7872",
"memory-size": 131072,
"name": "B.1.12",
"object-uri": "/api/blades/62F508A62D2111E0813BE41F13FE15A8",
"parent": "/api/bladecenters/ECEC1940F05B39EA9B3AEA5C1600AB1E",
"power-cap-allowed": "under-group-control",
"power-cap-current": 278,
"power-cap-maximum": 519,
"power-cap-minimum": 278,
"power-capping-state": "disabled",
"power-consumption": 249,
"power-rating": 519,
"power-save-allowed": "unknown",
"power-saving": "not-supported",
"processors": 2,
"status": "status-check",
"type": "system-x",
"virtualization-host": "/api/virtualization-hosts/47d3a864-82e1-11e0-b9e4-f0def10bff8d"
}

Figure 535. Sample inventory data for a blade of type "system-x"

Chapter 14. zBX infrastructure elements 983

 Level 04a

984 HMC Web Services API

 Level 04a

Chapter 15. Virtualization management

zManager provides facilities for running virtualized computing systems, termed Virtual Servers, on top of
system-firmware-managed hosting environments that coordinate the physical system resources that the
virtual servers share. These hosting environments upon which the virtual servers run are known as
Virtualization Hosts.

The Virtualization Host APIs provide access to the set of virtualization hosts managed by an Ensemble.
PowerVM, x Hyp, z/VM and PR/SM virtualization hosts are supported. APIs exist to query
virtualization hosts, retrieve and update select properties of virtualization hosts, and perform operations
on virtualization hosts, such as activate and deactivate.

Within Z, a virtual server can be described as a container for an operating system. It could be a logical
partition on an IBM POWER7 Blade, a virtual machine on an IBM System x Blade, a virtual machine
defined under z/VM, or an IBM Z logical partition (LPAR). It is created in cooperation with the
virtualization host on the hardware involved. The virtual server container includes the definition of
processor resources, network interfaces and storage devices it will access.

Virtualization host operations summary

The following tables provide an overview of the virtualization host operations provided.
Table 382. Virtualization management - virtualization host: operations summary
Operation name HTTP method and URI path
“List Virtualization Hosts of GET /api/zbxs/{zbx-id}/virtualization-hosts
a zBX (Node)” on page 998
“List Virtualization Hosts of GET /api/ensembles/{ensemble-id}/nodes/{node-id}/virtualization-hosts
a Node” on page 1000
“List Virtualization Hosts of GET /api/ensembles/{ensemble-id}/virtualization-hosts
an Ensemble” on page 1003
“List Virtualization Hosts of GET /api/cpcs/{cpc-id}/virtualization-hosts
a CPC” on page 1005
“Get Virtualization Host GET /api/virtualization-hosts/{virt-host-id}
Properties” on page 1008
“Update Virtualization Host POST /api/virtualization-hosts/{virt-host-id}
Properties” on page 1013
“List Virtual Switches” on GET /api/virtualization-hosts/{virt-host-id}/virtual-switches
page 1015
“Get Virtual Switch GET /api/virtualization-host/{virt-host-id}/virtual-switches/{virtual-switch-
Properties” on page 1016 id}
“Create IEDN Virtual POST /api/virtualization-hosts/{virt-host-id}/virtual-switches/operations/add-
Switch” on page 1019 iedn
“Create QDIO Virtual POST /api/virtualization-hosts/{virt-host-id}/virtual-switches/operations/add-
Switch” on page 1022 qdio
“Get Switch Controllers” on GET /api/virtualization-hosts/{virt-host-id}/operations/get-switch-controllers
page 1025
“Update Virtual Switch” on POST /api/virtualization-hosts/{virt-host-id}/virtual-switches/{virtual-
page 1027 switch-id}

© Copyright IBM Corp. 2017, 2018 985

 Level 04a

Table 382. Virtualization management - virtualization host: operations summary (continued)

Operation name HTTP method and URI path
“Delete Virtual Switch” on DELETE /api/virtualization-hosts/{virt-host-id}/virtual-switches/{virtual-
page 1031 switch-id}

Table 383. Virtualization management- virtualization host: URI variables

Variable Description
{zbx-id} Object ID of a zBX object
{node-id} Object ID of a Node object
{ensemble-id} Object ID of an Ensemble object
{cpc-id} Object ID of a CPC object
{virt-host-id} Object ID of a Virtualization Host object
{virtual-switch-id} Element ID of a virtual switch

Virtual server operations summary

The following tables provide an overview of the virtual server operations provided.
Table 384. Virtualization management - virtual server: operations summary
Operation name HTTP method and URI path
“List Virtual Servers of a GET /api/zbxs/{zbx-id}/virtual-servers
zBX (Node)” on page 1063
“List Virtual Servers of a GET /api/ensembles/{z-ensemble-id}/nodes/{node-id}/virtual-servers
Node” on page 1065
“List Virtual Servers of an GET /api/ensembles/{ensemble-id}/virtual-servers
Ensemble” on page 1067
“List Virtual Servers of a GET /api/cpcs/{cpc-id}/virtual-servers
CPC” on page 1070
“List Virtual Servers of a GET /api/virtualization-hosts/{virt-host-id}/virtual-servers
Virtualization Host” on page
1073
“Create Virtual Server” on POST /api/virtualization-hosts/{virt-host-id}/virtual-servers
page 1075
“Delete Virtual Server” on DELETE /api/virtual-servers/{virtual-server-id}
page 1080
“Get Virtual Server GET /api/virtual-servers/{virtual-server-id}
Properties” on page 1082
“Update Virtual Server POST /api/virtual-servers/{virtual-server-id}
Properties” on page 1090
“Create Network Adapter” POST /api/virtual-servers/{virtual-server-id}/network-adapters
on page 1095
“Delete Network Adapter” DELETE /api/virtual-servers/{virtual-server-id}/network-adapters/{network-
on page 1098 adapter-id}
“Get Network Adapter GET /api/virtual-servers/{virtual-server-id}/network-adapters/{network-
Properties” on page 1099 adapter-id}
“Update Network Adapter” POST /api/virtual-servers/{virtual-server-id}/network-adapters/{network-
on page 1101 adapter-id}

986 HMC Web Services API

 Level 04a

Table 384. Virtualization management - virtual server: operations summary (continued)

Operation name HTTP method and URI path
“Reorder Network Adapter” POST /api/virtual-servers/{virtual-server-id}/operations/reorder-network-
on page 1104 adapters
“Create Virtual Disk” on POST /api/virtual-servers/{virtual-server-id}/virtual-disks
page 1106
“Delete Virtual Disk” on DELETE /api/virtual-servers/{virtual-server-id}/virtual-disks/{virtual-disk-
page 1110 id}
“Get Virtual Disk GET /api/virtual-servers/{virtual-server-id}/virtual-disks/{virtual-disk-id}
Properties” on page 1112
“Update Virtual Disk POST /api/virtual-servers/{virtual-server-id}/virtual-disks/{virtual-disk-id}
Properties” on page 1114
“Reorder Virtual Disks” on POST /api/virtual-servers/{virtual-server-id}/operations/reorder-virtual-disks
page 1117
“Activate Virtual Server” on POST /api/virtual-servers/{virtual-server-id}/operations/activate
page 1119
“Deactivate Virtual Server” POST /api/virtual-servers/{virtual-server-id}/operations/deactivate
on page 1121
“Mount Virtual Media” on POST /api/virtual-servers/{virtual-server-id}/operations/mount-virtual-media
page 1124
“Mount Virtual Media POST /api/virtual-servers/{virtual-server-id}/operations/mount-virtual-media-
Image” on page 1126 image
“Unmount Virtual Media” POST /api/virtual-servers/{virtual-server-id}/operations/unmount-virtual-media
on page 1128
“Migrate Virtual Server” on POST /api/virtual-servers/{virtual-server-id}/operations/migrate
page 1130
“Initiate Virtual Server POST /api/virtual-servers/{virtual-server-id}/operations/initiate-dump
Dump” on page 1132

Table 385. Virtualization management - virtual server: URI variables

Variable Description
{zbx-id} Object ID of a zBX object
{node-id} Object ID of a Node object
{ensemble-id} Object ID of an ensemble object
{cpc-id} Object ID of a CPC object
{virt-host-id} Object ID of a Virtualization Host object
{virtual-server-id} Object ID of a Virtual Server object
{network-adapter-id} Element ID of a network adapter object
{virtual-disk-id} Element ID of a virtual disk object

Virtualization Host object

A Virtualization Host object represents a single virtualization host.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
with the following class-specific specialization:

Chapter 15. Virtualization management 987

 Level 04a

Table 386. Virtualization Host object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/ URI The canonical URI path for a Virtualization Host object is of the
form /api/virtualization-hosts/{object-id}.
name1 (ro) String (1-64) The display name of the virtualization host. Not writable. The name
is derived from the name of the underlying hosting environment
(e.g. blade).
class — String (19) The class will always be "virtualization-host".
parent — String/ URI The canonical URI path of the node that manages the virtualization
host.
status (sc) String Enum The current operational status of the virtualization host.

Valid values common to all types:

v "operating" - indicates virtualization host is running normally
v "not-operating" - indicates the virtualization host is deactivated,
in the process of loading, or has a error
v "status-check" - indicates the support element is not
communicating with the CPC or zBX node
v "not-communicating" - indicates the HMC is not communicating
with the support element.

Valid values for type "power-vm", "x-hyp":

v "definition-error" - indicates that the specified zBX Blade does
not match the characteristics of the installed zBX Blade
v "no-power" - indicates the zBX Blade powered off
v "stopped" - indicates the Support Element with the zBX Blade is
stopped.

Valid values for type "zvm":

v "exceptions" - indicates at least one CP is operating, but at least
one CP is not operating.
v "not-activated" - indicates the image has not been activated.

Valid values for type "prsm":

v "degraded" - indicates the CPC or zBX node is operating but
some hardware is not available.
v "exceptions" - indicates that at least one Central Processor (CP) is
operating, but at least one CP is not operating.
v "no-power" - indicates that the CPCor zBX node is powered off.
v "service" - indicates that CPs are in service status.
v "service-required" - indicates that the CPC or zBX node is still
operating but is using the last redundant part of a particular
type.
additional status — This property is not provided.
1
Note: The location of a blade can be moved from slot to slot within a zBX. When a blade is moved to a different
slot, the original URI of this blade and Virtualization Host object is retained. Since the name of the blade and
virtualization host is based on the slot location of the blade, the name property can change for a given URI when
the blade is moved within the zBX. The relocation of a blade generates inventory change notifications to report the
removal of the blade and the corresponding Virtualization Host object, then inventory change notifications to report
the addition of the blade and the virtualization host. Upon addition of the blade and virtualization host, expect the
value of the name property to differ.

988 HMC Web Services API

 Level 04a

Class specific additional properties

In addition to the properties defined in included schemas, this object includes the following additional
class-specific properties:
Table 387. Virtualization Host object: class-specific additional properties
Supported
“type”
Name Qualifier Type Description values
type — String Enum Type of the virtualization host. All

Values:
v "power-vm"- a virtualization host running on a
POWER7 blade
v "x-hyp" - The canonical URI path for the System x
blade that hosts the virtualization host.
v "zvm" - a z/VM operating system instance that is
participating as an ensemble-managed
virtualization host
v "prsm" - the virtualization host representation of a
CPC or zBX node
hosting- — String/URI The hosting environment (cpc, image, blade) of the All
environment virtualization host.

Value based on type:

v "power-vm" - The canonical URI path for the
POWER7 blade that hosts the virtualization host.
v "x-hyp" - The canonical URI path for the System x
blade that hosts the virtualization host.
v "zvm" - The canonical URI path for the PR/SM
virtual server that is hosting the z/VM
virtualization host.
v "prsm" - The canonical URI path for the CPC or
zBX node that is the PR/SM virtualization host.
virtual-server- (w)(pc) Integer Amount of time, in seconds, to allow a virtual server power-vm,
shutdown-timeout to shut down. After the elapsed time has passed, the x-hyp
virtual server will be forcefully terminated.

The value may be -1 to indicate to wait "forever" or

any integer value between 0 and 86400 to specify an
exact wait time in seconds. If a value over 86400 is
specified, it will be accepted and a value of 86400
will be set for this property.

This value will be not be used if the virtual server

supports the shutdown-timeout-source property and
it is set to any value other than "virtualization-host".
auto-start-virtual- (w)(pc) Boolean Automatically start any virtual servers configured to power-vm,
servers start when the virtualization host is started. x-hyp
total-memory (pc) Integer The total amount of memory the hypervisor has (in All
MB).
memory-increment- — Integer The minimum "increment", in megabytes, that is power-vm,
in-megabytes required when setting the memory size for a virtual x-hyp, zvm
server.

Chapter 15. Virtualization management 989

 Level 04a

Table 387. Virtualization Host object: class-specific additional properties (continued)

Supported
“type”
Name Qualifier Type Description values
minimum-memory- — Integer The minimum memory size, in megabytes, that can power-vm,
size-for-virtual- be configured for a virtual server. x-hyp, zvm
server
maximum-memory- — Integer The maximum memory size, in megabytes, that can power-vm,
size-for-virtual- be configured for a virtual server. x-hyp, zvm
servers
maximum-allowed- — Integer The maximum number of dedicated processors that power-vm,
dedicated- can be configured for a virtual server. zvm
processors
maximum-allowed- — Integer The maximum number of virtual processors that can power-vm,
virtual-processors be configured for a virtual server. x-hyp, zvm
maximum-allowed- — Float The maximum number of processing units that can power-vm
processing-units be configured for a virtual server. Processing units
are a unit of measure for shared processing power
across one or more virtual processors. One shared
processing unit on one virtual processor accomplishes
approximately the same work as one dedicated
processor.
maximum-allowed- — Integer The maximum number of IDE devices that can be x-hyp
ide-devices configured for a virtual server
mixed- — Boolean Indicates if a virtual disk boot restriction exists for x-hyp
mode-boot- the virtualization host's virtual servers that would
restriction prevent booting from "virtio" virtual disks when both
"ide" and "virtio" virtual disks are defined. In such a
case, the virtual server will always boot from an
"ide" virtual disk.
gpmp-available- — String The version of the Guest Platform Management power-vm,
version Provider (GPMP) ISO that is available and can be x-hyp, zvm
mounted (using the Mount Virtual Media operation)
on virtual servers hosted on this virtualization host.
This zManager-provided ISO contains installation
images that are used to install the GPMP into a
virtual server. The value is null if the available GPMP
version information cannot be obtained.
inband-monitoring- — Boolean If true, in-band monitoring is supported for the power-vm,
supported Virtualization Host, allowing it to gather performance x-hyp
metrics on its virtual servers.
supported- — Array of List of keyboard languages supported by the x-hyp
keyboard-languages Strings hypervisor for graphical console connections.

The value is null if no key map is supported or

necessary or if graphical console is not supported.

See the Virtual Server object's keyboard-language

property for the description of an array element
value.

990 HMC Web Services API

 Level 04a

Table 387. Virtualization Host object: class-specific additional properties (continued)

Supported
“type”
Name Qualifier Type Description values
is-bridge-capable — Boolean If the virtualization host is capable of having virtual zvm
switches with bridge ports, the value is true. For true
to be returned the following requirements must be
met; otherwise, false is returned:
v The os-level property of the PR/SM virtual server
running the z/VM virtualization host is “621” or
greater
v The se-version property of the CPC or zBX node
object is 2.11.1 or later.
feature-list — Array of Optional features or behaviors supported by this All
String virtualization host. The presence of one of the Enum
Enums values described below indicates that this
virtualization host provides the described feature. If
the virtualization host has no such optional features,
an empty array is provided.

Possible feature-list values for an "x-hyp"

virtualization host:
v "boot-sequence-mixed-disk-restriction" - Indicates
that a virtual disk boot restriction exists for the
virtualization host's virtual servers that would
prevent booting from "virtio" virtual disks when
both "ide" and "virtio" virtual disks are defined. In
such a case, the virtual server will always boot
from an "ide" virtual disk.
v "boot-sequence-network-priority-restriction" -
Indicates that a virtual network adapter boot
restriction exists for the virtualization host's virtual
servers that would force "network-adapter" to be
the first entry in the boot-sequence property.
v "boot-sequence-virtual-disk-enforcement" -
Indicates that a virtualization host's virtual server's
boot-sequence property must contain an entry for
"virtual-disk" if at least one virtual disk has been
configured.
v "boot-sequence-network-adapter-enforcement" -
Indicates that a virtualization host's virtual server's
boot-sequence property must contain an entry for
"network-adapter" if at least one network adapter
has been configured.
v "boot-sequence-virtual-media-enforcement" -
Indicates that a virtualization host's virtual server's
boot-sequence property must contain an entry for
"virtual-media".

Possible feature-list values for an "x-hyp" or "power"

virtualization host:
v "virtual-server-shutdown-timeout-override-
support" - Indicates that a virtualization host's
virtual servers support their own
shutdown-timeout-source and shutdown-timeout
property.

Chapter 15. Virtualization management 991

 Level 04a

Table 387. Virtualization Host object: class-specific additional properties (continued)

Supported
“type”
Name Qualifier Type Description values
cpu-shares- — Boolean If true, CPU share management is supported for the x-hyp
supported virtualization host, allowing it to manage the
processor shares on its virtual servers.

Virtual switch objects

A virtual switch is a special type of guest LAN that provides external LAN connectivity through an
OSA-Express device without the need for a routing virtual machine.

Note: Some properties are only valid when mutable prerequisite properties have specific values. When
such properties are not valid, their value is null. For instance a iedn-virtual-switch object's router
property value is null when the layer-mode value is "eth".

iedn-virtual-switch object: The iedn-virtual-switch object is a virtual-switch object that defines the IEDN
virtual switch of a virtualization-host object of type "zvm".
Table 388. iedn-virtual-switch object properties
Name Qualifier Type Description
element-id — String Unique ID for the virtual switch within the scope of the containing
virtualization host. The element-id is actually the name of the
virtual switch. Once the virtual switch is created, the name cannot
be changed.
element-uri — String/URI The canonical URI path for the virtual switch is of the form
/api/virtualization-hosts/{virt-host-id}/virtual-switches/
{element-id}, where {virt-host-id} is the object-id of the
virtualization host.
parent — String/URI The URI path of the z/VM Virtualization Host that hosts this
virtual switch.
class — String (14) Always "virtual-switch"
type — String The virtual switch type. Always "iedn"
Enum
name — String (1-8) The unique name identifying the virtual switch.

1-8 alphanumeric uppercase characters or any of the following

characters: “@#$”
switch-status — String Virtual switch status, read-only.
layer-mode — String Indicates the transport for the virtual switch is Ethernet or IP.
Enum Values:
v "eth" : This type is Data Link (Layer 2) based, where the
Ethernet frame is used as the point of reference for source and
destination Media Access Control (MAC) addresses in
transporting Ethernet frames on the LAN.
v "ip": This type is Network (Layer 3) based, where the IP package
is used as the point of reference for source and destination IP
addresses in transporting IP packets on the LAN.

992 HMC Web Services API

 Level 04a

Table 388. iedn-virtual-switch object properties (continued)

Name Qualifier Type Description
router — String The router type.
Enum
Prerequisites: layer-mode is "ip".

Values:
v "none" - Indicates that the OSA-Express device identified will
not act as a router to the virtual switch. If a datagram is received
at this device for an unknown IP address, the datagram will be
discarded.
v "primary" - Indicates that the OSA-Express device identified will
act as a primary router to the virtual switch. If a datagram is
received at this device for an unknown IP address, the datagram
will be passed to the virtual switch. The only time to set
PRIMARY for a virtual switch is if you have a guest attached to
the virtual switch that is providing a routing function for
systems attached to another network.
queue-size — Integer Queue storage in megabytes: decimal number between 1 and 8
ip-timeout — Integer IP timeout in seconds: decimal number between 1 and 240
is-connect-uplinks — Boolean If the switch is connected to uplinks, the value is true.
real-uplinks — Array of A list of zero to three real-uplink objects.
real-uplink
objects
is-use-any- — Boolean True if the switch uses any available controller.
available-controller
controllers — Array of A list of names of switch controllers. Prerequisites:
strings is-use-any-available-controller is false.
bridge-value-type (w) String Whether the bridge port is a primary or secondary port. There can
Enum only be 1 primary and up to 4 secondary bridge ports.

Values:
v "primary" - Bridge port is the primary port
v "secondary" - Bridge port is a secondary port.

Prerequisite: This field is applied to a vSwitch that has a valid

bridge-device-number.

If not specified when the bridge port is defined, then the default is
"secondary". This field can be modified when the
bridge-connection-status is "disconnected".
bridge-device- (w) String (1-4) The bridge device number. The following values may be specified:
number v The bridge real device number, 1~4 hex digits.

Prerequisites: The is-bridge-capable property of the virtualization

host is true and the layer-mode property of the virtual switch is
"eth".

This property is required to define a device for a bridge port and

must be a nonblank, valid device number.

Chapter 15. Virtualization management 993

 Level 04a

Table 388. iedn-virtual-switch object properties (continued)

Name Qualifier Type Description
bridge-connection- (w) String Whether the bridge port is connected or in standby state.
status Enum
Prerequisites: The is-bridge-capable property of the virtualization
host is true and the virtual switch has a valid bridge-device-
number.

Values:
v "connected" - Bridge port is connected
v "disconnected" - Bridge port is disconnected.
v "standby" - Bridge port is in standby state
mtu-size- (w) String How the virtual switch MTU size is enforced.
enforcement Enum
Prerequisites: The is-bridge-capable property of the virtualization
host is true.

Values:
v "external" - The MTU size will be set to the size used by the
OSA adapter. This is the default value.
v "off" - MTU enforcement is disabled
v "user-defined" - The MTU size is specified in the mtu-size field
mtu-size (w) Integer The MTU specification represents the acceptable MTU size, in
bytes, enforced by the virtual switch. MTU size is a decimal
number between 512-65535.

Prerequisite: This field is applied to a virtual switch where the

is-bridge-capable property of the virtualization host is true and the
mtu-size-enforcement property of the virtual switch is
"user-defined".

real-uplink object: This is the embedded object definition for a virtual switch. For IEDN virtual switch,
the switch-uri property is required. For QDIO virtual switch, the switch-uri property is ignored.
Table 389. real-uplink object properties
Name Type Description
switch-uri String The element-uri of the network-adapter-prsm object in use by the z/VM
virtual switch to provide a connection between a virtual network and a
physical network.

Prerequisites: type in the parent switch is "iedn".

device-number String The uplink real device number, 1-8 hex digits. The value could be either "none"
(1-8) or a string with the regular expression pattern [0-9a-fA-F]{1,4}(.P[0-9][0-9])?. If
the optional (.P[0-9][0-9]) part is not specified, a default string ".P00" will be
used.

qdio-virtual-switch object
The qdio-virtual-switch object is a virtual-switch object that defines the QDIO virtual switch of a
virtualization-host object of type "zvm".

994 HMC Web Services API

 Level 04a

Table 390. qdio-virtual-switch object properties

Name Qualifier Type Description
element-id — String Unique ID for the virtual switch within the scope of the containing
virtualization host. The element-id is actually the name of the
virtual switch. Once the virtual switch is created, the name cannot
be changed.
element-uri — String/URI The canonical URI path for the virtual switch is of the form
/api/virtualization-hosts/{virt-host-id}/virtual-switches/
{element-id}, where {virt-host-id} is the object-id of the
virtualization host.
parent — String/URI The URI path of the z/VM Virtualization Host that hosts this
virtual switch.
class — String (14) Always "virtual-switch"
type — String Enum Virtual switch type. Always "qdio"
name — String (1-8) The unique name identifying the virtual switch.

1-8 alphanumeric uppercase characters, or any of the following

characters: “@#$”
switch-status — String Virtual switch status, read-only.
is-vlan-aware — Boolean True if not VLAN unaware. VLAN unaware is a classification for a
networking device that indicates it does not support the IEEE
802.1Q VLAN specification for VLAN membership and VLAN
frame formats. These devices ignore the additional fields within
the Ethernet frame that carry VLAN specific semantics.
vlan-id — String (1-4) Vlan ID : 1-4 decimal digits, maximum 4094. Prerequisites:
is-vlan-aware is true.
vlan-object-uri — String/URI The canonical URI path for the associated virtual network.

Prerequisites: is-vlan-aware is true.

vlan-port-type — String Enum Indicates the port type of the simulated NIC. This setting is
applied to the switch, not the single port on the switch.

Prerequisites: is-vlan-aware is true.

Values:
v "trunk": When the switch port is configured in trunk mode, it
will allow the flow of traffic from multiple virtual networks (i.e.
VLANS). The port must be configured with those virtual
networks.
v "access": When the switch port is configured in access mode, it
will support a single virtual network. Traffic from the virtual
server's network adapter will be tagged with the virtual network
configured for this port, and traffic destined to the virtual server
on this port will be verified that it is tagged with the configured
virtual network.
vlan-native-id — String Native vlan ID : 1-4 decimal digits, maximum 4094.

Prerequisites: is-vlan-aware is true.

A native VLAN ID, (usually VLAN ID 0001) is deployed internally

by the virtual switch to associate or flow untagged frames through
the switching fabric. Only those guests that are configured for the
native VLAN ID will receive or send untagged frames.

Chapter 15. Virtualization management 995

 Level 04a

Table 390. qdio-virtual-switch object properties (continued)

Name Qualifier Type Description
is-gvrp-enabled — Boolean True if GVRP is enabled.

Prerequisites: is-vlan-aware is true.

Generic Attribute Registration Protocol (GARP) VLAN Registration

Protocol (GVRP) is an application defined in the IEEE802.1Q
standard that allows for the control of VLANs. It runs only on
802.1Q trunk links. It prunes trunk links so that only active
VLANs will be sent across trunk connections.
layer-mode — String Enum Indicates the transport for the virtual switch is Ethernet or IP.
Values:
v "eth" : This type is Data Link (Layer 2) based, where the
Ethernet frame is used as the point of reference for source and
destination Media Access Control (MAC) addresses in
transporting Ethernet frames on the LAN.
v "ip": This type is Network (Layer 3) based, where the IP
package is used as the point of reference for source and
destination IP addresses in transporting IP packets on the LAN.
router — String Enum The router type.

Prerequisites: layer-mode is "ip".

Values:
v "none" - Indicates that the OSA-Express device identified will
not act as a router to the virtual switch. If a datagram is
received at this device for an unknown IP address, the datagram
will be discarded.
v "primary" - Indicates that the OSA-Express device identified will
act as a primary router to the virtual switch. If a datagram is
received at this device for an unknown IP address, the datagram
will be passed to the virtual switch. The only time to set
PRIMARY for a virtual switch is if you have a guest attached to
the virtual switch that is providing a routing function for
systems attached to another network.
queue-size — Integer Indicates the upper limit of the amount of fixed storage CP and
Queued Direct I/O Hardware Facility will use for buffers for each
OSA-Express data device.

Queue storage in megabytes: decimal number between 1 and 8.

ip-timeout — Integer IP timeout in seconds: decimal number between 1 and 240.
is-connect-uplinks Boolean True if connected to uplinks.
real-uplinks — Array of A list of zero to three real-uplink objects.
real-uplink
objects
is-use-any- — Boolean True if the switch uses any available controller.
available-controller
controllers — Array of A list of names of switch controllers.
strings
Prerequisites: is-use-any-available-controller is false.

996 HMC Web Services API

 Level 04a

Table 390. qdio-virtual-switch object properties (continued)

Name Qualifier Type Description
bridge-value-type (w) String Enum Whether the bridge port is a primary or secondary port. There can
only be 1 primary and up to 4 secondary bridge ports.

Values:
v "primary" - Bridge port is the primary port
v "secondary" - Bridge port is a secondary port.

Prerequisite: This field is applied to a vSwitch that has a valid

bridge-device-number.

If not specified when the bridge port is defined, then the default is
"secondary". This field can be modified when the
bridge-connection-status is "disconnected".
bridge-device- (w) String (1-4) The bridge device number. The following values may be specified:
number v The bridge real device number, 1~4 hex digits.

Prerequisites: The is-bridge-capable property of the virtualization

host is true and the layer-mode property of the virtual switch is
"eth".

This property is required to define a device for a bridge port and

must be a nonblank, valid device number.
bridge-connection- (w) String Enum Whether the bridge port is connected, disconnected or in standby
status state.

Prerequisites: The is-bridge-capable property of the virtualization

host is true and the virtual switch has a valid bridge-device-
number.

Values:
v "connected" - Bridge port is connected (default)
v "disconnected" - Bridge port is disconnected
v "standby" - Bridge port is in standby state.
mtu-size- (w) String Enum How the virtual switch MTU size is enforced.
enforcement
Prerequisites: The is-bridge-capable property of the virtualization
host is true.

Values:
v "external" - The MTU size will be set to the size used by the
OSA adapter. This is the default value.
v "off" - MTU enforcement is disabled
v "user-defined" - The MTU size is specified in the mtu-size field
mtu-size (w) Integer The MTU specification represents the acceptable MTU size, in
bytes, enforced by the virtual switch. MTU size is a decimal
number between 512-65535.

Prerequisite: This field is applied to a virtual switch where the

is-bridge-capable property of the virtualization host is true and
the mtu-size-enforcement of the virtual switch is "user-defined".

Chapter 15. Virtualization management 997

 Level 04a

Operations
If a virtualization host operation accesses a z/VM virtualization host and encounters an error while
communicating with the virtualization host via SMAPI, the response body is a SMAPI Error Response
Body.

List Virtualization Hosts of a zBX (Node)

The List Virtualization Hosts of a zBX (Node) operation lists the Virtualization Hosts managed by the
zBX node with the given identifier.

HTTP method and URI

GET /api/zbxs/{zbx-id}/virtualization-hosts

In this request, the URI variable {zbx-id} is the object ID of the zBX node object.

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
Enum matching type property.

Value must be a valid Virtualization Host type property value.

Response body contents

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

Field name Type Description

virtualization-hosts Array of Array of virtualization-host-info objects, described in the next table.
objects Returned array may be empty.

Each nested virtualization-host-info object contains the following fields:

Field name Type Description

object-uri String/ The canonical URI path of the Virtualization Host
URI
name String Name of the Virtualization Host object
type String Type of Virtualization Host ("power-vm" or "x-hyp")
Enum
status String Current status of the Virtualization Host
Enum

Description
This operation lists the Virtualization Hosts that are managed by the identified zBX node. The object-uri,
name, type, and status are provided for each.

If the name query parameter is specified, the returned list is limited to those Virtualization Hosts that
have a name property matching the specified filter pattern. If the name parameter is omitted, this
filtering is not done

998 HMC Web Services API

 Level 04a

If the type query parameter is specified, the parameter is validated to ensure it is a valid Virtualization
Host type property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid,
the returned list is limited to those Virtualization Hosts that have a type property matching the specified
value. If the type parameter is omitted, this filtering is not done.

If both name and type query parameters are specified, a Virtualization Host is included in the list only if
it passes both the name and type filtering criteria.

The zBX specified by {zbx-id} must be a zBX node (that is, have a type of "node"), otherwise status code
400 (Bad Request) is returned.

A Virtualization Host is included in the list only if the API user has object-access permission to its
hosting-environment. If an HMC is a manager of a Virtualization Host but the API user does not have
permission to it, that object is simply omitted from the list but no error status code results.

If the zBX node does not manage any Virtualization Hosts or if no Virtualization Hosts are to be included
in the results due to filtering, 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 specified zBX node
v Object-access permission to hosting-environment of the Virtualization Hosts managed by the specified
zBX node.

HTTP status and reason codes

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

If errors occur, the following HTTP status codes are provided, 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.
80 A type query parameter defines an invalid value.
89 The request URI designates a zBX object that is not a zBX node (that is, does
not have a type of "node").
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) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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.

Chapter 15. Virtualization management 999

 Level 04a

Example HTTP interaction

GET /api/zbxs/8dac6a58-935e-352c-996e-ded17dbf92c0/virtualization-hosts HTTP/1.1

x-api-session: 579shzuc4ca3lwnly7xk2s64w6qmwy2v2zsikdrn4ky9sn9vv1

Figure 536. List Virtualization Hosts of a zBX (Node): Request

200 OK
server: zSeries management console API web server / 2.0
date: Mon, 09 Feb 2015 19:24:33 GMT
content-type: application/json;charset=UTF-8
content-length: 444
{
"virtualization-hosts": [
{
"name": "B.1.01",
"object-uri": "/api/virtualization-hosts/40a480b6-a7f1-11e4-ad46-
42f2e9106e93",
"status": "operating",
"type": "power-vm"
},
{
"name": "B.2.03",
"object-uri": "/api/virtualization-hosts/88f0a20a-a7f1-11e4-ad46-
42f2e9106e93",
"status": "operating",
"type": "x-hyp"
}
]
}

Figure 537. List Virtualization Hosts of a zBX (Node): Response

List Virtualization Hosts of a Node

The List Virtualization Hosts of a Node operation lists the Virtualization Hosts managed by the node
with the given identifier.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/nodes/{node-id}/virtualization-hosts

URI variables:

Name Description
{ensemble-id} The object ID of the Ensemble object
{node-id} The object ID of the Node object

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
Enum matching type property.

Value must be a valid Virtualization Host type property value.

1000 HMC Web Services API

 Level 04a

Response body contents

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

Field name Type Description

virtualization-hosts Array of Array of virtualization-host-info objects, described in the next table.
objects Returned array may be empty.

Each nested virtualization-host-info object contains the following fields:

Field name Type Description

object-uri String/ The canonical URI path of the Virtualization Host
URI
name String Name of the Virtualization Host object
type String Type of Virtualization Host. ("power-vm", "x-hyp", "zvm", or "prsm")
Enum
status String Current status of the Virtualization Host
Enum

Description
This operation lists the Virtualization Hosts that are managed by the specified node. The object-uri,
name, type, and status are provided for each.

If the name query parameter is specified, the returned list is limited to those Virtualization Hosts that
have a name property matching the specified filter pattern. If the name parameter is omitted, this
filtering is not done

If the type query parameter is specified, the parameter is validated to ensure it is a valid Virtualization
Host type property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid,
the returned list is limited to those Virtualization Hosts that have a type property matching the specified
value. If the type parameter is omitted, this filtering is not done.

If both name and type query parameters are specified, a Virtualization Host is included in the list only if
it passes both the name and type filtering criteria.

A Virtualization Host is included in the list only if the API user has object-access permission to its
hosting-environment. If an HMC is a manager of a Virtualization Host but the API user does not have
permission to it, that object is simply omitted from the list but no error status code results.

If the Node does not manage any Virtualization Hosts or if no Virtualization Hosts are to be included in
the results due to filtering, 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 specified node
v Object-access permission to hosting-environment of the Virtualization Hosts managed by the specified
node.

Chapter 15. Virtualization management 1001

 Level 04a

HTTP status and reason codes

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

If errors occur, the following HTTP status codes are provided, 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.
80 A type query parameter defines an invalid value.
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.

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/ensembles/de7915f4-a127-11e2-8273-5cf3fcae8019/nodes/8dac6a58-
935e-352c-996e-ded17dbf92c0/virtualization-hosts HTTP/1.1
x-api-session: 579shzuc4ca3lwnly7xk2s64w6qmwy2v2zsikdrn4ky9sn9vv1

Figure 538. List Virtualization Hosts of a Node: Request

200 OK
server: zSeries management console API web server / 2.0
date: Mon, 09 Feb 2015 19:24:27 GMT
content-type: application/json;charset=UTF-8
content-length: 444
{
"virtualization-hosts": [
{
"name": "B.1.01",
"object-uri": "/api/virtualization-hosts/40a480b6-a7f1-11e4-ad46-42f2e9106e93",
"status": "operating",
"type": "power-vm"
},
{
"name": "B.2.03",
"object-uri": "/api/virtualization-hosts/88f0a20a-a7f1-11e4-ad46-42f2e9106e93",
"status": "operating",
"type": "x-hyp"
}
]
}

Figure 539. List Virtualization Hosts of a Node: Response

1002 HMC Web Services API

 Level 04a

List Virtualization Hosts of an Ensemble

The List Virtualization Hosts of an Ensemble operation lists the Virtualization Hosts managed by the
ensemble with the given identifier.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/virtualization-hosts

In this request, the URI variable {ensemble-id} is the object ID of the Ensemble object.

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
Enum matching type property.

Value must be a valid Virtualization Host type property value.

Response body contents

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

Field name Type Description

virtualization-hosts Array of Array of virtualization-host-info objects, described in the next table.
objects Returned array may be empty.

Each nested virtualization-host-info object contains the following fields:

Field name Type Description

object-uri String/ The canonical URI path of the Virtualization Host
URI
name String Name of the Virtualization Host
type String Type of Virtualization Host
Enum
status String Current status of the Virtualization Host
Enum

Description
This operation lists the Virtualization Hosts that are managed by the identified ensemble.

If the name query parameter is specified, the returned list is limited to those Virtualization Hosts that
have a name property matching the specified filter pattern. If the name parameter is omitted, this
filtering is not done

If the type query parameter is specified, the parameter is validated to ensure it is a valid Virtualization
Host type property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid,
the returned list is limited to those Virtualization Hosts that have a type property matching the specified
value. If the type parameter is omitted, this filtering is not done.

Chapter 15. Virtualization management 1003

 Level 04a

A Virtualization Host is included in the list only if the API user has object-access permission to its
hosting-environment. If an HMC is a manager of a Virtualization Host but the API user does not have
permission to it, that object is simply omitted from the list but no error status code results.

If the ensemble does not manage any Virtualization Hosts or if no Virtualization Hosts are to be included
in the results due to filtering, 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 specified ensemble
v Object-access permission to hosting-environment of the Virtualization Hosts managed by the specified
ensemble.

HTTP status and reason codes

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

If errors occur, the following HTTP status codes are provided, 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.
80 A type query parameter defines an invalid value.
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.

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/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/virtualization-hosts HTTP/1.1

x-api-session: 4oup923zgs27vmd1wpzvu47ikgzhxa8bwimjofpq6d3eq3j13q

Figure 540. List Virtualization Hosts of an Ensemble: Request

1004 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 22 Jul 2011 15:02:37 GMT
content-type: application/json;charset=UTF-8
content-length: 824
{
"virtualization-hosts": [
{
"name": "APIVM1",
"object-uri": "/api/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4",
"status": "operating",
"type": "zvm"
},
{
"name": "B.2.02",
"object-uri": "/api/virtualization-hosts/ba97ff30-2990-11e0-8d5b-001f163803de",
"status": "operating",
"type": "power-vm"
},
{
"name": "B.2.03",
"object-uri": "/api/virtualization-hosts/931b25d6-82e1-11e0-b9e4-f0def10bff8d",
"status": "operating",
"type": "x-hyp"
},
{
"name": "R32",
"object-uri": "/api/virtualization-hosts/bab76208-2990-11e0-8d5b-001f163803de",
"status": "operating",
"type": "prsm"
}
]
}

Figure 541. List Virtualization Hosts of an Ensemble: Response

List Virtualization Hosts of a CPC

The List Virtualization Hosts of a CPC operation lists the Virtualization Hosts managed by the CPC with
the given identifier.

HTTP method and URI

GET /api/cpcs/{cpc-id}/virtualization-hosts

In this request, the URI variable {cpc-id} is Object ID of the CPC object.

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
Enum matching type property.

Value must be a valid Virtualization Host type property value.

Chapter 15. Virtualization management 1005

 Level 04a

Response body contents

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

Field name Type Description

virtualization-hosts Array of Array of virtualization-host-info objects, described in the next table.
objects Returned array may be empty.

Each nested virtualization-host-info object contains the following fields:

Field name Type Description

object-uri String/ The canonical URI path of the Virtualization Host
URI
name String Name of the Virtualization Host object
type String Type of Virtualization Host. ("power-vm", "x-hyp", "zvm", or "prsm")
Enum
status String Current status of the Virtualization Host
Enum

Description
This operation lists the Virtualization Hosts that are managed by the specified CPC. The object URI,
object ID, display name, and display description are provided for each.

If the object-id {cpc-id} does not identify a CPC object to which the API user has object-access permission
or if the CPC is not a member of an ensemble, a 404 status code is returned.

If the name query parameter is specified, the returned list is limited to those Virtualization Hosts that
have a name property matching the specified filter pattern. If the name parameter is omitted, this
filtering is not done.

If the type query parameter is specified, the parameter is validated to ensure it is a valid Virtualization
Host type property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid,
the returned list is limited to those Virtualization Hosts that have a type property matching the specified
value. If the type parameter is omitted, this filtering is not done.

If both name and type query parameters are specified, a Virtualization Host is included in the list only if
it passes both the name and type filtering criteria.

A Virtualization Host is included in the list only if the API user has object-access permission to its
hosting-environment. If an HMC is a manager of a Virtualization Host but the API user does not have
permission to it, that object is simply omitted from the list but no error status code results.

The list that is returned is never empty because a CPC always has a PR/SM Virtualization Host, and may
have additional ones as well. If no Virtualization Hosts are to be included in the results due to filtering,
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 specified CPC
v Object-access permission to hosting-environment of the Virtualization Hosts managed by the specified
CPC.

1006 HMC Web Services API

 Level 04a

HTTP status and reason codes

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

If errors occur, the following HTTP status codes are provided, and the response body is a standard error
response body providing the reason code indicated and associated error message.

HTTP error status

code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
80 A type query parameter defines an invalid value.
404 (Not Found) 1 A CPC with object-id {cpc-id} does not exist on the HMC or API user does
not have object-access permission for it.
100 The CPC with object-id {cpc-id} is not a member of an ensemble.
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/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/virtualization-hosts HTTP/1.1

x-api-session: 4oup923zgs27vmd1wpzvu47ikgzhxa8bwimjofpq6d3eq3j13q

Figure 542. List Virtualization Hosts of a CPC: Request

Chapter 15. Virtualization management 1007

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 22 Jul 2011 15:02:37 GMT
content-type: application/json;charset=UTF-8
content-length: 824
{
"virtualization-hosts": [
{
"name": "APIVM1",
"object-uri": "/api/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4",
"status": "operating",
"type": "zvm"
},
{
"name": "B.2.02",
"object-uri": "/api/virtualization-hosts/ba97ff30-2990-11e0-8d5b-001f163803de",
"status": "operating",
"type": "power-vm"
},
{
"name": "B.2.03",
"object-uri": "/api/virtualization-hosts/931b25d6-82e1-11e0-b9e4-f0def10bff8d",
"status": "operating",
"type": "x-hyp"
},
{
"name": "R32",
"object-uri": "/api/virtualization-hosts/bab76208-2990-11e0-8d5b-001f163803de",
"status": "operating",
"type": "prsm"
}
]
}

Figure 543. List Virtualization Hosts of a CPC: Response

Get Virtualization Host Properties

The Get Virtualization Host Properties operation retrieves the properties of a single Virtualization Host
object that is designated by its object-id.

HTTP method and URI

GET /api/virtualization-hosts/{virt-host-id}

In this request, the URI variable {virt-host-id} is Object ID of the Virtualization Host object for which
properties are to be obtained.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the Virtualization Host object as defined in the “Data model” on page 987. Field names
and data types in the JSON object are the same as the property and data types defined in the data model.

Description
Retrieve the current values for properties supported by the specified Virtualization Host.

1008 HMC Web Services API

 Level 04a

If the object-id {virt-host-id} does not identify a Virtualization Host object for which the API user has
object-access permission to its hosting-environment, a 404 status code is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to hosting-environment of the Virtualization Host with object-id {virt-host-id}.

HTTP status and reason codes

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

If errors occur, the following HTTP status codes are provided, 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 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.
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

GET /api/virtualization-hosts/bab76208-2990-11e0-8d5b-001f163803de HTTP/1.1

x-api-session: 4oup923zgs27vmd1wpzvu47ikgzhxa8bwimjofpq6d3eq3j13q

Figure 544. Get Virtualization Host Properties: Request

Chapter 15. Virtualization management 1009

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 22 Jul 2011 15:02:37 GMT
content-type: application/json;charset=UTF-8
content-length: 640
{
"acceptable-status": [
"operating"
],
"class": "virtualization-host",
"description": "Initial description",
"feature-list: [],
"has-unacceptable-status": false,
"hosting-environment": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"is-locked": false,
"name": "R32",
"object-id": "bab76208-2990-11e0-8d5b-001f163803de",
"object-uri": "/api/virtualization-hosts/bab76208-2990-11e0-8d5b-001f163803de",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-
be79e49dd340",
"status": "operating",
"type": "prsm",
"virtual-server-shutdown-timeout": 200
}

Figure 545. Get Virtualization Host Properties: Response for virtualization host of type "prsm"

1010 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 22 Jul 2011 15:02:37 GMT
content-type: application/json;charset=UTF-8
content-length: 988
{
"acceptable-status": [
"operating"
],
"auto-start-virtual-servers": true,
"class": "virtualization-host",
"description": "single update ABC ",
"feature-list: [],
"has-unacceptable-status": true,
"hosting-environment": "/api/blades/938706AC3FF111D78B5600215EC0330E",
"is-locked": false,
"maximum-allowed-dedicated-processors": 57,
"maximum-allowed-processing-units": 57.600000000000001,
"maximum-allowed-virtual-processors": 64,
"maximum-memory-size-for-virtual-server": 27648,
"memory-increment-in-megabytes": 256,
"minimum-memory-size-for-virtual-server": 256,
"name": "B.2.02",
"object-id": "ba97ff30-2990-11e0-8d5b-001f163803de",
"object-uri": "/api/virtualization-hosts/ba97ff30-2990-11e0-8d5b-001f163803de",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-
be79e49dd340",
"status": "operating",
"type": "power-vm",
"virtual-server-shutdown-timeout": 2147483647
}

Figure 546. Get Virtualization Host Properties: Response for virtualization host of type "power-vm"

Chapter 15. Virtualization management 1011

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 22 Jul 2011 15:02:37 GMT
content-type: application/json;charset=UTF-8
content-length: 930
{
"acceptable-status": [
"operating"
],
"auto-start-virtual-servers": true,
"class": "virtualization-host",
"description": "",
"feature-list: [],
"has-unacceptable-status": true,
"hosting-environment": "/api/blades/B8210BC02D1E11E0AE81E41F13FE1430",
"is-locked": false,
"maximum-allowed-ide-devices": 3,
"maximum-allowed-virtual-processors": 16.0,
"maximum-memory-size-for-virtual-server": 125829,
"memory-increment-in-megabytes": 1,
"minimum-memory-size-for-virtual-server": 1,
"mixed-mode-boot-restriction": true,
"name": "B.2.03",
"object-id": "931b25d6-82e1-11e0-b9e4-f0def10bff8d",
"object-uri": "/api/virtualization-hosts/931b25d6-82e1-11e0-b9e4-f0def10bff8d",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-
be79e49dd340",
"status": "operating",
"type": "x-hyp",
"virtual-server-shutdown-timeout": 302
}

Figure 547. Get Virtualization Host Properties: Response for virtualization host of type "x-hyp"

1012 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 22 Jul 2011 15:02:37 GMT
content-type: application/json;charset=UTF-8
content-length: 893
{
"acceptable-status": [
"operating"
],
"class": "virtualization-host",
"cpu-shares-supported": true,
"description": "An initial description",
"feature-list: ["boot-sequence-network-priority-restriction"],
"has-unacceptable-status": false,
"hosting-environment": "/api/virtual-servers/4401b16c-ac9a-11e0-ade4-001f163805d8",
"is-locked": false,
"maximum-allowed-dedicated-processors": 64,
"maximum-allowed-virtual-processors": 64,
"maximum-memory-size-for-virtual-server": 1048576,
"memory-increment-in-megabytes": 1,
"minimum-memory-size-for-virtual-server": 64,
"name": "APIVM1",
"object-id": "342d80e0-65ff-11e0-acfd-f0def10c03f4",
"object-uri": "/api/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-
be79e49dd340",
"status": "operating",
"type": "zvm",
"virtual-server-shutdown-timeout": 212
}

Figure 548. Get Virtualization Host Properties: Response for virtualization host of type "zvm"

Update Virtualization Host Properties

The Update Virtualization Host Properties operation updates one or more of the writable properties of a
Virtualization Host.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host object for which
properties are to be updated.

Request body contents

The request body contains a JSON object that provides the new values of the writable properties of the
Virtualization Host object as defined in the data model section above. Field names and data types in the
JSON object are the same as the property or relationship names and data types defined in the data
model.

writable properties are only valid if they are supported for a Virtualization Host whose type property
matches the given type property value. For example, auto-start-virtual-servers is only a writable property
for type "power-vm" and "x-hyp" Virtualization Hosts.

Chapter 15. Virtualization management 1013

 Level 04a

Description
This operation updates writable properties of the Virtualization Host object specified by the request URI.

The request body contains an object with one or more fields with field names that correspond to the
names of properties for this object. 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 without supplying any response body. The request body does not need to specify a value for all
writable properties, but rather can and should contain fields for the properties to be updated. Object
properties for which no input value is provided remain unchanged by this operation.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

The URI path must designate an existing Virtualization Host object and the API user must have
object-access permission to its hosting-environment. If either of these conditions is not met, status code
404 (Not Found) is returned. In addition, the API user must also have task permission to the System
Details task as well, otherwise status code 403 (Forbidden) is returned.

The request body is validated against the data model for this object type to ensure that it 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.

Authorization requirements
This operation has the following authorization requirements:
v Action/task permission to the System Details task
v Object-access permission to hosting-environment of the Virtualization Host with object-id {virt-host-id}.

HTTP status and reason codes

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

If errors occur, the following HTTP status codes are provided, 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 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) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other 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.

1014 HMC Web Services API

 Level 04a

List Virtual Switches

The List Virtual Switches operation lists the virtual switches managed by the z/VM Virtualization Host
with the given identifier.

HTTP method and URI

GET /api/virtualization-host/{virt-host-id}/virtual-switches

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host.

Response body contents

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

Field name Type Description

virtual-switches Array of Array of virtual-switch-info objects, described in the next table. Returned
objects array may be empty.

Each nested virtual-switch-info object contains the following fields:

Field name Type Description

element-uri String/URI The element-uri property of virtual-switch element.
type String The type property of virtual-switch element.
Enum
name String The name property of virtual-switch element.

Description
This operation lists the virtual switches that are managed by the identified Virtualization Host.

If the Virtualization Host does not have any virtual network switches, an empty list is provided and the
operation completes successfully.

Authorization requirements
This operation has the following authorization requirements:
v Action/task role permission to the Manage Virtual Switches task
v Object-access permission to hosting-environment of the Virtualization Host with object-id {virt-host-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.”

If errors occur, the following HTTP status codes are provided, 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.

Chapter 15. Virtualization management 1015

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 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 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with an SE needed to perform the requested operation.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4/virtual-switches HTTP/1.1

x-api-session: 4oup923zgs27vmd1wpzvu47ikgzhxa8bwimjofpq6d3eq3j13q

Figure 549. List Virtual Switches: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 22 Jul 2011 15:02:46 GMT
content-type: application/json;charset=UTF-8
content-length: 411
{
"virtual-switches": [
{
"element-uri": "/api/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4/virtual-switches/
S2777",
"name": "S2777",
"type": "iedn"
},
{
"element-uri": "/api/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4/virtual-switches/
4179SW3",
"name": "4179SW3",
"type": "qdio"
}
]
}

Figure 550. List Virtual Switches: Response

Get Virtual Switch Properties

The Get Virtual Switch Properties operation retrieves the properties of a single virtual switch that is
designated by the request URI.

1016 HMC Web Services API

 Level 04a

HTTP method and URI

GET /api/virtualization-host/{virt-host-id}/virtual-switches/{virtual-switch-id}

URI variables

Variable Type Description

virt-host-id String Object ID of the Virtualization Host
virtual-switch-id String Element ID of the Virtual Switch

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the virtual switch object as defined in the “Data model” on page 987. Field names and
data types in the JSON object are the same as the property or relationship names and data types defined
in the data model.

Description
This operation returns a JSON object that provides the current values of the properties for the virtual
switch element object as defined in the“Data model” on page 987.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to hosting-environment of the Virtualization Host with object-id {virt-host-id}
v Task role permission to the Manage Virtual Switches task.

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.”

If errors occur, the following HTTP status codes are provided, 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) 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 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 15. Virtualization management 1017

 Level 04a

Example HTTP interaction

GET /api/virtualization-hosts/57ab94c8-03e6-11e1-baf3-001f163805d8/virtual-switches/SSSS HTTP/1.1

x-api-session: 3ch9r8g2lavxw9st52brubgk4bpsqik3jcqbg8hdwpkg5flwpx

Figure 551. Get Virtual Switch Properties: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 07 Dec 2011 06:01:18 GMT
content-type: application/json;charset=UTF-8
content-length: 575
{
"bridge-connection-status": null,
"bridge-device-number": null,
"bridge-value-type": null,
"class": "virtual-switch",
"controllers": null,
"element-id": "SSSS",
"element-uri": "/api/virtualization-hosts/57ab94c8-03e6-11e1-baf3-001f163805d8/
virtual-switches/SSSS",
"ip-timeout": 5,
"is-connect-uplinks": true,
"is-use-any-available-controller": true,
"layer-mode": "eth",
"mtu-size": null,
"mtu-size-enforcement": "external",
"name": "SSSS",
"parent": "/api/virtualization-hosts/57ab94c8-03e6-11e1-baf3-001f163805d8",
"queue-size": 8,
"real-uplinks": [],
"router": null,
"switch-status": "Defined",
"type": "iedn"
}

Figure 552. Get Virtual Switch Properties: Response for virtual switch of type "iedn"

1018 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 07 Dec 2011 06:01:38 GMT
content-type: application/json;charset=UTF-8
content-length: 718
{
"bridge-connection-status": null,
"bridge-device-number": null,
"bridge-value-type": null,
"class": "virtual-switch",
"controllers": null,
"element-id": "TESTQPOP",
"element-uri": "/api/virtualization-hosts/57ab94c8-03e6-11e1-baf3-001f163805d8/
virtual-switches/TESTQPOP",
"ip-timeout": 5,
"is-connect-uplinks": true,
"is-gvrp-enabled": false,
"is-use-any-available-controller": true,
"is-vlan-aware": true,
"layer-mode": "eth",
"mtu-size": null,
"mtu-size-enforcement": "external",
"name": "TESTQPOP",
"parent": "/api/virtualization-hosts/57ab94c8-03e6-11e1-baf3-001f163805d8",
"queue-size": 8,
"real-uplinks": [],
"router": null,
"switch-status": "Defined",
"type": "qdio",
"vlan-id": "AWARE",
"vlan-native-id": "1",
"vlan-object-uri": "",
"vlan-port-type": "ACCESS"
}

Figure 553. Get Virtual Switch Properties: Response for virtual switch of type "qdio"

Create IEDN Virtual Switch

The Create IEDN Virtual Switch operation creates an IEDN virtual network switch for the z/VM
Virtualization Host.

HTTP method and URI

POST /api/virtualization-host/{virt-host-id}/virtual-switches/operations/create-iedn

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host.

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The name property of iedn-virtual-switch object
layer-mode String Optional The layer-mode property of iedn-virtual-switch object.
Enum Default value is "eth".
router String Optional The router property of iedn-virtual-switch object.
Enum Default value is "none".

Chapter 15. Virtualization management 1019

 Level 04a

Field name Type Rqd/Opt Description

queue-size Integer Optional The queue-size property of iedn-virtual-switch object.
Default value is 8.
ip-timeout Integer Optional The ip-timeout property of iedn-virtual-switch object.
Default value is 5.
is-connect-uplinks Boolean Optional The is-connect-uplinks property of iedn-virtual-switch
object. Default value is false.
real-uplinks Array of Required if The real-uplinks property of iedn-virtual-switch
real- is-connect-uplinks is object. Default value is an empty list. If
uplink true is-connect-uplinks is true, the list is required and
objects contains 1-3 real-uplink objects.
is-use-any- Boolean Optional The is-use-any-available-controller property of
available- iedn-virtual-switch object. Default value is true. If the
controller value is true and virtual switch is successfully created
and there is a controller available in the z/VM, this
property will be set to false, and the available
controller will be used and shown in the controllers
property.
controllers Array of Required if The controllers property of iedn-virtual-switch object
Strings is-use-any-available-
controller is false
bridge-value-type String Optional; The bridge-value-type property of the
iedn-virtual-switch object. Default value is
Allowed only if "secondary".
bridge-device-number
has been specified
bridge-device- String Optional; The bridge-device-number property of the
number iedn-virtual-switch object. Default value is null.
Allowed only if the
is-bridge-capable
property of the
virtualization host is true
and thelayer-mode
property of the virtual
switch is "eth"
bridge-connection- String Optional; Values:
status v "connect" - Connect the bridge port
Allowed only if
bridge-device-number v "disconnect" - Disconnect the bridge port
has been specified
Default value is "connect".
mtu-size- String Optional; The mtu-size-enforcement property of the
enforcement iedn-virtual-switch object.Default value is "external".
Allowed only if the
is-bridge-capable
property of the
virtualization host is true
mtu-size Integer Optional; The mtu-size property of the iedn-virtual-switch
object. Required if mtu-size-enforcement is
Allowed only if the "user-defined".
is-bridge-capable
property of the
virtualization host is true
and
themtu-size-enforcement
property of the virtual
switch is "user-defined"

1020 HMC Web Services API

 Level 04a

Response body contents

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

Field name Type Description

element-uri String/URI The element-uri property of the created virtual-switch element.

Description
This operation creates the IEDN virtual switch for the identified Virtualization Host and then returns its
URI. The response also includes a Location header that provides this URI.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to hosting-environment of the Virtualization Host with object-id {virt-host-id}
v Action/task permission to the Manage Virtual Switches 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.”

If errors occur, the following HTTP status codes are provided, 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.
81 A virtual switch with the name specified in the request body already exists
on the Virtualization Host with object-id {virt-host-id}.
87 The iedn-virtual-switch object bridge-device-number property specified is
already in use.
88 The iedn-virtual-switch object bridge-device-number property specified is
not defined available to the z/VM Virtualization Host.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 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.
409 (Conflict) 80 The Virtualization Host already has a vSwitch with a bridge where the
iedn-virtual-switch object bridge-value-type property is "primary".
81 The Virtualization Host already has four vSwitches with a bridge where the
iedn-virtual-switch object bridge-value-type property is "secondary". Four is
the maximum.

Chapter 15. Virtualization management 1021

 Level 04a

HTTP error status Reason

code code Description
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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

Create QDIO Virtual Switch

The Create QDIO Virtual Switch operation creates a QDIO virtual network switch for the z/VM
Virtualization Host.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/virtual-switches/operations/create-qdio

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host.

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The name property of qdio-virtual-switch object
is-vlan-aware Boolean Optional The is-vlan-aware property of qdio-virtual-switch
object. Default value is false.
vlan-id String Optional; The vlan-id property of qdio-virtual-switch object.
Default value is "".
Allowed only if
is-vlan-aware is true
vlan-port-type String Optional; The vlan-port-type property of qdio-virtual-switch
Enum object. Default value is "access".
Allowed only if
is-vlan-aware is true
vlan-native-id String Optional; The vlan-native-id property of qdio-virtual-switch
object. Default value is "1".
Allowed only if
is-vlan-aware is true
is-gvrp-enabled Boolean Optional; The is-gvrp-enabled property of qdio-virtual-switch
object. Default value is false.
Allowed only if
is-vlan-aware is true
layer-mode String Optional The layer-mode property of qdio-virtual-switch object.
Enum Default value is "eth".
router String Optional The router property of qdio-virtual-switch object.
Enum Default value is "none".
queue-size Integer Optional The queue-size property of qdio-virtual-switch object.
Default value is 8.

1022 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

ip-timeout Integer Optional The ip-timeout property of qdio-virtual-switch object.
Default value is 5.
is-connect-uplinks Boolean Optional The is-connect-uplinks property of qdio-virtual-switch
object. Default value is false.
real-uplinks Array of Required if The real-uplinks property of qdio-virtual-switch
real- is-connect-uplinks is true object. Default value is an empty list. If
uplink is-connect-uplinks is true, the list is required and
objects contains 1-3 real-uplink objects.
is-use-any- Boolean Optional The is-use-any-available-controller property of
available- qdio-virtual-switch object. Default value is true. If the
controller value is true and virtual switch is successfully created
and there is a controller available in the z/VM, this
property will be set to false, and the available
controller will be used and shown in the controllers
property
controllers Array of Required if The controllers property of qdio-virtual-switch object
Strings is-use-any-available-
controller is false
bridge-value-type String Optional; The bridge-value-type property of the
qdio-virtual-switch object. Default value is
Allowed only if "secondary".
bridge-device-number
has been specified
bridge-device- String Optional; The bridge-device-number property of the
number qdio-virtual-switch object. Default value is null.
Allowed only if
theis-bridge-capable
property of the
virtualization host is true
and thelayer-mode
property of the virtual
switch is "eth"
bridge-connection- String Optional; Values:
status v "connect" - Connect the bridge port. (Default value)
Allowed only if
bridge-device-number v "disconnect" - Disconnect the bridge port
has been specified
Default value is "connect".
mtu-size- String Optional; The mtu-size-enforcement property the
enforcement qdio-virtual-switch object.
Allowed only if the
is-bridge-capable Default value is "external".
property of the
virtualization host is true
mtu-size Integer Optional; The mtu-size property the qdio-virtual-switch object.

Allowed only if the Required if mtu-size-enforcement is "user-defined".

is-bridge-capable
property of the
virtualization host is true
and themtu-size-
enforcement property of
the virtual switch is
"user-defined"

Chapter 15. Virtualization management 1023

 Level 04a

Response body contents

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

Field name Type Description

element-uri String/URI The element-uri property of the created virtual-switch element.

Description
This operation creates the QDIO virtual switch for the identified Virtualization Host and then returns its
element URI. The response also includes a Location header that provides this URI.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to hosting-environment of the Virtualization Host with object-id {virt-host-id}
v Action/task permission to the Manage Virtual Switches 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.”

If errors occur, the following HTTP status codes are provided, 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.
81 A virtual switch with the name specified in the request body already exists
on the Virtualization Host with object-id {virt-host-id}.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 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.
409 (Conflict) 80 The Virtualization Host already has a vSwitch with a bridge where the
qdio-virtual-switch object bridge-value-type property is "primary".
81 The Virtualization Host already has four vSwitches with a bridge where the
qdio-virtual-switch object bridge-value-type property is "secondary". Four is
the maximum.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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

1024 HMC Web Services API

 Level 04a

Get Switch Controllers

The Get Switch Controllers operation gets a list of controllers for the z/VM Virtualization Host.
Controllers are z/VM TCP/IP virtual machines used to manage OSA-Express devices associated with
virtual switches. For details, see the z/VM CP Commands and Utility Reference, SC24-6175.

HTTP method and URI

GET /api/virtualization-hosts/{virt-host-id}/operations/get-switch-controllers

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host.

Response body contents

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

Field name Type Description

controllers Array of An array of controller objects as defined in the next table.
controller
objects

Each nested controller object provides the properties for a single switch controller, and has the following
format:

Field name Type Description

name String (0-8) Name for the controller
is-available Boolean True if the controller is available to control an additional set of OSA-Express
devices associated with the virtual switch.
vdev-range String (1-9) Identifies the device range where the OSA-Express devices associated with a
virtual switch can be attached. The value is two virtual device address
values separated by a hyphen (e.g. “8800-88FF”) or “*”, which indicates that
the virtual device address used to attach the OSA-Express devices is the
same as the real device address identified by the virtual switch's
real-uplinks.
is-ip Boolean True if the virtual switch controller can initialize an OSA-Express device in
IP mode. See Virtual Switch layer mode.
is-eth Boolean True if the virtual switch controller can initialize an OSA-Express device in
ETH mode. See Virtual Switch layer mode.
is-vlan-arp Boolean True if the virtual switch controller can register IP addresses on the
OSA-Express with the proper VLAN groups (VLAN_ARP).
is-gvrp Boolean True if the virtual switch controller can register VLAN IDs in use on a
virtual switch with GVRP-aware switches (GVRP).
is-linkagg Boolean True if the controller can control virtual switches that are using link
aggregation. A Link Aggregation port group is two or more links that are
grouped together to appear as a single logical link.
is-isolation Boolean True if the controller can control virtual switches that are using the isolation
setting.

Description
This operation lists the controllers for the identified Virtualization Host.

Chapter 15. Virtualization management 1025

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to hosting-environment of the Virtualization Host with object-id {virt-host-id}.
v Action/task permission to the Manage Virtual Switches task

HTTP status and reason codes

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

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) 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 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

GET /api/virtualization-hosts/0e4a5d94-a8c1-11e0-9492-00262df332b3/operations/
get-switch-controllers HTTP/1.1
x-api-session: lkcjo7eteu67cygzoknowww8caid5jiyck6yfupyqz3619t3r

Figure 554. Get Switch Controllers: Request

1026 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 07 Dec 2011 05:49:49 GMT
content-type: application/json;charset=UTF-8
content-length: 653
{
"controllers": [
{
"is-available": true,
"is-eth": true,
"is-gvrp": true,
"is-ip": true,
"is-isolation": true,
"is-linkagg": true,
"is-vlan-arp": true,
"name": "DTCVSW1",
"vdev-range": "0600-F000"
},
{
"is-available": true,
"is-eth": true,
"is-gvrp": true,
"is-ip": true,
"is-isolation": true,
"is-linkagg": true,
"is-vlan-arp": true,
"name": "DTCENS1",
"vdev-range": "*"
}
]
}

Figure 555. Get Switch Controllers: Response

Update Virtual Switch

The Update Virtual Switch operation modifies an existing virtual network switch for the z/VM
Virtualization Host.

HTTP method and URI

POST /api/virtualization-host/{virt-host-id}/virtual-switches/{virtual-switch-id}

URI variables

Variable Description
{virt-host-id} Object ID of the Virtualization Host
{virtual-switch-id} Element ID of the virtual switch

Chapter 15. Virtualization management 1027

 Level 04a

Request body contents

For IEDN virtual switch:

Field name Type Rqd/Opt Description

router String Optional; The router property of iedn-virtual-switch object
Enum
Allowed only if layer-mode
is "ip"
queue-size Integer Optional The queue-size property of iedn-virtual-switch
object.
ip-timeout Integer Optional The ip-timeout property of iedn-virtual-switch
object.
is-connect-uplinks Boolean Optional The is-connect-uplinks property of
iedn-virtual-switch object
is-use-any- Boolean Optional The is-use-any-available-controller property of
available- iedn-virtual-switch object. If the value is true and
controller virtual switch is successfully updated and there is
a controller available in the z/VM, this property
will be set to false, and the available controller will
be used and shown in the controllers property.
controllers Array of Optional; The controllers property of iedn-virtual-switch
Strings object.
Allowed only if
is-use-any-available-
controller is false
real-uplinks Array of Required if The real-uplinks property of iedn-virtual-switch
real- is-connect-uplinks is true object. If is-connect-uplinks is true, the list is
uplink required and contains 1-3 real-uplink objects.
objects
bridge-value-type String Optional; The bridge-value-type property of the
iedn-virtual-switch object
Allowed only if
bridge-device-number has
been specified
bridge-device- String Optional; The bridge-device-number property of the
number iedn-virtual-switch object
Allowed only if the
is-bridge-capable property
of the virtualization host is
true and the layer-mode
property of the virtual
switch is "eth"
bridge-connection- String Optional; Values:
status v "connect" - Connect the bridge port. (Default
Allowed only if
value)
bridge-device-number has
been specified v "disconnect" - Disconnect the bridge port

mtu-size- String Optional; The mtu-size-enforcement property of the

enforcement iedn-virtual-switch object
Allowed only if
theis-bridge-capable
property of the
virtualization host is true

1028 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

mtu-size Integer Optional; The mtu-size property of the iedn-virtual-switch
object. Required if mtu-size-enforcement is
Allowed only if the "user-defined".
is-bridge-capable property
of the virtualization host is
true and the
mtu-size-enforcement
property of the virtual
switch is "user-defined"

For QDIO virtual switch:

Field name Type Rqd/Opt Description

router String Optional; The router property of the qdio-virtual-switch
Enum object
Allowed only if layer-mode
is "ip"
queue-size Integer Optional The queue-size property of qdio-virtual-switch
object.
ip-timeout Integer Optional The ip-timeout property of qdio-virtual-switch
object.
is-connect-uplinks Boolean Optional The is-connect-uplinks property of
qdio-virtual-switch object
is-use-any- Boolean Optional The is-use-any-available-controller property of
available- qdio-virtual-switch object. If the value is true and
controller virtual switch is successfully updated and there is a
controller available in the z/VM, this property will
be set to false, and the available controller will be
used and shown in the controllers property.
controllers Array of Optional; The controllers property of qdio-virtual-switch
Strings object.
Allowed only if
is-use-any-available-
controller is false
real-uplinks Array of Required if The real-uplinks property of qdio-virtual-switch
real- is-connect-uplinks is true object. If is-connect-uplinks is true, the list is
uplink required and contains 1-3 real-uplink objects.
objects
bridge-value-type String Optional; The bridge-value-type property of the
qdio-virtual-switch object
Allowed only if
bridge-device-number has
been specified
bridge-device- String Optional; The bridge-device-number property of the
number qdio-virtual-switch object
Allowed only if
theis-bridge-capable
property of the
virtualization host is true
and the layer-mode
property of the virtual
switch is "eth"

Chapter 15. Virtualization management 1029

 Level 04a

Field name Type Rqd/Opt Description

bridge-connection- String Optional; Values:
status v "connect" - Connect the bridge port. (Default
Allowed only if
value)
bridge-device-number has
been specified v "disconnect" - Disconnect the bridge port

mtu-size- String Optional; The mtu-size-enforcement property of the

enforcement qdio-virtual-switch object
Allowed only if the
is-bridge-capable property
of the virtualization host is
true
mtu-size Integer Optional; The mtu-size property of the qdio-virtual-switch
object. Required if mtu-size-enforcement is
Allowed only if "user-defined".
theis-bridge-capable
property of the
virtualization host is true
and the
mtu-size-enforcement
property of the virtual
switch is "user-defined"

Description
This operation modifies the virtual switch for the identified virtual server.

Authorization requirements
This operation has the following authorization requirements:
v Action/task role permission to the Manage Virtual Switches task
v Object-access permission to hosting-environment of the Virtualization Host with object-id {virt-host-id}.

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.
87 The iedn-virtual-switch object bridge-device-number property specified is
already in use.
88 The iedn-virtual-switch object bridge-device-number property specified is
not defined available to the z/VM Virtualization Host.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 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.

1030 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 80 The Virtualization Host} already has a vSwitch with a bridge where the
qdio-virtual-switch object bridge-value-type property is "primary".
81 The Virtualization Host already has four vSwitches with a bridge where the
qdio-virtual-switch object bridge-value-type property is "secondary". Four is
the maximum.
82 The bridge-connection-status property for an iedn-virtual-switch or
qdio-virtual-switch object must be "disconnected" to update bridge
properties.
83 To change the bridge-device-number property for an iedn-virtual-switch or
qdio-virtual-switch object, it must first be set to "none". This removes the
bridge device.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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

Delete Virtual Switch

The Delete Virtual Switch operation deletes an existing virtual network switch specified by an element
identifier for the z/VM Virtualization Host with the given object identifier.

HTTP method and URI

DELETE /api/virtualization-hosts/{virt-host-id}/virtual-switches/{virtual-switch-id}

URI variables

Variable Description
{virt-host-id} Object ID of the Virtualization Host
{virtual-switch-id} Element ID of the virtual switch

Description
This operation deletes the virtual switch for the identified Virtualization Host.

Authorization requirements
This operation has the following authorization requirements:
v Action/task role permission to the Manage Virtual Switches task
v Object-access permission to hosting-environment of the Virtualization Host with object-id {virt-host-id}.

HTTP status and reason codes

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

Chapter 15. Virtualization management 1031

 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.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 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 1 The request could not be processed because the HMC is not currently
Unavailable) communicating with an SE needed to perform the requested operation.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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

Activating a Virtualization Host

This operation is not directly accessible; it will occur as a side effect of activating the hosting
environment. If auto-start-virtual-servers is true, the Virtualization Host activation will also activate all
virtual servers on the Virtualization Host whose auto-start property is true.

See the Activate sections of the hosting environment objects for operation details, including URI
parameters, response body contents, authorization requirements, and HTTP status and reason codes.

Asynchronous result description

Once the activation job 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 Activate Virtualization Host
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 operation description in “Job Status and Reason Codes” on page 1033. The results also
include a job-results nested object that has the following form:

Field name Type Description

failed-virtual-servers Array of Array of the virtual servers whose activation failed. This field only exists
String/URI if the virtualization host activated, but one or more virtual servers failed
to activate, indicated by job-status-code 500 and job-reason-code 102.

1032 HMC Web Services API

 Level 04a

Job Status and Reason Codes

Job reason
Job status code code Description
200 (OK) N/A Activation completed successfully.
500 (Server Error) 100 Virtualization host activation failed.
101 Virtualization host activation job timed out.
102 Virtualization host activation succeeded, but some virtual servers failed
to activate, see the response body for a list of virtual servers that failed
to activate.

Deactivating a Virtualization Host

This operation is not directly accessible; it will occur as a side effect of deactivating the hosting
environment.

See the Deactivate sections of the hosting environment objects for operation details, including URI
parameters, response body contents, authorization requirements, and HTTP status and reason codes.

Asynchronous result description

Once the deactivation job 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 Deactivate Virtualization Host
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 operation description below. The results also include a job-results nested object that has the
following form:

Field name Type Description

failed-virtual-servers Array of Array of the virtual servers whose deactivation failed. This field only
String/URI exists if the virtualization host deactivated, but one or more virtual
servers failed to deactivate, indicated by job-status-code 500 and
job-reason-code 102.

Job Status and Reason Codes

Job reason
Job status code code Description
200 (OK) N/A Deactivation completed successfully.
500 (Server Error) 100 Virtualization host deactivation failed.
101 Virtualization host deactivation job timed out.
102 Virtualization host deactivation succeeded, but some virtual servers
failed to deactivate, see the response body for a list of virtual servers that
failed to deactivate.

SMAPI Error Response Body

If an operation encounters an error while communicating with a z/VM Virtualization Host via SMAPI, a
503 (Service Unavailable) status code is returned with reason code 100. If an operation is able to

Chapter 15. Virtualization management 1033

 Level 04a

communicate with a z/VM Virtualization Host and execute a command via SMAPI, but the SMAPI
command returns a nonzero return code, a 503 (Service Unavailable) status code is returned with reason
code 101 and the standard error response body is extended with the following information about the
SMAPI command failure:

Field name Type Description

smapi-command String The name of the SMAPI command that encountered the error
smapi-return-code String The return code returned when executing the SMAPI command
smapi-reason-code String The reason code returned when executing the SMAPI command
smapi-message String The error message returned when executing the SMAPI command or
null if no error message was provided

Inventory service data

Information about the Virtualization Hosts managed by the HMC can be optionally included in the
inventory data provided by the Inventory Service.

Inventory entries for Virtualization Host objects are included in the response to the Inventory Service's
Get Inventory operation when the request specifies (explicitly by inventory class, implicitly via a
containing category, or by default) that objects of the various Virtualization Host type-specific inventory
classes are to be included. An entry for a particular Virtualization Host is included only if the API user
has object-access permission to that object and the applicable type-specific inventory class has been
specified, as described in the following table:

Inventory class Includes Virtualization Hosts with “type” value

power-vm-virtualization-host power-vm
prsm-virtualization-host prsm
x-hyp-virtualization-host x-hyp
zvm-virtualization-host zvm

For each Virtualization Host object to be included, the inventory response array includes the following:
v An entry that is a JSON object with the same contents as is specified in the response body contents
section for the Get Virtualization Host Properties operation. That is, the data provided is the same as
would be provided if a Get Virtualization Host Properties operation were requested targeting this
object.
v An array entry for each Virtual Switch object associated with the virtualization host. For each such
resource, an entry is included that is a JSON object with the same contents as specified in the response
body contents section of the Get Virtual Switch Properties operation. As a result, the data provided is
the same as would be obtained if a Get Virtual Switch Properties operation where requested for each
resource listed by a List Virtual Switches operation targeting the virtualization host.
v An array entry for each Virtualization Host Storage Resource object associated with the virtualization
host. For each such resource, an entry is included that is a JSON object with the same contents as
specified in the response body contents section of the Get Virtualization Host Storage Resource
Properties operation, however storage path accessibility status is not provided. (More specifically, the
accessible property of path-information-fcp and path-information-eckd nested objects will always null.)
This data is described in Chapter 16, “Storage management,” on page 1139. As a result, the data
provided is the same as would be obtained if a Get Virtualization Host Storage Resource Properties
operation were requested with the include-path-accessibility query parameter specified as false for
each resource listed by a List Virtualization Host Storage Resources operation targeting the
virtualization host.
v An array entry for each Virtualization Host Storage Group object associated with the virtualization
host. For each such group, an entry is included that is a JSON object with the same contents as
specified in the response body contents section of the Get Virtualization Host Storage Group
1034 HMC Web Services API
 Level 04a

Properties operation. This data is described in Chapter 16, “Storage management,” on page 1139. As a
result, the data provided is the same as would be obtained if a Get Virtualization Host Storage Group
Properties operation where requested for each group listed by a List Virtualization Host Storage
Groups operation targeting the virtualization host.

The array entry for a Virtualization Host object will appear in the results array before entries for
associated virtual switches, virtualization host storage resources, or groups.

Sample inventory data

The following fragments are examples of the JSON objects that would be included in the Get Inventory
response to describe a single Virtualization Host object of a particular type. These objects would appear
as array entries in the response array.

{
"acceptable-status": [
"operating"
],
"auto-start-virtual-servers": false,
"class": "virtualization-host",
"description": "",
"feature-list: [],
"has-unacceptable-status": "true",
"minimum-memory-size-for-virtual-server": 256,
"name": "B.1.14",
"object-id": "baab1cd2-2990-11e0-8d5b-001f163803de",
"object-uri": "/api/virtualization-hosts/baab1cd2-2990-11e0-8d5b-001f163803de",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-
be79e49dd340",
"status": "operating",
"type": "power-vm",
"virtual-server-shutdown-timeout": 300
}

Figure 556. Virtualization Host object: Sample inventory data for a virtualization host of type "power-vm"

Chapter 15. Virtualization management 1035

 Level 04a

{
"acceptable-status": [
"operating",
"channel-acceptable"
],
"auto-start-virtual-servers": false,
"class": "virtualization-host",
"description": "Initial description",
"feature-list: [],
"has-unacceptable-status": "false",
"hosting-environment": "/api/cpcs/37c6f8a9-8d5e-3e5d-8466-be79e49dd340",
"is-locked": false,
"name": "R32",
"object-id": "bab76208-2990-11e0-8d5b-001f163803de",
"object-uri": "/api/virtualization-hosts/bab76208-2990-11e0-8d5b-001f163803de",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-
be79e49dd340",
"status": "operating",
"type": "prsm",
"virtual-server-shutdown-timeout": 200
}

Figure 557. Virtualization Host object: Sample inventory data for a virtualization host of type "prsm"

{
"acceptable-status": [
"operating"
],
"auto-start-virtual-servers": true,
"class": "virtualization-host",
"cpu-shares-supported": true,
"description": "",
"feature-list: ["boot-sequence-network-priority-restriction"],
"has-unacceptable-status": "true",
"hosting-environment": "/api/blades/b8210bc0-2d1e-11e0-ae81-e41f13fe1430",
"is-locked": false,
"maximum-allowed-ide-devices": 3,
"maximum-allowed-virtual-processors": 16.0,
"maximum-memory-size-for-virtual-server": 125829,
"memory-increment-in-megabytes": 1,
"minimum-memory-size-for-virtual-server": 1,
"mixed-mode-boot-restriction": true,
"name": "B.1.03",
"object-id": "931b25d6-82e1-11e0-b9e4-f0def10bff8d",
"object-uri": "/api/virtualization-hosts/931b25d6-82e1-11e0-b9e4-f0def10bff8d",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/nodes/37c6f8a9-8d5e-3e5d-8466-
be79e49dd340",
"status": "operating",
"type": "x-hyp",
"virtual-server-shutdown-timeout": 302
}

Figure 558. Virtualization Host object: Sample inventory data for a virtualization host of type "x-hyp"

Virtual Server Object

A Virtual Server object represents a single virtual server.

1036 HMC Web Services API

 Level 04a

Data model
This object includes the properties defined the “Base managed object properties schema” on page 60, with
the following class-specific specialization:
Table 391. Virtual Server object: base managed object properties specializations
Name Qualifier Type Description of specialization
name (w)(pc) String The display name of the virtual server. Names must be unique to
(1-64) other existing virtual servers on the virtualization host.

The format of the name varies based on the virtual server type:
v "zvm": 1-8 characters, characters may be uppercase alphanumeric
or any of the following characters: “@#$+:”
v "power-vm", "x-hyp": 1-64 characters, must begin with an
alphabetic characters, other characters may be characters may be
alphanumeric, a space, or any of the following characters:
“!@#$%^*()_+-=,.:;'~”
v "prsm": 1-8 characters, alphanumeric

For virtual servers of type "prsm", this property is the LPAR name
as defined in the active IOCDS and is immutable.

This property is also immutable for virtual servers whose type

property is "zvm", though it is user-defined through the Create
Virtual Server operation.

For "power-vm" and "x-hyp" virtual servers, this property may only
be modified when the virtual server's status is "not-operating".
description (w)(pc) String Read-only for virtual servers of type "prsm".
object-uri — String/ The canonical URI path for a Virtual Server object is of the form
URI /api/virtual-servers/{object-id}.
parent — String/ The URI path of the virtualization host that hosts this virtual server.
URI
class — String (14) Always "virtual-server".

Chapter 15. Virtualization management 1037

 Level 04a

Table 391. Virtual Server object: base managed object properties specializations (continued)
Name Qualifier Type Description of specialization
status (sc) String The current operational status of the managed resource.
Enum
"prsm" values:
v "not-activated" - indicates the virtual server's LPAR image was
not activated.
v "operating" - indicates all CPs are operating
v "not-operating" - indicates no CPs are operating
v "not-communicating" - indicates the HMC is not communicating
with the support element
v "exceptions" - indicates the virtual server has a problem of some
sort, such as not being able to access storage
v "status-check" - indicates at least one CP is operating, but at least
one CP is not operating. When a "prsm" virtual server has this
status, its LPAR Image is not available.

"power-vm" and "x-hyp" values:

v "operating" - indicates virtual server is in an activated and
running state
v "not-operating" - indicates the virtual server is deactivated, in the
process of loading, or has a error
v "not-communicating" - indicates the HMC is not communicating
with the support element
v "exceptions" - indicates the virtual server has a problem of some
sort, such as not being able to access storage
v "status-check" - indicates the virtual server is powered on, but
the virtualization host is not communicating so there is no status
available
v "migrating" - indicates the virtual server is in the process of
migrating to another virtualization host
v "starting" - indicates the virtual server in the process of powering
on
v "stopping" - indicates the virtual server in the process of
powering off.

"zvm" values:
v "operating" – indicates the virtual machine is logged on and has
no current failure conditions
v "not-operating"– indicates the virtual machine is logged on, but
currently has some sort of failure condition
v "not-activated" – indicates the virtual machine is not logged on
v "not-communicating" - indicates the HMC is not communicating
with the support element
v "logoff-timeout-started" – indicates a logoff timeout has been
started for the virtual machine
v "storage-limit-exceeded" – indicates the storage limit has been
exceeded for the virtual machine
v "forced-sleep" – indicates the virtual machine is logged on, but
has been placed into a forced sleep state
v "unknown" – indicates the status of the virtual machine reported
by z/VM was not recognized.

1038 HMC Web Services API

 Level 04a

Table 391. Virtual Server object: base managed object properties specializations (continued)
Name Qualifier Type Description of specialization
acceptable-status (w)(pc) Array of For virtual servers of type "prsm", this property is immutable.
String
Enum For "zvm" virtual servers, the following status values may not be
set as acceptable: "not-communicating" and "unknown".
additional-status (sc) String The property is not provided for virtual servers of type
Enum "power-vm", "x-hyp", or "prsm".

For "zvm" virtual servers, this property only applies when the
status is "not-operating" and only if the status is "not-operating"
because of the current state of its hosting-environment. In other
cases for a "zvm" virtual server, the value of this property is null.

Values when non-null:

v "host-env-not-activated" - indicates the "zvm" virtual server is
not operating because the hosting-environment is not activated
v "host-env-not-capable" - indicates the "zvm" virtual server is not
operating because the hosting-environment is not allowing
communications. This can be due to a temporary condition at the
support element for the associated CPC or can be due to SMAPI
communication problems.
v "host-env-not-operating" – indicates the "zvm" virtual server is
not operating because the hosting-environment is not operating

Data model notes

For an x Hyp virtual server, the UUID assigned by zManager as the virtual server's object ID and thus
provided as the virtual server's object-id property is also used as the virtual server's System Management
BIOS (SMBIOS) UUID. As a result, this value is visible to software running within the virtual server as
the UUID field of the SMBIOS System Identification (Type 1) structure. Guest operating system interfaces
or utilities, such as the Linux lspci command, may be available to query this value. Because the object ID
is available both from outside the guest as well as within, it can serve as a reliable correlating value for
management application that have a need to associate data obtained from these two environments.

Class specific additional properties

In addition to the properties defined in included schemas, this object includes the following additional
class-specific properties.

Note: Many properties are only valid for virtual servers of specific “type”. These value are only included
in a Virtual Server object if the virtual server is of that type. For example a virtual server with type
"power-vm" will define a processing-mode property ("power-vm" only) and mac-prefix property
("power-vm", "zvm") but not an initial-share-mode property ("zvm" only).

Other properties are only valid when mutable prerequisite properties have specific values. When such
properties are not valid, their value is null. For instance a "power-vm" virtual server's
initial-virtual-processors property value is null when the processing-mode value is "dedicated".

Chapter 15. Virtualization management 1039

 Level 04a

Table 392. Virtual Server object: class specific additional properties

Supported
“type”
Name Qualifier Type Description values
type — String Type of the virtual server. Values: All
Enum v "power-vm" - a virtual server that has been defined on
an IBM POWER7 blade
v "x-hyp" - a virtual server that has been defined on an
IBM System x blade
v "zvm" - a virtual server that has been defined on an
IBM z/VM operating system instance that is
participating as an ensemble-managed Virtualization
Host
v "prsm" - the virtual server representation of an LPAR
image.
gpmp-status (pc) String Status of the Guest Platform Management Provider All
Enum (GPMP). Values:
v "unknown" – Guest performance agent status could not
be determined
v "not-operating" – Guest performance agent is not
operating
v "operating" – Guest performance agent is operating
v "status-check" – There is a failure in communications
between the virtual server and the guest performance
agent.

If virtual server type is "prsm", gpmp-status is only

available if virtual server is running z/OS.
cpu-perf-mgmt- (w)(pc) Boolean If true, management of processor performance is enabled x-hyp,
enabled for this virtual server if management of processor power-
performance is enabled at the ensemble level. vm, zvm
Note: Management of processor performance at the
ensemble level is enabled by virtual server type. See the
ensemble object's cpu-perf-mgmt-enabled-x-hyp,
cpu-perf-mgmt-enabled-power-vm, and
cpu-perf-mgmt-enabled-zvm properties.

Prerequisite:
v The parent virtualization host's cpu-shares-supported
value is true.
hostname (pc) String Virtual server host name. This data is only available if the power-
Guest Platform Management Provider is running on the vm,
virtual server. x-hyp,
zvm
os-name (pc) String The name given to this system by its operating system. All
This data is only available if the Guest Platform
Management Provider is running on the virtual server.
os-type (pc) String The type of operating system that is running on the All
virtual server. This data is only available if the Guest
Platform Management Provider is running on the virtual
server.
os-level (pc) String The release level of the operating system, as reported by All
the OS itself. This data is only available if the Guest
Platform Management Provider is running on the virtual
server.

1040 HMC Web Services API

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
mac-prefix (pc) mac-prefix MAC address provides the means of identification that power-
Object forwards frames within the LAN segment. This prefix is vm, zvm
the first part of all MAC addresses assigned for the
virtual server. The remaining bits are dynamically
assigned when the virtualization host has to generate a
MAC address for a network adapter.
processing-mode1 (w) String The manner in which virtual processors are associated power-vm
Enum with the physical processors available on the
virtualization host. Values:
v "shared" - In shared mode, the virtual servers can use
fractions of physical processors. The processor capacity
is assigned in 0.1 units of physical processor, equivalent
to 1.0 virtual processing unit. The virtual processor
units can be shared among multiple virtual servers.
v "dedicated" - In dedicated mode, the processors are
assigned in whole units of physical processors. The
processors that are dedicated to the virtual server
cannot be used by other virtual servers. The virtual
server cannot use any processors other than its own
dedicated processors.
minimum- (w) Integer Defines the minimum number of dedicated processors power-vm
dedicated- that the virtual server can use.3
processors1
Prerequisite: processing-mode is "dedicated".

Limits:
v >= 1
v <= maximum-allowed-dedicated-processors
initial-dedicated- (w)(pc) Integer Defines the initial number of dedicated processors that the power-vm
processors1, 2 virtual server can use; the number of dedicated processors
to be provided to the virtual server when it is next
activated.3

Prerequisite: processing-mode is "dedicated".

"power-vm" Limits:
v >= 1
v <= maximum-allowed-dedicated-processors
v >= minimum-dedicated-processors
maximum- (w) Integer The upper limit for the number of dedicated processors to power-vm
dedicated- for the virtual server to consume.3
processors1
Prerequisite: processing-mode is "dedicated"

"power-vm" Limits:
v >= 1
v <= maximum-allowed-dedicated-processors
v >= minimum-dedicated-processors
v >= initial-dedicated-processors

Chapter 15. Virtualization management 1041

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
minimum-virtual- (w) Integer Defines the minimum number of virtual processors that power-vm
processors1 the virtual server can use.3

Prerequisite: processing-mode is "shared".

Limits:
v >= 1
v <= 10 * minimum-processing-units
v >= minimum-processing-units
initial-virtual- (w) Integer Defines the initial number of virtual processors that the power-
processors1, 2 virtual server can use; the number of virtual processors to vm,
be provided to the virtual server when it is next x-hyp,
(1applies to activated.3 zvm
PowerVM and x
Hyp only, 2applies Prerequisites:
only to PowerVM) v "x-hyp", "zvm": none
v "power-vm": processing-mode is "shared"

"power-vm" limits:
v >= 1
v <= 10 * initial-processing-units
v >= initial-processing-units
v >= minimum-virtual-processors

"x-hyp" limits:
v >= 1
v <= maximum-allowed-virtual-processors

"zvm" limits:
v >= 1
maximum-virtual- (w) Integer The upper limit for the number of virtual processors to power-
processors1 for the virtual server to consume.3 vm, zvm

(1applies to Prerequisites:
PowerVM only) v "x-hyp", "zvm": none
v "power-vm": processing-mode is "shared"

"power-vm" limits:
v >= 1
v <= 10 * maximum-processing-units
v >= maximum-processing-units
v >= minimum-virtual-processors
v >= initial-virtual-processors
v <= maximum-allowed-virtual-processors

"zvm" limits:
v >= 1
v >= initial-virtual-processors
v <= maximum-allowed-virtual-processors

1042 HMC Web Services API

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
minimum- (w) Float The minimum number of processing units required for power-vm
processing-units1 this virtual server to start running.

Prerequisite: processing-mode is "shared".

Limits:
v >= 0.1 * minimum-virtual-processors
v <= minimum-virtual-processors
v <= maximum-allowed-processing-units
v Fixed to two decimal places
initial-processing- (w) Float The number of processing units representing the initial power-vm
units1, 2 processor scheduling target for this virtual server. If
resources are available, the virtual server may receive
more than this amount.4

Prerequisite: processing-mode is "shared".

Limits:
v >= .1 * initial-virtual-processors
v <= initial-virtual-processors
v <= maximum-allowed-processing-units
v >= minimum-processing-units
v Fixed to two decimal places
maximum- (w) Float The maximum number of processing units that will be power-vm
processing-units1 allocated to the virtual server (processor utilization
capping).

Prerequisite: processing-mode is "shared".

If you have enabled processor management, Maximum

processing units defines the upper limit for zManager. A
virtual server with a capacity equal to this maximum
value cannot receive resources from other virtual servers
on the blade.

Limits:
v >= 0.1 * maximum-virtual-processors
v <= maximum-virtual-processors
v <= maximum-allowed-processing-units
v >= minimum-processing-units
v >= initial-processing-units
v Fixed to two decimal places

Chapter 15. Virtualization management 1043

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
initial-share- (w) String Defines the virtual servers' initial share of system zvm
mode Enum resources either relative to other virtual servers or
absolutely. Values:
v "relative" - Grants all virtual servers different priorities
for processor and I/O. A relative share allocates to a
virtual server a portion of the total system resources
minus those resources allocated to virtual servers with
an absolute share. Also, a virtual server with a relative
share receives access to system resources that is
proportional with respect to other virtual servers with
relative shares. For example, if a virtual server (VM1)
has a relative share of 100, and a second virtual server
(VM2) has a relative share of 200, VM2 receives twice
as much access to system resources as VM1.
v "absolute" - Grants universal access and priority over
all other virtual servers. An absolute share allocates to a
virtual server an absolute percentage of all available
system resources. For example, if you assign a virtual
server an absolute share of 50%, CP allocates to that
virtual server approximately 50% of all available
resources (regardless of the number of other virtual
servers running).
initial-shares (w)(pc) Float/ On x Hyp virtualization hosts: x-hyp,
Integer zvm
Defines the initial share value for the virtual server
relative to other virtual servers on the virtualization host.
This field can not be updated when the virtual server's
status is "operating" and cpu-perf-mgmt-enabled is
"true". This field expects an integer.

Default value (used if cpu-shares-supported changes to

true: 1024.

Limits:
v >= minimum-shares
v <= maximum-shares

Prerequisite:
v The parent virtualization host's cpu-shares-supported
value is true.

On z/VM virtualization hosts:

If initial-share-mode is "relative", defines the initial share

value for the virtual server relative to other virtual servers
on the virtualization host. When maximum-share-mode is
"relative", this value must be an Integer between 1 and
min (maximum-shares, 10000).

If initial-share-mode is "absolute", defines the initial

share value for the virtual server absolutely. When
maximum-share-mode is "absolute", this value must be a
Number between 0.1 and min (maximum-shares, 100),
fixed to one decimal place.

1044 HMC Web Services API

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
share-limit (w) String Define how the virtual server's share of system resources zvm
is limited. Values:
v "none" - Specifies that a server share of processing
resource is not limited.
v "soft" - Specifies that the share of processing resource is
limited but at times these servers can receive more than
their limit, if no other server can use the available
resources.
v "hard" - Specifies that the share of processing resource
is limited. These servers can not receive more than their
limit.
maximum-share- (w) String Defines the virtual servers' maximum share of system zvm
mode Enum resources either relative to other virtual servers or
absolutely.

Prerequisites: share-limit is "soft" or "hard".

Values:
v "relative" - Grants all virtual servers different priorities
for processor and I/O. A relative share allocates to a
virtual server a portion of the total system resources
minus those resources allocated to virtual servers with
an absolute share. Also, a virtual server with a relative
share receives access to system resources that is
proportional with respect to other virtual servers with
relative shares. For example, if a virtual server (VM1)
has a relative share of 100, and a second virtual server
(VM2) has a relative share of 200, VM2 receives twice
as much access to system resources as VM1.
v "absolute" - Grants universal access and priority over
all other virtual servers. An absolute share allocates to a
virtual server an absolute percentage of all available
system resources. For example, if you assign a virtual
server an absolute share of 50%, CP allocates to that
virtual server approximately 50% of all available
resources (regardless of the number of other virtual
servers running).
minimum-shares (w)(pc) Integer Defines the minimum share value for the virtual server on x-hyp
the virtualization host. This field can not be updated
when the virtual server's status is "operating" and
cpu-perf-mgmt-enabled is "true". This field expects an
integer.

Limits:
v >= 2
v <= initial-shares

Prerequisite:
v The parent virtualization host's cpu-shares-supported
value is true.

Chapter 15. Virtualization management 1045

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
maximum-shares (w)(pc) Float/ On x Hyp virtualization hosts: x-hyp,
Integer zvm
Defines the maximum share value for the virtual server
on the virtualization host. This field can not be updated
when the virtual server's status is "operating" and
cpu-perf-mgmt-enabled is "true". This field expects an
integer.

Default value (used if cpu-shares-supported changes to

true): 262144.

Limits:
v >= initial-shares
v <= 262144

Prerequisite:
v The parent virtualization host's cpu-shares-supported
value is true.

On z/VM virtualization hosts:

If maximum-share-mode is "relative", defines the

maximum share value for the virtual server relative to
other virtual servers on the virtualization host. When
maximum-share-mode is "relative", this value must be an
Integer between 1 and min (maximum-shares, 10000).

If maximum-share-mode is "absolute", defines the

maximum share value for the virtual server absolutely.
When maximum-share-mode is "absolute", this value
must be a Number between 0.1 and min
(maximum-shares, 100), fixed to one decimal place.

Prerequisites: share-limit is "soft" or "hard".

minimum- (w) Integer Minimum memory value for use by the virtual server, power-vm
memory1 specified in megabytes (MB). Must be a multiple of
virtualization host's memory-increment-in-mega-bytes
value.

"power-vm" limits:
v >= minimum-memory-size-for-virtual-server
v multiple of memory-increment-in-mega-bytes

1046 HMC Web Services API

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
1, 2
initial-memory (w)(pc) Integer Initial memory value for use by the virtual server, power-
specified in MB. Must be a multiple of virtualization vm,
(1applies to host's memory-increment-in-mega-bytes value. x-hyp,
PowerVM and x zvm
Hyp only, 2applies "power-vm" limits:
only to PowerVM) v >= minimum-memory-size-for-virtual-server
v multiple of memory-increment-in-mega-bytes
v >= minimum-memory
v <= maximum-memory
v <= maximum-memory-size-for-virtual-server

"x-hyp" limits:
v >= minimum-memory-size-for-virtual-server
v multiple of memory-increment-in-mega-bytes
v <= maximum-memory-size-for-virtual-server

"zvm" limits:
v >= minimum-memory-size-for-virtual-server
v multiple of memory-increment-in-mega-bytes
v <= maximum-memory
v <= maximum-memory-size-for-virtual-server
maximum- (w) Integer Maximum memory value for use by the virtual server, power-
memory1 specified in MB. Must be a multiple of virtualization vm, zvm
host's memory-increment-in-mega-bytes value.
(1applies to
PowerVM only) "power-vm" limits:
v >= minimum-memory-size-for-virtual-server
v multiple of memory-increment-in-mega-bytes
v >= minimum-memory
v >= initial-memory
v <= maximum-memory-size-for-virtual-server

"zvm" limits:
v >= minimum-memory-size-for-virtual-server
v multiple of memory-increment-in-mega-bytes
v <= maximum-memory-size-for-virtual-server
workloads (c)(pc) Array of The canonical URI path of each workload resource group All
String/ to which the virtual server is assigned.
URI
network-adapters — Array of Array of nested Network Adapter objects defining the All
objects virtual server's network adapters. The nested objects are
of type network-adapter-power, network-adapter-x-hyp,
network-adapter-zvm or network-adapter-prsm
depending on the type of the virtual server.
virtual-disks — Array of Array of nested Virtual Disk objects defining the virtual power-
objects server's virtual disks. vm,
x-hyp,
zvm

Chapter 15. Virtualization management 1047

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
mounted-media- — String The display name of the mounted ISO or null if no media power-
name (0-255) is mounted. vm, x-hyp
boot-mode (w)(pc) String The boot mode of the virtual server. Values: power-vm
Enum v "normal" - The virtual server boots in normal mode.
v "sms" - The virtual server boots to the System
Management Services (SMS) menu.
v "diagnostic-default-boot-list"- The sequence of devices
read at startup.
v "diagnostic-stored-boot-list" - The virtual server
performs a service mode boot using the service mode
boot list saved in NVRAM.
v "open-firmware-prompt" - The virtual server boots to
the open firmware prompt.

1048 HMC Web Services API

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
boot-sequence (w)(pc) Array of List of boot sources. Values: power-
String v "virtual-disk" – virtual-disks will be tried in order vm, x-hyp
Enum
v "network-adapter" – the first network-adapter will be
used as a boot source
v "virtual-media" – virtual media will be used as a boot
source

List must contain one and only one element for type
"power-vm"

"virtual-disk" is not a valid value if the virtual server's

virtual-disks property is empty.

"network-adapter" is not a valid value if the virtual

server's network-adapters property is empty.

"power-vm" network-adapter boot notes:

v If boot-network-adapter-client-ip, boot-network-adapter-
subnet-ip, boot-network-adapter-gateway-ip, and
boot-network-adapter-server-ip are not defined, boot
network settings defined via DHCP.
v If boot-network-adapter-client-ip, boot-network-adapter-
subnet-ip, and boot-network-adapter-server-ip are
defined, but boot-network-adapter-gateway-ip is not
defined, boot network settings are manually defined
and netboot is limited to its own subnet.
v If boot-network-adapter-client-ip, boot-network-adapter-
subnet-ip, boot-network-adapter-gateway-ip, and
boot-network-adapter-server-ip are all defined, boot
network settings are manually defined and netboot is
not limited to its own subnet.

"x-hyp" virtual-disk boot notes:

v Booting is always enabled for Virtual DVDs (virtual
media), virtual disks, and virtual network adapters if
devices of these types are defined for the virtual server.
Although it is possible to change the order in which
booting is attempted, it is not possible to disable
booting from devices of these types if they are present
for the virtual server. See the text directly after this
table for considerations that apply to the value of the
boot-sequence property.
v If the virtual server resides on a node that is being
managed by Support Element Version 2.11.1, a virtual
network interface (if present) must be either the first or
last entry in the virtual server's boot sequence. That is,
the value "network-adapter" must appear as either the
first or last entry in the boot-sequence property.

"x-hyp" virtual-disk boot notes:

v If the virtualization host's mixed-mode-boot-restriction
value is true and the virtual-disks property defines both
"virtio" and "ide" virtual disks, the virtual server will
only boot from an "ide" virtual-disk when the
boot-sequence value contains "virtual-disk".

Chapter 15. Virtualization management 1049

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
boot-network- (w) String The IP address of the virtual server used during network power-vm
adapter-client-ip (0-39) boot in dotted-decimal form (“nnn.nnn.nnn.nnn”).

Prerequisites: boot-sequence contains "network-adapter".

boot-network- (w) String The IPv4 subnet mask of the network used during power-vm
adapter-subnet-ip (0-17) network boot of the virtual server in dotted-decimal form
(“nnn.nnn.nnn.nnn”).

Prerequisites: boot-sequence contains "network-adapter".

boot-network- (w) String The IP address of the gateway system used during power-vm
adapter-gateway- (0-39) network boot of the virtual server in dotted-decimal form
ip (“nnn.nnn.nnn.nnn”).

Prerequisites: boot-sequence contains "network-adapter".

boot-network- (w) String The IP address of the boot server on which the disk boot power-vm
adapter-server-ip (0-39) source files reside in dotted-decimal form
(“nnn.nnn.nnn.nnn”).

Prerequisites: boot-sequence contains "network-adapter".

keylock (w) String Indicates the state of the system key lock at boot time. power-vm
Enum Value:
v "normal" – Enables a regular operating system boot of
the virtual server including all services, under program
control.
v "manual" - Requires system operator to manually boot
the virtual server. This setting is useful for service
scenarios. The virtual server boots to the diagnostics
menu, then you have to open a console to the virtual
server and work with the displayed menu to choose the
next steps.
auto-start (w)(pc) Boolean If true, this virtual server is automatically started when its All
hosting virtualization host is started.
(w only
for
PowerVM
and x
Hyp)
dlpar-enabled (w) Boolean If true, this virtual server is configured for Dynamic power-vm
Logical Partitioning. Note: This setting does not enable
any DLPAR prerequisites (such as the Resource
Monitoring and Control network).
dlpar-active — Boolean If true, DLPAR support is enabled and specific virtual power-vm
server properties may be updated when the virtual server
status is "operating".
gpmp-support- (w)(pc) Boolean If true, Guest Platform Management Provider support is All
enabled enabled, allowing the GPMP to gather performance data
(ro for for work running on the virtual server.
PR/SM) Note: This only defines if support is enabled, not if it is
active.

1050 HMC Web Services API

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
gpmp-version — String Guest Platform Management Provider version or keyword power-
"unavailable" if not known. vm,
x-hyp,
If virtual server type is "prsm", "gpmp-version" is only zvm
available if virtual server is running z/OS.
password (w) String (1-8) The password or passphrase to be used for authentication. zvm
Password must meet the guidelines defined by the VM
system. 1-8 uppercase characters long.
privilege-classes (w) String String defining z/VM CP privilege classes denoted by the zvm
(1-32) letters A through Z (uppercase), the numbers 1 through 6,
and the word “ANY”. 1-32 characters long
ipl-device (w)(pc) String (1-8) Specifies the virtual device that you want to IPL. It is the zvm
virtual device number or sysname of the virtual device.5

A virtual device number is a four character hex number.

The sysname is a 1 - 8 uppercase alphanumeric-character

name of the named saved system you want to IPL.
ipl-load- (w)(pc) String (0-8) The z/VM LOADPARM option value; used to pass a load zvm
parameters parameter of up to 8 bytes of data to the operating system
you are IPLing.5

0-8 characters long, character may be uppercase

alphanumeric, a space, or a period
ipl-parameters (w)(pc) String String defining the z/VM IPL parameter list.5 zvm
(0-64)
0:64 characters.
associated-logical- — String/URI The canonical URI path for the Logical Partition that is prsm
partition the PR/SM virtual server.
inband- (w)(pc) Boolean If true, in-band monitoring support is enabled, allowing power-
monitoring- the hypervisor to gather performance metrics for the vm, x-hyp
enabled virtual server.

Prerequisites: parent virtualization host's

inband-monitoring-supported value is true.

Chapter 15. Virtualization management 1051

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
keyboard- (w)(pc) String String describing the locale required by graphical consoles x-hyp
language connecting to the virtual server.

The value is null if the parent virtualization host's

supported-keyboard-languages array is null or empty.

String value is the locale's language, country, and variant

values separated by underscores:
v The language value is either an empty string or a
lowercase ISO 639 language code (2-4 characters).
v The country value is either an empty string or an
uppercase ISO 3166 two-letter code.
v The variant value is either an empty string or a string
defining variations for a language/country pair. For
example, Serbian locales have Cyrillic (“Cyrl”) and
Latin (“Latn”) variants.

If the language is an empty string, the string will begin

with an underscore. If both the language and country
fields are empty strings, the value will be an empty string.

Example values: “en”, “en_GB”, “en_US”, “sr_RS”,

“sr_RS_Cyrl”, and “sr_RS_Latn”.

Value must be defined in the parent virtualization host's

supported-keyboard-languages value array.
avail-status (pc) Array of The list of availability statuses of the virtual server, each
objects with reasons explaining the status, in order of severity.
The list will always contain at least one element in the
form of a virtual server availability status with reasons
nested object, as described in Table 393 on page 1054.
acceptable-avail- (w) (pc) Array of The set of avail-status values that the virtual server can
status String be in and be considered to be in an acceptable (not alert
Enum causing) state. A virtual server avail-status value of
"not-supported" has no impact on a virtual server’s
acceptable state.

Prerequisites: The virtual server’s avail-status is not

"not-supported".

Values may not contain "not-supported".

Refer to the virtual server availability status with reasons

nested object's avail-status property described in Table 393
on page 1054 for possible values.
workload- (pc) Array of The canonical URI path of each workload element group
element-groups String/URI to which the virtual server is assigned.
perf-policies (pc) Array of The list of workloads and performance policies that are All
objects active on the virtual server, each with the activation status
of the policy on the virtual server. The list will contain
one element for each workload with a performance policy
that has been activated on the virtual server in the form
of a virtual server performance policy nested object, as
described in Table 394 on page 1055.

1052 HMC Web Services API

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
avail-policies (pc) Array of The list of workloads and availability policies that are
objects active on the virtual server. The list will contain one
element for each workload to which the virtual server is
assigned in the form of a virtual server availability policy
nested object, as described in Table 395 on page 1055.
power-vm- — Integer The identifier of the PowerVM partition in which the power-vm
partition-id virtual server is running. A virtual server is assigned to a
PowerVM partition during the virtual server activation
process, and may be assigned to a different partition each
time it is activated. Therefore, this property has a value
only when the virtual server's status property is
"operating". If the virtual server is in some other status,
the value of this property is null.
shutdown- (w)(pc) String The source of the shutdown-timeout property. power-
timeout-source Enum vm, x-hyp
Values:
v "virtualization-host" - Use the virtual-server-
shutdown-timeout property defined in the
virtualization host that contains this virtual server.
v "virtual-server" - Use the shutdown-timeout property
defined for this virtual server.
shutdown- (w)(pc) Integer Amount of time, in seconds, to allow a virtual server to power-
timeout shut down. After the elapsed time has passed, the virtual vm, x-hyp
server will be forcefully terminated.

The value may be -1 to indicate to wait "forever" or any

integer value between 0 and 86400 to specify an exact
wait time in seconds.

This value is only used when the shutdown-timeout-

source property is set to "virtual-server".
gpmp-network- — Object Nested network adapter object defining the virtual power-
adapter server's GPMP network adapter. For a virtual server of vm, x-hyp
type "x-hyp" the nested object is of type
network-adapter-x-hyp. For a virtual server of type
"power-vm" the nested object is of type
network-adapter-power.

Chapter 15. Virtualization management 1053

 Level 04a

Table 392. Virtual Server object: class specific additional properties (continued)
Supported
“type”
Name Qualifier Type Description values
Notes:
1
These properties represent configuration values for the virtual server that are used to establish the virtual
server's initial configuration when it is activated.
2
These properties update runtime values when the virtual server status is "operating" and DLPAR is active
(dlpar-active value is true). If DLPAR is not active, updating these properties will not affect runtime values.
DLPAR support is only available for "power-vm".
3
Note: Because zManager-managed "power-vm" virtual servers consume resources on the Power ASB only when
activated, it is possible to overcommit and define a set of virtual servers on a virtualization host that together
require more virtual processors than can be simultaneously supported. PowerVM resource limits are enforced at
the time that a virtual server is activated.
4
This value is a configuration value that is used to set the scheduling goal when the virtual server is activated.
If CPU performance management is active for this virtual server, the run time value may be adjusted as the
virtual server operates. This will not change the “initial” value and thus does not trigger property change event.
The current processing unit goal for the virtual server will be available as a virtual server metric.
5
The maximum length of the IPL Directory statement resulting from the ipl-device, ipl-load-parameters, and
ipl-parameters values may not exceed 72 characters. Refer to the z/VM CP Planning and Administration Guide for
details on the IPL Directory statement.

The following considerations apply to the value of the boot-sequence property:

v Because a virtual server always has a virtual DVD device, the value "virtual-media" must always
appear somewhere within the value of the boot-sequence property.
v If the virtual server has one or more virtual disks defined, then the value "virtual-disk" must appear
within boot-sequence property. When the first virtual disk is defined for a virtual server, the
boot-sequence property is updated to add "virtual-disk" as the last entry in the list. When the last
virtual disk is removed, the value "virtual-disk" is removed from the boot-sequence property.
v Similarly, if the virtual server has one or more virtual network interfaces defined, then the value
"network-adapter" must also appear within the boot-sequence property. When the first virtual network
interface is defined for a virtual server, the boot-sequence property is updated to add
"network-adapter" as the last entry in the list. When the last virtual network interface is removed, the
value "network-adapter" is removed from the boot-sequence property.

The virtual server availability status with reasons nested object is nested within a Virtual Server object to
encapsulate the availability status with the reasons explaining why it is in that state.
Table 393. Virtual Server object: virtual server availability status with reasons nested object properties
Name Type Description
avail-status String Enum The availability status of the virtual server, determined by its operational
status, its GPMP, its CPC, and its OS. The possible values are as follows:
v "available" - The virtual server is considered available.
v "exposed" - The virtual server is considered exposed.
v "critical"- The virtual server is considered critically exposed.
v "not-available" - The virtual server is considered not available.
v "not-supported" - The virtual server is from a CPC that does not
support Ensemble Availability Management.

1054 HMC Web Services API

 Level 04a

Table 393. Virtual Server object: virtual server availability status with reasons nested object properties (continued)
Name Type Description
reasons String Enum The list of reasons given for the availability status of the virtual server.
The possible values are as follows:
v "vs" - The virtual server's operational status is contributing to this
availability status.
v "cpc" - The virtual servers CPC's operational status is contributing to
this availability status.
v "gpmp"- The virtual server's GPMP's status is contributing to this
availability status.
v "node" - The operational status of the node is contributing to this
availability status.

The list may be empty if no reasons are given.

The virtual server performance policy nested object is nested within a Virtual Server object to encapsulate
the performance policies that are active on the virtual server and their activation status with respect to
the virtual server.
Table 394. Virtual Server object: virtual server performance policy nested object
Name Type Description
workload-uri String/URI The canonical URI path of the workload resource group to which the
performance policy identified by policy-name is assigned.
policy-name String The name property of the Performance Policy object.
activation-status String Enum The status of activating the performance policy on the virtual server.
Possible values are:
v "initializing" - Status is initializing (not yet known).
v "successful" - The policy has been successfully activated on the virtual
server.
v "failed"- Policy activation failed.
v "pending" - Policy activation is pending (in progress).

The virtual server availability policy nested object is nested within a Virtual Server object to encapsulate
the availability policies that are active on the virtual server.
Table 395. Virtual Server object: virtual server availability policy nested object
Name Type Description
workload-uri String/URI The canonical URI path of the workload resource group to which the
availability policy identified by policy-uri is assigned.
policy-uri String/URI Canonical URI path of the Availability Policy object, in the form
/api/workload-resource-groups/{workload-id}/availability-policies/
{policy-id}.
avail-status- Boolean The avail-status value of the virtual server is excluded from impacting
impact-exclusion the availability status of the workload identified by {workload-uri} by the
avail-status-impact-exclusion property of the availability policy
identified by {policy-uri}.

Value is always false if the class is "workload-resource-group" or

"workload-element-group" or if the class is "virtual-server" and the
parent-class is "workload-element-group".

Chapter 15. Virtualization management 1055

 Level 04a

mac-prefix object: A mac-prefix object defines a "power-vm" or "zvm" virtual server's mac-prefix
property value.
Table 396. mac-prefix object properties
Name Type Description
mac-address String The MAC address represented as 6 groups of two lower-case hexadecimal digits
(17) separated by colons ( : ), e.g. “01:23:45:67:89:ab”. Length is 17 characters. The
MAC address uses the ensemble prefix.
prefix-length Integer The bit length of the MAC address prefix. This is a 2-digit value with these
parameters in the range 12-44.

network-adapter objects: The bit length of the MAC address prefix. This is a 2-digit value with these
parameters in the range 12-44.

The network-adapter-power object defines a network adapter of a virtual-server of type "power-vm".

Table 397. network-adapter-power object properties
Name Qualifier Type Description
element-id — String Unique ID for the virtual network adapter within the scope of the
containing virtual server.

It is a randomly generated integer value when the object is

created. Currently this value will change if this object is modified
or the group of network adapters of the virtual server is
reordered.
element-uri — String/ URI The canonical URI path for the virtual network adapter is of the
form /api/virtual-servers/{virtual-server-id}/network-
adapters/{element-id}, where {virtual-server-id} is the object-id of
the virtual server.
network-uri (w) String/ URI The canonical URI path for the associated virtual network or null
if the network adapter is not connected to a virtual network.
mac-address — String (17) The MAC address of the network adapter represented as 6
groups of two lowercase hexadecimal digits separated by colons (
: ), e.g. “01:23:45:67:89:ab”. Length is 17 characters. The MAC
address uses the ensemble prefix.
adapter-type — String The type of the network adapter. The possible values are as
Enum follows:
v "regular" - The network adapter is the regular network adapter
( non-monitoring).
v "gpmp" - The network adapter is the resource monitoring
network adapter used for Guest Platform Management
Provider (GPMP).

The network-adapter-x-hyp object defines a network adapter of a virtual-server object of type "x-hyp".
Table 398. network-adapter-x-hyp object properties
Name Qualifiers Type Description
element-id — String Unique ID for the virtual network adapter within the scope of the
containing virtual server.
element-uri — String/ URI The canonical URI path for the virtual network adapter is of the
form /api/virtual-servers/{virtual-server-id}/network-
adapters/{element-id}, where {virtual-server-id} is the object-id of
the virtual server.

1056 HMC Web Services API

 Level 04a

Table 398. network-adapter-x-hyp object properties (continued)

Name Qualifiers Type Description
emulation-mode — String The network adapter emulation mode. Values:
Enum v "e1000" – Intel E1000
v "rtl8139" – Realtek 8139
v "virtio" – RedHat virtio
network-uri (w) String/ URI The canonical URI path for the associated virtual network or null
if the network adapter is not connected to a virtual network.
mac-address — String (17) The MAC address of the network adapter represented as 6 groups
of two lowercase hexadecimal digits separated by colons ( : ), e.g.
“01:23:45:67:89:ab”. Length is 17 characters.
adapter-type — String The type of the network adapter. The possible values are as
Enum follows:
v "regular" - The network adapter is the regular network adapter
( non-monitoring).
v "gpmp" - The network adapter is the resource monitoring
network adapter used for Guest Platform Management Provider
(GPMP).

The network-adapter-zvm object defines a network adapter of a virtual-server object of type "zvm".

Note: Some properties are only valid for network adapters of specific “type”. These value are only
included in a network-adapter-zvm object if the network adapter is of that type. For example, a network
adapter with type rmc will not define an interface-type property.

Other properties are only valid when mutable prerequisite properties have specific values. When such
properties are not valid, their value is null. For instance a network-adapter-zvm's real-device-address
property value is null when the interface-type value is "virtual-iedn".
Table 399. network-adapter-zvm object properties
Name Qualifier Type Description
element-id — String (1-4) Unique ID for the virtual network adapter within the scope of
the containing virtual server. This element-id is actually the
virtual-device-address listed in this table.

This element ID is not immutable. It will be changed if the

virtual-device-address of this object is modified.
element-uri — String/ URI The canonical URI path for the virtual network adapter is of the
form /api/virtual-servers/{virtual-server-id}/network-
adapters/{element-id}, where {virtual-server-id} is the object-id
of the virtual server.

This URI is not immutable because the element-id component of

it can change. See the description for the element-id property.
virtual-device- (w) String (1-4) Virtual device address
address
1-4 character hex string
device-count — Integer The number of device addresses to reserve

Chapter 15. Virtualization management 1057

 Level 04a

Table 399. network-adapter-zvm object properties (continued)

Name Qualifier Type Description
type (ro) String Enum Network adapter type. Values:
v "osx": OSX is a CHPID type. A network adapter that connects
through an OSX CHPID to provide connectivity to a virtual
network of the IEDN (Intra-Ensemble Data Network).
v "osd": OSD is a CHPID type. A network adapter that connects
through an OSD CHPID to provide connectivity to external
network.
v "iqd": IQD is a CHPID type. A network adapter that connects
through an IQD CHPID to provide connectivity to a
HiperSockets network that is not part of the IEDN.
v "iqdx": IQDX is a CHPID type that provides connectivity to
the IEDN HiperSockets network.
v "rmc": Identifies the network adapter is the Remote
Monitoring and Control network adapter.
interface-type (w) String Enum Network adapter switch type. Legal values based on type value.

osx values:
v "none"
v "virtual-iedn": Virtual IEDN switch
v "physical-iedn": Phycsical IEDN switch

osd values:
v "none"
v "virtual-iedn": Virtual IEDN switch
v "virtual-qdio": Virtual QDIO switch
v "physical-qdio": Physical QDIO switch

iqd values:
v "none"
v "physical-iqdn": Physical IQDN switch

iqdx values:
v "none"
v "physical-iedn": Physical IQDX switch
real-device-address (w) String (1-4) The device address that has been assigned to the port on the
switch that the “dedicated” NIC is mapped to.

Prerequisites: interface-type is "physical-iedn", "physical-qdio",

or "physical-iqdn"

1-4 character hex number (range 0-FFFF).

switch-uri (w) String/URI The switch to which the network adapter is connected.

Prerequisites: interface-type is not "none".

v If interface-type is "virtual-iedn" or "virtual-qdio", the value
is the element-uri of the virtual-switch object in use by the
z/VM network adapter.
v If interface-type is "physical-iedn" and type is "osx", the
value is the element-uri of the network-adapter-prsm object
in use by the z/VM network adapter.

1058 HMC Web Services API

 Level 04a

Table 399. network-adapter-zvm object properties (continued)

Name Qualifier Type Description
port-mode (w) String Enum The port mode, or null if the virtual-switch to which the
network adapter was connected no longer exists.

Prerequisites: interface-type is "virtual-iedn" or "virtual-qdio".

If interface-type is "virtual-qdio", the virtual switch identified
by switch-uri must be VLAN aware (its is-vlan-aware property
is true).

Values:
v "trunk": When the switch port is configured in trunk mode, it
will allow the flow of traffic from multiple virtual networks
(i.e. VLANS). The port must be configured with those virtual
networks.
v "access": When the switch port is configured in access mode,
it will support a single virtual network. Traffic from the
virtual server's network adapter will be tagged with the
virtual network configured for this port, and traffic destined
to the virtual server on this port will be verified that it is
tagged with the configured virtual network.
vlan-ids (w) String (0-19) A space-delimited String defining the VLAN IDs.

Prerequisites: interface-type is "virtual-qdio"

Value may contain one of the following:

v zero to four VLAN IDs
v zero to two ranges of VLAN IDs.

A VLAN ID is a decimal integer from 1-4094.

A range is defined by two VLAN IDs separated by a hyphen.

If port-mode is "access" this string must define a single VLAN

ID.

Examples: “”, “0 10”, “0 10 100 2000”, “0-10 2000-2000”, “0-10

1000-2000”
network-uris (w) Arrays of A list of associated Virtual Networks. Each item represents the
String/URI canonical URI path for the associated virtual network.

Prerequisites: interface-type is "virtual-iedn" or "physical-iedn".

List must contain at least one network URI. If port-mode is

"access", list must contain exactly one URI.

The network-adapter-prsm object defines a network adapter of a virtual-server object of type "prsm".
Table 400. network-adapter-prsm object properties
Name Qualifier Type Description
element-id — String Unique ID for the virtual network adapter within the scope of
the containing virtual server.
element-uri — String/URI The canonical URI path for the virtual network adapter is of the
form /api/virtual-servers/{virtual-server-id}/network-
adapters/{element-id}, where {virtual-server-id} is the object-id
of the virtual server.
type — String Enum The physical switch type. Either "osx" or "idqx".

Chapter 15. Virtualization management 1059

 Level 04a

Table 400. network-adapter-prsm object properties (continued)

Name Qualifier Type Description
css — String (1) The channel subsystem ID
chpid — String (2) The channel path ID
network-uris (w) Array of A list including the canonical URI path for each associated
String/ URI virtual network.

Virtual disk objects: A Virtual Disk is virtual storage space provided by a virtualization host to a guest
virtual server. A Virtual Disk is based upon a storage resource, but may be further virtualized by a
Virtualization Host.

Every virtual disk object contains the following base properties in addition to type-specific properties:
Table 401. Virtual disk object properties
Name Qualifier Type Description
element-id — String (36) The unique identifier for the virtual disk instance. This identifier is
in the form of a UUID.
element-uri — String/URI Canonical URI path of the virtual disk object, in the form
/api/virtual-servers/{virtual-server-id}/virtual-disks/
{element-id}, where {virtual-server-id} is the object-id of the
virtual server.
name (w) String (1-64) The name of the virtual disk. It must consist only of alphanumeric
characters, spaces and the following special characters: “._-”, and
it must begin with an alphabetic character.
description (w) String The description for the virtual disk. It must consist only of
(0-1024) alphanumeric characters, spaces and the following special
characters: “._-”.
type — String Enum The type of virtual disk. Values:
v "fullpack" - A virtual disk that is backed by an entire
virtualization host storage resource
v "storage-group-based" - A virtual disk that is backed by
resources allocated from a virtualization host storage group.
This type only applies to virtual disks of a virtual server whose
type property is "zvm".
v "linked" - A virtual disk that is linked to a virtual disk owned
by another virtual server. This type only applies to virtual disks
of a virtual server whose type property is "zvm".
size — Long The size of the virtual disk, in bytes.
owner — String/URI Canonical URI path of the virtual server that owns this virtual
disk.
emulation-mode (w) String Enum The disk I/O emulation mode. Values:
v "virtio" – This virtual disk emulates VIRTIO
v "ide" – This virtual disk emulates IDE
v "virtio-scsi" – This virtual disk emulates VIRTIO-SCSI

Only valid for virtual disks of a virtual server whose type

property is"x-hyp".

A fullpack-virtual-disk object contains information about a fullpack virtual disk of a non-z/VM virtual
server (i.e., the virtual server's type property is not "zvm", and the virtual disk's type property is
"fullpack").

1060 HMC Web Services API

 Level 04a

In addition to base properties, a fullpack-virtual-disk object contains the following properties:

Table 402. fullpack-virtual-disk object properties
Name Qualifier Type Description
backing- (w) String/URI Canonical URI path of the Virtualization Host Storage Resource
virtualization- object that backs this virtual disk.
host-storage-
resource

A fullpack-virtual-disk-zvm object contains information about a z/VM virtual server's fullpack virtual
disk (i.e., the virtual server's type property is "zvm", and the virtual disk's type property is "fullpack").

In addition to base properties, a fullpack-virtual-disk-zvm object contains the following properties:

Table 403. fullpack-virtual-disk-zvm object properties
Name Qualifier Type Description
device-address — String (1-4) The virtual device address. This is the device address by which
the virtual server knows this virtual disk. The string form of a 1-4
digit hexadecimal number.
access-mode (w) String Enum The access mode describing the virtual server's permission to read
and/or write to this virtual disk. The values are defined in
Table 406 on page 1062.
read-password (w) String (0-8) The read password for this virtual disk. Characters must be
uppercase.
write-password (w) String (0-8) The write password for this virtual disk. Characters must be
uppercase.
multi-password (w) String (0-8) The multiple-write password for this virtual disk. Characters must
be uppercase.
backing- — String/URI Canonical URI path of the Virtualization Host Storage Resource
virtualization- object that backs this virtual disk
host-storage-
resource

A storage-group-based-virtual-disk object contains information about a virtual server's

storage-group-based virtual disk (i.e., the virtual disk's type property is "storage-group-based").

In addition to base properties, a storage-group-based-virtual-disk object contains the following properties:

Table 404. storage-group-based-virtual-disk object properties
Name Qualifier Type Description
device-address — String (1-4) The virtual device address. This is the device address by which
the virtual server knows this virtual disk. The string form of a 1-4
digit hexadecimal number.
access-mode (w) String Enum The access mode describing the virtual server's permission to read
and/or write to this virtual disk. The values are defined Table 406
on page 1062.
read-password (w) String (0-8) The read password for this virtual disk. Characters must be
uppercase.
write-password (w) String (0-8) The write password for this virtual disk. Characters must be
uppercase.
multi–password (w) String (0-8) The multiple-write password for this virtual disk. Characters must
be uppercase.

Chapter 15. Virtualization management 1061

 Level 04a

Table 404. storage-group-based-virtual-disk object properties (continued)

Name Qualifier Type Description
backing-storage- — String/URI Canonical URI path of the Virtualization Host Storage Group
group object that backs this virtual disk.

A linked-virtual-disk object contains information about a virtual server's linked virtual disk (i.e., the
virtual disk's type property is "linked").

In addition to base properties, a linked-virtual-disk object contains the following properties:

Table 405. linked-virtual-disk object properties
Name Qualifier Type Description
device-address — String (1-4) The virtual device address. This is the device address by which the
virtual server knows this virtual disk. The string form of a 1-4
digit hexadecimal number.
access-mode (w) String Enum The access mode describing the virtual server's permission to read
and/or write to this virtual disk. The values are defined in
Table 406.
base-virtual-disk — String/URI Canonical URI path of the virtual disk to which this virtual disk is
ultimately linked.
source-virtual- — String/URI Canonical URI path of the virtual disk to which this virtual disk is
disk directly linked.

The possible access modes for a virtual disk of a z/VM virtual server are listed in the following table.
This table is effectively a String enumeration of the valid values for the access-modes property of a
virtual disk object.
Table 406. Valid values for the access-modes property of a virtual disk object
Type Description
String Enum The virtual disk's access mode. These modes correspond exactly to the disk access modes in the
z/VM user directory. Values:
v "read-only"
v "read-write"
v "multi-write"
v "unsupported" – any access mode other than the supported ones listed here. A virtual disk created
by some means other than zManager-provided functions could be created with such an access
mode.

Usage notes for virtual disks:

v For virtual disk objects whose type property is "linked", the “source” virtual disk is always the same
as the “base” virtual disk. The base virtual disk property is provided for the case where a virtual disk
is a link to a virtual disk which is itself a link to some other virtual disk. As such a configuration is not
supported by zManager, base and source will be identical.

Operations
If a virtual server operation accesses a z/VM virtualization host and encounters an error while
communicating with the virtualization host via SMAPI, the response body is a SMAPI Error Response
Body.

1062 HMC Web Services API

 Level 04a

List Virtual Servers of a zBX (Node)

The List Virtual Servers of a zBX (Node) operation lists the virtual servers managed by the zBX node
with the given identifier.

HTTP method and URI

GET /api/zbxs/{zbx-id}/virtual-servers

In this request, the URI variable {zbx-id} is the object ID of the zBX node object.

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
Enum matching type property.

Value must be a valid virtual server type property value.

Response body contents

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

Field name Type Description

virtual-servers Array of Array of virtual-server-info objects, described in the next table. Returned
objects array may be empty.

Each nested virtual-server-info object contains the following fields:

Field name Type Description

object-uri String/ The canonical URI path of the Virtual Server object
URI
name String The name property of the Virtual Server object
type String The type property of the Virtual Server object
Enum
status String The status property of the Virtual Server object
Enum

Description
This operation lists the virtual servers that are managed by the identified zBX node. The object-uri,
name, type, and status are provided for each.

If the object-id {zbx-id} does not identify a zBX object to which the API user has object-access permission,
or if the zBX is not a member of an ensemble, a 404 status code is returned.

If the name query parameter is specified, the returned list is limited to those virtual servers that have a
name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
done.

If the type query parameter is specified, the parameter is validated to ensure it is a valid virtual server
type property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid, the

Chapter 15. Virtualization management 1063

 Level 04a

returned list is limited to those virtual servers that have a type property matching the specified value. If
the type parameter is omitted, this filtering is not done.

The zBX specified by {zbx-id} must be a zBX node (that is, have a type of "node"), otherwise status code
400 (Bad Request) is returned.

A virtual server is included in the list only if the API user has object-access permission for that object. If
an HMC is a manager of a virtual server but the API user does not have permission to it, that object is
simply omitted from the list but no error status code results.

If the zBX node does not manage any virtual servers or if no virtual servers are to be included in the
results due to filtering, 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 zBX node whose object ID is {zbx-id}
v Object-access permission to each Virtual Server 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 1063.

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.
105 A type query parameter defines an invalid value.
112 The request URI designates a zBX object that is not a zBX node (that is, does
not have a type of "node").
404 (Not Found) 1 A zBX with object ID {zbx-id} does not exist on HMC or API user does not
have object-access permission for it.
100 The zBX with object ID {zbx-id} is not a member of an ensemble.
409 (Conflict) 244 The operation cannot be performed because the zBX node designated by the
request URI is an unmanaged zBX node, 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/zbxs/8dac6a58-935e-352c-996e-ded17dbf92c0/virtual-servers HTTP/1.1

x-api-session: 579shzuc4ca3lwnly7xk2s64w6qmwy2v2zsikdrn4ky9sn9vv1

Figure 559. List Virtual Servers of a zBX (Node): Request

1064 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 2.0
date: Mon, 09 Feb 2015 19:24:36 GMT
content-type: application/json;charset=UTF-8
content-length: 447
{
"virtual-servers": [
{
"name": "B.2.03_SERVER_1",
"object-uri": "/api/virtual-servers/bde7c552-a890-11e4-91e1-42f2e9106e93",
"status": "operating",
"type": "x-hyp"
},
{
"name": "B.1.01_SERVER_2",
"object-uri": "/api/virtual-servers/97cec09e-ae3c-11e4-a8fe-42f2e9106e93",
"status": "operating",
"type": "power-vm"
}
]
}

Figure 560. List Virtual Servers of a zBX (Node): Response

List Virtual Servers of a Node

The List Virtual Servers of a Node operation lists the virtual servers managed by the node with the
given identifier.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/nodes/{node-id}/virtual-servers

URI variables:

Name Description
{ensemble-id} The object ID of the Ensemble object
{node-id} The object ID of the Node object

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
Enum matching type property.

Value must be a valid virtual server type property value.

Chapter 15. Virtualization management 1065

 Level 04a

Response body contents

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

Field name Type Description

virtual-servers Array of Array of nested virtual-server-info objects, described in the next table.
objects

Each nested virtual-server-info object contains the following fields:

Field name Type Description

object-uri String/ The canonical URI path of the Virtual Server object
URI
name String The name property of the Virtual Server object
type String The type property of the Virtual Server object
Enum
status String The status property of the Virtual Server object
Enum

Description
This operation lists the virtual servers that are managed by the identified Node. The object-uri, name,
type, and status are provided for each.

If the object ID {node-id} does not identify a Node object to which the API user has object-access
permission or if the node is not a member of an ensemble, a 404 status code is returned.

If the name query parameter is specified, the returned list is limited to those virtual servers that have a
name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
done.

If the type query parameter is specified, the parameter is validated to ensure it is a valid virtual server
type property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid, the
returned list is limited to those virtual servers that have a type property matching the specified value. If
the type parameter is omitted, this filtering is not done.

A virtual server is included in the list only if the API user has object-access permission for that object. If
an HMC is a manager of a virtual server but the API user does not have permission to it, that object is
simply omitted from the list but no error status code results.

If the Node does not manage any virtual servers or if no virtual servers are to be included in the results
due to filtering, 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 node whose object ID is {node-id}
v Object-access permission to each Virtual Server 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.”

1066 HMC Web Services API

 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.
105 A type query parameter defines an invalid value.
404 (Not Found) 1 A node with object ID {node-id} does not exist on HMC or API user does not
have object-access permission for it.
100 The node with object ID{node-id} is not a member of an ensemble.

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/ensembles/de7915f4-a127-11e2-8273-5cf3fcae8019/nodes/
8dac6a58-935e-352c-996e-ded17dbf92c0/virtual-servers HTTP/1.1
x-api-session: 579shzuc4ca3lwnly7xk2s64w6qmwy2v2zsikdrn4ky9sn9vv1

Figure 561. List Virtual Servers of a Node: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 09 Feb 2015 19:24:33 GMT
content-type: application/json;charset=UTF-8
content-length: 447
{
"virtual-servers": [
{
"name": "B.2.03_SERVER_1",
"object-uri": "/api/virtual-servers/bde7c552-a890-11e4-91e1-42f2e9106e93",
"status": "operating",
"type": "x-hyp"
},
{
"name": "B.1.01_SERVER_2",
"object-uri": "/api/virtual-servers/97cec09e-ae3c-11e4-a8fe-42f2e9106e93",
"status": "operating",
"type": "power-vm"
}
]
}

Figure 562. List Virtual Servers of a Node: Response

List Virtual Servers of an Ensemble

The List Virtual Servers of an Ensemble operation lists the virtual servers managed by the ensemble
with the given identifier.

Chapter 15. Virtualization management 1067

 Level 04a

HTTP method and URI

GET /api/ensembles/{ensemble-id}/virtual-servers

In this request, the URI variable {ensemble-id} is the object ID of the Ensemble object.

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
Enum matching type property.

Value must be a valid virtual server type property value.

Response body contents

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

Field name Type Description

virtual-servers Array of Array of virtual-server-info objects, described in the next table. Returned
objects array may be empty.

Each nested virtual-server-info object contains the following fields:

Field name Type Description

object-uri String/ The canonical URI path of the Virtual Server object
URI
name String The name property of the Virtual Server object
type String The type property of the Virtual Server object
Enum
status String The status property of the Virtual Server object
Enum

Description
This operation lists the virtual servers that are managed by the identified ensemble. The object-uri,
object-id, name, type, and status are provided for each.

If the object-id {ensemble-id} does not identify an ensemble object to which the API user has object-access
permission, a 404 status code is returned.

If the name query parameter is specified, the returned list is limited to those virtual servers that have a
name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
done.

If the type query parameter is specified, the parameter is validated to ensure it is a valid virtual server
type property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid, the
returned list is limited to those virtual servers that have a type property matching the specified value. If
the type parameter is omitted, this filtering is not done.

1068 HMC Web Services API

 Level 04a

A virtual server is included in the list only if the API user has object-access permission for that object. If
an HMC is a manager of a virtual server but the API user does not have permission to it, that object is
simply omitted from the list but no error status code results.

If the ensemble does not manage any virtual servers or if no virtual servers are to be included in the
results due to filtering, 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 ensemble whose object-id is {ensemble-id}
v Object-access permission to each Virtual Server 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 1068.

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.
105 A type query parameter defines an invalid value.
404 (Not Found) 1 An ensemble with object-id {ensemble-id} does not exist on HMC or API user
does not have object-access permission for 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/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334/virtual-servers HTTP/1.1

x-api-session: 64zdknfzh24fqw8f9v5g99h96rhrxhodmawtknx4iutmgqrfvf

Figure 563. List Virtual Servers of an Ensemble: Request

Chapter 15. Virtualization management 1069

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Sat, 12 Nov 2011 21:09:23 GMT
content-type: application/json;charset=UTF-8
content-length: 1008
{
"virtual-servers": [
{
"name": "APIVM2",
"object-uri": "/api/virtual-servers/63911688-03f4-11e1-881f-001f163805d8",
"status": "operating",
"type": "prsm"
},
{
"name": "SS-Web-Svr-1",
"object-uri": "/api/virtual-servers/7ba96572-0d72-11e1-892f-f0def14b63af",
"status": "not-operating",
"type": "x-hyp"
},
{
"name": "SSWSVR3",
"object-uri": "/api/virtual-servers/86819708-0d72-11e1-bf89-f0def14b63af",
"status": "not-activated",
"type": "zvm"
},
{
"name": "ZOS",
"object-uri": "/api/virtual-servers/636768f6-03f4-11e1-881f-001f163805d8",
"status": "operating",
"type": "prsm"
},
{
"name": "SS-web-Srv-2",
"object-uri": "/api/virtual-servers/960529e2-0d3b-11e1-9f64-f0def14b63af",
"status": "operating",
"type": "power-vm"
}
]
}

Figure 564. List Virtual Servers of an Ensemble: Response

List Virtual Servers of a CPC

The List Virtual Servers of a CPC operation lists the virtual servers managed by the CPC with the given
identifier.

HTTP method and URI

GET /api/cpcs/{cpc-id}/virtual-servers

In this request, the URI variable {cpc-id} is the object ID of the CPC object.

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.

1070 HMC Web Services API

 Level 04a

Name Type Rqd/Opt Description

type String Optional Filter string to limit returned objects to those that have a
Enum matching type property.

Value must be a valid virtual server type property value.

Response body contents

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

Field name Type Description

virtual-servers Array of Array of nested virtual-server-info objects, described in the next table.
objects

Each nested virtual-server-info object contains the following fields:

Field name Type Description

object-uri String/ The canonical URI path of the Virtual Server object
URI
name String The name property of the Virtual Server object
type String The type property of the Virtual Server object
Enum
status String The status property of the Virtual Server object
Enum

Description
This operation lists the virtual servers that are managed by the identified CPC. The object-uri, name,
type, and status are provided for each.

If the object-id {cpc-id} does not identify a CPC object to which the API user has object-access permission
or if the CPC is not a member of an ensemble, a 404 status code is returned.

If the name query parameter is specified, the returned list is limited to those virtual servers that have a
name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
done.

If the type query parameter is specified, the parameter is validated to ensure it is a valid virtual server
type property value. If the value is not valid, a 400 (Bad Request) is returned. If the value is valid, the
returned list is limited to those virtual servers that have a type property matching the specified value. If
the type parameter is omitted, this filtering is not done.

A virtual server is included in the list only if the API user has object-access permission for that object. If
an HMC is a manager of a virtual server but the API user does not have permission to it, that object is
simply omitted from the list but no error status code results.

If the CPC does not manage any virtual servers or if no virtual servers are to be included in the results
due to filtering, an empty list is provided and the operation completes successfully.

Chapter 15. Virtualization management 1071

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the cpc whose object ID is {cpc-id}
v Object-access permission to each Virtual Server 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 1071.

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.
105 A type query parameter defines an invalid value.
404 (Not Found) 1 A CPC with object-id {cpc-id} does not exist on the HMC or API user does
not have object-access permission for it.
100 The CPC with object-id {cpc-id} is not a member of an ensemble.
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/37c6f8a9-8d5e-3e5d-8466-be79e49dd340/virtual-servers HTTP/1.1

x-api-session: 64zdknfzh24fqw8f9v5g99h96rhrxhodmawtknx4iutmgqrfvf

Figure 565. List Virtual Servers of a CPC: Request

1072 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Sat, 12 Nov 2011 21:09:23 GMT
content-type: application/json;charset=UTF-8
content-length: 423
{
"virtual-servers": [
{
"name": "ZOS",
"object-uri": "/api/virtual-servers/636768f6-03f4-11e1-881f-001f163805d8",
"status": "operating",
"type": "prsm"
},
{
"name": "SS-web-Srv-2",
"object-uri": "/api/virtual-servers/960529e2-0d3b-11e1-9f64-f0def14b63af",
"status": "operating",
"type": "power-vm"
}
]
}

Figure 566. List Virtual Servers of a CPC: Response

List Virtual Servers of a Virtualization Host

The List Virtual Servers of a Virtualization Host operation lists the virtual servers managed by the
virtualization host with the given identifier.

HTTP method and URI

GET /api/virtualization-hosts/{virt-host-id}/virtual-servers

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host object.

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.

Response body contents

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

Field name Type Description

virtual-servers Array of Array of nested virtual-server-info objects, described in the next table.
objects

Each nested virtual-server-info object contains the following fields:

Field name Type Description

object-uri String/ The object-uri property of the Virtual Server object.
URI

Chapter 15. Virtualization management 1073

 Level 04a

Field name Type Description

name String The name property of the Virtual Server object
type String The type property of the Virtual Server object
Enum
status String The status property of the Virtual Server object
Enum

Description
This operation lists the virtual servers that are managed by the identified virtualization host. The
object-uri, name, type, and status are provided for each.

If the object-id {virt-host-id} does not identify a Virtualization Host object for which the API user has
object-access permission to its hosting-environment, a 404 status code is returned.

If the name query parameter is specified, the returned list is limited to those virtual servers that have a
name property matching the specified filter pattern. If the name parameter is omitted, this filtering is not
done.

A virtual server is included in the list only if the API user has object-access permission for that object. If
an HMC is a manager of a virtual server but the API user does not have permission to it, that object is
simply omitted from the list but no error status code results.

If the virtualization host does not manage any virtual servers or if no virtual servers are to be included in
the results due to filtering, an empty list is provided and the operation completes successfully.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to hosting-environment of the virtualization host with object-id {virt-host-id}
v Object-access permission to each Virtual Server 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 1073.

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 A Virtualization Host with object-id {virt-host-id} does not exist on HMC or
API user does not have object-access permission for its hosting-environment.
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.

1074 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/virtualization-hosts/71822c16-0401-11e1-8eda-001f163805d8/virtual-servers HTTP/1.1

x-api-session: 64zdknfzh24fqw8f9v5g99h96rhrxhodmawtknx4iutmgqrfvf

Figure 567. List Virtual Servers of a Virtualization Host: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Sat, 12 Nov 2011 21:08:38 GMT
content-type: application/json;charset=UTF-8
content-length: 434
{
"virtual-servers": [
{
"name": "SS-Web-Svr-1",
"object-uri": "/api/virtual-servers/7ba96572-0d72-11e1-892f-f0def14b63af",
"status": "operating",
"type": "x-hyp"
},
{
"name": "SS-FTP-Svr-1",
"object-uri": "/api/virtual-servers/5483e6b2-09fc-11e1-9f08-001f163805d8",
"status": "not-operating",
"type": "x-hyp"
}
]
}

Figure 568. List Virtual Servers of a Virtualization Host: Response

Create Virtual Server

The Create Virtual Server operation creates a "power-vm", "x-hyp", or "zvm" virtual server with the
given properties on the identified Virtualization Host. This operation is not supported for "prsm"
Virtualization Hosts/virtual servers.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/virtual-servers

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host object.

Request body contents

Properties are only valid if they are supported for a virtual server whose type property matches the given
type property value. For instance a virtual server with type "power-vm" will define a processing-mode
property (PowerVM only) and mac-prefix property (PowerVM, z/VM) but not an initial-share-mode
property (z/VM only).

Properties may also only be valid if prerequisite properties have specific values. For example, a PowerVM
virtual server's initial-virtual-processors is only valid when the processing-mode value is "shared".

See the “Data model” on page 1037 for a complete definition of all properties including for what virtual
server types they are valid and their prerequisites.

Chapter 15. Virtualization management 1075

 Level 04a

Field name Type Rqd/Opt Description

type String Required The value to be set as the virtual server's type property. The value
Enum may not be "prsm".
name String Required The value to be set as the virtual server's name property.
description String Optional The value to be set as the virtual server's description property.
Default value: an empty string
cpu-perf-mgmt- Boolean Optional The value to be set as the virtual server's cpu-perf-mgmt-enabled
enabled property. Default value: true. Valid only when the ensemble's
management-enablement-level is "automate".
processing-mode String Optional The value to be set as the virtual server's processing-mode property.
Enum Default value: shared
minimum-virtual- Integer Optional The value to be set as the virtual server's minimum-virtual-
processors processors property. Default value: 1
initial-virtual- Integer Optional The value to be set as the virtual server's initial-virtual-processors
processors property. Default value: 1
maximum-virtual- Integer Optional The value to be set as the virtual server's maximum-virtual-
processors processors property. Default value based on type:
v power-vm: max (maximum-allowed-dedicated-processors,
initial-virtual-processors)
v zvm: 1
minimum-dedicated- Integer Optional The value to be set as the virtual server's minimum-dedicated-
processors processors property. Default value: 1
initial-dedicated- Integer Optional The value to be set as the virtual server's initial-dedicated-
processors processors property. Default value: 1
maximum-dedicated- Integer Optional The value to be set as the virtual server's maximum-dedicated-
processors processors property. Default value: maximum-allowed-dedicated-
processors
minimum-processing- Float Optional The value to be set as the virtual server's minimum-processing-
units units property. Default value: 0.1
initial-processing- Float Optional The value to be set as the virtual server's initial-processing-units
units property. Default value: 0.1
maximum-processing- Float Optional The value to be set as the virtual server's maximum-processing-
units units property. Default value: min (maximum-virtual-processors,
maximum-allowed-processing-units)
initial-share-mode String Optional The value to be set as the virtual server's initial-share-mode
Enum property. Default value: "relative"
initial-shares Float Optional The value to be set as the virtual server's initial-shares property.

For x Hyp virtual servers:

v Default: 1024
v Prerequisite: The parent virtualization host's cpu-shares-
supported value is true.

For z/VM servers:

v Default: Based on initial-share-mode:
– relative: 100
– absolute: 10.0
share-limit String Optional The value to be set as the virtual server's share-limit property.
Enum Default value: "none"
maximum-share-mode String Optional The value to be set as the virtual server's maximum-share-mode
Enum property. Default value: "relative"

1076 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

minimum-shares Float Optional The value to be set as the virtual server's minimum-shares property.

Default value: 2
maximum-shares Float Optional The value to be set as the virtual server's maximum-shares property.

Default value for x Hyp virtual servers: 262144.

Default value for z/VM virtual servers is based on

maximum-share-mode:
v relative: 100
v absolute: 10.0
minimum-memory Integer Optional The value to be set as the virtual server's minimum-memory
property. Default value: max (256, initial-memory)
initial-memory Integer Optional The value to be set as the virtual server's initial-memory property.
Default value: 1024
maximum-memory Integer Optional The value to be set as the virtual server's maximum-memory
property. Default value: initial-memory
boot-mode String Optional The value to be set as the virtual server's boot-mode property.
Enum Default: normal
book-network- String Optional The value to be set as the virtual server's boot-network-adapter-
adapter-client-ip client-ip property. Default value: an empty string
boot-network- String Optional The value to be set as the virtual server's boot-network-adapter-
adapter-subnet-ip subnet-ip property. Default value: an empty string
boot-network- String Optional The value to be set as the virtual server's boot-network-adapter-
adapter-gateway-ip gateway-ip property. Default value: an empty string
boot-network- String Optional The value to be set as the virtual server's boot-network-adapter-
adapter-server-ip server-ip property. Default value: an empty string
keylock String Optional The value to be set as the virtual server's keylock property. Default
Enum value: "normal"
auto-start Boolean Optional The value to be set as the virtual server's auto-start property.
Default value: false. Prerequisite: type is "power-vm" or "x-hyp".
dlpar-enabled Boolean Optional The value to be set as the virtual server's dlpar-enabled property.
Default value: false
gpmp-support- Boolean Optional The value to be set as the virtual server's gpmp-support-enabled
enabled property. Default value: false. Prerequisite: type is "power-vm",
"zvm" or "x-hyp".
rmc-virtual-device- String Optional The virtual device address of the resource monitoring and control
address network to create in order to support the Guest Platform
Management Provider (GPMP).

Prerequisite: type is "zvm" and gpmp-support-enabled is true.

Required if gpmp-support-enabled is true.

1-4 character hex string

password String Required The value to be set as the virtual server's password property.
if type is Prerequisite: type is "zvm"
"zvm"
privilege-classes String Optional The value to be set as the virtual server's privilege-classes property.
Default value “G”
ipl-device String Optional The value to be set as the virtual server's ipl-device property.
Default value “CMS”

Chapter 15. Virtualization management 1077

 Level 04a

Field name Type Rqd/Opt Description

ipl-load–parameters String Optional The value to be set as the virtual server's ipl-load-parameters
property. Default value: an empty string
ipl-parameters String Optional The value to be set as the virtual server's ipl-parameters property.
Default value “AUTOCR”.
inband-monitoring- Boolean Optional The value to be set as the virtual server's inband-monitoring-
enabled enabled property. Default value: false
keyboard-language String Optional The value to be set as the virtual server's keyboard-language
property. Default value: the first value in the virtualization host's
supported-keyboard-languages array or null if that array is null or
empty.
shutdown-timeout- String Optional The value to be set as the virtual server's shutdown-timeout-source
source Enum property. Default value: “virtualization-host”.

Prerequisite: type is "power-vm"or "x-hyp"

shutdown-timeout Integer Optional The value to be set as the virtual server's shutdown-timeout
property. Default value: 300

Prerequisite: type is "power-vm"or "x-hyp"

Response body contents

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

Field name Type Description

object-uri String/ The object-uri property of the created Virtual Server object.
URI

Description
This operation creates a virtual server with the values specified on the identified Virtualization Host and
then returns its object-uri in the response body. The response also includes a Location header that
provides this URI.

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 API user does not have authority to perform the Create Virtual Server task or the zManager
management enablement level for the ensemble does not allow the setting of a provided property, a 403
(Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object-id {virt-host-id}
does not identify a Virtualization Host object for which the API user has object-access permission to its
hosting-environment. If the Virtualization Host is of type "zvm" and its status is not-activated, a 409
(Conflict) status code is returned.

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 or defines a property that is not supported for
the given virtual server type. This may also occur if the document fails to define a single valid virtual
server, for instance defining a property with an invalid value (e.g. an initial-memory value less than zero
or a virtual server type of "zvm" when the Virtualization Host type is "power-vm"). A 400 (Bad Request)
will also be returned if the request body contains a property that is not valid given the value of a
prerequisite property (e.g. defining a value for initial-dedicated-memory when the value of
processing-mode is "shared").

1078 HMC Web Services API

 Level 04a

If the request body contents are valid, the virtual server is created on the target Virtualization Host 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 virtual server. The newly
created virtual server will have empty list values defined for its storage-adapters. For PowerVM and x
Hyp virtual servers, the network-adapters property will contain the definition of the network-adapter for
the Default network and it will have a boot-sequence array that contains only "network-adapter". For
z/VM virtual servers, the network-adapters property value will be an empty list. The virtual server will
also be a member of the default workload resource group.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Virtualization Host's hosting-environment
v Action/task permission to Create Virtual Server task.
v Action/task permission to the Virtual Server Performance Details task if the gpmp-support-enabled
or cpu-perf-mgmt-enabled field is specified in the request body.

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 1078.

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.
101 A virtual server with the name specified in the request body already exists
on the Virtualization Host with object-id {virt-host-id}.
102 The object-id {virt-host-id} identifies a Virtualization Host whose type
property value differs from the type defined in the request body.
103 A “shares” (initial-shares or maximum-shares) property value type is not
correct based on the value of its corresponding “share-mode”
(initial-share-mode or maximum-share-mode). For example, the
initial-share-mode is defined as "relative" but the initial-shares value is not
an Integer.
403 (Forbidden) 1 API user does not have action permission to the Create Virtual Server task.
100 The ensemble's management-enablement-level property value does not
allow the updating of a provided property.
404 (Not Found) 1 A Virtualization Host with object-id {virt-host-id} does not exist on HMC or
API user does not have object-access permission for its hosting-environment.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
101 Parent Virtualization Host has a status value that is not valid to perform the
operation (attempted to create a virtual server of type "zvm" and
Virtualization Host is not active).

Chapter 15. Virtualization management 1079

 Level 04a

HTTP error status Reason

code code Description
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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/virtualization-hosts/2f7bf364-03f8-11e1-8eda-001f163805d8/virtual-servers HTTP/1.1

x-api-session: 64zdknfzh24fqw8f9v5g99h96rhrxhodmawtknx4iutmgqrfvf
content-type: application/json
content-length: 161
{
"description": "Spacely Sprockets Web Store Web Server #2",
"initial-memory": 2048,
"initial-virtual-processors": 2,
"name": "SS-Web-Svr-2",
"type": "power-vm"
}

Figure 569. Create Virtual Server: Request for a virtual server of type "power-vm"

201 Created
server: zSeries management console API web server / 1.0
location: /api/virtual-servers/7d298eb8-0d72-11e1-8c83-f0def14b63af
cache-control: no-cache
date: Sat, 12 Nov 2011 21:08:41 GMT
content-type: application/json;charset=UTF-8
content-length: 74
{
"object-uri": "/api/virtual-servers/7d298eb8-0d72-11e1-8c83-f0def14b63af"
}

Figure 570. Create Virtual Server: Response for a virtual server of type "power-vm"

Delete Virtual Server

The Delete Virtual Server operation deletes the identified virtual server. This operation is not supported
for PR/SM virtual servers.

HTTP method and URI

DELETE /api/virtual-servers/{virtual-server-id}

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

1080 HMC Web Services API

 Level 04a

Description
A 409 (Conflict) status code is returned if the virtual server has a status other than "not-operating" or
"not-activated". A 409 (Conflict) status code is also returned if the virtual server is busy for the duration
of the request.

This operation deletes the identified virtual server, which includes the following:
v The virtual server's network adapters are disconnected and deleted.
v The virtual server's virtual disks are removed from the virtual server.
v Virtual servers of type "zvm" are also removed from the z/VM Directory.
v The virtual server is removed from the Virtualization Host.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server
v Object-access permission to the virtual server's Virtualization Host's hosting-environment.
v Action/task permission to Delete Virtual Server 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, 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
403 (Forbidden) 1 API user does not have action permission to the Delete Virtual Server task.
404 (Not Found) 1 A virtual server with object-id {virtual-server-id} does not exist on HMC or
API user does not have object-access permission for it or its virtualization
host’s hosting-environment.
409 (Conflict) 1 Virtual server status is not valid to perform the operation (must be either
"not-operating" or "not-activated").
2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other 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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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

Chapter 15. Virtualization management 1081

 Level 04a

Example HTTP interaction

DELETE /api/virtual-servers/7ba96572-0d72-11e1-892f-f0def14b63af HTTP/1.1

x-api-session: 64zdknfzh24fqw8f9v5g99h96rhrxhodmawtknx4iutmgqrfvf

Figure 571. Delete Virtual Server: Request

204 No Content
date: Sat, 12 Nov 2011 21:09:24 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 572. Delete Virtual Server: Response

Get Virtual Server Properties

The Get Virtual Server Properties operation retrieves the properties of a single Virtual Server object that
is designated by its object-id.

HTTP method and URI

GET /api/virtual-servers/{virtual-server-id}

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Query parameters

Name Type Req/Opt Description

properties String Optional Identifies the properties to be returned for the Virtual Server object.
The only supported value is "common", which indicates that only a
specific subset of properties that are quickly available and common
to all types of virtual server should be returned. This properties
included in this subset is specified in “Response body contents.” If
this query parameter is omitted, then all properties for the virtual
server as defined in “Data model” on page 1037 are returned.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Virtual Server object.

If the properties query parameter is not specified, the response body provides all of the properties for the
virtual server as defined in the data model section above. Field names and data types in the JSON object
are the same as the property names and data types defined in the data model.

If the properties=common query parameter is specified, the response body provides the values for only
the following properties: acceptable-status, auto-start, class, description, has-unacceptable-status,
hostname, is-locked, name, object-id, object-uri, os-level, os-name, os-type, parent, status, type, and
workloads. Field names and data types in the JSON object are the same as the property names and data
types defined in the data model. These properties are common to all types of virtual servers, and can be
provided more quickly than the entire set of properties for the virtual server.

1082 HMC Web Services API

 Level 04a

Description
Returns the current values of the properties for the Virtual Server object as defined in the “Data model”
on page 1037.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Virtual Server object designated by {virtual-server-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” on page 1082.

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 A Virtualization Host with object-id {virtual-server-id} does not exist on HMC
or API user does not have object-access permission for it.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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

Usage notes
Retrieval of the full property set for a virtual server will generally require an interaction with the SE, and
in some cases (for example, for z/VM virtual servers) may also require an interaction with the
virtualization host. Some API applications may choose to represent virtual servers in a generic, rather
than highly type-specialized, way and thus not need the full set of properties for each virtual server. The
properties=common query parameter is provided to allow for improved performance for such
applications by avoiding the processing that would be incurred in retrieving unneeded properties. The
properties specified by properties=common are available for all virtual server types, and are generally
cached on the HMC so that they can be retrieved quickly and without requiring an interaction with the
SE or virtualization host.

Chapter 15. Virtualization management 1083

 Level 04a

Example HTTP interaction

GET /api/virtual-servers/7ba96572-0d72-11e1-892f-f0def14b63af HTTP/1.1

x-api-session: 64zdknfzh24fqw8f9v5g99h96rhrxhodmawtknx4iutmgqrfvf

Figure 573. Get Virtual Server Properties: Request

1084 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2011 17:11:03 GMT
content-type: application/json;charset=UTF-8
content-length: 3175
{
"acceptable-status": [
"operating"
],
"auto-start": false,
"boot-mode": "normal",
"boot-network-adapter-client-ip": "192.168.1.22",
"boot-network-adapter-gateway-ip": "192.168.1.1",
"boot-network-adapter-server-ip": "192.168.1.254",
"boot-network-adapter-subnet-ip": "255.255.255.0",
"boot-sequence": [
"network-adapter"
],
"class": "virtual-server",
"cpu-perf-mgmt-enabled": true,
"description": "Spacely Sprockets Web Store Web Server #2",
"dlpar-active": false,
"dlpar-enabled": false,
"gpmp-network-adapter":
{
"adapter-type": "gpmp"
"element-id": "a3cbdcea-0fac-11e1-902b-f0def14b63af",
"element-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/
network-adapters/a3cbbdcea-0fac-11e1-902b-f0def14b63af",
"mac-address": "02:ff:a6:b3:3c:c6",
"network-uri": null
}
"gpmp-status": "not-operating",
"gpmp-support-enabled": false,
"gpmp-version": "unavailable",
"has-unacceptable-status": true,
"hostname": null,
"inband-monitoring-enabled": false,
"initial-dedicated-processors": null,
"initial-memory": 2048,
"initial-processing-units": 0.20000000000000001,
"initial-virtual-processors": 2,
"is-locked": false,
"keylock": "normal",
"mac-prefix": {
"mac-address": "02:d0:19:aa:76:00",
"prefix-length": 40
},
"maximum-dedicated-processors": null,
"maximum-memory": 2048,
"maximum-processing-units": 7.0,
"maximum-virtual-processors": 7,
"minimum-dedicated-processors": null,
"minimum-memory": 2048,
"minimum-processing-units": 0.10000000000000001,
"minimum-virtual-processors": 1,
"mounted-media-name": "gpa.iso",
"name": "SS-Web-Svr-2",

Figure 574. Get Virtual Server Properties: Response for virtual servers of "power-vm" (Part 1)

Chapter 15. Virtualization management 1085

 Level 04a

"network-adapters": [
{
"adapter-type": "regular"
"element-id": "596dd87c-0db7-11e1-9251-f0def14b63af",
"element-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/
network-adapters/596dd87c-0db7-11e1-9251-f0def14b63af",
"mac-address": null,
"network-uri": "/api/virtual-networks/f920171e-03f2-11e1-8e8e-0010184c8334"
},
{
"adapter-type": "regular"
"element-id": "c4bbdcea-0fac-11e1-903e-f0def14b63af",
"element-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/
network-adapters/c4bbdcea-0fac-11e1-903e-f0def14b63af",
"mac-address": null,
"network-uri": "/api/virtual-networks/f3aece54-0db8-11e1-9e2c-00215e69dea0"
}
],
"object-id": "588d8c18-0db7-11e1-b1f1-f0def14b63af",
"object-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af",
"os-level": null,
"os-name": null,
"os-type": null,
"parent": "/api/virtualization-hosts/2f7bf364-03f8-11e1-8eda-001f163805d8",
"processing-mode": "shared",
"status": "not-operating",
"type": "power-vm",
"virtual-disks": [
{
"backing-virtualization-host-storage-resource": "/api/virtualization-hosts/
2f7bf364-03f8-11e1-8eda-001f163805d8/virtualization-host-storage-resources/
37699380-0fa9-11e1-b69e-f0def14b63af",
"description": "Boot filesystem",
"element-id": "c547fb4e-0fac-11e1-842b-f0def14b63af",
"element-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/
virtual-disks/c547fb4e-0fac-11e1-842b-f0def14b63af",
"name": "boot",
"owner": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af",
"size": 17179869184,
"type": "fullpack"
},
{
"backing-virtualization-host-storage-resource": "/api/virtualization-hosts/
2f7bf364-03f8-11e1-8eda-001f163805d8/virtualization-host-storage-resources/
b0e6c160-0fa9-11e1-b69e-f0def14b63af",
"description": "Pysical vol for sysvg",
"element-id": "c568a13c-0fac-11e1-903e-f0def14b63af",
"element-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/
virtual-disks/c568a13c-0fac-11e1-903e-f0def14b63af",
"name": "pv01a",
"owner": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af",
"size": 8589934592,
"type": "fullpack"
}
],
"workloads": [
"/api/workload-resource-groups/f9fbe5fa-03f2-11e1-8e8e-0010184c8334"
]
}

Figure 575. Get Virtual Server Properties: Response for virtual servers of "power-vm" (part 2)

1086 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2011 18:23:31 GMT
content-type: application/json;charset=UTF-8
content-length: 1121
{
"acceptable-status": [
"operating"
],
"associated-logical-partition": "/api/logical-partitions/8394537b-1cc3-3607-88ad-06845b263439",
"class": "virtual-server",
"cpu-perf-mgmt-enabled": false,
"description": "",
"gpmp-status": "not-operating",
"gpmp-support-enabled": false,
"gpmp-version": "unavailable",
"has-unacceptable-status": true,
"is-locked": false,
"name": "LP03 ",
"network-adapters": [
{
"chpid": "42",
"css": "0",
"element-id": "OSX 0.42",
"element-uri": "/api/virtual-servers/916f73c8-de39-11e0-a58e-f0def161133a/
network-adapters/OSX%200.42",
"network-uris": null,
"type": "osx"
},
{
"chpid": "43",
"css": "0",
"element-id": "OSX 0.43",
"element-uri": "/api/virtual-servers/916f73c8-de39-11e0-a58e-f0def161133a/
network-adapters/OSX%200.43",
"network-uris": null,
"type": "osx"
}
],
"object-id": "916f73c8-de39-11e0-a58e-f0def161133a",
"object-uri": "/api/virtual-servers/916f73c8-de39-11e0-a58e-f0def161133a",
"os-level": "6.2.0 - 1101",
"os-name": "LP03",
"os-type": "z/VM",
"parent": "/api/virtualization-hosts/8e9cad8c-de39-11e0-a58e-f0def161133a",
"status": "operating",
"type": "prsm",
"workloads": [
"/api/workload-resource-groups/1fe39a72-de39-11e0-90a6-00215e67351a"
]
}

Figure 576. Get Virtual Server Properties: Response for virtual servers of type "prsm"

Chapter 15. Virtualization management 1087

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2014 16:56:19 GMT
’content-type’: ’application/json’
{
"os-name":null,
"shutdown-timeout-source":"virtualization-host",
"shutdown-timeout":300,
"boot-sequence":[
"virtual-media",
"virtual-disk",
"network-adapter"
],
"gpmp-status":"not-operating",
"avail-policies":[
{
"avail-status-impact-exclusion":false,
"policy-uri":"/api/workload-resource-groups/a40e2b96-9adb-11e1-8868-00215e67ad51/availability-policies/
d0b6fecc-191e-11e2-8561-00215e67ad51",
"workload-uri":"/api/workload-resource-groups/a40e2b96-9adb-11e1-8868-00215e67ad51"
}
],
"hostname":null,
"keyboard-language":"en_US",
"auto-start":false,
"os-type":null,
"avail-status":[
{
"reasons":[
"vs"
],
"avail-status":"not-available"
}
],
"gpmp-network-adapter":
{
"adapter-type": "gpmp"
"element-id": "a3cbdcea-0fac-11e1-902b-f0def14b63af",
"element-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/
network-adapters/a3cbbdcea-0fac-11e1-902b-f0def14b63af",
"emulation-mode":"e1000"
"mac-address": "02:ff:a6:b3:3c:c6",
"network-uri": null
}
"gpmp-version":"unavailable",
"is-locked":false,
"type":"x-hyp",
"status":"not-operating",
"maximum-shares":262144,
"mounted-media-name":null,
"description":"",
"parent":"/api/virtualization-hosts/6c54bdcc-0b3d-11e3-b37e-f0def1b30158",
"os-level":null,
"object-id":"f6755c24-a457-11e3-8a23-f0def1b30158",
"network-adapters":[
{

Figure 577. Get Virtual Server Properties: Response for virtual servers of type "x-hyp" (Part 1)

1088 HMC Web Services API

 Level 04a

"adapter-type": "regular"
"network-uri":"/api/virtual-networks/a1b736ee-9adb-11e1-8868-00215e67ad51",
"emulation-mode":"e1000",
"element-id":"f6a47892-a457-11e3-8195-f0def1b30158",
"mac-address":"02:ff:42:41:69:93",
"element-uri":"/api/virtual-servers/f6755c24-a457-11e3-8a23-f0def1b30158/network-adapters/
f6a47892-a457-11e3-8195-f0def1b30158"
}
],
"minimum-shares":2,
"virtual-disks":[
{
"description":"",
"element-uri":"/api/virtual-servers/f6755c24-a457-11e3-8a23-f0def1b30158/virtual-disks/
f6bdf2ae-a457-11e3-a23c-f0def1b30158",
"backing-virtualization-host-storage-resource":"/api/virtualization-hosts/
6c54bdcc-0b3d-11e3-b37e-f0def1b30158/virtualization-host-storage-resources/
9e7d4072-a457-11e3-8195-f0def1b30158",
"element-id":"f6bdf2ae-a457-11e3-a23c-f0def1b30158",
"emulation-mode":"ide",
"owner":"/api/virtual-servers/f6755c24-a457-11e3-8a23-f0def1b30158",
"size":1073741824,
"type":"fullpack",
"name":"testvdisk1"
},
{
"description":"",
"element-uri":"/api/virtual-servers/f6755c24-a457-11e3-8a23-f0def1b30158/virtual-disks/
f6c29840-a457-11e3-a23c-f0def1b30158",
"backing-virtualization-host-storage-resource":"/api/virtualization-hosts/
6c54bdcc-0b3d-11e3-b37e-f0def1b30158/virtualization-host-storage-resources/
be507bb2-a457-11e3-8a23-f0def1b30158",
"element-id":"f6c29840-a457-11e3-a23c-f0def1b30158",
"emulation-mode":"virtio-scsi",
"owner":"/api/virtual-servers/f6755c24-a457-11e3-8a23-f0def1b30158",
"size":1073741824,
"type":"fullpack",
"name":"testvdisk_2"
}
],
"class":"virtual-server",
"workload-element-groups":[],
"name":"testbootsequence_1",
"initial-memory":1024,
"perf-policies":[],
"cpu-perf-mgmt-enabled":true,
"acceptable-avail-status":[
"available"
],
"acceptable-status":[
"operating"
],
"initial-shares":1024,
"gpmp-support-enabled":false,
"initial-virtual-processors":1,
"object-uri":"/api/virtual-servers/f6755c24-a457-11e3-8a23-f0def1b30158",
"workloads":[
"/api/workload-resource-groups/a40e2b96-9adb-11e1-8868-00215e67ad51"
],
"has-unacceptable-status":true,
"inband-monitoring-enabled":false
}

Figure 578. Get Virtual Server Properties: Response for virtual servers of type "x-hyp" (Part 2)

Chapter 15. Virtualization management 1089

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 07 Dec 2011 05:31:36 GMT
content-type: application/json;charset=UTF-8
content-length: 1133
{
"acceptable-status": [
"operating"
],
"additional-status": null,
"auto-start": false,
"class": "virtual-server",
"cpu-perf-mgmt-enabled": false,
"description": "",
"gpmp-status": "not-operating",
"gpmp-support-enabled": false,
"gpmp-version": "unavailable",
"has-unacceptable-status": false,
"hostname": null,
"initial-memory": 32,
"initial-share-mode": "relative",
"initial-shares": 100.0,
"initial-virtual-processors": 1,
"ipl-device": "CMS",
"ipl-load-parameters": "",
"ipl-parameters": "AUTOCR",
"is-locked": false,
"mac-prefix": {
"mac-address": "02:ca:0d:00:00:00",
"prefix-length": 24
},
"maximum-memory": 0,
"maximum-share-mode": null,
"maximum-shares": null,
"maximum-virtual-processors": 64,
"name": "MEV1A",
"network-adapters": [],
"object-id": "1738f85e-1b6f-11e1-a8ab-f0def165da96",
"object-uri": "/api/virtual-servers/1738f85e-1b6f-11e1-a8ab-f0def165da96",
"os-level": null,
"os-name": null,
"os-type": null,
"parent": "/api/virtualization-hosts/911f4808-de39-11e0-a58e-f0def161133a",
"password": "999999",
"privilege-classes": "BDEG",
"share-limit": "none",
"status": "operating",
"type": "zvm",
"virtual-disks": [],
"workloads": [
"/api/workload-resource-groups/1fe39a72-de39-11e0-90a6-00215e67351a"
]
}

Figure 579. Get Virtual Server Properties: Response for virtual servers of type "zvm"

Update Virtual Server Properties

The Update Virtual Server Properties operation updates one or more of the writable properties of a
Virtual Server. This operation is not supported for PR/SM virtual servers.

1090 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Request body contents

Fields are only valid if they are supported for a virtual server of the targeted type. For instance a virtual
server with type property "power-vm" may define a processing-mode property (PowerVM only) and
mac-prefix property (PowerVM, z/VM) but not an initial-share-mode property (z/VM only).

Properties may also only be valid if prerequisite properties have specific values. For example a PowerVM
virtual server's initial-virtual-processors is only valid when the processing-mode value is "shared".

All fields in the following table are optional. If a field is not included in the request body contents, its
value will not be updated (unless a prerequisite field is changed, as noted in the table).

See the “Data model” on page 1037 for a complete definition of all properties including for what virtual
server types they are valid and their prerequisites.

Field name Type Description

name String The value to be set as the virtual server's name property. Prerequisite: virtual
server type is not "zvm".
description String The value to be set as the virtual server's description property.
acceptable-status Array of The value to be set as the virtual server's acceptable-status property.
String
Enum
cpu-perf-mgmt-enabled Boolean The value to be set as the virtual server's cpu-perf-mgmt-enabled property.
Default value: true. Valid only when the ensemble's management-
enablement-level is "automate".
processing-mode String The value to be set as the virtual server's processing-mode property.
Enum
minimum-virtual- Integer The value to be set as the virtual server's minimum-virtual-processors
processors property. Default value (used if processing-mode changes to "shared"): 1
initial-virtual- Integer The value to be set as the virtual server's initial-virtual-processors property.
processors Default value (used if processing-mode changes to "shared"): 1
maximum-virtual- Integer The value to be set as the virtual server's maximum-virtual-processors
processors property. Default value for power-vm (used if processing-mode changes to
"shared"): max (maximum-allowed-dedicated-processors,
initial-virtual-processors)
minimum-dedicated- Integer The value to be set as the virtual server's minimum-dedicated-processors
processors property. Default value (used if processing-mode changes to "dedicated"): 1
initial-dedicated- Integer The value to be set as the virtual server's initial-dedicated-processors
processors property. Default value (used if processing-mode changes to "dedicated"): 1
maximum-dedicated- Integer The value to be set as the virtual server's maximum-dedicated-processors
processors property. Default value: maximum-allowed-dedicated-processors Default
value (used if processing-mode changes to "dedicated"):
maximum-allowed-dedicated-processors
minimum-processing- Float The value to be set as the virtual server's minimum-processing-units
units property. Default value (used if processing-mode changes to "shared"): 0.1
initial-processing- Float The value to be set as the virtual server's initial-processing-units property.
units Default value (used if processing-mode changes to "shared"): 0.1

Chapter 15. Virtualization management 1091

 Level 04a

Field name Type Description

maximum-processing- Float The value to be set as the virtual server's maximum-processing-units
units property. Default value (used if processing-mode changes to "shared"): min
(maximum-virtual-processors, maximum-allowed-processing-units)
initial-share-mode String The value to be set as the virtual server's initial-share-mode property.
Enum
initial-shares Float The value to be set as the virtual server's initial-shares property. Default
value based on initial-share-mode (used if initial-share-mode changes):
v relative: 100
v absolute: 10.0
share-limit String The value to be set as the virtual server's share-limit property.
Enum
maximum-share-mode String The value to be set as the virtual server's maximum-share-mode property.
Enum Default value (used if share-limit changes from "none" to "soft" or "hard" ):
relative
maximum-shares Float The value to be set as the virtual server's maximum-shares property. Default
value based on maximum-share-mode (used if maximum-share-mode
changes):
v relative: 100
v absolute: 10.0
minimum-memory Integer The value to be set as the virtual server's minimum-memory property.
initial-memory Integer The value to be set as the virtual server's initial-memory property.
maximum-memory Integer The value to be set as the virtual server's maximum-memory property.
boot-mode String The value to be set as the virtual server's boot-mode property.
Enum
boot-sequence Array of The value to be set as the virtual server's boot-sequence property.
String
Enum
book-network-adapter- String The value to be set as the virtual server's boot-network-adapter-client-ip
client-ip property. Default value (used if boot-sequence changes to
["network-adapter"]): an empty string
boot-network-adapter- String The value to be set as the virtual server's boot-network-adapter-subnet-ip
subnet-ip property. Default value (used if boot-sequence changes to
["network-adapter"]): an empty string
boot-network-adapter- String The value to be set as the virtual server's boot-network-adapter-gateway-ip
gateway-ip property. Default value (used if boot-sequence changes to
"network-adapter"): an empty string
boot-network-adapter- String The value to be set as the virtual server's boot-network-adapter-server-ip
server-ip property. Default value (used if boot-sequence changes to
"network-adapter"): an empty string
keylock String The value to be set as the virtual server's keylock property.
Enum
auto-start Boolean The value to be set as the virtual server's auto-start property.
dlpar-enabled Boolean The value to be set as the virtual server's dlpar-enabled property.
gpmp-support-enabled Boolean The value to be set as the virtual server's gpmp-support-enabled property.

1092 HMC Web Services API

 Level 04a

Field name Type Description

rmc-virtual-device- String The virtual device address of the resource monitoring and control network
address to create in order to support the Guest Platform Management Provider
(GPMP).

Prerequisite: type is "zvm" and gpmp-support-enabled is true.

Required if gpmp-support-enabled changes to true.

1-4 character hex string

password String The value to be set as the virtual server's password property.
privilege-classes String The value to be set as the virtual server's privilege-classes property.
ipl-device String The value to be set as the virtual server's ipl-device property.
ipl-load–parameters String The value to be set as the virtual server's ipl-load-parameters property.
ipl-parameters String The value to be set as the virtual server's ipl-parameters property.
inband-monitoring- Boolean The value to be set as the virtual server's inband-monitoring-enabled
enabled property.
keyboard-language String The value to be set as the virtual server's keyboard-language property.
acceptable-avail- Array of The value to be set as the virtual server's acceptable-avail-status property.
status String
Enum

Description
This operation updates a virtual server's properties with the values specified on the identified
Virtualization Host.

If the API user does not have access action permission to Virtual Server Details or the zManager
management enablement level for the ensemble does not allow the setting of a provided property, a 403
(Forbidden) status code is returned. A 404 (Not Found) status code is also returned if the object-id
{virt-host-id} does not identify a Virtualization Host object to which the API user has object-access
permission. If the Virtualization Host is of type "zvm" and its status is "not-activated", a 409 (Conflict)
status code is returned.

If the request body contents fail to validate, a 400 (Bad Request) status code is returned. This may occur
because the document defines a field that is not supported for the given virtual server type or includes a
field that is not supported because a prerequisite is not met (e.g. attempting to set maximum-share-mode
when share-limit is "none").

If the request body contents are valid, the virtual server's properties are updated to their corresponding
request body content's field's values. All fields are optional and may be excluded from the request body;
if an optional field is not found in the request body, its property's value will not be modified. As
indicated, a property's value is set to its default value if the field is not included in the request body and
a prerequisite or other linked field is changed (e.g. if initial-share-mode is changed from "relative" to
"absolute", and initial-shares is not defined in the request body, initial-shares will be defaulted to 10.0).

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Virtual Server object designated by {virtual-server-id}
v Action/task permission to the Virtual Server Details task.

Chapter 15. Virtualization management 1093

 Level 04a

v Action/task permission to the Virtual Server Performance Details task if the gpmp-support-enabled
or cpu-perf-mgmt-enabled field is to be updated, otherwise action/task permission to the Virtual
Server Details task for all other fields.

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.
100 The operation does not support a virtual server of the given type.
101 A virtual server with the name specified in the request body already exists
on the Virtualization Host with object-id {virt-host-id}.
103 A “shares” (initial-shares or maximum-shares) property value type is not
correct based on the value of its corresponding “share-mode”
(initial-share-mode or maximum-share-mode). For example, the
initial-share-mode is defined as "relative" but the initial-shares value is not
an integer.
403 (Forbidden) 1 API user does not have action permission to the Virtual Server Details task.
100 The ensemble's management-enablement-level property value does not
allow the updating of a provided property.
404 (Not Found) 1 A virtual-server with object-id {virtual-server-id} does not exist on HMC or
API user does not have object-access permission for it.
409 (Conflict) 1 Virtual server status is not valid to perform the operation (does not allow
the updating of a specified virtual server property).
2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other 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.
2 The request could not be processed because the HMC is not currently
communicating with an element of a zBX needed to perform the requested
operation.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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

1094 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/virtual-servers/7ba96572-0d72-11e1-892f-f0def14b63af HTTP/1.1

x-api-session: 64zdknfzh24fqw8f9v5g99h96rhrxhodmawtknx4iutmgqrfvf
content-type: application/json
content-length: 169
{
"auto-start": true,
"description": "Spacely Sprockets Web Store Web Server #1A",
"initial-virtual-processors": 2,
"keyboard-language": "en_US",
"name": "SS-Web-Svr-1A"
}

Figure 580. Update Virtual Server Properties: Request for a virtual server of type "x-hyp"

204 No Content
date: Sat, 12 Nov 2011 21:08:38 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 581. Update Virtual Server Properties: Response for a virtual server of type "x-hyp"

Create Network Adapter

The Create Network Adapter operation creates a virtual network adapter for the PowerVM, x Hyp, or
z/VM virtual server with the given identifier. This operation is not supported for PR/SM virtual servers.

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/network-adapters

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Request body contents

Request body contents vary based on virtual server type.

For "power-vm":

Field name Type Rqd/Opt Description

network-uri String/ Optional The network-uri property of the network-adapter-power object.
URI Default: null

For "x-hyp":

Field name Type Rqd/Opt Description

network-uri String/ Optional The network-uri property of the network-adapter-x-hyp object.
URI Default: null
emulation-mode String Required The emulation-mode property of the network-adapter-x-hyp object.
Enum

For "zvm":

Chapter 15. Virtualization management 1095

 Level 04a

Field name Type Rqd/Opt Description

virtual-device- String Required The virtual-device-address property of
address network-adapter-zvm object
type String Required The type property of network-adapter-zvm object. The
value may not be "rmc".
interface-type String Required The interface-type property of network-adapter-zvm
Enum object
real-device-address String Optional The real-device-address property of
network-adapter-zvm object
switch-uri String/ Required if interface-type If the interface-type is virtual-iedn, or virtual-qdio,
URI is any value except none specify the switch-uri property of the of the
network-adapter-zvm object. If the interface-type is
physical-iedn, physical-qdio, or physical-iqdn, specify
the element-uri of a network-adapter-prsm object in
the list of network adapters from the
network-adapters property of the z/VM virtual
server's parent property's Virtual Server object.
port-mode String Required if interface-type The port-mode property of network-adapter-zvm
Enum is virtual-iedn or object
virtual-qdio
vlan-ids String Required if interface-type The vlan-ids property of network-adapter-zvm object
is virtual-qdio
network-uris Array of Required if interface-type The network-uris property of network-adapter-zvm
String/ is virtual-iedn or object
URI physical-iedn

Response body contents

On successful completion, the response body contains the URI of the created network-adapter object.

Field name Type Description

element-uri String/URI The element-uri property of the created network adapter object.

Description
This operation creates the network adapters for the identified virtual server and then returns the URI of
the created object. The response also includes a Location header that provides this URI.

If the virtual server is of type "power-vm" or "x-hyp" and its status is neither "not-operating"nor
"not-activated", a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Virtual Server object designated by {virtual-server-id}
v Action/task permission to the Virtual Server Details 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.”

1096 HMC Web Services API

 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.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 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.
409 (Conflict) 1 Virtual server status is not valid to perform the operation.
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
109 The switch-uri conflicts with the network adapter type
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/network-adapters HTTP/1.1

x-api-session: 3vkw2ncjqhmmpzo6bsyjojjlfgzd0kjoqbvhskz2m6z7esmjrr
content-type: application/json
content-length: 104
{
"emulation-mode": "e1000",
"network-uri": "/api/virtual-networks/f920171e-03f2-11e1-8e8e-0010184c8334"
}

Figure 582. Create Network Adapter: Request for a virtual server of type "x-hyp"

Chapter 15. Virtualization management 1097

 Level 04a

201 Created
server: zSeries management console API web server / 1.0
location: /api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/network-adapters/
4a5073e6-0f9b-11e1-94dc-f0def14b63af
cache-control: no-cache
date: Tue, 15 Nov 2011 15:05:48 GMT
content-type: application/json;charset=UTF-8
content-length: 129
{
"element-uri": "/api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/
network-adapters/4a5073e6-0f9b-11e1-94dc-f0def14b63af"
}

Figure 583. Create Network Adapter: Response for a virtual server of type "x-hyp"

Delete Network Adapter

The Delete Network Adapter operation deletes an existing virtual network adapter specified by an object
identifier for the PowerVM, x Hyp, or z/VM virtual server with the given identifier. This operation is not
supported for PR/SM virtual servers.

HTTP method and URI

DELETE /api/virtual-servers/{virtual-server-id}/network-adapters/{network-adapter-id}

URI variables

Variable Description
{virtual-server-id} Object ID of the Virtual Server object
{network-adapter-id} Element ID of the network adapter

Description
This operation deletes the network adapters for the identified virtual server.

If virtual server is of type "zvm" and the target network adapter is the Remote Monitoring and Control
network adapter (type "rmc"), a 400 (Bad Request) is returned.

If the virtual server is of type "power-vm" or "x-hyp" and its status is neither "not-operating" nor
"not-activated", a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server
v Action/task role permission to the Virtual Server 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

1098 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.
106 The targeted network adapter is the Resource Monitoring and Control
network adapter.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 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.
409 (Conflict) 1 Virtual server status is not valid to perform the operation.
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/network-adapters/
4a5073e6-0f9b-11e1-94dc-f0def14b63af HTTP/1.1
x-api-session: 3vkw2ncjqhmmpzo6bsyjojjlfgzd0kjoqbvhskz2m6z7esmjrr

Figure 584. Delete Network Adapter: Request

204 No Content
date: Tue, 15 Nov 2011 15:05:50 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 585. Delete Network Adapter: Response

Get Network Adapter Properties

The Get Network Adapter Properties operation retrieves the properties of a single network adapter
object that is designated by its element ID and the object ID of the owning virtual server.

HTTP method and URI

GET /api/virtual-servers/{virtual-server-id}/network-adapters/{network-adapter-id}

URI variables

Chapter 15. Virtualization management 1099

 Level 04a

Variable Description
{virtual-server-id} Object ID of the virtual server that owns the virtual disk.
{network-adapter-id} Element ID of the network adapter object for which properties are to be obtained.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the network adapter object as defined in the “Data model” on page 1037. Field names
and data types in the JSON object are the same as the property names and data types that are defined in
the data model.

Description
This operation returns the current properties for the network adapter object that is specified by
{network-adapter-id}.

On successful execution, all of the current properties as defined by the data model for the Network
Adapter object are provided in the response body and HTTP status code 200 (OK) is returned.

The URI path must designate an existing Virtual Server object and you must have object-access
permission to it. Furthermore, the URI path must designate an existing network adapter object. If either
of these conditions is not met, status code 404 (Not Found) is returned. In addition, you must have
action/task permission to the Virtual Server Details task, otherwise status code 403 (Forbidden) is
returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Virtual Server object designated by {virtual-server-id}
v Action/task permission to the Virtual Server Details task.

HTTP status and reason codes

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

The following HTTP status codes are returned for the indicated errors, and the response body is a
standard error response body providing the reason code that is 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 API user does not have action permission for this operation.
404 (Not Found) 1 A object-id in the URI {virtual-server-id} does not designate an existing Virtual
Server object, or the API user does not have object-access permission to it.
2 The element-id in the URI {network-adapter-id} does not designate an existing
network adapter object.

1100 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 1 Virtual server status is not valid to perform the operation.
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
108 The virtual switch to which the network adapter was connected is no longer
defined in z/VM.
109 The virtual switch specified by the switch-uri property conflicts with the
network adapter type in the request.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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/virtual-servers/c967fcb2-f950-11e2-856c-3c970e47dddb/network-adapters/
7db9e036-f951-11e2-9276-3c970e47dddb HTTP/1.1
x-api-session: v3motdpyqmgz4oe2hq5vtxhvoc80uea9efd4xjbc8emb2uung

Figure 586. Get Network Adapter Properties: Request

200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 30 Jul 2013 19:50:10 GMT
content-type: application/json;charset=UTF-8
content-length: 316
{
"adapter-type": "regular"
"element-id": "7db9e036-f951-11e2-9276-3c970e47dddb",
"element-uri": "/api/virtual-servers/c967fcb2-f950-11e2-856c-3c970e47dddb/network-adapters/
7db9e036-f951-11e2-9276-3c970e47dddb",
"emulation-mode": "virtio",
"mac-address": "02:ff:7d:2d:b2:43",
"network-uri": "/api/virtual-networks/43ea31fe-f950-11e2-b884-00215e67ac16"
}

Figure 587. Get Network Adapter Properties: Response

Update Network Adapter

The Update Network Adapter operation modifies an existing virtual network adapter specified by an
object identifier for the PowerVM, x Hyp, z/VM, or PR/SM virtual server with the given identifier.

Chapter 15. Virtualization management 1101

 Level 04a

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/network-adapters/{network-adapter-id}

URI variables

Variable Description
{virtual-server-id} Object ID of the Virtual Server object
{network-adapter-id} Element ID of the network adapter

Request body contents

Request body contents vary based on virtual server type.

For "prsm":

Field name Type Rqd/Opt Description

network-uris Array of Optional The network-uris property of the network-adapter-prsm object.
String/
URI

For "power-vm":

Field name Type Rqd/Opt Description

network-uri String/ Optional The network-uri property of the network-adapter-power object.
URI Specify a value of null to indicate that the network adapter should
not be connected to a virtual network.

For "x-hyp":

Field name Type Rqd/Opt Description

network-uri String/ Optional The network-uri property of the network-adapter-x-hyp object.
URI Specify a value of null to indicate that the network adapter should
not be connected to a virtual network.
emulation-mode String Optional The emulation-mode property of the network-adapter-x-hyp object.
Enum

For "zvm":

Field name Type Rqd/Opt Description

virtual-device- String Optional The virtual-device-address property of
address network-adapter-zvm object
interface-type String Optional The interface-type property of network-adapter-zvm
Enum object
real-device-address String Optional The real-device-address property of
network-adapter-zvm object
switch-uri String/ Optional; Allowed only if The switch-uri property of network-adapter-zvm
URI interface-type is object.
virtual-iedn or
virtual-qdio

1102 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

port-mode String Optional; Allowed only if The port-mode property of network-adapter-zvm
Enum interface-type is object
virtual-iedn or
virtual-qdio
vlan-ids String Optional; Allowed only if The vlan-ids property of network-adapter-zvm object
interface-type is
virtual-qdio
network-uris Array of Optional; Allowed only if The network-uris property of network-adapter-zvm
String/ interface-type is object
URI virtual-iedn or
physical-iedn

Description
This operation modifies the Network Adapter object identified by the request URI.

If virtual server is of type "zvm" and the target network adapter is the Remote Monitoring and Control
network adapter (type "rmc"), a 400 (Bad Request) is returned.

If the virtual server is of type "power-vm" or "x-hyp" and its status is neither "not-operating" nor
"not-activated", a 409 (Conflict) status code is returned. If the virtual server is of type "zvm", the network
adapter interface-type is "virtual-iedn" or "virtual-qdio", and the virtual-switch to which the network
adapter was connected no longer exists, a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server.
v Object-access permission to the Virtual Network object(s)
v Action/task permission to the Virtual Server 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, 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.
106 The targeted network adapter is the Resource Monitoring and Control
network adapter.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 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 15. Virtualization management 1103

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 1 Virtual server status is not valid to perform the operation.
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
108 The virtual switch to which the network adapter was connected is no longer
defined in z/VM.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/network-adapters/
4a5073e6-0f9b-11e1-94dc-f0def14b63af HTTP/1.1
x-api-session: 3vkw2ncjqhmmpzo6bsyjojjlfgzd0kjoqbvhskz2m6z7esmjrr
content-type: application/json
content-length: 105
{
"emulation-mode": "virtio",
"network-uri": "/api/virtual-networks/f3aece54-0db8-11e1-9e2c-00215e69dea0"
}

Figure 588. Update Network Adapter: Request for a virtual server of type "x-hyp"

204 No Content
date: Tue, 15 Nov 2011 15:05:48 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 589. Update Network Adapter: Response for a virtual server of type "x-hyp"

Reorder Network Adapter

The Reorder Network Adapter operation reorders the virtual network adapter defined for the PowerVM
or x Hyp virtual server with the given identifier. This operation is not supported for z/VM and PR/SM
virtual servers.

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/operations/reorder-network-adapters

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

1104 HMC Web Services API

 Level 04a

Request body contents

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

Field name Type Rqd/Opt Description

network-adapter- Array of Required Ordered list of element-uris for the network adapter object. The
uris String/ order of this array is significant.
URI

Description
This operation reorders the network adapters for the identified virtual server.

If the virtual server is of type "power-vm" or "x-hyp" and its status is neither "not-operating" nor
"not-activated", a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server
v Object-access permission to the Virtual Network object(s)
v Action/task permission to the Virtual Server 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, 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) 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.
409 (Conflict) 1 Virtual server status is not valid to perform the operation.
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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

Chapter 15. Virtualization management 1105

 Level 04a

Example HTTP interaction

POST /api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/operations/
reorder-network-adapters HTTP/1.1
x-api-session: 3vkw2ncjqhmmpzo6bsyjojjlfgzd0kjoqbvhskz2m6z7esmjrr
content-type: application/json
content-length: 256
{
"network-adapter-uris": [
"/api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/network-adapters/
4a5073e6-0f9b-11e1-94dc-f0def14b63af",
"/api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/network-adapters/
582b5d0e-0db7-11e1-b1f1-f0def14b63af"
]
}

Figure 590. Reorder Network Adapter: Request

204 No Content
date: Tue, 15 Nov 2011 15:05:48 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 591. Reorder Network Adapter: Response

Create Virtual Disk

The Create Virtual Disk operation adds a virtual disk to the specified virtual server. This operation is not
supported for PR/SM virtual servers.

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/virtual-disks

In this request, the URI variable {virtual-server-id} is the object ID of the virtual server that will own the
new virtual disk.

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The name property of the virtual disk object.
description String Optional The description property of the virtual disk object.
size Long Required The size property of the virtual disk object. Required and only valid
for virtual disks with a type of "storage-group-based".
type String Required The type property of the virtual disk object.
Enum
emulation-mode String Required The emulation-mode property of the virtual disk object. Required
Enum and only valid for all virtual disks for a virtual server with type of
"x-hyp".
access-mode String Required The access-mode property of the virtual disk object. Required and
Enum only valid for all virtual disks for a virtual server with type of
"zvm". Value may not be "unsupported".

1106 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

device-address String Required The device-address property of the virtual disk object. Required for
(1-4) all virtual disks for a virtual server with type of "zvm".
read-password String Optional The read-password property of the virtual disk. For all virtual disks
(0-8) for a virtual server with type "zvm" and a virtual disk type of either
"fullpack" or "storage-group-based".
write-password String Optional The write-password property of the virtual disk. For all virtual
(0-8) disks for a virtual server with type "zvm" and a virtual disk type of
either "fullpack" or "storage-group-based".
multi-password String Optional The multiple-write password property of the virtual disk. For all
(0-8) virtual disks for a virtual server with type "zvm" and a virtual disk
type of either "fullpack" or "storage-group-based".
password String Optional The password for the linked virtual disk. For virtual disks with a
(0-8) type of "linked".
backing- String/ Required The backing-virtualization-host-storage-resource property of the
virtualization- URI virtual disk. Required and only valid for virtual disks with a type of
host-storage- "fullpack".
resource
source-virtual-disk String/ Required The source-virtual-disk property of the virtual disk. Required and
URI only valid for virtual disks with a type of "linked".
backing-storage- String/ Required The backing-storage-group property of the virtual disk. Required
group URI and only valid for virtual disks with a type of "storage-group-
based".

Response body contents

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

Field name Type Description

element-uri String/URI The element-uri of the newly created Virtual Disk object.

Description
The Create Virtual Disk operation adds a virtual disk to the virtual server specified by the
{virtual-server-id} portion of the request URI.

Upon successful completion, the element-uri field of the Response Body and the value of the Location
response header identify the new virtual disk.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

The URI path must designate an existing Virtual Server 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. In
addition, the API user must also have action/task permission to the Virtual Server Details action as well,
otherwise status code 403 (Forbidden) is returned.

If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered.

If the virtual server is of type "power-vm" or "x-hyp" and its status is not "operating" ,"not-operating" or
"not-activated", a 409 (Conflict) status code is returned.

Chapter 15. Virtualization management 1107

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Virtual Server object designated by {virtual-server-id}
v Object-access permission to the storage resources to be used by the virtual disk:
– If virtual disk type is "fullpack", object-access permission to the storage resource used by the
Virtualization Host Storage Resource object designated by backing-virtualization-host-storage-
resource.
– If virtual disk type is "storage-group-based", object-access permission to the storage resource used
by every virtualization host storage resource owned by the Virtualization Host Storage Group object
designated by backing-storage-group.
– If virtual disk type is "linked", object-access permission to the storage resources used by the virtual
disk designated by source-virtual-disk and to the virtual server that owns it.
v Action/task permission to the Virtual Server Details task.

HTTP status and reason codes

On success, HTTP status code 201 (Created) is returned and both the response body and the Location
response header contain the URI of the newly created object.

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.
7 Another Virtual server instance running in this hypervisor with SCSI
passthrough enabled.
100 The operation does not support a virtual server of the given type.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 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.
107 The backing-virtualization-host-storage-resource property does not
designate an existing Virtualization Host Storage Resource object, or the API
user does not have object-access permission to it.
108 The backing-storage-group property does not designate an existing
Virtualization Host Storage Group object, or the API user does not have
object-access permission to it.
109 The source-virtual-disk property does not designate an existing virtual disk
object, or the API user does not have object-access permission to it.
409 (Conflict) 1 Virtual server status is not valid to perform the operation.
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

1108 HMC Web Services API

 Level 04a

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/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/virtual-disks HTTP/1.1

x-api-session: 29chofb3vqxpijctnd2kf5fiwnfll8z62mq3yomtqjyz8bx2gn
content-type: application/json
content-length: 259
{
"backing-virtualization-host-storage-resource": "/api/virtualization-hosts/
2f7bf364-03f8-11e1-8eda-001f163805d8/virtualization-host-storage-resources/
37699380-0fa9-11e1-b69e-f0def14b63af",
"description": "Boot filesystem",
"name": "boot",
"type": "fullpack"
}

Figure 592. Create Virtual Disk: Request for a virtual server of type "power-vm"

201 Created
server: zSeries management console API web server / 1.0
location: /api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/virtual-disks/
c547fb4e-0fac-11e1-842b-f0def14b63af
cache-control: no-cache
date: Tue, 15 Nov 2011 17:10:57 GMT
content-type: application/json;charset=UTF-8
content-length: 126
{
"element-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/virtual-disks/
c547fb4e-0fac-11e1-842b-f0def14b63af"
}

Figure 593. Create Virtual Disk: Response for a virtual server of type "power-vm"

POST /api/virtual-servers/7fa1b30c-7d30-11e3-aaaa-00262dfc0ec9/virtual-disks/
817ceb06-7d30-11e3-b0c0-5cf3fc260857
{
"emulation-mode": "virtio-scsi",
"backing-virtualization-host-storage-resource":"/api/virtualization-hosts/332de83c-c15c-11e2-
9510-00262dfc0ec9/virtualization-host-storage-resources/7ef9f73e-7d30-11e3-aaaa-
00262dfc0ec9",
"type": "fullpack",
"name": "fullpack_virtual_disk_3600",
"description": "fullpack virtual disk for API FVT testcase 3600"
}

Figure 594. Create Virtual Disk: Request for a virtual server of type "x-hyp"

Chapter 15. Virtualization management 1109

 Level 04a

201 Created
server: zSeries management console API web server / 2.0,
location: /api/virtual-servers/7fa1b30c-7d30-11e3-aaaa-00262dfc0ec9/virtual-disks/
817ceb06-7d30-11e3-b0c0-5cf3fc260857,
cache-control: no-cache,
date: Tue, 14 Jan 2014 15:28:23 GMT,
content-type’: application/json;charset=UTF-8
content-length: 126
{
element-uri: "/api/virtual-servers/7fa1b30c-7d30-11e3-aaaa-00262dfc0ec9/virtual-disks/
817ceb06-7d30-11e3-b0c0-5cf3fc260857"
}

Figure 595. Create Virtual Disk: Response for a virtual server of type "x-hyp"

Delete Virtual Disk

The Delete Virtual Disk operation removes a specified virtual disk from the specified virtual server. This
operation is not supported for PR/SM virtual servers.

HTTP method and URI

DELETE /api/virtual-servers/{virtual-server-id}/virtual-disks/{virtual-disk-id}

URI variables

Variable Description
{virtual-server-id} Object ID of the Virtual Server object
{virtual-disk-id} Element ID of the virtual disk object

Description
The Delete Virtual Disk operation removes a specified virtual disk from the specified virtual server. The
virtual disk is identified by the {virtual-disk-id} variable in the URI, and the virtual server is identified by
the {virtual-server-id} variable in the URI.

Upon successfully removing the virtual disk, HTTP status code 204 (No Content) is returned and no
response body is provided.

The URI path must designate an existing Virtual Server object and the API user must have object-access
permission to it. Furthermore, the URI path must designate an existing virtual disk object. If any of these
conditions is not met, status code 404 (Not Found) is returned. In addition, the API user must also have
action/task permission to the Virtual Server Details action as well, otherwise status code 403 (Forbidden)
is returned.

If the virtual server is of type "power-vm" or "x-hyp" and its status is neither "not-operating" nor
"not-activated", a 409 (Conflict) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Virtual Server object designated by {virtual-server-id}.
v If virtual disk type is "fullpack", object-access permission to the Virtualization Host Storage Resource
object designated by backing-virtualization-host-storage-resource

1110 HMC Web Services API

 Level 04a

v If virtual disk type is "storage-group-based", object-access permission to all virtualization host storage
resources owned by the virtualization host Group object designated by backing-storage-group.
v If virtual disk type is "linked", object-access permission to virtual disk designated by
source-virtual-disk and the virtual server that owns it.
v Action/task permission to the Virtual Server 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, 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.
100 The operation does not support a virtual server of the given type.
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 {virtual-server-id} does not designate an existing
Virtual Server object, or the API user does not have object-access permission
to it.
2 The object ID in the URI {virtual-disk-id} does not designate an existing
virtual disk object.
409 (Conflict) 1 Virtual server status is not valid to perform the operation.
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/virtual-disks/
c547fb4e-0fac-11e1-842b-f0def14b63af HTTP/1.1
x-api-session: 29chofb3vqxpijctnd2kf5fiwnfll8z62mq3yomtqjyz8bx2gn

Figure 596. Delete Virtual Disk: Request

Chapter 15. Virtualization management 1111

 Level 04a

204 No Content
date: Tue, 15 Nov 2011 17:11:03 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 597. Delete Virtual Disk: Response

Get Virtual Disk Properties

The Get Virtual Disk Properties operation retrieves the properties of a single virtual disk object that is
designated by its object ID and the object ID of the owning virtual server. This operation is not supported
for PR/SM virtual servers.

HTTP method and URI

GET /api/virtual-servers/{virtual-server-id}/virtual-disks/{virtual-disk-id}

URI variables

Variable Description
{virtual-server-id} Object ID of the virtual server that will own the virtual disk.
{virtual-disk-id} Element ID of the virtual disk object for which properties are to be obtained.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the virtual disk object as defined in the data model section above. 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
This operation returns the current properties for the virtual disk object specified by {virtual-disk-id}.

On successful execution, all of the current properties as defined by the “Data model” on page 1037 are
provided in the response body and HTTP status code 200 (OK) is returned.

The URI path must designate an existing Virtual Server object and the API user must have object-access
permission to it. Furthermore, the URI path must designate an existing virtual disk object. If any of these
conditions is not met, status code 404 (Not Found) is returned. In addition, the API user must have
action/task permission to the Virtual Server Details action, otherwise status code 403 (Forbidden) is
returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Virtual Server object designated by {virtual-server-id}
v If virtual disk type is "fullpack", object-access permission to the Virtualization Host Storage Resource
object designated by backing-virtualization-host-storage-resource

1112 HMC Web Services API

 Level 04a

v If virtual disk type is "storage-group-based", object-access permission to all virtualization host storage
resources owned by the Virtualization Host Storage Group object designated by backing-storage-
group.
v If virtual disk type is "linked", object-access permission to virtual disk designated by
source-virtual-disk and the virtual server that owns it.
v Action/task permission to the Virtual Server 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, 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.
100 The operation does not support a virtual server of the given type.
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 {virtual-server-id} does not designate an existing
Virtual Server object, or the API user does not have object-access permission
to it.
2 The object ID in the URI {virtual-disk-id} does not designate an existing
virtual disk 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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/virtual-disks/
c547fb4e-0fac-11e1-842b-f0def14b63af HTTP/1.1
x-api-session: 29chofb3vqxpijctnd2kf5fiwnfll8z62mq3yomtqjyz8bx2gn

Figure 598. Get Virtual Disk Properties: Request for a virtual server of type "power-vm"

Chapter 15. Virtualization management 1113

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2011 17:10:57 GMT
content-type: application/json;charset=UTF-8
content-length: 516
{
"backing-virtualization-host-storage-resource": "/api/virtualization-hosts/
2f7bf364-03f8-11e1-8eda-001f163805d8/virtualization-host-storage-resources/
37699380-0fa9-11e1-b69e-f0def14b63af",
"description": "Boot filesystem",
"element-id": "c547fb4e-0fac-11e1-842b-f0def14b63af",
"element-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/virtual-disks/
c547fb4e-0fac-11e1-842b-f0def14b63af",
"name": "boot",
"owner": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af",
"size": 17179869184,
"type": "fullpack"
}

Figure 599. Get Virtual Disk Properties: Response for a virtual server of type "power-vm"

GET:/api/virtual-servers/7fa1b30c-7d30-11e3-aaaa-00262dfc0ec9/virtual-disks/817ceb06-7d30-
11e3-b0c0-5cf3fc260857
x-api-session: 3rprukcrfwl0wfb57u0rw4e0epi5579ck253zbc02plfwypu0z

Figure 600. Get Virtual Disk Properties: Request for a virtual server of type "x-hyp"

200 OK
server: zSeries management console API web server / 2.0,
cache-control: no-cache,
date: Tue, 14 Jan 2014 15:28:37 GMT
content-type: application/json;charset=UTF-8,
content-length: 605
{
"description":"fullpack virtual disk for API FVT testcase 3600_updated",
"element-uri":"/api/virtual-servers/7fa1b30c-7d30-11e3-aaaa-00262dfc0ec9/virtual-disks/
817ceb06-7d30-11e3-b0c0-5cf3fc260857",
"backing-virtualization-host-storage-resource":"/api/virtualization-hosts/
332de83c-c15c-11e2-9510-00262dfc0ec9/virtualization-host-storage-resources/
7ef9f73e-7d30-11e3-aaaa-00262dfc0ec9",
"element-id":"817ceb06-7d30-11e3-b0c0-5cf3fc260857",
"emulation-mode":"virtio-scsi",
"owner":"/api/virtual-servers/7fa1b30c-7d30-11e3-aaaa-00262dfc0ec9",
"size":1234,
"type":"fullpack",
"name":"fullpack_virtual_disk_3600_updated"
}

Figure 601. Get Virtual Disk Properties: Response for a virtual server of type "x-hyp"

Update Virtual Disk Properties

The Update Virtual Disk Properties operation updates one or more of the writable properties of a virtual
disk object. This operation is not supported for PR/SM virtual servers.

1114 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/virtual-disks/{virtual-disk-id}

URI variables

Variable Description
{virtual-server-id} Object ID of the virtual server that owns the virtual disk.
{virtual-disk-id} Element ID of the virtual disk object for which properties are to be updated.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined in the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation. All such fields are optional.

The JSON object may also contain the following non-data-model field:

Field name Type Rqd/Opt Description

password String Optional The new password for a linked virtual disk. For virtual disks with a
(0-8) type of "linked"

Request body access-mode property value may not be "unsupported".

Description
This operation updates writable properties of the virtual disk object specified by {virtual-disk-id}.

The request body contains an object with one or more fields with field names that correspond to the
names of properties for this object. 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 without supplying any response body. The request body does not need to specify a value for all
writable properties, but rather can and should contain only fields for the properties to be updated. Object
properties for which no input value is provided remain unchanged by this operation.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

The URI path must designate an existing virtual disk object and the API user must have object-access
permission to it. Furthermore, the URI path must designate an existing Virtual Server object. If any of
these conditions is not met, status code 404 (Not Found) is returned. In addition, the API user must also
have action/task permission to the Virtual Server Details action as well, otherwise status code 403
(Forbidden) is returned.

The request body is validated against the data model for this object type to ensure that it 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.

If the virtual server is of type "power-vm" or "x-hyp" and its status is neither "not-operating" nor
"not-activated", a 409 (Conflict) status code is returned.

Chapter 15. Virtualization management 1115

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Virtual Server object designated by {virtual-server-id}
v If virtual disk type is "fullpack", object-access permission to the Virtualization Host Storage Resource
object designated by backing-virtualization-host-storage-resource
v If virtual disk type is "storage-group-based", object-access permission to all virtualization host storage
resources owned by the Virtualization Host Storage Group object designated by backing-storage-
group.
v If virtual disk type is "linked", object-access permission to virtual disk designated by
source-virtual-disk and the virtual server that owns it.
v Action/task permission to the Virtual Server 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, 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.
100 The operation does not support a virtual server of the given type.
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 {virtual-server-id} does not designate an existing
Virtual Server object, or the API user does not have object-access permission
to it.
2 The object ID in the URI {virtual-disk-id} does not designate an existing
virtual disk object.
409 (Conflict) 1 Virtual server status is not valid to perform the operation.
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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

1116 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/virtual-servers/7fa1b30c-7d30-11e3-aaaa-00262dfc0ec9/virtual-disks/817ceb06-
7d30-11e3-b0c0-5cf3fc260857
x-api-session: 3rprukcrfwl0wfb57u0rw4e0epi5579ck253zbc02plfwypu0z,
content-type: application/json
{
"emulation-mode": "virtio-scsi",
"name": "fullpack_virtual_disk_3600_updated",
"description": "fullpack virtual disk for API FVT testcase 3600_updated"
}

Figure 602. Update Virtual Disk Properties: Request for a virtual server of type "x-hyp"

204 No Content
date: Tue, 14 Jan 2014 15:28:36 GMT,
cache-control: no-cache,
server : zSeries management console API web server / 2.0
< No Response Body>

Figure 603. Update Virtual Disk Properties: Response for a virtual server of type "x-hyp"

Reorder Virtual Disks

The Reorder Virtual Disks operation reorders the virtual disks defined for the PowerVM or x Hyp
virtual server with the given identifier. This operation is not supported for z/VM and PR/SM virtual
servers.

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/operations/reorder-virtual-disks

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Request body contents

The JSON object may also contain the following field:

Field name Type Rqd/Opt Description

virtual-disk-uris Array of Required Ordered list of virtual disk object element-uri property values. The
String/ order of URIs in the array defines the new order of the virtual
URI disks.

The array size must equal the number of virtual disks for the virtual
server and the array must include the element-uri of each virtual
disk in the virtual server exactly once.

Description
This operation reorders the virtual disks for the identified virtual server.

If the URI path does not designate an existing Virtual Server object or the API user does not have
object-access permission to that virtual server and the storage-resource objects backing its virtual disks, a
404 (Not Found) status code is returned. If the virtual server is of type "zvm" or "prsm", a 400 (Bad
Request) status code is returned. If the API user does not have action/task permission to the Virtual
Server Details action, a 403 (Forbidden) status code is returned.

Chapter 15. Virtualization management 1117

 Level 04a

If virtual-disk-uris array size is not equal to the number of virtual disks in the virtual server or the array
does not include the element-uri of each virtual disk in the virtual server, a 400 (Bad Request) status code
is returned.

If the virtual server is of type "power-vm" or "x-hyp" and its status is neither "not-operating" nor
"not-activated", a 409 (Conflict) status code is returned.

If the request body contents are valid, the virtual server's virtual disks are reordered to match the order
of their element-uri properties in the virtual-disk-uris array.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Virtual Server object designated by {virtual-server-id}
v Object-access permission to the storage resources used by each virtual disk in the virtual server:
– If virtual disk type is "fullpack", object-access permission to the storage resource used by the
Virtualization Host Storage Resource object designated by backing-virtualization-host-storage-
resource.
– If virtual disk type is "storage-group-based", object-access permission to the storage resource used
by every virtualization host storage resource owned by the Virtualization Host Storage Group object
designated by backing-storage-group.
– If virtual disk type is "linked", object-access permission to the storage resources used by the virtual
disk designated by source-virtual-disk and the virtual server that owns it.
v Action/task permission to the Virtual Server 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, 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.
7 The virtual-disk-uris array does not designate a virtual disk of the virtual
server identified in the request URI.
100 The operation does not support a virtual server of the given type.
106 The virtual-disk-uris array contains an invalid number of values.
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 {virtual-server-id} does not designate an existing
Virtual Server object, or the API user does not have object-access permission
to it.
409 (Conflict) 1 Virtual server status is not valid to perform the operation.
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.

1118 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM Virtualization Host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM Virtualization Host via SMAPI failed.

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/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/operations/reorder-virtual-disks HTTP/1.1

x-api-session: 29chofb3vqxpijctnd2kf5fiwnfll8z62mq3yomtqjyz8bx2gn
content-type: application/json
content-length: 247
{
"virtual-disk-uris": [
"/api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/virtual-disks/
c1418fba-0fac-11e1-903e-f0def14b63af",
"/api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/virtual-disks/
c1149ce4-0fac-11e1-903e-f0def14b63af"
]
}

Figure 604. Reorder Virtual Disks: Request

204 No Content
date: Tue, 15 Nov 2011 17:10:50 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 605. Reorder Virtual Disks: Response

Activate Virtual Server

The Activate Virtual Server operation accepts a request to asynchronously activate the identified virtual
server.

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/operations/activate

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Response body contents

Once the activation request is accepted, the response body contains a JSON object with the following
fields:

Chapter 15. Virtualization management 1119

 Level 04a

Field name Type Description

job-uri String/URI URI that may be queried to retrieve activation status updates.

Asynchronous result description

Once the activation job 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 Activate Virtual Server
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 the operation description. The job-results field is null for asynchronous virtual server
activation jobs.

Description
This operation asynchronously activates the identified virtual server. If the URI does not identify a valid
virtual server a 404 (Not Found) status code is returned. If the user does not have authority to perform
the Activate action, a 403 (Forbidden) status code is returned.

For specific hypervisors, the Unified Resource Manager limits the number of virtual servers that can be
active at any given time. A virtual server is active when it is in Starting, Operating or Stopping state.
v The maximum number of active virtual servers for PowerVM is 32.
v The maximum number of active virtual servers for x Hyp is 99.

The virtual server activation job is then initiated and a 202 (Accepted) status code is returned. The
response body includes a URI that may be queried to retrieve the status of the activation job. See “Query
Job Status” on page 80 for information on how to query job status. When the activate job has completed,
an asynchronous result message is sent, including “Job status and reason codes” on page 1121.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server
v Action/task permission to the Activate 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 1119.

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.

1120 HMC Web Services API

 Level 04a

Table 407. Activate Virtual Server: 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 Another virtual server instance is running in this hypervisor with SCSI
passthrough enabled.
403 (Forbidden) 1 API user does not have access action permission to Activate.
404 (Not Found) 1 A virtual server with object-id {virtual-server-id} does not exist on HMC or
API user does not have object-access permission for it.
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

HTTP error status Reason
code code Description
200 (OK) N/A Activation completed successfully
500 (Server Error) 100 Virtual server activation failed
101 Virtual server activation job timed out

Example HTTP interaction

POST /api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/operations/activate HTTP/1.1

x-api-session: 1f6hv807yexwhfyk1p8ygrc8876y48adda2dfpvuz4t9iqeo9k

Figure 606. Activate Virtual Server: Request

202 Accepted
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 16 Nov 2011 18:49:07 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri": "/api/jobs/aa24c23e-1083-11e1-87b6-0010184c8334"
}

Figure 607. Activate Virtual Server: Response

Deactivate Virtual Server

The Deactivate Virtual Server operation accepts a request to asynchronously deactivate the identified
virtual server. If there is already a deactivate request active for the identified virtual server, it will be
canceled and the action requested by this subsequent invocation will be performed instead.

Chapter 15. Virtualization management 1121

 Level 04a

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/operations/deactivate

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Request body contents

An optional request body can be specified as a JSON object with the following field:

Field name Type Rqd/Opt Description

shutdown-timeout Integer Optional Amount of time, in seconds, to allow a virtual server to shutdown.
After the elapsed time has passed, the virtual server will be
forcefully terminated.

The value may be -1 to indicate to wait “forever” or any integer

value between 0 and 86400 to specify an exact wait time in seconds.

Specifying this property will cause the deactivate operation to use

this value, regardless of the setting of the use-hypervisor-shutdown-
timeout property of the virtual server.

Response body contents

Once the deactivation 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 deactivation status updates.

Asynchronous result description

Once the deactivation job 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 Deactivate Virtual Server
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 operation description below. The job-results field is null for asynchronous virtual server
deactivation jobs.

Description
This operation asynchronously deactivates the identified virtual server. If the URI does not identify a
valid virtual server a 404 (Not Found) status code is returned. If the user does not have authority to
perform the Deactivate action, a 403 (Forbidden) status code is returned.

The virtual server deactivation job is then initiated and a 202 (Accepted) status code is returned. The
response body includes a URI that may be queried to retrieve the status of the deactivation job. See
“Query Job Status” on page 80 for information on how to query job status. When the deactivate job has
completed, an asynchronous result message is sent, including “Job status and reason codes” on page
1123.

1122 HMC Web Services API

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server
v Action/task permission to the Deactivate 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 1122.

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 API user does not have access action permission to Activate.
404 (Not Found) 1 A virtual server with object-id {virtual-server-id} does not exist on HMC or
API user does not have object-access permission for it.
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

HTTP error status Reason
code code Description
200 (OK) N/A Deactivation completed successfully
500 (Server Error) 100 Virtual server deactivation failed
101 Virtual server deactivation job timed out

Example HTTP interaction

POST /api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/operations/deactivate HTTP/1.1

x-api-session: 1f6hv807yexwhfyk1p8ygrc8876y48adda2dfpvuz4t9iqeo9k

Figure 608. Deactivate Virtual Server: Request

Chapter 15. Virtualization management 1123

 Level 04a

202 Accepted
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 16 Nov 2011 18:50:49 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri": "/api/jobs/e6eb3504-1083-11e1-87b6-0010184c8334"
}

Figure 609. Deactivate Virtual Server: Response

Mount Virtual Media

The Mount Virtual Media operation starts an asynchronous operation to mount the specified
zManager-provided ISO to the identified PowerVM or x Hyp virtual server. This operation is not
supported for PR/SM and z/VM virtual servers.

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/operations/mount-virtual-media

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Request body contents

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

Field name Type Description

iso String The ID of the zManager-provided ISO to mount to the virtual server. Values:
Enum v "gpmp"– Guest Platform Performance Management ISO
v "virtio" – RedHat VirtIO driver CD

Asynchronous result description

Once the mount job 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 Mount Virtual Media 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 operation description below. The job-results field is null for asynchronous mount virtual
media jobs.

Description
The Mount Virtual Media operation starts an asynchronous operation to mount the specified
zManager-provided ISO to the identified PowerVM or x Hyp virtual server. This operation is not
supported for PR/SM and z/VM virtual servers.

Virtual media is a virtual DVD drive that can be attached to a virtual server. Because virtual media is
allocated from IBM blade storage instead of on a real media, it may be faster to use than a physical real
device.

1124 HMC Web Services API

 Level 04a

Preloaded ISO images come in two variants. The first is an ISO image that is packaged on the SE, such as
the GPMP Installation Image. When mounting this type of ISO image to the virtual server, the image will
be uploaded from the SE to the hypervisor. The second type is an ISO image preloaded onto the
hypervisor firmware, such as the Red Hat VirtIO Driver Image. When mounting this type of ISO image,
no uploading will occur.

The response from this operation, success or failure, will be presented asynchronously. Once the mount
operation job 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 Mount Virtual Media request.

If the API user does not have action permission for the Virtual Server Details task, a 403 (Forbidden)
status code is returned. A 404 (Not Found) status code is returned if the object-id {virtual-server-id} does
not identify a Virtual Server object to which the API user has object-access permission.

A mount operation cannot be performed when a virtual server or its Virtualization Host is busied by
another operation or when the Virtualization Host status is not "operating". Under these conditions a 409
(Conflict) status code is returned.

The mount virtual media job is then initiated and a 202 (Accepted) status code is returned. The response
body includes a URI that may be queried to retrieve the status of the mount job. See “Query Job Status”
on page 80 for information on how to query job status. When the mount job has completed, an
asynchronous result message is sent, including “Job status and reason codes” on page 1126.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server
v Action/task permission to the Virtual Server Details task.

HTTP status and reason codes

On success, HTTP status code 202 (Accepted) 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.
100 The operation does not support a virtual server of the given type.
403 (Forbidden) 1 API user does not have access action permission to Virtual Server Details
task.
404 (Not Found) 1 A virtual server with object-id {virtual-server-id} does not exist on HMC or
API user does not have object-access permission for it.
409 (Conflict) 2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
101 Parent Virtualization Host has a status value that is not valid to perform the
operation.
105 Parent Virtualization Host object was locked/busy and the request timed
out.

Chapter 15. Virtualization management 1125

 Level 04a

HTTP error status Reason

code code Description
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

HTTP error status Reason
code code Description
200 (OK) N/A Mount completed successfully
500 (Server Error) 100 Mount failed

Usage notes
v The mount operation may take some time as the zManager-provided ISO may need to be internally
uploaded to the hosting virtualization host from other elements in the management hierarchy.
v Upload and mount of user-provided ISOs is supported by the Mount Virtual Media Image operation
available in version 1.2 of the Web Services API.

Example HTTP interaction

POST /api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/operations/mount-virtual-media HTTP/1.1

x-api-session: 29chofb3vqxpijctnd2kf5fiwnfll8z62mq3yomtqjyz8bx2gn
content-type: application/json
content-length: 15
{
"iso": "gpmp"
}

Figure 610. Mount Virtual Media: Request

202 Accepted
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 15 Nov 2011 17:10:50 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri": "/api/jobs/c4e59922-0fac-11e1-bfcd-00215e69dea0"
}

Figure 611. Mount Virtual Media: Response

Mount Virtual Media Image

The Mount Virtual Media Image operation starts a synchronous operation to mount a user-provided ISO
image to the identified PowerVM or x Hyp virtual server. This operation is not supported for PR/SM
and z/VM virtual servers. Virtual media is a virtual DVD drive that can be attached to a virtual server.
Because virtual media is allocated from IBM blade storage instead of on a real media, it may be faster to
use than a physical real device. The contents of the ISO image is specified as binary data in the body of
the POST request.

1126 HMC Web Services API

 Level 04a

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/operations/mount-virtual-media-image

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Query parameters:

Name Type Rqd/Opt Description

image-name String Optional If specified, this will be used as the displayable name and returned as the
mounted-media-name in the virtual server properties. If omitted, the
service will generate a name for this use.

Request body contents

The request body is the binary contents of an ISO image file. A MIME media type of
application/octet-stream should be specified as the content-type on the request.

Description
This operation mounts the provided ISO image content to the identified virtual server.

If the API user does not have action permission for the Virtual Server Details task, a 403 (Forbidden)
status code is returned. A 404 (Not Found) status code is returned if the object-id {virtual-server-id} does
not identify a Virtual Server object to which the API user has object-access permission.

A mount operation cannot be performed when a virtual server or its virtualization host is busied by
another operation or when the virtualization host status is not "operating". Under these conditions a 409
(Conflict) status code is returned.

If the mount completes successfully a 204 (No Content) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server.
v Action/task permission to the Virtual Server 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, 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.
100 The operation does not support a virtual server of the given type.
403 (Forbidden) 1 API user does not have action permission to the Virtual Server Details task.
404 (Not Found) 1 A virtual server with object-id {virtual-server-id} does not exist on HMC or
API user does not have object-access permission for it.

Chapter 15. Virtualization management 1127

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
101 Parent Virtualization Host has a status value that is not valid to perform the
operation.
105 Parent Virtualization Host object was locked/busy and the request timed
out.
500 (Server Error) 100 Mount failed.
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.

Usage notes
v Because the ISO image is transmitted synchronously as part of the request body of this operation, the
time to execute this operation can be expected to be, at least in part, proportional to the size of the ISO
image being uploaded.
v Mount of preloaded ISO images is supported by the Mount Virtual Media operation of the Web
Services API.

Unmount Virtual Media

The Unmount Virtual Media operation unmounts the currently mounted ISO from the identified
PowerVM or x Hyp virtual server. This operation is not supported for PR/SM and z/VM virtual servers.

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/operations/unmount-virtual-media

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Request body contents

An optional request body can be specified as a JSON object with the following fields:

Field name Type Rqd/Opt Description

force Boolean Optional If true, a forced unmount is requested. Otherwise, a normal
unmount is requested. Default is false.

Description
This operation unmounts the currently mounted ISO from the identified virtual server. Note that there
are not separate unmount operations associated with the distinct Mount Virtual Media and Mount
Virtual Media Image operations; this single Unmount Virtual Media operation may be used regardless
of the mount operation used.

If the API user does not have action/task permission for the Virtual Server Details task, a 403
(Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object-id
{virtual-server-id} does not identify a Virtual Server object to which the API user has object-access
permission.

1128 HMC Web Services API

 Level 04a

If a request body is provided with the force request field specified as true, a request is issued to the
virtualization host to attempt to force the unmount even if the media is locked by a guest OS. Otherwise,
a normal unmount operation is performed.

An unmount operation cannot be performed when a virtual server or its virtualization host is busied by
another operation or when the virtualization host status is not "operating". Under these conditions a 409
(Conflict) status code is returned.

The virtual media is then unmounted and a 204 (No Content) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server.
v Action/task permission to the Virtual Server 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, 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.
100 The operation does not support a virtual server of the given type.
403 (Forbidden) 1 API user does not have action permission to the Virtual Server Details task.
404 (Not Found) 1 A virtual server with object-id {virtual-server-id} does not exist on HMC or
API user does not have object-access permission for it.
409 (Conflict) 2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
101 Parent Virtualization Host has a status value that is not valid to perform the
operation.
105 Parent Virtualization Host object was locked/busy and the request timed
out.
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

POST /api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/operations/unmount-virtual-media HTTP/1.1

x-api-session: 29chofb3vqxpijctnd2kf5fiwnfll8z62mq3yomtqjyz8bx2gn

Figure 612. Unmount Virtual Media: Request

Chapter 15. Virtualization management 1129

 Level 04a

204 No Content
date: Tue, 15 Nov 2011 17:10:55 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 613. Unmount Virtual Media: Response

Migrate Virtual Server

The Migrate Virtual Server operation moves the identified PowerVM or x Hyp virtual server to the
target virtualization host. This operation is not supported for PR/SM and z/VM virtual servers.

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/operations/migrate

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Request body contents

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

Field name Type Description

virt-host-id String Object ID of the target Virtualization Host object.

Response body contents

On successful completion, a response body is provided such that the caller may further target the
migrated virtual server.

Field name Type Description

object-uri String/URI The object-uri property of the migrated Virtual Server object on the new
virtualization host.

Description
This operation moves the identified virtual server to a new virtualization host.

Virtual server migration is a composite action consisting of the steps of creating a new virtual server on
the new virtualization host, configuring the new virtual server to correspond to the identified (original)
virtual server, and then deleting the identified virtual server. Upon completion, this operation returns the
object-uri of the new virtual server in the response body. The response also includes a Location header
that provides this URI.

The steps of the composite migration action may be observable through inventory and property change
notifications.

If the API user does not have action permission for the Migrate Virtual Server task, a 403 (Forbidden)
status code is returned. A 404 (Not Found) status code is returned if the object-id {virtual-server-id} does
not identify a Virtual Server object to which the API user has object-access permission. A 400 (Bad

1130 HMC Web Services API

 Level 04a

Request) status code is returned if the request body fails to validate (e.g. the target virtualization host is
of a different type than the current virtualization host).

A migrate operation cannot be performed when the virtual server, its storage-resources, or
virtual-networks are busied by another operation. Migrate is also not possible when the virtual server's
status is something other than "not-operating" or "not-activated" or when its current virtualization host
or the target virtualization host status is "not-communicating" or "status-check". Migration is also not
possible when the virtual server has media mounted. Under any of these conditions a 409 (Conflict)
status code is returned.

Virtual server migration is then attempted. Migration may fail if the user does not have object-access to
the storage resources used by the virtual server's virtual disks. Migration may also fail if the virtual
server has virtual disks and the target virtualization host does not have virtualization host storage
resources for them. If these or other failure occurs, migration fails, the original virtual server is restored,
and a 503 (Service Unavailable) status code is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server
v Object-access permission to the virtual server's virtualization host's hosting-environment
v Object-access permission to the target virtualization host's hosting-environment
v Object-access permission to the storage resources used by the virtual server's virtual disks
v Action/task permission to the Migrate Virtual Server 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” on page 1130.

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.
100 The operation does not support a virtual server of the given type.
104 Target virtualization host is invalid because it is not the same type as the
current virtualization host.
403 (Forbidden) 1 API user does not have action permission to the Migrate Virtual Server task.
404 (Not Found) 1 A Virtual Server object with object-id {virtual-server-id} does not exist on
HMC or API user does not have object-access permission for it or its
virtualization host's hosting-environment.
1 A virtualization host with object-id {virt-host-id} does not exist on HMC or
API user does not have object-access permission for its hosting-environment.

Chapter 15. Virtualization management 1131

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 0 Migration is not possible for a reason other than those indicated by the other
409 (Conflict) reason codes.
1 Virtual server status is not valid to perform the operation (must be either
"not-operating" or "not-activated").
2 Virtual Server object with ID {virtual-server-id} was busy and request timed
out.
101 Parent Virtualization Host has a status value that is not valid to perform the
operation.
103 Virtual server is an invalid target because it has virtual media is mounted.
105 The target virtualization host already has a virtual server with the same
name as the virtual server to be migrated.
106 One or more of the virtual server's storage resources was busy and the
request timed out.
107 One or more of the virtual server's Virtual Network objects was busy and
the request timed out.
108 One or more storage resources used by the virtual server are not available
on the target virtualization host.
503 (Service 0 Migration failed.
Unavailable)
1 The request could not be processed because the HMC is not currently
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.

Initiate Virtual Server Dump

The Initiate Virtual Server Dump operation disruptively stops the identified PowerVM or x Hyp virtual
server and sends an operating system-specific command to begin a memory dump of the operating
system running on the virtual server. This operation is not supported for PR/SM or z/VM virtual
servers.

HTTP method and URI

POST /api/virtual-servers/{virtual-server-id}/operations/initiate-dump

In this request, the URI variable {virtual-server-id} is the object ID of the Virtual Server object.

Description
The Initiate Virtual Server Dump operation disruptively stops the virtual server and initiates a dump.

Virtual server status must not be "not-operating".

This operation disruptively stops the identified virtual server and sends an virtual-server-type-specific
signal to begin a memory dump of the operating system running on the virtual server.

If the API user does not have action permission for the Initiate Virtual Server Dump task, a 403
(Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object-id
{virtual-server-id} does not identify a Virtual Server object to which the API user has object-access
permission. A 400 (Bad Request) status code is returned if the request body fails to validate or if the
operation is not supported for the given type of virtual server.

1132 HMC Web Services API

 Level 04a

A 409 (Conflict) status code is returned if the virtual server status is "not-operating".

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the virtual server
v Action/task permission to the Initiate Virtual Server Dump 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, 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.
100 The operation does not support a virtual server of the given type.
403 (Forbidden) 1 API user does not have action permission to the Initiate Virtual Server
Dump task.
404 (Not Found) 1 A Virtual Server object with object-id {virtual-server-id} does not exist on
HMC or API user does not have object-access permission for it.
409 (Conflict) 1 Virtual server status is not valid to perform the operation (status is
"not-operating").
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

POST /api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/operations/initiate-dump HTTP/1.1

x-api-session: 6cq5qn64f6zv388z20hu6nzpx1ukaqrl4ekri6sgezaxcwgtz0

Figure 614. Initiate Virtual Server Dump: Request

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

<No response body>

Figure 615. Initiate Virtual Server Dump: Response

Inventory service data

Information about the virtual servers managed by the HMC can be optionally included in the inventory
data provided by the Inventory Service.
Chapter 15. Virtualization management 1133
 Level 04a

Inventory entries for Virtual Server objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by inventory class, implicitly via a containing
category, or by default) that objects of the various virtual server type-specific inventory classes are to be
included. An entry for a particular Virtual Server is included only if the API user has object-access
permission to that object and the applicable type-specific inventory class has been specified, as described
in the following table:

Inventory class Includes virtual servers with “type” value

power-vm-virtual-server power-vm

power-vm-virtual-server-common
prsm-virtual-server prsm

prsm-virtual-server-common
x-hyp-virtual-server x-hyp

x-hyp-virtual-server-common
zvm-virtual-server zvm

zvm-virtual-server-common

For each Virtual Server object to be included, the inventory response array includes entry that is a JSON
object with the same contents as is specified in the response body contents section for the Get Virtual
Server Properties operation. That is, the data provided is the same as would be provided if a Get Virtual
Server Properties operation were requested targeting this object. For inventory class names that end with
–common (e.g. power-vm-virtual-server-common), the data is the same as would be provided for a Get
Virtual Sever Properties operation with the properties=common query parameter specified. For the
inventory class names that do not end in –common (e.g. power-vm-virtual-server), the results are the
same as would be provided for a Get Virtual Server Properties operation with no properties query
parameter specified.

1134 HMC Web Services API

 Level 04a

Sample inventory data

{
"acceptable-status": [
"operating"
],
"auto-start": false,
"boot-mode": "normal",
"boot-network-adapter-client-ip": null,
"boot-network-adapter-gateway-ip": null,
"boot-network-adapter-server-ip": null,
"boot-network-adapter-subnet-ip": null,
"boot-sequence": [
"virtual-disk"
],
"class": "virtual-server",
"cpu-perf-mgmt-enabled": true,
"description": "Order processing for the Shimmer floor wax/dessert topping product",
"dlpar-active": false,
"dlpar-enabled": false,
"gpmp-status": "not-operating",
"gpmp-support-enabled": false,
"gpmp-version": "unavailable",
"has-unacceptable-status": true,
"hostname": null,
"initial-dedicated-processors": null,
"initial-memory": 1024,
"initial-processing-units": 0.10000000000000001,
"initial-virtual-processors": 1,
"is-locked": false,
"keylock": "normal",
"mac-prefix": {
"mac-address": "02:ee:6b:6c:70:00",
"prefix-length": 40
},
"maximum-dedicated-processors": null,
"maximum-memory": 1024,
"maximum-processing-units": 7.0,
"maximum-virtual-processors": 7,
"minimum-dedicated-processors": null,
"minimum-memory": 1024,
"minimum-processing-units": 0.10000000000000001,
"minimum-virtual-processors": 1,
"mounted-media-name": null,
"name": "Shimmer orders server",
"network-adapters": [
{

Figure 616. Virtual Server object: Sample inventory data for a virtual server of type "power-vm" (Part 1)

Chapter 15. Virtualization management 1135

 Level 04a

"element-id": "0000",
"element-uri": "/api/virtual-servers/42eecf00-7b47-11e0-bc9e-001f163803de/
network-adapters/0000",
"network-uri": "/api/virtual-networks/9b9fe4f8-75b2-11e0-9219-0010184c8026"
},
{
"element-id": "0010",
"element-uri": "/api/virtual-servers/42eecf00-7b47-11e0-bc9e-001f163803de/
network-adapters/0010",
"network-uri": null
}
],
"object-id": "119338a2-4081-11e0-9e7c-f0def10bff8d",
"object-uri": "/api/virtual-servers/119338a2-4081-11e0-9e7c-f0def10bff8d",
"parent": "/api/virtualization-hosts/baab1cd2-2990-11e0-8d5b-001f163803de",
"processing-mode": "shared",
"status": "not-operating",
"type": "power-vm",
"virtual-disks": [
{
"backing-virtualization-host-storage-resource": "/api/virtualization-hosts/
baab1cd2-2990-11e0-8d5b-001f163803de/virtualization-host-storage-resources/
abfce790-4080-11e0-8486-f0def10bff8d",
"description": "",
"element-id": "11b5b0a8-4081-11e0-8486-f0def10bff8d",
"element-uri": "/api/virtual-servers/119338a2-4081-11e0-9e7c-f0def10bff8d/virtual-disks/
11b5b0a8-4081-11e0-8486-f0def10bff8d",
"name": "Superman5",
"owner": "/api/virtual-servers/119338a2-4081-11e0-9e7c-f0def10bff8d",
"size": 5242880,
"type": "fullpack"
}
],
"workloads": [
"/api/workload-resource-groups/a4019e06-7685-11e0-8fca-0010184c8026"
]
}

Figure 617. Virtual Server object: Sample inventory data for a virtual server of type "power-vm" (Part 2)

1136 HMC Web Services API

 Level 04a

"acceptable-status": [
"operating"
],
"associated-logical-partition": "/api/logical-partitions/0b239aa3-fea1-32e0-a38f-c632e7ee3b0c",
"class": "virtual-server",
"cpu-perf-mgmt-enabled": false,
"description": "",
"gpmp-status": "not-operating",
"gpmp-support-enabled": false,
"gpmp-version": "unavailable",
"has-unacceptable-status": true,
"is-locked": false,
"name": "VMALT2 ",
"network-adapters": [
{
"chpid": "F0",
"css": "0",
"element-id": "OSX 0.F0",
"element-uri": "/api/virtual-servers/d44575cc-40ea-11e0-9814-001f163803de/network-adapters/
OSX%200.F0",
"name": "OSX 0.F0",
"type": "osx"
},
{
"chpid": "A0",
"css": "0",
"element-id": "OSX 0.A0",
"element-uri": "/api/virtual-servers/d44575cc-40ea-11e0-9814-001f163803de/network-adapters/
OSX%200.A0",
"name": "OSX 0.A0",
"network-uris": [
"/api/virtual-networks/a9b6f8ce-771f-11e0-b1da-0010184c8026"
],
"type": "osx"
}
],
"object-id": "d44575cc-40ea-11e0-9814-001f163803de",
"object-uri": "/api/virtual-servers/d44575cc-40ea-11e0-9814-001f163803de",
"parent": "/api/virtualization-hosts/bab76208-2990-11e0-8d5b-001f163803de",
"status": "operating",
"type": "prsm",
"workloads": [
"/api/workload-resource-groups/a4019e06-7685-11e0-8fca-0010184c8026"
]
}

Figure 618. Virtual Server object: Sample inventory data for a virtual server of type "prsm"

Chapter 15. Virtualization management 1137

 Level 04a

{
"acceptable-status": [
"operating"
],
"auto-start": false,
"boot-sequence": [
"virtual-media"
],
"class": "virtual-server",
"description": "",
"gpmp-status": "not-operating",
"gpmp-support-enabled": false,
"gpmp-version": "unavailable",
"has-unacceptable-status": true,
"hostname": null,
"initial-memory": 4096,
"initial-virtual-processors": 4,
"is-locked": false,
"mounted-media-name": "ubuntu-11.04-server-i386.iso",
"name": "XVS1",
"network-adapters": [],
"object-id": "a4588932-8648-11e0-bbc1-f0def10bff8d",
"object-uri": "/api/virtual-servers/a4588932-8648-11e0-bbc1-f0def10bff8d",
"parent": "/api/virtualization-hosts/931b25d6-82e1-11e0-b9e4-f0def10bff8d",
"status": "stopping",
"type": "x-hyp",
"virtual-disks": [],
"workloads": [
"/api/workload-resource-groups/a4019e06-7685-11e0-8fca-0010184c8026"
]
}

Figure 619. Virtual Server object: Sample inventory data for a virtual server of type "x-hyp"

1138 HMC Web Services API

 Level 04a

Chapter 16. Storage management

zManager provides a common interface across the different Virtualization Host types and storage types
that it supports. It allows a system administrator to create virtualized storage resources and attach them
to virtual servers. The basic flow for all supported types of Virtualization Hosts and storage resources is
as follows:

The server administrator defines his requirements to the storage administrator (e.g., the number of
storage resources, their type and size information).

The server administrator uses zManager storage management interfaces to export the
virtualization-host-specific information which is required to allow the Storage Area Network (SAN)
administrator to setup the SAN accordingly. This information consists primarily of the Host WWPN List.

When the SAN administrator has finished configuring storage resources, the server administrator can add
these new storage resources to the ensemble for management by performing one or more of the following
actions:
v Triggering discovery of newly detected storage resources for a Virtualization Host
v Compiling a Storage Access List (a file with information about the storage resources, such as unique
name and addressing information) and importing this list into zManager
v Manually adding each storage resource.

zManager offers interfaces to work with all ensemble-managed storage resources. For example, there are
interfaces to:
v List the various storage-related entities (storage resources, Virtualization Host storage resources,
Virtualization Host storage groups and virtual disks)
v List details of the various storage-related entities
v Identify storage resources that are to be managed by zManager
v Grant Virtualization Hosts access to storage resources
v Assign storage resources to a Virtualization Host storage group
v Assign storage resources to virtual servers by creating virtual disks on them.

Terms
Host World Wide Port Name (WWPN) List
The Host WWPN List consists of a list of WWPNs of the Fibre-Channel host ports of each
virtualization host. It can be exported for one or multiple virtualization hosts through a zManager
function. The WWPN list is useful when the system administrator requires additional storage
resources to be configured by the storage administrator. The storage administrator must enter
these WWPNs into the SAN switches and storage controllers in order to allow these specific
WWPNs to access the storage controllers / Logical Units.
Storage Access List (SAL)
The Storage Access List is provided by a storage administrator to a system administrator after
configuring storage resources (e.g., FCP Logical Units). The Storage Access List consists of a
number of host port WWPNs and entries for a configured storage resource with its properties,
such as addressing information, or device type information, in the form of a Comma-Separated
Values (CSV) file. Importing a Storage Access List offers a convenient way for letting zManager
know which hypervisor has access to which storage resource, avoiding the cumbersome and
error-prone process of adding storage resources (and their associated properties) manually.

© Copyright IBM Corp. 2017, 2018 1139

 Level 04a

Storage Resource
An addressable storage entity, allowing a virtualization host to write data to and read data from.
A storage resource may be one of the following: a SCSI Logical Unit, attached via FCP, a file, a
Volume attached via ESCON/FICON.
Virtualization Host Storage Resource
The representation of a storage resource from the perspective of a virtualization host. It is a
storage resource to which the virtualization host has access.
Virtualization Host Storage Group
Representation of a z/VM Storage Group in zManager. It consists of homogeneous storage
resources to which a z/VM virtualization host has access.
Virtual Disk
Virtual storage space provided by a virtualization host to a guest virtual server. A Virtual Disk is
based upon a storage resource, but may be further virtualized by a virtualization host.

Object model overview

Figure 620. Object model

Storage management operations summary

The following tables provide an overview of the operations provided. The tables are organized according
to the scope of the operations listed.
Table 408. Storage management: ensemble-level storage operations
Operation name HTTP method and URI path
“List Storage Resources” on page GET /api/ensembles/{ensemble-id}/storage-resources
1143
“Get Storage Resource Properties” GET /api/storage-resources/{storage-resource-id}
on page 1146
“Create Storage Resource” on POST /api/ensembles/{ensemble-id}/storage-resources
page 1147

1140 HMC Web Services API

 Level 04a

Table 408. Storage management: ensemble-level storage operations (continued)

Operation name HTTP method and URI path
“Update Storage Resource POST /api/storage-resources/{storage-resource-id}
Properties” on page 1149
“Delete Storage Resource” on DELETE /api/storage-resources/{storage-resource-id}
page 1151
“Export World Wide Port Names POST /api/ensembles/{ensemble-id}/operations/export-port-names
List” on page 1153
“Import Storage Access List” on POST /api/ensembles/{ensemble-id}/operations/import-storage-access-list
page 1155
“List Virtualization Host Storage POST /api/storage-resources/{storage-resource-id}/operations/list-
Resources of a Storage Resource” virtualization-host-storage-resources
on page 1157

Table 409. Storage management: virtualization host storage operations

Operation name HTTP method and URI path
“List Virtualization Host HBA GET /api/virtualization-hosts/{virt-host-id}/hba-ports
Ports” on page 1162
“List Virtualization Host Storage GET /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-
Resources” on page 1164 resources
“Get Virtualization Host Storage GET /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-
Resource Properties” on page resources/{virt-host-storage-resource-id}
1167
“Create Virtualization Host POST /api/virtualization-hosts/{virt-host-id}/virtualization-host-
Storage Resource” on page 1171 storage-resources
“Delete Virtualization Host DELETE /api/virtualization-hosts/{virt-host-id}/virtualization-host-
Storage Resource” on page 1174 storage-resources/{virt-host-storage-resource-id}
“Add Virtualization Host Storage POST /api/virtualization-hosts/{virt-host-id}/operations/add-paths
Resource Paths” on page 1176
“Remove Virtualization Host POST /api/virtualization-hosts/{virt-host-id}/operations/remove-paths
Storage Resource Paths” on page
1179
“Discover Virtualization Host POST /api/virtualization-hosts/{virt-host-id}/operations/discover-
Storage Resources” on page 1182 virtualization-host-storage-resources
“List Virtual Disks of a POST /api/virtualization-hosts/{virt-host-id}/operations/list-virtual-
Virtualization Host Storage disks-of-virtualization-host-storage-resource
Resource” on page 1184

Table 410. Storage management: storage group operations

Operation name HTTP method and URI path
“List Virtualization Host Storage GET /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-
Groups” on page 1188 groups
“Get Virtualization Host Storage GET /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-
Group Properties” on page 1190 groups/{virt-host-storage-group-id}
“List Virtualization Host Storage POST /api/virtualization-hosts/{virt-host-id}/operations/list-
Resources in a Virtualization Host virtualization-host-storage-resources-in-group
Storage Group” on page 1192
“Add Virtualization Host Storage POST /api/virtualization-hosts/{virt-host-id}/operations/add-
Resource to Virtualization Host virtualization-host-storage-resource-to-group
Storage Group” on page 1194

Chapter 16. Storage management 1141

 Level 04a

Table 410. Storage management: storage group operations (continued)

Operation name HTTP method and URI path
“Remove Virtualization Host POST /api/virtualization-hosts/{virt-host-id}/operations/remove-
Storage Resource from virtualization-host-storage-resource-from-group
Virtualization Host Storage
Group” on page 1196

Table 411. Storage management: URI variables

Variable Description
{ensemble-id} Object ID of an ensemble object
{virt-host-id} Object ID of a Virtualization Host object
{virtual-server-id} Object ID of a Virtual Server object
{storage-resource-id} Object ID of a Storage Resource object
{virt-host-storage-resource-id} Element ID of a Virtualization Host Storage Resource object
{virt-host-storage-group-id} Element ID of a Virtualization Host Storage Group object

Note: Although virtual disk operations are also storage related, they have a closer affinity to
virtualization management. Thus, they are included within the specification for the “Virtual Server
Object” on page 1036 in Chapter 15, “Virtualization management,” on page 985.

Storage Resource object

A Storage Resource object represents a single physical storage resource available to one or more
Virtualization Hosts in an ensemble.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
but does not provide the operational-status-related properties defined in that schema because it does not
maintain the concept of an operational status.

The following class-specific specializations apply to the other base managed object properties:
Table 412. Storage Resource object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/ The canonical URI path for a Storage Resource object is of the form
URI /api/storage-resources/{storage-resource-id} where
{storage-resource-id} is the value of the object-id property of the
Storage Resource object.
parent — String/ The parent object of a Storage Resource object is an ensemble
URI object.
class — String The class of a Storage Resource object is "storage-resource".
description (w)(pc) String The optional user-supplied description for the storage resource.
(0-256) This is the description that will be displayed on the user interface.
It must consist only of alphanumeric characters, spaces and the
following special characters: “._-”.
name (w)(pc) String The user-supplied name of the storage resource. This is the name
(1-64) that will be displayed on the user interface. It must consist only of
alphanumeric characters, spaces and the following special
characters: “._-”, and it must begin with an alphabetic character.
This name must be unique within the Ensemble.

1142 HMC Web Services API

 Level 04a

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:
Table 413. Storage Resource object: class specific properties
Name Qualifier Type Description
type — String The type of the storage resource. Values:
Enum v "eckd" – An Extended Count Key Data storage resource
v "fcp" – A Fibre-channel attached storage resource
v "zvm-fcp" – A Fibre-channel attached storage resource for use by
z/VM virtualization hosts
size (w)(pc) Long The size of the storage resource. The units for this property are
specified by the allocation-units property.
allocation-units (w) String The units for the size property. Values:
Enum v "bytes"– used only for storage resources whose type property is
"fcp" or "zvm-fcp".
v "cylinders" – used only for storage resources whose type
property is "eckd".
v "unknown"
allocation-status (pc) String The status of the storage resource in terms of its current allocation.
Enum A storage resource is considered to be allocated for use if there is a
virtual disk backed by this storage resource or the storage resource
backs a hypervisor storage resource that is a member of a
virtualization host storage group.

Values:
v "free" – the storage resource is not currently allocated for use.
v "used" – the storage resource is currently allocated for use.
unique-device-id (pc) String The unique device identifier assigned to this storage resource. This
is a worldwide unique identifier based on information about the
device. zManager creates a unique device identifier for each
storage resource whose type property is "fcp". A unique device
identifier is not created for storage resources with a type property
of "eckd" or "zvm-fcp"; for such storage resources, the value of
this property is always null.

Note that even for storage resources with a type property of "fcp",
the value of the property may be null or an empty string. This is
typically the case if zManager has not yet accessed the storage
resource and thus the unique device identifier is not yet known.

Operations
If a storage resource operation accesses a z/VM Virtualization Host and encounters an error while
communicating with the Virtualization Host via SMAPI, the response body is as described in “SMAPI
Error Response Body” on page 1033.

List Storage Resources

The List Storage Resources operation lists the storage resources in the ensemble.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/storage-resources

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object.

Chapter 16. Storage management 1143

 Level 04a

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

Response body contents

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

Field name Type Description

storage-resources Array of Array of storage-resource-basic-info objects, described in the next table. If
objects no storage resources are to be returned, an empty array is provided.

Each storage-resource-basic-info object contains the following fields:

Field name Type Description

object-uri String/ Canonical URI path of the Storage Resource object
URI
name String The name property of the Storage Resource object
type String The type property of the Storage Resource object
Enum

Description
The List Storage Resources operation lists the storage resources in the ensemble. The object URI and
other basic properties are provided for each storage resource.

If the name query parameter is specified, the returned list is limited to those storage resources that have
a name property matching the specified filter pattern. If the name parameter is omitted, this filtering is
not done.

A set of basic properties is returned for each storage resource. See the storage-resource-basic-info object
definition.

A storage resource is included in the list only if the API user has object-access permission for that object.
If the ensemble contains a storage resource to which the API user does not have permission, that object is
omitted from the list, but no error status code results. Note that this could result in an empty list.

The URI path must designate an existing ensemble 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. In
addition, the API user must have action access permission to the Manage Storage Resources task;
otherwise, status code 403 (Forbidden) is returned.

If there are no storage resources in the ensemble, 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 ensemble object specified in the request URI
v Object-access permission to the Storage Resource objects passed in the response body
v Action/task permission to the Manage Storage Resources task.

1144 HMC Web Services API

 Level 04a

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 1144.

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {ensemble-id} does not designate an existing ensemble 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/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026/storage-resources HTTP/1.1

x-api-session: 1rmnds0imna61i3ll0eu7drk7jsec93mvclfbuqdb7xspk2fm5

Figure 621. List Storage Resources: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 04 Aug 2011 13:30:11 GMT
content-type: application/json;charset=UTF-8
content-length: 524
{
"storage-resources": [
{
"name": "erictest",
"object-uri": "/api/storage-resources/a23a998c-9693-11e0-aace-00215e69e3f5",
"type": "fcp"
},
{
"name": "Test2_ECKD",
"object-uri": "/api/storage-resources/8d7da556-6598-11e0-8946-00215e69e3f5",
"type": "eckd"
},
{
"name": "FCP5618",
"object-uri": "/api/storage-resources/b0be5b6e-5ada-11e0-b462-00215e69e3f5",
"type": "zvm-fcp"
}
]
}

Figure 622. List Storage Resources: Response

Chapter 16. Storage management 1145

 Level 04a

Get Storage Resource Properties

The Get Storage Resource Properties operation retrieves the properties of a single Storage Resource
object that is designated by its object ID.

HTTP method and URI

GET /api/storage-resources/{storage-resource-id}

In this request, the URI variable {storage-resource-id} is the object ID of the Storage Resource object for
which properties are to be obtained.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Storage Resource object as defined in the “Data model” on page 1142. 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 Storage Resource Properties operation returns the current properties for the Storage Resource
object specified by {storage-resource-id}.

On successful execution, all of the current properties as defined in “Data model” on page 1142 for the
Storage Resource object are provided in the response body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing Storage Resource 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. In addition, the API user must have action access permission to the Manage Storage Resources
task; otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Storage Resource object specified in the request URI
v Action/task permission to the Manage Storage Resources task.

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.”

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {storage-resource-id} does not designate an existing Storage
Resource object, or the API user does not have object-access permission to it.

1146 HMC Web Services API

 Level 04a

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/storage-resources/6967f806-2023-11e1-9c1e-0010184c8334 HTTP/1.1

x-api-session: 1tcd8u2o682d6diyfqt8q9aafhfxl25d8m87l50yl6osfcje7k

Figure 623. Get Storage Resource Properties: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 06 Dec 2011 16:00:26 GMT
content-type: application/json;charset=UTF-8
content-length: 402
{
"allocation-status": "free",
"allocation-units": "bytes",
"class": "storage-resource",
"description": "SS Ensemble volume V001",
"is-locked": false,
"name": "SS-V0001",
"object-id": "6967f806-2023-11e1-9c1e-0010184c8334",
"object-uri": "/api/storage-resources/6967f806-2023-11e1-9c1e-0010184c8334",
"parent": "/api/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334",
"size": 8589934592,
"type": "fcp",
"unique-device-id": null
}

Figure 624. Get Storage Resource Properties: Response

Create Storage Resource

The Create Storage Resource operation adds a storage resource to the specified ensemble.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/storage-resources

In this request, the URI variable {ensemble-id} is the object ID of the ensemble to which the new storage
resource is to be added.

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The name property of the new storage resource
description String Optional The description property of the new storage resource
size Long Required The size property of the storage resource
type String Required The type property of the storage resource
Enum

Chapter 16. Storage management 1147

 Level 04a

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 Canonical URI path of the Storage Resource object, in the form
/api/storage-resources/{storage-resource-id}

Description
The Create Storage Resource operation identifies a new storage resource to be added to the ensemble
specified by the {ensemble-id} portion of the request URI. Once added to the ensemble, the storage
resource can be managed using the various storage-related zManager functions.

On successful execution, the object-uri field of the response body and the Location response header
identify the new storage resource.

If this operation changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation. Upon success, an Inventory Change notification
is issued.

The URI path must designate an existing ensemble 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. In
addition, the API user must also have action access permission to the Add Storage Resource task;
otherwise, status code 403 (Forbidden) is returned.

If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object specified in the request URI
v Action/task permission to the Add Storage Resource task.

HTTP status and reason codes

On success, HTTP status code 201 (Created) is returned and both the response body and the Location
response header contain the URI of the newly created object.

Otherwise, 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.
8 The name specified for the new storage resource is not unique within the
ensemble.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {ensemble-id} does not designate an existing ensemble object, or
the API user does not have object-access permission to it.

1148 HMC Web Services API

 Level 04a

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

Usage notes
The Create Storage Resource operation performs a portion of the function provided by the Add Storage
Resource subtask of the Manage Storage Resources task. The Add Storage Resource subtask performs
some or all of the functions provided by the following Web Services APIs:
v Create Storage Resource
Creates a Storage Resource object in zManager, representing storage resources (FCP LUNs, or ECKD™
volumes). Each Storage Resource object has a unique name. zManager reports additional storage
resource specific information, such as a unique-device-id, after paths have been added and zManager
was able to access the storage resource.
v Create Virtualization Host Storage Resource
Creates an object in zManager, representing the virtualization host's view on the storage resource.
v Add Virtualization Host Storage Resource Path
Adds a path between a virtualization host and a storage resource.

Note: a path to an FCP storage resource is identified by a host-port-wwpn, target-port-wwpn, and lun.
See Table 415 on page 1161. A path to an ECKD resource is identified by the device number of the
ECKD volume. See Table 416 on page 1162.

Example HTTP interaction

POST /api/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334/storage-resources HTTP/1.1

x-api-session: 1tcd8u2o682d6diyfqt8q9aafhfxl25d8m87l50yl6osfcje7k
content-type: application/json
content-length: 109
{
"description": "New Storage Resource",
"name": "SS-New-Storage-Resource",
"size": 8589934592,
"type": "fcp"
}

Figure 625. Create Storage Resource: Request

201 Created
server: zSeries management console API web server / 1.0
location: /api/storage-resources/6967f806-2023-11e1-9c1e-0010184c8334
cache-control: no-cache
date: Tue, 06 Dec 2011 16:00:26 GMT
content-type: application/json;charset=UTF-8
content-length: 76
{
"object-uri": "/api/storage-resources/6967f806-2023-11e1-9c1e-0010184c8334"
}

Figure 626. Create Storage Resource: Response

Update Storage Resource Properties

The Update Storage Resource Properties operation updates one or more of the writable properties of a
Storage Resource object.

Chapter 16. Storage management 1149

 Level 04a

HTTP method and URI

POST /api/storage-resources/{storage-resource-id}

In this request, the URI variable {storage-resource-id} is the object ID of the Storage Resource object for
which properties are to be updated.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined in the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
The Update Storage Resource Properties operation updates writable properties of the Storage Resource
object specified by {storage-resource-id}.

The request body contains an object with one or more fields with field names that correspond to the
names of properties for this object. 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 without supplying any response body. The request body does not need to specify a value for all
writable properties, but rather can and should contain fields for the properties to be updated. Object
properties for which no input value is provided remain unchanged by this operation.

If the update changes the value of any property for which property-change notifications are due, those
notifications are issued asynchronously to this operation.

The URI path must designate an existing Storage Resource 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. In addition, the API user must have action access permission to the Storage Resources Details
task; otherwise, status code 403 (Forbidden) is returned.

The request body is validated against the data model for this object type to ensure that it 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.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Storage Resource object specified in the request URI
v Action/task permission to the Storage Resources Details task.

HTTP status and reason codes

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

Otherwise, 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.

1150 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.
8 The new name specified for the new storage resource is not unique within
the ensemble.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {storage-resource-id} does not designate an existing Storage
Resource 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

POST /api/storage-resources/6967f806-2023-11e1-9c1e-0010184c8334 HTTP/1.1

x-api-session: 1tcd8u2o682d6diyfqt8q9aafhfxl25d8m87l50yl6osfcje7k
content-type: application/json
content-length: 62
{
"description": "SS Ensemble volume V001",
"name": "SS-V0001"
}

Figure 627. Update Storage Resource Properties: Request

204 No Content
date: Tue, 06 Dec 2011 16:00:26 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 628. Update Storage Resource Properties: Response

Delete Storage Resource

The Delete Storage Resource operation deletes the specified storage resource from the ensemble.

HTTP method and URI

DELETE /api/storage-resources/{storage-resource-id}

In this request, the URI variable {storage-resource-id} is the object ID of the Storage Resource object to be
deleted.

Description
The Delete Storage Resource operation removes a specified storage resource from the ensemble. The
storage resource is identified by the {storage-resource-id} variable in the URI. There must be no
virtualization host storage resources associated with the storage resource to be deleted.

Chapter 16. Storage management 1151

 Level 04a

Upon successfully removing the storage resource, HTTP status code 204 (No Content) is returned and no
response body is provided. An inventory change event is issued asynchronously.

The URI path must designate an existing Storage Resource 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. In addition, the API user must have action access permission to the Remove Storage Resource
task; otherwise, status code 403 (Forbidden) is returned. If there are any virtualization host storage
resources associated with the storage resource, status code 409 (Conflict) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Storage Resource object specified in the request URI
v Action/task permission to the Remove Storage Resource task.

HTTP status and reason codes

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

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {storage-resource-id} does not designate an existing Storage
Resource object, or the API user does not have object-access permission to it.
409 (Conflict) 143 The object cannot be deleted at this time. There is a virtualization host
storage resource associated with the storage resource.

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

Usage notes
v Before a storage resource can be deleted from the ensemble, any virtualization host storage resources
associated with it must first be deleted.

Example HTTP interaction

DELETE /api/storage-resources/6967f806-2023-11e1-9c1e-0010184c8334 HTTP/1.1

x-api-session: 1tcd8u2o682d6diyfqt8q9aafhfxl25d8m87l50yl6osfcje7k

Figure 629. Delete Storage Resource: Request

1152 HMC Web Services API

 Level 04a

204 No Content
date: Tue, 06 Dec 2011 16:00:26 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 630. Delete Storage Resource: Response

Export World Wide Port Names List

The Export World Wide Port Names List operation exports the world wide port names (WWPNs) of the
fibre channel host ports of the specified virtualization hosts.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/operations/export-port-names

In this request, the URI variable {ensemble-id} is the object ID of the ensemble that contains the
virtualization hosts specified in the request body.

Request body contents

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

Field name Type Rqd/Opt Description

virtualization- Array of Required Array of canonical URI paths, one for each virtualization host whose
hosts String/URI WWPN list is to be exported

Response body contents

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

Field name Type Description

wwpn-list String The WWPN list in Comma-Separated Values (CSV) format

Description
The Export World Wide Port Names List operation returns the list of host port WWPNs of the
virtualization hosts specified by the virtualization-hosts field of the request body. These virtualization
hosts must be part of the ensemble specified by {ensemble-id}. The list is provided in a JSON object as a
single string in Comma-Separated Values (CSV) format. It will be of the format described in the Import
Storage Access List operation, with only the statement type, Location, and HostWwpn fields filled in.
This result can be used as the basis for a Storage Access List to be supplied as input to the Import
Storage Access List operation.

On successful execution, the WWPN list for the specified virtualization hosts is provided in the response
body, and HTTP status code 200 (OK) is returned.

The URI path must designate an existing ensemble 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. If the
array of virtualization host URIs is empty, status code 400 (Bad Request) is returned. The URIs in the
request body must designate existing Virtualization Host objects and the API user must have

Chapter 16. Storage management 1153

 Level 04a

object-access permission to them; otherwise, status code 404 (Not Found) is returned. The virtualization
hosts must be part of the specified ensemble; otherwise, status code 400 (Bad Request) is returned. In
addition, the API user must have action access permission to the Export WWPNs task; otherwise, status
code 403 (Forbidden) is returned.

The request body is validated against the schema described in “Request body contents” on page 1153. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object specified in the request URI
v Object-access permission to the hosting object of the virtualization hosts specified in the request body
v Action/task permission to the Export WWPNs task.

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 1153.

Otherwise, 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.
146 A virtualization host specified in the request body is not a member of the
ensemble specified in the request URI.
149 The array of virtualization host URIs in the request body is empty.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {ensemble-id} does not designate an existing ensemble object, or
the API user does not have object-access permission to it.
2 A URI specified in the request body does not identify a virtualization host.
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.
2 The request could not be processed because the HMC is not currently
communicating with an element of a zBX needed to perform the requested
operation.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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 creates the same file as the Export Host Port WWPN task. This file can be used as the
basis for a Storage Access List. The Comma-Separated Value format has been chosen because it allows
customers to use spreadsheet applications to display, sort, add or modify data.
1154 HMC Web Services API
 Level 04a

v The List Virtualization Host HBA Ports operation provides similar information in JSON format.

Example HTTP interaction

POST /api/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334/operations/export-port-names HTTP/1.1

x-api-session: 5mkvfjvxt6guptdr5omvc11et4tvazeb684stvvhq4c1aa7w4x
content-type: application/json
content-length: 158
{
"virtualization-hosts": [
"/api/virtualization-hosts/71822c16-0401-11e1-8eda-001f163805d8",
"/api/virtualization-hosts/2f676d90-03f8-11e1-8eda-001f163805d8"
]
}

Figure 631. Export World Wide Port Names List: WWPN list: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 07 Dec 2011 06:47:31 GMT
content-type: application/json;charset=UTF-8
content-length: 394
{
"wwpn-list":
"#Version: 1
#FCP_DEF:,Name,Size,Description,Location,HostWwpn,TargetWwpn,Lun
#ECKD_DEF:,Name,Size,Description,Location,Devno,Volser
#ZVM_FCP_DEF:,Name,Size,Description,Location,Devno,Volser,HostWwpn,TargetWwpn,Lun
FCP,,,,R32:B.2.12,21000024ff24df01
FCP,,,,R32:B.2.12,21000024ff24df00
FCP,,,,R32:B.2.02,21000024ff2b47cb
FCP,,,,R32:B.2.02,21000024ff2b47ca
"
}

Figure 632. Export World Wide Port Names List: WWPN list: Response

Import Storage Access List

The Import Storage Access List operation imports information about storage resources and the
virtualization hosts that have access to them. The Storage Access List (SAL) contains information, such as
host port WWPNs and properties, such as addressing and device type information for configured storage
resources.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/operations/import-storage-access-list

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object on which the Storage
Access List is to be imported.

Request body contents

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

Field name Type Rqd/Opt Description

sal String Required Storage Access List in Comma-Separated Values (CSV) format

Chapter 16. Storage management 1155

 Level 04a

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

Description
The Import Storage Access List operation imports the provided Storage Access List into the ensemble
specified by {ensemble-id}. The Storage Access List specifies paths between host ports and configured
storage resources. It is a convenient way to specify which virtualization hosts have access to each storage
resource.

The Storage Access List logically consists of lines of text, each one being a statement that identifies a
storage resource, a virtualization host that has access to that storage resource and a path for the
virtualization host to use when accessing the storage resource. For the full definition of the Storage
Access List, see the storage access list worksheet described in the appendix in the Ensemble Planning
Guide.

On successful execution, status code 204 (No Content) is returned without supplying a response body.

The URI path must designate an existing ensemble 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. In
addition, the API user must have action access permission to the Import SAL task; otherwise, status code
403 (Forbidden) is returned. All virtualization hosts designated in the Storage Access List are marked
busy for the duration of this request. If any of those virtualization hosts is already marked busy due to
some other operation, then status code 409 (Conflict) is returned.

The request body is validated against the schema described in “Request body contents” on page 1155. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered. In addition, the CSV-formatted SAL designated by the sal field must be
syntactically and semantically correct; otherwise, status code 400 (Bad Request) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object specified in the request URI
v Action/task permission to the Import SAL task.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and no response body is provided.

Otherwise, 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.
140 The CSV-formatted Storage Access List designated by the sal field is not
syntactically and semantically correct, or an error was encountered while
processing a Storage Access List entry. The response body contains a
message with more details.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {ensemble-id} does not designate an existing ensemble object, or
the API user does not have object-access permission to it.

1156 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 2 The operation cannot be performed because a virtualization host designated
by the Storage Access List is currently busy performing some other
operation.
150 The operation cannot be performed because a virtualization host designated
by the Storage Access List is currently busy due to a zBX Move operation.

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 accepts the same data/file as the Import Storage Access List task. This file contains
information about storage resources, virtualization host storage resources, and path information that is
to be added to zManager.
The Comma-Separated Value format has been chosen because it allows customers to use spreadsheet
applications in order to display, sort, add or modify data.
v The Create Storage Resource, Create Virtualization Host Storage Resource, and Add Virtualization
Host Storage Resource Paths operations can be used to provide the same information to zManager in
JSON format.

List Virtualization Host Storage Resources of a Storage Resource

The List Virtualization Host Storage Resources of a Storage Resource operation lists the virtualization
host storage resources that are backed by the storage resource identified in the request URI.

HTTP method and URI

POST /api/storage-resources/{storage-resource-id}/operations/list-virtualization-host-storage-resources

In this request, the URI variable {storage-resource-id} is the object ID of the storage resource.

Response body contents

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

Field name Type Description

virtualization-host- Array of Array of virtualization-host-storage-resource-basic-info objects, as
storage-resources objects described in the next table. If no virtualization host storage resources are
backed by the storage resource, an empty array is provided.

Each virtualization-host-storage-resource-basic-info object contains the following fields:

Field name Type Description

element-uri String/ Canonical URI path of the Virtualization Host Storage Resource object.
URI
name String The name property of the associated Storage Resource object.
type String The type property of the associated Storage Resource object.
Enum

Chapter 16. Storage management 1157

 Level 04a

Description
The List Virtualization Host Storage Resources of a Storage Resource operation returns basic
information about each virtualization host storage resource that is backed by the storage resource
specified by {storage-resource-id}. The element URI and other basic properties are provided for each
virtualization host storage resource. See the virtualization-host-storage-resource-basic-info object
definition.

The URI path must designate an existing Storage Resource object and you must have object-access
permission to it. If any of these conditions is not met, status code 404 (Not Found) is returned. In
addition, you must have action access permission to the Manage Storage Resources action; otherwise,
status code 403 (Forbidden) is returned.

If there are no virtualization host storage resources backed by the storage resource, an empty array is
provided and the operation completes successfully.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Storage Resource object specified in the request URI
v Action/task permission to the Manage Storage Resources task.

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 1157.

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {storage-resource-id} does not designate an existing Storage
Resource 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

POST /api/storage-resources/ca10557a-bf20-11e2-8d27-5cf3fcaf5679/operations/
list-virtualization-host-storage-resources HTTP/1.1
x-api-session: 66c13hnchkn6pzirewro4gxi9vwm6do8r6slo6cqf5ibnkw8q2

Figure 633. List Virtualization Host Storage Resources of a Storage Resource: Request

1158 HMC Web Services API

 Level 04a

200 OK
content-length:445,
server:zSeries management console API web server / 2.0,
cache-control:no-cache,
date:Wed, 26 Jun 2013 01:54:02 GMT,
content-type:application/json;charset=UTF-8

{
"virtualization-host-storage-resources":[
{
"element-uri":"/api/virtualization-hosts/580f90c0-836d-11e1-b3b0-f0def1cb6750/
virtualization-host-storage-resources/c9ce6462-bf20-11e2-9ebe-f0def1cb66b0",
"name":"p93_b1_06_V7000_000004",
"type":"fcp"
},
{
"element-uri":"/api/virtualization-hosts/83ec3aa8-8cc9-11e1-b149-f0def1cb6750/
virtualization-host-storage-resources/8283c9b0-dda4-11e2-b713-f0def1cb6750",
"name":"p93_b1_06_V7000_000004",
"type":"fcp"
}
]
}

Figure 634. List Virtualization Host Storage Resources of a Storage Resource: Response

Inventory service data

Information about the storage resources managed by the HMC can be optionally included in the
inventory data provided by the Inventory Service.

Inventory entries for Storage Resource objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "storage-resource" are to be included. An entry for a particular storage
resource is included only if the API user has object-access permission to that object.

For each Storage Resource object to be included, the inventory response array includes entry that is a
JSON object with the same contents as is specified in the response body contents section for the Get
Storage Resource Properties operation. That is, the data provided is the same as would be provided if a
Get Storage Resource Properties operation were requested targeting this object.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single storage resource. This object would appear as one array entry in the
response array:

Chapter 16. Storage management 1159

 Level 04a

{
"allocation-status": "used",
"allocation-units": "bytes",
"class": "storage-resource",
"description": "2024-0080-e518-4ac0\r\n0000-0000-0000-0000",
"name": "B1010000A",
"object-id": "2d588ee2-25a2-11e0-94a7-0010184c8334",
"object-uri": "/api/storage-resources/2d588ee2-25a2-11e0-94a7-0010184c8334",
"parent": "/api/ensembles/87d73ffc-75b2-11e0-9ba3-0010184c8026",
"size": 10737418240,
"type": "fcp",
"unique-device-id": "3E21360080E5000184AC00000441B4D07449B0F1814 FAStT03IBMfcp"
}

Figure 635. Storage Resource object: Sample inventory data

Virtualization Host Storage Resource object

A virtualization host storage resource represents a storage resource to which the virtualization host has
been granted access. It is the representation of a storage resource from the perspective of a virtualization
host.

Data model
This object includes the following properties:
Table 414. Virtualization Host Storage Resource object properties
Name Qualifier Type Description
element-uri — String/ Canonical URI path of the Virtualization Host Storage Resource
URI object, in the form /api/virtualization-hosts/{virt-host-id}/
virtualization-host-storage-resources/{virt-host-storage-
resource-id} where {virt-host-storage-resource-id} is the value of the
element-id property of this object.
element-id — String (36) The unique identifier for the virtualization host storage resource
instance. This identifier is in the form of a UUID.
parent — String/URI The parent object of a Virtualization Host Storage Resource object is
a Virtualization Host object.
class — String The class of a Virtualization Host Storage Resource object is
"virtualization-host-storage-resource".
name (pc) String The name of the storage resource, as defined in the Storage
Resource object's data model section.
description (pc) String The description for the storage resource, as defined in the Storage
Resource object's data model section.
size (pc) Long The size of the storage resource, as defined in the Storage Resource
object's data model section.
allocation-units — String The units for the size property, as defined in the Storage Resource
Enum object's “Data model” on page 1142.
type — String The type of the storage resource, as defined in the Storage Resource
Enum object's data model section.
storage-resource — String/ Canonical URI path of the Storage Resource object associated with
URI this virtualization host storage resource.

1160 HMC Web Services API

 Level 04a

Table 414. Virtualization Host Storage Resource object properties (continued)

Name Qualifier Type Description
paths (w) Array of Information about the paths by which the storage resource is
objects accessible to this virtualization host. It is an array of
path-information-fcp or path-information-eckd objects. If the
virtualization host has no paths to the storage resource, an empty
array is provided. Note that there can be at most one path for a
virtualization host storage resource whose type property is "eckd".
unique-device-id (pc) String The unique device identifier of the storage resource, as defined in
the Storage Resource object data model. See “Class specific
additional properties” on page 1143.
volume-serial- (pc) String (1-6) The volume serial for this virtualization host storage resource. Only
number present if the type property is "eckd" or "zvm-fcp".
device-number — String (1-4) The device number that the virtualization host uses to access an
ECKD storage resource, or the EDEV (emulated volume) that is
created for FCP storage resources when they get allocated to a
Virtual Server, or added to a Virtualization Host Storage Group. The
string form of a 1-4 digit hexadecimal number. Only present if the
type property is "eckd" or "zvm-fcp".
virtualization-host- (pc) String/URI Canonical URI path of the virtualization host storage group of
storage-group which this virtualization host storage resource is a member or null if
this virtualization host storage resource is not in a virtualization
host storage group. Only present if the type property is "eckd" or
"zvm-fcp".

A path-information-fcp object contains information about a single path by which an FCP storage resource
is accessible to a virtualization host. This object describes a path for a virtualization host storage resource
whose type property is "fcp" or "zvm-fcp".
Table 415. Virtualization Host Storage Resource object: path-information-fcp object properties
Name Type Description
host-port-wwpn String (16) The WWPN of the host port. The string form of a 16-digit hexadecimal number.
controller-port-wwpn String (16) The WWPN of the storage controller port. The string form of a 16-digit
hexadecimal number.
lun String (16) The Logical Unit Number (LUN) of the storage resource. The string form of a
16-digit hexadecimal number.
accessible Boolean Indicates whether the storage resource is currently accessible to the
virtualization host via this path.

Because path accessibility status can be time consuming to determine, by

default such status is omitted when Virtualization Host Storage Resource
properties are returned and instead the value provided for this property is null.
Operations that provide path accessibility status data will specifically indicate
the conditions under which they do so.

A path-information-eckd object contains information about a single path by which an ECKD storage
resource is accessible to a virtualization host. This object describes a path for a virtualization host storage
resource whose type property is "eckd".

Note: the path specified through URM is the device number specified in the system I/O Configuration
for the ECKD volume. It is not to be confused with the path (CHPID) between the system and the
Control Unit.

Chapter 16. Storage management 1161

 Level 04a

Table 416. Virtualization Host Storage Resource object: path-information-eckd object properties
Name Type Description
device-number String The device number of the storage resource. The string form of a 1-4 digit
(1-4) hexadecimal number.
accessible Boolean Indicates whether the storage resource is currently accessible to the
virtualization host via this path.

Because path accessibility status can be time consuming to determine, by

default such status is omitted when Virtualization Host Storage Resource
properties are returned and instead the value provided for this property is null.
Operations that provide path accessibility status data will specifically indicate
the conditions under which they do so.

Operations
If a virtualization host storage resource operation accesses a z/VM virtualization host and encounters an
error while communicating with the virtualization host via SMAPI, the response body is as described in
“SMAPI Error Response Body” on page 1033.

List Virtualization Host HBA Ports

The List Virtualization Host HBA Ports operation lists information about Fibre-Channel HBA (Host Bus
Adapter) ports for a virtualization host.

HTTP method and URI

GET /api/virtualization-hosts/{virt-host-id}/hba-ports

In this request, the URI variable {virt-host-id} is the object ID of the virtualization host.

Response body contents

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

Field name Type Description

hba-ports Array of Information about the virtualization host's HBA ports. It is an array of
objects hba-port-information objects, described in the next table. If no
virtualization host HBA ports are to be returned, an empty array is
provided.

Each hba-port-information object contains the following fields:

Field name Type Description

wwpn String World Wide Port Name (WWPN) of the port.
identifier String Identifier for the port. It contains the device number of the subchannel for
a virtualization host whose type property is "zvm". For Power ASB, an
example is fscsi2. For Intel based ASBs, the identifier starts with
“/dev/...”.

Description
The List Virtualization Host HBA Ports operation lists a virtualization host's HBA ports. All properties
are provided for each port.

1162 HMC Web Services API

 Level 04a

The URI path must designate an existing Virtualization Host 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. In addition, the API user must have action access permission to the Manage Storage Resources
task; otherwise, status code 403 (Forbidden) is returned.

If there are no HBA ports for the virtualization host, an empty list is provided and the operation
completes successfully with HTTP status code 200 (OK).

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Export WWPNs task.

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 1162.

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {virt-host-id} does not designate an existing Virtualization Host
object, or the API user does not have object-access permission to it.
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.
2 The request could not be processed because the HMC is not currently
communicating with an element of a zBX needed to perform the requested
operation.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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/virtualization-hosts/ba97ff30-2990-11e0-8d5b-001f163803de/hba-ports HTTP/1.1

x-api-session: 1rmnds0imna61i3ll0eu7drk7jsec93mvclfbuqdb7xspk2fm5

Figure 636. List Virtualization Host HBA Ports: Request

Chapter 16. Storage management 1163

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 04 Aug 2011 13:30:12 GMT
content-type: application/json;charset=UTF-8
content-length: 210
{
"hba-ports": [
{
"identifier": "fscsi3",
"wwpn": "21000024ff2b47cb"
},
{
"identifier": "fscsi2",
"wwpn": "21000024ff2b47ca"
}
]
}

Figure 637. List Virtualization Host HBA Ports: Response

List Virtualization Host Storage Resources

The List Virtualization Host Storage Resources operation lists the virtualization host storage resources
for a virtualization host.

HTTP method and URI

GET /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-resources

In this request, the URI variable {virt-host-id} is the object ID of the virtualization host.

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
properties String Optional Identifies the properties of each virtualization host storage resource
to be returned. The only supported value is "all", which results in all
properties being returned, including path accessibility status
properties. If this query parameter is omitted, a set of basic
properties is returned.

Response body contents

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

Field name Type Description

virtualization-host- Array of If the properties=all query parameter is specified, an array is provided
storage-resources objects whose elements are the set of virtualization host storage resource
properties that would be returned on a Get Virtualization Host Storage
Resource Properties request with the include-path-accessibility query
parameter specified as true. If the properties query parameter is omitted,
an array of virtualization-host-storage-resource-basic-info objects is
returned, described in the next table. If no virtualization host storage
resources are to be returned, an empty array is provided.

1164 HMC Web Services API

 Level 04a

Each virtualization-host-storage-resource-basic-info object contains the following fields:

Field name Type Description

element-uri String/ Canonical URI path of the Virtualization Host Storage Resource object
URI
name String The name property of the associated Storage Resource object
type String The type property of the associated Storage Resource object
Enum

Description
The List Virtualization Host Storage Resources operation lists a virtualization host's virtualization host
storage resources. The object URI and other basic properties are provided for each virtualization host
storage resource.

If the name query parameter is specified, the returned list is limited to those virtualization host storage
resources that have a name property matching the specified filter pattern. If the name parameter is
omitted, this filtering is not done.

If the properties query parameter is specified, it controls the set of properties returned. A value of "all"
results in all properties being returned, in exactly the same format as would be provided on a Get
Virtualization Host Storage Resource Properties request with the include-path-accessibility query
parameter specified as true. If the properties query parameter is omitted, a set of basic properties is
returned for each virtualization host storage resource. See the virtualization-host-storage-resource-basic-
info object definition. Any value other than all is not valid and results in an HTTP status code 400 (Bad
Request).

The URI path must designate an existing Virtualization Host 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. In addition, the API user must have action access permission to the Manage Storage Resources
task; otherwise, status code 403 (Forbidden) is returned.

The virtualization host designated by the URI path must have a status of "operating", otherwise status
code 409 (Conflict) is returned.

If there are no virtualization host storage resources for the virtualization host, 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 hosting object of the virtualization host specified in the request URI
v Action/task permission to the Manage Storage Resources task.

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 1164.

Otherwise, 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 16. Storage management 1165

 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.
145 A value other than "all" was specified for the properties query parameter, or
this query parameter was specified more than once.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {virt-host-id} does not designate an existing Virtualization Host
object, or the API user does not have object-access permission to it.
409 (Conflict) 1 Virtualization host has a status that is not valid for 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.
2 The request could not be processed because the HMC is not currently
communicating with an element of a zBX needed to perform the requested
operation.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Usage notes
v The information provided about a virtualization host storage resource can optionally include path
accessibility information, i.e. information on whether a path to the storage resources is currently
operational or not. However, determining path accessibility status can be an expensive action,
especially when a virtualization host has one or more non-functional paths as SAN rediscovery is
implicitly triggered in this case. For this reason, an API application should obtain path accessibility
information only if it is required to satisfy the function of the application. If not required, the
application should obtain virtualization host storage resource information using techniques that omit
path accessibility information in order to avoid unnecessary delays.
If path-accessibility information is required for all or many virtualization host storage resources, it may
be significantly faster to obtain that information by making a single request to this operation with the
properties=all parameter specified rather than by making a series of requests to the Get Virtualization
Host Storage Resource Properties operation (with the include-path-accessibility=true parameter
specified) to obtain hat information one resource at a time. This is because overhead due to SAN
rediscovery would be incurred at most one time by using this operation, but might be incurred on each
and ever iterated Get Virtualization Host Storage Resource Properties request.
On the other hand, if path-accessibility information is not required, using this operation with the
properties=all parameter specified may incur unnecessary application delays. Instead, the application
can bypass the determination of path-accessibility status by using this operation with properties=all
omitted to obtain the URIs of the virtualization host's storage resources, and then iterating over those
URIs and making a requests to the Get Virtualization Host Storage Resource Properties operation
with include-path-accessibility=false specified (or defaulted) for each. If the application requires
virtualization host storage resource information for all or many virtualization hosts in the ensemble,
obtaining this information via the Get Inventory operation of the Inventory Service (for the
virtualization host inventory categories) may provide the best performance. This service can provide
data across all virtualization hosts in the ensemble in a single request, and bypasses the potentially
costly determination of path-accessibility status when obtaining storage resource information.

1166 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/virtualization-hosts/ba97ff30-2990-11e0-8d5b-001f163803de/virtualization-host-
storage-resources HTTP/1.1
x-api-session: 1rmnds0imna61i3ll0eu7drk7jsec93mvclfbuqdb7xspk2fm5

Figure 638. List Virtualization Host Storage Resources: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 04 Aug 2011 13:30:12 GMT
content-type: application/json;charset=UTF-8
content-length: 729
{
"virtualization-host-storage-resources": [
{
"element-uri": "/api/virtualization-hosts/ba97ff30-2990-11e0-8d5b-001f163803de/virtualization-
host-storage-resources/dfbf23f0-b7b7-11e0-a46d-f0def152d359",
"name": "B2L0012",
"type": "fcp"
},
{
"element-uri": "/api/virtualization-hosts/ba97ff30-2990-11e0-8d5b-001f163803de/virtualization-
host-storage-resources/ff83dea8-64d1-11e0-b579-f0def10c03f4",
"name": "test1234",
"type": "fcp"
}
]
}

Figure 639. List Virtualization Host Storage Resources: Response

Get Virtualization Host Storage Resource Properties

The Get Virtualization Host Storage Resource Properties operation retrieves the properties of a single
Virtualization Host Storage Resource object.

HTTP method and URI

GET /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-resources/
{virt-host-storage-resource-id}

URI variables

Variable Description
{virt-host-id} Object ID of the virtualization host
{virt-host-storage- Element ID of the Virtualization Host Storage Resource object for which properties are to
resource-id} be obtained

Query parameters

Name Type Rqd/Opt Description

include-path- Boolean Optional If specified as true, the accessibility status of the paths for this
accessibility resource is determined and reported as values of the accessible
property. If specified as false or omitted, this status is not determined
and instead the value of the accessible property is always null.

Chapter 16. Storage management 1167

 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 Virtualization Host Storage Resource object as defined in “Data model” on page 1160.
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 Virtualization Host Storage Resource Properties operation returns the current properties for the
Virtualization Host Storage Resource object that is specified by its object ID {virt-host-id} and the object ID
of the owning virtualization host {virt-host-storage-resource-id}.

On successful execution, all of the current properties as defined in “Data model” on page 1160 for the
Virtualization Host Storage Resource object are provided in the response body and HTTP status code 200
(OK) is returned. If the include-path-accessibility query parameter is specified as true, these properties
include the current path accessibility status of each of the paths for the resource (as the accessible
property). If include-path-accessibility is false (which is the default), this path accessibility status is not
provided and instead the accessible property is always null.

The URI path must designate an existing Virtualization Host object and the API user must have
object-access permission to it. Furthermore, the URI path must designate an existing Virtualization Host
Storage Resource object. If any of these conditions are not met, status code 404 (Not Found) is returned.
In addition, the API user must have action access permission to the Manage Storage Resources task;
otherwise, status code 403 (Forbidden) is returned.

The virtualization host designated by the URI path must have a status of "operating", otherwise status
code 409 (Conflict) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Manage Storage Resources task.

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.”

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.

1168 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object ID {virt-host-id} does not designate an existing Virtualization Host
object, or the API user does not have object-access permission to it.
147 The object ID {virt-host-storage-resource-id} does not designate an existing
Virtualization Host Storage Resource object for the specified virtualization
host.
148 There is no Storage Resource object associated with the Virtualization Host
Storage Resource object identified by the object ID {virt-host-storage-resource-
id}. This is most likely a temporary condition due to a delete operation in
progress on the Storage Resource object.
409 (Conflict) 1 Virtualization host has a status that is not valid for 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.
2 The request could not be processed because the HMC is not currently
communicating with an element of a zBX needed to perform the requested
operation.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Usage notes
v Determining path accessibility status can be an expensive action, especially when a virtualization host
has one or more non-functional paths as SAN rediscovery is implicitly triggered in this case. For this
reason, this operation omits path accessibility status information (the accessible property) by default.
Use the include-path-accessibility query parameter to request that this status be determined and
reported when specifically needed by the application.
v If an application requires path accessibility status information for all or many of the storage resources
of a virtualization host, IBM recommends using the List Virtualization Host Storage Resources
operation with the properties=all query parameter to obtain information for all resources in a single
request as a better performing approach than iteratively using Get Virtualization Host Storage
Resources (with include-path-accessibility=true) one resource at a time. Repeated use of Get
Virtualization Host Storage Resource may incur SAN rediscovery overhead once per request, but such
overhead would be incurred at most once in the single List Virtualization Host of Storage Resources
request.

Example HTTP interaction

GET /api/virtualization-hosts/75ca2d2e-e854-11df-811c-00262df32766/
virtualization-host-storage-resources/c0261be8-ec51-11df-85fe-00262df32766 HTTP/1.1
x-api-session: 3gcd77glemvwq81dlmwxc8i4fwm4udxlby6i2auls4r6g529p1

Figure 640. Get Virtualization Host Storage Resource Properties: Request

Chapter 16. Storage management 1169

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 06 Dec 2011 14:34:00 GMT
content-type: application/json;charset=UTF-8
content-length: 1043
{
"allocation-units": "bytes",
"class": "virtualization-host-storage-resource",
"description": "xiv-41cb",
"element-id": "c0261be8-ec51-11df-85fe-00262df32766",
"element-uri": "/api/virtualization-hosts/75ca2d2e-e854-11df-811c-00262df32766/
virtualization-host-storage-resources/c0261be8-ec51-11df-85fe-00262df32766",
"name": "r93c1_12_hdisk4",
"parent": "/api/virtualization-hosts/75ca2d2e-e854-11df-811c-00262df32766",
"paths": [
{
"accessible": null,
"controller-port-wwpn": "500173800aa50180",
"host-port-wwpn": "2101001b32bf37e3",
"lun": "41cb000000000000"
},
{
"accessible": null,
"controller-port-wwpn": "500173800aa50142",
"host-port-wwpn": "2100001b329f37e3",
"lun": "41cb000000000000"
}
],
"size": 34359738368,
"storage-resource": "/api/storage-resources/c04f6f70-ec51-11df-a5bc-00215e6a0c27",
"type": "fcp",
"unique-device-id": "26112001738000AA5010B072810XIV03IBMfcp"
}

Figure 641. Get Virtualization Host Storage Resource Properties: Response for Virtualization Host of type "power-vm"
or "x-hyp"

1170 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 06 Dec 2011 14:34:01 GMT
content-type: application/json;charset=UTF-8
content-length: 651
{
"allocation-units": "cylinders",
"class": "virtualization-host-storage-resource",
"description": "B71C",
"device-number": "B71C",
"element-id": "e85e91c2-ee02-11e0-a0eb-00262df332b3",
"element-uri": "/api/virtualization-hosts/0e4a5d94-a8c1-11e0-9492-00262df332b3/
virtualization-host-storage-resources/e85e91c2-ee02-11e0-a0eb-00262df332b3",
"name": "B71C",
"parent": "/api/virtualization-hosts/0e4a5d94-a8c1-11e0-9492-00262df332b3",
"paths": [
{
"accessible": null,
"device-number": "B71C"
}
],
"size": 60000,
"storage-resource": "/api/storage-resources/ec9c3852-ee02-11e0-bc09-00215e6a0c27",
"type": "eckd",
"virtualization-host-storage-group": null,
"volume-serial-number": "NNB7BC"
}

Figure 642. Get Virtualization Host Storage Resource Properties: Response for Virtualization Host of type "zvm"

Create Virtualization Host Storage Resource

The Create Virtualization Host Storage Resource operation creates a new virtualization host storage
resource for the virtualization host.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-resources

In this request, the URI variable {virt-host-id} is the object ID of the virtualization host that owns the
new/modified virtualization host storage resource.

Request body contents

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

Field name Type Rqd/Opt Description

storage-resource String/URI Required Canonical URI path of the Storage Resource object to be associated
with this virtualization host storage resource.
paths Array of Optional The path information for the new virtualization host storage resource.
objects It is either an array of new-path-fcp or new-path-eckd objects, as
described in the Add Virtualization Host Storage Resource Path
operation. Note that there can be at most one path for a
virtualization host storage resource whose type property is "eckd".

Chapter 16. Storage management 1171

 Level 04a

Field name Type Rqd/Opt Description

volume-serial- String (1-6) Required if The volume-serial-number property of the Virtualization Host
number creating a Storage Resource object. This field is required when this operation is
VHSR on to create a new virtualization host storage resource on z/VM;
z/VM otherwise, it is optional. This field only applies to storage resources
whose type property is "eckd"or "zvm-fcp". The volume serial
number is written to the ECKD storage resource or FCP storage
resources when they get added to a virtualization host storage group.
The same volume serial number is to be used when creating multiple
virtualization host storage resources for a storage resource.
device-number String (1-4) Required if The device-number property of the Virtualization Host Storage
creating an Resource object. This field is required when this operation is to create
FCP VHSR a new virtualization host storage resource; otherwise, it is optional.
on z/VM This field only applies to storage resources whose type property is
"eckd"or "zvm-fcp". The device number is used to access an ECKD
storage resource, or assigned to the EDEV (emulated volume) that is
created for FCP storage resources when they get allocated to a virtual
server, or added to a virtualization host storage group.

Response body contents

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

Field name Type Description

element-uri String/URI Canonical URI path of the Virtualization Host Storage Resource object, in the
form /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-
resources/{virt-host-storage-resource-id}

Description
The Create Virtualization Host Storage Resource operation creates a new virtualization host storage
resource for the virtualization host specified by the {virt-host-id} portion of the request URI.

Upon successful completion, the element-uri field of the response body and the Location response
header identify the new virtualization host storage resource. An inventory change event is emitted
asynchronously. See “Notifications” on page 1186 for more information.

The URI path must designate an existing Virtualization Host 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. In addition, the API user must have action access permission to the Add Storage Resource task;
otherwise, status code 403 (Forbidden) is returned. The virtualization host is marked busy for the
duration of this request. If it is already marked busy due to some other operation, then status code 409
(Conflict) is returned.

If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Add Storage Resource task.

1172 HMC Web Services API

 Level 04a

HTTP status and reason codes

On success, HTTP status code 201 (Created) is returned and both the response body and the Location
response header contain the URI of the newly created object.

Otherwise, 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.
7 The Storage Resource object URI (storage-resource) in the request body
designates a storage resource that is not compatible with the virtualization
host designated in the request URI ({virt-host-id}).
141 The virtualization host storage resource already has the maximum allowed
number of paths.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {virt-host-id} does not designate an existing Virtualization Host
object, or the API user does not have object-access permission to it.
2 The storage resource URI specified in the request body does not identify a
storage resource.
409 (Conflict) 2 The operation cannot be performed because a virtualization host designated
by the request URI is currently busy performing some other operation.
150 The operation cannot be performed because a virtualization host designated
by the request URI is currently busy due to a zBX Move operation.

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

Usage notes
The Create Virtualization Host Storage Resource operation performs a portion of the function provided
by the Add Storage Resource subtask of the Manage Storage Resources task. The Add Storage Resource
subtask performs some or all of the functions provided by the following Web Services APIs:
v Create Storage Resource
Creates a Storage Resource object in zManager, representing storage resources (FCP LUNs, or ECKD
volumes). Each Storage Resource object has a unique name. zManager reports additional storage
resource specific information, such as a unique-device-id, after paths have been added and zManager
was able to access the storage resource.
v Create Virtualization Host Storage Resource
Creates an object in zManager, representing the hypervisor's view on the storage resource.
v Add Virtualization Host Storage Resource Path
Adds a path between a virtualization host and a storage resource.

Chapter 16. Storage management 1173

 Level 04a

Example HTTP interaction

POST /api/virtualization-hosts/2f029af0-03f8-11e1-8eda-001f163805d8/
virtualization-host-storage-resources HTTP/1.1
x-api-session: 68ps5rqvq1177xtcqz9rnrbmls29mglluq7ni0qlgnwjhup01c
content-type: application/json
content-length: 205
{
"paths": [
{
"controller-port-wwpn": "20240080e5184ac0",
"host-port-wwpn": "21000024ff2b4602",
"lun": "1234001000000000"
}
],
"storage-resource": "/api/storage-resources/17556bdc-2034-11e1-83b8-0010184c8334"
}

Figure 643. Create Virtualization Host Storage Resource: Request

201 Created
server: zSeries management console API web server / 1.0
location: /api/virtualization-hosts/2f029af0-03f8-11e1-8eda-001f163805d8/
virtualization-host-storage-resources/19625098-2034-11e1-b4a5-001f163805d8
cache-control: no-cache
date: Tue, 06 Dec 2011 18:00:24 GMT
content-type: application/json;charset=UTF-8
content-length: 155
{
"element-uri": "/api/virtualization-hosts/2f029af0-03f8-11e1-8eda-001f163805d8/
virtualization-host-storage-resources/19625098-2034-11e1-b4a5-001f163805d8"
}

Figure 644. Create Virtualization Host Storage Resource: Response

Delete Virtualization Host Storage Resource

The Delete Virtualization Host Storage Resource operation removes a specified virtualization host
storage resource from the specified virtualization host.

HTTP method and URI

DELETE /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-resources/
{virt-host-storage-resource-id}

URI variables

Variable Description
{virt-host-id} Object ID of the virtualization host
{virt-host-storage- Element ID of the Virtualization Host Storage Resource object to be deleted
resource-id}

Description
The Delete Virtualization Host Storage Resource operation removes a specified virtualization host
storage resource from the specified virtualization host, removing all related path information at the same
time. The virtualization host storage resource is identified by {virt-host-storage-resource-id} in the URI, and

1174 HMC Web Services API

 Level 04a

the virtualization host is identified by {virt-host-id} in the URI. The virtualization host storage resource
must not be part of a virtualization host storage group, and there must be no virtual disks backed by the
virtualization host storage resource.

Upon successfully removing the virtualization host storage resource, HTTP status code 204 (No Content)
is returned and no response body is provided. An inventory change event is issued asynchronously. See
“Notifications” on page 1186 for more information.

The URI path must designate an existing virtualization host and the API user must have object-access
permission to it. Furthermore, the URI path must designate an existing Virtualization Host Storage
Resource object. If any of these conditions is not met, status code 404 (Not Found) is returned. In
addition, the API user must also have action access permission to the Remove Storage Resource task as
well; otherwise, status code 403 (Forbidden) is returned. If the virtualization host storage resource is part
of a virtualization host storage group or there is a virtual disk backed by the virtualization host storage
resource, then status code 409 (Conflict) is returned. The virtualization host is marked busy for the
duration of the request. If it is already marked busy due to some other operation, then status code 409
(Conflict) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Remove Storage Resource task.

HTTP status and reason codes

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

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {virt-host-id} does not designate an existing Virtualization Host
object, or the API user does not have object-access permission to it.
147 The object ID in the URI {virt-host-storage-resource-id} does not designate an
existing Virtualization Host Storage Resource object for the specified
virtualization host.
409 (Conflict) 2 The operation cannot be performed because the virtualization host
designated by the request URI is currently busy performing some other
operation.
144 The object cannot be deleted at this time. Either the virtualization host
storage resource is part of a virtualization host storage group or a virtual
disk is backed by the virtualization host storage resource.
150 The operation cannot be performed because the virtualization host
designated by the request URI is currently busy due to a zBX Move
operation.

Chapter 16. Storage management 1175

 Level 04a

HTTP error status Reason

code code Description
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Usage note
v While this operation does delete all path information associated with this virtualization host storage
resource, it does not delete the associated storage resource, even if there is no longer a virtualization
host storage resource associated with the storage resource. If the storage resource is no longer needed,
it can be deleted using the Delete Storage Resource operation.

Example HTTP interaction

DELETE /api/virtualization-hosts/2f029af0-03f8-11e1-8eda-001f163805d8/
virtualization-host-storage-resources/19625098-2034-11e1-b4a5-001f163805d8 HTTP/1.1
x-api-session: 68ps5rqvq1177xtcqz9rnrbmls29mglluq7ni0qlgnwjhup01c

Figure 645. Delete Virtualization Host Storage Resource: Request

204 No Content
date: Tue, 06 Dec 2011 18:00:53 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 646. Delete Virtualization Host Storage Resource: Response

Add Virtualization Host Storage Resource Paths

The Add Virtualization Host Storage Resource Paths operation adds a path definition to the
virtualization host storage resource. The path is defined by its two endpoints – the virtualization host is
at one end, and the associated storage resource is at the other end.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/operations/add-paths

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host object.

1176 HMC Web Services API

 Level 04a

Request body contents

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

Field name Type Rqd/Opt Description

virtualization- String/URI Required Canonical URI path of the Virtualization Host storage Resource
host-storage- object.
resource-element-
uri
paths Array of Required Either an array of new-path-fcp or new-path-eckd objects, described
objects in the next table. Note that there can be at most one path for a
virtualization host storage resource whose type property is "eckd".

A new-path-fcp object contains information about a single path by which an FCP storage resource is
accessible to a virtualization host. This object describes a path for a virtualization host storage resource
whose type property is either "fcp"or "zvm-fcp".

Name Type Rqd/Opt Description

host-port-wwpn String (16) Required The WWPN of the host port. The string form of a 16-digit
hexadecimal number.
controller-port- String (16) Required The WWPN of the storage controller port. The string form of a
wwpn 16-digit hexadecimal number.
lun String (16) Required The Logical Unit Number (LUN) of the storage resource. The string
form of a 16-digit hexadecimal number.

A new-path-eckd object contains information about a single path by which an ECKD storage resource is
accessible to a virtualization host. This object describes a path for a virtualization host storage resource
whose type property is "eckd".

Name Type Rqd/Opt Description

device-number String Required The device number of the storage resource. The string form of a 1-4
(1-4) digit hexadecimal number.

Description
The Add Virtualization Host Storage Resource Paths operation adds path definitions to the specified
virtualization host storage resource. The controller-port-wwpn, lun, or device-number, as appropriate,
along with the host-port-wwpn, must identify a configured path of the storage resource associated with
this virtualization host storage resource. If that condition is not met, HTTP status code 400 (Bad Request)
is returned.

Only a single path may be configured for an ECKD virtualization host storage resource. An attempt to
define more than one path for such a resource will result in HTTP status code 400 (Bad Request) being
returned.

The URI path must designate an existing Virtualization Host object, and the API user must have
object-access permission to it. Furthermore, the request body must designate an existing Virtualization
Host storage Resource object. If any of these conditions is not met, status code 404 (Not Found) is
returned. In addition, the API user must have action access permission to the Add Storage Resource task;
otherwise, status code 403 (Forbidden) is returned. The virtualization host is marked busy for the
duration of this request. If it is already marked busy due to some other operation, then status code 409
(Conflict) is returned.

Chapter 16. Storage management 1177

 Level 04a

Upon success, HTTP status code 204 (No Content) is returned and no response body is provided. If this
operation changes the value of the path property, a property-change notification is issued asynchronously
to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Add Storage Resource task.

HTTP status and reason codes

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

Otherwise, 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.
141 The virtualization host storage resource already has the maximum allowed
number of paths.
142 The specified path information does not identify a configured path available
for the virtualization host to use to access the specified storage resource.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID in the URI ({virt-host-id}) does not designate an existing
Virtualization Host object, or the API user does not have object-access
permission to it.
147 The URI in the request body ({virtualization-host-storage-resource}) does not
designate an existing Virtualization Host storage Resource object for the
specified virtualization host.
409 (Conflict) 2 The operation cannot be performed because the virtualization host
designated by the request URI is currently busy performing some other
operation.
150 The operation cannot be performed because the virtualization host
designated by the request URI is currently busy due to a zBX Move
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.
2 The request could not be processed because the HMC is not currently
communicating with an element of a zBX needed to perform the requested
operation.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

1178 HMC Web Services API

 Level 04a

Usage notes
v The Add Virtualization Host Storage Resource Paths operation performs a portion of the function
provided by the Add Storage Resource subtask of the Manage Storage Resources task. The Add
Storage Resource subtask performs some or all of the functions provided by the following Web Services
APIs:
– Create Storage Resource
Creates a Storage Resource object in zManager, representing storage resources (FCP LUNs, or ECKD
volumes). Each Storage Resource object has a unique name. zManager reports additional storage
resource specific information, such as a unique-device-id, after paths have been added and
zManager was able to access the storage resource.
– Create Virtualization Host Storage Resource
Creates an object in zManager, representing the hypervisor's view on the storage resource.
– Add Virtualization Host Storage Resource Path
Adds a path between a virtualization host and a storage resource.
v There is no request to remove a virtualization host storage resource path. In order to remove a path,
the virtualization host storage resource must be deleted and recreated with only the desired path(s).

Example HTTP interaction

POST /api/virtualization-hosts/2f029af0-03f8-11e1-8eda-001f163805d8/operations/add-paths HTTP/1.1

x-api-session: 68ps5rqvq1177xtcqz9rnrbmls29mglluq7ni0qlgnwjhup01c
content-type: application/json
content-length: 315
{
"paths": [
{
"controller-port-wwpn": "20240080e5184ac0",
"host-port-wwpn": "21000024ff2b4603",
"lun": "1234001000000000"
}
],
"virtualization-host-storage-resource-element-uri": "/api/virtualization-hosts/
2f029af0-03f8-11e1-8eda-001f163805d8/virtualization-host-storage-resources/
19625098-2034-11e1-b4a5-001f163805d8"
}

Figure 647. Add Virtualization Host Storage Resource Paths: Request

204 No Content
date: Tue, 06 Dec 2011 18:00:53 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 648. Add Virtualization Host Storage Resource Paths: Response

Remove Virtualization Host Storage Resource Paths

The Remove Virtualization Host Storage Resource Paths operation removes a path definition from the
virtualization host storage resource. The path is defined by its two endpoints – the virtualization host is
at one end, and the associated storage resource is at the other end.

Chapter 16. Storage management 1179

 Level 04a

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/operations/remove-paths

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host object.

Request body contents

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

Field name Type Rqd/Opt Description

virtualization- String/URI Required Canonical URI path of the Virtualization Host Storage Resource
host-storage- object.
resource-element-
uri
paths Array of Required Information about the paths to be removed. It is either an array of
objects path-fcp or path-eckd objects, as described in the next tables. Note
that there can be at most one path for a virtualization host storage
resource whose type property is "eckd".

A path-fcp object contains information about a single path by which an FCP storage resource is accessible
to a virtualization host. This object describes a path for a virtualization host storage resource whose type
property is either "fcp"or "zvm-fcp".

Name Type Rqd/Opt Description

host-port-wwpn String (16) Required The WWPN of the host port. The string form of a 16-digit
hexadecimal number.
controller-port- String (16) Required The WWPN of the storage controller port. The string form of a
wwpn 16-digit hexadecimal number.
lun String (16) Required The Logical Unit Number (LUN) of the storage resource. The string
form of a 16-digit hexadecimal number.

A path-eckd object contains information about a single path by which an ECKD storage resource is
accessible to a virtualization host. This object describes a path for a virtualization host storage resource
whose type property is "eckd". A path-fcp object contains information about a single path by which an
FCP storage resource is accessible to a virtualization host. This object describes a path for a virtualization
host storage resource whose type property is either "fcp" or "zvm-fcp".

Name Type Rqd/Opt Description

device-number String Required The device number of the storage resource. The string form of a 1-4
(1-4) digit hexadecimal number.

Description
The Remove Virtualization Host Storage Resource Paths operation removes path definitions from the
specified virtualization host storage resource. The controller-port-wwpn, lun, or device-number, as
appropriate, along with the host-port-wwpn, must identify a configured path of the storage resource
associated with this virtualization host storage resource. If that condition is not met, HTTP status code
400 (Bad Request) is returned.

The URI path must designate an existing Virtualization Host object, and the API user must have
object-access permission to it. Furthermore, the request body must designate an existing Virtualization
Host Storage Resource object. If any of these conditions is not met, status code 404 (Not Found) is
returned. In addition, the API user must have action access permission to the Remove Storage Resources

1180 HMC Web Services API

 Level 04a

task; otherwise, status code 403 (Forbidden) is returned. The virtualization host is marked busy for the
duration of this request. If it is already marked busy due to some other operation, then status code 409
(Conflict) is returned.

Upon success, HTTP status code 204 (No Content) is returned and no response body is provided. If this
operation changes the value of the path property, a property-change notification is issued asynchronously
to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Manage Storage Resources task.

HTTP status and reason codes

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

Otherwise, 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.
142 The specified path information does not identify a configured path available
for the virtualization host to use to access the specified storage resource.
403 (Forbidden) 1 API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({virt-host-id}) does not designate an existing
Virtualization Host object, or the API user does not have object-access
permission to it, or it is not of a type for which this operation is supported.
147 The URI in the request body ({virtualization-host-storage-resource}) does not
designate an existing Virtualization Host Storage Resource object for the
specified virtualization host.
409 (Conflict) 2 The operation cannot be performed because the virtualization host
designated by the request URI is currently busy performing some other
operation.
150 The operation cannot be performed because the virtualization host
designated by the request URI is currently busy due to a zBX Move
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.
2 The request could not be processed because the HMC is not currently
communicating with an element of a zBX needed to perform the requested
operation.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Chapter 16. Storage management 1181

 Level 04a

Usage notes
v The Remove Virtualization Host Storage Resource Paths operation performs a portion of the function
(remove path) provided by the Details for Storage Resource subtask of the Manage Storage Resources
task. The operation performs some or all of the functions provided by the following Web Services APIs:
– Remove Virtualization Host Storage Resource Path
Removes a path between a virtualization host and a storage resource.
– Gives a warning/error message in case an incorrect path or no path is selected.

Discover Virtualization Host Storage Resources

The Discover Virtualization Host Storage Resources operation discovers the virtualization host storage
resources for a virtualization host.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/operations/discover-virtualization-host-storage-resources

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host object.

Query parameters

Name Type Rqd/Opt Description

prefix String Optional Prefix to use when constructing the value of the name property of
(1-50) each newly discovered virtualization host storage resource. It must
consist only of alphanumeric characters and the following special
characters: “._-”, and it must begin with an alphanumeric character.

Response body contents

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

Field name Type Description

virtualization-host- Array of On successful completion, the response body contains a JSON object that
storage-resources objects provides an array whose elements are discovered-virtualization-host-storage-
resource objects (described in the next table) including path accessibility
status. Field names and data types in the discovered-virtualization-host-
storage-resource are the same as the property names and data types defined
in the data model.

If no virtualization host storage resources are to be returned, an empty array

is provided.

Each discovered-virtualization-host-storage-resource object contains the following fields:

Field name Type Description

parent String/URI The parent property of the Virtualization Host Storage Resource object.
class String The class property of the Virtualization Host Storage Resource object.
name String The name property of the Virtualization Host Storage Resource object.
size Long The size property of the Virtualization Host Storage Resource object.
allocation-units String The allocation-units property of the Virtualization Host Storage Resource
Enum object.
type String The type property of the Virtualization Host Storage Resource object.
Enum

1182 HMC Web Services API

 Level 04a

Field name Type Description

storage-resource String/URI The storage-resource property of the Virtualization Host Storage Resource
object. This will be null unless this virtualization host storage resource
defines an additional path for the virtualization host to access an existing
storage resource.
paths Array of The paths property of the Virtualization Host Storage Resource object.
objects
unique-device-id String The unique-device-id property of the Virtualization Host Storage Resource
object.
volume-serial-number String (1-6) The volume serial for this virtualization host storage resource. Only present
if the type property is "eckd" or "zvm-fcp".
device-number String (1-4) The device number that the virtualization host uses to access an ECKD
storage resource, or the EDEV (emulated volume) that is created for FCP
storage resources when they get allocated to a Virtual Server, or added to a
Virtualization Host Storage Group. The string form of a 1-4 digit
hexadecimal number. Only present if the type property is "eckd" or
"zvm-fcp".

Description
The Discover Virtualization Host Storage Resources operation discovers a virtualization host's
virtualization host storage resources. The current values of the properties for the discovered Virtualization
Host Storage Resource objects, including path accessibility status, are returned as defined in the“Data
model” on page 1160.

If the prefix parameter is omitted, the ensemble's default prefix will be used. The default prefix consists
of the name of the ensemble concatenated with “_SR”.

If there are no discovered virtualization host storage resources for the specified virtualization host, an
empty array is provided and the operation completes successfully.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Discover Storage Resources task.

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 1182.

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {virt-host-id} does not designate an existing Virtualization Host
object, or the API user does not have object-access permission to it.

Chapter 16. Storage management 1183

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 2 The operation cannot be performed because the virtualization host
designated by the request URI is currently busy performing some other
operation.
150 The operation cannot be performed because the virtualization host
designated by the request URI is currently busy due to a zBX Move
operation.

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

List Virtual Disks of a Virtualization Host Storage Resource

The List Virtual Disks of a Virtualization Host Storage Resource operation lists the virtual disks that are
backed by the virtualization host storage resource identified in the request body.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/operations/
list-virtual-disks-of-virtualization-host-storage-resource

In this request, the URI variable {virt-host-id} is the object ID of the virtualization host.

Request body contents

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

Field name Type Rqd/Opt Description

virtualization-host- String/ Required Canonical URI path of the Virtualization Host Storage Resource
storage-resource URI object

Response body contents

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

Field name Type Description

virtual-disks Array of Array of virtual-disk-basic-info objects, as described in the next table. If no
objects virtual disks are backed by the virtualization host storage resource, an
empty array is provided.

Each virtual-disk-basic-info object contains the following fields:

Field name Type Description

element-uri String/ Canonical URI path of the virtual disk object
URI
name String The name property of the virtual disk object
type String The type property of the virtual disk object
Enum

1184 HMC Web Services API

 Level 04a

Description
The List Virtual Disks of a Virtualization Host Storage Resource operation returns basic information
about each virtual disk that is backed by the virtualization host storage resource identified in the request
body. The element URI and other basic properties are provided for each virtual disk. See the
virtual-disk-basic-info object definition.

The URI path must designate an existing virtualization host and the API user must have object-access
permission to its hosting object. Furthermore, the request body must designate an existing Virtualization
Host Storage Resource object of that virtualization host. If any of these conditions is not met, status code
404 (Not Found) is returned. In addition, the API user must have action access permission to the Manage
Storage Resources action; otherwise, status code 403 (Forbidden) is returned.

If there are no virtual disks backed by the virtualization host storage resource, an empty array is
provided and the operation completes successfully.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Manage Storage Resources task.

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 1184.

Otherwise, 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.
403 (Forbidden) 1 API user does not have the required permission to this operation.
404 (Not Found) 1 The object ID {virt-host-id} does not designate an existing Virtualization Host
object, or the API user does not have object-access permission to it.
147 The URI in the request body ({virtualization-host-storage-resource}) does not
designate an existing Virtualization Host Storage Resource object for the
specified virtualization host.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Chapter 16. Storage management 1185

 Level 04a

Example HTTP interaction

POST /api/virtualization-hosts/83ec3aa8-8cc9-11e1-b149-f0def1cb6750/operations
/list-virtual-disks-of-virtualization-host-storage-resource HTTP/1.1
x-api-session: 1tmwwkw0b80axgzun0mwfc7p5uxdv4gn1tbsul8e1sep2u4o2r

{
"virtualization-host-storage-resource": "/api/virtualization-hosts/
83ec3aa8-8cc9-11e1-b149-f0def1cb6750/virtualization-host-storage-resources/
11c32616-a1f5-11e2-893e-f0def1cb6750"
}

Figure 649. List Virtual Disks of a Virtualization Host Storage Resource: Request

"content-length":"180",
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 26 Jun 2013 01:55:06 GMT",
"content-type":"application/json;charset=UTF-8"

{
"virtual-disks":[
{
"element-uri":"/api/virtual-servers/5b529726-983c-11e1-baab-f0def1cb66b0/
virtual-disks/8aa31a04-a205-11e2-a0fd-f0def1cb6750",
"name":"hdisk0",
"type":"fullpack"
}
]
}

Figure 650. List Virtual Disks of a Virtualization Host Storage Resource: Response

Notifications
Changes to properties of a virtualization host storage resource are reflected via a property change
notification designating the virtualization host as the managed object and the virtualization host storage
resource as the element object. The standard property change notification fields (old value, new value and
property name) for each changed property are provided in the notification.

The creation or deletion of a virtualization host storage resource is reflected via an inventory change
notification designating the virtualization host as the managed object and the virtualization host storage
resource as the element object.

Inventory service data

Information about the storage resources associated with a virtualization host can be optionally included
in the inventory data provided by the Inventory Service.

Inventory entries for Virtualization Host Storage Resource objects are included in the response to the
Inventory Service's Get Inventory operation when the request specifies (explicitly by class, implicitly via a
containing category, or by default) that objects of class "virtualization-host" are to be included. An entry
for a particular virtualization host storage resource is included only if the API user has object-access
permission to the owning virtualization host.

1186 HMC Web Services API

 Level 04a

Virtualization Host Storage Group object

A virtualization host storage group is a representation of a z/VM Storage Group. It consists of
homogeneous storage resources to which a z/VM virtualization host has access, and whose
corresponding virtualization host storage resources have been placed into a storage group.

Data model
This object includes the following properties:
Table 417. Virtualization Host Storage Group object properties
Name Qualifier Type Description
element-uri — String/URI Canonical URI path of the Virtualization Host Storage Group object,
in the form /api/virtualization-hosts/{virt-host-id}/
virtualization-host-storage-groups/{virt-host-storage-group-id}
where {virt-host-storage-group-id} is the value of the element-id
property of the virtualization host storage group.
element-id — String (36) The unique identifier for the virtualization host storage group
instance. This identifier is in the form of a UUID.
parent — String/URI The parent object of a Virtualization Host Storage Group object is a
Virtualization Host object.
class — String The class of a Virtualization Host Storage Group object is
"virtualization-host-storage-group".
name — String The name of the virtualization host storage group. It must consist
(1-64) only of alphanumeric characters, spaces and the following special
characters: “._-$”, and it must begin with an alphanumeric character
or “$”.
description — String The description for the virtualization host storage group. It must
(0-256) consist only of alphanumeric characters, spaces and the following
special characters: “._-$”.
free-space — Array of Information about the free space in the virtualization host storage
object group. It is an array of free-space-information objects, each of which
describes an area of free storage in the virtualization host storage
group. If there is no free space in the virtualization host storage
group, an empty array is provided.
virtualization-host — String/URI Canonical URI path of the virtualization host that owns this
virtualization host storage group.

A free-space-information object contains information about an area of storage in the virtualization host
storage group that is currently not in use.
Table 418. Virtualization Host Storage Group object: free-space-information object properties
Name Type Description
device-number String The device number of the virtualization host storage resource which has free
(1-4) space on it. This is the string form of a 1-4 digit hexadecimal number.
size Long The size of the free storage area. The units for this property are specified by the
allocation-units property.
allocation-units String The units for the size property. Values:
Enum v "bytes"
v "cylinders"

Chapter 16. Storage management 1187

 Level 04a

Operations
If a virtualization host storage group operation accesses a z/VM virtualization host and encounters an
error while communicating with the virtualization host via SMAPI, the response body is as described in
“SMAPI Error Response Body” on page 1033.

List Virtualization Host Storage Groups

The List Virtualization Host Storage Groups operation lists the virtualization host storage groups for a
virtualization host.

HTTP method and URI

GET /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-groups

In this request, the URI variable {virt-host-id} is the object ID of the Virtualization Host object.

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.
properties String Optional Identifies the properties of each virtualization host storage group to
be returned. The only supported value is "all", which results in all
properties being returned. If this query parameter is omitted, a set of
basic properties considered to be of general interest is returned.

Response body contents

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

Field name Type Description

virtualization-host- Array of If the properties=all query parameter is specified, an array is provided
storage-groups objects whose elements are the set of virtualization host storage group properties
that would be returned on a Get Virtualization Host Storage Group
Properties operation. If the properties query parameter is omitted, an array
of virtualization-host-storage-group-basic-info objects is returned, described
in the next table. If no virtualization host storage groups are to be returned,
an empty array is provided.

Each virtualization-host-storage-group-basic-info object contains the following fields:

Field name Type Description

element-uri String/URI Canonical URI path of the Virtualization Host Storage Group object
name String The name property of the Virtualization Host Storage Group object

Description
The List Virtualization Host Storage Groups operation lists a virtualization host's virtualization host
storage groups. The element URI and name are provided for each virtualization host storage group.

If the name query parameter is specified, the returned list is limited to those virtualization host storage
groups that have a name property matching the specified filter pattern. If the name parameter is omitted,
this filtering is not performed.

1188 HMC Web Services API

 Level 04a

If the properties query parameter is specified, it controls the set of properties returned. A value of "all"
results in all properties being returned, in exactly the same format as would be provided on a Get
Virtualization Host Storage Group Properties operation. If the properties query parameter is omitted, a
set of basic properties is returned for each virtualization host storage group. See the virtualization-host-
storage-group-basic-info object definition. Any value other than "all" is not valid and results in an HTTP
status code 400 (Bad Request).

The URI path must designate an existing Virtualization Host 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. In addition, the API user must have action access permission to the Manage Storage Resources
task; otherwise, status code 403 (Forbidden) is returned.

If the virtualization host has no virtualization host storage groups, 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 hosting object of the virtualization host specified in the request URI
v Action/task permission to the Manage Storage Resources task.

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 1188.

Otherwise, 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.
145 A value other than "all" was specified for the properties query parameter, or
this query parameter was specified more than once.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {virt-host-id} does not designate an existing Virtualization Host
object, or the API user does not have object-access permission to it, or it is
not of a type for which this operation is supported.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Chapter 16. Storage management 1189

 Level 04a

Example HTTP interaction

GET /api/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4/
virtualization-host-storage-groups HTTP/1.1
x-api-session: 1rmnds0imna61i3ll0eu7drk7jsec93mvclfbuqdb7xspk2fm5

Figure 651. List Virtualization Host Storage Groups: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Thu, 04 Aug 2011 13:30:20 GMT
content-type: application/json;charset=UTF-8
content-length: 683
{
"virtualization-host-storage-groups": [
{
"element-uri": "/api/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4/
virtualization-host-storage-groups/92560990-6aa4-11e0-b3b9-f0def10c03f4",
"name": "$3390$"
},
{
"element-uri": "/api/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4/
virtualization-host-storage-groups/92559f6e-6aa4-11e0-b3b9-f0def10c03f4",
"name": "$3380$"
},
{
"element-uri": "/api/virtualization-hosts/342d80e0-65ff-11e0-acfd-f0def10c03f4/
virtualization-host-storage-groups/925337e2-6aa4-11e0-b3b9-f0def10c03f4",
"name": "$$FCP$$"
}
]
}

Figure 652. List Virtualization Host Storage Groups: Response

Get Virtualization Host Storage Group Properties

The Get Virtualization Host Storage Group Properties operation retrieves the properties of a single
Virtualization Host Storage Group object that is designated by its object ID and the object ID of the
owning virtualization host.

HTTP method and URI

GET /api/virtualization-hosts/{virt-host-id}/virtualization-host-storage-groups/
{virt-host-storage-group-id}

URI variables

Variable Description
{virt-host-id} Object ID of the virtualization host
{virt-host-storage-group- Element ID of the Virtualization Host Storage Group object for which properties are to be
id} obtained

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Virtualization Host Storage Group object as defined in “Data model” on page 1187.

1190 HMC Web Services API

 Level 04a

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 Virtualization Host Storage Group Properties operation returns the current properties for the
Virtualization Host Storage Group object specified by {virt-host-storage-group-id} for the virtualization host
specified by {virt-host-id}.

On successful execution, all of the current properties as defined by the data model for the Virtualization
Host Storage Group object are provided in the response body, and HTTP status code 200 (OK) is
returned.

The URI path must designate an existing Virtualization Host object and the API user must have
object-access permission to it. Furthermore, the URI path must designate an existing Virtualization Host
Storage Group object. If any of these conditions are not met, status code 404 (Not Found) is returned. In
addition, the API user must have action access permission to the Manage Storage Resources task;
otherwise, status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Manage Storage Resources task.

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 1190.

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID in the URI ({virt-host-id}) does not designate an existing
Virtualization Host object, or the API user does not have object-access
permission to it, or it is not of a type for which this operation is supported.
The object ID in the URI ({virt-host-storage-group-id}) does not designate an
existing Virtualization Host Storage Group object for the specified
virtualization host.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Chapter 16. Storage management 1191

 Level 04a

Example HTTP interaction

GET /api/virtualization-hosts/0e4a5d94-a8c1-11e0-9492-00262df332b3/
virtualization-host-storage-groups/305cf1fe-a8cf-11e0-9a45-00262df332b3 HTTP/1.1
x-api-session: 3gcd77glemvwq81dlmwxc8i4fwm4udxlby6i2auls4r6g529p1

Figure 653. Get Virtualization Host Storage Group Properties: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Tue, 06 Dec 2011 14:34:05 GMT
content-type: application/json;charset=UTF-8
content-length: 466
{
"class": "virtualization-host-storage-group",
"description": "$$FCP$$",
"element-id": "305cf1fe-a8cf-11e0-9a45-00262df332b3",
"element-uri": "/api/virtualization-hosts/0e4a5d94-a8c1-11e0-9492-00262df332b3/
virtualization-host-storage-groups/305cf1fe-a8cf-11e0-9a45-00262df332b3",
"free-space": [],
"name": "$$FCP$$",
"parent": "/api/virtualization-hosts/0e4a5d94-a8c1-11e0-9492-00262df332b3",
"virtualization-host": "/api/virtualization-hosts/0e4a5d94-a8c1-11e0-9492-00262df332b3"
}

Figure 654. Get Virtualization Host Storage Group Properties: Response

List Virtualization Host Storage Resources in a Virtualization Host

Storage Group
The List Virtualization Host Storage Resources in a Virtualization Host Storage Group operation lists
the virtualization host storage resources that are members of the specified virtualization host storage
group.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/operations/list-virtualization-host-storage-
resources-in-group

In this request, the URI variable {virt-host-id} is the object ID of the virtualization host that owns the
virtualization host storage group.

Request body contents

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

Field name Type Rqd/Opt Description

virtualization- String/URI Optional Canonical URI path of the virtualization host storage group whose
host-storage-group members are to be listed.

If none is specified, the operation returns information for all

virtualization host storage groups.

1192 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

virtualization-host- Array of Array of virtualization-host-storage-resource-basic-info objects is returned,
storage-resources objects described in the next table. If no virtualization host storage resources are to
be returned, an empty array is provided.

Each virtualization-host-storage-resource-basic-info object contains the following fields:

Field name Type Description

element-uri String/URI Canonical URI path of the Virtualization Host Storage Resource object
name String The name property of the associated Storage Resource object
type String The type property of the associated Storage Resource object
Enum

Description
The List Virtualization Host Storage Resources in a Virtualization Host Storage Group operation
returns basic information about each virtualization host storage resource in the virtualization host storage
group specified by {virtualization-host-storage-group} for the virtualization host specified by {virt-host-id}. If
{virtualization-host-storage-group} is omitted, information from all of the virtualization host's virtualization
host storage group is returned. The object URI and other basic properties are provided for each
virtualization host storage resource.

A set of basic properties is returned for each virtualization host storage resource. See the
virtualization-host-storage-resource-basic-info object definition.

The URI path must designate an existing Virtualization Host object and the API user must have
object-access permission to it. If any of these conditions is not met, status code 404 (Not Found) is
returned. If a URI is specified in the request body and it does not identify a virtualization host storage
group for the specified virtualization host, status code 404 (Not Found) is returned. In addition, the API
user must have action access permission to the Manage Storage Resources action; otherwise, status code
403 (Forbidden) is returned.

If there are no virtualization host storage resources in the target virtualization host storage group(s), 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 hosting object of the virtualization host specified in the request URI
v Action/task permission to the Manage Storage Resources task.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned.

Otherwise, 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 16. Storage management 1193

 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.
403 (Forbidden) 1 The API user does not have the required permission to this operation.
404 (Not Found) 1 The object ID in the URI ({virt-host-id}) does not designate an existing
Virtualization Host object, or the API user does not have object-access
permission to it, or it is not of a type for which this operation is supported.
2 The URI specified in the request body does not identify a virtualization host
storage group for the specified virtualization host.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Add Virtualization Host Storage Resource to Virtualization Host

Storage Group
The Add Virtualization Host Storage Resource to Virtualization Host Storage Group operation adds a
specified virtualization host storage resource to the appropriate virtualization host storage group.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/operations/add-virtualization-host-storage-resource-to-group

In this request, the URI variable {virt-host-id} is the object ID of the virtualization host that owns the
virtualization host storage group.

Request body contents

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

Field name Type Rqd/Opt Description

virtualization- String/URI Optional Canonical URI path of the Virtualization Host Storage Resource
host-storage- object to be added
resource

Response body contents

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

Field name Type Description

element-uri String/URI Canonical URI path of the virtualization host storage group to which the
virtualization host storage resource was added in the form
/api/virtualization-hosts/{virt-host-id}/ virtualization-host-storage-groups/
{virt-host-storage-group-id}.

1194 HMC Web Services API

 Level 04a

Field name Type Description

element-id String Element ID of the Virtualization Host Storage Group object. This is the
{virt-host-storage-group-id} portion of the URI path provided by the
element-uri field.

Description
The Add Virtualization Host Storage Resource to Virtualization Host Storage Group operation adds a
specified virtualization host storage resource to the appropriate virtualization host storage group for the
virtualization host specified by {virt-host-id}.

On successful execution, the virtualization host storage resource identified in “Request body contents” on
page 1194 has been added to the appropriate virtualization host storage group, and HTTP status code 200
(OK) is returned. “Response body contents” on page 1194 identifies the virtualization host storage group
to which the virtualization host storage resource was added.

On successful execution, a property-change notification is issued asynchronously to this operation. See

“Notifications” on page 1197 for more information.

The URI path must designate an existing Virtualization Host 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. If the URI in the request body does not identify a virtualization host storage resource for the
specified virtualization host, status code 404 (Not Found) is returned. In addition, the API user must have
action access permission to the Add Storage Resource to Group task; otherwise, status code 403
(Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Add Storage Resource to Group task.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned.

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID {virt-host-id} does not designate an existing Virtualization Host
object, or the API user does not have object-access permission to it, or it is
not of a type for which this operation is supported.
147 The URI in the request body ({virtualization-host-storage-resource}) does not
designate an existing Virtualization Host Storage Resource object for the
specified virtualization host.

Chapter 16. Storage management 1195

 Level 04a

HTTP error status Reason

code code Description
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Remove Virtualization Host Storage Resource from Virtualization Host

Storage Group
The Remove Virtualization Host Storage Resource from Virtualization Host Storage Group operation
removes a specified virtualization host storage resource from the appropriate virtualization host storage
group.

HTTP method and URI

POST /api/virtualization-hosts/{virt-host-id}/operations/remove-virtualization-host-
storage-resource-from-group

In this request, the URI variable {virt-host-id} is the object ID of the virtualization host that owns the
virtualization host storage resource.

Request body contents

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

Field name Type Rqd/Opt Description

virtualization- String/URI Required Canonical URI path of the Virtualization Host Storage Resource
host-storage- object to be removed
resource

Description
The Remove Virtualization Host Storage Resource from Virtualization Host Storage Group operation
removes a specified virtualization host storage resource from the appropriate virtualization host storage
group for the virtualization host specified by {virt-host-id}.

On successful execution, the virtualization host storage resource identified in “Request body contents”
has been removed from the appropriate virtualization host storage group, and HTTP status code 204 (No
Content) is returned and no response body is provided.

On successful execution, a property-change notification is issued asynchronously to this operation. See

“Notifications” on page 1197 for more information.

The URI path must designate an existing Virtualization Host object, and the API user must have
object-access permission to it. Furthermore, the request body must designate an existing Virtualization
Host Storage Resource object for the specified virtualization host. If any of these conditions is not met,
status code 404 (Not Found) is returned. In addition, the API user must have action access permission to
the Remove Storage Resource from Group task; otherwise, status code 403 (Forbidden) is returned.

1196 HMC Web Services API

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the hosting object of the virtualization host specified in the request URI
v Action/task permission to the Remove Storage Resource from Group task.

HTTP status and reason codes

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

Otherwise, 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.
403 (Forbidden) 1 API user does not have action permission to this operation.
404 (Not Found) 1 The object ID in the URI {virt-host-id} does not designate an existing
Virtualization Host object, or the API user does not have object-access
permission to it, or it is not of a type for which this operation is supported.
147 The URI in the request body ({virtualization-host-storage-resource}) does not
designate an existing Virtualization Host Storage Resource object for the
specified virtualization host.
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.
100 The request could not be processed because the HMC is unable to
communicate with a z/VM virtualization host via SMAPI.
101 The request could not be processed because a command executed on a
z/VM virtualization host via SMAPI failed.

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

Notifications
Changes to properties of a virtualization host storage group are reflected via a property change
notification designating the virtualization host as the managed object and the virtualization host storage
group as the element object. The standard property change notification fields (old value, new value and
property name) for each changed property are provided in the notification.

The addition or removal of a virtualization host storage resource to/from a virtualization host storage
group is reflected via a property change notification designating the virtualization host as the managed
object and the virtualization host storage group as the element object. The changed property identified in
the notification is the virtualization-host-storage-resources property. Note that this is not included as a
property of a virtualization host or a virtualization host storage group in their respective data models;
this property name is only used in the context of these property change notifications. When the
notification is due to the addition of a virtualization host storage resource, the new value in the
notification is the URI path of the added virtualization host storage resource and the old value is null.
When the notification is due to the removal of a virtualization host storage resource, the old value in the
notification is the URI path of the removed virtualization host storage resource and the new value is null.
Thus, unlike other property change notifications, these notifications only identify the delta to the set of

Chapter 16. Storage management 1197

 Level 04a

members of the virtualization host storage group rather than the complete new and old membership sets.
In that sense, they are more like inventory change notifications.

Inventory service data

Information about the storage groups associated with a virtualization host can be optionally included in
the inventory data provided by the Inventory Service.

Inventory entries for Virtualization Host Storage Group objects are included in the response to the
Inventory Service's Get Inventory operation when the request specifies (explicitly by class, implicitly via
a containing category, or by default) that objects of class "virtualization-host" are to be included. An
entry for a particular virtualization host storage group is included only if the API user has object-access
permission to the owning virtualization host.

Usage notes
v The group to which a virtualization host storage resource is added is determined by the type of the
resource. Specifically, FCP resources are added to a group named “$$FCP$$”, 3380 resources are added
to the “$3380$” group, and 3390 resources are added to the “$3390$” group. The user may not specify
any attributes of these groups (e.g., name or description). Thus, there are no writable properties of a
group.
v It is not possible for a virtual disk to span multiple physical storage devices. Thus, the largest virtual
disk that may be created in the virtualization host storage group is limited to the largest free space on
any single virtualization host storage resource in the group. The information describing all such areas
of free space may be useful when defining, or planning to define, multiple virtual disks in the group.

1198 HMC Web Services API

 Level 04a

Chapter 17. Virtual network management

In an ensemble, the Intra-Ensemble Data Network (IEDN) provides the physical, layer 2 network to
which all Z CECs and the blades in the zBX are attached. The zManager Manage Virtual Network tasks
are used to provision the IEDN into virtual networks, and to manage those virtual networks. In an
ensemble, a virtual network is defined by a name, VLAN ID, and zero or more associated network host
interfaces of the following types: virtual server, optimizers, and Top-of-Rack (TOR) switch ports that
attach ISAOPT and external routers. The ensemble has a default virtual network. This virtual network
cannot be deleted, although its VLAN ID can be changed.

To communicate on the IEDN, a network host's network interfaces must be associated with a virtual
network that is managed by zManager. Note that the different types of network hosts have different
requirements for defining and configuring network interfaces. For example, part of the process of
defining a virtual server is to create its virtual network interfaces and associate them with at virtual
network. The same is true for most optimizers. In the case of ISAOPT, the association to a virtual
network is a special case. For ISAOPT, the TOR port that attaches to the coordinator blade's access switch
provides the virtual network interface attachment. In cases where the TOR's external ports are attached to
external networking equipment, such as a router, these TOR ports are required to join one or more virtual
networks defined by zManager.

Virtual network management operations summary

The following tables provide an overview of the operations provided.
Table 419. Virtual network management: operations summary
Operation name HTTP method and URI
“List Virtual Networks” GET /api/ensembles/{ensemble-id}/virtual-networks
on page 1200
“Get Virtual Network GET /api/virtual-networks/{virtual-network-id}
Properties” on page 1202
“Update Virtual Network POST /api/virtual-networks/{virtual-network-id}
Properties” on page 1203
“Create Virtual POST /api/ensembles/{ensemble-id}/virtual-networks
Network” on page 1206
“Delete Virtual DELETE /api/virtual-networks/{virtual-network-id}
Network” on page 1208
“List Members of a GET /api/virtual-networks/{virtual-network-id}/host-vnics
Virtual Network” on
page 1210

Table 420. Virtual network management: URI variables

Variable Description
{ensemble-id} Object ID of an Ensemble object
{virtual-network-id} Object ID of a Virtual Network

Virtual Network object

A Virtual Network object represents a single virtual network.

© Copyright IBM Corp. 2017, 2018 1199

 Level 04a

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
with the following class-specific specialization:
Table 421. Virtual Network object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/URI The canonical URI path for a Virtual Network object is of the form
/api/virtual-networks/{virtual-network-id} where
{virtual-network-id} is the value of the object-id property of the Virtual
Network object.
parent — String/URI The parent of a Virtual Network object is an ensemble object.
class — String The class of a Virtual Network object is "virtual-network".
name (w)(pc) String The name of the Virtual Network object as known by zManager. This
(1-32) name must be unique across virtual networks. If the virtual network
is the default virtual network, then the name cannot be changed. The
name provided must be between 1 and 32 characters.

Class specific additional properties

In addition to the properties defined via included schemas, this object includes the following additional
class-specific properties:
Table 422. Virtual Network object: class specific additional properties
Name Qualifier Type Description
vlan-id (w)(pc) Integer The VLAN ID assigned to this virtual network. Valid VLAN IDs are
in the range of 10-1030.
is-default — Boolean This value is true when the virtual network is the default virtual
network.
has-members (pc) Boolean This value is true when the virtual network has member network
host interfaces attached to it.

List Virtual Networks

The List Virtual Networks operation lists the virtual networks managed by the HMC.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/virtual-networks

In this request, the URI variable {ensemble-id} is the object ID of an Ensemble object.

Query parameters

Name Type Rqd/Opt Description

is-default Boolean Optional Filter pattern to limit returned objects to those that have a matching
is-default property. There is only one default virtual network, and it
is always defined, so when is-default=true is specified, the response
will be an array with one element.
name String Optional Filter pattern (regular expression) to limit returned objects to those
that have a matching name property. If a match is found, the
response will be an array with one element. If no match is found, the
response will be an empty array.

1200 HMC Web Services API

 Level 04a

Response body contents

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

Field name Type Description

virtual-networks Array of Array of nested virtual-network-info objects as described in the next table.
objects

Each nested virtual-network-info object contains the following:

Field name Type Description

object-uri String/ Canonical URI path of the Virtual Network object, in the form
URI /api/virtual-networks/{virtual-network-id}.
name String Display name of the Virtual Network object.

Description
This operation lists the virtual networks that are in the specified ensemble. The response body content is
an array of one or more URI's that represent each virtual network. Each ensemble always has a single
default virtual network with the name of "Default".

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the target Ensemble object
v Action/task permission to the Manage Virtual Networks task.

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, 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.
1 The request included an unrecognized or unsupported query parameter.
403 (Forbidden) 1 The user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Manage Virtual
Networks task is required.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type,
or designates a resource for which the API user does not have object-access
permission.

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

Chapter 17. Virtual network management 1201

 Level 04a

Example HTTP interaction

GET /api/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334/virtual-networks HTTP/1.1

x-api-session: 5tjfpg1d6i7dfria4i52czubs5ptly4fqig2gm3mkluph6ebga

Figure 655. List Virtual Networks: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 05:11:15 GMT
content-type: application/json;charset=UTF-8
content-length: 316
{
"virtual-networks": [
{
"name": "Default",
"object-uri": "/api/virtual-networks/f920171e-03f2-11e1-8e8e-0010184c8334"
},
{
"name": "SS-Web-Store-Network",
"object-uri": "/api/virtual-networks/e58564e0-1723-11e1-aea4-0010184c8334"
}
]
}

Figure 656. List Virtual Networks: Response

Get Virtual Network Properties

Use the Get Virtual Network Properties operation retrieves the properties of a single Virtual Network
object that is designated by the {virtual-network-id}.

HTTP method and URI

GET /api/virtual-networks/{virtual-network-id}

In this request, the URI variable {virtual-network-id} is the object ID of the Virtual Network object for
which properties are to be obtained.

Response body contents

On successful completion, the response body contains a JSON object that provides the current values of
the properties for the Virtual Network object as defined in the data model section above. 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
This operation returns the current properties for the Virtual Network object. In an ensemble, there is at
least one virtual network. This is the default virtual network with the name "Default".

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the target Virtual Network
v Action/task permission to the Manage Virtual Networks task.

1202 HMC Web Services API

 Level 04a

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 1202.

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 user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Manage Virtual
Networks task is required.
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type,
or designates a resource for which the API user does not have object-access
permission.

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/virtual-networks/e58564e0-1723-11e1-aea4-0010184c8334 HTTP/1.1

x-api-session: 5tjfpg1d6i7dfria4i52czubs5ptly4fqig2gm3mkluph6ebga

Figure 657. Get Virtual Network Properties: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 05:11:15 GMT
content-type: application/json;charset=UTF-8
content-length: 368
{
"class": "virtual-network",
"description": "Spacely Sprockets Web Store Network",
"has-members": true,
"is-default": false,
"is-locked": false,
"name": "SS-Web-Store-Network",
"object-id": "e58564e0-1723-11e1-aea4-0010184c8334",
"object-uri": "/api/virtual-networks/e58564e0-1723-11e1-aea4-0010184c8334",
"parent": "/api/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334",
"vlan-id": 1030
}

Figure 658. Get Virtual Network Properties: Response

Update Virtual Network Properties

Use the Update Virtual Network Properties operation updates one or more of the writable properties of
a Virtual Network object.

Chapter 17. Virtual network management 1203

 Level 04a

HTTP method and URI

POST /api/virtual-networks/{virtual-network-id}

In this request, the URI variable {virtual-network-id} is the object ID of the Virtual Network object for
which properties are to be updated.

Request body contents

The request body is expected to contain a JSON object that provides the new values of any writable
property that is to be updated by this operation. Field names and data types in this JSON object are
expected to match the corresponding property names and data types defined by the data model for this
object type. The JSON object can and should omit fields for properties whose values are not to be
changed by this operation.

Description
This operation updates writable properties of the Virtual Network object specified by {virtual-network-id}.

If the vlan-id property is changed, and there are member attached hosts that are not in the proper
operating status to accept a virtual network change, then this request will fail with HTTP status code 409,
and the response body will contain the list of URI's of the network hosts that were unable to accept a
virtual network change. Upon failure, the virtual network's vlan-id is not changed, although requests for
updates to other virtual network properties may have successfully occurred. Upon successful complete,
the virtual network of the attached network hosts virtual network interfaces will be changed.

The request body is validated against the schema described in “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered.

The request body does not need to specify a value for all writable properties, but rather can and should
contain fields for the properties to be updated. Object properties for which no input value is provided
remain unchanged by this operation.

If the update changes the value of any property for which property-change notifications are due, those
notifications are emitted asynchronously to this operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the target Virtual Network object
v Action/task permission to the Edit Virtual Network Properties 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, and the response body is a
standard error response body providing the reason code indicated and associated error message.

1204 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.
129 The default virtual network name of "Default" cannot be changed.
131 The specified name or VLAN ID for a virtual network already exists. This
includes specification of the name "Default".
403 (Forbidden) 1 The user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Manage Virtual
Networks task is required.
404 (Not Found) 1 The object-id in the URI {virtual-network-id} does not designate an existing
resource of the correct type, or designates a resource for which the API user
does not have object-access permission.
409 (Conflict) 130 One or more of the network attached hosts that are members of this virtual
network do not have the proper operating status to support changes to the
virtual network at this time. The URIs of network hosts that were unable to
accept the virtual network change are returned in the response body.

Retry the request.

Currently PowerVM and x Hyp servers have operating status restrictions on

changes to a virtual network. See the network-adapter data model for details
for virtual server status that allows network-adapter changes.
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable request.
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.

On completion where the HTTP status code is 409 (Conflict), the standard error response body contains
an error-details field that provides a list of network hosts that were unable to accept a virtual network
change. The value of the error-details field is a nested object with the following fields:

Field name Type Description

hosts-list Array of Array of URIs that identify the network hosts that were unable to accept a
string/URI virtual network change. The URIs for the network hosts are in the following
forms:

Virtual server: /api/virtual-servers/{virtual-server-id}

Optimizer: /api/blades/{blade-id}

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

Chapter 17. Virtual network management 1205

 Level 04a

Example HTTP interaction

POST /api/virtual-networks/e58564e0-1723-11e1-aea4-0010184c8334 HTTP/1.1

x-api-session: 5tjfpg1d6i7dfria4i52czubs5ptly4fqig2gm3mkluph6ebga
content-type: application/json
content-length: 103
{
"description": "Spacely Sprockets Web Store Network",
"name": "SS-Web-Store-Network",
"vlan-id": 1030
}

Figure 659. Update Virtual Network Properties: Request

204 No Content
date: Fri, 25 Nov 2011 05:11:13 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 660. Update Virtual Network Properties: Response

Create Virtual Network

Use the Create Virtual Network operation creates a new virtual network in the ensemble.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/virtual-networks

In this request, the URI variable {ensemble-id} is the object ID of the Ensemble object to which the Virtual
Network is to be added.

Request body contents

The request body is expected to contain a JSON object with writable network properties of the Virtual
Network object that will be used to create the virtual network:

Field name Type Rqd/Opt Description

name String Required The name of the Virtual Network object as known by zManager.
This name must be unique across all virtual networks, and cannot
be the value "Default" as this name is reserved as the
zManager-defined name of the default virtual network. The name
provided must be between 1 and 32 characters.
description String Optional Display description of the Virtual Network object.
vlan-id Integer Required The VLAN ID assigned to this virtual network. Valid VLAN IDs are
in the range of 10-1030. This value must be unique across all virtual
networks.

1206 HMC Web Services API

 Level 04a

Response body contents

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

Field name Type Description

object-uri String/URI Canonical URI path of the Virtual Network object, in the form
/api/virtual-networks/{virtual-network-id}.

Description
This operation creates a new virtual network in the ensemble specified by {ensemble-id}. A virtual network
with the same vlan-id or name must not already exist in the ensemble.

On successful execution of this operation the virtual network is created using the inputs as specified by
the input fields of the request body. The URI of the new virtual network is provided in the response body
and in a Location response header as well.

The request body is validated against the schema described in the request body contents section. If the
request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the target Ensemble object
v Action/task permission to the New Virtual Networks 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, 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.
0 This error indicates maximum number of virtual networks exceeded or
unavailable resources.
131 The specified name or VLAN ID for a virtual network already exists. This
includes specification of the name "Default".
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform the requested action.
404 (Not Found) 1 The object-id in the URI {ensemble-id} does not designate an existing resource
of the correct type, or designates a resource for which the API user does not
have object-access permission.

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

Chapter 17. Virtual network management 1207

 Level 04a

Example HTTP interaction

POST /api/ensembles/f8fc3a9c-03f2-11e1-ba83-0010184c8334/virtual-networks HTTP/1.1

x-api-session: 5tjfpg1d6i7dfria4i52czubs5ptly4fqig2gm3mkluph6ebga
content-type: application/json
content-length: 71
{
"description": "New Network",
"name": "SS-New-Network",
"vlan-id": 11
}

Figure 661. Create Virtual Network: Request

201 Created
server: zSeries management console API web server / 1.0
location: /api/virtual-networks/e58564e0-1723-11e1-aea4-0010184c8334
cache-control: no-cache
date: Fri, 25 Nov 2011 05:11:13 GMT
content-type: application/json;charset=UTF-8
content-length: 75
{
"object-uri": "/api/virtual-networks/e58564e0-1723-11e1-aea4-0010184c8334"
}

Figure 662. Create Virtual Network: Response

Delete Virtual Network

Use the Delete Virtual Network operation removes a virtual network from an ensemble.

HTTP method and URI

DELETE /api/virtual-networks/{virtual-network-id}

In this request, the URI variable {virtual-network-id} is the object ID of the Virtual Network object to be
deleted.

Description
On successful completion, this operation removes the virtual network specified by the URI from the
ensemble. Any network attached hosts that are members of this virtual network and have the proper
operating status to accept a virtual network change will be removed from the virtual network. Currently
only PowerVM and x Hyp servers require the proper operating status to accept a virtual network change.
If attached hosts cannot be removed from the virtual network, then this request will fail with an HTTP
status code of 409, and the response body will contain the list of the URIs of the network hosts that were
unable to accept a virtual network change. Upon failure, no network attached hosts are removed from the
virtual network, and the virtual network is not deleted.

Note that the default virtual network, "Default", cannot be deleted from the ensemble.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the target Ensemble object
v Action/task permission to the New Virtual Networks task.

1208 HMC Web Services API

 Level 04a

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.
132 The default virtual network cannot be deleted.
404 (Not Found) 1 The object-id in the URI does not designate an existing resource of the
correct type, or designates a resource for which the API user does not have
object-access permission.
409 (Conflict) 130 One or more of the network attached hosts that are members of this virtual
network do not have the proper operating status to support a change to the
virtual network at this time. The URIs of network hosts that were unable to
accept the virtual network change are returned in the response body.

Retry the request.

Currently PowerVM and x Hyp type servers have operating status

restrictions on changes to a virtual network. See the network-adapter data
model for details for virtual server status that allows network-adapter
changes.
503 (Service 1 Communication between the HMC and SE is unavailable. Please retry the
Unavailable) request.
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.

On completion where the HTTP status code is 409 (Conflict), the standard error response body contains
an error-details field that provides a list of network hosts that were unable to accept a virtual network
change. The value of the error-details field is a nested object with the following fields:

Field name Type Description

hosts-list Array of Array of URIs that identify the network hosts that were unable to accept a
string/URI virtual network change. The URIs for the network hosts are in the following
forms:

Virtual server: /api/virtual-servers/{virtual-server-id}

Optimizer: /api/blades/{blade-id}

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

Chapter 17. Virtual network management 1209

 Level 04a

Example HTTP interaction

DELETE /api/virtual-networks/e58564e0-1723-11e1-aea4-0010184c8334 HTTP/1.1

x-api-session: 5tjfpg1d6i7dfria4i52czubs5ptly4fqig2gm3mkluph6ebga

Figure 663. Delete Virtual Network: Request

204 No Content
date: Fri, 25 Nov 2011 05:11:15 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 664. Delete Virtual Network: Response

List Members of a Virtual Network

Use the List Members of a Virtual Network operation lists the members of a Virtual Network.

HTTP method and URI

GET/api/virtual-networks/{virtual-network-id}/host-vnics

In this request, the URI variable {virtual-network-id} is the object ID of the Virtual Network for which
members are to be listed.

Response body contents

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

Field name Type Description

host-vnics Array of Array of nested member-info objects, each element of which identifies an
objects attached network host’s network interface that is a member of this virtual
network. The nested member-info object is described in the next table. If the
virtual network has no network interfaces associated with it then an empty
array is returned.

Each nested member-info object contains the following:

1210 HMC Web Services API

 Level 04a

Field name Type Description

object-uri String/URI A URI of an object or element that identifies an attached network host's
network interface that is a member of this virtual network. A network
interface can be one of the following: A network adapter of a virtual server
or optimizer, or a Top-of-Rack-Switch (TOR) port that is attached to an
ISAOPT optimizer or to an external router. The URI’s for the network
hosts/interfaces are:

Virtual server:

/api/virtual-servers/{virtual-server-id}/network-adapters/{network-
adapter-id}

Optimizer:

/api/blades/{blade-id}/iedn-interfaces/{iedn-interface-id}

TOR:

/api/zbxs/{zbx-id}/top-of-rack-switches/{tor-id}/ports/{port-id}

Description
The List Members of a Virtual Network operation lists the members of a Virtual Network. The members
of a virtual network are network attached hosts' network interfaces which include the following types:
virtual servers' virtual network interfaces, optimizer virtual network interfaces, and Top-of-Rack (TOR)
switch network interfaces (ports).

On successful execution, this operation returns an array of nested objects that identify the members of the
Virtual Network specified by the request URI. This array may be empty if the virtual network has no
associated network hosts. In some cases, a network host may have multiple interfaces associated with this
virtual network.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the target Virtual Network object
v Object-access to the specific member attached network host object
v Action/task permission to the Manage Virtual Networks task.

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 1210.

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 user under which the API request was authenticated is not authorized to
perform the requested operation. Permission to the Manage Virtual
Networks task is required.

Chapter 17. Virtual network management 1211

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The request URI does not designate an existing resource of the correct type,
or designates a resource for which the API user does not have object-access
permission.

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/virtual-networks/e58564e0-1723-11e1-aea4-0010184c8334/host-vnics HTTP/1.1

x-api-session: 5tjfpg1d6i7dfria4i52czubs5ptly4fqig2gm3mkluph6ebga

Figure 665. List Members of a Virtual Network: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Fri, 25 Nov 2011 05:11:15 GMT
content-type: application/json;charset=UTF-8
content-length: 274
{
"host-vnics": [
{
"object-uri": "/api/virtual-servers/588d8c18-0db7-11e1-b1f1-f0def14b63af/
network-adapters/596dd87c-0db7-11e1-9251-f0def14b63af"
},
{
"object-uri": "/api/virtual-servers/576569dc-0db7-11e1-b1f1-f0def14b63af/
network-adapters/582b5d0e-0db7-11e1-b1f1-f0def14b63af"
}
]
}

Figure 666. List Members of a Virtual Network: Response

Inventory service data

Information about the Virtual Networks managed by the HMC can be optionally included in the
inventory data provided by the Inventory Service.

Inventory entries for Virtual Network objects are included in the response to the Inventory Service's Get
Inventory operation when the request specifies (explicitly by class, implicitly via a containing category, or
by default) that objects of class "virtual-network" are to be included. An entry for a particular virtual
network is included only if the API user has object-access permission to that object.

For each Virtual Network object to be included, the inventory response array includes entry that is a
JSON object with the same contents as is specified in the response body contents section for the Get
Virtual Network Properties operation. That is, the data provided is the same as would be provided if a
Get Virtual Network Properties operation were requested targeting this object.

1212 HMC Web Services API

 Level 04a

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single virtual network. This object would appear as one array entry in the
response array:

{
"class": "virtual-network",
"description": "Network for servers of the Shimmer order processing application.",
"has-members": false,
"is-default": false,
"name": "Shimmer Order Processing Network",
"object-id": "e3a366f4-95e6-11e0-85c7-000c29bb873c",
"object-uri": "/api/virtual-networks/e3a366f4-95e6-11e0-85c7-000c29bb873c",
"parent": "/api/ensembles/890b6df2-93a4-11e0-887c-000c29bb873c",
"vlan-id": 1008
}

Figure 667. Virtual Network object: Sample inventory data

Chapter 17. Virtual network management 1213

 Level 04a

1214 HMC Web Services API

 Level 04a

Chapter 18. Workload resource group management

This chapter describes workload resource group management APIs, and provides a data model and
operations for each of the following: workload objects, Performance Policy objects, and performance
management reports.

Overview
Beginning with the IBM z Enterprise System, the Z family extends performance management capability to
both traditional Z and BladeCenter hardware environments. For multi-tier applications that span Z
hardware and BladeCenter hardware, this extended capability enables dynamic adjustments to processor
(CPU) allocations to ensure that those applications are provided with sufficient resources. To manage
hardware resources in the Z environment, you group these resources into workload resource groups and
define performance policies for them. zManager uses these policy definitions to manage the resources for
each workload resource group in an ensemble.

In computing terminology, the usual definition of the term workload is the amount of application
processing that a computer performs at a given time, and this processing usually includes a specific
number of connected users interacting with the running applications. This amount of work often serves
as a benchmark for computer performance.

In contrast, a Z workload resource group, which is sometimes referred to more simply as a “workload”,
is a customer-defined collection to be tracked, managed, and reported as a unit that reflects a business
goal or function. This collection consists of virtualized hardware rather than software resources.
Throughout the Z documentation, the term workload resource group means a collection of logical constructs
called virtual servers that perform a customer-defined collective purpose.

Initially, after Z hardware is installed and the ensemble is configured, all virtual servers are associated
with the default workload resource group and its default performance policy. Workload administrators
use the HMC to create and name the new workload resource groups, and to define which virtual servers
are associated with this workload resource group. A workload's virtual servers can then be further
divided into workload element groups, ensuring availability of each business function.

After a custom workload resource group is defined, an administrator can use ensemble tasks in the HMC
to create performance policies that describe the workload resource group performance objectives and
importance, and to create service classes that set priority for and classify work within a policy. These
values govern performance management. Each workload resource group can have one or more
performance policies that describe the performance objectives and importance. Each performance policy
has service classes that set the priority of and classify resources within the policy. Only one performance
policy within a specific workload resource group can be active at any given time; having multiple policies
with different defined goals gives an administrator the ability to quickly change priorities by merely
activating a different policy. zManager uses the active performance policy and its service classes to
manage how physical resources are applied to the virtual servers associated with the workload resource
group.

The Web Services API provides the same workload resource group management capabilities as those
provided through HMC tasks, including:
v Creating, updating and deleting workload resource groups, performance policies, or service classes.
v Activating a performance policy.

In addition, zManager also continuously collects performance-management data that is available through
a variety of reports that you view through the HMC. By setting a time interval for any report, you can
query historical performance data as it applied over that time period. zManager keeps only the last 36

© Copyright IBM Corp. 2017, 2018 1215

 Level 04a

hours of collected performance data, so that limit defines the maximum duration for reports. Through
HMC tasks, these various reports present performance data in tables, charts or graphs. In many cases,
you can request one report and select data within that report to request more detailed performance data
that is available in another report type. For example, through the HMC you can select the Workloads
Report task to list all workload resource groups defined in the ensemble. From that list, you can select a
specific workload resource group to view a Virtual Server Report that lists all virtual servers defined to
that specific workload resource group.

The Web Services API provide the same performance reports as those provided through HMC tasks,
returning the same data and including the capability to query time intervals. With the zManager API, the
caller requests a specific report through an operations call to generate and return the specific type of
report. Data returned for items in one report can be used in requests for subsequent drill-down report
generation requests for other report types.

For more information about workload resource group and performance management, including sample
reports as they are returned through the HMC, see the Ensemble Workload Resource Group Management
Guide, GC27-2629.

Workload resource group operations summary

The following tables list the workload resource group operations that are provided through the Web
Services API.
Table 423. Workload resource group management: operations summary
Operation name HTTP method and URI path
“List Workload Resource Groups of an GET /api/ensembles/{ensemble-id}/workload-resource-groups
Ensemble” on page 1224
“Get Workload Resource Group GET /api/workload-resource-groups/{workload-id}
Properties” on page 1226
“Create Workload Resource Group” on POST /api/ensembles/{ensemble-id}/workload-resource-groups
page 1228
“Delete Workload Resource Group” on DELETE /api/workload-resource-groups/{workload-id}
page 1231
“Update Workload Resource Group” POST /api/workload-resource-groups/{workload-id}
on page 1232
“List Virtual Servers of a Workload GET /api/workload-resource-groups/{workload-id}/virtual-servers
Resource Group” on page 1234
“Add Virtual Server to a Workload POST /api/workload-resource-groups/{workload-id}/operations/add-
Resource Group” on page 1237 virtual-server
“Remove Virtual Server from a POST /api/workload-resource-groups/{workload-id}/operations/remove-
Workload Resource Group” on page virtual-server
1239
“List Groups of Virtual Servers of a GET /api/workload-resource-groups/{workload-id}/virtual-server
Workload Resource Group” on page groups
1241
“Add Group of Virtual Servers to a POST /api/workload-resource-groups/{workload-id}/operations/add-
Workload Resource Group” on page virtual-server-group
1243
“Remove Group of Virtual Servers POST /api/workload-resource-groups/{workload-id}/operations/remove-
from a Workload Resource Group” on virtual-server-group
page 1245
“List Workload Element Groups of a GET /api/workload-resource-groups/{workload-id}/workload-element-
Workload Resource Group” on page groups
1247

1216 HMC Web Services API

 Level 04a

Table 423. Workload resource group management: operations summary (continued)

Operation name HTTP method and URI path
“Add Workload Element Group to a POST /api/workload-resource-groups/{workload-id}/operations/add-
Workload Resource Group” on page workload-element-group
1248
“Remove Workload Element Group POST /api/workload-resource-groups/{workload-id}/operations/remove-
from a Workload Resource Group” on workload-element-group
page 1250
“List Performance Policies” on page GET /api/workload-resource-groups/{workload-id}/performance-policies
1257
“Get Performance Policy Properties” GET /api/workload-resource-groups/{workload-id}/performance-
on page 1259 policies/{policy-id}
“Create Performance Policy” on page POST /api/workload-resource-groups/{workload-id}/performance-
1262 policies
“Delete Performance Policy” on page DELETE /api/workload-resource-groups/{workload-id}/performance-
1264 policies/{policy-id}
“Update Performance Policy” on page POST /api/workload-resource-groups/{workload-id}/performance-
1266 policies/{policy-id}
“Activate Performance Policy” on page POST /api/workload-resource-groups/{workload-id}/performance-
1269 policies/{policy-id}/operations/activate
“Import Performance Policy” on page POST /api/workload-resource-groups/{workload-id}/operations/import-
1270 performance-policy
“Export Performance Policy” on page POST /api/workload-resource-groups/{workload-id}/performance-
1272 policies/{policy-id}/operations/export
“Generate Workload Resource Groups POST /api/ensembles/{ensemble-id}/performance-management/operations/
Report (Performance Management)” on generate-workload-resource-groups-report
page 1276
“Generate Workload Resource Group POST /api/ensembles/{ensemble-id}/performance-management/operations/
Performance Index Report” on page generate-workload-resource-group-performance-index-report
1280
“Generate Workload Resource Group POST /api/ensembles/{ensemble-id}/performance-management/operations/
Resource Adjustments Report” on page generate-workload-resource-group-resource-adjustments-report
1283
“Generate Virtual Servers Report” on POST /api/ensembles/{ensemble-id}/performance-management/operations/
page 1287 generate-virtual-servers-report
“Generate Virtual Server CPU POST /api/ensembles/{ensemble-id}/performance-management/operations/
Utilization Report” on page 1291 generate-virtual-server-cpu-utilization-report
“Generate Virtual Server Resource POST /api/ensembles/{ensemble-id}/performance-management/operations/
Adjustments Report” on page 1294 generate-virtual-server-resource-adjustments-report
“Generate Hypervisor Report” on page POST /api/ensembles/{ensemble-id}/performance-management/operations/
1299 generate-hypervisor-report
“Generate Hypervisor Resource POST /api/ensembles/{ensemble-id}/performance-management/operations/
Adjustments Report” on page 1307 generate-hypervisor-resource-adjustments-report
“Generate Service Classes Report” on POST /api/ensembles/{ensemble-id}/performance-management/operations/
page 1311 generate-service-classes-report
“Generate Service Class Resource POST /api/ensembles/{ensemble-id}/performance-management/operations/
Adjustments Report” on page 1314 generate-service-class-resource-adjustments-report
“Generate Service Class Hops Report” POST /api/ensembles/{ensemble-id}/performance-management/operations/
on page 1319 generate-service-class-hops-report

Chapter 18. Workload resource group management 1217

 Level 04a

Table 423. Workload resource group management: operations summary (continued)

Operation name HTTP method and URI path
“Generate Service Class Virtual Server POST /api/ensembles/{ensemble-id}/performance-management/operations/
Topology Report” on page 1324 generate-service-class-virtual-server-topology-report
“Generate Load Balancing Report” on POST /api/ensembles/{ensemble-id}/performance-management/operations/
page 1332 generate-load-balancing-report
“List Workload Element Groups of an GET /api/ensembles/{ensemble-id}/workload-element-groups
Ensemble” on page 1337
“Get Workload Element Group GET /api/workload-element-groups/{group-id}
Properties” on page 1338
“Create Workload Element Group” on POST /api/ensembles/{ensemble-id}/workload-element-groups
page 1339
“Delete Workload Element Group” on DELETE /api/workload-element-groups/{group-id}
page 1342
“Update Workload Element Group” on POST /api/workload-element-groups/{group-id}
page 1343
“List Virtual Servers of a Workload GET /api/workload-element-groups/{group-id}/virtual-servers
Element Group” on page 1344
“Add Virtual Server to a Workload POST /api/workload-element-groups/{group-id}/operations/add-virtual-
Element Group” on page 1345 server
“Remove Virtual Server from a POST /api/workload-element-groups/{group-id}/operations/remove-
Workload Element Group” on page virtual-server
1347
“List Availability Policies” on page GET /api/workload-resource-groups/{workload-id}/availability-
1351 policies
“Get Availability Policy Properties” on GET /api/workload-resource-groups/{workload-id}/availability-
page 1353 policies/{policy-id}
“Create Availability Policy” on page POST /api/workload-resource-groups/{workload-id}/availability-
1354 policies
“Delete Availability Policy” on page DELETE /api/workload-resource-groups/{workload-id}/availability-
1356 policies/{policy-id}
“Update Availability Policy” on page POST /api/workload-resource-groups/{workload-id}/availability-
1357 policies/{policy-id}
“Activate Availability Policy” on page POST /api/workload-resource-groups/{workload-id}/ availability-
1359 policies/{policy-id}/operations/activate
“Generate Workload Resource Groups POST /api/ensembles/{ensemble-id}/availability-management/
Report (Ensemble Availability operations/generate-workload-resource-groups-report
Management)” on page 1362
“Generate Workload Resource Group POST /api/ensembles/{ensemble-id}/availability-management/
Availability Status Report” on page operations/generate-workload-resource-group-availability-status-
1365 report
“Generate Virtual Servers Report POST /api/ensembles/{ensemble-id}/availability-management/
(Ensemble Availability Management)” operations/generate-virtual-servers-report
on page 1370
“Generate Availability Status Report” POST /api/ensembles/{ensemble-id}/availability-management/
on page 1373 operations/generate-availability-status-report
“Get Performance Management GET /api/ensembles/{ensemble-id}/performance-management/velocity-
Velocity Level Range Mappings” on level-range-mappings
page 1375

1218 HMC Web Services API

 Level 04a

Table 424. Workload management: URI variables

Variable Description
{ensemble-id} Object ID (UUID) of an ensemble object
{workload-id} Object ID (UUID) of a workload object
{policy-id} ID (UUID) of a Performance Policy object within a workload resource
group
{group-id} Object ID (UUID) of a Workload Element Group object.

Workload Resource Group object

A workload object is a managed object representing a group of virtual servers in an ensemble. Virtual
servers can be managed in workload resource groups either by adding or removing them directly to or
from the workload resource group, or through user-defined managed object groups or workload element
groups. By adding a group to a workload resource group, all of the virtual servers in that group are
implicitly added to the workload resource group. By adding or removing a virtual server to or from a
group, that virtual server is implicitly added to or removed from the workload resource group. A virtual
server can belong to more than one custom workload resource group. Any virtual server that does not
belong to a custom workload resource group is placed in the default workload resource group.

A workload resource group contains a default performance policy as well as any custom performance
policies created for it. Exactly one performance policy is active for a specific workload resource group at
any given time, and is applied to the virtual servers in that workload resource group. The default
workload resource group also has a default performance policy that is always active.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
with the class-specific specialization described in the following tables. Note that this object does not
maintain the concept of an operational status, and therefore does not provide the operational-status-
related properties.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.
Table 425. Workload object: base managed object properties specializations
Name Qualifier Type Description of specialization
object-uri — String/URI The canonical URI path for a workload object is of the form
/api/workload-resource-groups/{workload-id} where
{workload-id} is the value of the object-id property of the
workload object.
object-id — String (36) The unique identifier for the workload resource group
instance. This identifier is in the form of a UUID.
parent — String/URI The parent of a workload resource group is conceptually its
owning ensemble, so the parent value is the canonical URI
path for the ensemble.
class — String The class of a workload object is "workload-resource-group".
name (w) (pc) String The display name specified for the workload resource group,
(1-64) which can be up to 64 characters made up of alphanumeric
characters, blanks, periods, underscores, or dashes. Names
must start with an alphabetic character and end with an
alphabetic character, numeric character, underscore, period, or
dash. Names must be unique to other existing workload
resource groups in the ensemble.

Chapter 18. Workload resource group management 1219

 Level 04a

Table 425. Workload object: base managed object properties specializations (continued)
Name Qualifier Type Description of specialization
description (w) (pc) String Arbitrary text describing the workload resource group in up
(0-256) to 256 characters.
status (sc) String The current status of the workload resource group, which
Enum must be one of the following values:
"compliant"
The contributors to workload compliance are all currently
compliant.
"not-compliant"
One or more of the contributors to the workload
compliance are currently not-compliant.
additional-status (sc) String This property is not supported for workload resource groups
Enum and will not be included in its data model.
acceptable-status (w)(pc) Array of The set of status values that the workload resource group can
String be in and be considered to be in an acceptable (not alert
Enum causing) state. By default, this is "compliant" for workloads,
and "not-compliant", "compliant" for the default workload.

In addition to the properties defined through included schemas, this object includes the additional
class-specific properties in Table 426.
Table 426. Workload object: class-specific properties
Name Qualifier Type Description
is-default — Boolean This value identifies the default workload object. It is true for
the default workload resource group and false for all other
(custom) workload resource group in the ensemble.
category (w) (pc) String Up to 32 characters used to categorize the workload object,
(0-32) often with other workload resource groups within the
ensemble.
virtual-servers (c) (pc) Array of The complete list of all virtual servers in the workload, each
String/URI identified by its URI, including those directly placed as well as
those placed due to membership in a group. (This list
corresponds to the list provided by the List Virtual Servers of
a Workload Resource Group operation.) If the workload
contains no virtual servers, then an empty array is provided.
The virtual severs provided in this list can change as a result
of the Add and Remove Virtual Server or the Add and
Remove Groups operations on the workload.
Note: This property is not returned by the Get Workload
Resource Group Properties operation.
directly-added-virtual- (c) (pc) Array of The list of virtual servers that have been directly placed in the
servers String/URI workload, each identified by its URI. If the workload contains
no directly placed virtual servers, then an empty array is
provided. This value can be modified through the Add and
Remove Virtual Server operations on the workload.
Note: This property is not returned by the Get Workload
Resource Group Properties operation.

1220 HMC Web Services API

 Level 04a

Table 426. Workload object: class-specific properties (continued)

Name Qualifier Type Description
virtual-server-groups (c) (pc) Array of The list of the user-defined managed object groups, each
String/URI identified by its URI, in the workload whose child virtual
servers automatically become members of the workload. If the
workload has no groups, an empty array is provided. This
value can be modified through the Add and Remove Group
operations on the workload.
Note: This property is not returned by the Get Workload
Resource Group Properties operation.
workload-element- (c) (pc) Array of The list of the workload element groups, each identified by its
groups String/URI URI, in the workload whose child virtual servers automatically
become members of the workload. If the workload has no
element groups, an empty array is provided. This value can be
modified through the Add Workload Element Group to a
Workload Resource Group and Remove Workload Element
Group from a Workload Resource Group operations on the
workload as well as the CreateWorkload Element Group and
Delete Workload Element Group operations.
active-perf-policy (pc) Object A perf-policy-summary object, as described in Table 427 on
page 1223, of the active performance policy in the workload
resource group. This value can be modified through the
operation “Activate Performance Policy” on page 1269.
perf-activation-node- (pc) Integer The number of nodes (ensemble members) that have
count (0-n) successfully activated the active performance policy for the
workload resource group. This value is between 0 and the
total number of ensemble members.
perf-activation-status (pc) String The status of the last performance policy activation. The
Enum possible values are:
"initializing"
The workload resource group performance function is
being initialized and status is not yet known.
"in-progress"
Performance policy activation is in progress and any new
activation request is rejected.
"active"
Performance policy activation is complete.
default-perf-policy — Object A perf-policy-summary object, as described in Table 427 on
page 1223, of the default performance policy in the workload
resource group.
custom-perf-policies (c) (pc) Array of A list of perf-policy-summary objects, as described in Table 427
objects on page 1223, of the user-defined performance policies in the
workload resource group. If no custom policies exist, an
empty array is provided. This value can be modified through
the operations “Create Performance Policy” on page 1262 and
“Delete Performance Policy” on page 1264.

Chapter 18. Workload resource group management 1221

 Level 04a

Table 426. Workload object: class-specific properties (continued)

Name Qualifier Type Description
perf-status (pc) String The performance status of the workload, determined by the
Enum importance and PI value of the active performance policy's
service classes. Possible values are:
"goals-met"
The PI values of all service classes in the active policy are
less than or equal to one.
"exposed"
The PI value of a service class in the active policy is
greater than one and its importance is "low" or "lowest".
"severe"
The PI value of a service class in the active policy is
greater than one and its importance is "medium".
"critical"
The PI value of a service class in the active policy is
greater than one and its importance is "high" or "highest".
"no-status"
Performance status of the workload cannot be calculated.
compliant-perf-status (w)(pc) Array of An array of values that define what perf-status values cause
String the workload's status to be compliant. Possible values are:
Enum "goals-met"
The workload's performance status is "goals-met".
"exposed"
The workload's performance status is "exposed".
"severe"
The workload's performance status is "severe".
"critical"
The workload's performance status is "critical".
"no-status"
The workload's performance status is "no-status".

By default, a workload's compliant performance statuses

include "goals-met".
active-avail-policy (pc) Object An avail-policy-summary object, as described in Table 428 on
page 1223, of the active availability policy in the workload.
This value can be modified with the Activate Availability
Policy operation.
default-avail-policy — Object An avail-policy-summary object, as described in Table 428 on
page 1223, of the default availability policy in the workload.
custom-avail-policies (c) (pc) Array of A list of avail-policy-summary objects, as described in
objects Table 428 on page 1223, of the user-defined availability policies
in the workload. If no custom policies exist, then an empty
array is provided. This value can be modified through
theCreate Availability Policy and Delete Availability Policy
operations on the workload.

1222 HMC Web Services API

 Level 04a

Table 426. Workload object: class-specific properties (continued)

Name Qualifier Type Description
avail-status (pc) String The availability status of the workload, determined by the
Enum active availability policy and the availability status of the
workload’s element groups and virtual servers. The possible
values are as follows:
"available"
The workload is considered "available".
"exposed"
The workload is considered "exposed".
"critical"
The workload is considered critically exposed.
"not-available"
The workload is considered "not-available".
"not-supported"
The workload is considered "not-supported".
compliant-avail-status (w) (pc) Array of An array of values that define what avail-status values causes
String the workload’s status to be compliant. The possible values are:
Enum "available"
The workload's availability is "available".
"exposed"
The workload's availability status is "exposed".
"critical"
The workload's availability status is "critical".
"not-available"
The workload's availability status is "not-available".

By default, a workload’s compliant availability status includes

"available".

Table 427. perf-policy-summary-object

Field name Type Description
element-uri String/URI Canonical URI path of the Performance Policy object.
element-id String The element-id of the Performance Policy object.
name String Display name of the Performance Policy object.
activation-status String Enum The activation status of the Performance Policy object. The value
is one of the following:
"not-active"
The performance policy is not currently the active policy in
the workload resource group.
"in-progress"
The performance policy is currently being activated in the
workload resource group.
"active"
The performance policy is currently the active policy in the
workload resource group and its activation has completed.

Table 428. avail-policy-summary-object

Field name Type Description
element-uri String/URI Canonical URI path of the Availability Policy object.
element-id String The element-id of the Availability Policy object.
name String Display name of the Availability Policy object.

Chapter 18. Workload resource group management 1223

 Level 04a

Table 428. avail-policy-summary-object (continued)

Field name Type Description
activation-status String Enum The activation status of the Availability Policy object. The value is
one of the following:
"not-active"
The availability policy is not currently the active policy in
the workload resource group.
"active"
The availability policy is currently the active policy in the
workload resource group.

List Workload Resource Groups of an Ensemble

Use the List Workload Resource Groups of an Ensemble operation to list the workload resource groups
within the target ensemble.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/workload-resource-groups

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a list of workload resource groups.

Query parameters

Name Type Rqd/Opt Description

name String Optional A filter pattern (regular expression) that limits returned objects to
those that have a matching name property. If matches are found, the
response is an array with all workload resource groups that match. If
a match is not found, the response is an empty array.

Response body contents

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

Field name Type Description

workloads Array of Array of nested workload-info objects as described in the next table.
objects

workload-info object

Field name Type Description

object-uri String/URI The canonical URI path of the workload object, in the form
/api/workload-resource-groups/{workload-id}.
object-id String The object-uri of the workload object. This string is the {workload-id} portion
of the URI path provided by the object-uri field.
name String The display name of the workload object.
status String Enum The status property of the Workload Resource Group object.

1224 HMC Web Services API

 Level 04a

Description
The List Workload Resource Groups of an Ensemble operation lists the workload resource groups that
belong to the ensemble targeted by the request URI. The object URI, status, object ID, and display name
are provided for each.

If the name query parameter is specified, the returned list is limited to the workload resource group in
the ensemble that has a name property matching the specified filter pattern. If the name parameter is
omitted, this filtering is not done.

A workload resource group is included in the list only if the API user has object-access permission for
that object. An error response is returned if the primary HMC does not manage the target ensemble or if
you do not have the requirements listed in “Authorization requirements.”

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Object-access permission to all workload objects to be included in the result.

HTTP status and reason codes

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

Otherwise, 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 ({ensemble-id}) does not designate an existing
ensemble 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/ensembles/b58f0846-8ef7-11df-bb72-00215ef9b504/workload-resource-groups HTTP/1.1

x-api-session: 466ske8jt8waeavxcs5rc26gsfjqjfs6aji8qbj7jgne6yrdbq

Figure 668. List Workload Resource Groups of an Ensemble: Request

Chapter 18. Workload resource group management 1225

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Mon, 28 Nov 2011 03:52:05 GMT
content-type: application/json;charset=UTF-8
content-length: 452
{
"workloads": [
{
"name": "Default",
"object-id": "b65a3066-8ef7-11df-95c2-00215ef9b504",
"object-uri": "/api/workload-resource-groups/b65a3066-8ef7-11df-95c2-00215ef9b504"
},
{
"name": "SS-Web-Store-Workload",
"object-id": "546a3398-1974-11e1-999c-00215e6a0c26",
"object-uri": "/api/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26"
}
]
}

Figure 669. List Workload Resource Groups of an Ensemble: Response

Get Workload Resource Group Properties

Use the Get Workload Resource Group Properties operation to retrieve the properties of a single
workload object that is designated by its object-id. This operation returns the properties of a single
workload resource group in the ensemble.

HTTP method and URI

GET /api/workload-resource-groups/{workload-id}

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
requesting properties.

Response body contents

On successful completion, the response body is a JSON object provides the current values of the
properties for the workload object as defined in “Data model” on page 1219. Field names and data types
in the JSON object are the same as the property names and data types defined in the data model.

Note that the virtual-servers, virtual-server-groups, and workload-element-groups properties are omitted
from this response schema. They are available through their own operations: “List Virtual Servers of a
Workload Resource Group” on page 1234, “List Groups of Virtual Servers of a Workload Resource
Group” on page 1241, and “List Workload Element Groups of a Workload Resource Group” on page
1247.

Description
The Get Workload Resource Group Properties operation returns the current properties for the workload
object specified by {workload-id}, as defined in “Response body contents.”

On successful execution, all of the current properties as defined by the data model for the Workload
Resource Group object are provided in the response body, excluding virtual-servers,
virtual-server-groups, and workload-element-groups and HTTP status code 200 (OK) is returned.

1226 HMC Web Services API

 Level 04a

An error response is returned if the targeted workload resource group does not exist or if you do not
have the requirements listed in “Authorization requirements.”

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the workload object passed in the request URI.

HTTP status and reason codes

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

Otherwise, 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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.

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/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26 HTTP/1.1

x-api-session: 67prscbokwxz6o1bn1q3feysece2q4275agf27uupjnvr98lse

Figure 670. Get Workload Resource Group Properties: Request

Chapter 18. Workload resource group management 1227

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Mon, 28 Nov 2011 05:09:12 GMT
content-type: application/json;charset=UTF-8
content-length: 1244
{
"active-perf-policy": {
"activation-status": "active",
"element-id": "160c563e-197f-11e1-8914-00215e6a0c26",
"element-uri": "/api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/160c563e-197f-11e1-8914-00215e6a0c26",
"name": "Prime Shift"
},
"category": "Production",
"class": "workload-resource-group",
"custom-perf-policies": [
{
"activation-status": "active",
"element-id": "160c563e-197f-11e1-8914-00215e6a0c26",
"element-uri": "/api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/160c563e-197f-11e1-8914-00215e6a0c26",
"name": "Prime Shift"
}
],
"default-perf-policy": {
"activation-status": "not-active",
"element-id": "13ec9170-197f-11e1-8914-00215e6a0c26",
"element-uri": "/api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/13ec9170-197f-11e1-8914-00215e6a0c26",
"name": "Default"
},
"description": "Spacely Sprockets Web Store Workload",
"is-default": false,
"is-locked": false,
"name": "SS-Web-Store-Workload",
"object-id": "13de1bfe-197f-11e1-8914-00215e6a0c26",
"object-uri": "/api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26",
"parent": "/api/ensembles/b58f0846-8ef7-11df-bb72-00215ef9b504",
"perf-activation-node-count": 2,
"perf-activation-status": "active"

Figure 671. Get Workload Resource Group Properties: Response

Create Workload Resource Group

Use the Create Workload Resource Group operation to create a new custom workload resource group in
an ensemble. The new workload resource group must be uniquely named within the ensemble.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/workload-resource-groups

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you want
to create a new workload resource group.

1228 HMC Web Services API

 Level 04a

Request body contents

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

Field name Type Rqd/Opt Description

name String Required The name to give the new workload resource group, as described in
(1-64) “Data model” on page 1219. The passed name must be unique among
all other workload resource groups currently in the ensemble.
description String Optional The description to give the new workload resource group, as
(0-256) described in “Data model” on page 1219.
category String Optional The category to give the new workload resource group, as described
(0-32) in “Data model” on page 1219.

Response body contents

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

Field name Type Description

object-uri String/URI Canonical URI path of the workload object, in the form /api/workload-resource-
groups/{workload-id}.

Description
The Create Workload Resource Group operation creates a new custom workload resource group in the
ensemble identified by {ensemble-id}. On successful execution, the workload resource group is created and
added to the ensemble and status code 201 is returned with a response body containing a reference to the
new workload resource group.

The Create Workload Resource Group operation returns an empty workload resource group that has a
default performance policy but does not contain any virtual servers or user-defined groups. To create a
fully functional workload resource group, you also need to use these additional operations, in sequence,
to minimize the number of policy activations on the virtual servers:
1. “Create Performance Policy” on page 1262– Use this operation to create all custom performance
policies desired for the new workload resource group. You can omit this step if you do not want to
use any custom performance policies.
2. “Activate Performance Policy” on page 1269– Use this operation to set the active policy for the new
workload resource group. You can omit this step if you want the default performance policy to be the
active policy.
3. “Add Virtual Server to a Workload Resource Group” on page 1237 or “Add Group of Virtual Servers
to a Workload Resource Group” on page 1243– Use one or both of these operations to add all of the
virtual servers and groups that you want to be members of the new workload resource group. As the
virtual servers or groups are added, the active performance policy of the workload resource group is
applied to them.

An error response is returned:

v If the targeted ensemble does not exist or if you do not have the requirements listed in “Authorization
requirements” on page 1230.
v If the request body is not valid. The request body is validated against the schema described in
“Request body contents.”
v If the ensemble contains the maximum number workload resource groups (500, including the default
workload).

Chapter 18. Workload resource group management 1229

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the New Workload Resource Group task.
In addition, the target ensemble must be at the Automate entitlement level.

HTTP status and reason codes

On successful completion, HTTP status code 201 (Created) is returned and the response body is provided
as described in “Response body contents” on page 1229.

Otherwise, 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.
65 The name of the new workload resource group is not unique.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
3 The ensemble is not operating at the management entitlement level required
to perform this operation (Automate).
404 (Not Found) 1 The object ID in the URI ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.
409 (Conflict) 66 The ensemble contains the maximum number of workload resource groups.
(500, including the default workload).

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/ensembles/b58f0846-8ef7-11df-bb72-00215ef9b504/workload-resource-groups HTTP/1.1

x-api-session: 466ske8jt8waeavxcs5rc26gsfjqjfs6aji8qbj7jgne6yrdbq
content-type: application/json
content-length: 73
{
"description": "New Workload Resource Group",
"name": "SS-New-Workload"
}

Figure 672. Create Workload Resource Group: Request

1230 HMC Web Services API

 Level 04a

201 Created
server: zSeries management console API web server / 1.0
location: /api/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26
cache-control: no-cache
date: Mon, 28 Nov 2011 03:52:01 GMT
content-type: application/json;charset=UTF-8
content-length: 83
{
"object-uri": "/api/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26"
}

Figure 673. Create Workload Resource Group: Response

Delete Workload Resource Group

Use the Delete Workload Resource Group operation to remove a workload resource group from an
ensemble, and deactivate its active policies against its workload element groups and virtual servers. Any
virtual server that is not contained by another custom workload resource group directly or through a
workload element group is moved into the default. A workload resource group may not be deleted if it
contains a workload element group that belongs only to the target workload resource group; to delete the
workload resource group you must first delete the workload element group.

HTTP method and URI

DELETE /api/workload-resource-groups/{workload-id}

In this request, the URI variable {workload-id} is the object ID of the workload object that you want to
remove.

Description
The Delete Workload Resource Group operation deletes the workload object specified by {workload-id}
from its ensemble.

On successful completion, all workload element groups and virtual servers in the workload resource
group are removed from it, the workload resource group is removed from the ensemble, and status code
204 (No Content) is returned without supplying a response body. See the Ensemble Workload Resource
Group Management Guide, GC27-2629, for details about managing virtual servers in workload resource
groups.

An error response is returned if the targeted workload object does not exist or if you do not have the
requirements listed in “Authorization requirements.” Targeting the default workload resource group also
returns an error response because the default workload resource group cannot be deleted.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object that owns the workload.
v Object-access permission to the workload object passed in the request URI.
v Action/task permission to the Delete Workload Resource Group task.

Chapter 18. Workload resource group management 1231

 Level 04a

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned. Otherwise, the following
HTTP status codes are returned for the indicated errors.

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.
60 The targeted workload resource group is the default workload object.
64 A workload element group in the workload resource group does not belong
to any other workload resource groups. The workload element group must
be deleted before you may delete the workload resource group.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
61 The operation cannot be performed because one or more virtual servers in
the workload resource group designated by the request URI are currently
busy performing some other 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/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26 HTTP/1.1

x-api-session: 466ske8jt8waeavxcs5rc26gsfjqjfs6aji8qbj7jgne6yrdbq

Figure 674. Delete Workload Resource Group: Request

204 No Content
date: Mon, 28 Nov 2011 03:52:06 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 675. Delete Workload Resource Group: Response

Update Workload Resource Group

Use the Update Workload Resource Group operation to modify simple writable properties of a workload
object.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}

1232 HMC Web Services API

 Level 04a

In this request, the URI variable {workload-id} is the object ID of the workload object that you are
modifying.

Request body contents

The request body is a JSON object with one or more of the following fields. You are required to supply
only those fields that you want to change.

Field name Type Rqd/Opt Description

name String Optional The new name to give the workload resource group, as described in
(1-64) “Data model” on page 1219. The passed name must be unique among
all other workload resource groups currently in the ensemble.
description String Optional The new description to give the workload resource group, as
(0-256) described in “Data model” on page 1219.
category String Optional The new category to give the workload resource group, as described
(0-32) in “Data model” on page 1219.
acceptable-status Array of Optional An array of values that define what causes the workload's status to
String be compliant as described in “Data model” on page 1219.
Enum
compliant-perf- Array of Optional An array of values that define what perf-status values cause the
status String workload's status to be compliant as described in “Data model” on
Enum page 1219.

Description
The Update Workload Resource Group operation updates one or more simple writable properties of the
workload object identified by {workload-id}. These properties are those that are not modified through other
specific operations, as noted in “Request body contents.”

The request body is validated against the schema described in “Request body contents.” On successful
execution, the workload object is updated with the supplied property values and status code 204 (No
Content) is returned without supplying a response body. Notifications for these property changes are sent
asynchronously to this operation.

An error response is returned if the targeted workload resource group does not exist or if you do not
have the requirements listed in “Authorization requirements.” Targeting the default workload resource
group also invokes an error response because its name, description, and category cannot be modified.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Action/task permission to the Workload Resource Group Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned. Otherwise, the following
HTTP status codes are returned for the indicated errors.

Chapter 18. Workload resource group management 1233

 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.
60 The targeted workload resource group is the default workload object.
65 The new name given to the workload resource group is not unique.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.

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/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26 HTTP/1.1

x-api-session: 466ske8jt8waeavxcs5rc26gsfjqjfs6aji8qbj7jgne6yrdbq
content-type: application/json
content-length: 114
{
"category": "Production",
"description": "Spacely Sprockets Web Store Workload",
"name": "SS-Web-Store-Workload"
}

Figure 676. Update Workload Resource Group: Request

204 No Content
date: Mon, 28 Nov 2011 03:52:01 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 677. Update Workload Resource Group: Response

List Virtual Servers of a Workload Resource Group

The List Virtual Servers of a Workload Resource Group operation lists the virtual servers in the passed
workload. This is the way to get the information corresponding to the virtual-servers and
directly-added-virtual-servers properties of a workload, as it is omitted from the standard GET
operation.

HTTP method and URI

GET /api/workload-resource-groups/{workload-id}/virtual-servers

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
requesting a list of virtual servers.

1234 HMC Web Services API

 Level 04a

Query parameters:

Field name Type Rqd/Opt Description

name String Optional Filter pattern (regular expression) to limit returned objects to those
that have a matching name property. If matches are found, the
response will be an array with information for all virtual servers
that match. If no match is found, the response will be an empty
array.

Response body contents

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

Field name Type Description

virtual-servers Array of Array of nested virtualserver-info objects as described in the next table.
objects

Each nested virtualserver-info object contains the following fields:

Field name Type Description

object-uri String/URI Canonical URI path of the Virtual Server object.
name String The current value of the name property of the Virtual Server object.
status String Enum The current value of the status property of the Virtual Server object.
type String Enum The value of the type property of the Virtual Server object.
inclusion-type Array of The reason(s) this virtual server is included in the workload resource group.
String Enum The possible values are as follows:
v "direct": The virtual server was added directly to the workload resource
group.
v "custom-group": The virtual server was added to the workload resource
group due to its membership in one or more user-defined groups which
belong to the workload resource group.
v "workload-element-group": The virtual server was added directly to the
workload resource group due to its membership in one or more element
groups which belong to the workload resource group.

Description
The List Virtual Servers of a Workload Resource Group operation lists the virtual servers that belong to
the workload resource group targeted by the request URI. The object URI, display name, status, type, and
inclusion-type information are provided for each. The inclusion-type information details how the virtual
server was added to the workload resource group, as described in “Response body contents.”

An error response is returned if the ensemble does not contain the targeted workload or if you do not
have the requirements listed in “Authorization requirements.”

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the workload object passed in the request URI.

Chapter 18. Workload resource group management 1235

 Level 04a

HTTP status and reason codes

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

Otherwise, 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 ({workload-id}) does not designate an existing
workload 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/workload-resource-groups/29354e42-20db-11e1-9e8d-00215e6a0c26/virtual-servers HTTP/1.1

x-api-session: 4sz56y4z445abfdwva0qsee8wceszpk34chfjfpcgkfg0i5szv

Figure 678. List Virtual Servers of a Workload Resource Group: Request

1236 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 07 Dec 2011 13:55:59 GMT
content-type: application/json;charset=UTF-8
content-length: 537
{
"virtual-servers": [
{
"inclusion-type": [
"custom-group"
],
"name": "SS-Web-Svr-3",
"object-uri": "/api/virtual-servers/1cc18bee-20db-11e1-b49e-00262df332b3",
"status": "not-operating",
"type": "x-hyp"
},
{
"inclusion-type": [
"direct"
],
"name": "SS-Web-Svr-2",
"object-uri": "/api/virtual-servers/1a4f490a-20db-11e1-b953-00262df332b3",
"status": "not-operating",
"type": "x-hyp"
},
{
"inclusion-type": [
"direct",
"custom-group"
],
"name": "SS-Web-Svr-1",
"object-uri": "/api/virtual-servers/180b51de-20db-11e1-b357-00262df332b3",
"status": "not-operating",
"type": "x-hyp"
}
]
}

Figure 679. List Virtual Servers of a Workload Resource Group: Response

Add Virtual Server to a Workload Resource Group

Use the Add Virtual Server to a Workload Resource Group operation to add a virtual server to the
target workload resource group.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/operations/add-virtual-server

In this request, the URI variable {workload-id} is the object ID of the workload object to which you want to
add a virtual server.

Request body contents

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

Field name Type Description

virtual-server String/URI The canonical URI identifying the Virtual Server object to be added to the
target workload resource group.

Chapter 18. Workload resource group management 1237

 Level 04a

Description
The Add Virtual Server to a Workload Resource Group operation adds a virtual server directly to the
workload resource group targeted by the request URI. See the Ensemble Workload Resource Group
Management Guide, GC27-2629, for details about managing virtual servers in workload resource groups.

A virtual server can become a member of a workload resource group through two ways: by adding the
virtual server individually or by adding a custom group that contains the virtual server. The way in
which the virtual server was added has an effect on the outcome of this operation:
v If the virtual server is not already a member of the workload resource group, the virtual server is
added and a property notification is sent asynchronously to this request. If the virtual server was
previously in the default workload resource group, the virtual server is removed automatically from
the default workload resource group.
v If the virtual server is already directly defined to the workload resource group (that is, the virtual
server was added individually at an earlier time), the request is ignored with a successful return code.
v If the virtual server is already a member of the workload resource group through its membership in a
group that already belongs to the workload resource group, the virtual-servers property does not
change. However, it is now directly defined to the workload resource group such that if the virtual
server is removed from the group later, it would remain in the workload resource group.

An error response is returned if the targeted workload resource group or virtual server does not exist or
if you do not have the requirements listed in “Authorization requirements.” Targeting the default
workload resource group also invokes an error response because you cannot directly modify the default
workload resource group.

The request body is validated against the schema described in “Request body contents” on page 1237. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Object-access permission to the Virtual Server object passed in the request body.
v Action/task permission to the Workload Resource Group Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned.

Otherwise, 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.
60 The targeted workload resource group is the default workload object.
403 (Forbidden) 1 The API user does not have the required permission for this operation.

1238 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object-id in the URI ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to it.
2 The object-id in the URI of the Virtual Server object in the request body
does not designate an existing object, or the API user does not have access
permission to it.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
61 The operation cannot be performed because the virtual server to be added is
currently busy performing some other operation.

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/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26/operations/
add-virtual-server HTTP/1.1
x-api-session: 466ske8jt8waeavxcs5rc26gsfjqjfs6aji8qbj7jgne6yrdbq
content-type: application/json
content-length: 79
{
"virtual-server": "/api/virtual-servers/ecd06dfc-1972-11e1-8879-00262df332b3"
}

Figure 680. Add Virtual Server to a Workload Resource Group: Request

204 No Content
date: Mon, 28 Nov 2011 03:52:04 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 681. Add Virtual Server to a Workload Resource Group: Response

Remove Virtual Server from a Workload Resource Group

Use the Remove Virtual Server from a Workload Resource Group operation to remove a virtual server
from the target workload resource group.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/operations/remove-virtual-server

In this request, the URI variable {workload-id} is the object ID of the workload object from which you want
to remove the virtual server.

Chapter 18. Workload resource group management 1239

 Level 04a

Request body contents

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

Field name Type Description

virtual-server String/URI The canonical URI identifying the Virtual Server object to be removed from
the targeted workload resource group.

Description
The Remove Virtual Server from a Workload Resource Group operation removes a virtual server from
being directly defined to the workload resource group targeted by the request URI. See the Ensemble
Workload Resource Group Management Guide, GC27-2629, for details about managing virtual servers in
workload resource groups.

A virtual server can become a member of a workload resource group through two ways: by adding the
virtual server individually or by adding a custom group that contains the virtual server. In some cases, a
virtual server can be defined twice to the same workload resource group. The way in which the virtual
server was added to the workload resource group has an effect on the outcome of this operation:
v If the virtual server was added individually to the workload resource group and is not also a member
of a custom group that is already defined to this workload resource group, the virtual server is
removed. A property change notification is sent asynchronously to this request.
v If the virtual server was added individually and as a member of a custom group in the workload
resource group, the virtual server remains in the workload resource group only as a member of the
custom group. In this case, a property change notification is not sent.
v If the virtual server is not already a member of the workload resource group (either individually or
through a custom group), the request is ignored with a successful return code.

An error response is returned if the targeted workload resource group or virtual server does not exist or
if you do not have the requirements listed in “Authorization requirements.” Targeting the default
workload resource group also invokes an error response because you cannot directly modify the default
workload resource group.

The request body is validated against the schema described in “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Object-access permission to the Virtual Server object passed in the request body.
v Action/task permission to the Workload Resource Group Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned.

Otherwise, the following HTTP status codes are returned for the indicated errors.

1240 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.
60 The targeted workload resource group is the default workload object.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to it.
2 The object-id in the URI of the Virtual Server object in the request body
does not designate an existing object, or the API user does not have access
permission to it.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
61 The operation cannot be performed because the virtual server to be removed
is currently busy performing some other operation.

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/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26/operations/
remove-virtual-server HTTP/1.1
x-api-session: 466ske8jt8waeavxcs5rc26gsfjqjfs6aji8qbj7jgne6yrdbq
content-type: application/json
content-length: 79
{
"virtual-server": "/api/virtual-servers/f1f581f4-196e-11e1-a344-00262df332b3"
}

Figure 682. Remove Virtual Server from a Workload Resource Group: Request

204 No Content
date: Mon, 28 Nov 2011 03:52:06 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 683. Remove Virtual Server from a Workload Resource Group: Response

List Groups of Virtual Servers of a Workload Resource Group

The List Groups of Virtual Servers of a Workload Resource Group operation lists the user-defined
managed object groups in the passed workload. This is a way to just get the information maintained in
the virtual-server-groups property of a workload.

HTTP method and URI

GET /api/workload-resource-groups/{workload-id}/virtual-server-groups

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
requesting a list of groups.

Chapter 18. Workload resource group management 1241

 Level 04a

Query parameters:

Field name Type Rqd/Opt Description

name String Optional Filter pattern to limit returned objects to those that have a matching
name property. If matches are found, the response will be an array
with information for all groups that match. If no match is found, the
response will be an empty array.

Response body contents

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

Field name Type Description

virtual-server-groups Array of An array of user-defined managed object groups in the workload resource
String/URI group, each identified by its URI.

Description
The List Groups of Virtual Servers of a Workload Resource Group operation lists the user-defined
managed object groups that belong to the workload resource group targeted by the request URI. The
Group object URI is provided for each.

A group is included in the list only if you meet the requirements listed in “Authorization requirements”;
otherwise, an error is returned. An error also is returned if the ensemble does not contain the targeted
workload resource group.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the workload object passed in the request URI.

HTTP status and reason codes

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

Otherwise, 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 ({workload-id}) does not designate an existing
workload 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.

1242 HMC Web Services API

 Level 04a

Example HTTP interaction

GET /api/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26/virtual-server-groups HTTP/1.1

x-api-session: 466ske8jt8waeavxcs5rc26gsfjqjfs6aji8qbj7jgne6yrdbq

Figure 684. List Groups of Virtual Servers of a Workload Resource Group: Request

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Mon, 28 Nov 2011 03:52:05 GMT
content-type: application/json;charset=UTF-8
content-length: 78
{
"virtual-server-groups": [
"/api/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341"
]
}

Figure 685. List Groups of Virtual Servers of a Workload Resource Group: Response

Add Group of Virtual Servers to a Workload Resource Group

Use the Add Group of Virtual Servers to a Workload Resource Group operation to add a user-defined
managed object group to the target workload resource group. Any virtual servers that the group contains
are added as virtual servers of the workload resource group.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/operations/add-virtual-server-group

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
requesting a list of groups.

Request body contents

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

Field name Type Description

virtual-server-group String/URI The canonical URI identifying the user-defined Group object to be added to
the targeted workload resource group.

Description
The Add Group of Virtual Servers to a Workload Resource Group operation adds a user-defined group
to the workload resource group targeted by the request URI. Through this operation, the virtual servers
that belong to the group are added automatically to the workload. See the Ensemble Workload Resource
Group Management Guide, GC27-2629, for details about managing virtual servers in workloads.

If the group is already defined to the workload, the request is ignored with a successful return code. If
the group is not already defined to the workload resource group, the group is added and a property
change notification for the virtual-server-groups property is sent asynchronously. All virtual servers in
the group are added to the workload resource group, and another property change notification is sent
asynchronously for the virtual-servers property including the virtual servers that are entirely new to the

Chapter 18. Workload resource group management 1243

 Level 04a

workload. If any of these virtual servers previously belonged to the default workload resource group,
they are removed automatically from the default workload resource group.

An error response is returned if the targeted workload resource group or custom group does not exist or
if you do not have the requirements listed in “Authorization requirements.” Targeting the default
workload resource group also results in an error because the default workload is not directly mutable.
Pattern match groups are not supported so specifying them in an Add Group of Virtual Servers to a
Workload operation results in an error.

The request body is validated against the schema described in “Request body contents” on page 1243. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Object-access permission to the Group object passed in the request body.
v Object-access permission to all virtual servers contained by the group.
v Action/task permission to the Workload Resource Group Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned.

Otherwise, 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.
60 The targeted workload resource group is the default workload object.
61 The object-id of the group to be added in the request body is that of a
pattern match group.
62 The group to be added contains virtual servers to which the API user does
not have access.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to it.
2 The object-id in the URI of the Group object in the request body does not
designate an existing object, or the API user does not have access permission
to it.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
62 The operation cannot be performed because the group to be added contains
one or more virtual servers that are currently busy performing some other
operation.

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

1244 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26/operations/
add-virtual-server-group HTTP/1.1
x-api-session: 466ske8jt8waeavxcs5rc26gsfjqjfs6aji8qbj7jgne6yrdbq
content-type: application/json
content-length: 76
{
"virtual-server-group": "/api/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341"
}

Figure 686. Add Group of Virtual Servers to a Workload Resource Group: Request

204 No Content
date: Mon, 28 Nov 2011 03:52:05 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 687. Add Group of Virtual Servers to a Workload Resource Group: Response

Remove Group of Virtual Servers from a Workload Resource Group

Use the Remove Group of Virtual Servers from a Workload Resource Group operation to remove a
user-defined managed object group from the target workload resource group. All virtual servers in the
group are removed from the workload resource group, unless the virtual server belongs to another group
that is associated with the same workload resource group, or is directly added.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/operations/remove-virtual-server-group

In this request, the URI variable {workload-id} is the object ID of the workload object from which you are
removing the group.

Request body contents

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

Field name Type Description

virtual-server-group String/URI The canonical URI identifying the user-defined Group object to be removed
from the targeted workload resource group.

Description
The Remove Group of Virtual Servers from a Workload Resource Group operation removes a
user-defined group from the workload resource group targeted by the request URI. Through this
operation, any virtual servers in the group are removed as well, unless they also belong to another group
that is associated with this workload resource group. See the Ensemble Workload Resource Group
Management Guide, GC27-2629, for details about managing virtual servers in workload resource groups.

If the group is not defined to the workload resource group, then the request is ignored with a successful
return code. If the group is in the workload resource group, then it is removed and a property change
notification for the virtual-server-groups property is sent asynchronously. Virtual servers in the group
that are not also members of another group in the workload resource group, or directly added, are
Chapter 18. Workload resource group management 1245
 Level 04a

removed from the workload resource group, and another property change notification is sent
asynchronously for the virtual-servers property. If any of those virtual servers do not belong to another
custom workload resource group, they are placed in the default workload resource group.

An error response is returned if the targeted workload resource group or group does not exist or if you
do not have the requirements listed in “Authorization requirements.” Targeting the default workload
resource group also invokes an error response because you cannot directly modify the default workload
resource group.

The request body is validated against the schema described in “Request body contents” on page 1245. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Object-access permission to the Group object passed in the request body.
v Object-access permission to all virtual servers contained by the group.
v Action/task permission to the Workload Resource Group Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned.

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.
60 The targeted workload resource group is the default workload object.
62 The group to be removed contains virtual servers to which the API user does
not have access.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to it.
2 The object-id in the URI of the Group object in the request body does not
designate an existing object, or the API user does not have access permission
to it.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
62 The operation cannot be performed because the group to be removed
contains one or more virtual servers that are currently busy performing some
other operation.

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

1246 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/workload-resource-groups/546a3398-1974-11e1-999c-00215e6a0c26/operations/
remove-virtual-server-group HTTP/1.1
x-api-session: 466ske8jt8waeavxcs5rc26gsfjqjfs6aji8qbj7jgne6yrdbq
content-type: application/json
content-length: 76
{
"virtual-server-group": "/api/groups/ee2782af-dd98-3ec0-bc2d-cfe2e9154341"
}

Figure 688. Remove Group of Virtual Servers from a Workload Resource Group: Request

204 No Content
date: Mon, 28 Nov 2011 03:52:06 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 689. Remove Group of Virtual Servers from a Workload Resource Group: Response

List Workload Element Groups of a Workload Resource Group

The List Workload Element Groups of a Workload Resource Group operation lists the workload
element groups in the specified workload.

HTTP method and URI

GET /api/workload-resource-groups/{workload-id}/workload-element-groups

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
requesting a list of workload element groups.

Query parameters:

Field name Type Rqd/Opt Description

name String Optional Filter pattern to limit returned objects to those that have a matching
name property. If matches are found, the response will be an array
with information for all workload element groups that match. If no
match is found, the response will be an empty array.

Response body contents

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

Field name Type Description

workload-element- Array of An array of workload element groups in the workload resource group, each
groups String/URI identified by its URI.

Description
The List Workload Element Groups of a Workload Resource Group operation lists the workload
element groups that belong to the workload resource group targeted by the request URI. The Workload
Element Group object URI is provided for each.

Chapter 18. Workload resource group management 1247

 Level 04a

A workload element group is included in the list only if you meet the requirements listed in
“Authorization requirements”; otherwise, an error is returned. An error also is returned if the ensemble
does not contain the targeted workload resource group.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the workload object passed in the request URI and to all Workload Element
Group objects to be included in the result.

HTTP status and reason codes

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

Otherwise, 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 ({workload-id}) does not designate an existing
workload 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.

Add Workload Element Group to a Workload Resource Group

Use the Add Workload Element Group to a Workload Resource Group operation to add a workload
element group to the target workload resource group. Any virtual servers that it contains are added as
virtual servers of the workload resource group.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/operations/add-workload-element-group

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
requesting a workload element group.

Request body contents

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

Field name Type Description

workload-element- String/URI The canonical URI identifying the Workload Element Group object to be
group added to the targeted workload resource group.

Description
The Add Workload Element Group to a Workload Resource Group operation adds a workload element
group to the workload resource group targeted by the request URI. A workload element group in a

1248 HMC Web Services API

 Level 04a

workload has its child virtual servers automatically added to the workload. See the Ensemble Workload
Resource Group Management Guide, GC27-2629, for details about managing workload element groups and
virtual servers in workloads.

If the workload element group is already defined to the workload, the request is ignored with a
successful return code. If the workload element group is not already defined to the workload resource
group, then it is added and a property change notification for the workload-element-groups property is
sent asynchronously. All virtual servers in the workload element group are added to the workload
resource group, and another property change notification is sent asynchronously for the virtual-servers
property including the virtual servers that are entirely new to the workload. If any of these virtual
servers previously belonged to the default workload resource group, they are removed automatically
from it.

An error response is returned if the targeted workload resource group or workload element group does
not exist or if you do not have the requirements listed in “Authorization requirements.” Targeting the
default workload resource group also results in an error because the default workload is not directly
mutable. A workload element group may only be added if you have authority to access all virtual servers
contained by it at the time of the request.

The request body is validated against the schema described in the “Request body contents” on page 1248.
If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating
the validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Object-access permission to the Workload Element Group object passed in the request body.
v Object-access permission to all virtual servers contained by the workload element group.
v Action/task permission to the Workload Resource Group Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned.

Otherwise, 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.
60 The targeted workload resource group is the default workload object.
62 The workload element group to be added contains virtual servers to which
the API user does not have access.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to it.
2 The object-id in the URI of the Workload Element Group object in the
request body does not designate an existing object, or the API user does not
have access permission to it.

Chapter 18. Workload resource group management 1249

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
62 The operation cannot be performed because the workload element group to
be added contains one or more virtual servers that are currently busy
performing some other operation.
65 The operation cannot be performed because the workload element group to
be added is currently busy performing some other operation.

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

Remove Workload Element Group from a Workload Resource Group

Use the Remove Workload Element Group from a Workload Resource Group operation to remove a
workload element group from the target workload resource group. All virtual servers in the group are
removed from the workload resource group, unless the virtual server belongs to another group that is
associated with the same workload resource group.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/operations/remove-workload-element-group

In this request, the URI variable {workload-id} is the object ID of the workload object from which you are
removing the workload element group.

Request body contents

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

Field name Type Description

workload-element- String/URI The canonical URI identifying the Workload Element Group object to be
group removed from the targeted workload resource group.

Description
The Remove Workload Element Group from a Workload Resource Group operation removes a
workload element group from the workload resource group targeted by the request URI. Through this
operation, any virtual servers in the workload element group are removed as well, unless they also
belong to another group that is associated with this workload resource group. See the Ensemble Workload
Resource Group Management Guide, GC27-2629, for details about managing virtual servers in workload
resource groups.

If the workload element group is not defined to the workload resource group, then the request is ignored
with a successful return code. If the workload element group is in the workload resource group, then it is
removed and a property change notification for the workload-element-groups property is sent
asynchronously. Virtual servers in the workload element group that are not also members of another
group in the workload resource group, or directly added, are removed from the workload resource
group, and another property change notification is sent asynchronously for the virtual-servers property. If
any of those virtual servers do not belong to another custom workload resource group, they are placed in
the default workload resource group.

An error response is returned if the targeted workload resource group or workload element group does
not exist or if you do not have the requirements listed in “Authorization requirements” on page 1251.
Targeting the
1250 HMC Web Services API
 Level 04a

default workload resource group also invokes an error response because it is not directly mutable. A
workload element group may only be removed if you have authority to access all virtual servers
contained by it at the time of the request. A workload element group may not be removed from the only
workload to which it belongs; to remove the workload element group from such a workload, the
workload element group must be deleted.

The request body is validated against the schema described in “Request body contents” on page 1250. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Workload Element Group object passed in the request URI.
v Object-access permission to all virtual servers contained by the group.
v Action/task permission to the Workload Resource Group Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned.

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.
60 The targeted workload resource group is the default workload object.
62 The group to be removed contains virtual servers to which the API user does
not have access.
64 The workload element group to be removed does not belong to any other
workloads. The workload element group must be deleted to remove it from
the workload.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to it.
2 The object-id in the URI of the Virtual Server object in the request body
does not designate an existing object, or the API user does not have access
permission to it.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
62 The operation cannot be performed because the group to be removed
contains one or more virtual servers that are currently busy performing some
other operation.
65 The operation cannot be performed because the workload element group to
be removed is currently busy performing some other operation.

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

Chapter 18. Workload resource group management 1251

 Level 04a

Performance Policy object

Performance Policy objects are elements that define performance goals for virtual servers in a workload
resource group. A performance policy consists mainly of an importance level and an ordered list of
service classes that define the goals. See “Service class nested object” on page 1254 for more details on
service classes.

Any number of custom Performance Policy objects can be defined for a workload resource group.
However, exactly one is active at a time. Every workload resource group contains an immutable default
performance policy that is active if a custom workload policy is not activated. Note that changing any
property of an active performance policy automatically causes its reactivation. Because activating a
performance policy can fail, it follows then that updating properties of an active performance policy can
fail. See “Activate Performance Policy” on page 1269 for further details.

Data model
This element includes the following class-specific properties. For definitions of the qualifier abbreviations
in the following table, see “Property characteristics” on page 58.
Table 429. Performance Policy object: class-specific properties
Name Qualifier Type Description
element-uri — String/URI The canonical URI path for a performance policy
is qualified by its workload object and is of the
form /api/workload-resource-groups/{workload-
id}/performance-policies/{policy-id} where
{workload-id} is the value of the object-id property
of the parent workload object and {policy-id} is the
value of the element-id property of the policy
element-id — String (36) The unique identifier for the performance policy
instance. The unique identifier is in the form of a
UUID.
parent — String/URI The parent of a performance policy is its owning
workload resource group, and so the parent value
is the canonical URI path for the workload
resource group.
class — String The class of a Performance Policy object is
“performance-policy”.
name (w) (pc) String (1-64) The display name specified for the performance
policy, which can be up to 64 characters made up
of alphanumeric characters, blanks, periods,
underscores, or dashes. Names must start with an
alphabetic character and end with an alphabetic
character, numeric character, underscore, period,
or dash. Names must be unique to other existing
performance policies in the workload resource
group.
description (w) (pc) String (0-256) Arbitrary text describing the performance policy
in up to 256 characters.
is-default — Boolean This value is used to identify the default
Performance Policy object. It is true for the default
policy and false for all other (custom) policies in
the workload resource group.

1252 HMC Web Services API

 Level 04a

Table 429. Performance Policy object: class-specific properties (continued)

Name Qualifier Type Description
importance (w) (pc) String Enum The importance value assigned to the performance
policy, which is one of the following:
v "highest"
v "high"
v "medium"
v "low"
v "lowest"

See the Ensemble Workload Resource Group

Management Guide, GC27-2629, for detailed
information on the importance property values.
custom-service-classes (w) (pc) Array of The ordered list of custom service classes in the
objects (0-99) performance policy. Each service class will be an
object in the form of a service class object, as
described in “Service class nested object” on page
1254. This list includes only custom service classes
and not the default service class for the policy.
This array can contain from 0 to 99 entries.
default-service-class — Object The object describing the default service class for
the performance policy, in the form of the service
class object, as described in “Service class nested
object” on page 1254.
revision (pc) Integer (1-n) The revision count of the performance policy,
which is the number of times the policy has been
modified. The initial value for a new performance
policy is 1.
activation-status (pc) String Enum The activation status of the performance policy,
which is one of the following values:
v "not-active" – the performance policy is not
currently the active policy for the workload
resource group
v "in-progress" – the performance policy is
currently being activated for the workload
resource group
v "active" – the performance policy is currently
the active policy for the workload resource
group, and its activation has completed
last-activation-requested-date (pc) Timestamp The standard date/time value indicating the time
of the last activation request of the policy. If the
policy has never been active or is the default
policy of the default workload resource group, this
value is negative.

The standard time value is defined as the number

of elapsed milliseconds after midnight on 1
January 1970.
last-activation-completed-date (pc) Timestamp The standard date/time value indicating the time
the policy last completed activation. If the policy
has never been active or is the default policy of
the default workload resource group, this value is
negative.

The standard time value is defined as the number

of elapsed milliseconds after midnight on 1
January 1970.

Chapter 18. Workload resource group management 1253

 Level 04a

Table 429. Performance Policy object: class-specific properties (continued)

Name Qualifier Type Description
last-activated-by (pc) String The user name used for the last activation request.
This value is the empty string if the policy has
never been activated or is the default policy of the
default workload resource group.
last-modified-date (pc) Timestamp The standard date/time value indicating the time
the policy was last modified. If the policy has
never been modified, this property is equal to the
created-date property. The value is negative for all
default policies.

The standard time value is defined as the number

of elapsed milliseconds after midnight on 1
January 1970.
last-modified-by (pc) String The user name used to last modify the policy. If
the policy has never been modified, this property
is equal to the created-by property. The value is
the empty string for all default policies.
created-date — Timestamp The standard date/time value indicating the time
the policy was created. The value is negative for
all default policies.

The standard time value is defined as the number

of elapsed milliseconds after midnight on 1
January 1970.
created-by — String The user name used to create the policy. The value
is the empty string for all default policies.

Service class nested object

A service class object is a nested object of a Performance Policy object. A performance policy can contain
zero or more ordered service classes, and contains a default service class. Service classes use classification
rules to classify and apply performance goals to virtual servers in the workload resource group. Service
classes are positional; during classification, zManager searches service classes from low-ordered to
high-ordered service class to find a match for a virtual server. The default service class applies for any
virtual server that does not match a custom service class.

You cannot directly change a service class object. When any property of a service class must be changed,
zManager creates a new service class object to replace the existing one in the policy object. For this
reason, service classes are not supported as objects in the standard sense, but rather as simple nested
objects of a performance policy. Because of this fact, direct operations and notifications are not supported
for service class objects.

The following properties are supported:

Table 430. Performance Policy object: Service class nested object properties
Field name Type Rqd/Opt Description
name String Required The display name specified for the service class, which can be up to 64
(1-64) characters made up of alphanumeric characters, blanks, periods,
underscores, or dashes. Names must start with an alphabetic character
and end with an alphabetic character, numeric character, underscore,
period, or dash. Names must be unique to other existing service
classes in the performance policy.
description String Optional Arbitrary text describing the performance policy in up to 256
(0-256) characters.

1254 HMC Web Services API

 Level 04a

Table 430. Performance Policy object: Service class nested object properties (continued)
Field name Type Rqd/Opt Description
type String Required This identifies the type of the service class object:
Enum v "server" – the service class type targeting specific virtual servers
goal-type String Required This identifies the type of performance goal for the service class, which
Enum must be one of the following:
v "velocity" – the service class goal is based on a velocity value as
given in the velocity property
v "discretionary" – the service class goal is up to the discretion of
zManager
business- String Optional* This field identifies the business importance level assigned to the
importance Enum service class, which must be one of the following:
v "highest"
v "high"
v "medium"
v "low"
v "lowest"

* - A business importance is required for the velocity goal type, but is

not used for a discretionary goal type.
velocity String Optional* This field identifies the velocity goal value of the service class, which
Enum must be one of the following:
v "fastest"
v "fast"
v "moderate"
v "slow"
v "slowest"

* - A velocity value is only required for the velocity goal type.

classification-rule Object Required The rule used to filter the virtual servers for which the service class
goal applies. The value must be a JSON object, as described in
“Classification rule nested object.”

Classification rule nested object

A classification rule object is a nested object within a service class object. It is a recursive object used to
define logical filter statements to be applied to the virtual servers of the workload resource group. If a
virtual server passes the classification rule, the service class goal is applied.
Table 431. Performance Policy object: classification rule nested object properties
Field name Type Rqd/Opt Description
type String Required This field identifies the type of classification rule object, which must be
Enum one of the following:
v "and" – for this rule to be true, both of the two rules referenced by
this rule must be true
v "or" – for this rule to be true, only one of the two rules referenced
by this rule must be true
v "rule" – the rule defines a filter that resolves to true or false based
on its filter pattern against a virtual server

If you specify "and" or "or", exactly two classification rule objects must
be nested inside this classification rule object so they can be logically
compared. If you specify "rule", exactly one filter object must be
nested inside this object.

Chapter 18. Workload resource group management 1255

 Level 04a

Table 431. Performance Policy object: classification rule nested object properties (continued)
Field name Type Rqd/Opt Description
classification- Object Required* The first of two classification rule objects that must be nested inside
rule-1 this classification rule object if they are to be logically compared as
defined by the type property. If the type is "rule", this property is not
supported.

* - The type property value determines whether this field is required.

classification- Object Required* The second of two classification rule objects that must be nested inside
rule-2 this classification rule object if they are to be logically compared as
defined by the type property. If the type is "rule", this property is not
supported.

* - The type property value determines whether this field is required.

filter Object Required* A filter object defining the filter statement if the classification rule type
is "rule". If the type is "and" or "or", this property is not supported.

* - The type property value determines whether this field is required.

Filter nested object

A filter object is a nested object within a classification rule object whose type is "rule". The filter object
defines a logical statement used to filter on properties of a virtual server.
Table 432. Performance Policy object: filter nested object properties
Field name Type Rqd/Opt Description
type String Required This field identifies the type of the filter object, which must be one of
Enum the following:
v "hostname" – the filter value is matched against the hostname of the
virtual server
v "virtual-server-name" – the filter value is matched against the name
of the virtual server
v "os-type" – the filter value is matched against the operating system
type of the virtual server
v "os-level" – the filter value is matched against the operating system
level of the virtual server
v "os-name" – the filter value is matched against the operating system
name of the virtual server
operation String Required This field identifies the logical filter operation, which must be one of
Enum the following:
v "string-match" – the filter value must match the property defined by
the filter type
v "string-not-match" – the filter value must not match the property
defined by the filter type
value String Required A string to match the property against. Only patterns "." (to match any
(1-255) character) and ".*" (to match any character zero or more times) are
currently supported and ".*" may only be used at the end of the filter
value string. The following characters must be escaped to be used
directly: +-()[]$^.*\".

Notifications of property changes to performance policies

Notifications of property changes to Performance Policy objects are similar to notifications of changes to
workload objects.

Because Performance Policy objects are sub-objects of workload objects, creating or deleting a
performance policy does not result in an inventory notification. Instead, these operations result in the

1256 HMC Web Services API

 Level 04a

appropriate property notification for the target workload object. However, updating performance policy
properties results in property notifications for the policy itself. In these cases, the notification header
contains an element uri and an element id to indicate the performance policy that changed.

List Performance Policies

Use the List Performance Policies operation to list the performance policies within the target workload
resource group.

HTTP method and URI

GET /api/workload-resource-groups/{workload-id}/performance-policies

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
requesting a list of performance policies.

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. If a match is found, the
response is an array with all policies that match. If no match is
found, the response is an empty array.

Response body contents

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

Field name Type Description

perf-policies Array of Array of nested perf-policy-info objects as the following table.
objects

Each nested perf-policy-info object contains the following fields:

Field name Type Description

element-uri String/URI Canonical URI path of the Performance Policy object, in the form
/api/workload-resource-groups/{workload-id}/performance-policies/
{policy-id}.
element-id String The element-id of the Performance Policy object. This field value is the
{policy-id} portion of the URI path provided by the element-uri field.
name String Display name of the Performance Policy object.
activation-status String The status of the Performance Policy object, which must be one of the
Enum following values:
v "not-active" – the performance policy is not currently the active policy for
the workload resource group
v "in-progress" – the performance policy is currently being activated for the
workload resource group
v "active" – the performance policy is currently the active policy for the
workload resource group, and its activation has completed

Chapter 18. Workload resource group management 1257

 Level 04a

Description
The List Performance Policies operation lists the performance policies that belong to the workload
resource group targeted by the request URI. The element URI, element ID, display name, and status are
provided for each.

If the name query parameter is specified, the returned list is limited to the policies in the workload
resource group that have a name property matching the specified filter pattern. If the name parameter is
omitted, this filtering is not done.

An error response is returned if the HMC does not manage the targeted workload resource group or if
you do not have the requirements listed in “Authorization requirements.”

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the workload object passed in the request URI. A policy is included in the
list only if you also have object-access permission for that policy object.

HTTP status and reason codes

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

Otherwise, 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 ({workload-id}) does not designate an existing
workload 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/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies HTTP/1.1
x-api-session: 67prscbokwxz6o1bn1q3feysece2q4275agf27uupjnvr98lse

Figure 690. List Performance Policies: Request

1258 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Mon, 28 Nov 2011 05:09:12 GMT
content-type: application/json;charset=UTF-8
content-length: 509
{
"perf-policies": [
{
"activation-status": "not-active",
"element-id": "13ec9170-197f-11e1-8914-00215e6a0c26",
"element-uri": "/api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/13ec9170-197f-11e1-8914-00215e6a0c26",
"name": "Default"
},
{
"activation-status": "active",
"element-id": "160c563e-197f-11e1-8914-00215e6a0c26",
"element-uri": "/api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/160c563e-197f-11e1-8914-00215e6a0c26",
"name": "Prime Shift"
}
]
}

Figure 691. List Performance Policies: Response

Get Performance Policy Properties

Use the Get Performance Policy Properties operation to retrieve the properties of a single performance
policy.

HTTP method and URI

GET /api/workload-resource-groups/{workload-id}/performance-policies/{policy-id}

URI variables

Variable Description
{workload-id} Object ID of the workload object for the workload resource group to which the
performance policy is defined.
{policy-id} Element ID of the Performance Policy object for which properties are to be
obtained.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Performance Policy object as defined in “Data model” on page 1252. 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 Performance Policy Properties operation returns the current properties for the Performance
Policy object specified by {policy-id}.

Chapter 18. Workload resource group management 1259

 Level 04a

An error response is returned if the targeted workload resource group or policy does not exist or if you
do not have the requirements listed in “Authorization requirements.”

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the workload object passed in the request URI.

HTTP status and reason codes

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

Otherwise, 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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.
62 The element id in the URI ({policy-id}) does not designate an existing
Performance Policy object in the workload resource group.

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/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/160c563e-197f-11e1-8914-00215e6a0c26 HTTP/1.1
x-api-session: 67prscbokwxz6o1bn1q3feysece2q4275agf27uupjnvr98lse

Figure 692. Get Performance Policy Properties: Request

1260 HMC Web Services API

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Mon, 28 Nov 2011 05:09:12 GMT
content-type: application/json;charset=UTF-8
content-length: 1586
{
"activation-status": "active",
"class": "performance-policy",
"created-by": "ENSADMIN",
"created-date": 1322456941929,
"custom-service-classes": [
{
"business-importance": "highest",
"classification-rule": {
"filter": {
"operation": "string-match",
"type": "virtual-server-name",
"value": "SS\\-Premium\\-Web\\-Svr\\-.*"
},
"type": "rule"
},
"description": "",
"goal-type": "velocity",
"name": "Premium Class",
"type": "server",
"velocity": "fastest"
},
{
"business-importance": "high",
"classification-rule": {
"filter": {
"operation": "string-match",
"type": "virtual-server-name",
"value": "SS\\-Web\\-Svr\\-.*"
},
"type": "rule"
},
"description": "",
"goal-type": "velocity",
"name": "Regular Class",
"type": "server",
"velocity": "moderate"
}
],

Figure 693. Get Performance Policy Properties: Response (Part 1)

Chapter 18. Workload resource group management 1261

 Level 04a

"default-service-class": {
"business-importance": "medium",
"classification-rule": {
"filter": {
"operation": "string-match",
"type": "(\\*)",
"value": "(\\*)"
},
"type": "rule"
},
"description": "The default workload performance policy service class.",
"goal-type": "velocity",
"name": "Default",
"type": "server",
"velocity": "moderate"
},
"description": "Performance policy for prime shift",
"element-id": "160c563e-197f-11e1-8914-00215e6a0c26",
"element-uri": "/api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/160c563e-197f-11e1-8914-00215e6a0c26",
"importance": "highest",
"is-default": false,
"last-activated-by": "ENSADMIN",
"last-activation-completed-date": 1322456944022,
"last-activation-requested-date": 1322456942144,
"last-modified-by": "ENSADMIN",
"last-modified-date": 1322456942090,
"name": "Prime Shift",
"parent": "/api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26",
"revision": 2
}

Figure 694. Get Performance Policy Properties: Response (Part 2)

Create Performance Policy

Use the Create Performance Policy operation to create a new custom performance policy for a workload
resource group. The new policy must be uniquely named within the workload resource group. The policy
is inactive until the Activate Performance Policy operation is applied to it.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/performance-policies

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
creating a new performance policy.

Request body contents

The request body contains properties used to define the new performance policy, which are the writable
properties of a performance policy. Some properties are optional.

Field name Type Rqd/Opt Description

name String Required The name to give the new performance policy, as described in “Data
(1-64) model” on page 1252. The passed name must be unique among all
other policies currently in the workload resource group.
description String Optional The description to give the new performance policy, as described in
(0-256) “Data model” on page 1252.

1262 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

importance String Required The importance value to give the new performance policy, as
Enum described in “Data model” on page 1252.
custom-service- Array of Optional The ordered list of custom service classes in the new performance
classes objects policy. Each service class is an object in the form of a service class
(0-99) object, as described in “Service class nested object” on page 1254.
This array can contain from 0 to 99 entries.

Response body contents

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

Field name Type Description

element-uri String/URI Canonical URI path of the Performance Policy object, in the form
/api/workload-resource-groups/{workload-id}/performance-policies/
{policy-id}

Description
The Create Performance Policy operation creates a new custom performance policy in a workload
resource group, identified by {workload-id}.

On successful execution, the performance policy is created and added to the workload resource group
and status code 201 is returned with a response body containing a reference to the new Performance
Policy object. Note that the new policy is not active until the Activate Performance Policy operation is
applied to it.

An error response is returned if the targeted workload resource group does not exist or if you do not
have the requirements listed in “Authorization requirements.” Targeting the default workload object also
results in an error because the default workload resource group cannot contain any performance policy
other than the default performance policy.

The request body is validated against the data model for this object type to ensure that it contains only
writable properties and that the data types of those properties are specified 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.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Action/task permission to the New Performance Policy task.

HTTP status and reason codes

On successful completion, HTTP status code 201 (Created) is returned and the response body is provided
as described in “Response body contents.”

Otherwise, 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 18. Workload resource group management 1263

 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.
60 The targeted workload resource group is the default workload object.
65 The name of the performance policy is not unique within its workload
resource group, or one or more of the defined service class names is reserved
or not unique.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
415 (Unsupported 0 The request does not include a Content-Type header that specifies the
Media Type) request body is of media type application/xml.

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/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/performance-policies HTTP/1.1

x-api-session: 67prscbokwxz6o1bn1q3feysece2q4275agf27uupjnvr98lse
content-type: application/json
content-length: 101
{
"description": "Performance policy for prime shift",
"importance": "highest",
"name": "Prime Shift"
}

Figure 695. Create Performance Policy: Request

201 Created
server: zSeries management console API web server / 1.0
location: /api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/160c563e-197f-11e1-8914-00215e6a0c26
cache-control: no-cache
date: Mon, 28 Nov 2011 05:09:01 GMT
content-type: application/json;charset=UTF-8
content-length: 142
{
"element-uri": "/api/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/160c563e-197f-11e1-8914-00215e6a0c26"
}

Figure 696. Create Performance Policy: Response

Delete Performance Policy

Use the Delete Performance Policy operation to remove a performance policy from a workload resource
group. This operation cannot be performed on an active or default performance policy.

1264 HMC Web Services API

 Level 04a

HTTP method and URI

DELETE /api/workload-resource-groups/{workload-id}/performance-policies/{policy-id}

URI variables

Variable Description
{workload-id} Object ID of the workload object whose Performance Policy object is to be
deleted.
{policy-id} Element ID of the Performance Policy object that is to be deleted.

Description
The Delete Performance Policy operation deletes the Performance Policy object specified by {policy-id}
from its workload resource group specified by {workload-id}.

On successful execution, the Performance Policy object is removed from the workload resource group and
status code 204 (No Content) is returned without a response body.

An error response is returned if the targeted policy object does not exist or if you do not have the
requirements listed in “Authorization requirements.” Targeting a default performance policy also results
in an error because the default performance policy cannot be deleted. You also cannot delete an active
performance policy without first activating another performance policy through the Activate Performance
Policy operation.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Action/task permission to the Delete Performance Policy task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned without a response body.

Otherwise, 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.
63 The targeted performance policy is a default Performance Policy object.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.
62 The element id in the URI ({policy-id}) does not designate an existing
Performance Policy object in the workload resource group.

Chapter 18. Workload resource group management 1265

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
60 The performance policy to be deleted is currently active or in the progress of
being activated. The operation can be retried after a different policy has been
activated, which causes the activation-status of this policy to be "not-active".

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/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/
performance-policies/160c563e-197f-11e1-8914-00215e6a0c26 HTTP/1.1
x-api-session: 67prscbokwxz6o1bn1q3feysece2q4275agf27uupjnvr98lse

Figure 697. Delete Performance Policy: Request

204 No Content
date: Mon, 28 Nov 2011 05:09:22 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 698. Delete Performance Policy: Response

Update Performance Policy

Use the Update Performance Policy operation to modify one or more writable properties of a
Performance Policy object. Note that updating an active performance policy causes its reactivation.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/performance-policies/{policy-id}

URI variables

Variable Description
{workload-id} Object ID of the workload object to which the target performance policy is
defined.
{policy-id} Element ID of the Performance Policy object that is to be modified.

Request body contents

The request body is a JSON object containing one or more of the writable fields for a performance policy,
as described in “Data model” on page 1252. You need to supply only those fields that you want to
modify.

1266 HMC Web Services API

 Level 04a

Description
The Update Performance Policy operation updates one or more writable properties of the Performance
Policy object identified by {policy-id}.

On successful execution, the Performance Policy object is updated with the supplied property values and
status code 204 (No Content) is returned without a response body. Notifications for these property
changes are sent asynchronously to this operation.

If the performance policy is active at the time of this request, a reactivation of the policy is submitted
asynchronously to this operation. Because activation of a performance policy is rejected if another
activation request is in progress for the target workload resource group, an update to an active
performance policy also can be rejected. In this case, a 409 (Conflict) status code is returned and you can
retry the update operation after the first activation completes.

An error response is returned if the targeted workload resource group or performance policy does not
exist or if you do not have the requirements listed in “Authorization requirements.” Targeting the default
performance policy also results in an error because the default performance policy cannot be directly
modified.

The request body is validated against the schema described in “Request body contents” on page 1266. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Action/task permission to the Performance Policy Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned without a response body.

Otherwise, 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.
63 The targeted performance policy is a default Performance Policy object.
65 The new name given to the performance policy is not unique within its
workload resource group, or one or more of the defined service class names
are reserved or not unique.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.
62 The element id in the URI ({policy-id}) does not designate an existing
Performance Policy object in the workload resource group.

Chapter 18. Workload resource group management 1267

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
60 The performance policy to be updated is currently in the progress of being
activated. The operation can be retried after activation has completed.

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/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/performance-policies/
160c563e-197f-11e1-8914-00215e6a0c26 HTTP/1.1
x-api-session: 67prscbokwxz6o1bn1q3feysece2q4275agf27uupjnvr98lse
content-type: application/json
content-length: 580
{
"custom-service-classes": [
{
"business-importance": "highest",
"classification-rule": {
"filter": {
"operation": "string-match",
"type": "virtual-server-name",
"value": "SS\\-Premium\\-Web\\-Svr\\-.*"
},
"type": "rule"
},
"goal-type": "velocity",
"name": "Premium Class",
"type": "server",
"velocity": "fastest"
},
{
"business-importance": "high",
"classification-rule": {
"filter": {
"operation": "string-match",
"type": "virtual-server-name",
"value": "SS\\-Web\\-Svr\\-.*"
},
"type": "rule"
},
"goal-type": "velocity",
"name": "Regular Class",
"type": "server",
"velocity": "moderate"
}
]
}

Figure 699. Update Performance Policy: Request

1268 HMC Web Services API

 Level 04a

204 No Content
date: Mon, 28 Nov 2011 05:09:01 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 700. Update Performance Policy: Response

Activate Performance Policy

Use the Activate Performance Policy operation to activate a performance policy for a workload resource
group. You can activate any performance policy defined to the workload resource group, including the
default and currently active policy.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/performance-policies/{policy-id}/operations/activate

URI variables

Variable Description
{workload-id} Object ID of the workload object to which the target performance policy is
defined.
{policy-id} Element ID of the Performance Policy object that is to be activated.

Description
The Activate Performance Policy operation activates or reactivates a performance policy for a specific
workload resource group.

On successful execution, the target policy is active and status code 204 (No Content) is returned without
a response body. Notifications for ensuing property changes are sent asynchronously to this operation.

An activation request is not accepted if another activation request is in progress for this workload
resource group. In this case, status code 409 (Conflict) is returned and you can retry this operation after
the first activation completes.

An error response is returned if the targeted workload resource group or performance policy does not
exist or if you do not have the requirements listed in “Authorization requirements.” Targeting the default
workload resource group also results in an error because its default performance policy is permanently
active.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Action/task permission to the Activate Performance Policy task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned without a response body.

Chapter 18. Workload resource group management 1269

 Level 04a

Otherwise, 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.
60 The targeted workload resource group is the default workload object.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.
62 The element id in the URI ({policy-id}) does not designate an existing
Performance Policy object in the workload resource group.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
60 Performance policy activation is currently in progress on the workload
resource group. The operation can be retried after activation has completed.

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/workload-resource-groups/13de1bfe-197f-11e1-8914-00215e6a0c26/performance-policies/
160c563e-197f-11e1-8914-00215e6a0c26/operations/activate HTTP/1.1
x-api-session: 67prscbokwxz6o1bn1q3feysece2q4275agf27uupjnvr98lse

Figure 701. Activate Performance Policy: Request

204 No Content
date: Mon, 28 Nov 2011 05:09:01 GMT
server: zSeries management console API web server / 1.0
cache-control: no-cache

<No response body>

Figure 702. Activate Performance Policy: Response

Import Performance Policy

Use the Import Performance Policy operation to create a new custom performance policy for a workload
resource group. This operation is equivalent to the Create Performance Policy operation, except the
request body is an XML document defining the configuration of the performance policy to be created.
The new policy must be uniquely named within the workload resource group. The policy is inactive until
the Activate Performance Policy operation is applied to it.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/operations/import-performance-policy

1270 HMC Web Services API

 Level 04a

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
importing a performance policy.

Request body contents

The request body must contain an XML document that describes the performance policy to be created.
The XML must conform to the schema described in Appendix A, “XML document structure of a
performance policy,” on page 1385. Note that the same rules apply as for the Create Performance Policy
operation, that the name must be unique within the workload.

Because the request body is expected to be in XML format, the request should specify MIME type
application/xml as the value of the HTTP Content-Type header for the request.

Response body contents

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

Field name Type Description

element-uri String/URI Canonical URI path of the Performance Policy object, in the form
/api/workload-resource-groups/{workload-id}/performance-policies/
{policy-id}

Description
The Import Performance Policy operation imports a performance policy from an XML document and
creates a Performance Policy object, adding it to the workload resource group identified by {workload-id}.

On successful execution, the Performance Policy object is created with the supplied property values,
added to the collection of custom performance policies for the workload resource group. Status code 201
(Created) is returned with a response body describing the location of the new Performance Policy object.
Note that the new policy is not active until the Activate Performance Policy operation is applied to it.

An error response is returned if the targeted workload does not exist or if you do not have the
requirements listed in “Authorization requirements.” Targeting the default workload object also results in
an error because the default workload resource group cannot contain any performance policy other than
the default performance policy.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Action/task permission to the Import Performance Policy task.

HTTP status and reason codes

On successful completion, HTTP status code 201 (Created) is returned and the response body is provided
as described in “Response body contents.”

Otherwise, 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 18. Workload resource group management 1271

 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.
60 The targeted workload resource group is the default workload object.
65 The name of the performance policy is not unique within its workload
resource group, or one or more of the defined service class names is reserved
or not unique.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
415 (Unsupported 0 The request does not include a Content-Type header that specifies the
Media Type) request body is of media type application/xml.

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

Export Performance Policy

Use the Export Performance Policy operation to return the configuration of an existing performance
policy in the form of an XML document.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/performance-policies/{policy-id}/operations/export

URI variables

Variable Description
{workload-id} Object ID of the workload object for the workload resource group to which the
performance policy is defined.
{policy-id} Element ID of the Performance Policy object to be exported.

Response body contents

On successful completion, the performance policy is returned in the response body as an XML document
that conforms to the schema described in Appendix A, “XML document structure of a performance
policy,” on page 1385.

Description
The Export Performance Policy operation returns the configurable properties of an existing performance
policy identified by {policy-id} in a workload resource group identified by {workload-id}. The policy
configuration is returned in the form of an XML document. You can save this XML as a backup copy of
the policy configuration or modify and import it through the Import Performance Policy operation to
create a new custom policy.

On successful execution, the Performance Policy object returned as a XML document with status code 200
(OK).

1272 HMC Web Services API

 Level 04a

An error response is returned if the targeted workload resource group or policy does not exist or if you
do not have the requirements listed in “Authorization requirements.”

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Action/task permission to the Export Performance Policy task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({workload-id}) does not designate an existing
workload object, or the API user does not have object-access permission to
the object.
62 The element id in the URI ({policy-id}) does not designate an existing
Performance Policy object in the workload resource group.

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/workload-resource-groups/e39812b2-209d-11e1-8bbc-0010184c8334/performance-policies/
e44af260-209d-11e1-8bbc-0010184c8334/operations/export HTTP/1.1
x-api-session: 2ggnk3nbcxsqi8w8qbjpnl4pqhwgkvdrdu5hw8pjw1o171qu2r

Figure 703. Export Performance Policy: Request

Chapter 18. Workload resource group management 1273

 Level 04a

200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Wed, 07 Dec 2011 06:37:21 GMT
content-type: application/xml;charset=utf-8
content-length: 1515
<?xml version="1.0" encoding="UTF-8"?>

<PerformancePolicy xmlns="http://www.ibm.com/PPM/WorkloadPerformancePolicy-1.0">
<Name>Prime Shift</Name>
<Description>Performance policy for prime shift</Description>
<Version>3.00.00</Version>
<UI>PPM Editor</UI>
<WorkloadImportance>Highest</WorkloadImportance>

<ServiceClasses>

<ServiceClass>
<Name>Premium Class</Name>
<Type>Server</Type>
<RuleBuilderElement>
<RuleBuilderElementType>Rule</RuleBuilderElementType>
<Filter>
<FilterType>Virtual Server Name</FilterType>
<FilterOperation>stringMatch</FilterOperation>
<FilterValue>SS\\-Premium\\-Web\\-Svr\\-\.\*</FilterValue>
</Filter>
</RuleBuilderElement>
<Goal>
<Velocity>
<Importance>Highest</Importance>
<Level>Fastest</Level>
</Velocity>
</Goal>
</ServiceClass>

<ServiceClass>
<Name>Regular Class</Name>
<Type>Server</Type>
<RuleBuilderElement>
<RuleBuilderElementType>Rule</RuleBuilderElementType>
<Filter>
<FilterType>Virtual Server Name</FilterType>
<FilterOperation>stringMatch</FilterOperation>
<FilterValue>SS\\-Web\\-Svr\\-\.\*</FilterValue>
</Filter>
</RuleBuilderElement>
<Goal>
<Velocity>
<Importance>High</Importance>
<Level>Moderate</Level>
</Velocity>
</Goal>
</ServiceClass>

</ServiceClasses>

</PerformancePolicy>

Figure 704. Export Performance Policy: Response

1274 HMC Web Services API

 Level 04a

Performance management reports

Through specific APIs described in this topic, you can request zManager to generate historical reports
that contain performance data related to specific performance management objects. You can request data
for a specific time interval, up to 36 hours before the current time. Because the actual performance
management objects might have changed since the time interval you request, or actually might not exist
now, the performance management report APIs are not object-based.

Instead, all of the report APIs are implemented as performance-management specific operations that
request an on-demand report to be generated and returned to the caller. They accept query parameters in
a request block, and query the historical reporting database to generate a custom report for the caller.

The performance management report APIs are interrelated because you can use certain properties
retrieved from one report as input to generate other reports, just as you can drill down for more
information through the report tasks in the HMC UI.

Figure 705 on page 1276 shows how the performance management reports are related, along with an
indication of which properties you can use from one report to generate the next one through the APIs.
Once you receive these properties in the response to an API request for one report, you can repeatedly
reuse them as input properties for subsequent reports for the same performance management object,
regardless of the time interval for the report.

For example, suppose that you use the API to request a Virtual Servers Report for the ensemble and the
response body includes a hypervisor-report-id property. At any time in the future, you can use the
hypervisor-report-id property directly to request a Hypervisor Report, rather than having to drill down
to it again through the Virtual Servers Report. The *-report-id property values do not change across
invocations of the reporting APIs; instead, the values remain constant over time.

Chapter 18. Workload resource group management 1275

 Level 04a

Workload Resource Groups Workload Resource

Report Group Resource
workload-report-id Adjustments Report

Workload Resource
Group Performance
Virtual Servers Report Index Report
workload-report-id,
virtual-server-report-id,
hypervisor-report-id

Virtual Server Resource

Adjustments Report

Virtual Server CPU

Utilization Report

Hypervisor Report Hypervisor

hypervisor-report-id Resource
Adjustments Report

Service Classes Report

workload-report-id,
service-class-report-id

Service Class Hops

Report

Service Class Virtual

Server Topology Report

Service Class Resource Load Balancing

Adjustments Report Report

Figure 705. Relationship between reports and the properties used

Generate Workload Resource Groups Report (Performance

Management)
Use the Generate Workload Resource Groups Report operation to create a custom on-demand report
that shows all workload resource groups in a specific ensemble over a requested time period. The report
is based on historical performance management data that was retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-workload-resource
-groups-report

1276 HMC Web Services API

 Level 04a

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a workload resource groups report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
report-workloads Array of Array of nested workload-report-entry objects described in Table 433.
objects

Each nested workload-report-entry object contains the following fields:

Table 433. Format of a workload-report-entry object
Field name Type Description
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific workload resource group named
in the workload-name field.
Note: This value is the same as one of the workload-report-id values that
are returned in the Workload Resource Groups Report for this same interval.
performance-policy- String The displayable name of the performance policy that was active during this
name reporting interval.

Chapter 18. Workload resource group management 1277

 Level 04a

Table 433. Format of a workload-report-entry object (continued)

Field name Type Description
performance-policy- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific performance policy named in the
performance-policy-name field.
Note: If more than one performance policy was activated over the span of
this reporting interval, only the name of the last one activated is returned in
this field. The multi-policy-activations field indicates whether more than
one policy was activated during this interval.
largest-pi-service- String The displayable name of the performance management service class that had
class-name the largest PI (performance index) value over this reporting interval.
Optional: This field is not returned if the performance index (PI) value
could not be calculated.
largest-pi-service- String An identifier used by the performance management reporting structure to
class-report-id keep track of reporting data for the specific service class named in
largest-pi-service-class-name field.
Optional: This field is not returned if the performance index (PI) value
could not be calculated.
largest-pi Float The largest PI (performance index) value over this reporting interval.
Optional: This field is not returned if the performance index (PI) value
could not be calculated.
multi-policy- Boolean Indicates whether more than one performance policy was activated over the
activations span of this reporting interval. The value is "true" if more than one policy or
"false" if only one policy was activated during this time interval.
cpu-utilization- Array of Array of nested cpu-utilization-range objects described in Table 434.
distribution objects
most-severe-perf- String The most severe perf-status value recorded for the workload over this
status Enum reporting interval. See “Data model” on page 1219 for more details about the
valid values of this property.
perf-status-data- Array of Array of nested perf-status-data-point objects described in Table 435.
points objects

Each nested cpu-utilization-range object contains the following fields:

Table 434. Format of a cpu-utilization-range object
Field name Type Description
low-boundary Float This value defines the low boundary of the CPU utilization range that this
object is covering.
high-boundary Float This value defines the high boundary of the CPU utilization range that this
object is covering.
virtual-server-count Integer This value is the number of virtual servers whose average CPU utilization
was within the CPU utilization range during the reporting interval.

Each nested perf-status-data-point object contains the following fields:

Table 435. Format of a perf-status-data-point object
Field name Type Description
time Integer Standard date/time value indicating the date and time that this performance
status value was recorded.

The standard time value is defined as the number of elapsed milliseconds

after midnight January 1, 1970.

1278 HMC Web Services API

 Level 04a

Table 435. Format of a perf-status-data-point object (continued)

Field name Type Description
perf-status Float The perf-status value of the workload at the recorded time. See the “Data
model” on page 1219 for more details about the valid values of this property.

Description
The Generate Workload Resource Groups Report operation generates a report that contains the
following information for the requested time interval:
v A list of all workload resource groups for which historical reporting information is available
v For each workload resource group:
– The active performance policy at that time
– A performance health indication (the performance index or PI) over that interval.
“Response body contents” on page 1277 describes the full list of data that is returned in this report for
each workload resource group. To request more detailed performance reporting data, you can use the
returned workload-report-id property for a specific workload resource group as input for additional
report operations.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements.”

The request body is validated against the schema described in “Request body contents” on page 1277. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Workloads Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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

Chapter 18. Workload resource group management 1279

 Level 04a

Example HTTP interaction

POST /api/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-workload-resource-groups-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 30
}

Figure 706. Generate Workload Resource Groups Report: Request

Generate Workload Resource Group Performance Index Report

Use the Generate Workload Resource Group Performance Index Report operation to create a custom
on-demand performance index report for a specific workload resource group over a requested time
period. The report is based on historical performance management data that was retained over that time
period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-workload-resource-group-
performance-index-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble containing the workload
resource group for which you want to receive a performance index report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
workload-report-id String Required The identifier used by the performance management reporting to
keep track of reporting data for the specific workload resource
group for which the report is being requested.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report
for this same interval.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.

1280 HMC Web Services API

 Level 04a

Field name Type Description

report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific workload resource group named
in the workload-name field.
pi-data-by-service- Array of Array of nested service-class-pi-data objects described in Table 436.
class objects

Each nested service-class-pi-data object contains the following fields:

Table 436. Format of a service-class-pi-data object
Field name Type Description
service-class-name String The displayable name of the service class.
service-class-report- String An identifier used by the performance management reporting structure to
id keep track of reporting data for the specific service class named in the
service-class-name field.
pi-data-points Array of Array of nested pi-data-point objects described in Table 437.
objects

Each nested pi-data-point object contains the following fields:

Table 437. Format of a pi-data-point object
Field name Type Description
pi-time Integer Standard date/time value indicating the requested starting date and time
that this data point was taken. The standard time value is defined as the
number of elapsed milliseconds after midnight on 1 January 1970.
pi-value Float The specific performance index (PI) value recorded at the date/time in the
pi-time field.

Description
The Generate Workload Resource Group Performance Index Report operation generates a report that
contains the following information for a specific workload resource group over the requested time
interval:
v A list of the services classes within the requested workload resource group for which performance
index data is available
v For each services class, a list of all of the individual PI data points that were recorded over that
interval. Each PI data point contains both the actual PI value and the date/time that it was recorded.
“Response body contents” on page 1280 describes the full list of data that is returned in this report for
each workload resource group. To request more detailed performance reporting data, you can use the
returned service-class-report-id property for a specific service class as input for additional report
operations.

Chapter 18. Workload resource group management 1281

 Level 04a

Note that when you request performance index information for a workload resource group through the
HMC UI, the resulting report is a line graph display that plots these PI values with plot points and a line
over time for each service class.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements.”

The request body is validated against the schema described in “Request body contents” on page 1280. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Workloads Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-workload-resource-group-performance-index-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group"
}

Figure 707. Generate Workload Resource Group Performance Index Report: Request

1282 HMC Web Services API

 Level 04a

Generate Workload Resource Group Resource Adjustments Report

Use the Generate Workload Resource Group Resource Adjustments Report operation to create a custom
on-demand resource adjustments report for a specific workload resource group over a requested time
period. The report is based on historical performance management data that was retained over that time
period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-workload-resource-group-
resource-adjustments-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble containing the workload
resource group for which you want to receive a resource adjustments report.

Request body contents

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

Field name Type Req/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
workload-report-id String Required The identifier used by the performance management reporting to
keep track of reporting data for the specific workload resource
group for which the report is being requested.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report
for this same interval.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific workload resource group named
in the workload-name field.

Chapter 18. Workload resource group management 1283

 Level 04a

Field name Type Description

successful-resource- Array of Array of nested successful-resource-adjustment objects. If no successful
adjustments objects adjustments occurred during the requested time interval, an empty array is
returned.
failed-resource- Array of Array of nested failed-resource-adjustment objects. If no failed
adjustments objects adjustments occurred during the requested time interval, an empty array is
returned.

Each nested successful-resource-adjustment object contains the following fields:

Field name Type Description

hypervisor-type String The value of the type property of the virtualization host. See the
Enum virtualization host “Data model” on page 987 for more details about the
valid values of this property.
adjustment-time Integer Standard date/time value indicating the requested starting date and time of
the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
receiver-virtual- String The name of the virtual server that was given additional resources.
server-name
receiver-workload- String The displayable name of the workload resource group that was given
name additional resources.
receiver-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the receiver-workload-name field.
receiver-service- String The displayable name of the service class within the workload resource
class-name group that was given additional resources.
receiver-service- String An identifier used by the performance management reporting structure to
class-report-id keep track of reporting data for the specific service class named in the
receiver-service-class-name field.
receiver-processing- Float The total number of processing units the receiver had after the additional
units-after resources were given to it.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
receiver-processing- Float The total number of processing units the receiver had before the additional
units-before resources were given to it.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
adjustment-donors Array of Array of nested adjustment-donors objects.
objects

Each nested adjustment-donors object contains the following fields:

Field name Type Description

donor-virtual-server- String The name of a virtual server that gave up resources as part of this
name adjustment.

1284 HMC Web Services API

 Level 04a

Field name Type Description

donor-processing- Float The total number of processing units this donor had after it gave up
units-after resources.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
donor-processing- Float The total number of processing units this donor had before it gave up
units-before resources.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
donor-workload-names Array of The displayable names of all workload resource groups that donated
strings resources when this donor virtual server gave up resources.

Each nested failed-resource-adjustment object contains the following fields:

Field name Type Description

hypervisor-type String The value of the type property of the virtualization host. See the
Enum virtualization host “Data model” on page 987 for more details about the
valid values of this property.
adjustment-time Integer Standard date/time value indicating the requested starting date and time of
the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
receiver-virtual- String The name of the virtual server that needed but did not receive additional
server-name resources.
receiver-workload- String The displayable name of the workload resource group that needed but did
name not receive additional resources.
receiver-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the receiver-workload-name field.
receiver-service- String The displayable name of the service class within the workload resource
class-name group that needed but did not receive additional resources.
receiver-service- String An identifier used by the performance management reporting structure to
class-report-id keep track of reporting data for the specific service class named in the
receiver-service-class-name field.
adjustment-fail- String The reason why the adjustment failed. Values are:
reason Enum v "not-enough-capacity" — The sum of the capacity that could be given up
by all the available donors in the group was not enough to meet the
capacity increase request of the intended receiver.
v "no-potential-donors" — The group did not contain any potential donors
so no assessments for increased capacity could be sent.
v "entitled-capacity-not-achievable" — The extra capacity required to be
added to the entitled capacity would have pushed the total beyond the
maximum entitled capacity.
v "processor-not-fully-utilized" — The virtual server is not fully using the
processors it already has, so adding more will not have any effect.
v "requested-more-shares-than-max" — More shares than the maximum
allowed for this virtual server were requested.
v "not-enough-virtual-cpus" — Not enough virtual CPUs were available for
the projected required total consumed capacity to be achieved.
v "unknown" — Unknown uncategorized failure reason.

Chapter 18. Workload resource group management 1285

 Level 04a

Description
The Generate Workload Resource Group Resource Adjustments Report operation generates a report
that contains the following information for a specific workload resource group over the requested time
interval:
v A list of resource adjustments that zManager successfully made to maintain specified performance
goals. For successful adjustments, the report includes:
– A list of workload resource groups and the virtual servers that received additional resources
(receivers)
– A list of workload resource groups and the virtual servers that donated the additional resources
(donors)
v A list of resource adjustments that zManager attempted but failed to make, along with a reason for the
failure.
“Response body contents” on page 1283 describes the full list of data that is returned in the report for
this workload resource group.

Additional types of resource adjustment reports are available. This particular generate-workload-resource-
group-resource-adjustments-report operation generates a resource adjustments report for a specific
workload over the requested time period. What this means is that it will contain entries for all
adjustments that affected the particular workload submitted; meaning all of the entries returned will
involve that specific workload either having received additional resources, or having been forced to give
up (donate) some of its resources.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements.”

The request body is validated against the schema described in “Request body contents” on page 1283. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Workloads Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

1286 HMC Web Services API

 Level 04a

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-workload-resource-group-resource-adjustments-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group"
}

Figure 708. Generate Workload Resource Group Resource Adjustments Report: Request

Generate Virtual Servers Report

Use the Generate Virtual Servers Report operation to create a custom on-demand report that shows all
virtual servers that were members of a particular workload resource group over a requested time period.
The report is based on historical performance management data that was retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-virtual-servers-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a virtual server report.

Request body contents

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

Field name Type Req/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
workload-report-id String Required The identifier used by the performance management reporting to
keep track of reporting data for the specific workload resource
group for which the report is being requested.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report
for this same interval.

Chapter 18. Workload resource group management 1287

 Level 04a

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific workload resource group named
in the workload-name field.
report-virtual- Array of Array of nested virtual-server-report-entry objects.
servers objects

Each nested virtual-server-report-entry object contains the following fields:

Field name Type Description

virtual-server-name String The displayable name of the virtual server.
virtual-server- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific virtual server named in the
virtual-server-name field.
hypervisor-type String The value of the type property of the virtualization host. See the
virtualization host “Data model” on page 987 for more details about the
valid values of this property.
hypervisor-name String The displayable name of the hypervisor under which this virtual server was
running.
hypervisor-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific hypervisor under which this
virtual server was running. (Hypervisor names returned in the
hypervisor-name field are not unique).
defined-cpc-name String The name of the central processor complex (CPC) with which this virtual
server was associated.
was-active Boolean Indicates whether this virtual server was actually active during this reporting
interval. It will be true if it was active and false if it was not active. If this
field is false, none of the fields in this next table this one can have data; so in
that case none of the fields below here will be returned.
os-name String The name of the operating system image that is running on the virtual server
as known to its operating system. Optional: This field is returned only if the
virtual server was active and a guest platform management provider was
running on the virtual server during this interval.

1288 HMC Web Services API

 Level 04a

Field name Type Description

os-type String The type of operating system that is running on the virtual server. Optional:
This field is returned only if the virtual server was active and a guest
platform management provider was running on the virtual server during this
interval.
os-level String The release level of the operating system that is running on the virtual
server. Optional: This field is returned only if the virtual server was active
and a guest platform management provider was running on the virtual
server during this interval.
hostname-ipaddr String The host name (or IP address) of the virtual server. Optional: This field is
returned only if the virtual server was active and a guest platform
management provider was running on the virtual server during this interval.
virtual-processors String The number of virtual processors associated with this virtual server.
Optional: This field is returned only if the virtual server was active during
this interval.
allocated-memory String For the x Hyp, PowerVM, and PR/SM hypervisor types, this field contains
the allocated memory (in MB) configured for the virtual server. For z/VM,
this field contains the amount of virtual memory currently resident in real
memory for the guest. Optional: This field is returned only if the virtual
server was active during this interval.
physical-cpu- Float The physical processor utilization percentage (%) of the virtual server. This
utilization-percent percentage is in fractional form (between 0 and 1 inclusive). Optional: This
field is returned only if the virtual server was active during this interval.
hypervisor-cpu-delay- Float The hypervisor processing unit delay in fractional form (between 0 and 1
percent inclusive). This field is returned for the following hypervisors only: z/VM
and PowerVM. In the case of z/VM, a value is available for this field only if
sampling is turned on for the guest. Optional: This field is returned only if
the virtual server was active during this interval and if the hypervisor type
supports this information.
idle-time-percent Float The idle time percentage (%) of the virtual server. It is the percentage of total
time that the virtual server had no work (that is, no application processes or
internal hypervisor specific process states). This percentage is in fractional
form (between 0 and 1 inclusive). Optional: This field is returned only if the
virtual server was active during this interval and if the hypervisor type
supports this information. For z/VM, this data is available only when
sampling is enabled and started. For PowerVM and PR/SM, idle time data is
not available.
other-time-percent Float The percentage (%) of total time that miscellaneous hypervisor specific
internal process states had control for this virtual server. In other words, the
percentage of time that the virtual server was not idle but also was not in a
state of active CPU utilization or hypervisor CPU delay. This percentage is in
fractional form (between 0 and 1 inclusive). Optional: This field is returned
only if the virtual server was active during this interval and if the hypervisor
type supports this information. For z/VM, this data is available only when
sampling is enabled and started. For PowerVM and PR/SM, other time data
is not available.
service-class-name String The displayable name of the service class. Optional: This field is returned
only if the virtual server was active and if the virtual server was associated
with a specific service class within the requested workload resource group
during this interval.
service-class-report- String An identifier used by the performance management reporting structure to
id keep track of reporting data for the specific service class named in the
service-class-name field. Optional: This field is returned only if the
service-class-name field is returned.

Chapter 18. Workload resource group management 1289

 Level 04a

Field name Type Description

pi-value Float The average performance index (PI) value calculated over this reporting
interval for the service class returned in the service-class-name field. This
field is not returned if the virtual server was not active or if a PI value could
not be calculated.
os-cpu-using-samples- Float The percentage of CPU using samples from among the total samples. For
percent example, if there are 10 CPU using samples out of a total of 10 samples, then
CPU using samples is 100% (because out of the total samples, all are CPU
using samples). This percentage is in fractional form (between 0 and 1
inclusive). Optional: This field is returned only if the virtual server was
active and a guest platform management provider was running on the
virtual server during this interval.
os-cpu-delay-samples- Float The percentage of CPU delay samples from among the total samples. For
percent example, if there are 10 CPU delay samples and 10 samples that are not CPU
delay samples, then CPU delay samples is 50% (because out of the total
samples half are CPU delay samples). This percentage is in fractional form
(between 0 and 1 inclusive). Optional: This field is returned only if the
virtual server was active and a guest platform management provider was
running on the virtual server during this interval.
os-io-delay-samples- Float The percentage of I/O delay samples from among the total samples. The
percent percent I/O delay is the percent of samples taken when work was delayed
for non-paging DASD I/O. The I/O delay includes IOS queue, subchannel
pending, and control unit queue delays. For example, if there are 10 I/O
delay samples and 10 samples that are not I/O delay samples, then I/O
delay samples is 50% (because out of the total samples half are I/O delay
samples). This percentage is in fractional form (between 0 and 1 inclusive).
Optional: This field is returned only if the virtual server was active and a
guest platform management provider was running on the virtual server
during this interval.
os-page-delay- Float The percentage of page delay samples from among the total samples. The
samples-percent percent page delay is the percent of samples when the address space
experienced page faults in cross-memory access, and the page faults were
resolved from auxiliary storage. For example, if there are 10 page delay
samples and 10 samples that are not page delay samples, then page delay
samples is 50% (because out of the total samples half are page delay
samples). This percentage is in fractional form (between 0 and 1 inclusive).
Optional: This field is returned only if the virtual server was active and a
guest platform management provider was running on the virtual server
during this interval.

Description
The Generate Virtual Servers Report operation generates a report that contains the following information
for a specific workload resource group over the requested time interval:
v A list of all virtual servers that were members in that specific workload resource group for which
historical reporting information is available
v For each virtual server:
– The unique performance reporting identifier for the virtual server
– The name and unique performance reporting identifier of the hypervisor under which the virtual
server was running
– An indication of whether the virtual server was active over the reporting interval.
“Response body contents” on page 1288 describes the full list of data that is returned in this report for
each virtual server. To request more detailed performance reporting data, you can use the returned
virtual-server-report-id, hypervisor-report-id, and service-class-report-id properties as input for
additional report operations.

1290 HMC Web Services API

 Level 04a

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements.”

The request body is validated against the schema described in “Request body contents” on page 1287. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Virtual Servers Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-virtual-servers-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group"
}

Figure 709. Generate Virtual Servers Report: Request

Generate Virtual Server CPU Utilization Report

Use the Generate Virtual Server CPU Utilization Report operation to create a custom on-demand report
that shows the processor (CPU) utilization for a specific virtual server over a requested time period. The
report is based on historical performance management data that was retained over that time period.

Chapter 18. Workload resource group management 1291

 Level 04a

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-virtual-server-
cpu-utilization-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a virtual server CPU utilization report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
virtual-server- String Required An identifier used by the performance management reporting
report-id structure to keep track of reporting data for the specific virtual
server named in the virtual-server-name field. This value is the
same as one of the virtual-server-report-id values that are returned
in the Virtual Servers Report. Alternatively, you can supply the
object-id property value of an existing Virtual Server object.
hypervisor-report- String Required An identifier used by the performance management reporting
id structure to keep track of reporting data for the specific hypervisor
under which this virtual server was running. (Hypervisor names
returned in the hypervisor-name field are not unique). This value is
the same as the hypervisor-report-id value that is returned for this
virtual server in the Virtual Servers Report. Alternatively, you can
supply the object-id property value of an existing Virtualization
Host object.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
virtual-server- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific virtual server named in the
virtual-server-name field.
virtual-server-name String The displayable name of the virtual server.

1292 HMC Web Services API

 Level 04a

Field name Type Description

hypervisor-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific hypervisor under which this
virtual server was running. (Hypervisor names returned in the
hypervisor-name field are not unique).
hypervisor-name String The displayable name of the hypervisor under which this virtual server was
running.
cpu-utilization-data- Array of Array of nested cpu-utilization-data-points objects.
points objects

Each nested cpu-utilization-data-points object contains the following fields:

Field name Type Description

cpu-utilization-time Integer Standard date/time value indicating the requested starting date and time
that this data point was taken. The standard time value is defined as the
number of elapsed milliseconds after midnight on 1 January 1970.
cpu-utilization-value Float The specific CPU utilization value recorded at the date/time in the
cpu-utilization-time field. This value is in fractional form representing a
percentage (between 0 and 1 inclusive).

Description
The Generate Virtual Server CPU Utilization Report operation generates a report that contains the
following information for a specific virtual server over the requested time interval:
v All of the individual CPU utilization data points for that virtual server that were recorded over the
requested reporting interval. Each CPU utilization data point contains both the actual CPU utilization
value and the date/time that it was recorded.
“Response body contents” on page 1292 describes the full list of data that is returned in this report for
each virtual server.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements.”

The request body is validated against the schema described in “Request body contents” on page 1292. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Virtual Servers Report task.

HTTP status and reason codes

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

Otherwise, 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 18. Workload resource group management 1293

 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-virtual-server-cpu-utilization-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"virtual-server-report-id": "vs241510-5678900000-xxxxx",
"hypervisor-report-id": "phyp241510-5678900000-xxxxx"
}

Figure 710. Generate Virtual Server CPU Utilization Report: Request

Generate Virtual Server Resource Adjustments Report

Use the Generate Virtual Server Resource Adjustments Report operation to create a custom on-demand
resource adjustments report for a specific virtual server over a requested time period. The report is based
on historical performance management data that was retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-virtual-server-
resource-adjustments-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble containing the workload
resource group for which you want to receive a virtual server resource adjustments report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.

1294 HMC Web Services API

 Level 04a

Field name Type Rqd/Opt Description

workload-report-id String Required An identifier used by the performance management reporting
structure to keep track of reporting data for the specific workload
resource group named in the workload-name field.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report
for this same interval.
virtual-server- String Required An identifier used by the performance management reporting
report-id structure to keep track of reporting data for the specific virtual
server named in the virtual-server-name field. This value is the
same as one of the virtual-server-report-id values that are returned
in the Virtual Servers Report. Alternatively, you can supply the
object-id property value of an existing Virtual Server object.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific workload resource group named
in the workload-name field.
virtual-server- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific virtual server named in the
virtual-server-name field.
successful-resource- Array of Array of nested successful-resource-adjustment objects. If no successful
adjustments objects adjustments occurred during the requested time interval, an empty array is
returned.
failed-resource- Array of Array of nested failed-resource-adjustment objects. If no failed
adjustments objects adjustments occurred during the requested time interval, an empty array is
returned.

Each nested successful-resource-adjustment object contains the following fields:

Field name Type Description

hypervisor-type String The value of the type property of the virtualization host. See the
Enum virtualization host “Data model” on page 987 for more details about the
valid values of this property.
adjustment-time Integer Standard date/time value indicating the requested starting date and time of
the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.

Chapter 18. Workload resource group management 1295

 Level 04a

Field name Type Description

receiver-virtual- String The name of the virtual server that was given additional resources.
server-name
receiver-workload- String The displayable name of the workload resource group that was given
name additional resources.
receiver-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the receiver-workload-name field.
receiver-service- String The displayable name of the service class within the workload resource
class-name group that was given additional resources.
receiver-service- String An identifier used by the performance management reporting structure to
class-report-id keep track of reporting data for the specific service class named in the
receiver-service-class-name field.
receiver-processing- Float The total number of processing units the receiver had after the additional
units-after resources were given to it.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
receiver-processing- Float The total number of processing units the receiver had before the additional
units-before resources were given to it.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
adjustment-donors Array of Array of nested adjustment-donors objects.
objects

Each nested adjustment-donors object contains the following fields:

Field name Type Description

donor-virtual-server- String The name of a virtual server that gave up resources as part of this
name adjustment.
donor-processing- Float The total number of processing units this donor had after it gave up
units-after resources.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
donor-processing- Float The total number of processing units this donor had before it gave up
units-before resources.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
donor-workload-names Array of The displayable names of all workload resource groups that donated
strings resources when this donor virtual server gave up resources.

Each nested failed-resource-adjustment object contains the following fields:

1296 HMC Web Services API

 Level 04a

Field name Type Description

hypervisor-type String The value of the type property of the virtualization host. See the
Enum virtualization host “Data model” on page 987 for more details about the
valid values of this property.
adjustment-time Integer Standard date/time value indicating the requested starting date and time of
the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
receiver-virtual- String The name of the virtual server that needed but did not receive additional
server-name resources.
receiver-workload- String The displayable name of the workload resource group that needed but did
name not receive additional resources.
receiver-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the receiver-workload-name field.
receiver-service- String The displayable name of the service class within the workload resource
class-name group that needed but did not receive additional resources.
receiver-service- String An identifier used by the performance management reporting structure to
class-report-id keep track of reporting data for the specific service class named in the
receiver-service-class-name field.
adjustment-fail- String The reason why the adjustment failed. Values are:
reason Enum v "not-enough-capacity" — The sum of the capacity that could be given up
by all the available donors in the group was not enough to meet the
capacity increase request of the intended receiver.
v "no-potential-donors" — The group did not contain any potential donors
so no assessments for increased capacity could be sent.
v "entitled-capacity-not-achievable" — The extra capacity required to be
added to the entitled capacity would have pushed the total beyond the
maximum entitled capacity.
v "processor-not-fully-utilized" — The virtual server is not fully using the
processors it already has, so adding more will not have any effect.
v "requested-more-shares-than-max" — More shares than the maximum
allowed for this virtual server were requested.
v "not-enough-virtual-cpus" — Not enough virtual CPUs were available for
the projected required total consumed capacity to be achieved.
v "unknown" — Unknown uncategorized failure reason.

Description
The Generate Virtual Server Resource Adjustments Report operation generates a report that contains
the following information for a specific virtual server over the requested time interval:
v A list of resource adjustments that zManager successfully made to maintain specified performance
goals. For successful adjustments, the report includes:
– A list of workload resource groups and the virtual servers that received additional resources
(receivers)
– A list of workload resource groups and the virtual servers that donated the additional resources
(donors)
v A list of resource adjustments that zManager attempted but failed to make, along with a reason for the
failure.
“Response body contents” on page 1295 describes the full list of data that is returned in the report for
this workload resource group.

Additional types of resource adjustment reports are available. This particular generate-virtual-server-
resource-adjustments-report operation generates a resource adjustments report for a specific virtual server
within a specific workload over the requested time period. What this means is that it will contain entries

Chapter 18. Workload resource group management 1297

 Level 04a

for all adjustments that affected the particular virtual server submitted; meaning all of the entries
returned will involve that specific virtual server either having received additional resources, or having
been forced to give up (donate) some of its resources.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements.”

The request body is validated against the schema described in “Request body contents” on page 1294. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Virtual Server Resource Adjustments Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-virtual-server-resource-adjustments-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group",
"virtual-server-report-id": "vs241510-5678900000-xxxxx"
}

Figure 711. Generate Virtual Server Resource Adjustments Report: Request

1298 HMC Web Services API

 Level 04a

Generate Hypervisor Report

Use the Generate Hypervisor Report operation to create a custom on-demand report that shows
information about a specific hypervisor and all virtual servers that were running under that hypervisor
over a requested time period. The report is based on historical performance management data that was
retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-hypervisor-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a hypervisor report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
hypervisor-report- String Required An identifier used by the performance management reporting
id structure to keep track of reporting data for the specific hypervisor
under which this virtual server was running. (Hypervisor names
returned in the hypervisor-name field are not unique).

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
hypervisor-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific hypervisor under which this
virtual server was running. (Hypervisor names returned in the
hypervisor-name field are not unique).
hypervisor-name String The displayable name of the hypervisor under which this virtual server was
running.

Chapter 18. Workload resource group management 1299

 Level 04a

Field name Type Description

hypervisor-type String The value of the type property of the virtualization host. See the
Enum virtualization host “Data model” on page 987 for more details about the
valid values of this property.
report-hypervisor- Object An object that contains report details for the hypervisor itself. The format of
details the returned object is described in Table 438.
report-hypervisor- Array of An array of nested objects, each representing a virtual server that was under
virtual-servers objects the control of this hypervisor during this reporting interval. The format of
the returned object depends on the value returned in the hypervisor-type
field:
v For "power-vm", see Table 439 on page 1301
v For "x-hyp", see Table 440 on page 1302
v For "zvm", see Table 441 on page 1303
v For "prsm", see Table 442 on page 1305
resource-adjustment- Object If a hypervisor-level resource adjustment report is available for this same
report reporting interval, this object is returned. The format of the
resource-adjustment-report object is the same as that described in “Response
body contents” on page 1308 for the Generate Hypervisor Resource
Adjustments Report operation.

The report-hypervisor-details object for a hypervisor contains the fields in Table 438.
Table 438. Format of a report-hypervisor-details object
Field name Type Description
allocated-processing- Float The total number of processing units that were allocated. This field is
units included in the object only for the PowerVM hypervisor type.
processor-count Integer The total number of physical processors.
cpu-consumption- Float The total consumption (utilization) percentage (%) of hypervisor CPUs. This
percent percentage is in fractional form (between 0 and 1 inclusive). This field is
returned for the following hypervisors only: z/VM, z Hyp, and PowerVM.
shared-cp- Float The total consumption (utilization) percentage (%) of shared processors. This
consumption-percent percentage is in fractional form (between 0 and 1 inclusive). This field is
returned for the following hypervisor only: PR/SM.
memory-used Integer The total amount of the hypervisor memory that was in use (in MB).
total-memory Integer The total amount of memory (in MB) that was that was available to the
hypervisor.
cp-cpu-consumption- Float The total consumption (utilization) percentage (%) of the hypervisor's
percent general purpose CPUs. It is in fractional form (between 0 and 1 inclusive).
This field is returned for the following hypervisor only: z/VM.
ifl-cpu-consumption- Float The total consumption (utilization) percentage (%) of the hypervisor's IFL
percent CPUs. It is in fractional form (between 0 and 1 inclusive). This field is
returned for the following hypervisor only: z/VM.
other-cpu- Float The total consumption (utilization) percentage (%) of the hypervisor's CPU
consumption-percent types other than CPs and IFLs. It is in fractional form (between 0 and 1
inclusive). This field is returned for the following hypervisor only: z/VM.

Each nested report-hypervisor-virtual-servers object for a PowerVM hypervisor contains the fields in
Table 439 on page 1301.

1300 HMC Web Services API

 Level 04a

Table 439. Format of a PowerVM report-hypervisor-virtual-servers object

Field name Type Description
virtual-server-name String The displayable name of the virtual server.
workload-processor- String The processor management status, which is one of the following values:
mgmt-status Enum v "active"
v "not-active"
workload-processor- String A further explanation of the reason for processor management status
mgmt-status-reason Enum returned in the workload-processor-mgmt-status field. Values are:
v "none"– the value of workload-processor-mgmt-status is "active"
v "mgmt-disabled-global"– the option to enable processor performance
management at the hypervisor type level was not set for this hypervisor
type
v "mgmt-disabled-vs"– the option to enable processor performance
management at the virtual server level was not set for this virtual server
v "dedicated-proc-mode"– the virtual server is running in dedicated
processor mode, and only shared mode is supported for processor
management
v "internal-error"– An internal error has occurred.
v "network-connection-failure"– the virtual server has no connectivity to its
hypervisor.
v "virtual-server-not-active"– the virtual server itself was not up and active
during this reporting interval
was-active Boolean Indicates whether this virtual server was active during this reporting
interval. The value is "true" if the virtual server was active or "false" if it
was not active.

If the value for this field is false, none of the remaining fields in this object
can have data so they are not returned.
virtual-processor- Integer This value is the number of virtual processors that were associated with this
count virtual server during the reporting interval. Optional: This field is returned
only if the virtual server was active during this interval.
min-virtual- Integer The minimum number of virtual processors allowed for this virtual server.
processors Optional: This field is returned only if the virtual server was active during
this interval.
max-virtual- Integer The maximum number of virtual processors allowed for this virtual server.
processors Optional: This field is returned only if the virtual server was active during
this interval.
consumed-processors Float The consumed processors metric for this virtual server. Optional: This field
is returned only if the virtual server was active during this interval.
was-dedicated Boolean Indicates whether this virtual server was running in dedicated mode (as
opposed to shared mode) during this reporting interval. The value is "true"
if the virtual server was in dedicated mode or "false" if it was in shared
mode. Optional: This field is returned only if the virtual server was active
during this interval.
was-capped Boolean Indicates whether this virtual server was capped during this reporting
interval. The value is "true" if the virtual server was capped or "false" if it
was not capped. Optional: This field is returned only if the virtual server
was active during this interval.
hypervisor-cpu-delay- Float The hypervisor processing unit delay in fractional form (between 0 and 1
percent inclusive). This field is returned for the following hypervisors only: z/VM
and PowerVM. In the case of z/VM, a value is available for this field only if
sampling is turned on for the guest. This field is returned only if the virtual
server was active and running in shared mode (as opposed to dedicated
mode) during this interval.

Chapter 18. Workload resource group management 1301

 Level 04a

Table 439. Format of a PowerVM report-hypervisor-virtual-servers object (continued)

Field name Type Description
processing-units Float The number of processing units that were assigned to this virtual server
during the reporting interval. Optional: This field is returned only if the
virtual server was active during this interval.
initial-processing- Float The number of processing units that were initially assigned to this virtual
units server. Optional: This field is returned only if the virtual server was active
during this interval.
min-processing-units Float The minimum number of processing units that this virtual server could use.
Optional: This field is returned only if the virtual server was active during
this interval.
max-processing-units Float The maximum number of processing units that this virtual server could use.
Optional: This field is returned only if the virtual server was active during
this interval.
min-memory Integer The minimum amount of memory (in MB) that this virtual server could use.
Optional: This field is returned only if the virtual server was active during
this interval.
max-memory Integer The maximum amount of memory (in MB) that this virtual server could use.
Optional: This field is returned only if the virtual server was active during
this interval.

Each nested report-hypervisor-virtual-servers object for an x Hyp hypervisor contains the fields in
Table 440.
Table 440. Format of an x Hyp report-hypervisor-virtual-servers object
Field name Type Description
virtual-server-name String The displayable name of the virtual server.
was-active Boolean Indicates whether this virtual server was active during this reporting
interval. The value is "true" if the virtual server was active or "false" if it
was not active.

If the value for this field is false, none of the remaining fields in this object
can have data so they are not returned.
virtual-processor- Integer This value is the number of virtual processors that were associated with this
count virtual server during the reporting interval. Optional: This field is returned
only if the virtual server was active during this interval.
consumed-processors Float The consumed processors metric for this virtual server. Optional: This field
is returned only if the virtual server was active during this interval.
hypervisor-cpu-delay- Float The hypervisor processing unit delay in fractional form (between 0 and 1
percent inclusive). This field is returned for the following hypervisors only: z/VM
and PowerVM. In the case of z/VM, a value is available for this field only if
sampling is turned on for the guest. Optional: This field is returned only if
the virtual server was active and a guest platform management provider
was running on the virtual server during this interval.
memory-in-use Integer The amount of memory (in MB) that was actually in use by this virtual
server. Optional: This field is returned only if the virtual server was active
during this interval.
allocated-memory Integer For the x Hyp, PowerVM, and PR/SM hypervisor types, this field contains
the allocated memory (in MB) configured for the virtual server. Optional:
This field is returned only if the virtual server was active during this
interval.

1302 HMC Web Services API

 Level 04a

Table 440. Format of an x Hyp report-hypervisor-virtual-servers object (continued)

Field name Type Description
workload-processor- String The status of automatic workload processor performance management
mgmt-status Enum during this reporting interval.

Values:
v "active"
v "not-active"
workload-processor- String A further explanation of the reason for workload processor performance
mgmt-status-reason Enum management status returned in workload-mgmt-status.

Values:
v "none" - No further reason available (for example, would be "none" when
workload-processor-mgmt-status is "active".
v "mgmt-disabled-global" - The option to enable processor performance
management at the hypervisor type level was not set for this hypervisor
type.
v "mgmt-disabled-vs" - The option to enable processor performance
management at the virtual server level was not set for this virtual server.
v "virtual-server-not-active" - The virtual server itself was not up and active
during this reporting interval.
v "hypervisor-not-correct-level" - The hypervisor controlling this virtual
server is not the correct level to support automatic performance
management.
v "internal-error" - An internal error has been encountered (contact IBM
support).
initial-shares Integer The number of processor shares that were initially associated to this virtual
server during this reporting interval. Optional: This data may not always be
available (for example, if was-active is false). In any case, if it is not
available this field will not be returned.
shares Integer The number of processor shares that were currently associated to this virtual
server during this reporting interval. Optional: This data may not always be
available (for example, if was-active is false). In any case, if it is not
available this field will not be returned.
min-shares Integer The minimum number of processor shares that could be dynamically
assigned to the virtual server. Optional: This data may not always be
available (for example, if was-active is false). In any case, if it is not
available this field will not be returned.
max-shares Integer The maximum number of processor shares that could be dynamically
assigned to the virtual server. Optional: This data may not always be
available (for example, if was-active is false). In any case, if it is not
available this field will not be returned.

Each nested report-hypervisor-virtual-servers object for a z/VM hypervisor contains the fields in
Table 441.
Table 441. Format of a z/VM report-hypervisor-virtual-servers object
Field name Type Description
virtual-server-name String The displayable name of the virtual server.
workload-processor- String The processor management status, which is one of the following values:
mgmt-status Enum v "active"
v "not-active"

Chapter 18. Workload resource group management 1303

 Level 04a

Table 441. Format of a z/VM report-hypervisor-virtual-servers object (continued)

Field name Type Description
workload-processor- String A further explanation of the reason for processor management status
mgmt-status-reason Enum returned in the workload-processor-mgmt-status field. Values are:
v "none"– the value of workload-processor-mgmt-status is "active"
v "mgmt-disabled-global"– the option to enable processor performance
management at the hypervisor type level was not set for this hypervisor
type
v "mgmt-disabled-vs"– the option to enable processor performance
management at the virtual server level was not set for this virtual server
v "absolute-share-mode"– the virtual server is running in absolute share
mode, and only relative share mode is supported for processor
management
v "sampling-disabled"– z/VM sampling was not enabled. Sampling must be
enabled for processor management under z/VM.
v "internal-error"– An internal error has occurred.
v "network-connection-failure"– the virtual server has no connectivity to its
hypervisor.
v "virtual-server-not-active"– the virtual server itself was not up and active
during this reporting interval
was-active Boolean Indicates whether this virtual server was active during this reporting
interval. The value is "true" if the virtual server was active or "false" if it
was not active.

If the value for this field is false, none of the remaining fields in this object
can have data so they are not returned.
virtual-processor- Integer This value is the number of virtual processors that were associated with this
count virtual server during the reporting interval. Optional: This field is returned
only if the virtual server was active during this interval.
consumed-processors Float The consumed processors metric for this virtual server. Optional: This field
is returned only if the virtual server was active during this interval.
hypervisor-cpu-delay- Float The hypervisor processing unit delay in fractional form (between 0 and 1
percent inclusive). This field is returned for the following hypervisors only: z/VM
and PowerVM. In the case of z/VM, a value is available for this field only if
sampling is turned on for the guest. This field is returned only if the virtual
server was active and sampling is enabled during this interval.
share-mode String The processor share mode configured for this virtual server during this
Enum reporting interval. Valid values are "absolute" and "relative". Optional: This
field is returned only if the virtual server was active during this interval.
share-limit String The processor share limit configured for this virtual server during this
Enum reporting interval. Valid values are "soft", "hard" and "none". Optional: This
field is returned only if the virtual server was active during this interval.
shares Integer The number of processor shares that were associated with this virtual server
during this reporting interval. Optional: This field is returned only if the
virtual server was active and running in relative share mode (as opposed to
absolute share mode) during this interval.
min-shares Integer The minimum number of processor shares that could be dynamically
assigned to the virtual server during this reporting interval. Optional: This
field is returned only if the virtual server was active and running in relative
share mode (as opposed to absolute share mode) during this interval.
max-shares Integer The maximum number of processor shares that could be dynamically
assigned to the virtual server during this reporting interval. Optional: This
field is returned only if the virtual server was active and running in relative
share mode (as opposed to absolute share mode) during this interval.

1304 HMC Web Services API

 Level 04a

Table 441. Format of a z/VM report-hypervisor-virtual-servers object (continued)

Field name Type Description
initial-shares Integer The number of processor shares that were initially associated to this virtual
server during this reporting interval. Optional: This data may not always be
available (for example, if was-active is false). In any case, if it is not available
this field will not be returned.
memory-used Integer The total amount of the hypervisor memory that was in use (in MB).
Optional: This field is returned only if the virtual server was active during
this interval.

Each nested report-hypervisor-virtual-servers object for a PR/SM hypervisor contains the fields in
Table 442.
Table 442. Format of a PR/SM report-hypervisor-virtual-servers object
Field name Type Description
virtual-server-name String The displayable name of the virtual server.
was-active Boolean Indicates whether this virtual server was active during this reporting
interval. The value is "true" if the virtual server was active or "false" if it
was not active.

If the value for this field is false, none of the remaining fields in this object
can have data so they are not returned.
logical-processor- Integer The number of logical processors that were associated with this virtual
count server during this reporting interval. Optional: This field is returned only if
the virtual server was active during this interval.
consumed-processors Float The consumed processors metric for this virtual server. Optional: This field
is returned only if the virtual server was active during this interval.
allocated-memory Integer For the x Hyp, PowerVM, and PR/SM hypervisor types, this field contains
the allocated memory (in MB) configured for the virtual server. Optional:
This field is returned only if the virtual server was active during this
interval.
was-dedicated Boolean Indicates whether this virtual server was running in dedicated mode (as
opposed to shared mode) during this reporting interval. The value is "true"
if the virtual server was in dedicated mode or "false" if it was in shared
mode. Optional: This field is returned only if the virtual server was active
during this interval.
cpu-weight Integer The CPU weight that was associated to this virtual server during this
reporting interval. This field is returned only if the virtual server was active
and running in shared mode (as opposed to dedicated mode) during this
interval.
min-cpu-weight Integer The minimum CPU weight that this virtual server could use. This field is
returned only if the virtual server was active and running in shared mode
(as opposed to dedicated mode) during this interval.
max-cpu-weight Integer The maximum CPU weight that this virtual server could use. This field is
returned only if the virtual server was active and running in shared mode
(as opposed to dedicated mode) during this interval.

Description
The Generate Hypervisor Report operation generates a report that contains the following information for
a specific hypervisor over the requested time interval:
v Information about the hypervisor itself, including the total number of physical processors and total
consumption percentage of those processors

Chapter 18. Workload resource group management 1305

 Level 04a

v A list of all virtual servers that were running under this specific hypervisor for which historical
reporting information is available
v For each virtual server:
– An indication of whether the virtual server was active over the reporting interval
– Additional information such as processor counts and memory statistics.
“Response body contents” on page 1299 describes the full list of data that is returned in this report for
each virtual server. The information available for virtual servers varies depending on the hypervisor type.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements.”

The request body is validated against the schema described in “Request body contents” on page 1299. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Hypervisor Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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

1306 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-hypervisor-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"hypervisor-report-id": "phyp241510-5678900000-xxxxx"
}

Figure 712. Generate Hypervisor Report: Request

Generate Hypervisor Resource Adjustments Report

Use the Generate Hypervisor Resource Adjustments Report operation to create a custom on-demand
resource adjustments report for a specific hypervisor over a requested time period. The report is based on
historical performance management data that was retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-hypervisor-
resource-adjustments-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble containing the workload
resource group for which you want to receive a hypervisor resource adjustments report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
hypervisor-report- String Required An identifier used by the performance management reporting
id structure to keep track of reporting data for the specific hypervisor
under which this virtual server was running. (Hypervisor names
returned in the hypervisor-name field are not unique). This value is
the same as the hypervisor-report-id value that is returned for this
virtual server in the Virtual Servers Report. Alternatively, you can
supply the object-id property value of an existing Virtualization
Host object.

Chapter 18. Workload resource group management 1307

 Level 04a

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
hypervisor-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific hypervisor under which this
virtual server was running. (Hypervisor names returned in the
hypervisor-name field are not unique).
successful-resource- Array of Array of nested successful-resource-adjustment objects. If no successful
adjustments objects adjustments occurred during the requested time interval, an empty array is
returned.
failed-resource- Array of Array of nested failed-resource-adjustment objects. If no failed
adjustments objects adjustments occurred during the requested time interval, an empty array is
returned.

Each nested successful-resource-adjustment object contains the following fields:

Field name Type Description

hypervisor-type String The value of the type property of the virtualization host. See the
Enum virtualization host “Data model” on page 987 for more details about the
valid values of this property.
adjustment-time Integer Standard date/time value indicating the requested starting date and time of
the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
receiver-virtual- String The name of the virtual server that was given additional resources.
server-name
receiver-workload- String The displayable name of the workload resource group that was given
name additional resources.
receiver-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the receiver-workload-name field.
receiver-service- String The displayable name of the service class within the workload resource
class-name group that was given additional resources.
receiver-service- String An identifier used by the performance management reporting structure to
class-report-id keep track of reporting data for the specific service class named in the
receiver-service-class-name field.

1308 HMC Web Services API

 Level 04a

Field name Type Description

receiver-processing- Float The total number of processing units the receiver had after the additional
units-after resources were given to it.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
receiver-processing- Float The total number of processing units the receiver had before the additional
units-before resources were given to it.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
adjustment-donors Array of Array of nested adjustment-donors objects.
objects

Each nested adjustment-donors object contains the following fields:

Field name Type Description

donor-virtual-server- String The name of a virtual server that gave up resources as part of this
name adjustment.
donor-processing- Float The total number of processing units this donor had after it gave up
units-after resources.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
donor-processing- Float The total number of processing units this donor had before it gave up
units-before resources.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
donor-workload-names Array of The displayable names of all workload resource groups that donated
strings resources when this donor virtual server gave up resources.

Each nested failed-resource-adjustment object contains the following fields:

Field name Type Description

hypervisor-type String The value of the type property of the virtualization host. See the
Enum virtualization host “Data model” on page 987 for more details about the
valid values of this property.
adjustment-time Integer Standard date/time value indicating the requested starting date and time of
the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
receiver-virtual- String The name of the virtual server that needed but did not receive additional
server-name resources.
receiver-workload- String The displayable name of the workload resource group that needed but did
name not receive additional resources.
receiver-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the receiver-workload-name field.

Chapter 18. Workload resource group management 1309

 Level 04a

Field name Type Description

receiver-service- String The displayable name of the service class within the workload resource
class-name group that needed but did not receive additional resources.
receiver-service- String An identifier used by the performance management reporting structure to
class-report-id keep track of reporting data for the specific service class named in the
receiver-service-class-name field.
adjustment-fail- String The reason why the adjustment failed. Values are:
reason Enum v "not-enough-capacity" — The sum of the capacity that could be given up
by all the available donors in the group was not enough to meet the
capacity increase request of the intended receiver.
v "no-potential-donors" — The group did not contain any potential donors
so no assessments for increased capacity could be sent.
v "entitled-capacity-not-achievable" — The extra capacity required to be
added to the entitled capacity would have pushed the total beyond the
maximum entitled capacity.
v "processor-not-fully-utilized" — The virtual server is not fully using the
processors it already has, so adding more will not have any effect.
v "requested-more-shares-than-max" — More shares than the maximum
allowed for this virtual server were requested.
v "not-enough-virtual-cpus" — Not enough virtual CPUs were available for
the projected required total consumed capacity to be achieved.
v "unknown" — Unknown uncategorized failure reason.

Description
The Generate Hypervisor Resource Adjustments Report operation generates a report that contains the
following information for a specific hypervisor over the requested time interval:
v A list of resource adjustments that zManager successfully made to maintain specified performance
goals. For successful adjustments, the report includes:
– A list of workload resource groups and the virtual servers that received additional resources
(receivers)
– A list of workload resource groups and the virtual servers that donated the additional resources
(donors)
v A list of resource adjustments that zManager attempted but failed to make, along with a reason for the
failure.
“Response body contents” on page 1308 describes the full list of data that is returned in the report for
this workload resource group.

Additional types of resource adjustment reports are available. This particular generate-hypervisor-
resource-adjustments-report operation generates a resource adjustments report for a specific hypervisor
over the requested time period. What this means is that it will contain entries for all adjustments that
affected virtual servers within the particular hypervisor submitted; meaning all of the entries returned
will involve a virtual server under the control of that specific hypervisor either having received
additional resources, or having been forced to give up (donate) some of its resources.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements” on page 1311.

The request body is validated against the schema described in “Request body contents” on page 1307. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

1310 HMC Web Services API

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Hypervisor Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-hypervisor-resource-adjustments-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"hypervisor-report-id": "phyp241510-5678900000-xxxxx"
}

Figure 713. Generate Hypervisor Resource Adjustments Report: Request

Generate Service Classes Report

Use the Generate Service Classes Report operation to create a custom on-demand report that shows all
service classes within a particular workload resource group over a requested time period. The report is
based on historical performance management data that was retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-service-classes-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a service classes report.

Chapter 18. Workload resource group management 1311

 Level 04a

Request body contents

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

Field name Type Req/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
workload-report-id String Required The identifier used by the performance management reporting to
keep track of reporting data for the specific workload resource
group for which the report is being requested.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report
for this same interval.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific workload resource group named
in the workload-name field.
performance-policy- String The displayable name of the performance policy that contains this service
name class.
performance-policy- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific performance policy named in the
performance-policy-name field.
report-service- Array of Array of nested service-class-report-entry objects.
classes objects

Each nested service-class-report-entry object contains the following fields:

1312 HMC Web Services API

 Level 04a

Field name Type Description

service-class-name String The displayable name of the service class. Optional: This field is returned
only if the virtual server was active and if the virtual server was associated
with a specific service class within the requested workload resource group
during this interval.
service-class-report- String An identifier used by the performance management reporting structure to
id keep track of reporting data for the specific service class named in the
service-class-name field. Optional: This field is returned only if the
service-class-name field is returned.
has-hop-data Boolean Indicates whether this service class has hop level data available for this
reporting interval. The value is "true" if hop data is available or "false" if it
is not available.
goal-type String The type of performance goal that was defined for this service class. Values
Enum are "velocity" or "discretionary".
goal-performance- String The performance goal of the service class as defined in performance policy.
level Enum Possible values are: "fastest", "fast", "moderate", "slow", and "slowest". This
field is returned only if a velocity performance goal was defined for this
service class.
business-importance String The business importance level that was defined for this service class. Possible
Enum values are: "highest", "high", "medium", "low", and "lowest". This field is
returned only if a velocity performance goal was defined for this service
class.
pi-value Float The average performance index (PI) value calculated over this reporting
interval for the service class returned in the service-class-name field. This
field is not returned if the virtual server was not active or if a PI value could
not be calculated.
actual-performance- String The average level of performance that was actually measured over this
level Enum reporting interval. Possible values are: "fastest", "fast", "moderate", "slow",
and "slowest". This field is returned only if a velocity performance goal was
defined for this service class and if the performance index value could be
measured.

Description
The Generate Service Classes Report operation generates a report that contains the following
information for a specific workload resource group over the requested time interval:
v A list of all service classes within that specific workload resource group for which historical reporting
information is available
v For each service class:
– The name and unique reporting ID of the performance policy that contains the service class
– An indication of whether the service class has available hop data for this reporting interval
– Details about the service class definition, such as the type of performance goal
– The actual performance level achieved during this reporting interval.
“Response body contents” on page 1312 describes the full list of data that is returned in this report for
each service class. If hop data is available for this service class (check the has-hop-data field), you can use
the service-class-report-id property as input for additional report operations related to service classes:
v “Generate Service Class Hops Report” on page 1319
v “Generate Service Class Virtual Server Topology Report” on page 1324

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements” on page 1314.

Chapter 18. Workload resource group management 1313

 Level 04a

The request body is validated against the schema described in “Request body contents” on page 1312. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Service Classes Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-service-classes-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group"
}

Figure 714. Generate Service Classes Report: Request

Generate Service Class Resource Adjustments Report

Use the Generate Service Class Resource Adjustments Report operation to create a custom on-demand
resource adjustments report for a specific service class within a workload resource group over a requested
time period. The report is based on historical performance management data that was retained over that
time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/
generate-service-class-resource-adjustments-report

1314 HMC Web Services API

 Level 04a

In this request, the URI variable {ensemble-id} is the object ID of the ensemble containing the workload
resource group for which you want to receive a service class resource adjustments report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
workload-report-id String Required An identifier used by the performance management reporting
structure to keep track of reporting data for the specific workload
resource group named in the workload-name field.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report
for this same interval.
service-class- String Required An identifier used by the performance management reporting
report-id structure to keep track of reporting data for the specific service class
named in the service-class-name field.
Note: This value is the same as the service-class-report-id value
that is returned in one of the service class entries in the Service
Classes Report for this same interval.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific workload resource group named
in the workload-name field.
service-class-name String The displayable name of the service class.
service-class-report- String An identifier used by the performance management reporting structure to
id keep track of reporting data for the specific service class named in the
service-class-name field.

Chapter 18. Workload resource group management 1315

 Level 04a

Field name Type Description

successful-resource- Array of Array of nested successful-resource-adjustment objects. If no successful
adjustments objects adjustments occurred during the requested time interval, an empty array is
returned.
failed-resource- Array of Array of nested failed-resource-adjustment objects. If no failed
adjustments objects adjustments occurred during the requested time interval, an empty array is
returned.

Each nested successful-resource-adjustment object contains the following fields:

Field name Type Description

hypervisor-type String The value of the type property of the virtualization host. See the
Enum virtualization host “Data model” on page 987 for more details about the
valid values of this property.
adjustment-time Integer Standard date/time value indicating the requested starting date and time of
the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
receiver-virtual- String The name of the virtual server that was given additional resources.
server-name
receiver-workload- String The displayable name of the workload resource group that was given
name additional resources.
receiver-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the receiver-workload-name field.
receiver-service- String The displayable name of the service class within the workload resource
class-name group that was given additional resources.
receiver-service- String An identifier used by the performance management reporting structure to
class-report-id keep track of reporting data for the specific service class named in the
receiver-service-class-name field.
receiver-processing- Float The total number of processing units the receiver had after the additional
units-after resources were given to it.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
receiver-processing- Float The total number of processing units the receiver had before the additional
units-before resources were given to it.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
adjustment-donors Array of Array of nested adjustment-donors objects.
objects

Each nested adjustment-donors object contains the following fields:

Field name Type Description

donor-virtual-server- String The name of a virtual server that gave up resources as part of this
name adjustment.

1316 HMC Web Services API

 Level 04a

Field name Type Description

donor-processing- Float The total number of processing units this donor had after it gave up
units-after resources.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
donor-processing- Float The total number of processing units this donor had before it gave up
units-before resources.

Processing units are returned in the units that are normal for the specific
hypervisor type of the virtual server. The units are entitled capacity for
PowerVM, and CPU shares for all other hypervisor types.
donor-workload-names Array of The displayable names of all workload resource groups that donated
strings resources when this donor virtual server gave up resources.

Each nested failed-resource-adjustment object contains the following fields:

Field name Type Description

hypervisor-type String The value of the type property of the virtualization host. See the
Enum virtualization host “Data model” on page 987 for more details about the
valid values of this property.
adjustment-time Integer Standard date/time value indicating the requested starting date and time of
the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
receiver-virtual- String The name of the virtual server that needed but did not receive additional
server-name resources.
receiver-workload- String The displayable name of the workload resource group that needed but did
name not receive additional resources.
receiver-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the receiver-workload-name field.
receiver-service- String The displayable name of the service class within the workload resource
class-name group that needed but did not receive additional resources.
receiver-service- String An identifier used by the performance management reporting structure to
class-report-id keep track of reporting data for the specific service class named in the
receiver-service-class-name field.
adjustment-fail- String The reason why the adjustment failed. Values are:
reason Enum v "not-enough-capacity" — The sum of the capacity that could be given up
by all the available donors in the group was not enough to meet the
capacity increase request of the intended receiver.
v "no-potential-donors" — The group did not contain any potential donors
so no assessments for increased capacity could be sent.
v "entitled-capacity-not-achievable" — The extra capacity required to be
added to the entitled capacity would have pushed the total beyond the
maximum entitled capacity.
v "processor-not-fully-utilized" — The virtual server is not fully using the
processors it already has, so adding more will not have any effect.
v "requested-more-shares-than-max" — More shares than the maximum
allowed for this virtual server were requested.
v "not-enough-virtual-cpus" — Not enough virtual CPUs were available for
the projected required total consumed capacity to be achieved.
v "unknown" — Unknown uncategorized failure reason.

Chapter 18. Workload resource group management 1317

 Level 04a

Description
The Generate Service Class Resource Adjustments Report operation generates a report that contains the
following information for a specific service class within a workload resource group over the requested
time interval:
v A list of resource adjustments that zManager successfully made to maintain specified performance
goals. For successful adjustments, the report includes:
– A list of workload resource groups and the virtual servers that received additional resources
(receivers)
– A list of workload resource groups and the virtual servers that donated the additional resources
(donors)
v A list of resource adjustments that zManager attempted but failed to make, along with a reason for the
failure.
“Response body contents” on page 1315 describes the full list of data that is returned in the report for
this workload resource group.

There are multiple types of resource adjustments reports that can be requested, and each has its own API
listed in this Performance Management Reports section. This particular generate-service-class-resource-
adjustments-report operation generates a resource adjustments report for a specific service class within a
specific workload over the requested time period. What this means is that it will contain entries for all
adjustments that affected the particular service class submitted; meaning all of the entries returned will
involve that specific service class either having received additional resources, or having been forced to
give up (donate) some of its resources.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements.”

The request body is validated against the schema described in “Request body contents” on page 1315. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Service Class Resource Adjustments Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

1318 HMC Web Services API

 Level 04a

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-service-class-resource-adjustments-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group",
"service-class-report-id": "Batch Service"
}

Figure 715. Generate Service Class Resource Adjustments Report: Request

Generate Service Class Hops Report

Use the Generate Service Class Hops Report operation to create a custom on-demand hops report for a
service class within a particular workload resource group over a requested time period. The report is
based on historical performance management data that was retained over that time period.

HTTP method and URI

Typically, a transactional service class has multiple hops, each hop corresponding to a tier in the
transactional flow. Each hop can have one or more application environments associated with it; an
application environment includes software and the server or network infrastructure that supports it. An
application environment, in turn, might have multiple application environment servers.
POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-service-class-hops-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a hops report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
workload-report-id String Required An identifier used by the performance management reporting
structure to keep track of reporting data for the specific workload
resource group named in the workload-name field.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report
for this same interval.

Chapter 18. Workload resource group management 1319

 Level 04a

Field name Type Rqd/Opt Description

service-class- String Required An identifier used by the performance management reporting
report-id structure to keep track of reporting data for the specific service class
named in the service-class-name field.
Note: This value is the same as the service-class-report-id value
that is returned in one of the service class entries in the Service
Classes Report for this same interval.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific workload resource group named
in the workload-name field.
service-class-name String The displayable name of the service class.
service-class-report- String An identifier used by the performance management reporting structure to
id keep track of reporting data for the specific service class named in the
service-class-name field.
performance-policy- String The displayable name of the performance policy that contains this service
name class.
performance-policy- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific performance policy named in the
performance-policy-name field.
goal-type String The type of performance goal that was defined for this service class. Values
Enum are "velocity" or "discretionary".
goal-performance- String The performance goal of the service class as defined in performance policy.
level Enum Possible values are: "fastest", "fast", "moderate", "slow", and "slowest". This
field is returned only if a velocity performance goal was defined for this
service class.
business-importance String The business importance level that was defined for this service class.
Enum Possible values are: "highest", "high", "medium", "low", and "lowest". This
field is returned only if a velocity performance goal was defined for this
service class.
pi-value Float The average performance index (PI) value calculated over this reporting
interval for the service class returned in the service-class-name field. This
field is not returned if the virtual server was not active or if a PI value could
not be calculated.

1320 HMC Web Services API

 Level 04a

Field name Type Description

actual-performance- String The average level of performance that was actually measured over this
level Enum reporting interval. Possible values are: "fastest", "fast", "moderate", "slow",
and "slowest". This field is returned only if a velocity performance goal was
defined for this service class and if the performance index value could be
measured.
equivalent-workload- Array of Because a specific virtual server can belong to more than one workload, the
service-classes objects hops report might contain reflect combined values for multiple workload
resource groups rather than those for the requested workload resource group
and service class. In this case, this field contains an array of nested
equivalent-workload-service-class objects, each of which identifies another
workload resource group or service class, if any, that have virtual servers
also contained within the reported hops. The format of the returned object is
described in Table 443. Otherwise, this field contains an empty array.
hops Array of An array of nested hop-entry objects. The format of the returned object is
objects described in Table 444.

Each nested equivalent-workload-service-class object contains the following fields:

Table 443. Format of an equivalent-workload-service-class object
Field name Type Description
equiv-workload-name String The displayable name of a workload resource group that is part of an
equivalent service class that was included in this report.
equiv-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the equiv-workload-name field.
equiv-service-class- String The displayable name of the equivalent service class (within the workload
name resource group defined by the equiv-workload-name) that was included in
this report.
equiv-service-class- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific service class named in the
equiv-service-class-name field.

Each nested hop-entry object contains the following fields:

Table 444. Format of a hop-entry object
Field name Type Description
hop-number Integer The number of this hop. The hop numbers reflect the relative order of the
flow of a work request (transaction) from one application environment to the
next. The first hop is 0, the next is hop 1, the next is hop 2, and so on.
hop-name String A text name generated for this hop number.
hop-statistics Object A hop-report-statistics object that reflects statistics for this hop as a whole (all
application environment groups and their virtual servers that are contained
in this hop). The format of the returned object is described in Table 445 on
page 1322.
hop-application- Array of An array of nested hop-application-env objects. The format of the returned
environments objects object is described in Table 446 on page 1322.

Each nested hops-report-statistics object contains the following fields:

Chapter 18. Workload resource group management 1321

 Level 04a

Table 445. Format of a hops-report-statistics object

Field name Type Description
successful- Integer The total number of transactions that completed successfully.
transactions
failed-transactions Integer The total number of transactions that failed.
stopped-transactions Integer Total number of transactions that stopped before completing. These
transactions did not fail or complete successfully; a transaction can enter the
stopped state if it encounters an error with the application or server that is
processing the transaction. For example, if an application detects that its
caller or client terminates the request before the transaction instance
completes, the application can stop processing for the transaction instance
and report it as stopped, rather than failed or successful.
inflight-transactions Integer The total number of transactions that had started, but not yet completed by
the end of the requested reporting interval.

Optional: This data may not always be available. For example, when Linux is
involved, it is not usually possible to obtain this statistic. If it is not available,
this field will not be returned.
queue-time Integer The average amount of time (in microseconds) from the time a transaction is
received until processing of the transaction begins.

Optional: This data may not always be available. For example, when Linux is
involved, it is not usually possible to obtain this statistic. If it is not available,
this field will not be returned.
execution-time Integer The average amount of time (in microseconds) that transactions took to
execute.

Optional: This data may not always be available. For example, when Linux is
involved, it is not usually possible to obtain this statistic. If it is not available,
this field will not be returned.
successful-avg- Integer Average response time (in microseconds) of all successful transactions.
response-time
inflight-avg- Integer Average amount of time (in microseconds) spent toward response time for
response-time inflight transactions.

Optional: This data may not always be available. For example, when Linux is
involved, it is not usually possible to obtain this statistic. If it is not available,
this field will not be returned.

Each nested hop-application-env object contains the following fields:

Table 446. Format of a hop-application-env object
Field name Type Description
appl-env-name String The name of the application environment. An application environment is the
environment that includes the software and the server or network
infrastructure that supports it. As defined by The Open Group application
response measurement (ARM) standard, the name is no more than 128
characters in length.
group-name String The name of the application environment group with which this application
environment is associated. This value cannot be more than 128 characters
long but is zero length when the application environment does not belong to
a group.

1322 HMC Web Services API

 Level 04a

Table 446. Format of a hop-application-env object (continued)

Field name Type Description
appl-env-hop- Object A hop-statistics object that reflects statistics for this application environment
statistics as a whole (all virtual servers that are contained in this application
environment). The format of the returned object is described in Table 445 on
page 1322.
hop-application-env- Array of An array of nested hop-application-env-virtual-server objects. The format of
virtual-servers objects the returned object is described in Table 447.

Each nested hop-application-env-virtual-server object contains the following fields:

Table 447. Format of a hop-application-env-virtual-server object
Field name Type Description
virtual-server-name String The displayable name of the virtual server. This field identifies the virtual
server within the application environment.
virtual-server-hop- Object A hop-report-statistics object that reflects statistics for this specific virtual
statistics server within the application environment. The format of the returned object
is described in Table 445 on page 1322.

Description
The Generate Service Class Hops Report operation generates a report that contains the following
information for a specific workload resource group and service class over the requested time interval:
v A list of application-level hops associated with this specific workload resource group and service class
for which historical reporting information is available. A hop corresponds to a tier in the transactional
flow, and each hop can have one or more application environments associated with it.
A service class can have multiple hops associated with it, and each hop can have one or more
associated application environments. These application environments might have multiple virtual
servers.
v For each hop associated with the service class:
– A common set of statistics
– Statistics for the application environments and virtual servers within each hop.
“Response body contents” on page 1320 describes the full list of data that is returned in this report.

For more information about transactional service classes, hops in the transaction flow, and application
environments, see the topic “Enhanced monitoring and management through guest platform management
providers” in the Ensemble Workload Resource Group Management Guide, GC27-2629.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. The hops report for the service class can be empty when one of
the following circumstances is true for all of the virtual servers associated with the service class:
v A guest platform management provider is not installed or running on the operating system.
v No ARM-instrumented applications are running on the operating system.
v None of the ARM-instrumented applications running on the operating system are hop 0 application
environments.

An error response is returned if the targeted ensemble does not exist or if you do not have the
requirements listed in “Authorization requirements” on page 1324.

The request body is validated against the schema described in “Request body contents” on page 1319. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Chapter 18. Workload resource group management 1323

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Hops Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-service-class-hops-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group",
"service-class-report-id": "Batch Service"
}

Figure 716. Generate Service Class Hops Report: Request

Generate Service Class Virtual Server Topology Report

Use the Generate Service Class Virtual Server Topology Report operation to create a custom on-demand
topology report for a specific service class within a workload resource group over a requested time
period. The report is based on historical performance management data that was retained over that time
period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-service-class-
virtual-server-topology-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble containing the workload
resource group for which you want to receive a virtual server topology report.

1324 HMC Web Services API

 Level 04a

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
workload-report-id String Required An identifier used by the performance management reporting
structure to keep track of reporting data for the specific workload
resource group named in the workload-name field.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report
for this same interval.
service-class- String Required An identifier used by the performance management reporting
report-id structure to keep track of reporting data for the specific service class
named in the service-class-name field.
Note: This value is the same as the service-class-report-id value
that is returned in one of the service class entries in the Service
Classes Report for this same interval.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the performance management reporting structure to
keep track of reporting data for the specific workload resource group named
in the workload-name field.
service-class-name String The displayable name of the service class.
service-class-report- String An identifier used by the performance management reporting structure to
id keep track of reporting data for the specific service class named in the
service-class-name field.

Chapter 18. Workload resource group management 1325

 Level 04a

Field name Type Description

equivalent-workload- Array of Because a specific virtual server can belong to more than one workload, the
service-classes objects hops report might contain reflect combined values for multiple workload
resource groups rather than those for the requested workload resource group
and service class. In this case, this field contains an array of nested
equivalent-workload-service-class objects, each of which identifies another
workload resource group or service class, if any, that have virtual servers
also contained within the reported hops. The format of the returned object is
described in Table 448. Otherwise, this field contains an empty array.
topo-hop-count Integer The total number of hops represented in this topology report.
topo-hops Array of An array of nested topo-hop objects. The format of the returned object is
objects described in Table 449.

Each nested equivalent-workload-service-class object contains the following fields:

Table 448. Format of an equivalent-workload-service-class object
Field name Type Description
equiv-workload-name String The displayable name of a workload resource group that is part of an
equivalent service class that was included in this report.
equiv-workload- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific workload resource group named
in the equiv-workload-name field.
equiv-service-class- String The displayable name of the equivalent service class (within the workload
name resource group defined by the equiv-workload-name) that was included in
this report.
equiv-service-class- String An identifier used by the performance management reporting structure to
report-id keep track of reporting data for the specific service class named in the
equiv-service-class-name field.

Each nested topo-hop object contains the following fields:

Table 449. Format of a topo-hop object
Field name Type Description
hop-number Integer The number of this hop. The hop numbers reflect the relative order of the
flow of a work request (transaction) from one application environment to the
next. The first hop is 0, the next is hop 1, the next is hop 2, and so on.
topo-virtual-server- Array of An array of nested topo-virtual-server-node objects that represent virtual
nodes objects servers that are part of this hop. The format of the returned object is
described in Table 450.

Each nested topo-virtual-server-node object contains the following fields:

Table 450. Format of a topo-virtual-server-node object
Field name Type Description
node-identifier String A topology node identifier that uniquely identifies this specific node within
this entire topology report. For example, a virtual server that shows up in
multiple hops of the transaction flow has the same virtual server name in all
of those nodes but each node identifier is different.
virtual-server-name String The displayable name of the virtual server.

1326 HMC Web Services API

 Level 04a

Table 450. Format of a topo-virtual-server-node object (continued)

Field name Type Description
hypervisor-type String The value of the type property of the virtualization host. See the
virtualization host “Data model” on page 987 for more details about the
valid values of this property.
hypervisor-name String The displayable name of the hypervisor under which this virtual server was
running.
was-active Boolean Indicates whether this virtual server was active during this reporting
interval. The value is "true" if the virtual server was active or "false" if it
was not active. If the value of this field is false, none of the remaining fields
in this table have data, so none of these fields are returned.
physical-cpu- Float The physical processor utilization percentage (%) of the virtual server. This
utilization-percent percentage is in fractional form (between 0 and 1 inclusive). Optional: This
field is returned only if the virtual server was active during this interval.
hypervisor-cpu-delay- Float The hypervisor processing unit delay in fractional form (between 0 and 1
percent inclusive). This field is returned for the following hypervisors only: z/VM
and PowerVM. In the case of z/VM, a value is available for this field only if
sampling is turned on for the guest. Optional: This field is returned only if
the virtual server was active during this interval and if the hypervisor type
supports this information.
idle-time-percent Float The idle time percentage (%) of the virtual server. It is the percentage of total
time that the virtual server had no work (that is, no application processes or
internal hypervisor specific process states). This percentage is in fractional
form (between 0 and 1 inclusive). Optional: This field is returned only if the
virtual server was active during this interval and if the hypervisor type
supports this information. For z/VM, this data is available only when
sampling is enabled and started. For PowerVM and PR/SM, idle time data is
not available.
other-time-percent Float The percentage (%) of total time that miscellaneous hypervisor specific
internal process states had control for this virtual server. In other words, the
percentage of time that the virtual server was not idle but also was not in a
state of active CPU utilization or hypervisor CPU delay. This percentage is in
fractional form (between 0 and 1 inclusive). Optional: This field is returned
only if the virtual server was active during this interval and if the hypervisor
type supports this information. For z/VM, this data is available only when
sampling is enabled and started. For PowerVM and PR/SM, other time data
is not available.
os-cpu-using-samples- Float The percentage of CPU using samples from among the total samples. For
percent example, if there are 10 CPU using samples out of a total of 10 samples, then
CPU using samples is 100% (because out of the total samples, all are CPU
using samples). This percentage is in fractional form (between 0 and 1
inclusive). Optional: This field is returned only if the virtual server was
active and a guest platform management provider was running on the
virtual server during this interval.
os-cpu-delay-samples- Float The percentage of CPU delay samples from among the total samples. For
percent example, if there are 10 CPU delay samples and 10 samples that are not CPU
delay samples, then CPU delay samples is 50% (because out of the total
samples half are CPU delay samples). This percentage is in fractional form
(between 0 and 1 inclusive). Optional: This field is returned only if the
virtual server was active and a guest platform management provider was
running on the virtual server during this interval.

Chapter 18. Workload resource group management 1327

 Level 04a

Table 450. Format of a topo-virtual-server-node object (continued)

Field name Type Description
os-io-delay-samples- Float The percentage of I/O delay samples from among the total samples. The
percent percent I/O delay is the percent of samples taken when work was delayed
for non-paging DASD I/O. The I/O delay includes IOS queue, subchannel
pending, and control unit queue delays. For example, if there are 10 I/O
delay samples and 10 samples that are not I/O delay samples, then I/O
delay samples is 50% (because out of the total samples half are I/O delay
samples). This percentage is in fractional form (between 0 and 1 inclusive).
Optional: This field is returned only if the virtual server was active and a
guest platform management provider was running on the virtual server
during this interval.
os-page-delay- Float The percentage of page delay samples from among the total samples. The
samples-percent percent page delay is the percent of samples when the address space
experienced page faults in cross-memory access, and the page faults were
resolved from auxiliary storage. For example, if there are 10 page delay
samples and 10 samples that are not page delay samples, then page delay
samples is 50% (because out of the total samples half are page delay
samples). This percentage is in fractional form (between 0 and 1 inclusive).
Optional: This field is returned only if the virtual server was active and a
guest platform management provider was running on the virtual server
during this interval.
appl-env-vs-response- Array of An array of nested appl-env-vs-response-entry objects that contain
data objects response time data for each of the application environments with which the
virtual server is associated. If no response data is available, this field
contains an empty array. The format of the returned object is described in
Table 451.
appl-env-vs- Array of An array of nested appl-env-vs-utilization-data objects that contain
utilization-data objects utilization data for each of the application environments with which the
virtual server is associated. If no response data is available, this field
contains an empty array. The format of the returned object is described in
Table 452 on page 1329.
child-virtual-server- Array of An array of nested child-virtual-server-node-link objects that contain a
node-links objects list of links to other virtual server nodes in the topology, if this particular
virtual server sent transactions to one or more virtual server nodes in the
next hop. These link objects provide the information required to identify
those next-level nodes (or “child” virtual servers). If this virtual server node
has no child nodes, this field contains an empty array. The format of the
returned object is described in Table 453 on page 1330.

Each nested appl-env-vs-response-entry object contains the following fields:

Table 451. Format of an appl-env-vs-response-entry object
Field name Type Description
appl-env-name String The name of the application environment. An application environment is the
environment that includes the software and the server or network
infrastructure that supports it.
group-name String The name of the application environment group with which this application
environment is associated. This value cannot be more than 128 characters
long but is zero length when the application environment does not belong to
a group.
successful- Integer The total number of transactions that completed successfully.
transactions
failed-transactions Integer The total number of transactions that failed.

1328 HMC Web Services API

 Level 04a

Table 451. Format of an appl-env-vs-response-entry object (continued)

Field name Type Description
stopped-transactions Integer Total number of transactions that stopped before completing. These
transactions did not fail or complete successfully; a transaction can enter the
stopped state if it encounters an error with the application or server that is
processing the transaction. For example, if an application detects that its
caller or client terminates the request before the transaction instance
completes, the application can stop processing for the transaction instance
and report it as stopped, rather than failed or successful.
inflight-transactions Integer The total number of transactions that had started, but not yet completed by
the end of the requested reporting interval.

Optional: This data may not always be available. For example, when Linux is
involved, it is not usually possible to obtain this statistic. If it is not available,
this field will not be returned.
queue-time Integer The average amount of time (in microseconds) from the time a transaction is
received until processing of the transaction begins.

Optional: This data may not always be available. For example, when Linux is
involved, it is not usually possible to obtain this statistic. If it is not available,
this field will not be returned.
execution-time Integer The average amount of time (in microseconds) that transactions took to
execute.

Optional: This data may not always be available. For example, when Linux is
involved, it is not usually possible to obtain this statistic. If it is not available,
this field will not be returned.
successful-avg- Integer Average response time (in microseconds) of all successful transactions.
response-time
inflight-avg- Integer Average amount of time (in microseconds) spent toward response time for
response-time inflight transactions.

Optional: This data may not always be available. For example, when Linux is
involved, it is not usually possible to obtain this statistic. If it is not available,
this field will not be returned.

Each nested appl-env-vs-utilization-entry object contains the following fields:

Table 452. Format of an appl-env-vs-utilization-entry object
Field name Type Description
appl-env-name String The name of the application environment. An application environment is the
environment that includes the software and the server or network
infrastructure that supports it.
group-name String The name of the application environment group with which this application
environment is associated. This value cannot be more than 128 characters
long but is zero length when the application environment does not belong to
a group.
cpu-time Integer The processor (CPU) time, in microseconds, that was consumed on this
virtual server as part of this application environment.

Chapter 18. Workload resource group management 1329

 Level 04a

Table 452. Format of an appl-env-vs-utilization-entry object (continued)

Field name Type Description
os-cpu-using-samples- Float The percentage of CPU using samples from among the total samples. For
percent example, if there are 10 CPU using samples out of a total of 10 samples, then
CPU using samples is 100% (because out of the total samples, all are CPU
using samples). This percentage is in fractional form (between 0 and 1
inclusive). Optional: This field is returned only if the virtual server was
active and a guest platform management provider was running on the
virtual server during this interval.
os-cpu-delay-samples- Float The percentage of CPU delay samples from among the total samples. For
percent example, if there are 10 CPU delay samples and 10 samples that are not CPU
delay samples, then CPU delay samples is 50% (because out of the total
samples half are CPU delay samples). This percentage is in fractional form
(between 0 and 1 inclusive). Optional: This field is returned only if the
virtual server was active and a guest platform management provider was
running on the virtual server during this interval.
os-io-delay-samples- Float The percentage of I/O delay samples from among the total samples. The
percent percent I/O delay is the percent of samples taken when work was delayed
for non-paging DASD I/O. The I/O delay includes IOS queue, subchannel
pending, and control unit queue delays. For example, if there are 10 I/O
delay samples and 10 samples that are not I/O delay samples, then I/O
delay samples is 50% (because out of the total samples half are I/O delay
samples). This percentage is in fractional form (between 0 and 1 inclusive).
Optional: This field is returned only if the virtual server was active and a
guest platform management provider was running on the virtual server
during this interval.
os-page-delay- Float The percentage of page delay samples from among the total samples. The
samples-percent percent page delay is the percent of samples when the address space
experienced page faults in cross-memory access, and the page faults were
resolved from auxiliary storage. For example, if there are 10 page delay
samples and 10 samples that are not page delay samples, then page delay
samples is 50% (because out of the total samples half are page delay
samples). This percentage is in fractional form (between 0 and 1 inclusive).
Optional: This field is returned only if the virtual server was active and a
guest platform management provider was running on the virtual server
during this interval.

Each nested child-virtual-server-node-link object contains the following fields:

Table 453. Format of a child-virtual-server-node-link object
Field name Type Description
child-node-identifier String The unique identifier assigned within this topology report to this child
virtual server node.
child-hop-number Integer The number of the hop that contains this child virtual server node.
transaction-count Integer The number of transactions that flowed from the parent virtual server node
to this specific child virtual server node over this reporting period. If no
transaction data is available, this field is not returned.

Description
The Generate Service Class Virtual Server Topology Report operation generates a report that contains
the following information for a specific service class within a workload resource group over the requested
time interval:

1330 HMC Web Services API

 Level 04a

v A list of application-level hops associated with this specific workload resource group and service class
for which historical reporting information is available. A hop corresponds to a tier in the transactional
flow, and each hop can have one or more application environments associated with it.
A service class can have multiple hops associated with it, and each hop can have one or more
associated application environments. These application environments might have multiple virtual
servers.
v For each hop associated with the service class:
– A common set of statistics
– Statistics for the application environments and virtual servers within each hop.

This report returns information that is similar to the output of the Generate Service Class Hops Report
operation; the virtual server nodes are organized by hop and the reports contain some similar statistics
for each virtual server. This topology report, however, also returns information about the relationship
between the virtual servers from one hop to the next. This type of information relationships is not always
available, depending on the actual configuration of the application environments.

For an example of a graphical representation of the virtual server topology, use the Virtual Server
Topology Report that is available through the HMC or see the topic about that report in the Ensemble
Workload Resource Group Management Guide, GC27-2629. The Virtual Server Topology Report task
graphically depicts the relationships between virtual servers that are running the workload resource
group and providing the resources to complete the work. The framed image in that report displays
graphical representations of virtual servers. Each is represented by an icon that displays the name and
status of the virtual server; by clicking the icon, you can view statistics for that virtual server node. The
Generate Service Class Virtual Server Topology Report operation generates the same information that
you can access through the Virtual Server Topology Report and the icons in its display.

“Response body contents” on page 1325 describes the full list of data that is returned in the report for
this workload resource group.

If reporting data is not available for the requested time interval, an empty response object is provided
and the operation completes successfully. An error response is returned if the targeted ensemble does not
exist or if you do not have the requirements listed in “Authorization requirements.”

The request body is validated against the schema described in “Request body contents” on page 1325. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Virtual Server Topology Report and the View Statistics tasks.

HTTP status and reason codes

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

Otherwise, 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 18. Workload resource group management 1331

 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-service-class-virtual-server-topology-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group",
"service-class-report-id": "Batch Service"
}

Figure 717. Generate Service Class Virtual Server Topology Report: Request

Generate Load Balancing Report

Use the Generate Load Balancing Report operation to list information about network load balancing
activity in an ensemble. Unlike other performance management reports, which are based on historical
performance management data that was retained over a specific time period, this report contains data
that is available when the Generate Load Balancing Report API is called.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/performance-management/operations/generate-load-balancing-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble for which you want to
receive a load balancing report.

Response body contents

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

Field name Type Description

load-balancing-groups Array of An array of nested load-balancing-Group objects. If no load balancing
objects groups have been defined for this ensemble, an empty array is returned for
this field.

Each nested load-balancing-Group object contains the following fields:

1332 HMC Web Services API

 Level 04a

Field name Type Description

load-balancer-group- String The name given to this load balancer group. The returned string in this field
name conforms to Server/Application State Protocol (SASP) standards, which
allow a group name to consist of 1 through 255 UTF8 characters.
load-balancer-group- Array of An array of nested load-balancer-group-member objects. If a group does not
members objects have any members associated with it, an empty array is returned for this
field.

Each nested load-balancer-group-member object contains the following fields:

Field name Type Description

virtual-server-name String The name of a virtual server defined to this load balancing group.
hostname-ipaddr String The IP address of the virtual server.
weight Float The relative weight recommendation that zManager assigned to this member.
status String The status of or environmental conditions for each virtual server in the
Enum selected load balancing group. Possible values are:
v "active"
v "down"
v "inactive"
v "failure-recovery"
v "quiesced"
v "unknown"
status-detailed String A further explanation for the specific status condition "down" or "inactive";
Enum for other status field values, this field is not returned. Possible values are:
v "matching-ip-address-not-found"
v "gpmp-downlevel"
v "lsof-not-available"
v "no-process-listening"
v "not-initialized"
v "vs-not-operating"
v "load-balance-data-initializing"
v "unsupported-hypervisor-config"
v "hypervisor-details-not-available"
v "data-retrieval-error"
port-number Integer The port number on the virtual server that is being used for load balancing
purposes. This field is not returned if the port number is not available.
protocol-type String The protocol in use for this virtual server; possible values are:
Enum v "tcp" for Transmission Control Protocol, or
v "udp" for User Datagram Protocol
This field is not returned if the protocol type is not available.

Description
The Generate Load Balancing Report operation generates a report that contains a list of all of the
load-balancing groups that zManager is monitoring within a specific ensemble. For each load-balancing
group, the report also contains information about each individual virtual server that is a member of the
group. “Response body contents” on page 1332 describes the full list of data that is returned in this
report for each load-balancing group and its members.

The generated load-balancing report contains data that is available when the Generate Load Balancing
Report API is called. Load-balancing data for an ensemble is refreshed every 30 seconds. For the most
efficient use of the Generate Load Balancing Report API, space additional API calls at least 30 seconds
apart.

Chapter 18. Workload resource group management 1333

 Level 04a

If no load-balancing groups are defined for this ensemble, an empty response object is provided and the
operation completes successfully. An error response is returned if the targeted ensemble does not exist or
if you do not have the requirements listed in “Authorization requirements.”

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Load Balancing Report task.

HTTP status and reason codes

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

Otherwise, 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.

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

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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

Example HTTP interaction

POST /api/ensembles/12345678-1234-1234-1234-123456789000/performance-management/operations/
generate-load-balancing-report

Figure 718. Generate Load Balancing Report: Request

Workload Element Group object

A Workload Element Group object is a container object of redundant elements of one or more workloads.
The group is used to maintain redundancy for a function within the workload business unit. It must
always be in one or more user-defined workloads.

Data model
This object includes the properties defined in the “Base managed object properties schema” on page 60,
with the class-specific specialization described in the following tables. Note that this object does not
maintain the concept of an operational status, and therefore does not provide the operational-status-
related properties.

For definitions of the qualifier abbreviations in the following tables, see “Property characteristics” on
page 58.

1334 HMC Web Services API

 Level 04a

Table 454. Workload object: base managed object properties specializations

Name Qualifier Type Description of specialization
object-uri — String/URI The canonical URI path for a Workload Element Group object
is of the form /api/workload-element-groups/{group-id}
where {group-id} is the value of the object-id property of the
Workload Element Group object.
object-id — String (36) The unique identifier of the Workload Element Group object,
in the form of a UUID.
parent — String The object-uri property of the owning ensemble object.
class — String The class of a Workload Element Group object is
"workload-element-group".
name (w) (pc) String The user-specified workload element group name, which can
(1-64) be up to 64 characters made up of alphanumeric characters,
blanks, periods, underscores, or dashes. Names must start
with an alphabetic character and end with an alphabetic
character, numeric character, underscore, period, or dash.
Names must be unique to other existing workload element
groups in the ensemble.
description (w) (pc) String The user-specified workload element group description, up to
(0-256) 256 characters, or if none was provided, an empty string.
is-locked — Boolean This property is always false for a Workload Element Group
object.

In addition to the properties defined through included schemas, this object includes the additional
class-specific properties:
Table 455. Workload Element Group object: class-specific properties
Name Qualifier Type Description
category (w) (pc) String Up to 32 characters used to categorize the workload object,
(0-32) often with other workloads within the ensemble.
workloads (c) (pc) Array of An array of URIs of the workloads in which the workload
String/URI element group belongs.

Value may not be null or an empty list.

minimum-available- (w) (pc) Integer The number of workload elements that should minimally be
elements available in the Workload Element Group object, by default,
unless overridden by an Availability Policy object.

Value must be greater than or equal to zero.

preferred-available- (w) (pc) Integer The number of workload elements that are preferred to be
elements available in the Workload Element Group object, by default,
unless overridden by an Availability Policy object.

Value must be greater than or equal to minimum-available-

elements.

Chapter 18. Workload resource group management 1335

 Level 04a

Table 455. Workload Element Group object: class-specific properties (continued)

Name Qualifier Type Description
virtual-servers (c) (pc) Array of This is a placeholder property for which container-type events
String/URI will be fired to indicate the delta of the URIs of virtual
servers of the workload element group which were added or
removed. The actual list of virtual servers can be retrieved
through the List Virtual Servers of a Workload Element
Group operation.

Note that only virtual servers that support Ensemble

Availability Management may be added to the list. Virtual
servers which do not support Ensemble Availability
Management will have an avail-status of “not-supported”.
avail-statuses (pc) Array of The availability statuses of the workload element group for
objects each workload it belongs to, each in the form of a workload
element group availability status object, as described below.
The availability status of a workload element group can vary
by workload context due to the workload element group
configuration overrides a workload’s availability policy can
define.

Workload element group availability status nested object

The workload element group availability status object is nested within a workload element group to
provide the availability status for the workload element group within the context of each workload to
which it belongs.

The following properties are supported:

Table 456. Workload Element Group object: Workload element group availability status nested object properties
Field name Type Rqd/Opt Description
workload-uri String/URI The canonical URI path for a workload object that the workload
element group availability status is in the context of, in the form
/api/workload-resource-groups/{workload-id} where {workload-id} is
the value of the object-id property of the workload object.
avail-status-with- Array of The list of availability statuses of the workload element group, each
reasons objects with reasons explaining the status, in order of severity. The list will
always contain at least one workload element in the form of a
workload element group availability status with reasons nested object,
as described in the next table.

Workload element group availability status with reasons nested object: The workload element group
availability status with reasons nested object is nested within a workload element group availability
status object for a particular workload to encapsulate the availability status with the reasons explaining
why it is in that state.

1336 HMC Web Services API

 Level 04a

Table 457. Workload Element Group object: Workload element group availability status with reasons nested object
properties
Field name Type Rqd/Opt Description
avail-status String The availability status of the workload element group, determined by
Enum the active availability policy in the workload and the availability status
of the workload element group’s virtual servers. The possible values
are as follows:
v "available": The workload element group is considered available.
v "exposed": The workload element group is considered exposed.
v "critical": The workload element group is considered critically
exposed.
v "not-available": The workload element group is considered not
available.
reasons Array of The list of reasons given for the availability status of the workload
String element group. The possible values are as follows:
Enum v "min-avail": The number of available workload elements in the
workload element group is below the configured minimum.
v "pref-avail": The number of available workload elements in the
workload element group is below the configured preference.
v "zero-avail": The number of available workload elements in the
workload element group is zero and the "min-avail" is > 0.

The list may be empty if no reasons are given.

List Workload Element Groups of an Ensemble

Use the List Workload Element Groups of an Ensemble operation to list the workload element groups
within the target ensemble.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/workload-element-groups

In this request, the URI variable {ensemble-id} is the object ID of the ensemble for which you are
requesting a list of workload element groups.

Query parameters

Name Type Rqd/Opt Description

name String Optional Filter pattern to limit returned objects to those that have a matching
name property. If matches are found, the response is an array with
all workload element groups that match. If no match is found, the
response is an empty array.

Response body contents

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

Field name Type Description

workload-element- Array of Array of nested element-group-info objects as described in the next table.
groups objects

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

Chapter 18. Workload resource group management 1337

 Level 04a

Field name Type Description

object-uri String/URI Canonical URI path of the Workload Element Group object, in the form
/api/workload-element-groups/{group-id}.
name String Display name of the Workload Element Group object.

Description
The List Workload Element Groups of an Ensemble operation lists the workload element groups that
belong to the ensemble targeted by the request URI. The object URI and display name are provided for
each.

If the name query parameter is specified, the returned list is limited to the workload element group in
the ensemble that has a name property matching the specified filter pattern. If the name parameter is
omitted, this filtering is not done.

A workload element group is included in the list only if you have object-access permission for that object.
Additionally, you must have access to the ensemble object, or an error response will be returned

If the HMC does not manage the targeted ensemble, then an error response occurs.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the ensemble object passed in the request URI and all Workload Element
Group objects to be included in the result.

HTTP status and reason codes

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

Otherwise, 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 ({ensemble-id}) does not designate an existing
ensemble 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.

Get Workload Element Group Properties

Use the Get Workload Element Group Properties operation to retrieve the properties of a single
Workload Element Group object that is designated by its object ID.

HTTP method and URI

GET /api/workload-element-groups/{group-id}

URI variables
1338 HMC Web Services API
 Level 04a

Variable Description
{group-id} Object ID of the Workload Element Group object for which properties are to be
obtained.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Workload Element Group object as defined in “Data model” on page 1334. 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 Workload Element Group Properties operation returns the current properties for the Workload
Element Group object specified by {group-id}.

On successful execution, all of the current properties as defined by the “Data model” on page 1334 are
provided in the response body and HTTP status code 200 (OK) is returned.

A URI path must designate an existing Workload Element Group object and you must have object-access
permission to it. If either of these conditions is not met, status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Workload Element Group object designated by {group-id}.

HTTP status and reason codes

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

Otherwise, 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 ({group-id}) does not designate an existing Workload
Element Group object, or the API user does not have object-access
permission to the object.

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

Create Workload Element Group

Use the Create Workload Element Group operation to create a new custom workload element group in
an ensemble. The new workload element group must be uniquely named within the ensemble.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/workload-element-groups

Chapter 18. Workload resource group management 1339

 Level 04a

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which a workload
element group is to be created.

Request body contents

The request body contains properties used to define the new workload element group, which are a subset
of the properties of a workload element group. Some properties are optional:

Field name Type Rqd/Opt Description

name String Required The value to be set as the workload element group’s name property.
(1-64)
description String Optional The value to be set as the workload element group’s description
(0-256) property.
category String Optional The value to be set as the workload element group’s category
(0-32) property.
workloads Array of Required The value to be set as the workload element group's workloads
String/URI property.
minimum- Integer Optional The value to be set as the workload element group’s
available- minimum-available-elements property.
elements
Default value: 2
preferred- Integer Optional The value to be set as the workload element group’s
available- preferred-available-elements property.
elements
Default value: minimum-available-elements
virtual-servers Array of Optional The value to be set as the workload element group’s virtual-servers
String/URI property.

Default value: an empty list

Response body contents

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

Field name Type Description

object-uri String/URI Canonical URI path of the Workload Element Group object, in the form
/api/workload-element-groups/{group-id}.

Description
The Create Workload Element Group operation creates a new custom workload element group in the
ensemble identified by {ensemble-id}.

The request body contains an object with one or more fields with field names that correspond to the
names of properties for this object. The only required properties are the workload element group name,
which must be unique among existing workload element groups in the ensemble, and the workloads in
which the workload element group belongs. On successful execution, the workload element group is
created, added to the identified workloads, and added to the ensemble and status code 201 is returned
with a response body containing a reference to the new workload element group.

The URI path must designate an existing ensemble object and the API user must have object-access
permission to it. The workloads property must designate a list of existing workload objects and the API
user must have object-access permission to them. If provided, the virtual-servers property must designate
a list of existing Virtual Server objects and the API user must have object-access permission to them. If

1340 HMC Web Services API

 Level 04a

any of these conditions is not met, status code 404 (Not Found) is returned. If any of the passed virtual
servers do not support Ensemble Availability Management, status code 400 (Bad Request) is returned. In
addition, you must have permission to the New Element Group task and the ensemble must be at the
AUTOMATE entitlement level, otherwise status code 403 (Forbidden) is returned.

The request body is validated against the “Data model” on page 1334 to ensure that it 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.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Object-access permission to all Workload objects designated by workloads.
v Object-access permission to all Virtual Server objects designated by virtual-servers.
v Action/task permission to the New Element Group task.

HTTP status and reason codes

On successful completion, HTTP status code 201 (Created) is returned and the response body is provided
as described in “Response body contents” on page 1340.

Otherwise, 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.
65 The name of the new workload element group is not unique.
66 One or more of the virtual servers in the request body do not support
Ensemble Availability Management.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
3 The ensemble is not operating at the management entitlement level required
to perform this operation (Automate).
404 (Not Found) 1 The object ID in the URI ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.
2 A URI in workloads or virtual-servers does not designate an existing
workload or Virtual Server object, or the API user does not have
object-access permission to the object.
409 (Conflict 61 The operation cannot be performed because one or more virtual servers
designated by the virtual-servers URI are currently busy performing some
other operation.
64 The operation cannot be performed because one or more workload resource
groups servers designated by the workloads URI are currently busy
performing some other operation.

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

Chapter 18. Workload resource group management 1341

 Level 04a

Delete Workload Element Group

Use the Delete Workload Element Group operation to remove a workload element group from an
ensemble and the workloads to which it belongs.

HTTP method and URI

DELETE /api/workload-element-groups/{group-id}

In this request, the URI variable {group-id} is the object ID of the Workload Element Group object that you
want to remove.

Description
The Delete Workload Element Group operation deletes the Workload Element Group object specified by
{group-id} from its ensemble.

On successful completion, the workload element group is removed from all workloads (potentially
removing its virtual servers from the workloads), the workload element group is removed from the
ensemble, and the status code 204 (No Content) is returned without supplying a response body. See the
Ensemble Workload Resource Group Management Guide, GC27-2629, for details about managing workload
element groups.

The URI path must designate an existing Workload Element Group object and the API user must have
object-access permission to it. If this condition is not met, status code 404 (Not Found) is returned.
Additionally, you must have permission to the Delete Element Group task. If this condition is not met,
status code 403 (Forbidden) is returned.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object that owns the workload element group.
v Object-access permission to the Workload Element Group object designated by {group-id}.
v Action/task permission to the Delete Element Group task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned.

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.
62 The workload element group to be removed contains virtual servers to
which the API user does not have access.
68 The workload element group to be removed is assigned to one or more
workload resource groups servers to which the API user does not have
access.
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 ({group-id}) does not designate an existing Workload
Element Group object, or the API user does not have object-access
permission to the object.

1342 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
61 The operation cannot be performed because one or more virtual servers in
the workload element group designated by the request URI are currently
busy performing some other operation.
64 The operation cannot be performed because one or more workload resource
groups to which the workload element group is assigned are currently busy
performing some other operation.

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

Update Workload Element Group

Use the Update Workload Element Group operation to modify one or more writable properties of a
Workload Element Group object.

HTTP method and URI

POST /api/workload-element-groups/{group-id}

In this request, the URI variable {group-id} is the object ID of the Workload Element Group object that you
are modifying.

Request body contents

The request body is a JSON object with one or more of the writable fields for a workload element group
as described in the “Data model” on page 1334. You are required to supply only those fields that you
want to change.

Description
The Update Workload Element Group updates one or more simple writable properties of the Workload
Element Group object identified by {group-id}.

On successful execution, the Workload Element Group object is updated with the supplied property
values and status code 204 (No Content) is returned without supplying a response body. Notifications for
these property changes are sent asynchronously to this operation.

The URI path must designate an existing Workload Element Group object and you must have
object-access permission to it. If either of these conditions is not met, status code 404 (Not Found) is
returned. In addition, you must also have permission to the Element Group Details task as well,
otherwise status code 403 (Forbidden) is returned.

The request body is validated against the schema described in “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Workload Element Group object designated by {group-id}.
v Action/task permission to the Element Group Details task.

Chapter 18. Workload resource group management 1343

 Level 04a

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned. Otherwise, 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.
65 The new name given to the workload element group is not unique.
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 ({group-id}) does not designate an existing Workload
Element Group object, or the API user does not have object-access
permission to the object.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.

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

List Virtual Servers of a Workload Element Group

The List Virtual Servers of a Workload Element Group operation lists the virtual servers in the passed
workload element group. This is the way to get the information corresponding to the virtual-servers
property of a workload element group, as it is omitted from the standard GET operation.

HTTP method and URI

GET /api/workload-element-groups/{group-id}/virtual-servers

In this request, the URI variable {group-id} is the object ID of the Workload Element Group object for
which you are requesting a list of virtual servers.

Query parameters:

Field name Type Rqd/Opt Description

name String Optional Filter pattern to limit returned objects to those that have a matching
name property. If matches are found, the response will be an array
with information for all virtual servers that match. If no match is
found, the response will be an empty array.

Response body contents

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

Field name Type Description

virtual-servers Array of Array of nested virtual-server-info objects as described in the next table.
objects

Each nested virtual-server-info object contains the following fields:

1344 HMC Web Services API

 Level 04a

Field name Type Description

object-uri String/URI Canonical URI path of the Virtual Server object.
name String The current value of the name property of the Virtual Server object.
status String Enum The current value of the status property of the Virtual Server object.
type String Enum The value of the type property of the Virtual Server object.

Description
The List Virtual Servers of a Workload Element Group operation lists the virtual servers that belong to
the workload element group targeted by the request URI. The object URI, display name, status, and type
are provided for each.

A virtual server is included in the list only if you have object-access permission for that object.
Additionally, you must have access to the Workload Element Group object, or an error response will be
returned.

If the HMC’s Ensemble does not contain the targeted workload element group, then an error response
occurs.

Authorization requirements
This operation has the following authorization requirement:
v v Object-access permission to the Workload Element Group object passed in the request URI and all
Virtual Server objects to be included in the result.

HTTP status and reason codes

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

Otherwise, 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 ({group-id}) does not designate an existing workload
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.

Add Virtual Server to a Workload Element Group

Use the Add Virtual Server to a Workload Element Group operation to add a virtual server to the target
workload element group.

HTTP method and URI

POST /api/workload-element-groups/{group-id}/operations/add-virtual-server

Chapter 18. Workload resource group management 1345

 Level 04a

In this request, the URI variable {group-id} is the object ID of the Workload Element Group object to
which you want to add a virtual server.

Request body contents

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

Field name Type Description

virtual-server String/URI The canonical URI identifying the Virtual Server object to be added to the
target workload element group.

Description
The Add Virtual Server to a Workload Element Group operation adds a virtual server directly to the
workload element group targeted by the request URI. See the Ensemble Workload Resource Group
Management Guide, GC27-2629, for details on managing virtual servers in workload element groups.

If the virtual server is already defined to the workload element group, then the request is ignored with a
successful return code. If the virtual server is new to the workload element group, then it is added and a
property notification is sent asynchronously to the request. Note that adding a virtual server may impact
the availability status of the workload element group and its workload(s), depending on the workload
element objectives of the workload element group and availability status of the virtual server.

An error response will be returned if the targeted workload element group or virtual server does not
exist or you do not have object-access to either of them. If the virtual server being added does not
support Ensemble Availability Management, status code 400 (Bad Request) will be returned. Additionally,
you must have access to the Element Group Details task, or an error response will be returned.

The request body is validated against the schema described in the “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Workload Element Group object passed in the request URI.
v Object-access permission to the Virtual Server object passed in the request body.
v Action/task permission to the Element Group Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned.

Otherwise, 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.
66 The virtual server in the request body does not support Ensemble
Availability Management.
403 (Forbidden) 1 The API user does not have the required permission for this operation.

1346 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object-id in the URI ({group-id}) does not designate an existing Workload
Element Group object, or the API user does not have object-access
permission to it.
2 The object-id in the URI of the Virtual Server object in the request body
does not designate an existing object, or the API user does not have access
permission to it.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
61 The operation cannot be performed because the virtual server to be added is
currently busy performing some other operation.
64 The operation cannot be performed because one or more workload resource
groups to which the workload element group is assigned are currently busy
performing some other operation.

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

Remove Virtual Server from a Workload Element Group

Use the Remove Virtual Server from a Workload Element Group operation to remove a virtual server
from the target workload element group.

HTTP method and URI

POST /api/workload-element-groups/{group-id}/operations/remove-virtual-server

In this request, the URI variable {group-id} is the object ID of the Workload Element Group object from
which you are removing the virtual server.

Request body contents

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

Field name Type Description

virtual-server String/URI The canonical URI identifying the Virtual Server object to be removed from
the targeted workload element group.

Description
The Remove Virtual Server from a Workload Element Group operation removes a virtual server from
being defined to the workload element group targeted by the request URI. See the, Ensemble Workload
Resource Group Management Guide, GC27-2629, for details on managing virtual servers in workload
element groups.

If the virtual server is not defined to the workload element group, then the request is ignored with a
successful return code. If the virtual server is defined to the workload element group, then it is removed
and a property change notification will be sent asynchronously to this request. If the virtual server is no
longer contained by a user-defined workload for any reason, then it will be placed in the default
workload. Note that removing a virtual server may impact the availability status of the workload element
group and its workload(s), depending on the redundancy objectives of the workload element group and
availability status of the virtual server.

Chapter 18. Workload resource group management 1347

 Level 04a

An error response is returned if the targeted workload element group or virtual server does not exist or if
you do not have object-access to either of them. Additionally, you must have access to the Element
Group Details task, or an error response will be returned.

The request body is validated against the schema described in “Request body contents” on page 1347. If
the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the
validation error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the Workload Element Group object passed in the request URI.
v Object-access permission to the Virtual Server object passed in the request body.
v Action/task permission to the Element Group Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned.

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 ({group-id}) does not designate an existing Workload
Element Group object, or the API user does not have object-access
permission to it.
2 The object-id in the URI of the Virtual Server object in the request body
does not designate an existing object, or the API user does not have access
permission to it.
409 (Conflict) 2 The operation cannot be performed because the virtual server to be removed
is currently busy performing some other operation.
61 The operation cannot be performed because the group to be removed
contains one or more virtual servers that are currently busy performing some
other operation.
64 The operation cannot be performed because one or more workload resource
groups to which the workload element group is assigned are currently busy
performing some other operation.

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

Availability Policy object

Performance Policy objects are elements of a workload which define availability objectives for its
workloads elements and how the availability of those elements impacts the availability of the workload.
An availability policy consists mainly of a set importance level, availability status impact statements, and
workload elements group configuration override statements.

1348 HMC Web Services API

 Level 04a

Any number of custom Availability Policy objects can be defined for a workload. However, exactly one
will be active at a time. Every workload contains an immutable default availability policy which will be
active if a custom availability policy is not activated.

Data model
This element includes the following class-specific properties. For definitions of the qualifier abbreviations
in the following table, see “Property characteristics” on page 58.
Table 458. Availability Policy object: class-specific properties
Name Qualifier Type Description
element-uri — String/URI The canonical URI path for an availability policy is
qualified by its workload object and is of the form
/api/workloads/{workload-id}/availability-
policies/{policy-id} where {workload-id} is the
value of the object-id property of the parent
workload object and {policy-id} is the value of the
element-id property of the policy.
element-id — String (36) The unique identifier for the availability policy
instance. The policy's unique identifier of the
policy is in the form of a UUID.
parent — String/URI The parent of an availability policy is its owning
workload, and so the parent value is the canonical
URI path for the workload resource group.
class — String The class of an Availability Policy object is
"availability-policy".
name (w) (pc) String (1-64) The display name specified for the availability
policy, which can be up to 64 characters made up
of alphanumeric characters, blanks, periods,
underscores, or dashes. Names must start with an
alphabetic character and end with an alphabetic
character, numeric character, underscore, period,
or dash. Names must be unique to other existing
availability policies in the workload.
description (w) (pc) String (0-256) Arbitrary text describing the availability policy in
up to 256 characters.
is-default — Boolean This value is used to identify the default
Availability Policy object. It is true for the default
policy and false for all other (custom) policies in
the workload.
importance (w) (pc) String Enum The importance value assigned to the availability
policy, which is one of the following:
v "highest"
v "high"
v "medium"
v "low"
v "lowest"

See the Ensemble Workload Resource Group

Management Guide, GC27-2629, for detailed
information on the importance property values.

Chapter 18. Workload resource group management 1349

 Level 04a

Table 458. Availability Policy object: class-specific properties (continued)

Name Qualifier Type Description
vs-exclusions (w) (pc) Array of The list of canonical URI paths of Virtual Server
String/URI objects for which availability status will not impact
the workload availability status.

Note that only virtual servers that support

Ensemble Availability Management may be added
to the list. Virtual servers which do not support
Ensemble Availability Management will have an
avail-status of "not-supported".

Note that only virtual servers whose workload

inclusion-type is "direct" or "custom-group" may
be added to the list.
eg-overrides (w) (pc) Array of The list of Workload Element Group objectives
objects override values in place against workload element
groups in the workload when the availability
policy is active. Each workload element group
override value will be in the form of a workload
element group override object, as described in the
next table.

If no workload element group overrides are

defined, an empty array will be returned.
revision (pc) Integer (1-n) The revision count of the availability policy, which
is the number of times the policy has been
modified. The initial value for a new availability
policy is 1.
activation-status (pc) String Enum The activation status of the availability policy,
which will have one of the following values:
v "not-active": The availability policy is not
currently the active policy in the workload.
v "active": The availability policy is currently the
active policy in the workload.
last-activation-date (pc) Timestamp The standard date/time value indicating the time
of the last activation of the policy. If the policy has
never been active or is the default policy of the
default workload, this will be negative.

The standard time value is defined as the number

of elapsed milliseconds after midnight January 1,
1970.
last-activated-by (pc) String The user name used for the last activation. This is
an empty string if the policy has never been
activated or is the default policy of the default
workload.
last-modified-date (pc) Timestamp The standard date/time value indicating the time
the policy was last modified. If the policy has
never been modified, this property will be equal to
the created-date property. The value will be
negative for all default policies.

The standard time value is defined as the number

of elapsed milliseconds after midnight January 1,
1970.

1350 HMC Web Services API

 Level 04a

Table 458. Availability Policy object: class-specific properties (continued)

Name Qualifier Type Description
last-modified-by (pc) String The user name used to last modify the policy. If
the policy has never been modified, this property
will be equal to the created-by property. The value
will be an empty string for all default policies.
created-date — Timestamp The standard date/time value indicating the time
the policy was created. The value will be negative
for all default policies.

The standard time value is defined as the number

of elapsed milliseconds after midnight January 1,
1970.
created-by — String The user name used to create the policy. The value
will be an empty string for all default policies.

Workload element group override nested object

The element group override object is nested within a workload’s availability policy. It is used to override
the objectives values on an element group in the workload.
Table 459. Availability Policy object: Workload element group override nested object properties
Field name Type Rqd/Opt Description
eg-uri String/URI The canonical URI path of the Workload Element Group object whose
values to override.
minimum- Integer The minimum number of elements that should be available in the
available- Workload Element Group object.
elements
Value must be greater than or equal to zero.
preferred- Integer The number of elements that are preferred to be available in the
available- Workload Element Group object.
elements
Value must be greater than or equal to minimum-available-elements.

List Availability Policies

Use the List Availability Policies operation to list the availability policies within the target workload.

HTTP method and URI

GET /api/workload-resource-groups/{workload-id}/availability-policies

In this request, the URI variable {workload-id} is the object ID of the workload object for which you are
requesting a list of availability policies.

Query parameters

Name Type Rqd/Opt Description

name String Optional Filter pattern to limit returned objects to those that have a matching
name property. If a match is found, the response is an array with all
policies that match. If no match is found, the response is an empty
array.

Chapter 18. Workload resource group management 1351

 Level 04a

Response body contents

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

Field name Type Description

avail-policies Array of Array of nested avail-policy-info objects as described in the following table.
objects

Each nested avail-policy-info object contains the following fields:

Field name Type Description

element-uri String/URI Canonical URI path of the Availability Policy object, in the form
/api/workload-resource-groups/{workload-id}/availability-policies/
{policy-id}.
element-id String The element-id of the Availability Policy object. This field value is the
{policy-id} portion of the URI path provided by the element-uri field.
name String Display name of the Availability Policy object.
activation-status String The status of the Availability Policy object, which must be one of the
Enum following values:
v "not-active" – the availability policy is not currently the active policy for
the workload.
v "active" – the availability policy is currently the active policy for the
workload, and its activation has completed.

Description
The List Availability Policies operation lists the availability policies that belong to the workload targeted
by the request URI. The element URI, element ID, display name, and status are provided for each.

If the name query parameter is specified, the returned list is limited to the policy in the workload that
has a name property matching the specified filter pattern. If the name parameter is omitted, this filtering
is not done.

A policy is included in the list only if you have object-access permission for that object. Additionally, you
must have access to the workload object, or an error response is returned.

If the HMC does not manage the targeted workload, then an error response occurs.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Workload Resource Group object designated by {workload-id}.

HTTP status and reason codes

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

Otherwise, 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.

1352 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.
404 (Not Found) 1 The object-id in the URI ({workload-id}) does not designate an existing
Workload Resource Group 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.

Get Availability Policy Properties

Use the Get Availability Policy Properties operation to retrieve the properties of a single Availability
Policy object, designated by its element ID.

HTTP method and URI

GET /api/workload-resource-groups/{workload-id}/availability-policies/{policy-id}

URI variables

Variable Description
{workload-id} Object ID of the Workload Resource Group object for which the policy's properties
are to be obtained.
{policy-id} Element ID of the Availability Policy object for which properties are to be obtained.

Response body contents

On successful completion, the response body is a JSON object that provides the current values of the
properties for the Availability Policy object as defined in “Data model” on page 1349. 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 Availability Policy Properties operation returns the current properties for the Availability Policy
object specified by {policy-id}.

On successful execution, all of the current properties as defined by the “Data model” on page 1349 are
provided in the response body and HTTP status code 200 (OK) is returned.

The URI path must designate an existing Workload Resource Group and Availability Policy object and
you must have object-access permission to the Workload Resource Group object. If either of these
conditions is not met, status code 404 (Not Found) is returned.

Authorization requirements
This operation has the following authorization requirement:
v Object-access permission to the Workload Resource Group object designated by {workload-id}.

Chapter 18. Workload resource group management 1353

 Level 04a

HTTP status and reason codes

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

Otherwise, 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 ({workload-id}) does not designate an existing
Workload Resource Group object, or the API user does not have object-access
permission to the object.
63 The element ID in the URI ({policy-id}) does not designate an existing
Availability Policy object in the workload.

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

Create Availability Policy

Use the Create Availability Policy operation to create a new custom availability policy for a workload
resource group. The new policy must be uniquely named within the workload. The policy is inactive
until the Activate Availability Policy operation is applied to it.

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/availability-policies

In this request, the URI variable {workload-id} is the object ID of the Workload Resource Group object for
which you are creating a new availability policy.

Request body contents

The request body contains properties used to define the new performance policy, which are the writable
properties of a performance policy. Some properties are optional.

Field name Type Rqd/Opt Description

name String Required The name to give the new availability policy, as described in the
(1-64) “Data model” on page 1349. The passed name must be unique
among all other availability policies currently in the workload.
description String Optional The description to give the new availability policy, as described in
(0-256) the “Data model” on page 1349.
importance String Required The importance value to give the new availability policy, as
Enum described in the “Data model” on page 1349.
vs-exclusions Array of Optional The vs-exclusions value to give the new availability policy, as
String/ described in the “Data model” on page 1349.
URI
eg-overrides Array of Optional The eg-overrides value to give to the new availability policy, as
objects described in the “Data model” on page 1349.

1354 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

element-uri String/URI Canonical URI path of the Availability Policy object, in the form
/api/workload-resource-groups/{workload-id}/availability-policies/
{policy-id}

Description
The Create Availability Policy operation creates a new custom availability policy in a workload,
identified by {workload-id}.

The request body contains an object with field names that correspond to the names of properties for this
object. The only required properties are the policy name, which must be unique among existing policies
in the workload, and the new policy’s importance. Supplying a description of the policy is optional. Also
optional are the list of non-redundant virtual servers that should not impact the workload’s availability
status and Workload Element Group objectives overrides. On successful execution, the availability policy
is created and added to the workload and status code 201 is returned with a response body containing a
reference to the new policy. Note that the new policy is not active until the Activate Availability Policy
operation is applied to it.

The URI path must designate an existing Workload Resource Group object and you must have
object-access permission to it. If either of these conditions is not met, status code 404 (Not Found) is
returned. In addition, you must also have permission to the New Availability Policy task as well,
otherwise status code 403 (Forbidden) is returned. Targeting the default Workload Resource Group object
will incur a 400 (Bad Request) response, since the default workload may only ever contain its default
availability policy.

The request body is validated against the “Data model” on page 1349 to ensure that it 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.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object passed in the request URI.
v Action/task permission to the New Availability Policy task.

HTTP status and reason codes

On successful completion, HTTP status code 201 (Created) is returned and the response body is provided
as described in “Response body contents.”

Otherwise, 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 18. Workload resource group management 1355

 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.
60 The targeted workload is the default Workload Resource Group object.
65 The name of the availability policy is not unique within its workload.
66 A virtual server in the request body’s vs-exclusions list does not support
Ensemble Availability Management.
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 ({workload-id}) does not designate an existing
Workload Resource Group object, or the API user does not have object-access
permission to the object.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.

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

Delete Availability Policy

Use the Delete Availability Policy operation to remove an availability policy from a workload. Note that
this operation cannot be performed on an active or default availability policy.

HTTP method and URI

DELETE /api/workload-resource-groups/{workload-id}/availability-policies/{policy-id}

URI variables

Variable Description
{workload-id} Object ID of the Workload Resource Group object whose Availability Policy
object is to be deleted.
{policy-id} Element ID of the Availability Policy object that is to be deleted.

Description
The Delete Availability Policy operation deletes the Availability Policy object specified by {policy-id} from
its workload specified by {workload-id}.

On successful execution, the Availability Policy object is removed from the workload and status code 204
(No Content) is returned without a response body.

The URI path must designate an existing Availability Policy object and you must have object-access
permission to its workload. If this condition is not met, status code 404 (Not Found) is returned.
Additionally, you must have permission to the Delete Availability Policy task. If this condition is not
met, status code 403 (Forbidden) is returned. Targeting a default availability policy will also invoke an
error response, since it cannot be deleted. An active availability policy cannot be deleted as well. To
delete an active policy, first target another availability policy in the workload with the Activate
Availability Policy operation, and then run the Delete Availability Policy operation.

1356 HMC Web Services API

 Level 04a

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object designated by {workload-id}.
v Action/task permission to the Delete Availability Policy task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned without a response body.

Otherwise, 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.
67 The targeted availability policy is a default Availability Policy object.
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 ({workload-id}) does not designate an existing
Workload Resource Group object, or the API user does not have object-access
permission to the object.
63 The element ID in the URI ({policy-id}) does not designate an existing
Availability Policy object in the workload.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.
63 The availability policy to be deleted is currently active or in the progress of
being activated. The operation can be retried after a different policy has been
activated, which causes the activation-status of this policy to be "not-active".

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

Update Availability Policy

Use the Update Availability Policy operation to modify one or more writable properties of an
Availability Policy object

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/availability-policies/{policy-id}

URI variables

Variable Description
{workload-id} Object ID of the workload object to which the target availability policy is
defined.
{policy-id} Element ID of the Availability Policy object that is to be modified.

Chapter 18. Workload resource group management 1357

 Level 04a

Request body contents

The request body is a JSON object containing one or more of the writable fields for an availability policy,
as described in the “Data model” on page 1349. You need to supply only those fields that you want to
modify.

Description
The Update Availability Policy operation updates one or more writable properties of the Availability
Policy object identified by {policy-id}.

On successful execution, the Availability Policy object is updated with the supplied property values and
status code 204 (No Content) is returned without a response body. Notifications for these property
changes are sent asynchronously to this operation.

If the availability policy is active at the time of this request, the Ensemble Availability Management of the
workload’s virtual servers to be dynamically updated without a reactivation of the policy.

The URI path must designate existing workload and Availability Policy objects and you must have
object-access permission to the workload. If either of these conditions is not met, status code 404 (Not
Found) is returned. In addition, you must also have permission to the Availability Policy Details task as
well, otherwise status code 403 (Forbidden) is returned. Targeting a default availability policy will also
invoke an error response, since it is not directly mutable.

The request body is validated against the schema described in the “Request body contents.” If the request
body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation
error encountered.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object designated by {workload-id}.
v Action/task permission to the Availability Policy Details task.

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned without a response body.

Otherwise, 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.
65 The new name given to the availability policy is not unique within its
workload.
67 The targeted performance policy is a default Availability Policy object.
403 (Forbidden) 1 The API user does not have the required permission for this operation.

1358 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object ID in the URI ({workload-id}) does not designate an existing
Workload Resource Group object, or the API user does not have object-access
permission to the object.
63 The element ID in the URI ({policy-id}) does not designate an existing
Availability Policy object in the workload.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.

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

Activate Availability Policy

Use the Activate Availability Policy operation to activate a workload’s availability policy. This may be
any availability policy in the workload, including the default, whose activation-status is "not-active".

HTTP method and URI

POST /api/workload-resource-groups/{workload-id}/availability-policies/{policy-id}/operations/activate

URI variables

Variable Description
{workload-id} Object ID of the workload object to which the target availability policy is
defined.
{policy-id} Element ID of the Availability Policy object that is to be activated.

Description
The Activate Availability Policy operation activates an availability policy identified by {policy-id} in its
workload identified by {workload-id}.

On successful execution, the target policy is active and status code 204 (No Content) is returned without
a response body. Notifications for ensuing property changes are sent asynchronously to this operation.

On successful execution, the activation request completes and status code 204 (No Content) is returned
without supplying a response body. Notifications for ensuing property changes are sent asynchronously
to this operation.

The URI path must designate existing workload and Availability Policy objects and you must have
object-access permission to the workload. If either of these conditions is not met, status code 404 (Not
Found) is returned. In addition, you must also have permission to the Activate Availability Policy task
as well, otherwise status code 403 (Forbidden) is returned. If the target availability policy is already
active, a 409 (Conflict) is returned. Targeting the default workload will also invoke an error response,
since its default availability policy is permanently active.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the workload object designated by {workload-id}.
v Action/task permission to the Activate Availability Policy task.

Chapter 18. Workload resource group management 1359

 Level 04a

HTTP status and reason codes

On successful completion, HTTP status code 204 (No Content) is returned without a response body.

Otherwise, 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.
60 The targeted workload is the default Workload Resource Group object.
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 ({workload-id}) does not designate an existing
Workload Resource Group object, or the API user does not have object-access
permission to the object.
63 The element ID in the URI ({policy-id}) does not designate an existing
Availability Policy object in the workload.
409 (Conflict) 2 The operation cannot be performed because the object designated by the
request URI is currently busy performing some other operation.

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

Ensemble Availability Management reports

Each ensemble, with its set of workloads, contains Ensemble Availability Management components. The
APIs related to actual creation, activation, deletion, etc. of Ensemble Availability Management
components within the object model are contained in the previous sections where the objects are defined.
This subsection describes a special category of Ensemble Availability Management APIs related to
reporting.

Ensemble Availability Management has the ability to generate historical reports, on demand, which are
based on reporting data that it has been saved over time which is related to the Ensemble Availability
Management objects as they existed at those points in time. But since the actual objects involved may
have changed since then, or actually may not even exist now, these reports are being treated differently
than the normal object based APIs.

Note: The Ensemble Availability Management historical reporting data currently goes back up to 36
hours from the current time.

Instead of being object based, all of the Ensemble Availability Management report APIs will be
implemented as availability-management specific operations, that request an on-demand report be
generated and returned to the caller. They will take in the query parameters in a request block, and
essentially do the queries into the historical reporting database to generate a custom report for that caller.

The Ensemble Availability Management report APIs are interrelated, in that certain properties retrieved
from one report can be used as input to generate other reports. One could visualize drilling down for
more detailed information about a specific item found within a previous report; just as one might
traverse these same reports when using the Hardware Management Console user interface.

The following chart shows how the reports are related, along with an indication of which -report-id
properties (explained in more detail below the chart) would be used from one report to generate the next

1360 HMC Web Services API

 Level 04a

one via the APIs. The actual descriptions of these reports, how to generate them via the APIs, and the
API properties, are fully described following this introduction. Therefore, it is suggested this chart be
referred to again after reading through and understanding each of them individually.

Workload Resource Groups

Report
workload-report-id

Workload Resource Groups

Availability Status Report
workload-report-id
object-report-id
Availability Status Report
workload-report-id
element-report-id
Virtual Servers Report
workload-report-id
virtual-server- report-id

Figure 719. Relationship between reports and the properties used

The special properties, all containing names ending in -report-id, are the actual query keys into the
internal reporting system. If following the drill down approach, one would never have to actually know
what those key values are. Once they are returned as response properties from one report, the values in
them can just be used again as-is for input request properties to subsequent reports concerning those
same items (i.e. for the same virtual server or workload or hypervisor or service class).

Furthermore, they should be considered durable in that, for the same items, they do not change across
invocations of the reporting APIs. For example, once the workload-report-id for a particular workload is
obtained, it can be kept around and used over and over again when trying to generate subsequent
reports involving that particular workload, regardless of the time interval of the report. In other words,
once known for a particular item, they will remain constant, and so it is not necessary to start drilling
again from the top every time to obtain a particular sub-report that requires any of those values as input
request block properties.

Note: As a general rule, the reporting system internal keys are intentionally not documented as to what
specific information is actually used to index the data for internal retrieval; so that there would be no
client impact should the type of data used to internally index the data change in the future. But in the
case of virtual-server-report-id and object-report-id (Virtual Servers Report), where the currently in use
key types are unlikely to change in the future, the keys are being documented in order to provide an
additional convenient way to obtain those key values directly from currently existing Workload objects.
This allows a shortcut for calling certain select sub-reports directly, without having to obtain the key
values via other calls to higher level reports.
v virtual-server-report-id: the value of the object-id property of the Virtual Server object.
v object-report-id: the value of the object-id property of the workload element group or Virtual Server
object.

For example, if there is a Workload in the ensemble for which an Availability Status Report is desired, the
API caller would be able to get it directly by providing the value from its object-id property as the input
request workload-report-id property (as opposed to drilling through the Workload Resource Groups
Report to get the workload-report-id from the reporting system).

Chapter 18. Workload resource group management 1361

 Level 04a

As mentioned above concerning the -report-id values in general, though, the workload-report-id values
obtained from the reports are durable over time, so if the calling application has a design such that it has
already drilled down and saved these values for future use anyway, a direct call to the sub-report could
be made using it from there as well.

The -report-id values are consistent between the performance management reports and Ensemble
Availability Management. This allows for performance management and Ensemble Availability
Management report data to be combined using -report-id values to generate combined workload
performance and Ensemble Availability Management reports.

Generate Workload Resource Groups Report (Ensemble Availability

Management)
Use the Generate Workload Resource Groups Report of Ensemble Availability Management operation to
create a custom on-demand Workload Resource Groups Report for a requested time period, based on
historical Ensemble Availability Management data that was retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/availability-management/operations/generate-workload-resource
-groups-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a workload resource groups report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.

1362 HMC Web Services API

 Level 04a

Field name Type Description

report-workloads Array of Array of nested workload-report-entry objects described in the next table.
objects

Each nested workload-report-entry object contains the following fields:

Table 460. Format of a workload-report-entry object
Field name Type Description
workload-name String The displayable name of the workload resource group.
workload-report-id String The object-id property of the workload object represented by this entry.

Because the report contains historical data, the workload object with this
object ID may no longer exist.
workload-object-uri String/URI The object-uri property of the workload object represented by this entry.

Because the report contains historical data, the workload object with this
object URI may no longer exist.
workload-object-id String The object-id property of the workload object represented by this entry.

Because the report contains historical data, the workload object with this
object ID may no longer exist.
availability-policy- String The name (displayable) of the availability policy that was active during this
name reporting interval.
Note: If more than one availability policy was activated over the span of
this reporting interval, only the name of the last one activated will be
returned here. See the multi-policy-activations field to determine whether
there was more than one.
availability-policy- String/URI The element-uri of the availability policy that was active during this
element-uri reporting interval.

Because the report contains historical data, the workload object with this
element-uri may no longer exist.
availability-policy- String The element-id property of the Availability Policy object represented by this
element-id entry.

Because the report contains historical data, the workload object with this
element-id may no longer exist.
most-severe- String/ The most severe avail-status value recorded for the workload over this
availability-status Enum reporting interval.
multi-policy- Boolean Indicates whether more than one availability policy was activated over the
activations span of this reporting interval (true if more than one, false if not more than
one).
avail-status-data- Array of Array of nested avail-status-data-point objects, described in the next table.
points objects

Each nested avail-status-data-point object contains the following fields:

Chapter 18. Workload resource group management 1363

 Level 04a

Table 461. Format of nested avail-status-data-point object

Field name Type Description
time Integer Standard date/time value indicating the date and time that this availability
status value was recorded.

The standard time value is defined as the number of elapsed milliseconds

after midnight January 1, 1970.
avail-status String/ The avail-status value of the workload at the recorded time. See the “Data
Enum model” on page 1219 for more details about the valid values of this property.

Description
This operation generates an Ensemble Availability Management Workload Resource Groups Report. For a
requested interval, designated by a start date/time and duration, it will generate and return a list of all
workloads for which there is historical Ensemble Availability Management reporting information
available. Additionally, for each workload, it also returns the active availability policy at that time and an
availability health indication (availability status) over that interval. Please refer to the list of returned
fields in the previous tables for a full list of all data that is returned in this report for each workload.

It should be noted that the returned workload-object-id for each returned workload can be used as input
in the request bodies for further availability reports defined in this section that can be generated to dig
deeper into other Ensemble Availability Management reporting data for a specific workload.

If there is no reporting data available for the requested time interval, an empty response object will be
provided and the operation completes successfully.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Workloads Resource Groups Report task.

HTTP status and reason codes

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.

Reason
HTTP Status Code Code Description
400 (Bad Request) Various Errors were detected during common request validation. See section “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform the requested operation (Action/task permission
failure).
404 (Not Found) 1 An object with object-id {ensemble-id} does not exist on HMC or API user does
not have object-access permission for the identified ensemble.

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

1364 HMC Web Services API

 Level 04a

Example HTTP interaction

POST /api/ensembles/12345678-1234-1234-1234-123456789000/availability-management/operations/generate-
workload-resource-groups-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 30
}

Figure 720. Generate Workload Resource Groups Report (Ensemble Availability Management): Request

Generate Workload Resource Group Availability Status Report

Use the Generate Workload Resource Group Availability Status Report of an Ensemble Availability
Management operation to create a custom on-demand availability status report for a specific workload
over a requested time period. It is based on historical Ensemble Availability Management data that was
retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/availability-management/operations/generate-workload-resource
-group-availability-status-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a report.

Request body contents

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

Field name Type Rqd/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated.

The standard time value is defined as the number of elapsed

milliseconds after midnight January 1, 1970.
report-interval- Integer Required The length, in minutes, of the interval this report should cover
duration (from the report-interval-start-time). Value must be greater than 0.
workload-report-id String Required An identifier used by the Ensemble Availability Management
reporting structure to keep track of reporting data for the specific
workload this entry represents.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.

Chapter 18. Workload resource group management 1365

 Level 04a

Field name Type Description

report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The name (displayable) of the workload this report covers.
workload-report-id String An identifier used by the Ensemble Availability Management reporting
structure to keep track of reporting data for the specific workload, named in
workload-name, this report covers.
workload-object-uri String/URI The object-uri property of the workload object represented by this entry.

Because the report contains historical data, the workload object with this
object-uri may no longer exist.
policy-activation- Array of Array of nested policy-activation-record objects described in Table 462.
records objects
If none, an empty array will be returned for this field.
availability-status- Array of Array of nested availability-status-record objects described in Table 463
records objects
If none, an empty array will be returned for this field.

Each nested policy-activation-record object contains the following fields:

Table 462. Format of a policy-activation-record object
Field name Type Description
time Integer Standard date/time value indicating the date and time that the availability
policy was activated. The standard time value is defined as the number of
elapsed milliseconds after midnight January 1, 1970.
availability-policy- String The name (displayable) of the availability policy that was activated.
name
availability-policy- String/URI The element-uri property of the availability policy that was activated.
element-uri
Because the report contains historical data, the Availability Policy object with
this element-uri may no longer exist.
availabilty-policy- Integer (1-n) The revision property of the availability policy that was activated.
revision

Each availability-status-record object contains the following fields:

Table 463. Format of availability-status-record object
Field name Type Description
class String The class of the object. Values:
Enum v "workload-resource-group": Entity is a workload resource group.
v "workload-element-group": Entity is a workload element group.
v "virtual-server": Entity is a virtual server.
entity-name String The name of the workload, workload element group, virtual server, or
Enum availability policy represented by the entry.

1366 HMC Web Services API

 Level 04a

Table 463. Format of availability-status-record object (continued)

Field name Type Description
object-uri String/URI The object-uri property of the workload, workload element group, or Virtual
Server object represented by this entry.

Because the report contains historical data, the object with this object-uri
may no longer exist.
object-report-id String An identifier used by the Ensemble Availability Management reporting
structure to keep track of reporting data for the specific workload, workload
element group, or virtual server.
time Integer Standard date/time value indicating the date and time that this availability
status change took place.

The standard time value is defined as the number of elapsed milliseconds

after midnight January 1, 1970.
availability-policy- String The name (displayable) of the availability policy that was active when this
name availability status change was reported.

Value is always null for entities whose class is "virtual-server".

availability-policy- String/URI The element-uri property of the availability policy that was active when this
element-uri availability status change was reported.

Because the report contains historical data, the Availability Policy object with
this element-uri may no longer exist.

Value is always null for entities whose class is "virtual-server".

availability-policy- Integer (1-n) The revision property of the availability policy that was active when this
revision availability status change was reported.

Value is always null for entities whose class is "virtual-server".

parents Array of Array of nested parent objects, described in the next table, listing the parent
objects objects of this entity. These parents may be affected by the availability status
change described by this record (and therefore have their own availability
status change record in the report).

If none, an empty array will be returned for this field.

Value is always null for entities whose class is "workload-resource-group".

old-avail-status String The avail-status value of the object before this change.
Enum
new-avail-status String The avail-status value of the object after this change.
Enum
avail-status-impact- Boolean The avail-status value of the object was excluded from impacting the
exclusion workload availability status. This condition occurs when an object is selected
to have its workload availability status impact ignored in an availability
policy.

Value is always false if the class is "workload-resource-group" or

"workload-element-group" or if the class is "virtual-server" and the
parent-class is "workload-element-group".

Chapter 18. Workload resource group management 1367

 Level 04a

Table 463. Format of availability-status-record object (continued)

Field name Type Description
reason String The reason for the new availability status. Values:
Enum v "at-least-preferred-available": The number of available virtual servers in
the workload element group is greater than or equal to its preferred
available objective.
v "fewer-than-preferred-available": The number of available virtual servers
in the workload element group is fewer than its preferred available
objective.
v "at-least-minimum-available": The number of available virtual servers in
the workload element group is greater than or equal to its minimum
available objective.
v "fewer-than-minimum-available": The number of available virtual servers
in the workload element group is fewer than its minimum available
objective.
v "status-is-exposed": Virtual server operating status indicates the element is
exposed.
v "status-is-critical": Virtual server operating status indicates the element is
critical.
v "status-is-notavailable": Virtual server operating status indicates the
element is not available.
v "status-is-available": Virtual server operating status indicates the element
is available.
v "gpmp-is-exposed": GPMP operating status indicates the element is
exposed.
v "gpmp-is-available": GPMP operating status indicates the element is
available.
v "member-is-exposed": Member operating status indicates the element is
exposed.
v "member-is-critical": GPMP operating status indicates the element is
critical.
v "member-is-available": GPMP operating status indicates the element is
available.
v "entity-was-created": The entity was created.
v "entity-was-deleted": The entity was deleted.
v "entity-was-updated": The entity was updated.
v "virtual-server-deactivated": The virtual server was deactivated.
v "virtual-server-status-changed": The virtual server's operating status
changed.
v "virtual-server-not-supported": The virtual server is not supported by
Ensemble Availability Management.
v "policy-activated": A new policy was activated for the workload.

Each nested policy-activation-record object contains the following fields:

1368 HMC Web Services API

 Level 04a

Table 464. Format of a parent object

Field name Type Description
name String The name of the parent entity whose availability status may be affected by
Enum this entity’s availability status change.

A parent entity is defined by the name, URI, and class properties. The
parent object’s URI property and the time property of the
availability-status-record object that contain the parent can be used to find
the availability-status-record for the parent (the record whose object-uri
matches this parent object’s URI and whose time matches the record’s time).

If the record is of class "virtual-server", the parent entity may be the

workload in which the virtual server is a direct member (the target of the
report) or the workload element group in which the virtual server is a
member.

If the record is of class "workload-element-group", the parent entity is the

workload in which the workload element group is a member (the target of
the report).
object-uri String/URI The object-uri property of the parent entity.
class String The class property of the parent entity. Values:
Enum v "workload-resource-group": Entity is a workload resource group.
v "workload-element-group": Entity is a workload element group.

Description
In general, an availability status report shows information about the availability status changes for the
workload and its elements. For each availability status change within the workload, the report lists the
object to which the change occurred, why the change occurred, and what parent object(s) may be affected
by the availability status change.

Multiple availability status updates resulting from a workload element availability status change will
result in all related records being recorded with the same time. This time link and the parent properties
allow one to link records together for reporting. For example:

old-availability- new-availability-
time object-uri class parent-uri status status
1316101902 <wl1-uri> workload null critical available
1316101902 <eg1-uri> workload- <wl1-uri> critical exposed
element-group
1316101902 <vs1-uri> virtual-server <eg2-uri> exposed available
1316101902 <vs1-uri> virtual-server <eg2-uri> exposed available

If there is no reporting data available for the requested time interval, an empty response object will be
provided and the operation completes successfully. If there are no availability status changes to report,
then the availability-status-records array will be returned as an empty array.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble.
v Action/task permission to the Availability Status Event Report task.

Chapter 18. Workload resource group management 1369

 Level 04a

HTTP status and reason codes

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.

Reason
HTTP Status Code Code Description
400 (Bad Request) Various Errors were detected during common request validation. See section “Common
request validation reason codes” on page 41 for a list of the possible reason
codes.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the
required authority to perform the requested operation (Action/task permission
failure).
404 (Not Found) 1 An object with object-id {ensemble-id} does not exist on HMC or API user does
not have object-access permission for the identified ensemble.

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/ensembles/12345678-1234-1234-1234-123456789000/availability-management/operations/ generate-

workload-resource-group-availability-status-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group"
}

Figure 721. Generate Workload Resource Group Availability Status Report: Request

Generate Virtual Servers Report (Ensemble Availability Management)

Use the Generate Virtual Servers Report of an Ensemble Availability Management operation to create a
custom on-demand report that shows all virtual servers that were members of a particular workload over
a requested time period for which reporting data is available. The report is based on historical
performance management data that was retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/availability-management/operations/generate-virtual-servers-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting a virtual server report.

Request body contents

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

Field name Type Req/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.

1370 HMC Web Services API

 Level 04a

Field name Type Req/Opt Description

report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
workload-report-id String Required The identifier used by the Ensemble Availability Management
reporting to keep track of reporting data for the specific workload
for which the report is being requested.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report
for this same interval.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.
report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the Ensemble Availability Management reporting
structure to keep track of reporting data for the specific workload, named in
the workload-name field.
report-virtual- Array of Array of nested virtual-server-report-entry objects, described in the next
servers objects table.

Each nested virtual-server-report-entry object contains the following fields:

Field name Type Description

virtual-server-name String The displayable name of the virtual server.
virtual-server- String An identifier used by the Ensemble Availability Management reporting
report-id structure to keep track of reporting data for the specific virtual server,
because virtual server names by themselves are not unique.
most-severe- String The most severe avail-status value recorded for the virtual server over the
availability-status Enum specified reporting interval. See the “Data model” on page 1219 for more
details about the valid values of this property.
avail-status-impact- Boolean The most-severe-availability-status value was excluded from impacting the
exclusion workload availability status. This condition occurs when a virtual server is
selected to have its workload availability status impact ignored in an
availability policy.

Chapter 18. Workload resource group management 1371

 Level 04a

Description
The Generate Virtual Servers Report operation generates an Ensemble Availability Management report
that contains the following information for a specific workload over the requested time interval:
v A list of all virtual servers that were members in that specific workload for which historical Ensemble
Availability Management reporting information is available
v For each virtual server:
– The unique availability reporting identifier for the virtual server
– The name and unique availability reporting identifier of the hypervisor under which the virtual
server was running
– An indication of whether the virtual server was active over the reporting interval.

If there is no reporting data available for the requested time interval, an empty response object will be
provided and the operation completes successfully.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Virtual Servers Report task.

HTTP status and reason codes

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

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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

Example HTTP interaction

{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group"
}

Figure 722. Generate Virtual Servers Report: Request

1372 HMC Web Services API

 Level 04a

Generate Availability Status Report

Use the Generate Availability Status Report of an Ensemble Availability Management operation to create
a custom on-demand report showing the availability status of a workload, workload virtual server, or
workload element group over a requested time period for which reporting data is available. It is based on
historical Ensemble Availability Management data that was retained over that time period.

HTTP method and URI

POST /api/ensembles/{ensemble-id}/availability-management/operations/generate-availability-status-report

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object for which you are
requesting an availability status report.

Request body contents

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

Field name Type Req/Opt Description

report-interval- Integer Required Standard date/time value indicating the requested starting date and
start-time time of the report to be generated. The standard time value is
defined as the number of elapsed milliseconds after midnight on 1
January 1970.
report-interval- Integer Required The length, in minutes, of the interval this report covers, starting
duration from the value specified for the report-interval-start-time field. This
value must be greater than 0.
workload-report-id String Required The identifier used by the Ensemble Availability Management
reporting to keep track of reporting data for the specific workload
for which the report is being requested.
Note: This value is the same as one of the workload-report-id
values that are returned in the Workload Resource Groups Report,
Virtual Servers Report, or Workload Resource Groups Availability
Status Report for this same interval.
element-report-id String Required The identifier used by the Ensemble Availability Management
reporting to keep track of reporting data for the specific workload
element for which the report is being requested or null if the report
covers a workload and not a workload element.
Note: This value is the same as one of the virtual-server-report-id
values that are returned in the Virtual Servers Report, or the
object-report-id returned in the Workload Resource Groups
Availability Status Report for this same interval.

Response body contents

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

Field name Type Description

report-interval- Integer Standard date/time value indicating the requested starting date and time of
start-time the report to be generated. The standard time value is defined as the number
of elapsed milliseconds after midnight on 1 January 1970.
Note: The returned value might differ from the requested time if no report
data was available at the requested time, but data was available starting
later within the requested interval.

Chapter 18. Workload resource group management 1373

 Level 04a

Field name Type Description

report-interval- Integer The length, in minutes, of the interval this report covers, starting from the
duration value specified for the report-interval-start-time field. This value must be
greater than 0.
Note: The returned value might differ from the requested duration if report
data was not available for the entire requested interval, but data was
available for a shorter duration within that same requested interval.
workload-name String The displayable name of the workload resource group.
workload-report-id String An identifier used by the Ensemble Availability Management reporting
structure to keep track of reporting data for the specific workload, named in
the workload-name field.
element-name String The displayable name of the workload element this report covers or null if
the report covers a workload and not a workload element.
element-report-id String An identifier used by the Ensemble Availability Management reporting
structure to keep track of reporting data for the specific workload element,
specified by element-name, or null if the report covers a workload and not a
workload element.
avail-status-data- Array of Array of nested avail-status-data-point objects, described in the next table.
points objects

Each nested avail-status-data-point object contains the following fields:

Field name Type Description

time Integer Standard date/time value indicating the requested starting date and time
that this value was recorded. The standard time value is defined as the
number of elapsed milliseconds after midnight on 1 January 1970.
avail-status String The avail-status value of the workload at the recorded time. See the “Data
Enum model” on page 1219 for more details about the valid values of this property.

Description
The Generate Availability Status Report operation generates an Ensemble Availability Management
report that contains the following information for a specific workload over the requested time interval:
v A list of all virtual servers that were members in that specific workload for which historical Ensemble
Availability Management reporting information is available
v For each virtual server:
– The unique availability reporting identifier for the virtual server
– The name and unique availability reporting identifier of the hypervisor under which it was running
– An indication of whether the hypervisor was active over the reporting interval.

If there is no reporting data available for the requested time interval, an empty response object will be
provided and the operation completes successfully.

Authorization requirements
This operation has the following authorization requirements:
v Object-access permission to the ensemble object passed in the request URI.
v Action/task permission to the Virtual Servers Report task.

HTTP status and reason codes

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

1374 HMC Web Services API

 Level 04a

Otherwise, 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.
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 ({ensemble-id}) does not designate an existing
Ensemble object, or the API user does not have object access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/availability-management/operations/generate-
virtual-servers-report
{
"report-interval-start-time": 1296149252662,
"report-interval-duration": 60,
"workload-report-id": "Payroll Workload Resource Group"
}

Figure 723. Generate Virtual Servers Report: Request

Get Performance Management Velocity Level Range Mappings

Use the Get Performance Management Velocity Level Range Mappings operation to retrieve the
numeric ranges that zManager uses to calculate the actual performance velocity for a service class. Each
range of numbers is mapped to one of the valid descriptive values that are used in performance
management reports for service classes that have a velocity rather than discretionary performance goal.

HTTP method and URI

GET /api/ensembles/{ensemble-id}/performance-management/velocity-level-range-mappings

In this request, the URI variable {ensemble-id} is the object ID of the ensemble object.

Response body contents

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

Field name Type Description

performance- Array of An array of nested velocity-level-range-mapping-entry objects.
management-velocity- objects
level-range-mappings

Each nested velocity-level-range-mapping-entry object contains the following fields:

Chapter 18. Workload resource group management 1375

 Level 04a

Field name Type Description

low-boundary Integer This value defines the low boundary (inclusive) that defines this specific
range of calculated velocity numbers.
high-boundary Integer This value defines the upper boundary (inclusive) that defines this specific
range of calculated velocity numbers.
velocity-level String The descriptive velocity level that this numeric range represents. Possible
Enum values are: "fastest", "fast", "moderate", "slow", and "slowest".

Description
The Get Performance Management Velocity Level Range Mappings operation retrieves the list of
numeric ranges that zManager uses to calculate the actual performance for a service class that has a
performance goal of the "velocity" (rather than "discretionary") type. Each range of numbers is mapped
to one of the valid descriptive values that are used in performance management reports; these descriptive
values are: "fastest", "fast", "moderate", "slow", and "slowest".

For service classes with a velocity performance goal, zManager:

1. Calculates a numeric value for actual performance
2. Compares the calculated numeric value to a predefined set of ranges, one range for each of the
descriptive velocity-level values
3. Substitutes the appropriate descriptive value to present in performance management reports.
This substitution occurs because the actual performance is not significantly different between numbers
that are close together; it is more meaningful to define a smaller set of velocity levels that describe the
performance.

Through the Get Performance Management Velocity Level Range Mappings API and the service class
metrics described in “Workload service class data metrics group” on page 115, you can calculate raw
velocity numbers and compare and substitute the performance level using the same descriptive velocity
levels that zManager uses in its performance management reports.

“Response body contents” on page 1375 describes the full list of data that is returned for the Get
Performance Management Velocity Level Range Mappings operation. An error response is returned if
the targeted ensemble does not exist or if you do not have the requirements listed in “Authorization
requirements.”

Authorization requirements
This operation has the following authorization requirement:
v object-access permission to the ensemble object passed in the request URI.

HTTP status and reason codes

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

Otherwise, 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.

1376 HMC Web Services API

 Level 04a

HTTP error status Reason

code code Description
404 (Not Found) 1 The object ID in the URI ({ensemble-id}) does not designate an existing
ensemble object, or the API user does not have object-access permission to
the object.

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/ensembles/12345678-1234-1234-1234-123456789000/performance-management/
velocity-level-range-mappings

Figure 724. Get Performance Management Velocity Level Range Mappings: Request

Inventory service data

Information about the Workload Resource Groups managed by the HMC and the associated Performance
Policies can be optionally included in the inventory data provided by the Inventory Service.

Inventory entries for workload and associated policy objects are included in the response to the Inventory
Service's Get Inventory operation when the request specifies (explicitly by class, implicitly via a
containing category, or by default) that objects of class "workload-resource-group" are to be included.
Information for a particular workload (and associated policies) is included only if the API user has
object-access permission to that object.

For each workload to be included, the inventory response array includes the following:
v An array entry for the workload object itself. This entry is a JSON object with the same contents as is
specified in the response body contents section for “Get Workload Resource Group Properties” on page
1226. That is, the data provided is the same as would be provided if a Get Workload Resource Group
Properties operation were requested targeting this object.
v An array entry for each policy associated with the workload. For each such policy, an entry is included
that is a JSON object with the same contents as specified in the response body contents section of “Get
Performance Policy Properties” on page 1259. As a result, the data provided is the same as would be
obtained if a Get Performance Policy Properties operation were requested for each policy listed by a
List Performance Policies operation targeting the workload.

The array entry for a workload object will appear in the results array before entries for associated
performance policies.

Sample inventory data

The following fragment is an example of the JSON object that would be included in the Get Inventory
response to describe a single workload (named “Online Ordering”) that defines a custom performance
policy (“Prime shift”) in addition to the default policy. These objects would appear as a sequence of array
entries in the response array:

Chapter 18. Workload resource group management 1377

 Level 04a

{
"active-perf-policy": {
"activation-status": "active",
"element-id": "cc79445a-95e4-11e0-b6ef-000c29bb873c",
"element-uri": "/api/workload-resource-groups/cc79fa6c-95e4-11e0-b6ef-000c29bb873c
/performance-policies/cc79445a-95e4-11e0-b6ef-000c29bb873c",
"name": "Prime shift"
},
"category": "Retail Operations",
"class": "workload-resource-group",
"custom-perf-policies": [
{
"activation-status": "active",
"element-id": "cc79445a-95e4-11e0-b6ef-000c29bb873c",
"element-uri": "/api/workload-resource-groups/cc79fa6c-95e4-11e0-b6ef-000c29bb873c
/performance-policies/cc79445a-95e4-11e0-b6ef-000c29bb873c",
"name": "Prime shift"
}
],
"default-perf-policy": {
"activation-status": "not-active",
"element-id": "cc7b38dc-95e4-11e0-b6ef-000c29bb873c",
"element-uri": "/api/workload-resource-groups/cc79fa6c-95e4-11e0-b6ef-000c29bb873c
/performance-policies/cc7b38dc-95e4-11e0-b6ef-000c29bb873c",
"name": "Default"
},
"description": "Workload Resource Group for managing the online ordering application.",
"is-default": false,
"name": "Online Ordering",
"object-id": "cc79fa6c-95e4-11e0-b6ef-000c29bb873c",
"object-uri": "/api/workload-resource-groups/cc79fa6c-95e4-11e0-b6ef-000c29bb873c",
"parent": "/api/ensembles/890b6df2-93a4-11e0-887c-000c29bb873c",
"perf-activation-node-count": 0,
"perf-activation-status": "active"
},
{
"activation-status": "active",
"class": "performance-policy",
"created-by": "ENSADMIN",
"created-date": 1307987073673,

Figure 725. Workload Resource Group: Sample inventory data (Part 1)

1378 HMC Web Services API

 Level 04a

"custom-service-classes": [
{
"business-importance": "highest",
"classification-rule": {
"filter": {
"operation": "string-match",
"type": "virtual-server-name",
"value": "OOWS(\\*)"
},
"type": "rule"
},
"description": "",
"goal-type": "velocity",
"name": "Web servers",
"type": "server",
"velocity": "fast"
},
{
"business-importance": "highest",
"classification-rule": {
"filter": {
"operation": "string-match",
"type": "virtual-server-name",
"value": "OODB(\\*)"
},
"type": "rule"
},
"description": "",
"goal-type": "velocity",
"name": "DB Servers",
"type": "server",
"velocity": "fastest"
}
],

Figure 726. Workload Resource Group: Sample inventory data (Part 2)

Chapter 18. Workload resource group management 1379

 Level 04a

"default-service-class": {
"business-importance": "medium",
"classification-rule": {
"filter": {
"operation": "string-match",
"type": "(\\*)",
"value": "(\\*)"
},
"type": "rule"
},
"description": "The default workload performance policy service class.",
"goal-type": "velocity",
"name": "Default",
"type": "server",
"velocity": "moderate"
},
"description": "Performance policy for prime shift operatoin",
"element-id": "cc79445a-95e4-11e0-b6ef-000c29bb873c",
"element-uri": "/api/workload-resource-groups/cc79fa6c-95e4-11e0-b6ef-
000c29bb873c/performance-policies/cc79445a-95e4-11e0-b6ef-000c29bb873c",
"importance": "highest",
"is-default": false,
"last-activated-by": "DBUGGER",
"last-activation-completed-date": 1307991376227,
"last-activation-requested-date": 1307991376226,
"last-modified-by": "ENSADMIN",
"last-modified-date": 1307987073673,
"name": "Prime shift",
"parent": "/api/workload-resource-groups/cc79fa6c-95e4-11e0-b6ef-000c29bb873c",
"revision": 1
},
{
"activation-status": "not-active",
"class": "performance-policy",
"created-by": "",
"created-date": -1,
"custom-service-classes": [],

Figure 727. Workload Resource Group: Sample inventory data (Part 3)

1380 HMC Web Services API

 Level 04a

"default-service-class": {
"business-importance": "medium",
"classification-rule": {
"filter": {
"operation": "string-match",
"type": "(\\*)",
"value": "(\\*)"
},
"type": "rule"
},
"description": "The default workload performance policy service class.",
"goal-type": "velocity",
"name": "Default",
"type": "server",
"velocity": "moderate"
},
"description": "The default workload performance policy",
"element-id": "cc7b38dc-95e4-11e0-b6ef-000c29bb873c",
"element-uri": "/api/workload-resource-groups/cc79fa6c-95e4-11e0-b6ef-000c29bb873c
/performance-policies/cc7b38dc-95e4-11e0-b6ef-000c29bb873c",
"importance": "medium",
"is-default": true,
"last-activated-by": "DBUGGER",
"last-activation-completed-date": 1307991361463,
"last-activation-requested-date": 1307991361463,
"last-modified-by": "",
"last-modified-date": -1,
"name": "Default",
"parent": "/api/workload-resource-groups/cc79fa6c-95e4-11e0-b6ef-000c29bb873c",
"revision": 1
}

Figure 728. Workload Resource Group: Sample inventory data (Part 4)

Chapter 18. Workload resource group management 1381

 Level 04a

1382 HMC Web Services API

 Level 04a

Part 5. Appendixes

© Copyright IBM Corp. 2017, 2018 1383

 Level 04a

1384 HMC Web Services API

 Level 04a

Appendix A. XML document structure of a performance policy

To import a performance policy for a workload resource group through the HMC Workload Resource
Group Details task or the Import Performance Policy operation, you must first create an XML document
that defines the policy elements. Use this topic to create a properly structured XML document to import.

The XML document starts with the WorkloadPerformancePolicy element, which contains all the elements
of a workload resource group performance policy. The following sample shows the correct structure of
the major elements in the WorkloadPerformancePolicy element:
<WorkloadPerformancePolicy
xmlns=”http://www.ibm.com/PPM/WorkloadPerformancePolicy”>
<Name> SampleWorkloadPerformancePolicy </Name>
<Description> Sample performance policy for a workload </Description>
<Version> 3.00.00 </Version>
<UI> PPM Editor </UI>
<WorkloadImportance> High </WorkloadImportance>
<ServiceClasses> ... </ServiceClasses>
</WorkloadPerformancePolicy>

The following table describes the major elements in the WorkloadPerformancePolicy element.
Table 465. Performance policy XML elements
Element name Rqd/Opt Description
Name Required The display name specified for the performance policy. All Name
elements must be up to 64 characters long, consisting of alphanumeric
characters, blanks, periods, underscores, or dashes. Names must start
with an alphabetic character and end with an alphabetic character,
numeric character, underscore, period, or dash. Names must be unique
to other existing performance policies in the workload resource group.
Description Optional Arbitrary text describing the performance policy in up to 256 characters.
Version Required A version number, a release number, and a level number, which are each
separated by a period. The version number must be between 1 and 99.
The release and level numbers must be between 0 and 99.
UI Required The name of the product that last edited the XML document. UI has the
same length and content restrictions as the Name element.
WorkloadImportance Required The importance value assigned to the performance policy, which is one
of the following: highest, high, medium, low, or lowest
ServiceClasses Required The ServiceClasses element contains one or more service classes, as
defined in “XML structure of a ServiceClasses element.”

XML structure of a ServiceClasses element

The ServiceClasses element contains one or more ServiceClass elements that set the priority of and
classify resources within a performance policy. A service class is a group of virtual servers that has the
same service goals or performance objectives, resource requirements, or availability requirements.

The following sample shows the structure of a ServiceClass element within the ServiceClasses element:
<ServiceClasses>
<ServiceClass>
<Name> Web Hot </Name>
<Description> Critical web transactions </Description>
<Type> Server </Type>

© Copyright IBM Corp. 2017, 2018 1385

 Level 04a

<Goal> ... </Goal>

<RuleBuilderElement> ... </RuleBuilderElement>

</ServiceClasses>
</ServiceClasses>

ServiceClass elements are positional. After you import and activate the policy, zManager searches service
classes from low-ordered to high-ordered service class during classification to find a match.

The following table describes the elements in the ServiceClass element.

Table 466. Performance policy XML: Elements in a ServiceClass element
Element name Rqd/Opt Description
Name Required The name specified for the service class. The Name element must be a
valid identifier up to 64 characters long, consisting of alphanumeric
characters, blanks, periods, underscores, or dashes. Names must start
with an alphabetic character and end with an alphabetic character,
numeric character, underscore, period, or dash. Names must be unique to
other existing service classes in the performance policy.
Description Optional Arbitrary text describing the service class in up to 256 characters.
Type Required This element identifies the resource associated with the service class. The
Type value must be server to target specific virtual servers.
Goal Required The Goal element identifies the type of performance goal required for
this service class, as described in “XML structure of a Goal element.”
RuleBuilderElement Required The RuleBuilderElement contains the classification attributes for the
service class, which are described in “XML structure of a
RuleBuilderElement ” on page 1387.

XML structure of a Goal element

The Goal element identifies the type of performance goal, which is either a velocity goal or a
discretionary goal. If you code the Velocity element, you also need to code the Importance element. The
following samples show how to code the XML for each type of goal:
<Goal>
<Discretionary/>
</Goal>

or
<Goal>
<Velocity>
<Importance> Medium </Importance>
<Level> Fast </Level>
</Velocity>
</Goal>

For every Goal element, you must code either the Discretionary element or the Velocity element. If you
code the Velocity element, you must code the Importance and Level elements as described in the
following table.
Table 467. Performance policy XML: Elements required for a Velocity element
Element name Rqd/Opt Description
Importance Required This field identifies the business importance level assigned to the service
class, which must be one of the following: highest, high, medium, low,
or lowest

1386 HMC Web Services API

 Level 04a

Table 467. Performance policy XML: Elements required for a Velocity element (continued)
Element name Rqd/Opt Description
Level Required This field identifies the velocity goal value of the service class, which
must be one of the following: fastest, fast, moderate, slow, or slowest

XML structure of a RuleBuilderElement

The RuleBuilderElement represents a classification rule for the service class. Each service class within a
performance policy has one or more classification rules that identify how hardware or software elements
of a workload resource group are associated with the service class. So each ServiceClass element can
have one or more RuleBuilderElements.

Each classification rule consists of one or more conditions that enable zManager to associate a service
class to incoming work. A condition is a group containing a filter type, filter operator and filter value. To
fully represent a classification rule, a RuleBuilderElement consists of one or more Filter elements, each
containing one FilterType, one FilterOperation, and one FilterValue element.

Classification rules within a service class are positional. Assign any RuleBuilderElement containing a
wildcard filter value to a high-order service class, and assign any RuleBuilderElement containing a
specific filter value to a low-order service class.

The following sample shows the XML structure of a simple RuleBuilderElement:

<RuleBuilderElement>
<RuleBuilderElementType> Rule </RuleBuilderElementType>
<Filter>
<FilterType> Virtual Server Name </FilterType>
<FilterOperation> stringMatch </FilterOperation>
<FilterValue> WebSales* </FilterValue
</Filter>
</RuleBuilderElement>

This RuleBuilderElement classifies all virtual servers with the string “WebSales” in the name as resources
to be managed according to the goals set for the service class.

All RuleBuilderElements must begin with RuleBuilderElementType, which identifies the type of
classification rule as one of the following:
Rule
Defines a simple filter that resolves to true or false based on its filter pattern compared to a specified
virtual server attribute.
And
Defines a complex set of two rules; during classification, both of the two rules imbedded within this
RuleBuilderElement must be true for the virtual server to be managed according to the goals for this
service class
Or Defines a complex set of two rules; during classification, only one of the two rules imbedded within
this RuleBuilderElement must be true for the virtual server to be managed according to the goals for
this service class

If you code a RuleBuilderElementType value of and or or, exactly two RuleBuilderElements must be
nested inside this RuleBuilderElement object so they can be logically compared. The following sample
shows nested RuleBuilderElements for a complex set of rules that are equivalent to the expression Rule
1 and (Rule 2 or Rule 3):
<RuleBuilderElement>

<RuleBuilderElementType>And</RuleBuilderElementType>

Appendix A. XML document structure of a performance policy 1387

 Level 04a

<RuleBuilderElement>
<RuleBuilderElementType>Rule</RuleBuilderElementType>
<Filter> ... filters for rule 1 ... </Filter>
</RuleBuilderElement>

<RuleBuilderElement>
<RuleBuilderElementType>Or</RuleBuilderElementType>

<RuleBuilderElement>
<RuleBuilderElementType>Rule</RuleBuilderElementType>
<Filter> ... filters for rule 2 ... </Filter>
</RuleBuilderElement>

<RuleBuilderElement>
<RuleBuilderElementType>Rule</RuleBuilderElementType>
<Filter> ... filters for rule 3 ... </Filter>
</RuleBuilderElement>

</RuleBuilderElement>

</RuleBuilderElement>

Within every Filter element, you must code one FilterType, one FilterOperation, and one FilterValue
element. These elements are described in the following table.
Table 468. Performance policy XML: Elements in a Filter element
Element name Rqd/Opt Description
FilterType Required This element identifies the virtual server attribute to be used during
classification. Valid values are:
Hostname
The host name of the virtual server. To use this value, a guest
platform management provider must be running on the operating
system on the virtual server.
Virtual Server Name
The virtual server ID for z/VM and x Hyp or the logical partition
(LPAR) ID for PowerVM and PR/SM. This ID is the same as the
name used on the Virtual Servers tab on the Ensemble Management
window in the primary HMC.
OS Type
The type of operating system, such as AIX® or Linux, that is running
on the virtual server. You can select this type only if he virtual server
definition contains the OS type. To use this value, a guest platform
management provider must be running on the operating system on
the virtual server.
OS Level
The release level of the operating system running on the virtual
server. To use this value, a guest platform management provider
must be running on the operating system on the virtual server.
OS Name
The name of the operating system image running on the virtual
server as known to its operating system. To use this value, a guest
platform management provider must be running on the operating
system on the virtual server.

1388 HMC Web Services API

 Level 04a

Table 468. Performance policy XML: Elements in a Filter element (continued)

Element name Rqd/Opt Description
FilterOperation Required This element identifies the logical filter operation, which must be one of
the following:
v stringMatch – the filter value must match the property defined by the
filter type
v stringNotMatch – the filter value must not match the property defined
by the filter type
FilterValue Required The value to be used for classification. Possible values vary based on the
value specified for the FilterType element. A filter value cannot be longer
than 255 characters. A filter value must be a regular expression that can
include one period (.) as a substitute for one character and one wildcard
(.*) as a substitute for multiple characters. This wildcard can be used only
at the end of an expression.
v For filter type Hostname, provide a fully qualified host name that
consists of the host name and the TCP domain name. The TCP domain
name specifies a group of systems that share a common suffix (domain
name). For example, given a fully qualified host name of
server1.us.ibm.com:
– server1 is the host name
– us.ibm.com is the TCP domain name
The fully qualified host name server1.us.ibm.com illustrates a
character-based format, but you can use a numerical-based name. The
numerical-based host name is not the same as the system's IP address.
v For filter type OS Level, provide the release level of the operating
system.
v For filter type OS Name, provide the LPAR name or virtual machine
ID.
v For filter type OS Type, provide the name of the operating system.
v For filter type Virtual Server Name, provide the virtual server name
shown in the Virtual Server Details window in the HMC.

Sample XML document for a performance policy

The following sample illustrates a correctly structured XML document for a workload resource group
performance policy.

This performance policy consists of two service classes:

SC1
This service class sets a performance goal of slow velocity and medium importance for virtual servers
with attributes that match both of the following classification rules:
v The virtual server name is “Server1”, and
v The hostname is “abc.pok.ibm.com”
SC2
This service class sets a performance goal of slow velocity and medium importance for virtual servers
with a virtual server name that matches “Lpar1”.

Appendix A. XML document structure of a performance policy 1389

 Level 04a

<?xml version="1.0" encoding="UTF-8"?>

<WorkloadPerformancePolicy
xmlns=”http://www.ibm.com/PPM/WorkloadPerformancePolicy”>

<Name>Workload Policy name</Name>

<Description>Workload performance policy for sample workload</Description>
<Version>1.00.00</Version>
<UI>PPM Editor</UI>
<WorkloadImportance>High</WorkloadImportance>

<ServiceClasses>

<ServiceClass>
<Name>SC1</Name>
<Description>SC1 Description</Description>
<Type>Server</Type>

<RuleBuilderElement>
<RuleBuilderElementType>And</RuleBuilderElementType>
<RuleBuilderElement>
<RuleBuilderElementType>Rule</RuleBuilderElementType>
<Filter>
<FilterType>Virtual Server Name</FilterType>
<FilterOperation>stringMatch</FilterOperation>
<FilterValue>Server1</FilterValue>
</Filter>
</RuleBuilderElement>
<RuleBuilderElement>
<RuleBuilderElementType>Rule</RuleBuilderElementType>
<Filter>
<FilterType>Hostname</FilterType>
<FilterOperation>stringMatch</FilterOperation>
<FilterValue>abc.pok.ibm.com</FilterValue>
</Filter>
</RuleBuilderElement>
</RuleBuilderElement>

<Goal>
<Importance>Medium</Importance>
<Velocity>Slow</Velocity>
</Goal>
</ServiceClass>

Figure 729. Policy XML example, Part 1

1390 HMC Web Services API

 Level 04a

<ServiceClass>
<Name>SC2</Name>
<Description>Service Class for virtual server</Description>
<Type>Server</Type>

<RuleBuilderElement>
<RuleBuilderElementType>Rule</RuleBuilderElementType>
<Filter>
<FilterType>Virtual Server Name</FilterType>
<FilterOperation>stringMatch</FilterOperation>
<FilterValue>Lpar1</FilterValue>
</Filter>
</RuleBuilderElement>

<Goal>
<Importance>Medium</Importance>
<Velocity>Slow</Velocity>
</Goal>
</ServiceClass>

</ServiceClasses>
</WorkloadPerformancePolicy>

Figure 730. Policy XML example, Part 2

Appendix A. XML document structure of a performance policy 1391

 Level 04a

1392 HMC Web Services API

 Level 04a

Appendix B. Enum values for a type of managed objects

within User Roles
The valid Enum values that can be used to specify a class of managed objects within User Role objects
are listed in the following table:
Table 469. Enum values for a class of managed objects
Enum for type name Type
accelerator-adapter zEnterprise Data Compression (zEDC) adapter
alternate-console
A Hardware Management Console (HMC) paired with the primary
HMC to provide redundancy in an ensemble
blade-center
BladeCenter chassis which contains blades (DataPower XI50z,
POWER, and/or System x)
cpc
CPC defined to the console via Add Object Definition
crypto-adapter Cryptographic coprocessor adapter
datapower-device
IBM WebSphere DataPower Integration Appliance XI50 for
zEnterprise (DataPower XI50z) blade used to optimize XML and Web
services processing
default-workload
System defined workload resource group used as a default in an
ensemble

eckd-storage-resource ECKD Storage Resource

ensemble
Ensemble object representing a collection of one or more nodes (CPC
or zBX Node) managed as a single logical virtualized system
| fc-storage-group Fibre Connection (FICON) storage group
| fcp-storage-group FCP storage group

fcp-storage-resource FCP Storage Resource

ficon-adapter Fibre Connection (FICON) adapter
hipersockets-adapter Memory-based network adapter
lpar-image
Partition where an operating system is run
osa-adapter Open Systems Adapter (OSA) network adapter
p-blade
Select IBM POWER blade running AIX applications in an ensemble
p-virtual-server
Virtual server defining resources (processor, memory, and I/O) on a
POWER blade
partition Dynamic Partition Manager (DPM) partition

pattern-match-group Group containing objects whose name matches a specified pattern

roce-adapter RDMA over Converged Ethernet adapter

© Copyright IBM Corp. 2017, 2018 1393

 Level 04a

Table 469. Enum values for a class of managed objects (continued)

Enum for type name Type
system-manual-definition
Template used to manually define a system object to the Hardware
Management Console
undefined-cpc
CPC that is discovered in the console domain but not defined to the
console
undefined-zbx-node
zBX Node that is discovered in the console domain but not defined to
the console
user-defined-group
A group of objects defined by a user for organizing objects with a
similar purpose or to assign different activation profiles
virtual-network
A group of virtual servers network interfaces that are associated with
a VLAN ID
workload-element-group
Group of virtual servers organized for redundancy in a workload
resource group
workload-resource-group
A collection of virtual servers associated with a set of policies that
define performance and availability goals
x-blade
Select System x blade running 64-bit Windows or Linux applications
in an ensemble
x-virtual-server
Virtual server defining resources (processor, memory, and I/O) on a
System x blade
zbx-node
zBX Node defined to the console via Add Object Definition
zvm-fcp-storage-resource
z/VM FCP Storage Resource
zvm-virtual-machine
Virtualized processor, communications, storage, networking, and I/O
resources running on the z/VM hypervisor

1394 HMC Web Services API

 Level 04a

Appendix C. Enum values for the User Role object

The valid Enum values for the name property of User Role objects with a type of "system-defined" are
listed in the following table:
Table 470. Enum values for the name property of User Role objects with a type of "system-defined"
Enum for system-defined User Role
name System-defined User Role Valid as an associated User Role
hmc-access-administrator-tasks Access Administrator Tasks Yes
hmc-advanced-operator-tasks Advanced Operator Tasks Yes
hmc-all-resources All Resources No
hmc-all-system-managed-objects All System Managed Objects No
hmc-bladecenter-objects BladeCenter Objects No
hmc-defined-system-managed-objects Defined System Managed Objects No
hmc-dpxi50z-blade-objects DPXI50z Blade Objects No
hmc-energy-administrator-tasks Energy Administrator Tasks Yes
hmc-ensemble-administrator-tasks Ensemble Administrator Tasks Yes
hmc-ensemble-object Ensemble Object No
hmc-ibm-blade-objects IBM Blade Objects No
hmc-ibm-blade-virtual-server-objects IBM Blade Virtual Server Objects No
hmc-operator-tasks Operator Tasks Yes
hmc-policy-administrator-tasks Policy Administrator Tasks Yes
hmc-policy-operator-tasks Policy Operator Tasks Yes
hmc-service-representative-tasks Service Representative Tasks Yes
| hmc-storage-administrator-objects Storage Administrator Objects No
| hmc-storage-administrator-tasks Storage Administrator Tasks Yes
hmc-storage-resource-administrator- Storage Resource Administrator Tasks Yes
tasks
hmc-storage-resource-objects Storage Resource Objects No
hmc-system-programmmer-tasks System Programmer Tasks Yes
hmc-virtual-network-administrator- Virtual Network Administrator Tasks Yes
tasks
hmc-virtual-network-objects Virtual Network Objects No
hmc-virtual-server-administrator- Virtual Server Administrator Tasks Yes
tasks
hmc-virtual-server-operator-tasks Virtual Server Operator Tasks Yes
hmc-workload-administrator-tasks Workload Administrator Tasks Yes
hmc-workload-objects Workload Objects No
hmc-z-vm-virtual-machine-objects z/VM Virtual Machine Objects No
hmc-z-vm-virtual-machine-tasks z/VM Virtual Machine Tasks Yes

© Copyright IBM Corp. 2017, 2018 1395

 Level 04a

1396 HMC Web Services API

 Level 04a

Appendix D. Enum values for the Task object

The valid Enum values for the name property of Task objects are listed in the following table:
Table 471. Enum values for the name property of Task objects
view-only-mode
Enum for task name Task supported
access-removable-media Access Removable Media false
activate-availability-policy Activate Availability Policy false
activate-base Activate false
activate-performance-policy Activate Performance Policy false
activate-policies Activate Policies false
adapter-details Adapter Details false
add-hosts-to-virtual-network Add Hosts to Virtual Network false
add-member-to-ensemble Add Member to Ensemble false
add-object-definition Add Object Definition false
add-storage-resource Add Storage Resource false
add-storage-resource-to-group Add Storage Resource to Group false
add-systems-to-ctn Add Systems to CTN false
adjust-leap-second-offset Adjust Leap Second Offset false
adjust-time Adjust Time false
adjust-time-zone-offset Adjust Time Zone Offset false
alternate-details Alternate Details false
alternate-support-element Alternate Support Element false
alternate-support-element- Alternate Support Element Engineering Changes false
engineering-changes (ECs)
analyze-console-internal-code Analyze Console Internal Code false
archive-security-logs-base Archive Security Logs false
archive-security-logs-z Archive Security Logs false
audit-and-log-management Audit and Log Management false
authorize-internal-code-changes Authorize Internal Code Changes false
automatic-activation Automatic Activation false
availability-policy-details Availability Policy Details false
availability-status-event-report Availability status Event Report false
availability-status-monitor Availability Status Monitor false
backup-critical-console-data Backup Critical Console Data false
backup-critical-data Backup Critical Data false
bc-san-dashboard BladeCenter Storage Diagnostics false
block-automatic-licensed-internal- Block Automatic Licensed Internal Code Change false
code-change-installation Installation
certificate-management Certificate Management false
change-console-internal-code Change Console Internal Code false

© Copyright IBM Corp. 2017, 2018 1397

 Level 04a

Table 471. Enum values for the name property of Task objects (continued)
view-only-mode
Enum for task name Task supported
change-internal-code Change Internal Code false
change-lpar-controls Change LPAR Controls false
change-lpar-group-controls Change LPAR Group Controls false
change-lpar-i-o-priority-queuing Change LPAR I/O Priority Queuing false
change-lpar-security Change LPAR Security false
change-object-definition Change Object Definition false
change-object-options Change Object Options false
choose-z-vm-virtual-machines-to- Choose z/VM Virtual Machines to Manage false
manage
choose-z-vm-virtual-servers-to- Choose z/VM Virtual Servers to Manage false
manage
compare-access-lists Compare Access Lists false
concurrent-upgrade-engineering- Concurrent Upgrade Engineering Changes (ECs) false
changes
configure-3270-emulators Configure 3270 Emulators false
configure-backup-settings Configure Backup Settings false
configure-channel-path-on-off Configure Channel Path On/Off true
configure-data-replication Configure Data Replication false
configure-external-time-source Configure External Time Source false
| configure-storage-storageadmin Configure Storage – Storage Administrator false
| configure-storage-sysprog Configure Storage - System Programmer false
configure-top-of-rack-switch Configure Top-of-rack (TOR) Switch false
control-pulse-per-second-signal Control Pulse Per Second Signal false
console-default-user-settings Console Default User Settings false
console-messenger Console Messenger false
copy-console-logs-to-media Copy Console Logs to Media false
create-ensemble Create Ensemble false
create-virtual-network Create a New Virtual Network false
create-hipersockets-adapter Create HiperSockets Adapter false
create-welcome-text Create Welcome Text false
customer-information Customer Information false
customize-activity-profiles Customize Activity Profiles false
customize-api-settings Customize API Settings false
customize-automatic-logon Customize Automatic Logon false
customize-console-date-time Customize Console Date/Time false
customize-console-services Customize Console Services false
customize-customer-information Customize Customer Information false
customize-delete-activation-profiles Customize/Delete Activation Profiles false
customize-network-settings-base Customize Network Settings false
customize-network-settings-z Customize Network Settings false

1398 HMC Web Services API

 Level 04a

Table 471. Enum values for the name property of Task objects (continued)
view-only-mode
Enum for task name Task supported
customize-outbound-connectivity Customize Outbound Connectivity false
customize-product-engineering-access Customize Product Engineering Access false
customize-remote-service Customize Remote Service false
customize-scheduled-operations Customize Scheduled Operations false
customize-scheduled-operations-c Customize Scheduled Operations false
customize-support-element-date-time Customize Support Element Date/Time false
deactivate-base Deactivate false
deconfigure-ctn Deconfigure CTN false
delete-availability-policy Delete Availability Policy false
delete-element-group Delete Element Group false
delete-ensemble Delete Ensemble false
delete-hipersockets-adapter Delete HiperSockets Adapter false
delete-partition Delete Partition false
delete-performance-policy Delete Performance Policy false
delete-virtual-network Delete a Virtual Network false
delete-virtual-server Delete Virtual Server false
delete-workload-resource-group Delete Workload Resource Group false
discover-storage-resources Discover Storage Resources false
domain-security Domain Security false
dump-partition Dump false
edit-frame-layout Edit Frame Layout false
edit-virtual-network-properties Edit Virtual Network Properties false
edit-vmrm-active-configuration-file Edit the VMRM Active Configuration File false
element-group-details Element Group Details false
enable-ftp-access-to-mass-storage- Enable FTP Access to Mass Storage Media false
media
enable-i-o-priority-queuing Enable I/O Priority Queuing false
energy-optimization-advisor Energy Optimization Advisor false
engineering-changes Engineering Changes (ECs) false
ensemble-details Ensemble Details false
ensemble-details-performance- Ensemble Details Performance Management false
management
ensemble-management-guide Ensemble Management Guide false
environmental-efficiency-statistics Environmental Efficiency Statistics false
export-ctn-data Export CTN data (.xls) false
| export-import-profile-data Export/Import Profile Data (API only) false
export-performance-policy Export Performance Policy false
export-world-wide-port-name-list Export World Wide Port Name List false
export-wwpns Export WWPNs false
fibre-channel-analyzer Fibre Channel Analyzer false

Appendix D. Enum values for the Task object 1399

 Level 04a

Table 471. Enum values for the name property of Task objects (continued)
view-only-mode
Enum for task name Task supported
file-dialog File Dialog false
firmware-details Firmware Details false
format-media Format Media false
getting-started-with-dynamic- Getting Started with Dynamic Partition Manager false
partition-manager
grouping Grouping false
hardware-messages Hardware Messages true
hops-report Hops Report false
hypervisor-report Hypervisor Report false
| idaa-callhome-config Configure IDAA Call-Home false
image-details Image Details false
import-performance-policy Import Performance Policy false
import-storage-access-list Import Storage Access List false
initiate-hypervisor-dump Initiate Hypervisor Dump false
initiate-virtual-server-dump Initiate Virtual Server Dump false
initiate-zvm-management-guest-dump Initiate zVM Management Guest Dump false
input-output-configuration-save-and- Input/Output (I/O) Configuration Save and false
restore Restore
installation-complete-report Installation Complete Report false
integrated-3270-console Integrated 3270 Console false
integrated-ascii-console Integrated ASCII Console false
lic-security-mode Licensed Internal Code Security Mode false
load Load false
load-balancing-report Load Balancing Report false
load-from-removable-media-or-server Load from Removable Media or Server false
logical-processor-add Logical Processor Add false
maintain-z-vm-profiles Maintain z/VM Profiles false
maintain-z-vm-prototypes Maintain z/VM Prototypes false
maintain-z-vm-virtual-machines Maintain z/VM Virtual Machines false
maintain-z-vm-volume-space Maintain z/VM Volume Space false
manage-adapters Manager Adapters false
manage-alternate-hmc Manage Alternate HMC false
manage-datapower-xi50z Manage DataPower XI50z false
manage-flash-allocation Manage Flash allocation false
manage-ldap-server-definitions Manage LDAP Server Definitions false
manage-password-rules Manage Password Rules false
| manage-power-service-state Manage Power Service State false
manage-print-screen-files Manage Print Screen Files false
manage-processor-sharing Manage Processor Sharing false
manage-remote-connections Manage Remote Connections false

1400 HMC Web Services API

 Level 04a

Table 471. Enum values for the name property of Task objects (continued)
view-only-mode
Enum for task name Task supported
manage-remote-support-requests Manage Remote Support Requests false
manage-ssh-keys Manage SSH Keys false
manage-storage-resources Manage Storage Resources false
manage-system-time Manage System Time false
manage-user-patterns Manage User Patterns false
manage-user-roles Manage User Roles false
manage-user-templates Manage User Templates false
manage-users Manage Users false
manage-virtual-networks Manage Virtual Networks false
manage-virtual-switches Manage Virtual Switches false
manage-web-services-api-logs Manage Web Services API Logs false
manage-workload-element-groups Manage Workload Element Groups false
manage-zbx-move Manage zBX Move false
migrate-virtual-server Migrate Virtual Server false
mobile-app-preferences HMC Mobile Settings false
modify-assigned-server-roles Modify Assigned Server Roles false
monitor-system-events Monitor System Events false
monitor-system-events-service-class-pi Monitor System Events - Service Class PI Monitor false
monitor-system-events-virtual-server- Monitor System Events - Virtual Server CPU false
cpu-utilization Utilization Monitor
monitors-dashboard Monitors Dashboard false
mount-virtual-media Mount Virtual Media false
multi-factor-auth Manage Multi-factor Authentication false
network-diagnostic-information Network Diagnostic Information false
network-monitors-dashboard Network Monitors Dashboard false
new-availability-policy New Availability Policy false
new-element-group New Element Group false
new-partition New Partition false
new-performance-policy New Performance Policy false
new-virtual-server New Virtual Server false
new-virtual-server-based-on New Virtual Server Based n false
new-workload-resource-group New Workload Resource Group false
object-locking-settings Object Locking Settings false
offload-virtual-retain-data-to- Offload Problem Analysis Data to Removable false
removable-media Media
open-graphical-console-novnc Open Graphical Console false
open-text-console Open Text Console false
operating-system-messages Operating System Messages true
osa-advanced-facilities OSA Advanced Facilities true
partition-details Partition Details false

Appendix D. Enum values for the Task object 1401

 Level 04a

Table 471. Enum values for the name property of Task objects (continued)
view-only-mode
Enum for task name Task supported
partition-details-controls Partition Details - Controls false
perform-console-repair-action Perform a Console Repair Action false
| perform-model-conversion Perform Model Conversion (API only) false
perform-problem-analysis Perform Problem Analysis false
perform-transfer-rate-test Perform Transfer Rate Test false
performance-policy-details Performance Policy Details false
product-engineering-directed-changes Product Support Directed Changes false
psw-restart PSW Restart false
reassign-channel-path-ids Reassign Channel Path IDs false
reassign-devices Reassign Devices false
reassign-hardware-management- Reassign Hardware Management Console false
console
reassign-i-o-path Reassign I/O Path false
reboot-support-element Reboot Support Element false
rebuild-vital-product-data Rebuild Vital Product Data false
remote-hardware-management- Remote Hardware Management Console false
console
remote-service Remote Service false
remove-hosts-from-virtual-network Remove Hosts from Virtual Network false
remove-member-from-ensemble Remove Member from Ensemble false
remove-object-definition Remove Object Definition false
remove-storage-resource Remove Storage Resource false
remove-storage-resource-from-group Remove Storage Resource from Group false
remove-systems-from-ctn Remove Systems from CTN false
rename-ctn Rename CTN false
repair-moved-hosts Repair Moved Hosts false
repair-virtual-network Repair Virtual Network false
report-problem-base Report a Problem false
report-problem-z Report a Problem false
reset-clear Reset Clear false
reset-normal Reset Normal false
restart-zvm-management-guest Restart zVM Management Guest false
| restore-config Import Dynamic Partition Manager Configuration false
retrieve-backup-file-from-ftp Retrieve Backup or Upgrade Data false
retrieve-internal-code Retrieve Internal Code false
save-legacy-upgrade-data Save Legacy Upgrade Data false
save-restore-customizable-console- Save/Restore Customizable Console Data false
data
save-stp-debug-data Save STP Debug Data false
save-upgrade-data Save Upgrade Data false

1402 HMC Web Services API

 Level 04a

Table 471. Enum values for the name property of Task objects (continued)
view-only-mode
Enum for task name Task supported
save-upgrade-ftp Save Upgrade Data false
service-class-resource-adjustments- Service Class Resource Adjustments Report false
report
service-classes-report Service Classes Report false
service-status Service Status false
set-ctn-member-restriction Set CTN Member Restriction false
set-power-cap Set Power Cap false
set-power-saving Set Power Saving false
setup-new-ctn Setup New CTN false
shutdown-or-restart Shutdown or Restart false
single-object-operations Single Object Operations false
single-step-console-internal-code Single Step Console Internal Code false
single-step-internal-code-changes Single Step Internal Code Changes false
start-all Start All Processors false
start-partitions Start false
start-systems Start false
stop-all Stop All Processors false
stop-partitions Stop false
stop-systems Stop false
storage-resource-details Storage Resource Details false
system-activity-display Activity false
system-details System Details false
system-information System Information false
system-input-output-configuration- System Input/Output Configuration Analyzer false
analyzer
test-communications-with-storage- Test Communications with Storage Resources false
resources
tip-of-the-day Tip of the Day false
toggle-lock Toggle Lock false
transmit-console-service-data Transmit Console Service Data false
transmit-service-data Transmit Service Data false
transmit-vital-product-data-base Transmit Vital Product Data false
transmit-vital-product-data-z Transmit Vital Product Data false
undefine-z-vm-virtual-machines-for- Undefine z/VM Virtual Machines for false
management Management
user-settings User Settings false
users-and-tasks Users and Tasks false
view-activation-profiles View Activation Profiles false
view-console-events View Console Events false
view-console-information View Console Information false

Appendix D. Enum values for the Task object 1403

 Level 04a

Table 471. Enum values for the name property of Task objects (continued)
view-only-mode
Enum for task name Task supported
view-console-service-history View Console Service History false
view-console-tasks-performed View Console Tasks Performed false
view-external-time-source View External Time Source false
view-frame-layout View Frame Layout false
view-licenses View Licenses false
view-partition-resource-assignments View Partition Resource Assignments false
view-pmv-records-base View PMV Records false
view-pmv-records-z View PMV Records false
view-pulse-per-second-signal View Pulse Per Second Signal false
view-security-logs View Security Logs false
view-service-history View Service History false
view-statistics View Statistics false
view-the-vmrm-measurement-data View the VMRM Measurement Data false
virtual-server-details Virtual Server Details false
virtual-server-performance-details Virtual Server Performance Details false
virtual-server-resource-adjustments- Virtual Server Resource Adjustments Report false
report
virtual-server-topology-report Virtual Server Topology Report false
virtual-servers-report Virtual Servers Report false
whats-new What's New false
workload-resource-adjustments-report Workload Resource Adjustments Report false
workload-resource-group-details Workload Resource Group Details false
workloads-report Workloads Report false
xnode-details System Details false
z-vm-virtual-machine-details z/VM Virtual Machine Details false
z-vm-virtual-network-information z/VM Virtual Network Information false
zbx-blade-details Blade Details false
zbx-bladecenter-details BladeCenter Details false

1404 HMC Web Services API

 Level 04a

Appendix E. Notices
This information was developed for products and services offered in the US.

IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program,
or service that does not infringe any IBM intellectual property right may be used instead. However, it is
the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or
service.

IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can send
license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
US

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS”

WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM websites are provided for convenience only and do not in
any manner serve as an endorsement of those websites. The materials at those websites are not part of
the materials for this IBM product and use of those websites is at your own risk.

IBM may use or distribute any of the information you provide in any way it believes appropriate without
incurring any obligation to you.

Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.

Statements regarding IBM's future direction or intent are subject to change or withdrawal without notice,
and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to actual people or business enterprise is
entirely coincidental.

© Copyright IBM Corp. 2017, 2018 1405

 Level 04a

Trademarks
IBM, the IBM logo, and ibm.com® are trademarks of International Business Machines Corp., registered in
many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other
companies. A current list of IBM trademarks is available on the web at “Copyright and trademark
information” at www.ibm.com/legal/copytrade.shtml.

Intel, and Intel logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the
United States and other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or
its affiliates.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United
States, other countries, or both.

Unix is a trademark of The Open Group in the United States, other countries, or both.

Other product and service names might be trademarks of IBM or other companies.

1406 HMC Web Services API

 Level 04a

Class A Notices
The following Class A statements apply to this IBM product. The statement for other IBM products
intended for use with this product will appear in their accompanying manuals.

Federal Communications Commission (FCC) Statement

Note: This equipment has been tested and found to comply with the limits for a Class A digital device,
pursuant to Part 15 of the FCC Rules. These limits are designed to provide reasonable protection against
harmful interference when the equipment is operated in a commercial environment. This equipment
generates, uses, and can radiate radio frequency energy and, if not installed and used in accordance with
the instruction manual, may cause harmful interference to radio communications. Operation of this
equipment in a residential area is likely to cause harmful interference, in which case the user will be
required to correct the interference at his own expense.

Properly shielded and grounded cables and connectors must be used in order to meet FCC emission
limits. IBM is not responsible for any radio or television interference caused by using other than
recommended cables and connectors or by unauthorized changes or modifications to this equipment.
Unauthorized changes or modifications could void the user's authority to operate the equipment.

This device complies with Part 15 of the FCC rules. Operation is subject to the following two conditions:
(1) this device may not cause harmful interference, and (2) this device must accept any interference
received, including interference that may cause undesired operation.

Industry Canada Compliance Statement

This Class A digital apparatus complies with Canadian ICES-003.

Avis de conformité à la réglementation d'Industrie Canada

Cet appareil numérique de la classe A est conforme à la norme NMB-003 du Canada.

European Community Compliance Statement

This product is in conformity with the protection requirements of EU Council Directive 2014/30/EU on
the approximation of the laws of the Member States relating to electromagnetic compatibility. IBM cannot
accept responsibility for any failure to satisfy the protection requirements resulting from a
non-recommended modification of the product, including the fitting of non-IBM option cards.

This product has been tested and found to comply with the limits for Class A Information Technology
Equipment according to European Standard EN 55032. The limits for Class A equipment were derived for
commercial and industrial environments to provide reasonable protection against interference with
licensed communication equipment.

European Community contact:

IBM Deutschland GmbH
Technical Regulations, Department M372
IBM-Allee 1, 71139 Ehningen, Germany
Tele: +49 (0) 800 225 5423 or +49 (0) 180 331 3233
email: halloibm@de.ibm.com

Warning: This is a Class A product. In a domestic environment, this product may cause radio
interference, in which case the user may be required to take adequate measures.

Appendix E. Notices 1407

 Level 04a

VCCI Statement - Japan

The following is a summary of the Japanese VCCI statement above:

This is a Class A product based on the standard of the VCCI Council. If this equipment is used in a
domestic environment, radio interference may occur, in which case the user may be required to take
corrective actions.

Japan JIS C 61000-3-2 Compliance

（"#）%&'()*+,-./ 012%3456789
/ :;に=づく@ABC%CD： Knowledge CenterのGHIの/
/ / / / / / / / / / / / / JKページOP
For products less than or equal to 20 A per phase, the following statement applies:

!"#$%&' JIS C 61000-3-2 ()*

For products greater than 20 A, single-phase, the following statements apply:

,:;3TUV JIS C 61000-3-2 WXY

&'(は、「,-.は/0,-で23する678の,:;<=>
?ガイドライン」>FGH（,:;JKGH）です。
#$NO：６（!"、ＰＦＣ#$%）
PQRS：０
For products greater than 20 A per phase, three-phase, the following statements apply:

%&'()*+ JIS C 61000-3-2 ,-.

/01は、「%56は78%5で:(する=>?の%&'ABC
Dガイドライン」CKLM（%&'OPLM）です。
"#ST ：５ (３!、ＰＦＣ"#$）
UVWX ：０

1408 HMC Web Services API

 Level 04a

Electromagnetic Interference (EMI) Statement - People's Republic of China

Declaration: This is a Class A product. In a domestic environment, this product may cause radio
interference, in which case the user may need to perform practical action.

Electromagnetic Interference (EMI) Statement - Taiwan

The following is a summary of the Taiwan EMI statement above:

Warning: This is a Class A product. In a domestic environment, this product may cause radio
interference, in which case the user will be required to take adequate measures.

IBM Taiwan Contact Information:

Electromagnetic Interference (EMI) Statement - Korea

! ""# $%&( A')() *+,-./01 2 ""!34

56+ 7# 8&+# ! 91 :;<=" >?@, ABC;
DEFG 8&<# H1 I-() .4J.

Germany Compliance Statement

Deutschsprachiger EU Hinweis: Hinweis für Geräte der Klasse A EU-Richtlinie zur
Elektromagnetischen Verträglichkeit

Dieses Produkt entspricht den Schutzanforderungen der EU-Richtlinie 2014/30/EU zur Angleichung der
Rechtsvorschriften über die elektromagnetische Verträglichkeit in den EU-Mitgliedsstaaten und hält die
Grenzwerte der EN 55032 Klasse A ein.

Appendix E. Notices 1409

 Level 04a

Um dieses sicherzustellen, sind die Geräte wie in den Handbüchern beschrieben zu installieren und zu
betreiben. Des Weiteren dürfen auch nur von der IBM empfohlene Kabel angeschlossen werden. IBM
übernimmt keine Verantwortung für die Einhaltung der Schutzanforderungen, wenn das Produkt ohne
Zustimmung von IBM verändert bzw. wenn Erweiterungskomponenten von Fremdherstellern ohne
Empfehlung von IBM gesteckt/eingebaut werden.

EN 55032 Klasse A Geräte müssen mit folgendem Warnhinweis versehen werden:

"Warnung: Dieses ist eine Einrichtung der Klasse A. Diese Einrichtung kann im Wohnbereich
Funk-Störungen verursachen; in diesem Fall kann vom Betreiber verlangt werden, angemessene
Maßnahmen zu ergreifen und dafür aufzukommen."

Deutschland: Einhaltung des Gesetzes über die elektromagnetische Verträglichkeit von Geräten

Dieses Produkt entspricht dem "Gesetz über die elektromagnetische Verträglichkeit von Geräten (EMVG)".
Dies ist die Umsetzung der EU-Richtlinie 2014/30/EU in der Bundesrepublik Deutschland.

Zulassungsbescheinigung laut dem Deutschen Gesetz über die elektromagnetische Verträglichkeit von
Geräten (EMVG) (bzw. der EMC EG Richtlinie 2014/30/EU) für Geräte der Klasse A

Dieses Gerät ist berechtigt, in Übereinstimmung mit dem Deutschen EMVG das EG-Konformitätszeichen
- CE - zu führen.

Verantwortlich für die Einhaltung der EMV Vorschriften ist der Hersteller:
International Business Machines Corp.
New Orchard Road
Armonk, New York 10504
Tel: 914-499-1900

Der verantwortliche Ansprechpartner des Herstellers in der EU ist:

IBM Deutschland GmbH
Technical Regulations, Abteilung M372
IBM-Allee 1, 71139 Ehningen, Germany
Tel: +49 (0) 800 225 5423 or +49 (0) 180 331 3233
email: halloibm@de.ibm.com

Generelle Informationen:

Das Gerät erfüllt die Schutzanforderungen nach EN 55024 und EN 55032 Klasse A.

Electromagnetic Interference (EMI) Statement - Russia

1410 HMC Web Services API

 Level 04a

Index
A Create IEDN Interface for a DataPower
XI50z Blade 977
Delete Storage Resource 1151
Delete Storage Site 330
accessibility xxxii Create IEDN Virtual Switch 1019 Delete User 549
contact IBM xxxii Create LDAP Server Definition 611 Delete User Pattern 586
features xxxii Create Metrics Context 94 Delete User Role 569
Activate a Blade 973, 975 Create Network Adapter 1095 Delete Virtual Disk 1110
Activate Availability Policy 1359 Create NIC 213 Delete Virtual Function 208
Activate BladeCenter 953 Create Partition 170 Delete Virtual Network 1208
Activate CPC 662 Create Password Rule 597 Delete Virtual Server 1080
Activate Logical Partition 731 Create Performance Policy 1262 Delete Virtual Switch 1031
Activate Performance Policy 1269 Create QDIO Virtual Switch 1022 Delete Virtualization Host Storage
Activate Virtual Server 1119 Create Storage Fabric 339 Resource 1174
Activate zBX (Node) 902 Create Storage Group 426 Delete Workload Element Group 1342
Activating a Virtualization Host 1032 Create Storage Path 400 Delete Workload Resource Group 1231
Add Candidate Adapter Ports to an FCP Create Storage Resource 1147 Delete zBX (Node) Hardware
Storage Group 443 Create Storage Site 327 Message 917
Add Connection Endpoint 378 Create User 546 Detach Storage Group from
Add Group of Virtual Servers to a Create User Pattern 584 Partition 237
Workload Resource Group 1243 Create User Role 567 Discover Virtualization Host Storage
Add MAC Filters to Top-of-Rack Switch Create Virtual Disk 1106 Resources 1182
Port 930 Create Virtual Function 205 Dump Partition 195
Add Member to Custom Group 624 Create Virtual Network 1206
Add Node to Ensemble 875 Create Virtual Server 1075
Add Partition to Capacity Group 317
Add Permission to User Role 562
Create Virtualization Host Storage
Resource 1171
E
Add Temporary Capacity 671 Ensemble power metric group 111
Create Workload Element Group 1339
Add Top-of-Rack Switch Port to Virtual Enum values for a class of managed
Create Workload Resource Group 1228
Networks 934 objects 1393
Add User Role to User 542 Enum values for Task objects 1397
Add Virtual Server to a Workload Enum values for User Role objects 1395
Element Group 1345 D Establish Shared Secret Key 75
Add Virtual Server to a Workload Deactivate BladeCenter 956 Export Performance Policy 1272
Resource Group 1237 Deactivate CPC 664 Export Profiles 668
Add Virtualization Host Storage Resource Deactivate Logical Partition 733 Export World Wide Port Names
Paths 1176 Deactivate Virtual Server 1122 List 1153
Add Virtualization Host Storage Resource Deactivate zBX (Node) 905 Export WWPN List 693
to Virtualization Host Storage Deactivating a Virtualization Host 1033
Group 1194 Decrease Crypto Configuration 228
Add Volume Range 396 Define Storage Control Unit 388
Define Storage Subsystem 369
F
Add Workload Element Group to a FICON storage configuration 137
Workload Resource Group 1248 Define Storage Switch 353
Flash memory adapters 111
API version number, function included Delete Availability Policy 1356
Fulfill FCP Storage Volume 456
in 7 Delete Capacity Group 313
Fulfill FICON Storage Volume 453
assistive technologies xxxii Delete Completed Job Status 83
Attach Storage Group to Partition 234 Delete Console Hardware Message 509
Delete CPC Hardware Message 691
Delete Custom Group 622 G
C Delete HBA 241
Delete Hipersocket 284
Generate Availability Status Report 1373
Generate Hypervisor Report 1299
Cancel Job 84 Delete IEDN Interface for a DataPower Generate Hypervisor Resource
Change Adapter Type 294 XI50z Blade 980 Adjustments Report 1307
Change Crypto Domain Delete LDAP Server Definition 613 Generate Load Balancing Report 1332
Configuration 226 Delete Metrics Context 101 Generate Service Class Hops
Change Crypto Type 280 Delete Network Adapter 1098 Report 1319
Change STP-only Coordinated Timing Delete NIC 217 Generate Service Class Resource
Network 678 Delete Partition 175 Adjustments Report 1314
Create Availability Policy 1354 Delete Partition Asynchronously 177 Generate Service Class Virtual Server
Create Capacity Group 311 Delete Password Rule 599 Topology Report 1324
Create Custom Group 620 Delete Performance Policy 1265 Generate Service Classes Report 1311
Create HBA 239 Delete Storage Fabric 342 Generate Virtual Server CPU Utilization
Create Hipersocket 282 Delete Storage Group 430 Report 1292
Delete Storage Path 402

© Copyright IBM Corp. 2017, 2018 1411

 Level 04a

Generate Virtual Server Resource

Adjustments Report 1294
Get Partitions for a Storage Group 465
Get Password Rule Properties 594
K
Generate Virtual Servers Report 1287 Get Performance Management Velocity keyboard
Generate Virtual Servers Report Level Range Mappings 1375 navigation xxxii
(Ensemble Availability Get Performance Policy Properties 1259
Management) 1370 Get Rack Properties 941
Generate Workload Resource Group Get Reset Activation Profile L
Availability Status Report 1365 Properties 763 Leave STP-only Coordinated Timing
Generate Workload Resource Group Get Storage Control Unit Properties 392 Network 681
Performance Index Report 1280 Get Storage Fabric Properties 343 List Adapters of a CPC 273
Generate Workload Resource Group Get Storage Group Properties 433 List Availability Policies 1351
Resource Adjustments Report 1283 Get Storage Path Properties 404 List BladeCenters in a Rack 947, 949
Generate Workload Resource Groups Get Storage Port Properties 291 List Blades in a BladeCenter 964
Report (Ensemble Availability Get Storage Resource Properties 1146 List Blades in a zBX 966
Management) 1362 Get Storage Site Properties 331 List Capacity Groups of a CPC 309
Generate Workload Resource Groups Get Storage Subsystem Properties 372 List Capacity Records 812
Report (Performance Get Storage Switch Properties 357 List Console Hardware Messages 505
Management) 1276 Get Storage Volume Properties 452 List CPC Hardware Messages 687
Get Adapter Properties 275 Get Switch Controllers 1025 List CPC Objects 644
Get ASCII Console WebSocket URI 256 Get Task Properties 574 List Custom Group Members 627
Get Availability Policy Properties 1353 Get Top-of-Rack Switch Port Details 926 List Custom Groups 617
Get Blade Properties 969 Get Top-of-Rack Switch Properties 924 List Ensemble CPC Objects 646
Get BladeCenter Properties 951 Get User Pattern Properties 580 List Ensemble Nodes 871
Get Capacity Group Properties 315 Get User Properties 537 List Ensembles 865
Get Capacity Record Properties 813 Get User Role Properties 558 List Group Profiles 804
Get Connected VNICs of a Virtual Get Virtual Disk Properties 1112 List Groups of Virtual Servers of a
Switch 303 Get Virtual Function Properties 209 Workload Resource Group 1241
Get Console Audit Log 498 Get Virtual Network Properties 1202 List Image Activation Profiles 786
Get Console Hardware Message Get Virtual Server Properties 1082 List LDAP Server Definitions 605
Properties 507 Get Virtual Storage Resource List Load Activation Profiles 796
Get Console Properties 488 Properties 461 List Logical Partitions of CPC 720
Get Console Security Log 501 Get Virtual Switch Properties 301, 1017 List Managed Virtual Machines of a
Get CPC Audit Log 682 Get Virtualization Host Properties 1008 Logical Partition 757
Get CPC Energy Management Data 836 Get Virtualization Host Storage Group List Members of a Virtual Network 1210
Get CPC Hardware Message Properties 1190 List OS Messages of a Logical
Properties 690 Get Virtualization Host Storage Resource Partition 749
Get CPC Notification Preferences for Properties 1167 List OS Messages of a Partition 253
Device 517 Get Workload Element Group List Partitions of a CPC 164
Get CPC Properties 648 Properties 1338 List Password Rules 591
Get CPC Security Log 685 Get Workload Resource Group List Performance Policies 1257
Get Custom Group Properties 619 Properties 1226 List Permitted Logical Partitions 722
Get EC/MCL Description of zBX Get zBX (Node) Audit Log 907 List Permitted Partitions 167
(Node) 899 Get zBX (Node) Hardware Message List Racks of a zBX 939
Get Energy Optimization Advice Properties 915 List Reset Activation Profiles 761
Details 844 Get zBX (Node) Security Log 909 List Storage Control Units of a Storage
Get Energy Optimization Advice Get zBX Properties 896 Subsystem 386
Summary 837 List Storage Fabrics 337
Get Ensemble Properties 867 List Storage Groups 424
Get Group Profile Properties 806
Get HBA Properties 245
I List Storage Resources 1143
IBM z Unified Resource Manager 3 List Storage Sites 324
Get Image Activation Profile List Storage Subsystems of a Storage
Import DPM Configuration 695
Properties 788 Site 367
Import Performance Policy 1270, 1385
Get Inventory 88 List Storage Switches of a Storage
Import Profiles 667
Get LDAP Server Definition Fabric 351
Import Storage Access List 1155
Properties 607 List Storage Switches of a Storage
Increase Crypto Configuration 224
Get Load Activation Profile Site 348
Initiate Virtual Server Dump 1132
Properties 798 List Storage Volumes of a Storage
Inventory Service Data 1034
Get Logical Partition Properties 725 Group 448
Get Metrics 98 List Tasks 573
Get Mobile App Preferences 514 List Top-of-Rack Switches of a zBX 921
Get Network Adapter Properties 1099 J List Unmanaged CPCs 510
Get Network Port Properties 288 Join STP-only Coordinated Timing List Unmanaged zBX Nodes 512
Get NIC Properties 219 Network 680 List User Patterns 578
Get Node Properties 873 List User Roles 556
Get Notification Topics 77 List Users 535
Get Partition Properties 179 List Virtual Disks of a Virtualization Host
Get Partitions Assigned to Adapter 285 Storage Resource 1184

1412 HMC Web Services API

 Level 04a

List Virtual Networks 1200

List Virtual Servers of a CPC 1070
O Set BladeCenter Power Save 848
Set CPC Power Capping 830
List Virtual Servers of a Node 1065 Open OS Message Channel 251, 747 Set CPC Power Save 827
List Virtual Servers of a Virtualization Set Mobile App Preferences 516
Host 1073 Set STP Configuration 677
List Virtual Servers of a Workload P Set zBX (Node) Power Capping 824
Element Group 1344 Perform PSW Restart 203 Set zBX (Node) Power Save 822
List Virtual Servers of a Workload policy XML document Set zCPC Power Capping 834
Resource Group 1234 description 1385 Set zCPC Power Save 832
List Virtual Servers of a zBX example 1389 shortcut keys xxxii
(Node) 1063 PSW Restart 741 Shutdown Console 495
List Virtual Servers of an Ensemble 1068 SMAPI Error Response Body 1033
List Virtual Storage Resources of a Start CPC 657
Storage Group 459
List Virtual Switches 1015
Q Start Dump Program 199
Start Logical Partition 742
List Virtual Switches of a CPC 299 Query API Version 68 Start Partition 190
List Virtualization Host HBA Ports 1162 Query Job Status 80 Stop CPC 660
List Virtualization Host Storage Stop Logical Partition 744
Groups 1188 Stop Partition 193
List Virtualization Host Storage R Summary of updates by API version
Resources 1164 Reassign Storage Adapter Port 247 number 7
List Virtualization Host Storage Resources Remove Candidate Adapter Ports from Swap Current Time Server 675
in a Virtualization Host Storage an FCP Storage Group 446
Group 1192 Remove Connection Endpoint 380
List Virtualization Host Storage Resources
of a Storage Resource 1157
Remove Group of Virtual Servers from a T
Workload Resource Group 1245 Task objects, valid enum values 1397
List Virtualization Hosts of a CPC 1005 Remove MAC Filters from Top-of-Rack
List Virtualization Hosts of a Node 1000 Switch Port 932
List Virtualization Hosts of a zBX Remove Member from Custom
(Node) 998 Group 625 U
List Virtualization Hosts of an Remove Node from Ensemble 878 Undefine Storage Control Unit 390
Ensemble 1003 Remove Partition from Capacity Undefine Storage Subsystem 371
List Workload Element Groups of a Group 319 Undefine Storage Switch 355
Workload Resource Group 1247 Remove Permission from User Role 565 Unified Resource Manager 3
List Workload Element Groups of an Remove Temporary Capacity 673 Unmount ISO Image 233
Ensemble 1337 Remove Top-of-Rack Switch Port from Unmount Virtual Media 1128
List Workload Resource Groups of an the Virtual Networks 936 Update Adapter Properties 277
Ensemble 1224 Remove User Role from User 544 Update Availability Policy 1357
List zBX (Node) Hardware Remove Virtual Server from a Workload Update Capacity Group Properties 321
Messages 912 Element Group 1347 Update CPC Notification Preferences for
List zBXs of a CPC 892 Remove Virtual Server from a Workload Device 521
List zBXs of an Ensemble 894 Resource Group 1239 Update CPC Properties 656
Load Logical Partition 739 Remove Virtualization Host Storage Update Ensemble Properties 869
Logoff 76 Resource from Virtualization Host Update Group Profile Properties 808
Logon 70 Storage Group 1196 Update HBA Properties 243
Remove Virtualization Host Storage Update Image Activation Profile
Resource Paths 1180 Properties 793
M Remove Volume Range 398 Update LDAP Server Definition
Properties 609
Make Console Primary 494 Remove Workload Element Group from a
Workload Resource Group 1250 Update Load Activation Profile
managed objects, valid enum
Reorder Network Adapter 1104 Properties 801
values 1393
Reorder User Patterns 496 Update Logical Partition Properties 730
Migrate Virtual Server 1130
Reorder Virtual Disks 1117 Update Network Adapter 1102
Modify Storage Group Properties 435
Reset Clear 737 Update Network Port Properties 289
Mount ISO Image 231
Reset Normal 735 Update NIC Properties 220
Mount Virtual Media 1124
Restart Console 493 Update Partition Properties 182
Mount Virtual Media Image 1127
RoCE adapters 111 Update Partition Properties
Move Storage Subsystem to Storage
Asynchronously 186
Site 376
Update Password Rule Properties 595
Move Storage Switch to Storage
Fabric 362 S Update Performance Policy 1266
Update Reset Activation Profile
Move Storage Switch to Storage Site 360 SCSI Dump 755 Properties 765
SCSI Load 753 Update Storage Control Unit
Send OS Command 249, 746 Properties 394
N Set Auto-Start List 669 Update Storage Fabric Properties 345
navigation Set Blade Power Capping 855 Update Storage Path Properties 405
keyboard xxxii Set Blade Power Save 853 Update Storage Port Properties 292
Set BladeCenter Power Capping 851

Index 1413
 Level 04a

Update Storage Resource

Properties 1150
Update Storage Site Properties 333
Update Storage Subsystem
Properties 374
Update Storage Switch Properties 358
Update Top-of-Rack Switch Port
Properties 928
Update User Pattern Properties 582
Update User Properties 539
Update User Role Properties 560
Update Virtual Disk Properties 1115
Update Virtual Function Properties 211
Update Virtual Network Properties 1204
Update Virtual Server Properties 1091
Update Virtual Storage Resource
Properties 463
Update Virtual Switch 1027
Update Virtual Switch Properties 304
Update Virtualization Host
Properties 1013
Update Workload Element Group 1343
Update Workload Resource Group 1232
User Role objects, valid enum
values 1395

V
Validate LUN Path 467

W
Web Services API 3
Workload Resource Group Details
task 1385

X
XML document
description for performance
policy 1385
example for performance policy 1389

Z
zManager 3

1414 HMC Web Services API

IBM®

Printed in USA

SC27-2636-04