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
ServerPoolNotFound
Exception
UserNotFoundException
IOSoapException
unassignUsersFromServerPool
Name
Server
getComputeServer
unassignUsersFromServer
Pool
List<String> userNames
noneReturns
InvalidParameterExceptionExceptions
ServerPoolNotFound
Exception
UserNotFoundException
IOSoapException
getComputeServerName
Removes 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 from which to remove user access.String serverPoolNameParameters
A list of the names of users and Active Directory groups for which to
remove server pool access.
Gets details of a specified compute server. Cannot be used to get
information about a VM host.
The ID of the server resource for which to get details.String serverIdParameters
Returns
getVmHost
Server resource details.ComputeServer
computeServer
InvalidParameterExceptionExceptions
ServerResourceNotFound
Exception
IOSoapException
Gets details of a specified VM host.getVmHostName
The ID of the VM host for which to get details.String serverIdParameters
VM host resource details.VmHost vmHostReturns
InvalidParameterExceptionExceptions
ServerResourceNotFound
Exception
IOSoapException
Server 31
Software
listSoftware
Returns
getSoftware
Returns
listSoftwareName
noneParameters
List<DeployableSoftware>
software
IOSoapExceptionExceptions
getSoftwareName
software
InvalidParameterExceptionExceptions
SoftwareNotFoundException
IOSoapException
Gets a list of software available for deployment. This operation may be
performed only by an infrastructure orchestration Administrator,
organization Administrator, or Architect.
List of DeployableSoftware objects containing information about software
resources.
Gets information about a specified deployable software image. This
operation may be performed only by an infrastructure orchestration
Administrator, organization Administrator, or Architect.
The ID of the software to get.String softwareIdParameters
A DeployableSoftware object containing information about the software.DeployableSoftware
Subnet
listSubnets
getSubnet
listSubnetsName
noneParameters
IOSoapExceptionExceptions
getSubnetName
InvalidParameterExceptionExceptions
SubnetNotFoundException
Gets a list of subnets available to the user. This operation may be
performed only by an infrastructure orchestration Administrator or Architect
or an Organization Administrator.
List of SubnetInfo objects containing information about network resources.List<SubnetInfo> subnetsReturns
Gets details of a specified subnet. This operation may be performed only
by an infrastructure orchestration Administrator or Architect or an
Organization Administrator.
The ID of the subnet for which to get details.String subnetIdParameters
A SubnetDetails object containing the details of the subnet.SubnetDetails subnetReturns
32 Operations
IOSoapException
Storage
listSanVolumes
listSanVolumesName
noneParameters
Returns
sanVolumes
IOSoapExceptionExceptions
getSanVolume
getSanVolumeName
InvalidParameterExceptionExceptions
SanVolumeNotFound
Exception
IOSoapException
listSanVolumeTemplates
Gets a list of SAN volume resources. This operation may be performed
only by an infrastructure orchestration Administrator.
List of SanVolume objects containing information about storage resources.List<SanVolume>
Gets information about a specified SAN volume. This operation may be
performed only by an infrastructure orchestration Administrator.
The ID of the SAN volume to get.String sanVolumeIdParameters
A SanVolume object containing the details of the SAN volume.SanVolume sanVolumeReturns
listSanVolumeTemplatesName
noneParameters
Returns
List<SanVolumeTemplate>
sanVolumeTemplates
IOSoapExceptionExceptions
getSanVolumeTemplate
getSanVolumeTemplateName
Parameters
sanVolumeTemplateId
Returns
SanVolumeTemplate
sanVolumeTemplate
InvalidParameterExceptionExceptions
SanVolumeTemplateNot
FoundException
IOSoapException
Gets a list of SAN volume templates. This operation may be performed
only by an infrastructure orchestration Administrator or Architect.
List of SanVolumeTemplate objects containing information about storage
templates.
Gets information about a specified SAN volume template. This operation
may be performed only by an infrastructure orchestration Administrator
or Architect.
The ID of the SAN volume template to get.String
A SanVolumeTemplate object containing the details of the SAN volume
template.
Storage 33
Organization
listOrganizations
Returns
getOrganization
Parameters
Returns
listOrganizationsName
noneParameters
organizations
IOSoapExceptionExceptions
getOrganizationName
organizationName
Organization
organization
InvalidParameterExceptionExceptions
OrganizationNotFound
Exception
IOSoapException
Gets a list of existing organizations. This operation may be performed
only by a Service Provider Administrator.
A list of Organization objects representing the organizations defined.List<Organization>
Gets information about a specified organization. This operation may be
performed only by a Service Provider Administrator.
The ID or name of the organization for which to get information.String
An Organization object containing information about the specified
organization.
assignTemplateToOrganization
Name
assignTemplateTo
Organization
organizationName
noneReturns
InvalidParameterExceptionExceptions
Exception
OrganizationNotFound
Exception
IOSoapException
unassignTemplateFromOrganization
Assigns a template to an organization. A single template may be
assigned to multiple organizations. It also remains in the Service Provider
template set. The operation has no effect if the template is already
assigned to the organization. This operation may be performed only by
a Service Provider Administrator.
The template to be assigned to an organization.String templateNameParameters
The ID or name of the organization to which to assign the template.String
No template exists with given template name.TemplateNotFound
Name
34 Operations
unassignTemplateFrom
Organization
Unassigns a template from an organization. The operation has no effect
if the template is not assigned to the organization. A template may be
organizationName
noneReturns
InvalidParameterExceptionExceptions
Exception
OrganizationNotFound
Exception
IOSoapException
assignServerToOrganization
unassigned even if services in the organization were created from it. This
operation may be performed only by a Service Provider Administrator.
The template to be unassigned from an organization.String templateNameParameters
The ID or name of the organization from which to unassign the template.String
No template exists with given template name.TemplateNotFound
assignServerToOrganizationName
String
organizationName
noneReturns
InvalidParameterExceptionExceptions
ServerInUseException
ResourceException
OrganizationNotFound
Exception
IOSoapException
unassignServerFromOrganization
Name
unassignServerFrom
Organization
Assigns a compute resource to an organization. The compute resource
must be in the Service Provider Unassigned pool and must not be in use.
It is moved out of the Service Provider Unassigned pool and into the
organization Unassigned pool. This operation may be performed only
by a Service Provider Administrator.
The compute resource to be assigned.String serverResourceIdParameters
The ID or name of the organization to which to assign the compute
resource.
The resource is not in the Unassigned pool.ServerPoolNotFoundFor
Unassigns a compute resource from an organization. The compute
resource must be in the organization Unassigned pool and must not be
in use. It is moved out of the organization Unassigned pool and into the
Service Provider Unassigned pool. This operation may be performed
only by a Service Provider Administrator.
String
organizationName
noneReturns
InvalidParameterExceptionExceptions
ServerInUseException
ResourceException
The compute resource to be unassigned.String serverResourceIdParameters
The ID or name of the organization from which to unassign the compute
resource.
The resource is not in the Unassigned pool.ServerPoolNotFoundFor
Organization 35
OrganizationNotFound
Exception
IOSoapException
assignSubnetToOrganization
assignSubnetToOrganizationName
organizationName
noneReturns
InvalidParameterExceptionExceptions
OrganizationNotFound
Exception
IOSoapException
unassignSubnetFromOrganization
Name
unassignSubnetFrom
Organization
Assigns a subnet to an organization. A single subnet may be assigned
to multiple organizations. It also remains in the Service Provider subnet
set. The operation has no effect if the subnet is already assigned to the
organization. This operation may be performed only by a Service Provider
Administrator.
The subnet to be assigned to an organization.String subnetIdParameters
The ID or name of the organization to which to assign the subnet.String
No subnet exists with given subnet ID.SubnetNotFoundException
Unassigns a subnet from an organization. The operation has no effect
if the subnet is not assigned to the organization. A subnet may be
unassigned even if services in the organization are using it. This operation
may be performed only by a Service Provider Administrator.
organizationName
noneReturns
InvalidParameterExceptionExceptions
OrganizationNotFound
Exception
IOSoapException
assignSoftwareToOrganization
assignSoftwareToOrganizationName
organizationName
The subnet to be unassigned from an organization.String subnetIdParameters
The ID or name of the organization from which to unassign the subnet.String
No subnet exists with given subnet ID.SubnetNotFoundException
Assigns software to an organization. A single software image can be
assigned to multiple organizations. It also remains in the Service Provider
software set. The operation has no effect if the software is already
assigned to the organization. This operation may be performed only by
a Service Provider Administrator.
The software to be assigned to an organization.String softwareIdParameters
The ID or name of the organization to which to assign the software.String
36 Operations
noneReturns
InvalidParameterExceptionExceptions
OrganizationNotFound
Exception
IOSoapException
unassignSoftwareFromOrganization
No software exists with the given software ID.SoftwareNotFoundException
Name
syncOrganizations
unassignSoftwareFrom
Organization
organizationName
noneReturns
InvalidParameterExceptionExceptions
OrganizationNotFound
Exception
IOSoapException
syncOrganizationsName
Unassigns software from an organization. The operation has no effect if
the software is not assigned to the organization. Software may be
unassigned even if services in the organization are using it. This operation
may be performed only by a Service Provider Administrator.
The software to be unassigned from an organization.String softwareIdParameters
The ID or name of the organization from which to unassign the software.String
No software exists with the given software ID.SoftwareNotFoundException
Synchronizes changes made to organization local groups outside of the
infrastructure orchestration organization portal. This ensures any changes
to organization membership are preserved in the event of a migration.
Perform this operation after all changes to local organization groups are
completed. This operation may be performed only by an infrastructure
orchestration Administrator.
noneParameters
noneReturns
IOSoapExceptionExceptions
CMS
beginCmsMaintenance
beginCmsMaintenanceName
noneReturns
InvalidParameterExceptionExceptions
IOSoapException
Puts a CMS in maintenance mode in a federated environment. This
operation may be performed only by an infrastructure orchestration
Administrator.
The fully-qualified domain name of the CMS to put in maintenance mode.String cmsNameParameters
CMS 37
endCmsMaintenance
endCmsMaintenanceName
String cmsNameParameters
noneReturns
InvalidParameterExceptionExceptions
IOSoapException
countRunningRequestsForCms
Name
CountRunningRequestsFor
Cms
String cmsNameParameters
InvalidParameterExceptionExceptions
IOSoapException
Takes a CMS out of maintenance mode in a federated environment. This
operation may be performed only by an infrastructure orchestration
Administrator.
The fully-qualified domain name of the CMS to take out of maintenance
mode.
Counts the number of requests running on a CMS in maintenance mode.
This operation may be performed only by an infrastructure orchestration
Administrator.
The fully-qualified domain name of the CMS for which to count running
requests.
The number of requests currently running on the specified CMS.int numRunningRequestsReturns
addCms
quiesceCms
unquiesceCms
addCmsName
noneReturns
InvalidParameterExceptionExceptions
IOSoapException
quiesceCmsName
noneParameters
noneReturns
IOSoapExceptionExceptions
Notify infrastructure orchestration of a CMS added to the federation. This
operation may be performed only by an infrastructure orchestration
Administrator.
The fully-qualified domain name of the CMS added to the federation.String cmsNameParameters
Quiesces the CMS. This operation may be performed only by an
infrastructure orchestration Administrator.
38 Operations
unquiesceCmsName
noneParameters
Removes the CMS from the quiesced state. This operation may be
performed only by an infrastructure orchestration Administrator.
noneReturns
IOSoapExceptionExceptions
getCmsQuiesceStatus
Returns
LoadBalancer
listLoadBalancers
Returns
addLoadBalancer
getCmsQuiesceStatusName
noneParameters
cmsQuiesceStatus
IOSoapExceptionExceptions
listLoadBalancersName
noneParameters
List<LoadBalancerInfo>
loadBalancers
IOSoapExceptionExceptions
Gets the current quiesce status of the CMS. This operation may be
performed only by an infrastructure orchestration Administrator.
The current quiesce state.CmsQuiesceStatus
Gets a list of load balancer resources. This operation may be performed
only by an infrastructure orchestration Administrator.
A list of LoadBalancerInfo objects containing information about load
balancer resources.
Parameters
modifyLoadBalancer
Parameters
Exceptions
addLoadBalancerName
loadBalancer
noneReturns
InvalidParameterExceptionExceptions
IOSoapException
modifyLoadBalancerName
LoadBalancerInfo
loadBalancer
noneReturns
LoadBalancerNotFound
Exception
InvalidParameterException
Adds a load balancer to the infrastructure orchestration server. This
operation may be performed only by an infrastructure orchestration
Administrator.
The load balancer definition.LoadBalancerInfo
Modifies an existing load balancer to the infrastructure orchestration
server. This operation may be performed only by an infrastructure
orchestration Administrator.
The load balancer definition. Contains only the load balancer ID and the
attributes to be changed. All other attributes are set to null.
IOSoapException
LoadBalancer 39
removeLoadBalancer
removeLoadBalancerName
noneReturns
Exceptions
LoadBalancerNotFound
Exception
InvalidParameterException
IOSoapException
addLoadBalancerCertificate
addLoadBalancerCertificateName
noneReturns
InvalidParameterExceptionExceptions
Removes a load balancer from the infrastructure orchestration server. This
operation may be performed only by an infrastructure orchestration
Administrator.
The ID of the load balancer to remove.String loadBalancerIdParameters
Adds the certificate for a load balancer corresponding to a certificate
ID. This operation may be performed only by an infrastructure
orchestration Administrator.
The certificate ID of a load balancer.String certificateIdParameters
The certificate to be added.byte[] certificate
IOSoapException
removeLoadBalancerCertificate
Name
removeLoadBalancer
Certificate
noneReturns
CertificateNotFoundExceptionExceptions
InvalidParameterException
IOSoapException
setLoadBalancerPassword
setLoadBalancerPasswordName
Removes the certificate for a load balancer corresponding to a certificate
ID. This operation may be performed only by an infrastructure
orchestration Administrator.
The certificate ID of a load balancer.String certificateIdParameters
Sets the password for a load balancer corresponding to a password ID.
This operation may be performed only by an infrastructure orchestration
Administrator.
The password ID of a load balancer.String passwordIdParameters
40 Operations
The password of the load balancer.String password
noneReturns
InvalidParameterExceptionExceptions
IOSoapException
unsetLoadBalancerPassword
unsetLoadBalancerPasswordName
noneReturns
PasswordNotFoundExceptionExceptions
InvalidParameterException
IOSoapException
LogicalLoadBalancer
createLogicalLoadBalancerGroup
Name
createLogicalLoadBalancer
Group
logicalLoadBalancerId
Unsets the password for a load balancer corresponding to a password
ID. This operation may be performed only by an infrastructure
orchestration Administrator.
The password ID of a load balancer.String passwordIdParameters
Creates a group in a logical load balancer defined in an infrastructure
orchestration service, with Administrator approval. A group describes a
service to load balance. A load balancer will forward incoming requests
to members, after members are added to a group.
The ID or name of the service where to add a group.String serviceNameParameters
The logical load balancer ID.String
Info group
InvalidParameterExceptionExceptions
ServiceNotFoundException
LogicalLoadBalancerNot
FoundException
IOSoapException
deleteLogicalLoadBalancerGroup
Name
deleteLogicalLoadBalancer
Group
logicalLoadBalancerId
InvalidParameterExceptionExceptions
The information defining a logical load balancer group.LogicalLoadBalancerGroup
Request ID for the operation.String requestIdReturns
Deletes a group from an infrastructure orchestration service. All the existing
members within the group will be removed.
The ID or name of the service where to delete a group.String serviceNameParameters
The logical load balancer ID.String
The name of the group to be deleted.String groupName
Request ID for the operation.String requestIdReturns
ServiceNotFoundException
LogicalLoadBalancer
NotFoundException
IOSoapException
LogicalLoadBalancer 41
addLogicalLoadBalancerGroupMember
Name
addLogicalLoadBalancer
GroupMember
logicalLoadBalancerId
String address
InvalidParameterExceptionExceptions
ServiceNotFoundException
LogicalLoadBalancerNot
FoundException
IOSoapException
Adds a member to a logical load balancer group defined in an
infrastructure orchestration service.
The ID or name of the service which contains the group.String serviceNameParameters
The logical load balancer ID.String
The group name where to add the new member.String groupName
The IP address or host name of the member to be added to the load
balancer group.
The port on which the member is listening.int port
Request ID for the operation.String requestIdReturns
removeLogicalLoadBalancerGroupMember
Name
removeLogicalLoadBalancer
GroupMember
Removes a member from a logical load balancer group defined in an
infrastructure orchestration service.
FirewallRuleGroup
getFirewallRuleGroup
Parameters
logicalLoadBalancerId
String address
InvalidParameterExceptionExceptions
ServiceNotFoundException
LogicalLoadBalancer
NotFoundException
IOSoapException
firewallRuleGroupId
The ID or name of the service which contains the group.String serviceNameParameters
The logical load balancer ID.String
The group name which contains the member to be removed.String groupName
The IP address or host name of the member to be removed from the load
balancer group.
Request ID for the operation.String requestIdReturns
Gets the details of a specified firewall rule group.getFirewallRuleGroupName
The ID of the firewall rule group to get.String
Returns
42 Operations
Details of the firewall rule group.FirewallRuleGroupDetails
firewallRuleGroup
Exceptions
FirewallRuleGroupNotFound
Exception
InvalidParameterException
IOSoapException
addRuleToFirewallRuleGroup
Name
Parameters
Exceptions
addRuleToFirewallRule
Group
firewallRuleGroupId
noneReturns
FirewallRuleGroupNotFound
Exception
InvalidParameterException
IOSoapException
removeRuleFromFirewallRuleGroup
Name
Parameters
removeRuleFromFirewall
RuleGroup
firewallRuleGroupId
FirewallRule firewallRule
Add a rule to an existing firewall rule group in the inventory and in the
underlying resource.
The ID of the firewall rule group in which to add a rule.String
The firewall rule to be added.FirewallRule firewallRule
Remove a rule from an existing firewall rule group in the inventory and
in the underlying resource.
The ID of the firewall rule group from which to remove a rule.String
The firewall rule to be removed. All attributes of the specified FirewallRule
must match an existing rule for it to be identified and removed.
noneReturns
Exceptions
FirewallRuleGroupNotFound
Exception
FirewallRuleNotFound
Exception
InvalidParameterException
IOSoapException
syncFirewallRuleGroups
syncFirewallRuleGroupsName
noneParameters
noneReturns
IOSoapExceptionExceptions
Causes IO to resynchronize the firewall rules of the firewall rule group
IO is managing. This operation runs asynchronously, returning before
the synchronization has completed. This operation may be performed
only by an infrastructure orchestration Administrator.
FirewallRuleGroup 43
FloatingIPAddress
addFloatingIPAddress
addFloatingIPAddressName
logicalServerName
String
logicalNetworkInterface
Name
InvalidParameterExceptionExceptions
ServiceNotFoundException
LogicalServerNotFound
Exception
IOSoapException
moveFloatingIPAddress
Acquires a floating IP address and adds it to a specified logical server,
with Administrator approval. The lifecycle of a floating IP address is
independent from the server to which it is added, allowing it to be moved
between servers. A floating IP address should be removed explicitly when
it is no longer needed.
The ID or name of the service containing the logical server.String serviceNameParameters
The name of the logical server to which to add the floating IP address.String
The name of the network interface to which to add the floating IP address.
This parameter is optional if the logical server has only one network
interface.
Request ID for the operation.String requestIdReturns
moveFloatingIPAddressName
logicalServerName
String
logicalNetworkInterface
Name
InvalidParameterExceptionExceptions
ServiceNotFoundException
LogicalServerNotFound
Exception
IOSoapException
removeFloatingIPAddress
removeFloatingIPAddressName
Moves a floating IP address to a specified logical server, removing it
from another server if necessary. Administrator approval is required unless
the address is already in use by a service with the same owner as the
target service.
The ID or name of the service containing the logical server.String serviceNameParameters
The name of the logical server to which to move the floating IP address.String
The name of the network interface to which to move the floating IP
address. This parameter is optional if the logical server has only one
network interface.
Request ID for the operation.String requestIdReturns
Removes a floating IP address from a logical server and releases it
permanently.
44 Operations
String
logicalServerName
The ID or name of the service containing the logical server.String serviceNameParameters
The name of the logical server from which to remove the floating IP
address.
InvalidParameterExceptionExceptions
ServiceNotFoundException
LogicalServerNotFound
Exception
IOSoapException
releaseFloatingIPAddress
The floating IP address to remove.String ipAddress
Request ID for the operation.String requestIdReturns
releaseFloatingIPAddressName
Parameters
cloudCapacityPoolId
InvalidParameterExceptionExceptions
ServerResourceNotFound
Exception
IOSoapException
listUnassociatedFloatingIPAddresses
Name
Parameters
listUnassociatedFloating
IPAddresses
String
cloudCapacityPoolId
Permanently releases a floating IP address that is not associated to a
server. This operation may be performed only by an infrastructure
orchestration Administrator.
The ID of a cloud capacity pool in which the floating IP address exists.String
The floating IP address to release.String ipAddress
Request ID for the operation.noneReturns
Returns a list of floating IP addresses in a cloud capacity pool that are
not associated with a server.
The ID of the cloud capacity pool for which to list unassociated floating
IP addresses.
A list of unassociated floating IP addresses.List<String> ipAddressesReturns
ServerSnapshot
listServerSnapshots
Returns
InvalidParameterExceptionExceptions
ServerResourceNotFound
Exception
IOSoapException
Retrieves a list of snapshots for a server. Supported only for ESX VMs.listServerSnapshotsName
The ID or name of the service containing the logical server.String serviceNameParameters
The name of the logical server for which to retrieve snapshot information.String
logicalServerName
A list of snapshots for the servers.List<ServerSnapshot>
snapshots
InvalidParameterExceptionExceptions
ServerSnapshot 45
ServiceNotFoundException
LogicalServerNotFound
Exception
IOSoapException
createServerSnapshot
revertServerSnapshot
createServerSnapshotName
logicalServerName
Boolean
includeMemoryState
Boolean
quiesceFileSystem
InvalidParameterExceptionExceptions
ServiceNotFoundException
LogicalServerNotFound
Exception
IOSoapException
Creates a snapshot of the current state of a server, with Administrator
approval. Supported only for ESX VMs.
The ID or name of the service containing the logical server.String serviceNameParameters
The name of the logical server for which to create a snapshot.String
The name to assign to the new snapshot.String snapshotName
Indicates whether to include the server memory state in the snapshot if
the server is running. Defaults to true.
Indicates whether to ensure the snapshot represents a consistent file system
state if the server is running. Defaults to false.
Request ID for the operation.String requestIdReturns
deleteServerSnapshot
logicalServerName
Boolean
suppressPowerOn
InvalidParameterExceptionExceptions
ServiceNotFoundException
LogicalServerNotFound
Exception
IOSoapException
deleteServerSnapshotName
Reverts a server to a specified snapshot. Supported only for ESX VMs.revertServerSnapshotName
The ID or name of the service containing the logical server.String serviceNameParameters
The name of the logical server for which to revert a snapshot.String
The ID or name of the snapshot to which to revert.String snapshotName
Indicates whether the server should be left powered off even if it was
powered on when the snapshot was created. Defaults to false.
Request ID for the operation.String requestIdReturns
Deletes a server snapshot and optionally its child snapshots. Supported
only for ESX VMs.
The ID or name of the service containing the logical server.String serviceNameParameters
46 Operations
logicalServerName
The name of the logical server for which to delete a snapshot.String
The ID or name of the snapshot to delete.String snapshotName
Boolean removeChildren
InvalidParameterExceptionExceptions
ServiceNotFoundException
LogicalServerNotFound
Exception
IOSoapException
Indicates whether to also delete the child snapshots of the specified
snapshot, recursively. Defaults to false.
Request ID for the operation.String requestIdReturns
ServerSnapshot 47
4 Data Model
The complex data types that are used in the API operation definitions are defined here.
The Service data model incorporates many of the data types defined here. Figure 2 (page 48)
shows the relationships between the major data types from a Service perspective, using Unified
Modeling Language (UML) notation. Some of the data classes are separated into “Info” and
“Details” classes, where the Details class extends the Info class. For example, the Service data type
shown in Figure 2 represents the ServiceDetails class which extends ServiceInfo. This separation
allows some operations (such as List) to return high-level data and others (like Get) to return deep
containment data.
Figure 2 Service Data Model
The data model is designed to avoid indirect references. This design is intended to simplify data
processing and it allows Service subcomponents, such as LogicalServer, to be self-contained. An
outcome of this choice is that Service data may contain redundant components. For example, all
the LogicalServers in a group may contain information about the same logical subnet.
Enumerated types are modeled with a structure that contains an enumeration value (with OTHER
as a possible value) and an “other” string (which is used when the enumeration value is OTHER).
The use of an explicit enumeration allows the set of possible values to be clearly defined in the
WSDL. The inclusion of an OTHER value allows future extensions to the enumeration to be
represented in this data model.
48 Data Model
ByteSize
(Required) The value as an enumerated type.ByteSizeEnum enumValue
String otherValue
ByteSizeEnum
Possible values: MB, GB, OTHER
CidrIpRange
CmsQuiesceState
enumValue
String otherValue
CmsQuiesceStateEnum
Possible values: NOT_QUIESCED, QUIESCING, QUIESCED, OTHER
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
IP address component of the CIDR specification.String ipAddress
Specifies the CIDR notation for the prefix size for the specified IP address.Integer cidrPrefixSize
(Required) The value as an enumerated type.CmsQuiesceStateEnum
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
CmsQuiesceStatus
ComputeServer
Extends ServerResource
localDisks
ComputeServerLocalDisk
(Required) The current quiesce state.CmsQuiesceState state
An estimated timeout value (in seconds) for a quiesce operation.Long timeoutSeconds
VirtualConnect domain group ID for blades, or compute actual name for other servers.String domainGroupId
Indicates whether a server profile is assigned to the server.Boolean inUse
Disk resources attached directly to the server.List<ComputeServerLocalDisk>
Disk ID.String id
Disk size, in megabytes.Long sizeMB
ByteSize 49
Cost
CostFrequency
(Required) A numeric cost value.Float value
The units of the cost value.String units
Time period to which the cost value applies.CostFrequency frequency
(Required) The value as an enumerated type.CostFrequencyEnum enumValue
String otherValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
CostFrequencyEnum
Possible values: MONTH, WEEK, DAY, HOUR, UNSPECIFIED, OTHER
CustomAddressAssignmentTypeAttribute
String logicalServerGroupName
String subnetId
addressAssignmentType
List<String> staticIPValues
Name of the logical server group for which to customize the IP address assignment
type.
ID of the subnet for which to customize the IP address assignment type in the logical
server group.
Customized IP address assignment type (STATIC, AUTOMATIC, or DHCP).IPAddressAssignmentTypeEnum
For STATIC address assignment, a list of the IP addresses to use must be specified.
The list size must match the initial logical server group size. For other assignment
types, no addresses should be specified.
CustomMemoryAttribute
Name of logical server group for which to customize the OS image.String logicalServerGroupName
ByteSizeEnum memorySizeUnits
CustomOsImageAttribute
VirtualizationTypeEnum
virtualizationType
String osVariation
50 Data Model
Customized memory size.Integer memorySize
Customized memory size units. The specified memory size and units must be
convertible to a whole number value in the memory size units defined for the logical
server group in the template.
Name of the logical server group for which to customize the memory size.String logicalServerGroupName
Customized software ID.String softwareId
(Optional) Virtualization type for the specified software. Must be HYPER_V or
INTEGRITY_VM. Either a virtualizationType or osVariation must be specified.
(Optional) Operating system type/variation for the specified software with ESX
virtualization type. Either a virtualizationType or osVariation must be specified.
CustomProcessorAttribute
Name of logical server group for which to customize the processor count.String logicalServerGroupName
Customized processor count.Integer processorCount
CustomStorageVolumeAttribute
Name of the virtual logical disk for which to customize the storage volumes.String logicalDiskName
Customized storage volume names.List<String> storageVolumes
CustomSubnetBindingAttribute
ID of a subnet specified in the template.String originalSubnetId
Customized subnet ID to use instead of the subnet ID specified in the template.String customSubnetId
CustomTemplateAttributes
Optional list of subnet ID customizations.List<CustomSubnetBindingAttribute>
subnetBindingAttributes
TypeAttribute>addressAssignment
TypeAttributes
memoryAttributes
processorAttributes
storageVolumeAttributes
osImageAttributes
DeployableSoftware
String name
OperatingSystemType osType
String osSubType
Optional list of IP address assignment type customizations.List<CustomAddressAssignment
Optional list of memory size customizations.List<CustomMemoryAttribute>
Optional list of processor count customizations.List<CustomProcessorAttribute>
Optional list of storage volume customizations.List<CustomStorageVolumeAttribute>
Optional list of operating system customizations.List<CustomOsImageAttribute>
Resource ID of the software.String id
Indicates whether the software is a VM template or a DS image.SoftwareType type
String osDescription
processorArchitecture
Custom software notes.String notes
Location from which the software is available.String location
Size of the disk image for the software, in the units specified by sizeUnits.Integer size
Software size units.ByteSize sizeUnits
Processor architecture with which the software is compatible.Organization
CustomProcessorAttribute 51
deploymentServiceType
virtualizationType
Only applicable when the type is IMAGE.DeploymentServiceType
Only applicable when the type is IMAGE.ImageType imageType
Only applicable when the type is VM_TEMPLATE.VirtualizationType
List<SoftwareDiskDefinition>
softwareDiskDefinitions
Breakdown of individual disk definitions for the software image, when available.
Only applicable when the type is VM_TEMPLATE.
DeploymentService
Name of the deployment server.String name
IP address of the deployment server.String ipAddress
DeploymentServiceType type
Operating system types supported by the deployment service.List<MessageSeverity> osTypes
DeploymentServiceType
(Required) The value as an enumerated type.DeploymentServiceTypeEnum
enumValue
String otherValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
DeploymentServiceTypeEnum
Possible values: RDP, SA, Ignite-UX, CUSTOM, OTHER
DrMode
String otherValue
DrModeEnum
Possible values: ACTIVE, INACTIVE, UNCONFIGURED, OTHER
DrPolicy
DrState
(Required) The value as an enumerated type.DrModeEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
Indicates whether the disaster recovery policy calls for DR protection.Boolean drProtection
Indicates the mode of an entity within a disaster recovery protection configuration.DrMode drMode
Indicates whether an entity was created as a replica for disaster recovery.Boolean drReplica
52 Data Model
FirewallRule
FirewallRuleGroupInfo
Specifies the protocol type to be either TCP, UDP, or ICMP.PacketProtocol packetProtocol
Starting port range.Integer portRangeStart
Ending port range.Integer portRangeEnd
ICMP type (specified if protocolType is ICMP above).Integer icmpType
ICMP code (specified if protocolType is ICMP above).Integer icmpCode
List of IP Sources allowed access on the port range specified above.List <CidrIpRange> ipSources
ID of the FirewallRuleGroup.String firewallRuleGroupId
Name of the FirewallRuleGroup.String firewallRuleGroupName
ID of the underlying resourceString resourceId
ID of the capacity pool to which the firewall rule group belongsString capacityPoolId
Names of users authorized to perform operations on the FirewallRuleGroup.List<String> userNames
FirewallRuleGroupDetails
Extends FirewallRuleGroupInfo
ImageType
String otherValue
ImageTypeEnum
Possible values: OS, APPS, PATCH, UNKNOWN, OTHER
IPAddressAssignmentType
enumValue
String otherValue
List of firewall rules.List<FirewallRule> rules
(Required) The value as an enumerated type.ImageTypeEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
(Required) The value as an enumerated type.IPAddressAssignmentTypeEnum
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
IPAddressAssignmentTypeEnum
Possible values:
Automatically assigned via DHCP.DHCP
Statically assigned using literal values.STATIC
Automatically assigned from the static IP address range set defined for the network.AUTOMATIC
FirewallRule 53
[Not yet defined]EXTERNAL
No assignment type specified.UNSPECIFIED
OTHER
IPType
String otherValue
IPTypeEnum
Possible values: IPV4, IPV6, UNSPECIFIED, OTHER
LeasePeriod
Long endEpoch
LoadBalancerInfo
A value other than above, possibly introduced by an extension in a subsequent
release.
(Required) The value as an enumerated type.IPTypeEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
(Required) The beginning of the lease term, in milliseconds since the epoch.Long startEpoch
The end of the lease term, in milliseconds since the epoch. A null value indicates
the lease has no end date.
isCookieBasedStickySessionSupported
isSourceAddressBasedSticky
SessionSupported
The ID of the load balancer.String id
The model of the load balancer.String model
The version of load balancer.String version
A list of IDs of the subnets on which the load balancer operates.List<String> subnetIds
A management address to connect to a load balancer.String managementAddress
A management port on which to connect a load balancer.Integer managementPort
The management user name for the load balancer.String managementUserName
The password ID of a load balancer.String managementPasswordId
The certificate ID of a load balancer.String managementCertificateId
Indicates if the load balancer supports a high availability.Boolean isHASupported
Indicates if the load balancer supports Secure-Socket-Layer protocol.Boolean isSSLSupported
Indicates if the load balancer can support multiple tenants.Boolean isMultiTenantSupported
Indicates if the load balancer supports cookie based session persistence.Boolean
Indicates if the load balancer supports source address session persistence.Boolean
54 Data Model
Maximum number of groups supported in the load balancer.Integer maxGroups
List of tag names by which this load balancer can be referenced in designer.List<String> tags
LogicalDisk
A logical name for the disk, based on the stereotypeName.String name
String stereotypeName
Boolean isShareable
Boolean isSinglePath
rawMappingType
String resourceBindingId
String templateBindingId
The name that appears in the template and applies across the Logical Server group.
This name is used as a parameter to the addDiskToLogicalServerGroup operation.
Minimum disk size, in the units specified by sizeUnits.Integer size
Disk size units.ByteSize sizeUnits
RAID level defined for the disk.RaidLevel raidLevel
The type of storage represented by the disk. Only applicable for physical disks.StorageType storageType
Indicates whether the disk is a boot disk. A null value indicates “unspecified”.Boolean isBootable
Indicates whether the disk is shared across servers. A null value indicates
“unspecified”.
Indicates whether a SAN disk has redundant paths. A null value indicates
“unspecified”.
Raw Disk Mapping (RDM) type of the disk.RawMappingType
Cost associated with the disk resource, per GB.Cost cost
A unique identifier for the resource that is allocated to the logical disk. A null value
indicates that no resource is currently allocated.
An ID of a SAN volume template to use for the disk. Only applicable for physical
disks.
Disk notes specified in the service templateString notes
LogicalFirewallRuleGroup
LogicalIPAddress
assignmentType
Time at which the logical object was created, in milliseconds since the epochLong createEpoch
Time at which the logical object was last modified, in milliseconds since the epoch.Long lastModifiedEpoch
Resource binding ID.String resourceBindingId
List of firewall rules associated with this group.List<FirewallRule> rules
Description.String notes
The IP address, or a logical representation for DHCP assigned addresses.String address
Manner in which the IP address is assigned.IPAddressAssignmentType
Cost associated with the IP address.Cost cost
Time at which the logical object was created, in milliseconds since the epoch.Long createEpoch
Time at which the logical object was last modified, in milliseconds since the epoch.Long lastModifiedEpoch
List of NAT entries associated with this LogicalIPAddress.List<NatEntry> natEntries
LogicalDisk 55
LogicalLoadBalancerDetails
Extends LogicalLoadBalancerInfo
A list of load balancer groups.List<LogicalLoadBalancerGroup
Details> groups
LogicalLoadBalancerGroupDetails
Extends LogicalLoadBalancerGroupInfo
A list of members in a load balancer group.List<LogicalLoadBalancerGroup
Member> members
LogicalLoadBalancerGroupInfo
The name of the group.String name
The type of protocol the application service will use.LogicalLoadBalancerProtocol
protocol
The virtual IP address to be used by the load balancer to receive requests.String virtualIpAddress
The port the load balancer will be listening on.Integer loadBalancerPort
The host name of the application service being load balanced.String hostname
The URI pathString path
The SSL certificate for secure connections to load balancer.byte[] sslCertificate
Integer
stickySessionTimeoutInSeconds
stickySessionSourceAddressMask
The number of seconds between incoming requests that the load balancer will persist
a session.
The name or ID of a http(s) cookie to store session information.String stickySessionCookieName
A mask for filtering source address based session persistence.String
LogicalLoadBalancerGroupMember
The IP address or host name of the member to be added to the load balancer group.String address
The port on which the member is listening.Integer port
LogicalLoadBalancerInfo
The ID of the logical load balancer.String id
Indicates if the load balancer supports a high availability feature.Boolean isHASupported
isCookieBasedStickySession
Supported
isSourceAddressBasedStickySession
Supported
56 Data Model
Indicates if the load balancer supports Secure-Socket-Layer protocol.Boolean isSSLSupported
Indicates if the load balancer supports cookie based session persistence.Boolean
Indicates if the load balancer supports source address based session persistence.Boolean
A list of networks the load balancer needs to have access to.List<String> subnetIds
A list of tags used to match a specific load balancer during allocation.List<String> tags
LogicalLoadBalancerProtocol
(Required) The value as an enumerated type.LogicalLoadBalancerProtocolEnum
enumValue
String otherValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
LogicalLoadBalancerProtocolEnum
Possible values: TCP, HTTP, HTTPS, OTHER
LogicalNetworkInterface
Name assigned to the network interface.String name
Subnet to which the network interface is connected.LogicalSubnet logicalSubnet
IP address configured for the network interface.LogicalIPAddress
logicalIPAddress
Indicates whether the network interface is a server’s primary one.Boolean isPrimary
Time at which the logical object was created, in milliseconds since the epoch.Long createEpoch
Time at which the logical object was last modified, in milliseconds since the epoch.Long lastModifiedEpoch
LogicalServerDetails
Extends LogicalServerInfo
logicalNetworkInterfaces
LogicalServerGroupDetails
Extends LogicalServerGroupInfo
logicalServers
logicalFirewallRuleGroups
logicalLoadBalancer
List<LogicalIPAddress>
virtualIPAddresses
A list of automatically triggered actions defined for the logical server.List<ServiceAction>serverActions
The logical disks attached to the logical server.List<LogicalDisk>logicalDisks
System software to be deployed on the logical server.List<LogicalSoftware>software
Network interfaces defined for the logical server.List<LogicalNetworkInterface>
A list of automatically triggered actions defined for the logical server group.List<ServiceAction> groupActions
Details of the logical servers in the group.List<LogicalServerDetails>
List of LogicalFirewallRuleGroups associated with this LogicalServerGroup.List<LogicalFirewallRuleGroup>
Details of the LogicalLoadBalancer associated with this LogicalServerGroup, if any.LogicalLoadBalancerDetails
IP addresses assigned to the group for use as floating IP addresses within the group
(for example, by an Oracle DB server).
LogicalLoadBalancerProtocol 57
LogicalServerGroupInfo
Name of the service containing the logical server group.String serviceName
Name of the logical server group.String name
Initial size of the logical server group on service creation.Integer minServerCount
Maximum size of the logical server group that may be achieved by adding servers.Integer maxServerCount
The number of logical servers in the group with status UP.Integer activeServerCount
Integer bootSequenceOrdinal
LogicalServerInfo
String resourceBindingId
String parentResourceBindingId
Indicates the sequence in which the logical server group is booted relative to others,
or 0 if no sequence is defined
Status of operation/automation for the logical server group.ServiceEntityStatus status
Logical server group notes specified in the template.String notes
Time at which the logical object was created, in milliseconds since the epoch.Long createEpoch
Time at which the logical object was last modified, in milliseconds since the epoch.Long lastModifiedEpoch
Name of the service containing the logical server.String serviceName
Name of the logical server group containing the logical server.String logicalServerGroupName
Name of the logical server.String name
Name of the associated logical server in Virtualization Manager.String logicalServerName
Network hostname for the server represented by the logical server.String hostname
A unique identifier for the server resource that is allocated to the logical server. A
null value indicates that no server resource is currently allocated.
The resourceBindingId of the “parent” VM from which a linked clone has been
generated. Is set to null for logical servers which are not linked clones.
String capacityPoolId
Boolean isInCloud
Boolean isBase
String serverType
Integer memorySize
Integer maxMemorySize
The ID of the ESX resource pool or cloud capacity pool in which the server was
provisioned, if applicable.
Indicates whether the logical server is physical or virtual.Boolean isVirtual
Indicates whether the logical server is defined for provisioning to an external cloud
provider.
Indicates whether the logical server is recoverable.Boolean isRecoverable
False if agentless VMM is used and the logical server is not the shared disk host,
or if the logical server is a linked clone.
A named server type corresponding to the server memory and processor attributes.
Applicable only for servers provisioned in cloud capacity pools for which server
types are defined.
Minimum memory requirement for the logical server, in the units specified by
memorySizeUnits.
The maximum value to which the memory size may be updated, using the same
units as the memory size.
Memory size units.ByteSize memorySizeUnits
Minimum number of processors required for the logical server.Integer processorCount
The maximum value to which the processor count may be updated.Integer maxProcessorCount
58 Data Model
Integer processorSpeedMHz
processorArchitecture
LogicalSoftware
deploymentServiceType
Minimum processor speed required for the logical server, in MHz (physical servers
only).
Processor architecture required for the logical server (physical servers only).ProcessorArchitecture
Status of operation/automation for the logical server.ServiceEntityStatus status
Cost associated with the server resource.Cost cost
Time at which the logical object was created, in milliseconds since the epoch.Long createEpoch
Time at which the logical object was last modified, in milliseconds since the epoch.Long lastModifiedEpoch
Name of the software.String name
Indicates whether the software is a VM template or an image.SoftwareType type
The operating system type for the software.OperatingSystemType osType
Deployment service type for an image.DeploymentServiceType
String osCustomizationFileName
virtualizationType
Integer ordinal
String resourceBindingId
LogicalSubnet
Boolean isPublic
The name of a file containing customization data needed to prepare a system (virtual
servers only).
The virtualization technology used by a VM (virtual servers only).VirtualizationType
Indicates the sequence in which the software is deployed to a server relative to
others.
A unique identifier for the resource that is allocated to the logical software. A null
value indicates that no resource is currently allocated.
Time at which the logical object was created, in milliseconds since the epoch.Long createEpoch
Time at which the logical object was last modified, in milliseconds since the epoch.Long lastModifiedEpoch
Name of the logical subnet.String name
Indicates whether the network is public or private. A public subnet is routed within
(and potentially outside) the data center’s L3 IP infrastructure and should not include
192.x.x.x or 10.x.x.x address ranges. A private subnet will not be routed either
within or outside of the data center L3 IP infrastructure and its IP address ranges
should be confined to 192.x.x.x or 10.x.x.x addresses.
Indicates whether the network may be shared with other service instances.Boolean isShareable
String resourceBindingId
IP version used on the network (IPv4 or IPv6).IPType ipType
A unique identifier for the resource that is allocated to the logical subnet. A null
value indicates that no resource is currently allocated.
Network notes specified in the service template.String notes
Time at which the logical object was created, in milliseconds since the epoch.Long createEpoch
Time at which the logical object was last modified, in milliseconds since the epoch.Long lastModifiedEpoch
LogicalSoftware 59
MessageSeverity
(Required) The value as an enumerated type.MessageSeverityEnum enumValue
String otherValue
MessageSeverityEnum
Possible values: CRITICAL, MAJOR, MINOR, WARNING, NORMAL, INFORMATIONAL, OTHER
NatEntry
NatType
String otherValue
NatTypeEnum
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
Specifies the NAT type.NatType type
Public IP address assigned to this entry.String ipAddress
DNS name assigned to this entry.String name
(Required) The value as an enumerated type.NatTypeEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
Possible values: DYNAMIC, FLOATING, OTHER
NetworkSource
String otherValue
NetworkSourceEnum
Possible values: PHYSICAL, VIRTUAL, DEFINED, CLOUD, OTHER
OperatingSystemType
enumValue
String otherValue
OperatingSystemTypeEnum
Possible values: WINDOWS, WINDOWS_2008, LINUX, HP_UX, VMWARE, HYPER_V, CITRIX_XEN,
SOLARIS, AIX, UNKNOWN, UNSPECIFIED, OTHER
(Required) The value as an enumerated type.NetworkSourceEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
(Required) The value as an enumerated type.OperatingSystemTypeEnum
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
60 Data Model
Organization
Name of the organization.String name
String id
PacketProtocol
String otherValue
PacketProtocolEnum
Possible values: TCP, UDP, ICMP, OTHER
ProcessorArchitecture
enumValue
String otherValue
ProcessorArchitectureEnum
Unique identifier for the organization. The Service Provider organization ID is
"SERVICEPROVIDER".
(Required) The value as an enumerated type.PacketProtocolEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
(Required) The value as an enumerated type.ProcessorArchitectureEnum
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
Possible values: IA32, IA64, X86_64, SPARC, POWER_PC, UNSPECIFIED, OTHER
RaidLevel
String otherValue
RaidLevelEnum
Possible values: RAID0, RAID1, RAID3, RAID4, RAID5, RAID6, RAID01, RAID05, RAID10, RAID50,
RAID60, AUTOMATIC, UNSPECIFIED, OTHER
RAID01 represents a RAID 0 striped data set which is then mirrored for recovery.
RAID05 represents a RAID 0 striped data set which is then written with RAID 5 single parity for
recovery.
RawMappingType
enumValue
String otherValue
(Required) The value as an enumerated type.RaidLevelEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
(Required) The value as an enumerated type.RawMappingTypeEnum
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
RawMappingTypeEnum
Possible values: VIRTUAL, PHYSICAL, NONE, OTHER
Organization 61
RequestDetails
Extends RequestInfo
requestHistory
RequestHistoryItem
RequestHistoryItemLevel
enumValue
Detail messages associated with the request.List<RequestHistoryItem>
Time at which the history item event occurred, in milliseconds since the epoch.Long occurEpoch
A message describing the event.String message
Severity of the event.MessageSeverity messageSeverity
Detail level of the message.RequestHistoryItemLevel level
(Required) The value as an enumerated type.RequestHistoryItemLevelEnum
String otherValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
RequestHistoryItemLevelEnum
Possible values: NORMAL, VERBOSE, OTHER
RequestInfo
String id
Long startEpoch
Long endEpoch
RequestStatus status
An identifier assigned to the request when it is submitted. Corresponds to the request
parameters and return values defined for many of the API operations.
Type of operation represented by the request.RequestType type
Time at which the request was submitted, in milliseconds since the epoch.Long submitEpoch
Time at which processing started for the request, in milliseconds since the epoch.
The value may be null if the request is scheduled for future processing (such as a
Create Service request with a future lease start date/time) or if an error prevented
processing of the request.
Time at which processing ended for the request, in milliseconds since the epoch.
The value is null if the request does not have a terminal status.
Current status of the request processing. The progression of a request through various
status values is highly dependent on the request type and other parameters as well
as user interaction.
Integer percentComplete
Boolean manualCleanUpRequired
62 Data Model
Indicates the progress of request processing. The value is based on the number of
steps required/completed and is not a reliable indicator of processing time
remaining.
Indicates whether a manual clean-up action is required as a result of the request
processing.
Name of the service affected by the request.String serviceName
Name of the template used for the service affected by the request.String templateName
String createdByUser
RequestStatus
Name of the user that submitted the request (or on whose behalf the request was
submitted).
Unique identifier for the organization to which the request belongs.String organizationId
(Required) The value as an enumerated type.RequestStatusEnum enumValue
String otherValue
RequestStatusEnum
Possible values: PENDING, ALLOCATING, ALLOCATING_DATA_DISKS, ALLOCATED,
ALLOCATED_DATA_DISKS, PAUSED_FOR_APPROVAL, APPROVED, SCHEDULING, SCHEDULED,
PROVISIONING, SAN_VOLUME_PROVISIONING, SAN_VOLUME_PROVISIONED,
SAN_VOLUME_DATA_DISK_PROVISIONING, PAUSED_FOR_MANUAL_STORAGE_ZONING,
PAUSED_FOR_MANUAL_DATA_STORAGE_ZONING, PROVISIONED,
PAUSED_FOR_OS_DEPLOYMENT, OS_DEPLOY, OS_DEPLOYED,
RUNNING_SERVICE_BEGIN_ACTION, RUNNING_SERVICE_END_ACTION,
RUNNING_GLOBAL_END_ACTION, RUNNING_LOGICAL_SERVER_GROUP_BEGIN_ACTION,
RUNNING_LOGICAL_SERVER_GROUP_END_ACTION,
RUNNING_LOGICAL_SERVER_BEGIN_ACTION, RUNNING_LOGICAL_SERVER_END_ACTION,
COMPLETE, REJECTING, REJECTED, FAILED, CANCELING, CANCELED, STOPPING_SERVERS,
STOPPED_SERVERS, STARTING_SERVERS, STARTED_SERVERS, TERMINATED, PAUSED,
IN_PROGRESS, PAUSED_FOR_DISK_SCRUBBING, PAUSED_FOR_BOOT_DISK_ALLOCATION,
PAUSED_FOR_DATA_DISK_ALLOCATION, PROVISIONING_DATA_DISKS,
PROVISIONED_DATA_DISKS, RESERVING, RESERVED,
RUNNING_STOP_SERVICE_BEGIN_ACTION, RUNNING_STOP_SERVICE_END_ACTION,
RUNNING_START_SERVICE_BEGIN_ACTION, RUNNING_START_SERVICE_END_ACTION,
PAUSED_FOR_PHYSICAL_NETWORK_ALLOCATION,
PAUSED_FOR_VIRTUAL_NETWORK_ALLOCATION, FIREWALLRULEGROUP_PROVISIONING,
FIREWALLRULEGROUP_DELETING, ASSOCIATING, ASSOCIATED, DELETING, DELETED, OTHER
A “terminal” status indicates that no more processing will be performed on the request. Terminal
status values are COMPLETE, CANCELED, REJECTED, FAILED, and TERMINATED.
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
RequestType
String otherValue
RequestTypeEnum
Possible values: CREATE, DELETE, DEACTIVATE, ACTIVATE, UPDATE, ADD_SERVERS,
REMOVE_SERVERS, CHANGE_LEASE_PERIOD, POWER_ON, POWER_OFF, POWER_CYCLE,
EDIT_SERVERS, CREATE_REPLICA, DELETE_REPLICA, IMPORT_SERVER,
CREATE_LOAD_BALANCER_GROUP, DELETE_LOAD_BALANCER_GROUP,
ADD_LOAD_BALANCER_MEMBER, REMOVE_LOAD_BALANCER_MEMBER, ADD_FLOATING_IP,
MOVE_FLOATING_IP, REMOVE_FLOATING_IP, CREATE_SERVER_SNAPSHOT,
DELETE_SERVER_SNAPSHOT, REVERT_TO_SERVER_SNAPSHOT, OTHER
(Required) The value as an enumerated type.RequestTypeEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
RequestStatus 63
SanVolume
StorageProvisioningType
provisioningType
Resource ID for the SAN volume.String id
Volume name, for volumes managed by Storage Provisioning Manager (SPM).String name
Volume size, in megabytes.Long sizeMB
RAID level of the volume.RaidLevel raidLevel
Operating system type with which the volume is to be used.OperatingSystemType osType
Storage tags assigned to the volume.List<String> tags
LUN ID at which the volume is addressed.String lunId
Readiness state of the volume.SanVolumeState state
Indicates whether the volume is currently allocated for use.Boolean inUse
Portability group ID. Only applicable when the state is CONFIGURED.String domainGroupId
Storage pool entry ID. Only applicable when the state is CONFIGURED.String storageEntryId
Storage pool entry name. Only applicable when the state is CONFIGURED.String storageEntryName
Boolean multiMemberSet
Integer
availableConnectionCount
Boolean bootable
Boolean singlePath
rawMappingType
wwnConnections
SanVolumeState
String otherValue
SanVolumeStateEnum
Indicates whether the storage pool entry has multiple members. Only applicable
when the state is CONFIGURED.
Number of storage pool entry connections available. Only applicable when the
state is CONFIGURED.
Indicates whether the volume may be used as a boot disk. Only applicable when
the state is CONFIGURED.
Indicates whether the volume can be accessed via multiple paths. Only applicable
when the state is CONFIGURED.
Raw Disk Mapping (RDM) type of the volume.RawMappingType
Details of server connections for the volume.List<WwnConnection>
(Required) The value as an enumerated type.SanVolumeStateEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
Possible values:
CONFIGURED
64 Data Model
Storage is partitioned into a volume, the volume is presented to WWNs, and the
WWNs are zoned.
Storage is partitioned into a volume.CARVED
A block of storage is not yet partitioned into volumes.UNCARVED_BLOCK
The state cannot be determined.UNKNOWN
OTHER
SanVolumeTemplate
String description
StorageProvisioningType
provisioningType
defaultOsType
A value other than above, possibly introduced by an extension in a subsequent
release.
Resource ID for the SAN volume template.String id
ID of the SPM server from which the template was discovered.String spmServerId
Template name.String name
Default size of SAN volumes provisioned from the template, in megabytes.Long defaultSizeMB
Default RAID level of SAN volumes provisioned from the template.RaidLevel defaultRaidLevel
Default operating system type used for SAN volumes provisioned from the template.OperatingSystemType
Storage tags matched by default when allocating storage for the template.List<String> defaultTags
Minimum size of SAN volumes provisioned from the template, in megabytesLong minSizeMB
Maximum size of SAN volumes provisioned from the template, in megabytes.Long maxSizeMB
allowedRaidLevels
allowedOsTypes
ServerPool
List<String> userNames
List<ServerPoolResourceNote>
resourceNotes
RAID levels allowed for SAN volumes provisioned from the template.List<RaidLevel>
Operating system types allowed for SAN volumes provisioned from the template.List<OperatingSystemType>
Storage tags that must be matched when allocating storage for the template.List<String> requiredTags
Storage tags that must not be matched when allocating storage for the template.List<String> excludedTags
Name of the server pool.String name
Custom server pool notes.String notes
IDs of the VM hosts in the server pool.List<String> vmHostIds
IDs of the compute servers in the server pool.List<String> computeServerIds
IDs of the cloud capacity pools in the server pool.List<String> cloudCapacityPoolIds
IDs of the ESX capacity pools in the server poolList<String> esxCapacityPoolIds
Names of the users and Active Directory groups assigned to the server pool. This
value is reported only to infrastructure orchestration Administrators.
Notes associated with the movement of servers to the server pool. These notes are
present only in the Maintenance pool.
Unique identifier for the organization to which the server pool belongs.String organizationId
SanVolumeTemplate 65
ServerPoolResourceNote
ID of the server (VM host or compute server) to which the note applies.String serverResourceId
Long movedEpoch
String movedFromPoolName
ServerResource
Integer memoryConsumedMB
processorArchitecture
Time at which the server was moved to the server pool, in milliseconds since the
epoch.
Name of the server pool from which the server was moved. This value is not available
after the referenced server pool is deleted.
Name of the user who initiated the server pool move.String movedByUser
User-specified notes associated with the server pool move.String notes
Resource ID for the server.String id
Server model identifier.String model
Server serial number.String serialNumber
Universally unique identifier for the server.String uuid
Physical memory configured on the server, in megabytesInteger memorySizeMB
Physical memory in use on the server, in megabytes, if the server is running a
managed operating system.
Processor architecture used by the server.Organization
Integer processorLoadPercent
ServerSnapshot
ServiceAction
Number of physical processor cores in the server.Integer processorCoreCount
Speed of the server’s processors, in megahertz.Integer processorSpeedMHz
Percentage of the server’s processor cycles being consumed, if the server is running
a managed operating system.
Blade enclosure name or rack name depending on server model.String enclosure
Blade enclosure bay name or rack position depending on server model.String bay
False when errors are detected that would prevent successful provisioning.Boolean validTarget
Name of the server snapshot.String name
Identifier for the snapshot, unique within the set of snapshots for a server.String id
ID of the parent snapshot, if any.String parentSnapshotId
IDs of the child snapshots, if anyList<String> childSnapshotIds
Indicates whether the snapshot is the basis for the current server state.Boolean isActive
66 Data Model
Type of request to which the service action applies.RequestType requestType
The event that triggers execution of the service action.ServiceActionTrigger trigger
A list of workflows comprising the service action, sorted by ordinal.List<Workflow> workflows
ServiceActionTrigger
enumValue
(Required) The value as an enumerated type.ServiceActionTriggerEnum
String otherValue
ServiceActionTriggerEnum
Possible values: SERVICE_BEGIN, SERVICE_END, OTHER
ServiceDetails
Extends ServiceInfo
serviceActions
logicalServerGroups
ServiceEntityStatus
enumValue
String otherValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
A list of automatically triggered actions defined for the service.List<ServiceAction>
Details of the logical server groups contained by the service.List<LogicalServerGroupDetails>
Overhead cost not included in service resource costs.Cost fixedCost
(Required) The value as an enumerated type.ServiceEntityStatusEnum
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
ServiceEntityStatusEnum
Possible values:
PARTIAL
OTHER
The entity has been defined but no work has been performed on it yet.NEW
Resources required for the entity have been allocated.ALLOCATED
A request is operating on the entity.IN_PROGRESS
Resources required for the entity have been reserved.RESERVED
The entity is up and running.UP
The entity is powered off.OFF
The entity has been deactivated.DEACTIVATED
A failure has occurred on the entity.DOWN
The entity represents an aggregation of entities with different status values, none of
which are IN_PROGRESS.
Processing of a request on the entity has failed.FAILED
Processing of a request on the entity is being canceled.CANCELING
The entity status cannot be determined.UNKNOWN
A value other than above, possibly introduced by an extension in a subsequent
release.
ServiceActionTrigger 67
ServiceInfo
Name of the service.String name
Unique identifier for the service.String id
Status of operation/automation for the service.ServiceEntityStatus status
Name of the template on which the service is based.String basedOnTemplate
Time at which the service was created, in milliseconds since the epoch.Long createEpoch
Long lastModifiedEpoch
SoftwareDiskDefinition
(Required) Time at which the service was last modified, in milliseconds since the
epoch.
Aggregate cost of the service resources and overhead.Cost cost
The time period for which service resources are allocatedLeasePeriod leasePeriod
Name of the user that owns the service.String ownerName
Unique identifier for the organization to which the service belongs.String organizationId
Service notes specified at the time of service creation.String notes
Identification of the entity responsible for the service costs.String billingCode
Disaster recovery policy.DrPolicy drPolicy
Disaster recovery state.DrState drState
Disk name, within a software image.String name
Disk size, in the units specified by sizeUnits.Integer size
Disk size units.ByteSize sizeUnits
SoftwareType
String otherValue
SoftwareTypeEnum
Possible values: IMAGE, VM_TEMPLATE, UNSPECIFIED, CLOUD_IMAGE, OTHER
StaticIPAddressRange
Integer addressesInMaintenance
(Required) The value as an enumerated type.SoftwareTypeEnum enumValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
First address in the range.String startAddress
Last address in the range.String endAddress
Number of addresses in the range.Integer addressCount
Number of addresses in the range that are allocated to a service.Integer addressesInUse
Number of addresses in the range that are assigned to a server currently in
maintenance, and are therefore unavailable.
68 Data Model
StorageProvisioningType
enumValue
(Required) The value as an enumerated type.StorageProvisioningTypeEnum
String otherValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
StorageProvisioningTypeEnum
Possible values: THICK, THIN, UNSPECIFIED, OTHER
StorageType
(Required) The value as an enumerated type.StorageTypeEnum enumValue
String otherValue
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
StorageTypeEnum
Possible values: FC_SAN, DAS, VMFS, SAS_SAN, ISCSI_SAN, UNSPECIFIED, OTHER
SubnetDetails
Extends SubnetInfo
DNS domain for the subnet.String dnsDomain
DNS servers configured for the subnet.List<String> dnsServers
String msDomainName
String msWorkgroupName
staticIpAddressRanges
SubnetInfo
DNS search suffixes configured for the subnet.List<String> dnsSearchSuffixes
Default gateways configured for the subnet.List<String> defaultGateways
The name of the MS domain to which Windows servers should be joined when
provisioned on this subnet.
The name of the MS workgroup to which Windows servers should be joined when
provisioned on this subnet. (Not used if msDomainName is set.)
WINS servers configured for the subnet.List<String> winsServers
NTP date servers configured for the subnet.List<String> ntpDateServers
The VLAN ID used to identify the subnet.String vlanId
Indicates the sources from which the subnet was discovered.List<String> groupIds
IDs of the trunk subnets which include this subnet.List<String> parentIds
IDs of the subnets which are contained in this trunk subnet.List<String> childIds
Indicates whether this subnet acts as a trunk.Boolean trunk
Static IP address ranges configured for allocation on this subnet.List<StaticIPAddressRange>
The subnet ID, usually discovered from the managed environment.String id
Network address for the subnet.String address
StorageProvisioningType 69
Subnet mask.String mask
The source types from which the network was discovered/defined.List<NetworkSource> sources
Primary IP type for the subnet.IPType ipType
Indicates whether the subnet serves as a boot network.Boolean bootNetwork
Indicates whether the subnet is publicly addressable.Boolean isPublic
Indicates whether the subnet may be shared across services.Boolean shareable
Number of DHCP addresses configured for allocation on this subnet.Integer dhcpAddressCount
Number of DHCP addresses on this subnet that are allocated to a service.Integer dhcpAddressesInUse
Integer
dhcpAddressesInMaintenance
Integer
staticAddressesInMaintenance
deploymentServices
TemplateInfo
Long lastModifiedEpoch
Number of DHCP addresses on this subnet that are assigned to a server currently
in maintenance, and are therefore unavailable
Number of static addresses configured for allocation on this subnet.Integer staticAddressCount
Number of static addresses on this subnet that are allocated to a service.Integer staticAddressesInUse
Number of static addresses on this subnet that are assigned to a server currently in
maintenance, and are therefore unavailable.
Currently limited to one deployment service per subnet.List<DeploymentService>
Custom subnet notes.String notes
Name of the template.String name
Time at which the template was created, in milliseconds since the epoch.Long createEpoch
(Required) Time at which the template was last modified, in milliseconds since the
epoch.
Aggregate cost of resources for a service based on the template.Cost cost
Indicates whether the template is published for general use.Boolean isPublished
VirtualizationType
enumValue
String otherValue
VirtualizationTypeEnum
Possible values: ESX, XEN, HYPER_V, MSVS, GSX, INTEGRITY_VM, UNKNOWN, OTHER
The XEN, MSVS, and GSX values are currently not used in IO logical servers.
70 Data Model
Indicates whether template customization is available at service creation time.Boolean isCustomizable
Custom template notes.String notes
Disaster recovery policy.DrPolicy drPolicy
(Required) The value as an enumerated type.VirtualizationTypeEnum
A more specific value not defined in the enumerated type, when the enumValue is
OTHER.
VirtualSwitch
VmHost
Extends ServerResource
virtualizationType
Name of the virtual switch.String name
IDs of the subnets served by the virtual switch.List<String> subnetIds
Virtualization type used by the VM host.VirtualizationType
Network hostname of the VM host.String hostname
Network domain of the VM host.String dnsDomain
Network IP address of the VM host.String ipAddress
Name of the cluster containing the VM host.String clusterName
Indicates whether the VM host supports high availability for VM guests.Boolean haEnabled
List<VmHostDataStore>
dataStores
virtualSwitches
VmHostDataStore
Workflow
Does not include data stores that cannot be used or are specifically excluded for
use by IO
Virtual switches configured on the VM host.List<VirtualSwitch>
Mount point of the data store in the VM host file system.String mountPoint
Data store size, in megabytes.Long sizeMB
Available space on the data store, in megabytes.Long freeSizeMB
Indicates whether the data store is a VMFS volume.Boolean vmfsVolume
Indicates whether the data store is shared across hosts in a cluster.Boolean shared
Name of the workflow.String name
Path of the workflow.String path
Indicates the sequence in which the workflow is executed relative to others.Integer ordinal
WwnConnection
String presentedTo
World wide name of the server to which the storage is presented.String serverWwn
World wide names of the disk array containing the volume.List<String> targetWwns
ID of the SAN fabric on which the volume is available.String fabricId
VirtualSwitch 71
5 Exceptions
IOSoapException
An error occurred while processing the operation. This is the base class for all the API exception.
This exception is returned for general errors, where the more specific exceptions do not apply.
A string describing the error.String message
InvalidParameterException
An interface parameter value was not valid.
LoadBalancerNotFoundException
A specified load balancer was not found.
The load balancer ID that was not recognized.String loadBalancerId
LogicalLoadBalancerNotFoundException
A logical load balancer was not found in a specified service.
The name of the service in which the logical load balancer was not found.String serviceName
The logical load balancer ID that was not found.String logicalLoadBalancerId
LogicalServerGroupNotFoundException
A specified logical server group name was not found in a specified service.
The name of the service in which the logical server group was not found.String serviceName
The logical server group name that was not found.String logicalServerGroupName
LogicalServerNotFoundException
A specified logical server name was not found in a specified service.
The name of the service in which the logical server was not found.String serviceName
The logical server name that was not found.String logicalServerName
LogicalServerNotFoundForServerException
A logical server was not found with a specified server name/address.
The name of the server for which a logical server was not found.String serverName
NoServerPoolsAvailableException
No server pools are available for use by the requesting user. Occurs when a default server pool
list is used, but a default list cannot be generated because no pools are available to the user.
The name of the requesting user.String userName
72 Exceptions
OrganizationNotFoundException
A specified organization name was not recognized.
The organization ID or name that was not recognized.String organizationName
RequestNotFoundException
A specified request ID was not recognized.
The request ID that was not recognized.String requestId
SanVolumeNotFoundException
A specified SAN volume ID was not recognized.
The SAN volume ID that was not recognized.String sanVolumeId
SanVolumeTemplateNotFoundException
A specified SAN volume template ID was not recognized.
The SAN volume template ID that was not recognized.String sanVolumeTemplateId
ServerInUseException
A specified compute resource is in use and cannot be un/assigned from/to an organization.
The ID of the compute resource that is in use.String serverResourceId
ServerPoolNotFoundException
A specified server pool name was not recognized.
The server pool name that was not recognized.String serverPoolName
ServerPoolNotFoundForResourceException
No server pool was found containing a specified resource ID.
The resource ID that was not found in a server pool.String resourceId
ServerResourceNotFoundException
A specified compute server or VM host ID was not recognized.
The compute server or VM host ID that was not recognized.String serverId
ServiceNotFoundException
A specified service name was not recognized.
The service name that was not recognized.String serviceName
OrganizationNotFoundException 73
SoftwareNotFoundException
A specified software ID was not recognized.
The software ID that was not recognized.String softwareId
SubnetNotFoundException
A specified subnet ID was not recognized.
The subnet ID that was not recognized.String subnetId
TemplateNotFoundException
A specified template name was not recognized.
The template name that was not recognized.String templateName
UserNotFoundException
A specified user name was not recognized.
The user name that was not recognized.String userName
74 Exceptions
6 Example Usage
The web service operations may be called individually for targeted purposes or they may be
sequenced to perform more complex actions.
Physical Server Maintenance Example
If a physical server in use by an infrastructure service experiences a hardware failure, one may
wish to move it to the Maintenance pool in IO and use another server in the infrastructure service.
The following sequence of operations may be used for that purpose. (Note: Error handling is not
considered in this example.)
• Find the logical server associated with the server hostname.
findLogicalServer
hostId = hostname
The result is a logicalServer.
• Deactivate the logical server.
deactivateLogicalServers
serviceName = logicalServer.serviceName
logicalServers = { logicalServer.name }.
The result is requestId1.
• Wait for the deactivateLogicalServers operation to complete.
getRequestInfo
requestId = requestId1
Repeat periodically until the returned request.status is a terminal status.
• Move the server to the IO Maintenance pool.
moveServerToServerPool
destinationPoolName = “Maintenance”
serverResourceId = logicalServer.resourceId
• Activate the logical server.
activateLogicalServers
serviceName = logicalServer.serviceName
logicalServers = { logicalServer.name }
The result is requestId2.
• Wait for the activateLogicalServers operation to complete.
getRequestInfo
requestId = requestId2
Repeat periodically until the returned request.status is a terminal status.
Physical Server Maintenance Example 75
7 Sample Java Client
The Web Service Interfaces may be accessed from a Java client program by using one of the
generally available tools to create Java language bindings from the WSDL. This sample uses the
wsdl2java utility provided with Apache CXF (cxf.apache.org). A sample environment can be
created as follows:
• Create a development environment with Java 5 or later and Apache Ant
• Install Apache CXF in C:\apache-cxf
• Set the CXF_HOME environment variable: set CXF_HOME=C:\apache-cxf
• Create a C:\hp-io-wsdl-client directory to use for the Java client program
• Save the IO WSDL to the file C:\hp-io-wsdl-client\hp-io-v5.wsdl (see “Accessing
WSDL” (page 16))
• Run C:\apache-cxf\bin\wsdl2java -ant -client -d c:\hp-io-wsdl-client
c:\hp-io-wsdl-client\hp-io-v5.wsdl
• Create the files IOClientPasswordHandler.java and
TrustAllX509TrustManager.java in C:\hp-io-wsdl-client\com\hp\io\soap\
v5 with the contents shown in the sample code below
• Replace the file C:\hp-io-wsdl-client\com\hp\io\soap\v5\
IO_IOSoapServicePort_Client.java with the contents shown below
• Customize IO_IOSoapServicePort_Client.java as necessary, including user and
password information, template name, and service name
• Build and run the Java client program from the C:\hp-io-wsdl-client directory with the
command ant IOClient
The sample program lists templates, creates a service, deactivates the service, and activates the
service. It includes logic to wait for processing of asynchronous requests to complete.
Please note that this sample is provided only to demonstrate one method of accessing the Web
Service Interfaces. It is not intended to be used as production code.
IO_IOSoapServicePort_Client.java must be customized to operate correctly in a particular
environment. Using parameterized input rather than literal values is encouraged, particularly for
the user/password information.
Sample Code
IO_IOSoapServicePort_Client.java:
76 Sample Java Client
package com.hp.io.soap.v5;
import com.hp.io.soap.v1.*;
import java.util.EnumSet;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;
import javax.net.ssl.TrustManager;
import javax.xml.namespace.QName;
import org.apache.cxf.configuration.jsse.TLSClientParameters;
import org.apache.cxf.endpoint.Client;
import org.apache.cxf.endpoint.Endpoint;
import org.apache.cxf.frontend.ClientProxy;
import org.apache.cxf.transport.http.HTTPConduit;
import org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor;
import org.apache.ws.security.WSConstants;
import org.apache.ws.security.handler.WSHandlerConstants;
public final class IO_IOSoapServicePort_Client {
private static final QName SERVICE_NAME =
new QName("http://v5.soap.io.hp.com/", "IO");
private static final Set<RequestStatusEnum> TERMINAL_STATUSES =
EnumSet.of(
RequestStatusEnum.COMPLETE,
RequestStatusEnum.CANCELED,
RequestStatusEnum.REJECTED,
RequestStatusEnum.FAILED,
RequestStatusEnum.TERMINATED);
private IO_IOSoapServicePort_Client() {
}
public static void main(String args[]) throws Exception {
IO_Service ss =
new IO_Service(IO_Service.WSDL_LOCATION, SERVICE_NAME);
IO port = ss.getIOSoapServicePort();
setupConnection(port);
System.out.println("Invoking listTemplates...");
try {
java.util.List<TemplateInfo> templateList =
port.listTemplates();
System.out.println(
"Operation completed with these templates returned:");
for (TemplateInfo template : templateList) {
System.out.println(template.getName());
}
} catch (Exception e) {
System.out.println("Operation failed with exception: " +
e.getMessage());
}
final String infServiceName = "MyServiceName";
System.out.println("Invoking createService...");
try {
String requestId = port.createService(
infServiceName, // Name of service to create
"MyTemplateName", // Name of template for new service
new LeasePeriod(), // Start now and never expire
"hostx", // Hostname completion text
null, // Use all available server pools
null, // Do not set user's email address
"Service Purpose", // Annotation for the new service
Sample Code 77
"MyBillingCode");
RequestStatus requestStatus =
waitForTerminalStatus(port, requestId);
System.out.println("Operation completed with status: " +
requestStatus.getEnumValue());
} catch (Exception e) {
System.out.println("Operation failed with exception: " +
e.getMessage());
}
System.out.println("Invoking deactivateService...");
try {
String requestId = port.deactivateService(infServiceName);
RequestStatus requestStatus =
waitForTerminalStatus(port, requestId);
System.out.println("Operation completed with status: " +
requestStatus.getEnumValue());
} catch (Exception e) {
System.out.println("Operation failed with exception: " +
e.getMessage());
}
System.out.println("Invoking activateService...");
try {
String requestId = port.activateService(infServiceName,null);
RequestStatus requestStatus =
waitForTerminalStatus(port, requestId);
System.out.println("Operation completed with status: " +
requestStatus.getEnumValue());
} catch (Exception e) {
System.out.println("Operation failed with exception: " +
e.getMessage());
}
System.exit(0);
}
/**
* Initializes the security settings for the web service client.
*/
private static void setupConnection(IO port) {
final String USER_NAME = "MyUserName";
final String PASSWORD = "MySecretPassword";
Client proxy = ClientProxy.getClient(port);
// Configure WS-Security UsernameToken parameters
Endpoint cxfEndpoint = proxy.getEndpoint();
Map<String, Object> outProps = new HashMap<String, Object>();
outProps.put(WSHandlerConstants.ACTION,
WSHandlerConstants.USERNAME_TOKEN + " " +
WSHandlerConstants.TIMESTAMP);
outProps.put(WSHandlerConstants.USER, USER_NAME);
outProps.put(WSHandlerConstants.PASSWORD_TYPE,
WSConstants.PW_TEXT);
IOClientPasswordHandler.setPassword(PASSWORD);
outProps.put(WSHandlerConstants.PW_CALLBACK_CLASS,
IOClientPasswordHandler.class.getName());
outProps.put(WSHandlerConstants.TTL_TIMESTAMP, "1800");
outProps.put(WSHandlerConstants.TIMESTAMP_PRECISION, "false");
WSS4JOutInterceptor wssOut = new WSS4JOutInterceptor(outProps);
cxfEndpoint.getOutInterceptors().add(wssOut);
// Configure TLS client parameters
HTTPConduit conduit = (HTTPConduit) proxy.getConduit();
TLSClientParameters tcp = new TLSClientParameters();
tcp.setTrustManagers(
new TrustManager[] { new TrustAllX509TrustManager() });
78 Sample Java Client
tcp.setDisableCNCheck(true);
conduit.setTlsClientParameters(tcp);
}
/**
* Waits until the specified request is no longer active, and
* returns the terminal status.
*/
private static RequestStatus waitForTerminalStatus(
IO port, String requestId) throws Exception {
RequestStatus requestStatus =
port.getRequestInfo(requestId).getStatus();
// Note: The request may require approval or other intervention
// before reaching a terminal status
while (!TERMINAL_STATUSES.contains(requestStatus.getEnumValue()))
{
// Check the status every 10 seconds
Thread.sleep(10000);
requestStatus = port.getRequestInfo(requestId).getStatus();
}
return requestStatus;
}
}
IOClientPasswordHandler.java:
package com.hp.io.soap.v5;
import java.io.IOException;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import org.apache.ws.security.WSPasswordCallback;
public class IOClientPasswordHandler implements CallbackHandler {
private static ThreadLocal<String> password =
new ThreadLocal<String>();
public static void setPassword(String password) {
IOClientPasswordHandler.password.set(password);
}
public void handle(Callback[] callbacks)
throws IOException, UnsupportedCallbackException {
WSPasswordCallback pc = (WSPasswordCallback) callbacks[0];
pc.setPassword(password.get());
}
}
TrustAllX509TrustManager.java:
package com.hp.io.soap.v5;
import java.security.cert.CertificateException;
import java.security.cert.X509Certificate;
import javax.net.ssl.X509TrustManager;
/**
* This class allow any X509 certificates to be used to authenticate the
* remote side of a secure socket, including self-signed certificates.
*/
public class TrustAllX509TrustManager implements X509TrustManager {
Sample Code 79
/** Empty array of certificate authority certificates. */
private static final X509Certificate[] acceptedIssuers =
new X509Certificate[] {};
/**
* Always trust for client SSL chain peer certificate chain with any
* authType authentication types.
*
* @param chain The peer certificate chain.
* @param authType The authentication type based on the client
* certificate.
*/
public void checkClientTrusted(
X509Certificate[] chain, String authType)
throws CertificateException {
}
/**
* Always trust for server SSL chain peer certificate chain with any
* authType exchange algorithm types.
*
* @param chain The peer certificate chain.
* @param authType The key exchange algorithm used.
*/
public void checkServerTrusted(
X509Certificate[] chain, String authType)
throws CertificateException {
}
/**
* Return an empty array of certificate authority certificates which
* are trusted for authenticating peers.
*
* @return an empty array of issuer certificates.
*/
public X509Certificate[] getAcceptedIssuers() {
return (acceptedIssuers);
}
}
80 Sample Java Client
8 Sample VisualStudio/.NET/C# Client
The Web Service Interfaces may be accessed from a .NET client program by using Microsoft
VisualStudio® to create C# language bindings from the WSDL:
• In VisualStudio®, create (for example) a consoled application
• Add a Service Reference, and enter the IO web service endpoint URL (see “Accessing WSDL”
(page 16))
• Enter a service name (e.g., “IOService”) as the Namespace value
• Add these namespaces:
using System.Net;
using System.Net.Security;
using System.Xml;
• Add this code:
try
{
//Open the config file to set the timestamp token and username token
XmlDocument xmlDoc = new XmlDocument();
xmlDoc.Load(
AppDomain.CurrentDomain.SetupInformation.ConfigurationFile);
//Get the configuration node
XmlNode appSettingsNode =
xmlDoc.SelectSingleNode("configuration");
//get the service model node
XmlNode servicemodelNode = appSettingsNode.LastChild;
//Get the client node
XmlNode clientNode = servicemodelNode.LastChild;
//get the endpoint node
XmlNode endpointNode = clientNode.LastChild;
//get the headers node
XmlNode headersNode = endpointNode.LastChild;
//get the security node
81
XmlNode securityNode = headersNode.ChildNodes[1];
//change the timestamp token
securityNode.FirstChild.FirstChild.InnerText =
String.Format("{0:s}", DateTime.Now);
securityNode.FirstChild.LastChild.InnerText =
String.Format("{0:s}", DateTime.Now.AddMinutes(30));
//change the username token with username and password
securityNode.LastChild.FirstChild.InnerText = "administrator";
securityNode.LastChild.ChildNodes[1].InnerText = "password";
//save the timestamp token and the username token
xmlDoc.Save(
AppDomain.CurrentDomain.SetupInformation.ConfigurationFile);
//create object from the service proxy
IOService.OClient wcfClient = new IOService.OClient();
//Trust the certificate
ServicePointManager.ServerCertificateValidationCallback =
new RemoteCertificateValidationCallback(
delegate
{
return true;
});
//call the IO API and write the returned version
Console.WriteLine("The version: " + wcfClient.getVersion());
//call the IO API and write the returned template nnames
Console.WriteLine("The templates:");
IOService.TemplateInfo[] template = wcfClient.listTemplates();
for (int i = 0; i < template.Length; i++)
{
Console.WriteLine(template[i].name);
}
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
• Open the app.config file and find the endpoint tag inside client tag:
<endpoint address=" "
binding="basicHttpBinding"
bindingConfiguration="IOSoapBinding"
contract="IOService.IO" name="IOSoapServicePort" >
// Paste the configurations in the following step here
</endpoint>
• Insert this content inside the endpoint tag from the previous step:
<headers>
<wsa:Action xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
<wsa:To>https://127.0.0.1:51443/hpio/controller/soap/v5</wsa:To>
</wsa:Action>
<wsse:Security s:mustUnderstand="1"
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsu:Created></wsu:Created>
<wsu:Expires></wsu:Expires>
</wsu:Timestamp>
<wsse:UsernameToken
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username></wsse:Username>
<wsse:Password
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password>
<wsse:Nonce></wsse:Nonce>
</wsse:UsernameToken>
</wsse:Security>
</headers>
82 Sample VisualStudio/.NET/C# Client
NOTE: The Timestamp and UsernameToken values are intentionally left blank here. They are
set dynamically by the C# code.
• Modify the wsa:To value inserted in the previous step to specify the target system IP address
or hostname.
• Compile and run.
83
Part II Chargeback API
9 Introduction
Chargeback SOAP API
HP CloudSystem Matrix 7.1 includes a new chargeback feature. Chargeback is primarily a metering
system capable of collecting and exposing usage data for the provisioned infrastructure.
Using the infrastructure orchestration chargeback feature, the administrator can:
• Map allocation data to services, logical servers, logical networks, and logical disks
• Map uptime for logical servers
• Filter data for a specific period in time
The chargeback server collects, stores and exposes usage and cost metrics for services and individual
resources in these services. Collected metrics are accessible through the chargeback SOAP API.
Chargeback web services retrieve the allocation data according to the filter specified in the request.
The resulting output file is a structured XML file that contains the usage and cost metrics required
to build a user customized report. Several different tools can be used to process XML files and
build complex reports; however, there are cases for which only a simple report is required. This
appendix describes how to create customized simple reports from those XML files using a client to
connect to the chargeback SOAP API.
The chargeback command line interface can also be used to retrieve allocation data.
For more information about the chargeback feature, see the HP Matrix Operating Environment
Infrastructure Orchestration User Guide at http://www.hp.com/go/matrixoe/docs.
NOTE: While the chargeback API is similar in build and specifications to the HP Matrix OE
infrastructure orchestration API, there is no overlap between the two.
Chargeback SOAP API 85
10 Accessing the Chargeback Web Service Interfaces
Accessing WSDL
The Web Service Description Language or WSDL (see Reference [1]) definition of chargeback
operations can be accessed from any installed chargeback 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 in the web browser to access the WSDL:
https://<cms-ip-address>:55443/hpio/chargeback/soap/v1?wsdl
The browser will show the formal XML definition of the web service interface.
The WSDL also can be accessed through a command line interface (CLI) using a BAT file. The
chargeback.bat tool is found in the default location at C:\Program Files\HP\Matrix
infrastructure orchestration\chargeback\bin.
Security
The chargeback web service is accessible only over HTTPS. The service uses WS-Security
UsernameToken authentication in text form. A username and password of a registered IO
administrator is required to access the web service interface. A WS-Security timestamp header is
also required.
Authorization
If the presented username/password corresponds to a registered IO user who has the role of
Administrator, the web services returns the requested data. For username/password corresponds
to registered users with the role of Architect or User, the web services will return an authorization
error.
86 Accessing the Chargeback Web Service Interfaces
11 Operations
Operations
The supported operations are specified in the following sections.
Summary Usage Report
getServiceUsagePage
Returns
getServiceUsagePageName
Period periodParameters
Paging
pagingInformation
List<ServiceFilter>
serviceFilters
ServiceUsagePage
resultReport
InvalidPeriodExceptionExceptions
InvalidPagingException
InvalidFilterException
ChargebackException
RequiredParameterException
Returns usage and cost data for selected services.
Report result is paged according to the information passed in.
Specifies the period of time for which to return data, and specifies how
data should be consolidated in the report. There are two options for
formatting report result which depend on Period specification. If
PeriodType is set to DAILY, report will return one entry per pay per service
in the selected period. Each entry will contain usage information for that
service in that day. If PeriodType is set to PERIOD, result will contain one
entry per service for the entire period.
Specifies paging information for the data being returned. This attribute
identifies page size in terms of services and the page to be returned.
Query is re-executed every time the API is called and the query result is
not stored in server. Attribute totalPages is ignored.
Controls which services are included in the result. If no filter is supplied,
all services for the given period are returned.
Required page for the specified query. This contains usage data for
services that match filters and existed over the specified period. Page is
formatted according to PeriodType attribute.
Detailed Usage Report
getServiceUsageDetailedPage
Period periodParameters
Paging pageInformation
List<ServiceFilter>
serviceFilters
Returns detailed usage and cost data for selected services.getServiceUsageDetailPageName
Specifies the period of time for which to return data, and specifies how
data should be consolidated in the report. There are two options for
formatting report result which depend on Period specification. If
PeriodType is set to DAILY, report will return one entry per pay per service
in the selected period. Each entry will contain usage information for that
service in that day. If PeriodType is set to PERIOD, the result will contain
one entry per service for the entire period.
Specifies paging information for the data being returned. This attribute
identifies page size in terms of services and the page to be returned.
Attribute totalPages is ignored.
Controls which services are included in the result. If no filter is supplied,
the call returns information on all services the logged user has access to.
Access to service data follows the same authorization model as elsewhere
in infrastructure orchestration (for example, the listServices API).
Operations 87
Returns
ServiceUsageDetailPage
resultReport
InvalidPeriodExceptionExceptions
InvalidPagingException
InvalidFilterException
RequiredParameterException
ChargebackException
Aggregated Usage Report
getAggregatedServiceUsage
Specified page for the query result containing service usage detailed
data. This page is formatted according to PeriodType attribute.
Returns
getAggregateServiceUsageName
Period periodParameters
List <ServiceFilter>
serviceFilters
AggregateServiceUsage
resultReport
InvalidPeriodExceptionExceptions
InvalidFilterException
ChargebackException
RequiredParameterException
Returns aggregated usage and cost values for selected services. Returns
one entry with consolidated data for the entire period.
Specifies period of time for which to return data. Type is ignored by this
API.
Controls which services are included in the result. If no filter is supplied,
all services for the given period are returned.
Usage data for all services that match the filters and existed over the
specified period.
88 Operations
12 Data model
The complex data types that are used in the API operation definitions are defined in this section.
Figure 3 presents the relationship between the classes that are part of getServiceUsagePage.
Figure 4 presents the data model returned from a getServiceUsageDetailPage operation and
Figure 5 for getAggregateServiceUsage.
Figure 3 ServiceUsagePage Data Model
Figure 4 : ServiceUsageDetailPageData Model
Figure 5 AggregateServiceUsage Data Model
89
Period
Represents the period of time of the data to be returned.
PeriodType enum
Represents the possible usage data grouping. PERIOD means that the result will consolidate one
entry per service for the entire period, and DAILY means one entry per day.
Possible values: PERIOD, DAILY
ServiceFilter
Represents queries to be done while returning data.
filterAttribute
filterOperator
Start date from which to return data. Format: YYYY-MM-DDDate startDate
End date from which to stop returning data. Format: YYYY-MM-DDDate endDate
Specifies how data must be consolidated in the report.PeriodType type
Represents the attribute that will be used to filter data.ServiceFilterAttribute
Represents the comparison operator.FilterOperator
String serviceFilterValue
filterConnector
Specifies the value to be searched. This value, together with filterAttribute and filterOperator,
is used in the form: filterAttribute filterOperator value. For example: ORGANIZATION_ID
LIKE “HP*”.
Used with the prior filter.FilterConnector
ServiceFilterAttribute enum
Represents the fields supported for usage data filtering.
Possible values: ORGANIZATION_ID, BILLING_CODE, OWNER, SERVICE_NAME
FilterOperator enum
Represents the supported operators for filters.
Possible values: EQUAL, NOT_EQUAL, LIKE, NOT_LIKE. These are non case sensitive.
FilterConnector enum
Represents the supported filter connectors.
Possible values: AND, OR, NONE
Paging
Provides paging information for the data returned by the chargeback web service. This object is
ignored when PERIOD is used. The result is paged only for period type set to DAILY. When PERIOD
is used, only one page is returned with all registers.
int pageSize
int pageIndex
90 Data model
Number of services in a page. It is used to determine the number of pages in the report.
It must be greater than 0. If 0 is supplied, InvalidPageSizeException is thrown.
Indicates which page to be returned by the webservice. First page is 0 and last is totalPages
– 1.
int totalPages
Filled every time the web service is called and contains the total number of pages based
on the query executed and the pageSize. If no data is returned, totalPages is 0.
Indicates if the returned page is the last page for the specified query.bool lastPage
ServiceInformation
Represents descriptive information of a service.
Service name.String name
Unique id used by Matrix OE infrastructure orchestration and chargeback.String id
Organization unique ID associated with the service.String organizationId
Billing code associated with this service as specified during service creation.String billingCode
Name of the service owner.String owner
Date that the service was created.Date startDate
Returned when the service is already deleted and has a delete date saved.Date endDate
ResourceUsageSummary
BigDecimal fixedCost
ipAddressUsage
ServerUsageSummary
DiskUsageSummary
Fixed cost associated with the service in the given day or period (depending
on the query).
Summarized data for the service’s servers.ServerUsageSummary serverUsage
Summarized data for the service’s disks.DiskUsageSummary diskUsage
Summarized data for the service’s IP addresses.IpAddressUsageSummary
Number of servers in the service for the given period or day.Long serversCount
Sum of servers allocation hours for the given period or day.BigDecimal allocationHours
Servers’ allocation cost for the given period or day.BigDecimal allocationCost
Sum of servers uptime hours for the given period or day.BigDecimal uptimeHours
Number of disks associated to the service for the given period or day.Long disksCount
Sum of disks allocation hours for the given period or day.BigDecimal allocationHours
IpAddressUsageSummary
Disks allocation cost for the given period or day.BigDecimal allocationCost
Amount of storage allocated for the given period or day.BigDecimal disksSizeGb
Number of IP addresses associated to the service for the given period or dayLong ipAddressCount
Sum of IP addresses allocation hours for the given period or day.BigDecimal allocationHours
IP addresses’ allocation cost for the given period or day.BigDecimal allocationCost
ServiceInformation 91
ServiceUsagePage
Paging object with detailed information about the pages for the given query.Paging pagingInformation
List<ServiceUsageSummary>
serviceUsageSummary
ServiceUsageSummary
ResourceUsageSummary
resourceUsageSummary
AggregateServiceUsage
ResourceUsageSummary
resourceUsageSummary
List of registers returned by this query. A register is represented by a
ServiceUsageSummary object. This contains allocation metric information
for a given service in a given date. The number of objects returned in a page
is determined by the pageSize and the amount of data resulted by specified
query. This list is ordered by service ID and then by date.
Represents the date for which that object has data.String date
Contains service specific information.ServiceInformation serviceInformation
Contains collected metrics for the given service (identified by
serviceInformation) in the given date (date).
Number of existing services in the period and that match specified filters.Long servicesCount
Contains collected metrics for all services that existed in the given period
and that match specified filters.
Total cost for the query.BigDecimal totalCost
ServiceUsageDetailPage
List<ServiceUsageDetail>
serviceUsageDetail
ServiceUsageDetail
ServiceInformation serviceInformation
ResourceUsageDetail resourceUsageDetail
ResourceUsageDetail
ServerUsageDetail
Paging object with detailed information about the pages for the given query.Paging pagingInformation
If Period is set to DAILY, this represents the date for the associated data.String date
Data for each server in the service.List<ServerUsageDetailList> servers
Data for each disk in the service.List<DiskUsageDetail> disks
Data for each IP Address in the service.List<IpAddressUsageDetail> ipAddresses
String resourceType
92 Data model
Contains server’s hostname.String hostName
Identifies whether the server is PHYSICAL, VIRTUAL or CLOUD. Physical and
virtual types are servers deployed on-premise. The Cloud type identifies
resources deployed to external cloud providers such as HP Cloud Services,
Savvis, or Amazon EC2.
Total of allocations hours for the server in the given period or day.BigDecimal allocationHours
Total cost of the server for the server in the given period or day.BigDecimal allocationCost
BigDecimal uptimeHours
DiskUsageDetail
Bool isInCLoud
IpAddressUsageDetail
BigDecimal allocationHours
Total of uptime hours for the server in the given period or day. Uptime hours
for cloud resources may vary 30 minutes.
Service disk name.String logicalDiskName
Total of allocation hours for the disk in the given period or day.BigDecimal allocationHours
Total cost of the disk for the server in the given period or day.BigDecimal allocationCost
Disk size allocated.BigDecimal sizeGb
True for the disks that are created in a server created in an external cloud
provider.
IP address or Fully Qualified Domain Name associated with the IP address.String ipAddress
DHCP, STATIC, or AUTO according to the template definition.String ipAssignmentType
Total amount of allocations hours for the IP address in the given period or
day.
Total cost of the IP address for the server in the given period or day.BigDecimal allocationCost
Bool isInCLoud
True for the IP address associated with a server created in an external cloud
provider.
DiskUsageDetail 93
13 Exceptions
AuthenticationException
Username was not authenticated.
AuthorizationException
Username was not authorized or is not a Service Provider administrator.
ChargebackDataBaseException
An error occurred during database query, or trying to connect to the chargeback database.
ChargebackException
An exception occurred during the request fulfillment.
A string describing the errorString message
A string describing the errorString message
A string describing the errorString message
InvalidDateFormatException
A date is not in the format yyyy-MM-dd.
InvalidFilterException
The filter object was not specified correctly.
InvalidPageIndexException
Page index is a number less than 0.
InvalidPageSizeException
Page size is a number less or equal to 0.
A string describing the errorString message
A string describing the errorString message
A string describing the errorString message
A string describing the errorString message
94 Exceptions
A string describing the errorString message
PeriodStartDateGreaterThanEndDateException
Start date is a date newer than end date.
A string describing the errorString message
PeriodStartDateTooOldException
Start date is older than 365 days from the current date.
A string describing the errorString message
RequiredParameterException
A required parameter was not specified.
A string describing the errorString message
PeriodStartDateGreaterThanEndDateException 95
14 Sample Python Client
The following sample client was developed in Python 2.7.2 with the use of open source libraries.
It provides the user with a UI to query the chargeback API and returns the report in a formatted
PDF.
To create the sample client environment:
• Download and install Python 2.7 from python.org
• Download and install Suds, a lightweight SOAP python client for consuming web services,
from https://fedorahosted.org/suds/
• Download and install the Reportlab Toolkit, a Python library for creating reports in PDF, from
http://www.reportlab.com/software/opensource/
• Create a directory called ChargebackSample/root
• Save connection.py and reports.py in /root/chargeback
• Save GUI.py in /root/GUI
• Save reports_file.py in /root/reports
Execute the sample as:
> python GUI.py
Figure 6 Sample client UI
Known limitations in the sample:
• Only the first page of each report is returned.
• The report is filtered by one tenant name (organization ID) or one billing code.
• It is not possible to use ‘OR’ to filter reports.
• The output path must exist, otherwise the sample will throw an exception.
96 Sample Python Client
Figure 7 Example of a report for getAggregatedUsage generated from sample client
Example 1 connection.py
import suds
PORT = "55443"
SERVICE = "/hpio/chargeback/soap/v1?wsdl"
TRANSPORT = "https://"
URL = "{0}{1}:{2}{3}"
class Connection(object):
'''
classdocs
'''
def __init__(self, server, username, password):
'''
Constructor
'''
endpoint = URL.format(TRANSPORT, server, PORT, SERVICE)
self.client = suds.client.Client(url=endpoint)
security = suds.wsse.Security()
token = suds.wsse.UsernameToken(username, password)
security.tokens.append(token)
security.tokens.append(suds.wsse.Timestamp())
self.client.set_options(wsse=security, autoblend = True)
97
Example 2 reports.py
import suds
import datetime
import locale
import root.reports.reports_file
from reportlab.platypus import Table, TableStyle, Paragraph
from reportlab.platypus.flowables import PageBreak
from reportlab.lib import colors
from reportlab.lib.colors import Color, PCMYKColor, HexColor, black, white
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.graphics.shapes import Drawing
from reportlab.graphics.charts.piecharts import Pie
from reportlab.graphics.charts.legends import Legend
styleSheet = getSampleStyleSheet()
resourcescolumntitles_fontsize = 8
resourcescolumnvalues_fontsize = 7
PAGE_SIZE = 100
PAGE_INDEX = 0
pdf_chart_colors = [
HexColor("#0000e5"),
HexColor("#1f1feb"),
HexColor("#5757f0"),
HexColor("#8f8ff5"),
HexColor("#c7c7fa"),
HexColor("#f5c2c2"),
HexColor("#eb8585"),
HexColor("#e04747"),
HexColor("#d60a0a"),
HexColor("#cc0000"),
HexColor("#ff0000"),
]
class PeriodInformation(object):
def __init__(self, startDate, endDate):
self.start = startDate
self.end = endDate
def getDailyPeriodObj(self, chargebackservice):
reportPeriod = chargebackservice.factory.create('period')
reportPeriod.startDate = self.start
reportPeriod.endDate = self.end
periodType = chargebackservice.factory.create('periodType')
reportPeriod.type = periodType.DAILY
return reportPeriod
def getPeriodObj(self, chargebackservice):
reportPeriod = chargebackservice.factory.create('period')
reportPeriod.startDate = self.start
reportPeriod.endDate = self.end
periodType = chargebackservice.factory.create('periodType')
reportPeriod.type = periodType.PERIOD
return reportPeriod
class Filters(object):
def __init__(self, organizationid="", billingcode="", owner="", service=""):
self.organizationid = organizationid
self.billing_code = billingcode
self.owner = owner
self.service = service
def getFiltersObj(self, chargebackservice):
filterCollection = []
attributefilter = chargebackservice.factory.create("serviceFilterAttribute")
connectorfilter = chargebackservice.factory.create("filterConnector")
operatorfilter = chargebackservice.factory.create("filterOperator")
if len(self.organizationid) > 0:
organizationfilter = chargebackservice.factory.create('serviceFilter')
organizationfilter.filterAttribute = attributefilter.ORGANIZATION_ID
organizationfilter.filterOperator = operatorfilter.EQUAL
organizationfilter.serviceFilterValue = self.organizationid
filterCollection.append(organizationfilter)
if len(self.billing_code) >0 :
billingcodefilter = chargebackservice.factory.create('serviceFilter')
billingcodefilter.filterAttribute = attributefilter.BILLING_CODE
billingcodefilter.filterOperator = operatorfilter.EQUAL
billingcodefilter.serviceFilterValue = self.billing_code
billingcodefilter.filterConnector = connectorfilter.AND
filterCollection.append(billingcodefilter)
if len(self.owner) > 0:
ownerfilter = chargebackservice.factory.create('serviceFilter')
ownerfilter.filterAttribute = attributefilter.OWNER
ownerfilter.filterOperator = operatorfilter.EQUAL
ownerfilter.serviceFilterValue = self.owner
ownerfilter.filterConnector = connectorfilter.AND
filterCollection.append(ownerfilter)
98 Sample Python Client
if len (self.service) >0:
servicefilter = chargebackservice.factory.create('serviceFilter')
servicefilter.filterAttribute = attributefilter.SERVICE_NAME
servicefilter.filterOperator = operatorfilter.EQUAL
servicefilter.serviceFilterValue = self.service
servicefilter.filterConnector = connectorfilter.AND
filterCollection.append(servicefilter)
if len(filterCollection) > 0:
filterCollection[0].filterConnector = connectorfilter.NONE
return filterCollection
def get_servicename(serviceUsage):
return str(serviceUsage.serviceInformation.name)
def get_organization(serviceUsage):
return str(serviceUsage.serviceInformation.organizationId)
def get_billingcode(serviceUsage):
return str(serviceUsage.serviceInformation.billingCode)
def get_owner(serviceUsage):
return str(serviceUsage.serviceInformation.owner)
def get_startdate(serviceUsage):
return str(serviceUsage.serviceInformation.startDate)
def get_enddate(serviceUsage):
try:
return str(serviceUsage.serviceInformation.endDate)
except:
return ""
def report_Summary(number_of_service, period):
result = [[]]
result[0] = Paragraph(''' ''', styleSheet["BodyText"])
summarytable = [[]]
now = datetime.datetime.now()
summarytable[0] = ["Date run: ", now.strftime("%Y-%m-%d")]
start_date = datetime.datetime.strptime (period.start, "%Y-%m-%d")
end_date = datetime.datetime.strptime (period.end, "%Y-%m-%d")
days = end_date - start_date
periodStr = "{0} to {1} ({2} days)"
summarytable.append(["Reporting period: ", periodStr.format(period.start, period.end, str(days.days))])
summarytable.append(["Number of services: ", number_of_service])
t = Table(summarytable, style=[('LINEABOVE', (0,0), (-1,0), 0.25, colors.black),
('LINEBELOW', (0,-1), (-1,-1), 0.25, colors.black),
('FONTSIZE', (0,0), (0,2), 9),
('FONTSIZE', (1,0), (1,2), 8),
('BOX', (0,0), (-1,-1), 0.25, colors.black)]
)
t.hAlign = "LEFT"
result.append(t)
result.append(Paragraph(''' ''',styleSheet["BodyText"]))
result.append(Paragraph(''' ''',styleSheet["BodyText"]))
return result
class ServiceUsageReport (object):
def __init__ (self, periodInformation, connection, filters=None, title="Title", footer="Footer"):
self.title = title
self.data = footer
self.footer = ""
self.period = periodInformation
self.filters = filters
self.chargebackservice = connection.client
def get_serviceCost(self, serviceUsage):
disckCost = serviceUsage.resourceUsageSummary.DiskUsageSummary.allocationCost
ipCost = serviceUsage.resourceUsageSummary.IpAddressUsageSummary.allocationCost
serversCost = serviceUsage.resourceUsageSummary.ServerUsageSummary.allocationCost
fixedCost = serviceUsage.resourceUsageSummary.fixedCost
return disckCost + ipCost + serversCost + fixedCost
def get_totalServices(self, services):
return len(services)
def format_data(self):
Elements = []
if self.chargebackservice :
dataPeriod = self.period.getPeriodObj(self.chargebackservice)
paging = self.chargebackservice.factory.create('paging')
99
paging.pageIndex = PAGE_INDEX
paging.pageSize = PAGE_SIZE
filters = []
if self.filters :
filters = self.filters.getFiltersObj(self.chargebackservice)
if len(filters) > 0:
print "[" + str(datetime.datetime.now()) + "]" + "getServiceUsagePage: start"
result = self.chargebackservice.service.getServiceUsagePage(dataPeriod, paging, filters)
print "[" + str(datetime.datetime.now()) + "]" + "getServiceUsagePage: end"
else:
result = self.chargebackservice.service.getServiceUsagePage(dataPeriod, paging)
if result.pagingInformation and len (result.ServiceUsageSummary) > 0:
pages = result.pagingInformation
services = result.ServiceUsageSummary
Elements.extend(report_Summary(len(services), self.period))
reportTable = [[]]
reportTable[0] = ["Organization", "Billing Code", "Owner", "Service", "Total Cost ($)"]
billingCost = 0.0
for item in services:
organizationName = get_organization(item)
billingCode = get_billingcode(item)
owner = get_owner(item)
serviceName = get_servicename(item)
serviceCost = self.get_serviceCost(item)
billingCost += serviceCost
reportLine = [organizationName, billingCode, owner, serviceName,
str(locale.currency(val=serviceCost,symbol=False, grouping=True)) ]
reportTable.append(reportLine)
reportTable.append(["", "", "", "Total", str(locale.currency( val=billingCost, symbol=False,
grouping=True))])
t = Table (reportTable, style=[('LINEABOVE', (0,0), (-1,0), 0.25, colors.black),
('LINEABOVE', (0,-1), (-1,-1), 0.25, colors.black),
('FONTSIZE', (0,0), (-1,0), 10),
('FONTSIZE', (0,1), (-1, -1), 9),
('ALIGN',(-1,1),(-1,-1),'RIGHT'),
('BACKGROUND',(0,0), (-1,0), colors.blue),
('TEXTCOLOR',(0,0), (-1,0), colors.white)
])
t.hAlign = "LEFT"
Elements.append(t)
else:
print "Result: " + result
return Elements
def generate (self, outputfile):
usageReport = root.reports.reports.Report(self.title, self.footer)
usageReport.generate (self.format_data(), outputfile)
class ServiceUsageDetailReport (object):
def __init__ (self, periodInformation, connection, filters=None, title="Title", footer="Footer"):
self.title = title
self.data = footer
self.footer = ""
self.period = periodInformation
self.filters = filters
self.chargebackservice = connection.client
def addserversdetails(self, servers, serviceData):
serviceData.append(["Servers", "", "", "", ""])
serviceData.append(["Hostname", "Type", "Allocation time (hrs)", "Allocation cost($)", "Up time (hrs)"
])
for server in servers.serverUsageDetail:
serviceData.append([str(server.hostName), server.resourceType, server.allocationHours,
str(locale.currency(val=server.allocationCost,symbol=False, grouping=True)), server.uptimeHours])
return len(servers.serverUsageDetail)
def adddisksdetails(self, disks, serviceData):
serviceData.append (["Disks", "", "", "", ""])
serviceData.append(["Name", "Size (Gb)", "Allocation time (hrs)", "Allocation cost($)", "In cloud?"])
for disk in disks.diskUsageDetail:
serviceData.append([disk.logicalDiskName, disk.sizeGb, disk.allocationHours,
str(locale.currency(val=disk.allocationCost, symbol=False, grouping=True)), disk.isInCloud])
return len(disks.diskUsageDetail)
def addipaddressesdetails(self, ipAddresses, serviceData):
serviceData.append (["IP Addresses", "", "", "", ""])
serviceData.append(["IP Address", "Type", "Allocation time (hrs)", "Allocation cost($)", ""])
for ipAddress in ipAddresses.ipAddressUsageDetail:
100 Sample Python Client
Loading...