HP CloudSystem Matrix CLI Reference Guide
HP CloudSystem Matrix/Matrix Operating Environment 7.1 Integration Interfaces
API and CLI Operations Reference Guide
Abstract
This document describes the rich set of Matrix OE’s infrastructure orchestration (IO) interfaces available to HP customers,
partners, and integrators. These interfaces allow customers to integrate Matrix OE into their business and IT operations processes.
Partners and Integrators can use the interfaces in combination with their own offerings to provide new, rich capabilities.
HP Part Number: 5900-2282
Published: October 2012
Edition: 6
© Copyright 2009 – 2012 Hewlett-Packard Development Company, L.P.
Warranty
The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express
warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall
not be liable for technical or editorial errors or omissions contained herein.
Revision history
Edition notesPublication dateDocument editionSoftware versionDocument part number
October 201267.1.15900-2282
Corrected the “RequestDetails” (page 62)
data type.
September 201257.1.15900-2282
Includes new v5 service endpoint with
interface extensions. See “New features
in 7.1 Update 1” (page 12).
June 201217.1.05900-2282
Includes new v4 service endpoint with
interface extensions. See “New features
in 7.1” (page 13).
Contents
I Matrix API................................................................................................10
1 Introduction..........................................................................................11
Integration interface overview..............................................................................................12
New features in 7.1 Update 1..............................................................................................12
New features in 7.1............................................................................................................13
Chargeback.................................................................................................................15
2 Accessing the Web Service Interfaces......................................................16
Accessing WSDL...............................................................................................................16
Security............................................................................................................................16
Authorization................................................................................................................16
Impersonation...............................................................................................................16
Command Line Interface.....................................................................................................16
3 Operations..........................................................................................17
Version.............................................................................................................................17
getVersion....................................................................................................................17
Template...........................................................................................................................17
listTemplates.................................................................................................................17
importTemplate.............................................................................................................17
exportTemplate.............................................................................................................17
deleteTemplate..............................................................................................................18
Service.............................................................................................................................18
listServices...................................................................................................................18
getService....................................................................................................................18
createService................................................................................................................18
deleteService................................................................................................................19
deactivateService..........................................................................................................19
activateService..............................................................................................................20
changeServiceLease......................................................................................................20
powerOffService...........................................................................................................20
powerOnService...........................................................................................................21
powerCycleService........................................................................................................21
deleteReplicaService......................................................................................................21
Request............................................................................................................................21
listRequests...................................................................................................................21
getRequestInfo..............................................................................................................22
getRequest...................................................................................................................22
setRequestApprovalState................................................................................................22
continueRequest............................................................................................................22
cancelRequest...............................................................................................................23
Logical Server Group.........................................................................................................23
getLogicalServerGroup..................................................................................................23
addServersToLogicalServerGroup....................................................................................23
addDiskToLogicalServerGroup........................................................................................24
addNewDiskToLogicalServerGroup.................................................................................24
setLogicalServerGroupActiveServerCount..........................................................................25
Logical Server...................................................................................................................26
findLogicalServer..........................................................................................................26
getLogicalServer...........................................................................................................26
deactivateLogicalServers................................................................................................26
activateLogicalServers....................................................................................................27
Contents 3
powerOffLogicalServers.................................................................................................27
powerOnLogicalServers.................................................................................................27
powerCycleLogicalServers..............................................................................................28
editLogicalServers.........................................................................................................28
removeLogicalServers....................................................................................................28
syncLogicalServers........................................................................................................29
Server Pool.......................................................................................................................29
listServerPools...............................................................................................................29
getServerPool................................................................................................................29
createServerPool...........................................................................................................29
deleteServerPool...........................................................................................................30
moveServerToServerPool.................................................................................................30
assignUsersToServerPool.................................................................................................30
unassignUsersFromServerPool.........................................................................................31
Server..............................................................................................................................31
getComputeServer.........................................................................................................31
getVmHost...................................................................................................................31
Software...........................................................................................................................32
listSoftware...................................................................................................................32
getSoftware..................................................................................................................32
Subnet..............................................................................................................................32
listSubnets....................................................................................................................32
getSubnet.....................................................................................................................32
Storage............................................................................................................................33
listSanVolumes..............................................................................................................33
getSanVolume..............................................................................................................33
listSanVolumeTemplates..................................................................................................33
getSanVolumeTemplate..................................................................................................33
Organization.....................................................................................................................34
listOrganizations...........................................................................................................34
getOrganization...........................................................................................................34
assignTemplateToOrganization........................................................................................34
unassignTemplateFromOrganization.................................................................................34
assignServerToOrganization...........................................................................................35
unassignServerFromOrganization....................................................................................35
assignSubnetToOrganization..........................................................................................36
unassignSubnetFromOrganization...................................................................................36
assignSoftwareToOrganization........................................................................................36
unassignSoftwareFromOrganization.................................................................................37
syncOrganizations.........................................................................................................37
CMS................................................................................................................................37
beginCmsMaintenance..................................................................................................37
endCmsMaintenance.....................................................................................................38
countRunningRequestsForCms.........................................................................................38
addCms.......................................................................................................................38
quiesceCms..................................................................................................................38
unquiesceCms..............................................................................................................38
getCmsQuiesceStatus....................................................................................................39
LoadBalancer....................................................................................................................39
listLoadBalancers..........................................................................................................39
addLoadBalancer..........................................................................................................39
modifyLoadBalancer......................................................................................................39
removeLoadBalancer.....................................................................................................40
addLoadBalancerCertificate...........................................................................................40
removeLoadBalancerCertificate.......................................................................................40
4 Contents
setLoadBalancerPassword...............................................................................................40
unsetLoadBalancerPassword...........................................................................................41
LogicalLoadBalancer..........................................................................................................41
createLogicalLoadBalancerGroup....................................................................................41
deleteLogicalLoadBalancerGroup....................................................................................41
addLogicalLoadBalancerGroupMember...........................................................................42
removeLogicalLoadBalancerGroupMember.......................................................................42
FirewallRuleGroup..............................................................................................................42
getFirewallRuleGroup.....................................................................................................42
addRuleToFirewallRuleGroup...........................................................................................43
removeRuleFromFirewallRuleGroup..................................................................................43
syncFirewallRuleGroups..................................................................................................43
FloatingIPAddress...............................................................................................................44
addFloatingIPAddress....................................................................................................44
moveFloatingIPAddress...................................................................................................44
removeFloatingIPAddress................................................................................................44
releaseFloatingIPAddress................................................................................................45
listUnassociatedFloatingIPAddresses.................................................................................45
ServerSnapshot..................................................................................................................45
listServerSnapshots........................................................................................................45
createServerSnapshot....................................................................................................46
revertServerSnapshot.....................................................................................................46
deleteServerSnapshot....................................................................................................46
4 Data Model.........................................................................................48
ByteSize...........................................................................................................................49
ByteSizeEnum....................................................................................................................49
CidrIpRange......................................................................................................................49
CmsQuiesceState...............................................................................................................49
CmsQuiesceStateEnum.......................................................................................................49
CmsQuiesceStatus.............................................................................................................49
ComputeServer..................................................................................................................49
ComputeServerLocalDisk.....................................................................................................49
Cost.................................................................................................................................50
CostFrequency...................................................................................................................50
CostFrequencyEnum...........................................................................................................50
CustomAddressAssignmentTypeAttribute................................................................................50
CustomMemoryAttribute......................................................................................................50
CustomOsImageAttribute....................................................................................................50
CustomProcessorAttribute....................................................................................................51
CustomStorageVolumeAttribute............................................................................................51
CustomSubnetBindingAttribute.............................................................................................51
CustomTemplateAttributes...................................................................................................51
DeployableSoftware...........................................................................................................51
DeploymentService.............................................................................................................52
DeploymentServiceType......................................................................................................52
DeploymentServiceTypeEnum...............................................................................................52
DrMode...........................................................................................................................52
DrModeEnum....................................................................................................................52
DrPolicy............................................................................................................................52
DrState.............................................................................................................................52
FirewallRule.......................................................................................................................53
FirewallRuleGroupInfo.........................................................................................................53
FirewallRuleGroupDetails....................................................................................................53
ImageType........................................................................................................................53
Contents 5
ImageTypeEnum.................................................................................................................53
IPAddressAssignmentType...................................................................................................53
IPAddressAssignmentTypeEnum............................................................................................53
IPType..............................................................................................................................54
IPTypeEnum.......................................................................................................................54
LeasePeriod.......................................................................................................................54
LoadBalancerInfo...............................................................................................................54
LogicalDisk.......................................................................................................................55
LogicalFirewallRuleGroup....................................................................................................55
LogicalIPAddress................................................................................................................55
LogicalLoadBalancerDetails.................................................................................................56
LogicalLoadBalancerGroupDetails........................................................................................56
LogicalLoadBalancerGroupInfo............................................................................................56
LogicalLoadBalancerGroupMember......................................................................................56
LogicalLoadBalancerInfo.....................................................................................................56
LogicalLoadBalancerProtocol...............................................................................................57
LogicalLoadBalancerProtocolEnum.......................................................................................57
LogicalNetworkInterface.....................................................................................................57
LogicalServerDetails...........................................................................................................57
LogicalServerGroupDetails..................................................................................................57
LogicalServerGroupInfo......................................................................................................58
LogicalServerInfo...............................................................................................................58
LogicalSoftware.................................................................................................................59
LogicalSubnet....................................................................................................................59
MessageSeverity................................................................................................................60
MessageSeverityEnum........................................................................................................60
NatEntry...........................................................................................................................60
NatType...........................................................................................................................60
NatTypeEnum....................................................................................................................60
NetworkSource..................................................................................................................60
NetworkSourceEnum..........................................................................................................60
OperatingSystemType.........................................................................................................60
OperatingSystemTypeEnum.................................................................................................60
Organization.....................................................................................................................61
PacketProtocol...................................................................................................................61
PacketProtocolEnum............................................................................................................61
ProcessorArchitecture..........................................................................................................61
ProcessorArchitectureEnum..................................................................................................61
RaidLevel..........................................................................................................................61
RaidLevelEnum...................................................................................................................61
RawMappingType..............................................................................................................61
RawMappingTypeEnum......................................................................................................61
RequestDetails...................................................................................................................62
RequestHistoryItem.............................................................................................................62
RequestHistoryItemLevel......................................................................................................62
RequestHistoryItemLevelEnum...............................................................................................62
RequestInfo.......................................................................................................................62
RequestStatus....................................................................................................................63
RequestStatusEnum.............................................................................................................63
RequestType......................................................................................................................63
RequestTypeEnum..............................................................................................................63
SanVolume.......................................................................................................................64
SanVolumeState.................................................................................................................64
SanVolumeStateEnum.........................................................................................................64
SanVolumeTemplate...........................................................................................................65
6 Contents
ServerPool........................................................................................................................65
ServerPoolResourceNote.....................................................................................................66
ServerResource..................................................................................................................66
ServerSnapshot..................................................................................................................66
ServiceAction....................................................................................................................66
ServiceActionTrigger...........................................................................................................67
ServiceActionTriggerEnum...................................................................................................67
ServiceDetails....................................................................................................................67
ServiceEntityStatus.............................................................................................................67
ServiceEntityStatusEnum......................................................................................................67
ServiceInfo........................................................................................................................68
SoftwareDiskDefinition........................................................................................................68
SoftwareType.....................................................................................................................68
SoftwareTypeEnum.............................................................................................................68
StaticIPAddressRange.........................................................................................................68
StorageProvisioningType.....................................................................................................69
StorageProvisioningTypeEnum..............................................................................................69
StorageType......................................................................................................................69
StorageTypeEnum..............................................................................................................69
SubnetDetails....................................................................................................................69
SubnetInfo........................................................................................................................69
TemplateInfo.....................................................................................................................70
VirtualizationType...............................................................................................................70
VirtualizationTypeEnum.......................................................................................................70
VirtualSwitch.....................................................................................................................71
VmHost............................................................................................................................71
VmHostDataStore...............................................................................................................71
Workflow..........................................................................................................................71
WwnConnection................................................................................................................71
5 Exceptions...........................................................................................72
IOSoapException...............................................................................................................72
InvalidParameterException...................................................................................................72
LoadBalancerNotFoundException.........................................................................................72
LogicalLoadBalancerNotFoundException...............................................................................72
LogicalServerGroupNotFoundException................................................................................72
LogicalServerNotFoundException.........................................................................................72
LogicalServerNotFoundForServerException............................................................................72
NoServerPoolsAvailableException........................................................................................72
OrganizationNotFoundException.........................................................................................73
RequestNotFoundException.................................................................................................73
SanVolumeNotFoundException............................................................................................73
SanVolumeTemplateNotFoundException................................................................................73
ServerInUseException.........................................................................................................73
ServerPoolNotFoundException.............................................................................................73
ServerPoolNotFoundForResourceException.............................................................................73
ServerResourceNotFoundException.......................................................................................73
ServiceNotFoundException..................................................................................................73
SoftwareNotFoundException................................................................................................74
SubnetNotFoundException..................................................................................................74
TemplateNotFoundException...............................................................................................74
UserNotFoundException......................................................................................................74
6 Example Usage....................................................................................75
Physical Server Maintenance Example..................................................................................75
Contents 7
7 Sample Java Client...............................................................................76
Sample Code....................................................................................................................76
8 Sample VisualStudio/.NET/C# Client.....................................................81
II Chargeback API.......................................................................................84
9 Introduction..........................................................................................85
Chargeback SOAP API.......................................................................................................85
10 Accessing the Chargeback Web Service Interfaces..................................86
Accessing WSDL...............................................................................................................86
Security............................................................................................................................86
Authorization................................................................................................................86
11 Operations.........................................................................................87
Operations.......................................................................................................................87
Summary Usage Report.................................................................................................87
getServiceUsagePage................................................................................................87
Detailed Usage Report...................................................................................................87
getServiceUsageDetailedPage....................................................................................87
Aggregated Usage Report..............................................................................................88
getAggregatedServiceUsage......................................................................................88
12 Data model........................................................................................89
Period..............................................................................................................................90
PeriodType enum................................................................................................................90
ServiceFilter......................................................................................................................90
ServiceFilterAttribute enum..................................................................................................90
FilterOperator enum...........................................................................................................90
FilterConnector enum..........................................................................................................90
Paging.............................................................................................................................90
ServiceInformation.............................................................................................................91
ResourceUsageSummary.....................................................................................................91
ServerUsageSummary........................................................................................................91
DiskUsageSummary...........................................................................................................91
IpAddressUsageSummary...................................................................................................91
ServiceUsagePage.............................................................................................................92
ServiceUsageSummary.......................................................................................................92
AggregateServiceUsage.....................................................................................................92
ServiceUsageDetailPage.....................................................................................................92
ServiceUsageDetail............................................................................................................92
ResourceUsageDetail..........................................................................................................92
ServerUsageDetail.............................................................................................................92
DiskUsageDetail................................................................................................................93
IpAddressUsageDetail........................................................................................................93
13 Exceptions..........................................................................................94
AuthenticationException......................................................................................................94
AuthorizationException.......................................................................................................94
ChargebackDataBaseException...........................................................................................94
ChargebackException........................................................................................................94
InvalidDateFormatException................................................................................................94
InvalidFilterException..........................................................................................................94
InvalidPageIndexException..................................................................................................94
InvalidPageSizeException....................................................................................................94
PeriodStartDateGreaterThanEndDateException.......................................................................95
PeriodStartDateTooOldException..........................................................................................95
8 Contents
RequiredParameterException...............................................................................................95
14 Sample Python Client...........................................................................96
15 Sample Chargeback Usage Report......................................................107
A References.............................................................................................108
B Support and other resources....................................................................109
Information to collect before contacting HP...............................................................................109
How to contact HP................................................................................................................109
Registering for software technical support and update service.....................................................109
How to use your software technical support and update service.............................................109
Warranty information.......................................................................................................110
HP authorized resellers..........................................................................................................110
Documentation feedback.......................................................................................................110
Security bulletin and alert policy for non-HP owned software components....................................110
Subscribing to security bulletins..........................................................................................110
Related information...............................................................................................................111
Documentation and support..............................................................................................111
Matrix infrastructure orchestration documentation.............................................................111
Contents 9
Part I Matrix API
1 Introduction
HP CloudSystem Matrix is the industry’s first Converged Infrastructure platform that doubles
administrator productivity and reduces total cost of ownership (TCO) versus traditional infrastructures.
HP CloudSystem Matrix integrates silos of compute, storage, network, and facilities resources with
unified management to deliver a virtualized, highly automated environment. The HP Matrix
Operating Environment (Matrix OE) provides the automated provisioning, optimization, and
recovery management capabilities for HP CloudSystem Matrix.
This document describes the rich set of HP Matrix OE infrastructure orchestration (IO) interfaces
available to HP customers, partners, and integrators. These interfaces allow customers to integrate
Matrix OE into their business and IT operations processes. Partners and Integrators can use the
interfaces in combination with their own offerings to provide new, rich capabilities. HP is committed
to an industry open standard cloud services API, and submitted this content to the Distributed
Management Task Force (DMTF) Cloud Incubator, which has now been moved to the recently
formed DMTF Cloud Management Working Group.
The API and CLI interfaces were introduced in HP BladeSystem Matrix/Matrix OE (Insight Dynamics)
6.0, and are expected to be compatible with subsequent releases, but are subject to change due
to evolving standards. Future releases may include additional interfaces.
HP Matrix OE infrastructure orchestration provides extensive out-of-the-box functionality that is
pre-integrated with HP Insight Control and HP System Insight Manager software, including:
• A graphical designer used to create templates describing the architecture and requirements
of infrastructure services. These templates are published into a catalog.
• Self service users pick a particular template from the catalog and initiate the creation of an
infrastructure service from that template.
• Administrative users create pools containing blades, virtual machine hosts together with
associated storage and subnets. One or more pools are assigned to one or users and this
defines the potential set of resources that can be used in the processing of self service user
requests. Administrative users also can review, approve, or reject user requests.
• After creation of the service, the self-service user can further extend the service. For example,
add additional disk and server resources to the service. In non-peak periods server resources
can be deactivated, allowing those resources to be powered down, or used by another service.
• IO includes an embedded version of HP Operations Orchestration (OO) workflow engine.
This engine can be used by customers and partners to extend the capabilities of IO and to
allow IO operations to be integrated into the customer environment.
• All access to IO functionality is secured by username/password login and restricted by the
assigned role of the particular user.
◦ The most restrictive role, User, has access to published templates (or a subset) and their
own services. User requests are subject to approval by an Administrator.
◦ The Architect role extends the capability of User, allowing the creation and publication
of templates, as well as the provisioning of non-published templates to allow testing.
◦ The Organization Administrator role extends the role of Architect, and allows the viewing
and manipulation of all services owned by that organization. Organization Administrator
initiated operations do not need their own approval.
◦ The Service Provider Administrator role also extends the role of Architect, and allows the
viewing and manipulation of all services in the environment. Service Provider Administrator
initiated operations do not need their own approval.
11
Integration interface overview
Figure 1 HP Matrix Operating Environment Integration Interfaces
Figure 1 (page 12) depicts the set of integration interfaces allowing customers and partners to
integrate Matrix OE capabilities into their environment and products.
The integration interfaces include:
• Web Service Interfaces to initiate lifecycle operations on infrastructure services including
creation and deletion of services, and to view or modify an existing service. These operations
are also accessible via command line tools for use in scripts.
• Customizable OO workflows that are invoked during every IO operation. Customers can
modify these workflows to integrate Matrix OE with enterprise processes.
• Customer or Partner authored OO workflows that may be associated with a particular
infrastructure template and triggered as part of IO operations. For example, partners can use
these integrations to provide unique capabilities related to their applications or for differentiated
service management.
• Software deployment technology integration: Matrix infrastructure orchestration provides
out-of-the-box integration with HP server deployment technologies and VMware and Microsoft
Virtual Machine deployment technologies.
This document describes the Web Service Interfaces.
New features in 7.1 Update 1
The HP Matrix Operating Environment 7.1 Update 1 release includes a new v5 service endpoint
with interface extensions. The v1, v2, v3, and v4 endpoints continue to be served, so clients of
these interfaces remain compatible with the 7.1 Update 1 release.
12 Introduction
NOTE: The extensions in this section are not available in the v4 endpoint, which is included in
Matrix OE 7.1.
Interface extensions include:
• Floating IP address operations:
addFloatingIPAddress◦
◦ moveFloatingIPAddress
◦ removeFloatingIPAddress
◦ releaseFloatingIPAddress
◦ listUnassociatedFloatingIPAddresses
• Server snapshot operations:
createServerSnapshot◦
◦ deleteServerSnapshot
◦ revertServerSnapshot
◦ listServerSnapshots
• New Organization operations:
assignSoftwareToOrganization◦
◦ unassignSoftwareFromOrganization
• New data model classes:
CustomOsImageAttribute◦
◦ CustomStorageVolumeAttributes
◦ ServerSnapshot
• New attributes in the CustomTemplateAttributes class:
CustomOsImageAttribute◦
◦ CustomStorageVolumeAttribute
New features in 7.1
The HP Matrix Operating Environment 7.1 release includes a new v4 service endpoint with interface
extensions.
Interface extensions include:
• New Service operations:
powerCycleService◦
◦ deleteReplicaService
• A new addNewDiskToLogicalServerGroup operation
• New LogicalServer operations:
powerCycleLogicalServers◦
New features in 7.1 13
◦ editLogicalServers
◦ removeLogicalServers
• New CMS operations:
quiesceCms◦
◦ unquiesceCms
◦ getCmsQuiesceStatus
• LoadBalancer operations:
listLoadBalancers◦
◦ addLoadBalancer
◦ modifyLoadBalancer
◦ removeLoadBalancer
◦ addLoadBalancerCertificate
◦ removeLoadBalancerCertificate
◦ setLoadBalancerPassword
◦ unsetLoadBalancerPassword
• LogicalLoadBalancer operations:
createLogicalLoadBalancerGroup◦
◦ deleteLogicalLoadBalancerGroup
◦ addLogicalLoadBalancerGroupMember
◦ removeLogicalLoadBalancerGroupMember
• FirewallRuleGroup operations:
getFirewallRuleGroup◦
◦ addRuleToFirewallRuleGroup
◦ removeRuleFromFirewallRuleGroup
◦ syncFirewallRuleGroups
• New CustomTemplateAttributes parameter to the createService operation
• New attributes in the following classes:
LogicalServerGroupDetails◦
14 Introduction
– LogicalLoadBalancerDetails
– LogicalFirewallRuleGroup
◦ LogicalServerInfo
capacityPoolId–
– isInCloud
– serverType
◦ RequestInfo
◦ ServiceInfo
◦ TemplateInfo
Chargeback
HP Matrix OE infrastructure orchestration includes API extensions to retrieve chargeback usage
data, described in Part II “Chargeback API”. Client software can connect to the chargeback server
to build infrastructure resource allocation and usage reports for information on current and past
services.
Matrix infrastructure orchestration also includes a command line tool to retrieve chargeback usage
data. This tool generates an xml file containing chargeback data that can be opened in a browser
or using Microsoft Excel.
See the HP Developer Resource Center for CloudSystem Whitepapers tab for Creating customized
chargeback reports based on Matrix 7.1 CLI output files, and the Toolkits/Samples tab for
CloudSystem Matrix 7.1 Chargeback formatters.
For more information about using the chargeback feature, see the HP Matrix Operating Environment
Infrastructure Orchestration User Guide at http://www.hp.com/go/matrixoe/docs.
– maxMemorySize
– maxProcessorCount
manualCleanUpRequired–
DrPolicy–
– DrState
– isCustomizable
– DrPolicy
New features in 7.1 15
2 Accessing the Web Service Interfaces
Accessing WSDL
The Web Service Description Language or WSDL (See Reference [1]) definition of IO operations
can be accessed from any installed IO system using a web browser. For example, if the software
is installed on a server with an IP address of <cms-ip-address>, enter the following into the
web browser to access the WSDL:
https://<cms-ip-address>:51443/hpio/controller/soap/v5?wsdl
The browser will show the formal XML definition of the Web Service Interface. The IO API is already
available in the embedded Operations Orchestration when IO is installed.
Security
The IO Web Service is only accessible over HTTPS. The service uses WS-Security UsernameToken
authentication in text form. A username and password of a registered IO user is required to access
the Web Service Interface. A WS-Security timestamp header is also required.
Authorization
If the presented username/password belongs to a Windows user in the Service Provider
Administrator role, the web services are able to view and act on all services. For
username/passwords that belong to a Windows user in the Organization Administrator role, the
web services can operate only on the services owned by that organization. For username/passwords
that belong to Windows users in the Architect or User roles, the web services are only able to view
or act on the services owned by that particular user.
The Activate Service operation (and others) specifies a list of server pools from which the servers
will be allocated. The set of available pools is based on the assignments of the requesting user
(not the service owner). For Administrator users, all pools except Maintenance and Unassigned
are available.
Impersonation
An “Impersonation” feature allows an authenticated Administrator role user to perform an operation
in the context of a specified requesting user. This behavior can be used in the implementation of
enterprise service catalogs to initiate operations on behalf of enterprise users. Impersonation is
achieved by including an HP-IO-Impersonate cookie in the HTTP message header. For example, if
the request includes the HTTP header “Cookie: HP-IO-Impersonate=Steve”, the operation will be
performed as though it were requested by Steve. A message is written to the audit log to record
the impersonation event.
Command Line Interface
An IO installation includes an “ioexec” command line interface (CLI) to access the IO Web Service.
The CLI may be useful for scripting web service invocations and for testing purposes when
developing a web service client. The CLI operations and data model mirror the Web Service
Interface. The CLI may be copied from an IO installation to a different system to operate on the
CMS remotely. The “ioexec” command help provides specific usage details.
16 Accessing the Web Service Interfaces
3 Operations
The supported operations are specified in the following sections, grouped by target data type.
Version
getVersion
Gets the IO product version.getVersionName
noneParameters
Template
listTemplates
Returns
importTemplate
String versionReturns
IOSoapExceptionExceptions
listTemplatesName
noneParameters
List<TemplateInfo>
templates
IOSoapExceptionExceptions
importTemplateName
Product version string (e.g., “6.0.0”) or “Unknown” if the version cannot
be determined.
Gets a list of templates. If the template.access.restricted configuration is
set to “true” in the conf\hpio.properties file, the result for non-Administrator
users only includes templates to which they are assigned. Unpublished
templates are included in the result only for Administrator and Architect
users.
List of TemplateInfo objects containing basic information about the
templates.
Adds a template definition. This operation may be performed only by an
infrastructure orchestration Administrator or Architect.
exportTemplate
byte templateXml[]Parameters
boolean forceOverwrite
noneReturns
InvalidParameterExceptionExceptions
IOSoapException
exportTemplateName
InvalidParameterExceptionExceptions
A template definition encoded as an XML document, unmodified from a
template export operation.
If true, overwrites the definition of an existing template with more recent
modification.
Exports a template definition. This operation may be performed only by
an infrastructure orchestration Administrator or Architect.
The name of the template to export.String templateNameParameters
A template definition encoded as an XML document.byte[] templateXmlReturns
Version 17
deleteTemplate
TemplateNotFound
Exception
IOSoapException
Service
listServices
deleteTemplateName
noneReturns
InvalidParameterExceptionExceptions
TemplateNotFound
Exception
IOSoapException
listServicesName
noneParameters
IOSoapExceptionExceptions
Deletes an existing template. This operation may be performed only by
an infrastructure orchestration Administrator or Architect.
The name of the template to delete.String templateNameParameters
Gets a list of services owned by the requester. For Administrator users,
the list contains all services.
List of ServiceInfo objects containing basic information about the services.List<ServiceInfo> servicesReturns
getService
createService
ServiceDetails serviceReturns
InvalidParameterExceptionExceptions
ServiceNotFoundException
IOSoapException
createServiceName
LeasePeriod leasePeriod
Gets details of a specified service.getServiceName
The ID or name of the service for which to get details.String serviceNameParameters
Creates an infrastructure service from a template, with Administrator
approval.
The name of the new service to create.String serviceNameParameters
The name of the template to use in service creation.String templateName
New service lease period. A startEpoch value of null or a time in the past
is interpreted as the current time. An endEpoch value of null or 0 indicates
that the lease is open ended. Otherwise, the endEpoch must be greater
than both the startEpoch value and the current time.
18 Operations
String replacementText
String used to make the template hostnames unique. The string is
substituted for the # symbol used in the template element names. If no
such replacement is defined in the template, this value may be null.
List<String>
serverPoolNames
String
ownerEmailAddress
String note
String billingCode
customTemplateAttributes
InvalidParameterExceptionExceptions
NoServerPoolsAvailable
Exception
ServerPoolNotFound
Exception
Optional list of server pools used to create the service. If null, the pools
currently available to the requesting user are used.
Optional email address of the service owner (the user performing the
operation). If specified, the value replaces the user’s email address on
record. If the value is an empty string, any existing email address is
removed with no replacement. An email address update applies generally,
not just to the service created by this operation. The email address update
may take effect even if the CreateService operation is not submitted
successfully.
Optional descriptive text about the created service to be added to the
created service notes.
Optional text identifying the entity responsible for the service costs. The
value is limited to 128 characters and may not include the characters
[<>'`"&] or control characters.
Optional list of custom attributes.CustomTemplateAttributes
Request ID for the operation.String requestIdReturns
deleteService
deactivateService
TemplateNotFound
Exception
IOSoapException
InvalidParameterExceptionExceptions
ServiceNotFoundException
IOSoapException
deactivateServiceName
Deletes an infrastructure service.deleteServiceName
The ID or name of the service to delete.String serviceNameParameters
Request ID for the operation.String requestIdReturns
Deactivates all logical servers in an infrastructure service (existing at the
time of the request).
The ID or name of the service containing the logical servers to deactivate.String serviceNameParameters
Request ID for the operation.String requestIdReturns
InvalidParameterExceptionExceptions
ServiceNotFoundException
IOSoapException
Service 19
activateService
changeServiceLease
activateServiceName
List<String>
serverPoolNames
InvalidParameterExceptionExceptions
NoServerPoolsAvailable
Exception
ServerPoolNotFound
Exception
ServiceNotFound
Exception
IOSoapException
changeServiceLeaseName
Activates all logical servers in an infrastructure service (existing at the
time of the request).
The ID or name of the service containing the logical servers to activate.String serviceNameParameters
Optional list of server pools from which to allocate physical servers, if
necessary. If null, the pools currently available to the requesting user are
used.
Request ID for the operation.String requestIdReturns
Changes the start and/or end time of a service lease. Administrator
approval may be required.
powerOffService
LeasePeriod leasePeriod
InvalidParameterExceptionExceptions
ServiceNotFoundException
IOSoapException
powerOffServiceName
The ID or name of the service for which to change the lease period.String serviceNameParameters
New service lease period. A startEpoch or endEpoch value of null
indicates that the value shall not be changed. A new startEpoch and/or
endEpoch value must be specified. If the lease has not yet started, a
startEpoch in the past is considered to be “now”. If the lease has already
started, a non-null startEpoch value that differs from the time the lease
started results in an error. An endEpoch value of 0 indicates that the lease
is open ended. Otherwise, the endEpoch must be greater than both the
startEpoch value and the current time.
Request ID for the operation.String requestIdReturns
Powers off all logical servers in an infrastructure service (existing at the
time of the request).
The ID or name of the service containing the logical servers to power off.String serviceNameParameters
Request ID for the operation.String requestIdReturns
20 Operations
InvalidParameterExceptionExceptions
ServiceNotFoundException
IOSoapException
powerOnService
powerCycleService
powerOnServiceName
InvalidParameterExceptionExceptions
ServiceNotFoundException
IOSoapException
powerCycleServiceName
String serviceNameParameters
InvalidParameterExceptionExceptions
ServiceNotFoundException
IOSoapException
Powers on all logical servers in an infrastructure service (existing at the
time of the request).
The ID or name of the service containing the logical servers to power on.String serviceNameParameters
Request ID for the operation.String requestIdReturns
Power cycles all logical servers in an infrastructure service (existing at
the time of the request).
The ID or name of the service containing the logical servers to power
cycle.
Request ID for the operation.String requestIdReturns
deleteReplicaService
Request
listRequests
Returns
InvalidParameterExceptionExceptions
ServiceNotFoundException
IOSoapException
listRequestsName
noneParameters
requests
Deletes a DR (disaster recovery) replica service without deprovisioning.deleteReplicaServiceName
The ID or name of the service to delete.String serviceNameParameters
Delete the replica service regardless of its state.boolean ignoreStatus
Request ID for the operation.String requestIdReturns
Gets a list of requests initiated by the requester. For Administrator users,
the list contains all requests.
A List of RequestInfo objects containing request status information.List<RequestInfo>
IOSoapExceptionExceptions
Request 21
getRequestInfo
Gets status information about a specified request.getRequestInfoName
String requestIdParameters
InvalidParameterExceptionExceptions
RequestNotFoundException
IOSoapException
getRequest
String requestIdParameters
InvalidParameterExceptionExceptions
RequestNotFoundException
IOSoapException
setRequestApprovalState
The ID of the request for which to get status (returned when the action
was initiated).
A RequestInfo object containing the status of the request.RequestInfo requestReturns
Gets status and history information about a specified request.getRequestName
The ID of the request for which to get details (returned when the action
was initiated).
A RequestDetails object containing the details of the request.RequestDetails requestReturns
continueRequest
setRequestApprovalStateName
String requestIdParameters
String note
noneReturns
InvalidParameterExceptionExceptions
RequestNotFoundException
IOSoapException
continueRequestName
String note
Approves or rejects a request that is paused for approval. This operation
may be performed only by an infrastructure orchestration Administrator.
The ID of the request to approve or reject (returned when the action was
initiated).
Indicates whether the request is approved (true) or rejected (false).boolean approved
Optional note to be added to the request history when the approval state
is set.
Continues a paused request. This operation may be performed only by
an infrastructure orchestration Administrator.
The ID of the request to continue (returned when the action was initiated).String requestIdParameters
Optional note to be added to the request history when the request is
continued.
22 Operations
NoneReturns
InvalidParameterExceptionExceptions
cancelRequest
RequestNotFoundException
IOSoapException
Cancels a request, if allowed for the request type and status.cancelRequestName
The ID of the request to cancel (returned when the action was initiated).String requestIdParameters
String note
noneReturns
InvalidParameterExceptionExceptions
RequestNotFoundException
IOSoapException
Logical Server Group
getLogicalServerGroup
logicalServerGroupName
LogicalServerGroupDetailsReturns
logicalServerGroup
InvalidParameterExceptionExceptions
Optional note to be added to the request history on successful
cancellation.
Gets details of a specified logical server group.getLogicalServerGroupName
The ID or name of the service containing the logical server group.String serviceNameParameters
The name of the logical server group for which to get details.String
LogicalServerGroupNot
FoundException
ServiceNotFoundException
IOSoapException
addServersToLogicalServerGroup
Name
addServersToLogicalServer
Group
logicalServerGroupName
List<String>
serverPoolNames
InvalidParameterExceptionExceptions
LogicalServerGroupNot
FoundException
Adds logical servers to a logical server group to achieve a specified
target count (flex up), with Administrator approval.
The ID or name of service containing the logical server group.String serviceNameParameters
The name of the logical server group to adjust.String
The target number of logical servers in the group.int targetServerCount
Optional list of server pools used to fulfill the request. If null, the pools
currently available to the requesting user are used.
Request ID for the operation.String requestIdReturns
Logical Server Group 23
NoServerPoolsAvailable
Exception
ServerPoolNotFound
Exception
ServiceNotFoundException
IOSoapException
addDiskToLogicalServerGroup
Name
addDiskToLogicalServer
Group
logicalServerGroupName
String
stereotypeDiskName
InvalidParameterExceptionExceptions
LogicalDiskNotFound
Exception
LogicalServerGroupNot
FoundException
ServiceNotFoundException
IOSoapException
addNewDiskToLogicalServerGroup
Adds a data disk to a logical server group, with Administrator approval.
The new disk is based on an existing disk stereotype already in use by
the logical server group.
The ID or name of service containing the logical server group.String serviceNameParameters
The name of the logical server group to adjust.String
The name of a stereotype disk used by the logical server group. (It must
not be a boot disk.)
Request ID for the operation.String requestIdReturns
Name
addNewDiskToLogical
ServerGroup
logicalServerGroupName
String
stereotypeDiskName
Float cost
Boolean shared
List tags
RaidLevelEnum raidLevel
Adds a new data disk stereotype to a logical server group, with
Administrator approval. The disk type is automatically determined by the
logical server group type.
The ID or name of service containing the logical server group.String serviceNameParameters
The name of the logical server group to adjust.String
Optional. The name of the new disk stereotype to create. It must be unique
for the service. If not specified, a unique name will be auto-generated.
The size in GB for the new disk.Integer size
Optional. The cost per GB for the new disk. If not specified, or specified
by a non-admin user, a default cost will be calculated based on existing
disks in the server group. The units for the cost will be same as the units
used for the server group.
Optional. Mark the disk to be shared across the servers in the server
group. Certain server group configurations does not allow shared disks.
Defaults to not shared.
Optional. A list of storage tags. For physical disks only. Ignored for virtual
disks. For virtual disks, volume names are copied from the boot disk.
Optional. The raid level for the disk. Defaults to “any.” For physical disks
only. Ignored for virtual disks.
24 Operations
Boolean redundantPaths
Optional. Mark the disk as needing redundant SAN paths. Defaults to
single path. For physical disks only. Ignored for virtual disks.
RawMappingTypeEnum
rawMappingType
InvalidParameterExceptionExceptions
LogicalServerGroupNot
FoundException
ServiceNotFoundException
IOSoapException
Optional. The Raw Disk Mapping (RDM) type for the disk. Defaults to
NONE. For physical disks only. Ignored for virtual disks.
Request ID for the operation.String requestIdReturns
setLogicalServerGroupActiveServerCount
Name
setLogicalServerGroupActive
ServerCount
Activates or deactivates logical servers as necessary to achieve a target
number of active logical servers in a logical server group. The existing
number of active logical servers is evaluated against the target. If they
are the same, no action is taken. If the target is greater, the required
number of logical servers in a DEACTIVATED state is activated. If the
target is less, the required number of logical servers in an UP state is
deactivated. No logical servers are added to the logical server group in
any case. (Note that the logical servers to be affected may be selected
before the operation is processed, so an independent operation may
cause the resulting active server count to differ from what was requested.)
The ID or name of the service containing the logical server group.String serviceNameParameters
logicalServerGroupName
boolean
acceptPartialResult
List<String>
serverPoolNames
String requestIdReturns
InvalidParameterExceptionExceptions
LogicalServerGroupNot
FoundException
NoServerPoolsAvailable
Exception
ServerPoolNotFound
Exception
ServiceNotFoundException
IOSoapException
The name of the logical server group.String
The target number of active logical servers.int targetServerCount
Accept a partial result when too few logical servers are available to
achieve the target count. If false, an error is returned in this case and the
operation is not partially performed.
Optional list of server pools from which to allocate physical servers, if
necessary. If null, the pools currently available to the requesting user are
used.
Request ID for the operation, or an empty string may be returned if no
change is initiated.
Logical Server Group 25
Logical Server
findLogicalServer
Returns
getLogicalServer
findLogicalServerName
String hostIdParameters
LogicalServerInfo
logicalServer
InvalidParameterExceptionExceptions
LogicalServerNotFoundFor
ServerException
IOSoapException
Gets information about the logical server associated with a hostname or
IP address.
The fully-qualified hostname or IP address of the logical server to look
up. If hostId is an IP address, the search will be successful if the IP address
is equivalent to a LogicalIPAddress referenced by a LogicalServer’s
LogicalNetworkInterface. If hostId is a host name, the search will be
successful if the host name differs only by case from the host name of a
LogicalServer or if one of the IP addresses returned by a name service
lookup is equivalent to a LogicalIPAddress referenced by a LogicalServer’s
LogicalNetworkInterface.
Basic information about the logical server associated with the specified
hostname or IP address.
Gets details of a specified logical server.getLogicalServerName
The ID or name of the service containing the logical server.String serviceNameParameters
logicalServerName
LogicalServerDetailsReturns
logicalServer
InvalidParameterExceptionExceptions
LogicalServerNotFound
Exception
ServiceNotFoundException
IOSoapException
deactivateLogicalServers
logicalServerNames
InvalidParameterExceptionExceptions
The name of the logical server for which to get details.String
Deactivates selected logical servers in an infrastructure service.deactivateLogicalServersName
The ID or name of the service containing the logical servers to deactivate.String serviceNameParameters
A list of names of logical servers to deactivate.List<String>
Request ID for the operation.String requestIdReturns
26 Operations
LogicalServerNotFound
Exception
ServiceNotFoundException
IOSoapException
activateLogicalServers
logicalServerNames
Activates selected logical servers in an infrastructure service.activateLogicalServersName
The ID or name of the service containing the logical servers to activate.String serviceNameParameters
A list of names of logical servers to activate.List<String>
List<String>
serverPoolNames
InvalidParameterExceptionExceptions
LogicalServerNotFound
Exception
NoServerPoolsAvailable
Exception
ServerPoolNotFound
Exception
ServiceNotFoundException
IOSoapException
powerOffLogicalServers
logicalServerNames
Optional list of server pools from which to allocate physical servers, if
necessary. If null, the pools currently available to the requesting user are
used.
Request ID for the operation.String requestIdReturns
Powers off one or more logical servers.powerOffLogicalServersName
The ID or name of service containing the logical servers.String serviceNameParameters
A list of names of logical servers to power off.List<String>
InvalidParameterExceptionExceptions
LogicalServerNotFound
Exception
ServiceNotFoundException
IOSoapException
powerOnLogicalServers
logicalServerNames
InvalidParameterExceptionExceptions
LogicalServerNotFound
Exception
Request ID for the operation.String requestIdReturns
Powers on one or more logical servers.powerOnLogicalServersName
The ID or name of service containing the logical servers.String serviceNameParameters
A list of names of logical servers to power on.List<String>
Request ID for the operation.String requestIdReturns
Logical Server 27
ServiceNotFoundException
IOSoapException
powerCycleLogicalServers
logicalServerNames
InvalidParameterExceptionExceptions
LogicalServerNotFound
Exception
ServiceNotFoundException
IOSoapException
editLogicalServers
Power cycles one or more logical servers.powerCycleLogicalServersName
The ID or name of service containing the logical servers.String serviceNameParameters
A list of names of logical servers to power cycle.List<String>
Request ID for the operation.String requestIdReturns
editLogicalServersName
logicalServerNames
Integer memorySize
ByteSizeEnum
memorySizeUnits
Integer processorCount
InvalidParameterExceptionExceptions
LogicalServerNotFound
Exception
ServiceNotFoundException
IOSoapException
Updates the memory size and/or processor count for one or more logical
servers, with Administrator approval.
The ID or name of the service containing the logical servers.String serviceNameParameters
A list of names of logical servers to update.List<String>
The memory size to set for the logical servers, in the units specified by
memorySizeUnits. If not specified, the memory size is not changed.
The units for the memory size value. The specified memory size and units
must be convertible to a whole number value in the memory size units
for the existing logical server.
The processor count to set for the logical servers. If not specified, the
processor count is not changed.
Request ID for the operation.String requestIdReturns
removeLogicalServers
28 Operations
removeLogicalServersName
logicalServerNames
Deprovisions and removes selected logical servers from an infrastructure
service.
The ID or name of the service containing the logical servers.String serviceNameParameters
A list of names of logical servers to remove.List<String>
Request ID for the operation.String requestIdReturns
syncLogicalServers
InvalidParameterExceptionExceptions
LogicalServerNotFound
Exception
ServiceNotFoundException
IOSoapException
Server Pool
listServerPools
syncLogicalServersName
noneParameters
noneReturns
IOSoapExceptionExceptions
listServerPoolsName
noneParameters
IOSoapExceptionExceptions
Causes IO to resynchronize the state of the logical servers that IO is
managing with the current state of the logical servers in Matrix OE
visualization. This operation runs asynchronously, returning before the
synchronization has completed. This operation may be performed only
by an infrastructure orchestration Administrator.
Gets a list of names of the server pools available to the user. For
infrastructure orchestration Administrators, the list contains all server pools
including the Maintenance and Unassigned pools.
Names of the server pools for the requesting user.List<String> serverPoolsReturns
getServerPool
createServerPool
InvalidParameterExceptionExceptions
ServerPoolNotFound
Exception
IOSoapException
createServerPoolName
String serverPoolNameParameters
Gets details of a specified server pool.getServerPoolName
The name of the server pool to get.String serverPoolNameParameters
Details of the server pool contents and configuration.SanVolume serverPoolReturns
Creates an empty server pool. This operation may be performed only by
an infrastructure orchestration Administrator or Organization
Administrator.
The name of the server pool to create. It is limited to 64 characters
(alphanumeric, hyphen, underscore, and space).
Optional annotation to be attached to the server pool.String note
Server Pool 29
deleteServerPool
noneReturns
InvalidParameterExceptionExceptions
IOSoapException
deleteServerPoolName
NoneReturns
InvalidParameterExceptionExceptions
ServerPoolNotFound
Exception
IOSoapException
moveServerToServerPool
moveServerToServerPoolName
Parameters
destinationPoolName
String serverResourceId
Deletes an existing server pool. Any servers in the server pool are moved
to the "Unassigned" pool. This operation may be performed only by an
infrastructure orchestration Administrator or Organization Administrator.
The name of the server pool to delete.String serverPoolNameParameters
Moves a server to a different server pool. This operation may be
performed only by an infrastructure orchestration Administrator or
Organization Administrator.
The name of the server pool to which the server is to be moved.String
The resource ID of the server to be moved. (For example, the
LogicalServerInfo.resourceBindingId value when
LogicalServerInfo.isVirtual=false.)
String note
noneReturns
InvalidParameterExceptionExceptions
ServerPoolNotFound
Exception
ServerPoolNotFoundFor
ResourceException
IOSoapException
assignUsersToServerPool
assignUsersToServerPoolName
List<String> userNames
noneReturns
Optional annotation to be attached to the resource move. This note used
only when the destination pool is the Maintenance pool.
Assigns user access to a server pool. This operation may be performed
only by an infrastructure orchestration Administrator or Organization
Administrator.
The name of the server pool to which to assign user access.String serverPoolNameParameters
A list of the names of users and Active Directory groups for which to allow
server pool access.
30 Operations
InvalidParameterExceptionExceptions
Loading...