Dell Active System Manager Version 8.3 Manual
Active System Manager Release 8.3
API Reference Guide
Notes, cautions, and warnings
NOTE: A NOTE indicates important information that helps you make better use of your product.
CAUTION: A CAUTION indicates either potential damage to hardware or loss of data and tells you how to avoid the
problem.
WARNING: A WARNING indicates a potential for property damage, personal injury, or death.
© 2016 Dell Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. Dell and the Dell
logo are trademarks of Dell Inc. in the United States and/or other jurisdictions. All other marks and names mentioned herein may be trademarks of
their respective companies.
2016 - 09
Rev. A00
Contents
1 Overview........................................................................................................................10
Other Documents You May Need......................................................................................................................................10
2 Resource URI Endpoints.................................................................................................11
3 Authentication Headers................................................................................................. 12
4 Generic Query Parameters.............................................................................................14
Dates in query strings........................................................................................................................................................14
5 HTTP Message Bodies.................................................................................................. 15
Validations.........................................................................................................................................................................15
6 Usage Examples............................................................................................................ 16
Timezone.......................................................................................................................................................................... 16
Get the current timezone............................................................................................................................................16
Set the current timezone............................................................................................................................................ 16
Credential..........................................................................................................................................................................17
Get all dened Credentials...........................................................................................................................................17
Dene new Credential................................................................................................................................................. 17
DiscoveryRequest............................................................................................................................................................. 17
Discover Chassis and contained Blade Servers........................................................................................................... 18
ManagedDevice................................................................................................................................................................ 18
Get all Managed Devices.............................................................................................................................................18
ServiceTemplate................................................................................................................................................................19
Get all ServiceTemplates.............................................................................................................................................19
Get a ServiceTemplate by name..................................................................................................................................19
Publish a ServiceTemplate..........................................................................................................................................20
Deployment......................................................................................................................................................................20
Get all deployed Services........................................................................................................................................... 20
Deploy a new Service..................................................................................................................................................21
Tear down a Service....................................................................................................................................................21
Firmware.......................................................................................................................................................................... 22
Check Firmware compliance of all Resources............................................................................................................. 22
7 Exception Handling........................................................................................................23
8 Appendix A - API Reference.......................................................................................... 24
/AddOnModule.................................................................................................................................................................24
/AddOnModule.................................................................................................................................................................24
/AddOnModule/{id}.........................................................................................................................................................25
/Authenticate/.................................................................................................................................................................26
3
/Chassis/......................................................................................................................................................................... 26
/Chassis/{refId}............................................................................................................................................................... 27
/Chassis/{refId}............................................................................................................................................................... 28
/Chassis/{refId}............................................................................................................................................................... 28
/Chassis/iom/ip/{ip}........................................................................................................................................................29
/Chassis/{refId}/sensorlog.............................................................................................................................................. 30
/Chassis/{refId}/sensorlog.............................................................................................................................................. 30
/Chassis/{serviceTag}/{type}........................................................................................................................................... 31
/Chassis/{serviceTag}/{type}.......................................................................................................................................... 32
/Credential/..................................................................................................................................................................... 32
/Credential/..................................................................................................................................................................... 33
/Credential/{id}................................................................................................................................................................34
/Credential/{id}................................................................................................................................................................35
/Credential/{id}................................................................................................................................................................35
/DHCP/........................................................................................................................................................................... 36
/DHCP/........................................................................................................................................................................... 36
/Deployment/.................................................................................................................................................................. 37
/Deployment/.................................................................................................................................................................. 38
/Deployment/{id}.............................................................................................................................................................39
/Deployment/{id}.............................................................................................................................................................39
/Deployment/{id}.............................................................................................................................................................40
/Deployment/users...........................................................................................................................................................41
/Deployment/export/csv.................................................................................................................................................. 41
/Deployment/deneService............................................................................................................................................. 42
/Deployment/deneServiceDi........................................................................................................................................42
/Deployment/network/{networkId}................................................................................................................................. 43
/Deployment/device/{deviceId}.......................................................................................................................................44
/Deployment/lter/{numOfDeployments}........................................................................................................................44
/Deployment/migrate/{serviceId}/{serverId}...................................................................................................................45
/Deployment/migrateServer/{serviceId}/{componentId}.................................................................................................46
/Deployment/serverNetworking/{serviceId}/{serverId}.................................................................................................. 46
/DeviceGroup/.................................................................................................................................................................47
/DeviceGroup/.................................................................................................................................................................48
/DeviceGroup/{refId}.......................................................................................................................................................49
/DeviceGroup/{refId}.......................................................................................................................................................49
/DeviceGroup/{refId}.......................................................................................................................................................50
/DiscoveryRequest/......................................................................................................................................................... 51
/DiscoveryRequest/......................................................................................................................................................... 51
/DiscoveryRequest/{id}................................................................................................................................................... 52
/DiscoveryRequest/{id}................................................................................................................................................... 52
/DiscoveryRequest/chassislist......................................................................................................................................... 53
/DiscoveryRequest/discoveryresult/{id}..........................................................................................................................54
/FirmwareRepository/......................................................................................................................................................54
/FirmwareRepository/......................................................................................................................................................55
/FirmwareRepository/{id}................................................................................................................................................ 56
4
/FirmwareRepository/{id}................................................................................................................................................ 56
/FirmwareRepository/connection.....................................................................................................................................57
/FirmwareRepository/compliance.................................................................................................................................... 58
/FirmwareRepository/compliance/{id}.............................................................................................................................58
/FirmwareRepository/softwarecomponent......................................................................................................................59
/FirmwareRepository/softwarebundle/{id}...................................................................................................................... 60
/ManagedDevice/............................................................................................................................................................60
/ManagedDevice/............................................................................................................................................................ 61
/ManagedDevice/count...................................................................................................................................................62
/ManagedDevice/{refId}..................................................................................................................................................63
/ManagedDevice/{refId}..................................................................................................................................................63
/ManagedDevice/{refId}..................................................................................................................................................64
/ManagedDevice/rmware..............................................................................................................................................65
/ManagedDevice/export/csv...........................................................................................................................................65
/ManagedDevice/withcompliance................................................................................................................................... 66
/ManagedDevice/puppet/{certName}.............................................................................................................................66
/ManagedDevice/puppet/{certName}.............................................................................................................................67
/ManagedDevice/withcompliance/{refId}........................................................................................................................68
/NTP/.............................................................................................................................................................................. 68
/NTP/..............................................................................................................................................................................69
/NTP/..............................................................................................................................................................................69
/Network/....................................................................................................................................................................... 70
/Network/........................................................................................................................................................................ 71
/Network/export/csv....................................................................................................................................................... 71
/Network/{networkId}.....................................................................................................................................................72
/Network/{networkId}.....................................................................................................................................................73
/Network/{networkId}.....................................................................................................................................................73
/Network/ipAddress/assign.............................................................................................................................................74
/Network/ipAddress/release............................................................................................................................................75
/Network/{networkId}/usageids......................................................................................................................................75
/Network/{networkId}/ipaddresses.................................................................................................................................76
/OSRepository/................................................................................................................................................................77
/OSRepository/................................................................................................................................................................77
/OSRepository/{id}..........................................................................................................................................................78
/OSRepository/{id}..........................................................................................................................................................78
/OSRepository/{id}..........................................................................................................................................................79
/OSRepository/sync/{id}................................................................................................................................................. 79
/OSRepository/connection.............................................................................................................................................. 80
/Proxy/.............................................................................................................................................................................81
/Proxy/.............................................................................................................................................................................81
/Proxy/test...................................................................................................................................................................... 82
/Server/...........................................................................................................................................................................83
/Server/count.................................................................................................................................................................. 83
/Server/{refId}.................................................................................................................................................................84
/Server/{refId}.................................................................................................................................................................85
5
/Server/serviceTag/{serviceTag}..................................................................................................................................... 86
/ServiceTemplate/........................................................................................................................................................... 87
/ServiceTemplate/........................................................................................................................................................... 87
/ServiceTemplate/{id}......................................................................................................................................................88
/ServiceTemplate/{id}......................................................................................................................................................89
/ServiceTemplate/{id}......................................................................................................................................................90
/ServiceTemplate/users...................................................................................................................................................90
/ServiceTemplate/upload..................................................................................................................................................91
/ServiceTemplate/export.................................................................................................................................................. 91
/ServiceTemplate/{id}/copy.............................................................................................................................................92
/ServiceTemplate/export/csv.......................................................................................................................................... 93
/ServiceTemplate/uploadCong.......................................................................................................................................93
/ServiceTemplate/updateParameters...............................................................................................................................94
/ServiceTemplate/device/{deviceId}................................................................................................................................95
/ServiceTemplate/{id}/mapToPhysicalResources............................................................................................................ 95
/ServiceTemplate/components/service/{serviceId}.........................................................................................................96
/ServiceTemplate/components/template/{templateId}....................................................................................................97
/ServiceTemplate/service/{serviceId}/{componentType}................................................................................................ 97
/ServiceTemplate/template/{templateId}/{componentType}...........................................................................................98
/Timezone/......................................................................................................................................................................99
/Timezone/......................................................................................................................................................................99
/Timezone/all................................................................................................................................................................. 100
/User/............................................................................................................................................................................100
/User/.............................................................................................................................................................................101
/User/{userId}................................................................................................................................................................ 102
/User/{userId}................................................................................................................................................................ 103
/User/{userId}................................................................................................................................................................ 103
/WizardStatus/.............................................................................................................................................................. 104
/WizardStatus/.............................................................................................................................................................. 104
9 Appendix B - Model Reference.................................................................................... 106
BrowneldStatus............................................................................................................................................................ 106
ComparatorValue ........................................................................................................................................................... 106
CompliantState ..............................................................................................................................................................106
DeploymentHealthStatusType ........................................................................................................................................107
DeploymentStatusType .................................................................................................................................................. 107
DeviceHealth ..................................................................................................................................................................107
DeviceState ................................................................................................................................................................... 107
DeviceType .....................................................................................................................................................................107
DiscoverDeviceType .......................................................................................................................................................108
DiscoveryStatus .............................................................................................................................................................108
DiskMediaType ...............................................................................................................................................................108
Health ............................................................................................................................................................................108
HotSpareStatus .............................................................................................................................................................108
IOMLocationType ...........................................................................................................................................................109
IdentityType ................................................................................................................................................................... 109
6
LogSeverity ....................................................................................................................................................................109
MediaType ..................................................................................................................................................................... 109
NetworkMode ............................................................................................................................................................... 109
PhysicalType .................................................................................................................................................................. 109
RepositoryState ..............................................................................................................................................................110
RepositoryStatus ............................................................................................................................................................110
ServerSlotType ............................................................................................................................................................... 110
ServiceTemplateComponentSubType ............................................................................................................................. 110
ServiceTemplateComponentType ................................................................................................................................... 110
ServiceTemplateSettingType ........................................................................................................................................... 111
UIRaidLevel ......................................................................................................................................................................111
UpdateType ..................................................................................................................................................................... 111
AsmDetailedMessage ...................................................................................................................................................... 111
AuthenticateRequest ......................................................................................................................................................112
AuthenticateResponse ....................................................................................................................................................112
ChassisController ............................................................................................................................................................112
ChassisPowerSupply .......................................................................................................................................................112
Enclosure ........................................................................................................................................................................113
FirmwareInventory ..........................................................................................................................................................113
GroupUser ...................................................................................................................................................................... 114
IKVM .............................................................................................................................................................................. 114
IpAddress ........................................................................................................................................................................114
IpRange .......................................................................................................................................................................... 115
Link .................................................................................................................................................................................115
List ................................................................................................................................................................................. 115
MemoryInventory ........................................................................................................................................................... 115
OSRepository ................................................................................................................................................................. 116
OperatingSystemSupport................................................................................................................................................116
ProcessorInventory .........................................................................................................................................................117
RejectedServer ...............................................................................................................................................................117
SelectedNIC ....................................................................................................................................................................117
ServerJobStatus .............................................................................................................................................................117
ServiceTemplateOption ...................................................................................................................................................118
ServiceTemplateUploadRequest ..................................................................................................................................... 118
SoftwareComponent ......................................................................................................................................................119
timeZone ........................................................................................................................................................................ 119
URL................................................................................................................................................................................ 120
UsageIdList ....................................................................................................................................................................120
VM .................................................................................................................................................................................120
connected_switch .......................................................................................................................................................... 121
dhcpSettings .................................................................................................................................................................. 121
fc_interface .................................................................................................................................................................... 121
logEntry ......................................................................................................................................................................... 122
ntpSettings .................................................................................................................................................................... 122
proxySettings .................................................................................................................................................................122
7
references ......................................................................................................................................................................122
testProxyResponse ........................................................................................................................................................123
timeZone ........................................................................................................................................................................123
AsmDetailedMessageList ............................................................................................................................................... 123
DeploymentDevice .........................................................................................................................................................123
DeviceDiscoveryRequest ............................................................................................................................................... 124
FirmwareComplianceComponents ................................................................................................................................. 125
FirmwareUpdateRequest ............................................................................................................................................... 125
GregorianCalendar ......................................................................................................................................................... 125
GroupUserList ................................................................................................................................................................126
IOM ................................................................................................................................................................................126
LogicalNetworkIdentityInventory ................................................................................................................................... 126
PhysicalDisk ................................................................................................................................................................... 126
Server ............................................................................................................................................................................ 127
ServiceTemplateValid ..................................................................................................................................................... 127
SoftwareBundle ............................................................................................................................................................. 127
StaticNetworkConguration .......................................................................................................................................... 128
VirtualDiskConguration .................................................................................................................................................128
availableTimeZones ........................................................................................................................................................129
credential .......................................................................................................................................................................129
wizardStatus ..................................................................................................................................................................129
Chassis .......................................................................................................................................................................... 130
ChassisLogEntry .............................................................................................................................................................131
DeviceDiscoveryRequests ...............................................................................................................................................131
LogicalNetworkInterface .................................................................................................................................................131
Network .........................................................................................................................................................................132
User ............................................................................................................................................................................... 132
VirtualDisk ......................................................................................................................................................................133
asmCredential ................................................................................................................................................................133
Controller .......................................................................................................................................................................133
Partition ......................................................................................................................................................................... 134
RAIDConguration ......................................................................................................................................................... 134
credentialList ................................................................................................................................................................. 135
Interface ........................................................................................................................................................................ 135
SelectedServer .............................................................................................................................................................. 135
DeploymentFilterResponse ............................................................................................................................................ 136
Fabric .............................................................................................................................................................................136
NetworkConguration ....................................................................................................................................................136
ServerNetworkObjects ...................................................................................................................................................137
ServiceTemplateSetting ................................................................................................................................................. 137
ServiceTemplateCategory .............................................................................................................................................. 138
component .................................................................................................................................................................... 138
FirmwareRepository ....................................................................................................................................................... 139
ServiceTemplate ............................................................................................................................................................ 140
Deployment .................................................................................................................................................................... 141
8
AddOnModule.................................................................................................................................................................142
DiscoveredDevices .........................................................................................................................................................143
DiscoveryResult ............................................................................................................................................................. 144
FirmwareDeviceInventory ...............................................................................................................................................144
DiscoveryRequest ..........................................................................................................................................................145
ManagedDevice .............................................................................................................................................................145
ManagedDeviceList ........................................................................................................................................................147
DeviceGroup .................................................................................................................................................................. 147
DeviceGroupList .............................................................................................................................................................147
10 Appendix C -Ruby Code Usage...................................................................................148
9
1
Overview
This document is intended for a technical audience. It is assumed that the reader is familiar with REST, and programmatic interaction
with REST APIs. In reality, any programming languages can be used with these APIs, however, the code examples contained in this
guide are written in Ruby. XML is also used extensively for these examples.
ASM is intended to automate the processes involved in provisioning, conguring, and managing bare metal hardware: chassis,
servers, switches, and network storage devices. ASM supports processes such as automated discovery of hardware, automated
installation of operating systems, creation of virtual networks, and rmware management.
Two essential concepts in ASM are, ServiceTemplate and Deployment process. A ServiceTemplate describes a blueprint for
provisioning and conguring a collection of devices as a named unit, also known as a Service. Deployment is the process of utilizing a
ServiceTemplate to physically realize what service the ServiceTemplate describes. While the names Deployment and Service are
synonymous, ASM-UI uses the term Service while the REST API uses the term Deployment.
ASM is distributed as a virtual appliance running a collection of interacting web applications that communicate through the REST
interfaces. An additional web application, ASM-UI, also residing on the appliance, provides full browser-based GUI access to ASM.
This ASM-UI interacts with ASM through the same REST interfaces described in this guide.
It is possible to eectively integrate ASM with any custom UI or access it through programs for better automation experiences.
In this API guide, we have described how to use these APIs with appropriate examples.
A full reference to all of the available REST methods is explained in Appendix A.
NOTE: Most of these REST methods exchange complex data models within the HTTP requests and responses, which
can be represented as either XML or JSON depending on the preference. The structure of these models is contained in
Appendix B for further reference.
Other Documents You May Need
Go to dell.com/asmdocs for additional supporting documents such as:
• Active System Manager Release 8.3 User’s Guide
• Active System Manager Release 8.3 Installation Guide
• Active System Manager Release 8.3 Compatibility Matrix
• Active System Manager Release 8.3 Release Notes
• Active System Manager Release 8.2 SDK Reference Guide
• Active System Manager Integration for VMware vRealize Orchestrator User's Guide
For more information about ASM, including how-to videos, white papers, and blogs, see the Active System Manager page on Dell
TechCenter:
http://www.dell.com/asmtechcenter
10
Resource URI Endpoints
An example of resource endpoint is:https://Api/V1/ServiceTemplate
From this example, API endpoints are accessible over https (at port 443 ).
All URI paths are prexed with /Api/V1/ where V1 is the current API version.
Following the prex above the remainder of the URI path (endpoint) will have the form /<resource>/<action>?<query>.
Where action and query are optional, and resource is one of the following resources:
• Authenticate
• Chassis
• Credential
• Deployment
• DeviceGroup
• DHCP
• DiscoveryRequest
• FirmwareRepository
• ManagedDevice
• Network
• NTP
• Proxy
• Server
• ServiceTemplate
• Timezone
• User
• WizardStatus
2
Each of these resources is fully detailed in Appendix A, showing the applicable HTTP methods for each, optional actions and query
parameters, and relevant payloads for POST and PUT methods.
11
Authentication Headers
All API requests require 3 custom HTTP headers for authentication.
• X-dell-auth-key
• X-dell-auth-signature
• X-dell-auth-timestamp
In order to compute the authentication headers, rst a REST call must be made to the /Authenticate endpoint. The Full URI
is /Api/V1/Authenticate.
This call must be a POST request supplying either an XML or JSON payload. For illustration, the XML payload will follow the
structure below providing the user name and password:
<AuthenticateRequest>
<userName>admin</userName>
<domain>ASMLOCAL</domain>
<password>abc123</password>
</AuthenticateRequest>
This call must be a POST request supplying either an XML or JSON payload. For illustration, the XML payload will follow the
structure below providing the user name and password:
Depending on the Accept header, the response will contain either an XML or JSON payload. For illustration we show the XML
version:
3
<AuthenticateResponse>
<userName>admin</userName>
<domain>ASMLOCAL</domain>
<role>Administrator</role>
<apiKey>34b3577f7c3c03174a9a506b</apiKey>
<apiSecret>9a6d9692ba64142e6a1934f9be994f3b0ae63959a6132c8b</apiSecret>
</AuthenticateResponse>
The returned apiKey and apiSecret from the XML response above will then be used to generate the security headers. The method is
to concatenate 5 values and then compute a digest using the apiSecret from above. For illustration, a Ruby implementation of the
generated headers is shown. This relies on the base64 and openssl gems to compute the signature and is extracted from the
supplied Ruby ASM module discussed further in Appendix C.
apiKey = '34b3577f7c3c03174a9a506b'
apiSecret = '9a6d9692ba64142e6a1934f9be994f3b0ae63959a6132c8b'
timestamp = Time.now.to_i.to_s
# Concatenate the following values
requestString = "%s:%s:%s:%s:%s" % [apiKey,httpMethod,uriPath,userAgent,timestamp]
# Compute a digest on concatenated string using apiSecret
hash_str = OpenSSL::HMAC.digest('sha256',apiSecret,requestString)
signature = Base64.strict_encode64(hash_str)
headers['x-dell-auth-key'] = apiKey
headers['x-dell-auth-signature'] = signature
headers['x-dell-auth-timestamp'] = timestamp
12
NOTE: Due to the timestamp component, authentication of future requests may fail if the 2 systems communicating with
each other have system clocks that are not well synchronized. So, this is essential before anything else, to synchronize
the system clocks of 2 dierent systems.
13
Generic Query Parameters
Many GET methods which return a list of objects support generic query parameters for ltering, sorting, and pagination. These
methods are indicated in the API reference section but the detailed syntax is described here.
• lter=<operator>,<valid lter column>,<value>,<value2>…
• operator is one of ( eq, co )
• where valid lter columns are listed for each supporting method in the API reference
• Examples:
– "eq,columnName,columnValue"
To include resources where columnName is columnValue.
– "eq,columnName,columnValue,columnValue2[,columnValue3…]"
To include resources where columnName is columnValue OR columnValue2.
– "eq,columnName,"
To include resources where columnName is empty.
– "eq,columnName,,columnValue[,columnValue2…]"
To include resources where columnName is empty OR columnValue.
– "co,columnName,columnValue"
To include resources where columnName contains columnValue:
4
• sort=[-]<valid sort column>, where valid sort columns are listed for each supporting method in the API reference and a minus
sign preceding the column name indicates descending order
• oset= <integer> default is 0
• limit= <integer> default is 50
Dates in query strings
Some of the columns that are sortable or lterable are dates such as createdDate. When using the lter parameter with date strings,
only the eq operator is valid. The format for these date strings is:
dd-MM-yyyy
example: 30-07-2015
14
5
HTTP Message Bodies
All HTTP Requests and Responses support both XML and JSON content types. The examples used throughout this document show
HTTP body content in XML form. The represented data models accepted and returned by the API calls can be quite complex. The
structure of these data models is detailed in Appendix B in a language independent representation. While it is possible to craft say an
XML request body from this reference documentation, a much more convenient method is to GET an existing object from ASM in
the desired representation ( XML or JSON ) and save it to a le for use as a skeleton for future requests involving that model type.
Since a fresh system will not have any existing Deployments. A Deployment model is shown below for illustration. It is actually only a
skeleton because it is lacking the essential ServiceTemplate content that would make it useful. For more information see the Usage
Example called Deploy a Service.
<?xml version="1.0" encoding="UTF-8"?>
<Deployment>
<deploymentName>Ottomatic</deploymentName>
<numberOfDeployments>1</numberOfDeployments>
<deploymentDescription>test REST deployment</deploymentDescription>
<allUsersAllowed>false</allUsersAllowed>
<canCancel>false</canCancel>
<canDelete>false</canDelete>
<canDeleteResources>false</canDeleteResources>
<canEdit>false</canEdit>
<canMigrate>false</canMigrate>
<canRetry>false</canRetry>
<canScaleupApplication>false</canScaleupApplication>
<canScaleupCluster>false</canScaleupCluster>
<canScaleupServer>false</canScaleupServer>
<canScaleupStorage>false</canScaleupStorage>
<canScaleupVM>false</canScaleupVM>
<updateServerFirmware>false</updateServerFirmware>
<individualTeardown>false</individualTeardown>
<teardown>false</teardown>
<retry>false</retry>
<serviceTemplate>
</serviceTemplate>
</Deployment>
Validations
Message bodies are subject to a wide range of validations. Capturing every validation rule is currently beyond the scope of this
document but a few general rules are worth noting.
• In general validation failures generate exceptions and structured messages to isolate the violation. See the section on Exception
Handling for more details. Most validation exceptions return a 400 HTTP response, but some API methods generate specic
HTTP response codes to indicate particular exceptions. These are listed in the API reference in the Appendix.
• Uniqueness validations. Many models require unique names. Notable models include ServiceTempate, Deployment, Network,
User. This violation returns a 409 HTTP response in these cases.
• Relationship constraints. In the case of deletion, an exception will occur when trying to delete an entity which is being used by
another entity.
• In a ServiceTemplate containing a Server component, if a hostname is supplied in addition to a hostname_template (hostname
generator ), this will not generate a validation exception and the behavior is to use the hostname_template over the supplied
hostname.
15
6
Usage Examples
The following examples use a simple Ruby module called ASM which utilizes the publicly available RestClient gem to perform the
HTTP requests. This module contains utilities to generate the security headers so we can focus on the API calls themselves. See
Appendix C for detailed information on using and conguring the ASM module.
In addition to the API requests, there is sometimes signicant XML processing required to prepare the request bodies or parse the
responses. A utility module ASM::Payload is provided for simple get/set operations on XML document elements and simple load/save
operations on XML les for use as starting templates and intermediate data storage between API calls. This module is not required
but is useful for simplifying the example code that follows.
Timezone
Get the current timezone
require 'ASMConfig'
# Get timezone settings
url = ASM::API::URI("/Timezone")
response = ASM::API::sign {
RestClient.get url
}
# Save it for future use as a payload
payload = ASM::Payload.from_xml(response)
payload.save_xml('timezone.xml')
Here we utilize a block construct to sign our request. All RestClient invocations inside the sign block will automatically be signed. The
url is specied simply as ‘/Timezone’ because ASM has already been congured with the base path prex /Asm/V1. The response
object as XML is:
<timeZone>
<timeZone>(UTC-06:00) Central Time (US & Canada)</timeZone>
<timeZoneId>11</timeZoneId>
</timeZone>
which we saved in the le ‘timezone.xml’ as a payload used in the next example to set the timezone.
Set the current timezone
Here we utilize the simple XML utility class called ASM::Payload to do simple manipulations of our XML.
require 'ASMConfig'
payload = ASM::Payload.load_xml('timezone.xml')
payload.set('timeZoneId','15')
# Set Timezone
response = ASM::API::sign {
16
url = ASM::API::URI("/Timezone")
RestClient.put url, payload.to_xml, :content_type => :xml
}
Credential
Credential objects can be created and referenced in ASM. These named credentials are used to gain access to the various Resources
during the Discovery process. Credentials are also typed according to their target resource such as, Server, Storage, VCenter, IOM,
Chassis, and SCVMM.
Get all dened Credentials
Default credentials are dened for several hardware types. These can be listed for the purpose of obtaining their reference id’s
needed for the Discovery process and to utilize as XML skeleton.
require 'ASMConfig'
url = ASM::API::URI('/Credential')
begin
response = ASM::API::sign {
RestClient.get url, :content_type => :xml
}
payload = ASM::Payload.from_xml(response)
payload.save_xml('credentials.xml')
rescue RestClient::Exception => e
print "Got exception with status: %d\n" % e.response.code
print "%s\n" % e.response
end
Dene new Credential
Dene a new Server Credential using a skeleton le previously saved to a le.
require 'ASMConfig'
url = ASM::API::URI('/Credential')
cred = ASM::Payload::load_xml('credential_skeleton.xml')
# Set Credential parameters
cred.set('label', 'ServerX')
cred.set('username', 'admin')
cred.set('password', 'abc123')
cred.set('protocol', '')
cred.set('snmpCommunityString', '')
response = ASM::API::sign {
RestClient.post url, cred.to_xml, :content_type => :xml
}
payload = ASM::Payload.from_xml(response)
credId = payload.get('id')
# Save it for future use as a payload
payload.save_xml("credential_%s.xml" % credId)
DiscoveryRequest
A DiscoveryRequest is a set of credential references and a set of IP ranges. A sweep of the given IP ranges will attempt to determine
if Resources of the given types, specied by the credential types referenced in the request, exist at those IP addresses.
17
Discover Chassis and contained Blade Servers
Using the predened chassis and server credentials, initiate a discovery request against an IP address that is known to belong to a
Chassis.
require 'ASMConfig'
url = ASM::API::URI('/DiscoveryRequest')
# Get credential ids
creds = ASM::Payload::load_xml('credentials.xml')
server_cred = creds.doc.xpath('//serverCredential').select{|c| c.at_xpath('label').text ==
'Dell PowerEdge Default'}.first.xpath('id').text
chassis_cred = creds.doc.xpath('//chassisCredential').select{|c| c.at_xpath('label').text
== 'Dell chassis default'}.first.xpath('id').text
disc = ASM::Payload::load_xml('discovery_skeleton.xml')
disc.set('deviceStartIp', '172.17.4.17')
disc.set('deviceEndIp', '172.17.4.17')
disc.set('unmanaged', 'false')
disc.appendChildren('DiscoverIPRangeDeviceRequest',
'deviceChassisCredRef' => chassis_cred,
'deviceServerCredRef' => server_cred,
'bDiscoverDevicesInChassis' => 'true')
begin
response = ASM::API::sign {
RestClient.post url, disc.to_xml, :content_type => :xml
}
payload = ASM::Payload.from_xml(response)
# Get the job status
jobStatus = payload.get('DiscoveryRequest/status')
print "<status>%s</status>\n" % jobStatus
rescue RestClient::Exception => e
print "Got exception with status: %d\n" % e.response.code
print "%s\n" % e.response
end
ManagedDevice
ManagedDevice is a generic interface to any Resources on the network which is being managed by ASM. A successful discovery
request results in the creation of instances of ManagedDevice.
Get all Managed Devices
Assuming the Discovery process succeeded, ASM will now know about some or all of the devices available on the network.
require 'ASMConfig'
url = ASM::API::URI('/ManagedDevice')
response = ASM::API::sign {
RestClient.get url
}
doc = Nokogiri::XML(response)
# Print selected info for each device
print "%30s%15s%20s%20s%15s\n" % %w(ServiceTag State IP Model Type)
print
18
"-------------------------------------------------------------------------------------------
---------\n"
doc.xpath('//ManagedDevice').sort_by{|d| d.at_xpath('deviceType').content}.each do |device|
svc_tag = device.at_xpath('serviceTag').content
state = device.at_xpath('state').content
ip_addr = device.at_xpath('ipAddress').content
model = device.at_xpath('model').content
dev_type = device.at_xpath('deviceType').content
print "%30s%15s%20s%20s%15s\n" % [svc_tag,state,ip_addr,model,dev_type]
end
ServiceTemplate
A ServiceTemplate is a reusable structure that denes the network topology and components of a future service deployment. A
trivial example template could be a single server component setup to run Linux. Deploying this template would result in a single
server being chosen from the available discovered resources and installing Linux on it.
Get all ServiceTemplates
Here we retrieve all ServiceTemplates and output the names of those not in draft mode ( published ). The draft property determines
if a template is in the published state. Only published templates can be deployed.
require 'ASMConfig'
url = ASM::API::URI('/ServiceTemplate')
result = ASM::API::sign {
RestClient.get url
}
# Do some XML processing to find all published templates
doc = Nokogiri::XML(result)
templates = doc.xpath('//ServiceTemplate')
published = templates.select{|t| t.at_xpath('draft').content == 'false'}
template_names = published.collect{|t| t.at_xpath('templateName').content}
print "Published Templates:\n"
template_names.each{|name| print "%s\n" % name}
Get a ServiceTemplate by name
Here we retrieve an existing ServiceTemplate from ASM named 'TwoServers' by passing the 'lter' query parameter. See the detail
for ServiceTemplate in Appendix B for the full list of names that can be sorted and ltered on. Note that even if the template name is
unique this method will always return a container around the result(s). For example, in the case of XML the root element is
<ServiceTemplates>.
require 'ASMConfig'
url = ASM::API::URI('/ServiceTemplate')
template_name = 'TwoServers'
template_filter = "eq,name,#{template_name}"
response = ASM::API::sign {
RestClient.get url, {:params=>{:filter=>template_filter}}
}
The response object is not shown for this example because it is too verbose. However, within the ServiceTemplate XML are
parameters designated with the element <requiredAtDeploy>. If this value is true, then this parameter will be required when this
19
ServiceTemplate is deployed. Otherwise the parameter is optional. For example, the server host name is required in this extracted
snippet of the ServiceTemplate. Save the result above to a le inspect the full XML for a ServiceTemplate.
<parameters>
<id>os_host_name</id>
<value/>
<type>STRING</type>
<displayName>Host Name</displayName>
<required>true</required>
<requiredAtDeployment>true</requiredAtDeployment>
<hideFromTemplate>true</hideFromTemplate>
<min>0</min>
<max>0</max>
<dependencyTarget>generate_host_name</dependencyTarget>
<dependencyValue>false</dependencyValue>
</parameters>
Publish a ServiceTemplate
In order to use a ServiceTemplate to deploy a Service, the ServiceTemplate must be rst published. This is accomplished by setting
the ServiceTemplate element <draft> to false. i.e. it is no longer in the draft state.
require 'ASMConfig'
templateId = "ff8080814be03f17014bea250f100b7d"
url = ASM::API::URI("/ServiceTemplate/%s"%templateId)
response = ASM::API::sign {
RestClient.get url
}
# Set draft to false
payload = ASM::Payload.from_xml(response)
payload.set('//draft', 'false')
# Send it back as a PUT
response = ASM::API::sign {
RestClient.put url, payload.to_xml, :content_type => :xml
}
Deployment
While the ASM UI refers to a Service, the REST API resource is not Service, but rather Deployment. The two terms are synonymous.
Deployments require an instance of a ServiceTemplate with its required parameters supplied.
Get all deployed Services
require 'ASMConfig'
response = ASM::API::sign {
url = ASM::API::URI("/Deployment")
RestClient.get url
}
doc = Nokogiri::parse(response)
doc.xpath('//Deployment').each do |deploy|
id = deploy.at_xpath('id').content
name = deploy.at_xpath('deploymentName').content
status = deploy.at_xpath('jobStatus').content
print "%s : %s : %s\n" % [id,name,status]
end
20
After getting all Services we print the id, name, and status of each. Services that are still in the act of being deployed will have a
status of IN_PROGRESS. So calling this method with the Deployment Id as a path parameter can also be used to periodically poll a
Deployment to nd out when it has nished.
Deploy a new Service
Here, after having previously gotten an existing ServiceTemplate by name, and saved it to a le, we then set the required parameters
in the ServiceTemplate le, and nally embed the ServiceTemplate into a prefabricated Deployment structure that is read from a le.
As mentioned previously we can monitor the status of this Deployment by performing a GET with the deployment id as a path
parameter.
require 'ASMConfig'
url = ASM::API::URI('/Deployment')
template_name = 'TwoServers'
template = ASM::Payload::load_xml("%s.xml"%template_name)
deployment = ASM::Payload::load_xml('deployment_skeleton.xml')
# Set Deployment parameters
deployment.set("deploymentName", 'ManualAPIDeploymentDeux')
deployment.set("deploymentDescription", 'Manual API Deployment')
deployment.set("numberOfDeployments", '1')
# Inject the template into the deployment
deployment.replaceInner('serviceTemplate', template.doc.at_xpath('ServiceTemplate'))
deployment.save_xml('deploy_payload.xml')
response = ASM::API::sign {
RestClient.post url, deployment.to_xml, :content_type => :xml
}
doc = Nokogiri::parse(response)
deploymentId = doc.xpath('//Deployment/id').text
print "<id>%s</id>\n" % deploymentId
Tear down a Service
In order to completely tear down a Service we set the teardown element to true for all components in the Deployment plus the
Deployment itself, and then we PUT this Deployment back to ASM.
require 'ASMConfig'
deploymentId = "ff8080814aba74ce014ac455e9b80951"
url = ASM::API::URI("/Deployment/%s"%deploymentId)
response = ASM::API::sign {
RestClient.get url
}
payload = ASM::Payload.from_xml(response)
payload.set('Deployment/teardown', 'true')
payload.set_all('components/teardown', 'true')
payload.save_xml('teardown.xml')
response = ASM::API::sign {
RestClient.put url, payload.to_xml, :content_type => :xml
}
doc = Nokogiri::parse(response)
deploymentId = doc.xpath('//Deployment/id').text
jobStatus = doc.xpath('//Deployment/jobStatus').text
print "<jobStatus>%s</jobStatus>\n" % jobStatus
21
Firmware
Firmware versions reported by individual resource components are compared against a rmware repository to determine if
component rmware is up-to-date with the latest required versions.
Check Firmware compliance of all Resources
Here we check the rmware compliance state of all resources. Note this is done by the POST method and supplying a
ManagedDevice as the request body. The response is the same ManagedDevice with the addition of a compliance eld.
require 'ASMConfig'
# Get all managed devices
url = ASM::API::URI('/ManagedDevice')
response = ASM::API::sign {
RestClient.get url
}
doc = Nokogiri::XML(response)
doc.xpath('//ManagedDevice').each do |device|
url = ASM::API::URI('/FirmwareRepository/compliance')
begin
response = ASM::API::sign {
RestClient.post url, device.to_xml, :content_type => :xml
}
doc2 = Nokogiri::XML(response)
serviceTag = doc2.at_xpath('//serviceTag').content
compliance = doc2.at_xpath('//compliance').content
print "Device %s firmware is %s\n" % [serviceTag,compliance]
rescue RestClient::Exception => e
print "Got exception with status: %d\n" % e.response.code
print "%s\n" % e.response
end
end
22
7
Exception Handling
When an HTTP error code is returned the response payload will contain information about the error that occurred. For the purpose
of illustration the following exception response was intentionally generated by trying to get a ServiceTemplate with an id that doesn't
exist. In this case the HTTP response was 404 and the XML response is below. See the API reference section for the relevant HTTP
responses that may be returned by each REST endpoint.
The example code used to catch this exception and report the error is below.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AsmDetailedMessageList>
<Messages>
<messages>
<messageBundle>AsmManagerMessages</messageBundle>
<messageCode>ASM0042</messageCode>
<severity>ERROR</severity>
<category>USER_FACING</category>
<displayMessage>Unable to find the Template Id: ABC.</displayMessage>
<responseAction>Make sure that a correct Template Id is entered and retry the
operation. Template Ids are case sensitive. Verify the list of devices under the Summary
tab to make sure whether or not the Template already exists.</responseAction>
<detailedMessage>The Template Id cannot be found.</detailedMessage>
<agentId>ASM Manager</agentId>
<timeStamp>2015-03-10T14:34:24.866Z</timeStamp>
<sequenceNumber>0</sequenceNumber>
</messages>
</Messages>
</AsmDetailedMessageList>
require 'ASMConfig'
templateId = "ABC" // bogus id
url = ASM::API::URI("/ServiceTemplate/%s"%templateId)
begin
response = ASM::API::sign {
RestClient.get url
}
rescue RestClient::Exception => e
print "Got exception with status: %d\n" % e.response.code
print "%s\n" % e.response
end
23
Appendix A - API Reference
/AddOnModule
Description
Retrieve all AddOnModule with lter, sort, paginate which returns Array of AddOnModule.class
Method
get
Response Class
AddOnModule
Response Content-Type: application/json, application/xml
Parameters
8
Table 1. Parameters
Parameter Value Description Default Value Parameter Type Data Type
sort N/A Sort Column N/A query string
lter N/A Filter Criteria N/A query array
oset N/A Pagination Oset 0 query integer
limit N/A Page Limit 50 query integer
Response Status Codes
Table 2. Response Status Codes
HTTP Status Code Reason
200 All AddOnModule Retrived on lter, sort, paginate
/AddOnModule
Description
Create a new AddOnModule
24
Method
post
Response Class
Response Content-Type: application/xml, application/json
Parameters
Table 3. Parameters
Parameter Value Description Default Value Parameter Type Data Type
body (required) AddOnModule N/A body AddOnModule
Response Status Codes
Table 4. Response Status Codes
HTTP Status Code Reason
201 AddOnModule created
400 Bad Request, verify AddOnModule upload URL is correct
/AddOnModule/{id}
Description
Retrieve an individual AddOnModule
Method
get
Response Class
Response Content-Type: application/xml, application/json
Parameters
Table 5. Parameters
Parameter Value Description Default Value Parameter Type Data Type
id (required) addOnModuleId N/A path string
Response Status Codes
Table 6. Response Status Codes
HTTP Status Code Reason
200 retrieved
400 Bad Request, verify id is correct
25
HTTP Status Code Reason
404 Bad Request, verify id is correct
/Authenticate/
Description
Conrm User access credentials
Method
post
Response Class
AuthenticateResponse
Response Content-Type: application/json, application/xml
Parameters
Table 7. Parameters
Parameter Value Description Default Value Parameter Type Data Type
body (required) Description of user
to be authenticated
N/A body AuthenticateReques
t
Response Status Codes
Table 8. Response Status Codes
HTTP Status Code Reason
201 Authentication successful
401 User not found, domain not found or password does not match
/Chassis/
Description
Retrieve a list a Chassis Devices
Method
get
Response Class
[ Chassis ]
Response Content-Type: application/xml, application/json
26
Parameters
Table 9. Parameters
Parameter Value Description Default Value Parameter Type Data Type
sort N/A Valid sort columns:
health,managementI
P,serviceTag,creden
tialRefId
lter N/A Valid lter columns:
health,managementI
P,serviceTag,creden
tialRefId
oset N/A Specify pagination
oset
limit N/A Specify page limit 50 query integer
N/A query string
N/A query array
0 query integer
Response Status Codes
Table 10. Response Status Codes
HTTP Status Code Reason
200 Retrieved
400 Bad Request, verify input parameters are correct
401 No login information specied in the request
403 User doesn't have privileges to access this operation
500 Server Internal Error, contact your system administrator
/Chassis/{refId}
Description
Retrieve an individual Chassis Device
Method
get
Response Class
Chassis
Response Content-Type: application/xml, application/json
Parameters
Table 11. Parameters
Parameter Value Description Default Value Parameter Type Data Type
refId (required) Device Id N/A path string
27
Response Status Codes
Table 12. Response Status Codes
HTTP Status Code Reason
200 retrieved
400 Bad Request, verify Device id is correct
404 Bad Request, verify Device id is correct
/Chassis/{refId}
Description
Update The Chasis conguration
Method
put
Response Class
Chassis
Response Content-Type: application/xml, application/json
Parameters
Table 13. Parameters
Parameter Value Description Default Value Parameter Type Data Type
body (required) Chassis to update N/A body Chassis
refId (required) Id of Chassis to
update
N/A path string
Response Status Codes
Table 14. Response Status Codes
HTTP Status Code Reason
204 Update completed successfully
400 Problem with the update data, check error response for details
404 Chasis not found
/Chassis/{refId}
Description
Deletes an existing Chassis Device
28
Method
delete
Response Class
void
Response Content-Type: application/xml, application/json
Parameters
Table 15. Parameters
Parameter Value Description Default Value Parameter Type Data Type
refId (required) Device Id N/A path string
Response Status Codes
Table 16. Response Status Codes
HTTP Status Code Reason
204 deleted
400 Bad Request, verify Device id is correct.
/Chassis/iom/ip/{ip}
Description
Retrieve an individual IOM Device
Method
get
Response Class
IOM
Response Content-Type: application/xml, application/json
Parameters
Table 17. Parameters
Parameter Value Description Default Value Parameter Type Data Type
ip (required) Device IP N/A path string
29
Response Status Codes
Table 18. Response Status Codes
HTTP Status Code Reason
200 retrieved
400 Bad Request, verify Device IP is correct
404 Bad Request, verify Device IP is correct
/Chassis/{refId}/sensorlog
Description
Retrieve an individual Chassis Device Sensor Event Logs
Method
get
Response Class
[ ChassisLogEntry ]
Response Content-Type: application/xml, application/json
Parameters
Table 19. Parameters
Parameter Value Description Default Value Parameter Type Data Type
refId (required) Device Id N/A path string
Response Status Codes
Table 20. Response Status Codes
HTTP Status Code Reason
200 retrieved
400 Bad Request, verify Device id is correct
404 Bad Request, verify Device id is correct
/Chassis/{refId}/sensorlog
Description
Clear an individual Chassis Device Sensor Event Logs
Method
delete
30