Cisco UCS Director REST Developer Guide, Release 5.1
First Published: September 29, 2014
Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS,
INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH
THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY,
CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version
of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS.
CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT
LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS
HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network
topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional
and coincidental.
Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: http://
www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership
relationship between Cisco and any other company. (1110R)
© 2014
Cisco Systems, Inc. All rights reserved.
CONTENTS
Preface
Preface vii
Audience vii
Conventions vii
Related Documentation ix
Documentation Feedback ix
Obtaining Documentation and Submitting a Service Request ix
CHAPTER 1
New and Changed Information for this Release 1
New and Changed Information 1
CHAPTER 2
Overview 7
About the Cisco UCS Director REST API 7
Access Privileges 7
Supported Protocols and Formats 8
Recommended Tools 8
CHAPTER 3
Getting Started 11
About the API Access Key 11
Generating an API Access Key 11
Enabling the Developer Menu Options 12
Using the REST API Browser 13
Accessing the Report Metadata 14
Request Format 14
Response Format 17
CHAPTER 4
API Operations 19
About the REST API Operations 20
Cisco UCS Director REST Developer Guide, Release 5.1
iii
Contents
Login Operations 20
User Account Operations 21
Account Operations 24
Report Operations 26
Approval Operations 29
Catalog Operations 29
Chargeback Operations 31
Funds Operations 31
Group Operations 32
Inventory (Cloud) Operations 32
LOV Provider Operations 33
Payment Status Operations 34
Resource Accounting and Limits 34
Service Container Operations 36
APIC Container Operations 42
Service Category Operations 43
Service Request Operations 44
Task Operations 49
VDC Operations 49
VM Operations 51
Workflow Operations 63
Activity Operations 66
Tag Operations 67
Resource Group Operations 69
Application Profile Operations 71
Tenant Profile Operations 72
Tenant Onboarding Operations 74
CHAPTER 5
API Request Parameters 75
API Request Context Parameters 75
API Request Parameters for Reports or JSON Objects 77
CHAPTER 6
JSON Objects 79
JSON Object Parameter Types 79
JSON Example: APIVDCDetails 80
Cisco UCS Director REST Developer Guide, Release 5.1
iv
Contents
JSON Example: APICatalogItem 81
JSON Example: APIUserOnBoardParams 81
JSON Example: APIUserOnBoardDetails 81
JSON Example: APILoginProfile 81
JSON Example: APIMakePaymentParams 82
JSON Example: APIProvisionParams 82
JSON Example: APIServiceContainerTemplate 82
CHAPTER 7
Reports 89
About Reports 89
Reports and JSON Object Response Samples 90
Using GetAvailableReports to Obtain ReportIds 97
Tabular Reports 99
Example of a Tabular Report 99
Historical Reports 100
Example of a Historical Report 100
Snapshot Reports 100
Example of a Snapshot Report 101
List of Available Cisco UCS Director Reports 101
Using the List of Available Reports 118
CHAPTER 8
Additional REST API Resources 119
Creating and Testing API Request Code using XML or Java 119
Importing a Custom Task 120
CHAPTER 9
About the Java API 123
Java API Examples 123
Java Example: userAPIGetMyLoginProfile 123
Java Example: userAPIGetAllVDCs 124
APPENDIX A
Cisco UCS Director REST API SDK Bundle 125
About the Cisco UCS Director REST API SDK Bundle 125
Importing the SDK Bundle Project into the Eclipse IDE 126
Cisco UCS Director REST Developer Guide, Release 5.1
v
Contents
Cisco UCS Director REST Developer Guide, Release 5.1
vi
Preface
This preface contains the following sections:
• Audience, page vii
• Conventions, page vii
• Related Documentation, page ix
• Documentation Feedback, page ix
• Obtaining Documentation and Submitting a Service Request, page ix
Audience
This guide is intended for software engineers with expertise using APIs to develop and extend applications.
These engineers should understand Cisco UCS and related networking and storage protocols, and have
experience working with JSON, XML, and Java.
Conventions
Text Type
Indication
GUI elements
GUI elements such as tab titles, area names, and field labels appear in this font.
Main titles such as window, dialog box, and wizard titles appear in this font.
Document titles
Document titles appear in this font.
TUI elements
In a Text-based User Interface, text the system displays appears in this font.
System output
Terminal sessions and information that the system displays appear in this
font.
CLI commands
CLI command keywords appear in this font.
Variables in a CLI command appear in this font.
Cisco UCS Director REST Developer Guide, Release 5.1
vii
Preface
Conventions
Note
Tip
Text Type
Indication
[]
Elements in square brackets are optional.
{x | y | z}
Required alternative keywords are grouped in braces and separated by vertical
bars.
[x | y | z]
Optional alternative keywords are grouped in brackets and separated by vertical
bars.
string
A nonquoted set of characters. Do not use quotation marks around the string or
the string will include the quotation marks.
<>
Nonprinting characters such as passwords are in angle brackets.
[]
Default responses to system prompts are in square brackets.
!, #
An exclamation point (!) or a pound sign (#) at the beginning of a line of code
indicates a comment line.
Means reader take note. Notes contain helpful suggestions or references to material not covered in the
document.
Means the following information will help you solve a problem. The tips information might not be
troubleshooting or even an action, but could be useful information, similar to a Timesaver.
Caution
Means reader be careful. In this situation, you might perform an action that could result in equipment
damage or loss of data.
Timesaver
Means the described action saves time. You can save time by performing the action described in the
paragraph.
Warning
IMPORTANT SAFETY INSTRUCTIONS
This warning symbol means danger. You are in a situation that could cause bodily injury. Before you
work on any equipment, be aware of the hazards involved with electrical circuitry and be familiar with
standard practices for preventing accidents. Use the statement number provided at the end of each warning
to locate its translation in the translated safety warnings that accompanied this device.
SAVE THESE INSTRUCTIONS
Cisco UCS Director REST Developer Guide, Release 5.1
viii
Preface
Related Documentation
Related Documentation
Cisco UCS Director Documentation Roadmap
For a complete list of Cisco UCS Director documentation, see the Cisco UCS Director Documentation
Roadmap available at the following URL: http://www.cisco.com/en/US/docs/unified_computing/ucs/
ucs-director/doc-roadmap/b_UCSDirectorDocRoadmap.html.
Cisco UCS Documentation Roadmaps
For a complete list of all B-Series documentation, see the Cisco UCS B-Series Servers Documentation Roadmap
available at the following URL: http://www.cisco.com/go/unifiedcomputing/b-series-doc.
For a complete list of all C-Series documentation, see the Cisco UCS C-Series Servers Documentation Roadmap
available at the following URL: http://www.cisco.com/go/unifiedcomputing/c-series-doc.
Note
The Cisco UCS B-Series Servers Documentation Roadmap includes links to documentation for Cisco
UCS Manager and Cisco UCS Central. The Cisco UCS C-Series Servers Documentation Roadmap includes
links to documentation for Cisco Integrated Management Controller.
Documentation Feedback
To provide technical feedback on this document, or to report an error or omission, please send your comments
to [email protected]. We appreciate your feedback.
Obtaining Documentation and Submitting a Service Request
For information on obtaining documentation, submitting a service request, and gathering additional information,
see the monthly What's New in Cisco Product Documentation, which also lists all new and revised Cisco
technical documentation.
Subscribe to the What's New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed
and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free
service and Cisco currently supports RSS version 2.0.
Cisco UCS Director REST Developer Guide, Release 5.1
ix
Preface
Obtaining Documentation and Submitting a Service Request
Cisco UCS Director REST Developer Guide, Release 5.1
x
CHAPTER
1
New and Changed Information for this Release
• New and Changed Information, page 1
New and Changed Information
The following table provides an overview of the significant changes to this guide for this current release. The
table does not provide an exhaustive list of all changes made to this guide or of all new features in this release.
Table 1: New Features and Changed Behavior in Cisco UCS Director, Release 5.1
Feature
What's New
Where Documented
Deprecated
From Cisco UCS Director Release 5.x and later
UserAPIProvisionRequestWithPortGroup releases, deprecated the
UserAPIProvisionRequestWithPortGroup API.
To provision a VM, use the
userAPIVMWareProvisionRequest API.
VM Operations, on page 51
REST API support for APIC
Container and Fenced Container
Updated service container APIs to support both
the fenced container and the APIC container.
Service Container Operations, on page 36
REST API support for APIC
Container
Added the following API for creating an APIC
container:
APIC Container Operations, on page 42
• userAPICreateAPICContainer
REST API support for Account
Updated the parameter for the following API:
Account Operations, on page 24
• userAPICreateInfraAccount
Added the following API for modifying the
account:
• userAPIUpdateInfraAccount
Cisco UCS Director REST Developer Guide, Release 5.1
1
New and Changed Information for this Release
New and Changed Information
Feature
What's New
Where Documented
REST API support for Service
Category
Added the following APIs:
Service Category Operations, on page 43
• userAPIGetServiceCategory
• userAPICreateServiceCategory
• userAPICloneServiceCategory
• userAPIModifyServiceCategory
• userAPIDeleteServiceCategory
REST API support for Activity
Added the following APIs:
Activity Operations, on page 66
• userAPIGetActivity
• userAPICreateActivity
• userAPICloneActivity
• userAPIModifyActivity
• userAPIDeleteActivity
REST API support for Tag
Added the following APIs:
Tag Operations, on page 67
• userAPIGetTagLibrary
• userAPICreateTag
• userAPICloneTag
• userAPIModifyTag
• userAPIDeleteTag
REST API support for Resource
Group
Added the following APIs:
Resource Group Operations, on page 69
• userAPIgetResourceGroups
• userAPICreateResourceGroup
• userAPIModifyResourceGroup
• userAPIDeleteResourceGroup
REST API support for Application Added the following APIs:
Profile
• userAPIGetApplicationProfile
• userAPICreateApplicationProfile
• userAPIModifyApplicationProfile
• userAPIDeleteApplicationProfile
Cisco UCS Director REST Developer Guide, Release 5.1
2
Application Profile Operations, on page
71
New and Changed Information for this Release
New and Changed Information
Feature
What's New
Where Documented
REST API support for Tenant
Profile
Added the following APIs:
Tenant Profile Operations, on page 72
• userAPIGetTenantProfile
• userAPICreateTenantProfile
• userAPICloneTenantProfile
• userAPIModifyTenantProfile
• userAPIDeleteTenantProfile
REST API support for Tenant
Onboarding
Added the following API:
• userAPIInitiateTenantOnboarding
Tenant Onboarding Operations, on page
74
Table 2: New Features and Changed Behavior in Cisco UCS Director, Release 4.1.0.4 and Release 5.0
Feature
What's New
Where Documented
REST API support for Workflow
Added the following API:
Workflow Operations, on page 63
• userAPIGetWorkflowStatus
REST API support for Account
Added the following APIs:
Account Operations, on page 24
• userAPICreateInfraAccount
• userAPIGetAllAccounts
• userAPIGetAllPhysicalInfraAccounts
• userAPIGetAccountTypeEntryByName
• userAPIGetAccountTypeByName
• userAPIDeleteInfraAccount
REST API support for Service
Container
Updated the parameters and return type for the
following APIs:
Service Container Operations, on page 36
• userAPIGetServiceContainerDetails
• userAPIPowerOnServiceContainer
• userAPIPowerOffServiceContainer
• userAPIAddVMsServiceContainer
• userAPIDeleteServiceContainer
Cisco UCS Director REST Developer Guide, Release 5.1
3
New and Changed Information for this Release
New and Changed Information
Feature
What's New
Where Documented
REST API support for Service
Container
Added the following APIs:
Service Container Operations, on page 36
• userAPICreateServiceContainerTemplate
• userAPIUpdateServiceContainerTemplate
• userAPICreateServiceContainerWithoutCatalog
REST API support for Virtual Data Added the following APIs:
Center (vDC)
• userAPIExportVDC
VDC Operations, on page 49
• userAPIImportVDC
REST API support for Virtual
Machine
Added the following APIs:
VM Operations, on page 51
• UserAPIProvisionRequest
• UserAPIProvisionRequestWithPortGroup
• userAPIDeleteCatalogItem
• userAPIVMWareProvisionRequest
• userAPIVMWareCloneVMProvisionRequest
• userAPIVMWareMoveVMProvisionRequest
Updated the action name list for the following
APIs:
• userAPIExecuteVMAction (for Generic
VMs)
• userAPIExecuteVMAction (for Microsoft
Hyper-V VMs)
• userAPIExecuteVMAction (for Microsoft
Hyper-V VMs)
JSON Example: APIVDCDetails
Provided the examples of valid name/value pairs JSON Example: APIVDCDetails, on page
for the Hyper-V type virtual Data Center (vDC) 80
and VMware type vDC.
Importing a Custom Task
Added the procedure to import a custom task.
Cisco UCS Director REST Developer Guide, Release 5.1
4
Importing a Custom Task, on page 120
New and Changed Information for this Release
New and Changed Information
Table 3: New Features and Changed Behavior in Cisco UCS Director, Release 4.1.0.3
Feature
Description
Where Documented
REST API support for Service
Container
Added the following APIs:
Service Container Operations, on page 36
• userAPIGetApplicationContainerTemplateDetails
• userAPIGetServiceContainerDetails
• userAPIGetServiceContainerVirtualInfraPolicy
• userAPIAddVMsServiceContainer
• userAPIPowerOnServiceContainer
• userAPIPowerOffServiceContainer
• userAPIDeleteServiceContainer
• userAPICloneServiceContainer
Reports
userAPIGetServiceContainerDetails (tabular
report)
Reports and JSON Object Response
Samples, on page 90
Service Request Operations
Updated the workflow status of
userAPIGetServiceRequestWorkFlow
Service Request Operations, on page 44
VM Operations
Updated the parameters of userAPIGetAllVMs
VM Operations, on page 51
Cisco UCS Director REST Developer Guide, Release 5.1
5
New and Changed Information for this Release
New and Changed Information
Cisco UCS Director REST Developer Guide, Release 5.1
6
CHAPTER
2
Overview
This chapter contains the following sections:
• About the Cisco UCS Director REST API, page 7
• Access Privileges, page 7
• Supported Protocols and Formats, page 8
• Recommended Tools, page 8
About the Cisco UCS Director REST API
The Cisco UCS Director REST API enables you to perform operations on Cisco UCS Director resources and
to integrate these operations into applications so that they can provide API-supported functionality and features.
You can use applications developed using this REST (Representational State Transfer) API to do the following:
• Get Cisco UCS Director reports about physical and virtual devices, networks, appliances, groups and
users, policies, administration, resource accounting, funds, and other monitored entities within your
Cisco UCS domains.
• Invoke orchestrator workflow and task operations.
• Invoke additional operations specific to Cisco UCS Director.
Access Privileges
With appropriate access privileges, you can use the APIs to get any report made available through Cisco UCS
Director. Access to the API interface is limited to registered user accounts. Secure access is administered
through the use of the REST API Access Key, which is a unique key code assigned to each user account. A
user account is administratively associated with a user type, so this access key determines the user account's
level of access to information exposed through the API.
Different user types have access to different categories of data. A Cisco UCS Director administrator defines
the access rules associated with each user type. For more information on the end-user and administrator user
types and the data accessible to each type of user, see the http://www.cisco.com/c/en/us/support/
servers-unified-computing/ucs-director/products-maintenance-guides-list.html or contact your system
Cisco UCS Director REST Developer Guide, Release 5.1
7
Overview
Supported Protocols and Formats
administrator . Work with your system administrator to get the necessary user access privileges for your
project.
Supported Protocols and Formats
Cisco UCS Director REST APIs are compatible with any HTTP or HTTPS browser. The REST APIs use
code formatted in JSON and XML. A Java API is also available.
JSON
Unless otherwise noted, the Cisco UCS Director API documentation refers to REST API request arguments
and responses (payload data) that are encoded in JSON (JavaScript Object Notation) format. For more
information, see http://www.json.org or http://en.wikipedia.org/wiki/JSON.
Note
Live and valid UCS Director REST API requests and responses in JSON format are provided within Cisco
UCS Director. These provide excellent examples of JSON protocols and formatting. To see this API data,
you must first enable the developer menus and then use the Report Metadata option available on any
report in Cisco UCS Director. For more information, see Enabling the Developer Menu Options, on page
12.
XML
For information about using XML-formatted REST API requests, see Using the REST API Browser, on page
13. This provides information about using the REST API browser, which is embedded in Cisco UCS Director.
Java
For information about using the Java API, see the Cisco UCS Director REST API Javadocs ands the Cisco
UCS Director Open Automation API Javadocs.
Recommended Tools
The Cisco UCS Director API uses HTTP or HTTPS as communication protocols. Any compatible browser
or client with user account access can be used to submit requests to the Cisco UCS Director API. Most
programming languages have built-in or open source libraries that provide REST API access and parsing of
JSON and XML.
For exploring and testing the APIs, we recommend the following software tools and options:
Developer Menu Options
Cisco UCS Director includes Developer Menu options that include crucial features and tools for developers,
such as Report Metadata and access to the Rest API Browser. To enable these options, see Accessing the
Report Metadata, on page 14.
Cisco UCS Director REST Developer Guide, Release 5.1
8
Overview
Recommended Tools
Mozilla Firefox RESTClient Add-On
RESTClient is a Mozilla FireFox add-on that provides useful options for parsing and viewing API requests
and responses. See https://addons.mozilla.org/en-US/firefox/addon/restclient/?src=ss, but check for more
recent releases.
Note
If you are currently logged into Cisco UCS Director with user account credentials that your application
will use, you should be able to use any supported web browser to send API requests and get responses.
However, the Mozilla Firefox RESTClient add-on provides a standalone client that also parses and labels
the API data in a useful and informative way.
Cisco UCS Director REST API Browser
The REST API Browser is available in the Orchestration area of Cisco UCS Director. It provides API
information and API code generation capabilities that make it easy to see and work with all of the available
APIs, including both the REST APIs and the Java API.
After you enable the developer menu, you can access this feature and get extensive information about Cisco
UCS Director exposed APIs, including the REST API in XML format and the Java API. For more information,
see Using the REST API Browser, on page 13.
Cisco UCS Director REST Developer Guide, Release 5.1
9
Overview
Recommended Tools
Cisco UCS Director REST Developer Guide, Release 5.1
10
CHAPTER
3
Getting Started
This chapter contains the following sections:
• About the API Access Key, page 11
• Generating an API Access Key, page 11
• Enabling the Developer Menu Options, page 12
• Using the REST API Browser, page 13
• Accessing the Report Metadata, page 14
• Request Format, page 14
• Response Format, page 17
About the API Access Key
To access Cisco UCS Director through the API interface, you must have a valid Cisco UCS Director user
account and an API access key. The API access key is required for Cisco UCS Director to authenticate API
requests. This access key is a unique security access key code that is associated with a specific, valid Cisco
UCS Director user account.
To authenticate API requests, all Cisco UCS Director APIs require the API access key for authentication. You
must pass the REST API access key as a name:value header following standard HTTP syntax and semantic
rules. For example, a valid name:value header is X-Cloupia-Request-Key:
F90ZZF12345678ZZ90Z12ZZ3456FZ789. For more information about the API request header, see Request
Format, on page 14 and RFC2616 Header Field Definitions.
To provide data security, send all requests over an HTTPs (SSL) connection.
Generating an API Access Key
Procedure
Step 1
In Cisco UCS Director, click your login name in the upper right.
Cisco UCS Director REST Developer Guide, Release 5.1
11
Getting Started
Enabling the Developer Menu Options
For example, if you logged in as admin, Cisco UCS Director displays admin in the upper right.
Step 2
In the User Information dialog box, click the Advanced tab.
Step 3
Step 4
To copy the value displayed in the REST API Access Key area, click Copy Key Value.
Save the access key in a secure location, and use it in the API request header.
For more information about the API request header, see Request Format, on page 14.
Step 5
If you want to change the API access key, click Regenerate Key.
After you generate a new key, the old key code is retired and you cannot use it.
Enabling the Developer Menu Options
Cisco UCS Director includes features and capabilities that are intended expressly for developers and engineers.
After you enable the Developer Menus option, you have access to the integrated REST API Browser and
Report Metadata information. These features provide you with site-specific API data and with REST API
request code that you can send through any standard HTTP or HTTPS browser. The HTTP request code
provided by the Report Metadata views yields immediate API service results. Plan to use these options in
every situation where you need API information.
The Cisco UCS Director REST API Browser provides API information and API code generation capabilities
that make it easy to see and work with all of the available APIs, including both the REST APIs and the Java
API.
Before You Begin
Obtain one or more user accounts that provide exactly the same administrative access to data that your
application users will have. Your Cisco UCS Director administrator can explain the data access limitations
associated with different administrator and end-user roles. You may want multiple user accounts in order to
test the user-experiences associated with different data access and security controls.
Procedure
Step 1
In Cisco UCS Director, click your login name in the upper right.
For example, if you logged in as admin, Cisco UCS Director displays admin in the upper right.
Step 2
In the User Information dialog box, click the Advanced tab.
Step 3
Check the Enable Developer Menu (for this session) check box and close the User Information dialog box.
The REST API Browser is activated for the duration of the current session, and the Report Metadata option
becomes available in the report views opened in the session.
Tip
Step 4
The Advanced tab also displays the REST API Access Key code for the account.
Close the User Information dialog box.
Cisco UCS Director REST Developer Guide, Release 5.1
12
Getting Started
Using the REST API Browser
Using the REST API Browser
The Cisco UCS Director REST API Browser provides API information and API code generation capabilities
that assist and educate Developers in the use of all available exposed Cisco UCS Director APIs, including the
XML-formatted REST API and the Java API. The primary view lists the Task folders, each of which provides
access to the APIs. The task name effectively supplies the top-level context or category folder under which
the APIs are listed. For example, all the APIs pertaining to NetApp ONTAP tasks and NetApp OnCommand
tasks are available inside the folders with these names.
Before You Begin
• Obtain one or more user accounts that provide exactly the same administrative access to data that your
application users will have. Your Cisco UCS Director administrator can explain the data access limitations
associated with different administrator and end-user roles. You may want multiple user accounts in order
to test the user-experiences associated with different data access and security controls.
• Enable the Developer Menu options for the session.
Procedure
Step 1
Step 2
On the menu bar, choose Policies > Orchestration.
Click the REST API Browser tab.
Click the right scroll arrow, if necessary, to navigate to the REST API Browser tab.
Step 3
Open the task folder that contains the API you want to view.
Tip
You can use the Search field at the top right corner of the Rest API Browser tab to find a specific
API if you do not know which task folder it belongs in. Enter a string that occurs in the API Resource,
Operation or Description fields to narrow your search. You can also use the other options on that menu
bar, such as the Add Advanced Filter, to help you find a specific API.
Double-click a row that contains an API resource and operation that interests you.
The REST API browser displays the following:
Step 4
• API Examples tab—Displays the API data for your selection and enables you to generate a sample
URL. Depending on the operation and resource that you selected, this tab might also include data entry
boxes that accept parameter values and enable you to construct a successful API request. If available in
a data entry box, click Select... to open data search filters that can help you sort out and select the data
that you need to enter.
• Details tab—Provides additional details about the API, including the API definition, input parameters,
and output parameters.
• Sample Java Code tab—Provides sample code for the API.
Cisco UCS Director REST Developer Guide, Release 5.1
13
Getting Started
Accessing the Report Metadata
Accessing the Report Metadata
Report Metadata enables you to view the API code used by Cisco UCS Director, including the API request
code for every report displayed in Cisco UCS Director. This code includes complete URL code that is ready
to paste into a browser and send. The immediate API responses provide a trove of information and education
for the developer. To see the API request code, you simply navigate to a report, select Report Metadata, and
scroll down through the resulting list to the API request used to fetch the report.
Before You Begin
• Obtain one or more user accounts that provide exactly the same administrative access to data that your
application users will have. Your Cisco UCS Director administrator can explain the data access limitations
associated with different administrator and end-user roles. You may want multiple user accounts in order
to test the user-experiences associated with different data access and security controls.
• Enable the Developer Menu options for the session.
Procedure
Step 1
In Cisco UCS Director, navigate to the page for which you want to see the API code.
For example, choose one of the following:
• Policies > Orchestration
• Physical > Storage > Storage_Account > Filers
Step 2
Step 3
Click Report Metadata.
In the Information dialog box, review the sample code.
Request Format
API clients can use HTTP or HTTPS to interact with Cisco UCS Director. To pass the REST API access key,
each request must be associated with an http/https header called X-Cloupia-Request-Key with its value
set to the current REST API Access Key. For information about getting and using this key, see Generating
an API Access Key, on page 11.
URL Format
http://SERVER/app/api/rest?formatType=json&opName=operationName&opData=operationData
where SERVER is the IP address of the hostname of the Cisco UCS Director VM,
and where opName is the API operation name associated with the request. For example:
userAPIGetMyLoginProfile, or userAPIGetVMActionStatus,
and where opData includes the JSON parameters (the arguments associated with the operation).
Cisco UCS Director REST Developer Guide, Release 5.1
14
Getting Started
Request Format
Request URL Parameters
• formatType—The only supported format that is discussed here is JavaScript Object Notation (JSON).
Set this parameter value to json.
• opName—The operation name associated with the request. A list of operations is provided in About
the REST API Operations, on page 20.
• opData—Parameters (or arguments) associated with the operation. Cisco UCS Director uses JSON
encoding of the parameters. If no arguments are required for the operation, use {} as an empty set. Before
you send JSON data in a request, you must apply escape characters as appropriate. For details about
encoding the URL, see the RFC at http://www.ietf.org/rfc/rfc1738.txt.
For more information about JSON syntax and data types, see http://en.wikipedia.org/wiki/JSON#Data_
types.2C_syntax_and_example.
For information about non-JSON formatted API requests, see Using the REST API Browser, on page 13.
About Operations Data Parameters/Arguments
Because the method and a generic designation of the API resource are communicated through the opName,
the operation parameters must present any arguments that are needed to designate a specific instance of the
resource to be operated upon.
For a list of available API operations and parameter specifications, see About the REST API Operations, on
page 20.
Operations Data Parameter Syntax
The following table shows examples of operations data parameter syntax in JSON format.
If the operation needs the following parameters
(opData)
How to represent in JSON
No parameters
{}
One parameter; integer (for example, 10)
{param0:10}
One parameter: string (for example, cloud)
{param0:"cloud"}
Two parameters: a string and an Integer
{param0:"cloud",param1:10}
Two parameters: a string with null value and an
Integer
{param0:null,param1:10}
Three parameters
{param0:"cloud",param1:"cloupia",param2:100}
Operation Data Parameters
…&opData={param0:"datacenter",param1:"DataCenter1",param2:"STORAGE-ACCOUNTS-T51"
…&opData= {param0:"Create NFS Datastore",param1:{"list":[{"name":"Volume
Size","value":100},{"name":"Select Group","value":"14"},{"name":"Select
vDC","value":18}]},param2:212}
Cisco UCS Director REST Developer Guide, Release 5.1
15
Getting Started
Request Format
• param0—Name of the workflow being invoked through the REST API.
• param1—Input being passed to the workflow. If there are more than one input, separate the inputs by
comma and within the curly braces with proper quotations. If there are no inputs, use null for the API
invocation.
• param2—If this workflow is being invoked as a child workflow of another service request, use the
service request (SR) ID. If this workflow is not invoked as a child workflow, use -1. When -1 is used,
a new service request will be invoked.
Tip
Cisco UCS Director provides many complete API requests, formatted as URLs and ready for you to cut
and paste into a browser. See Enabling the Developer Menu Options, on page 12.
Context Parameters
In the example above, Param0 is used to specify the UCS Director context. The context data value refers to
one of the major domains managed by Cisco UCS Director, for example, "global-services", "vm", "vdc",
"datacenter", "storage_accounts", "Compute-chassis", "network-device". A list of the standard UCS
Director contexts appears in API Request Context Parameters, on page 75.
Report Parameters
The report parameter value is always the reportId. Typical reportIds include "STORAGE-ACCOUNTS-T51",
"CPU-S0", "VOLUMES--X1", "NETWORK-USAGE-H0", "PORT-SUMMARY-V50", "PRIVATE-CLOUD-FREE-STORAGE-S1".
The reportId is typically the last parameter listed in an API request for a report. So, if the context is specified
by two parameters, the report parameter is often the third, param2. For an extensive list of report names, and
reportIds, categorized by context, see List of Available Cisco UCS Director Reports, on page 101.
Sample API Request 1
The operation that requests a Login profile refers to the logged in user, so there is no need for a parameter.
Most other operations need multiple arguments.
http://10.10.1.153/app/api/rest?formatType=json&opName=userAPIGetMyLoginProfile&opData={}
Response to Sample API Request 1
{
"serviceResult":{"userId":"jsmith","firstName":"John","lastName":"Smith","email":"[email protected]",
"groupName":"Eng Group","role":"Regular"}, "serviceError":null,
"serviceName":"InfraMgr", "opName":"userAPIGetMyLoginProfile" }
Sample API Request 2
In this request for a report about chassis for a data center, the operation requires three parameters, which is
typical for a report request.
http://172.99.999.142/app/api/rest?opName=userAPIGetTabularReport&opData={param0:"datacenter",
param1:"datacenter",param2:"UCS-CHASSIS-T50"}
Response to Sample API Request 2
{ "serviceResult":
{"rows":[{"ID":"PHY-ACC;sys/chassis-2",
Cisco UCS Director REST Developer Guide, Release 5.1
16
Getting Started
Response Format
"Account_Name":"PHY-ACC","DN":"sys/chassis-2",
"Serial_Number":"1558","Model":"N20-C6508","Power_State":"ok",
"Operation_State":"accessibility-problem",
"Configuration_State":"ok","License_State":"license-ok","Servers":5,
"IO_Modules":2,"PSUs":4,"Fan_Modules":8,
"Vendor":"Cisco Systems Inc"},{"ID":"UCSCirrus;sys/chassis-1",
"Account_Name":"UCSCirrus","DN":"sys/chassis-1",
"Serial_Number":"FOX1352GDX4","Model":"N20-C6508",
"Power_State":"redundancy-failed","Operation_State":"power-problem",
"Configuration_State":"ok","License_State":"license-ok","Servers":7,
"IO_Modules":2,"PSUs":4,"Fan_Modules":8,
"Vendor":"Cisco Systems Inc"},{"ID":"UCSM237;sys/chassis-1",
"Account_Name":"UCSM237","DN":"sys/chassis-1",
"Serial_Number":"1557","Model":"N20-C6508","Power_State":"ok",
"Operation_State":"operable",
"Configuration_State":"unsupported-connectivity","License_State":"license-ok",
"Servers":6,"IO_Modules":2,
"PSUs":4,"Fan_Modules":8,"Vendor":"Cisco Systems Inc"},
{"ID":"real108;sys/chassis-1","Account_Name":"real108",
"DN":"sys/chassis-1","Serial_Number":"FOX1352GDX4","Model":"N20-C6508",
"Power_State":"redundancy-failed",
"Operation_State":"power-problem","Configuration_State":"ok",
"License_State":"license-ok","Servers":7,
"IO_Modules":2,"PSUs":4,"Fan_Modules":8,"Vendor":"Cisco Systems Inc"}],
"columnMetaData":null}, "serviceError":null, "serviceName":"InfraMgr",
"opName":"userAPIGetTabularReport" }}
Tip
For advanced Cisco UCS Director API users, the code in the Report Metadata request for the data center's
UCS-CHASSIS-T50 report gave the first parameter as param0:"23". In the request used in Sample API
Request 2, the context "datacenter" was substituted for the value "23" and the request was successful. By
comparing the API documentation against the Report Metadata and Cisco UCS Director, you can sometimes
discover alpha string value substitutes for the numeral string values (representing contexts) that appear in
the Report Metadata requests.
Response Format
The following HTTP status codes are returned by Cisco UCS Director:
• 401 Unauthorized—The API key is not a valid key.
• 200 OK— Cisco UCS Director has processed the request. The actual status of the request is in the body
of the response.
The Cisco UCS Director response body is in JSON format as determined by the FormatType parameter
specified in the API request.
Cisco UCS Director REST Developer Guide, Release 5.1
17
Getting Started
Response Format
Components of an API Response
API Response
Component
Description
Component Example (Success Scenario)
serviceResult
If the request succeeds, this
result contains a specified set
of name-value pairs or a JSON
object or a report.
"serviceResult":
{"userId":"jsmith",
"firstName":"John","lastName":"Smith",
"email":"[email protected]",
groupName":"Eng Group","role":"Regular"}
serviceError
If the request succeeds, the
serviceError is set to null. If the
operation fails, the serviceError
contains the actual error
message.
"serviceError":null
serviceName
Name of the back end service.
Often set to InfraMgr, for
example.
"serviceName":"InfraMgr"
opName
Name of the operation provided
in the request.
"opName":"userAPIGetMyLoginProfile"
Example: API Response in a Success Scenario
{
"serviceResult":{"userId":"jsmith","firstName":"John","lastName":"Smith",
"email":"jsmith@example.
com","groupName":"Eng Group","role":"Regular"}, "serviceError":null,
"serviceName":"InfraMgr",
"opName":"userAPIGetMyLoginProfile"
}
Example: API Response in a Failure Scenario
{ "serviceResponse":null,
"serviceError":"SERVICE_CALL_EXCEPTION: Service InfraMgr does not support operation test",
"serviceName":"InfraMgr", "opName":"test"
}
API Response (Service Result) Data Types
The service result (payload) sent in a response to a Cisco UCS Director REST API request is specified for
the operation. The service result can be an operation-specific set of name-value pairs, or it can be formatted
as a standard data type for this API, that is, as a report or a JSON object.
To see examples of the different report types, see Reports and JSON Object Response Samples, on page 90.
For information about the most commonly used Cisco UCS Director report formats and their contents, see
About Reports, on page 89.
For a list of available reports and the contexts with which they are associated, see List of Available Cisco
UCS Director Reports, on page 101.
For samples of JSON Objects, see JSON Object Parameter Types, on page 79.
Cisco UCS Director REST Developer Guide, Release 5.1
18
CHAPTER
4
API Operations
This chapter contains the following sections:
• About the REST API Operations, page 20
• Login Operations, page 20
• User Account Operations, page 21
• Account Operations, page 24
• Report Operations, page 26
• Approval Operations, page 29
• Catalog Operations, page 29
• Chargeback Operations, page 31
• Funds Operations, page 31
• Group Operations, page 32
• Inventory (Cloud) Operations, page 32
• LOV Provider Operations, page 33
• Payment Status Operations, page 34
• Resource Accounting and Limits, page 34
• Service Container Operations, page 36
• APIC Container Operations, page 42
• Service Category Operations, page 43
• Service Request Operations, page 44
• Task Operations, page 49
• VDC Operations, page 49
• VM Operations, page 51
• Workflow Operations, page 63
Cisco UCS Director REST Developer Guide, Release 5.1
19
API Operations
About the REST API Operations
• Activity Operations, page 66
• Tag Operations, page 67
• Resource Group Operations, page 69
• Application Profile Operations, page 71
• Tenant Profile Operations, page 72
• Tenant Onboarding Operations, page 74
About the REST API Operations
The catalog of Cisco UCS Director REST API operations provided in this section can help you determine
which operations serve your needs, and how to work with each operation. You can find examples of the request
and response values for an API operation through the Report Metadata and REST API Browser.
Note
The operations performed using the POST method are used primarily for services and provisioning.
Note
The opData of the API request URL, includes the following JSON parameters (the arguments associated
with the operation):
• param0—Name of the workflow being invoked through the REST API.
• param1—Input being passed to the workflow. If there are more than one input, separate the inputs
by comma and within the curly braces with proper quotations. If there are no inputs, use null for the
API invocation.
• param2—If this workflow is being invoked as a child workflow of another service request, use the
service request (SR) ID. If this workflow is not invoked as a child workflow, use -1. When -1 is
used, a new service request will be invoked.
Login Operations
userAPIGetMyLoginProfile
Description
Returns information about the logged-in user.
Parameters
None.
Return Value Type
APILoginProfile
Cisco UCS Director REST Developer Guide, Release 5.1
20
API Operations
User Account Operations
Accessible
Administrator/end user
userAPIGetUserLoginProfile
Description
Returns user information for the given user ID.
Parameters
String userId
Return Value Type
APILoginReport
Accessible
Administrator/end user
Note
See also User Account Operations, on page 21, which include operations for adding users, onboarding,
managing passwords, and profiles.
User Account Operations
userAPIAddUser
Description
Adds a user with the provided information (for example, user ID, password, email).
Parameters
• String userId
• String password
• String firstName
• String lastName
• String email
• String role
• String groupName
Cisco UCS Director REST Developer Guide, Release 5.1
21
API Operations
User Account Operations
Return Value Type
boolean (true when successful)
Accessible
Administrator
userAPIOnBoarding
Description
Creates user, group and VDC with the details provided in the APIUserOnBoardDetails argument.
Parameters
APIUserOnBoardParams inParams
For an example of this JSON object, see JSON Object Parameter Types, on page 79.
Return Value Type
APIUserOnBoardDetails
For an example of this JSON object, see JSON Object Parameter Types, on page 79.
Accessible
Administrator/end user
userAPIGetUserLoginProfile
Description
Returns user information for the given user ID.
Parameters
String userId
Return Value Type
APILoginReport
Accessible
Administrator/end user
userAPIDeleteUser
Description
Deletes the user with the given user ID.
Parameters
String userId
Cisco UCS Director REST Developer Guide, Release 5.1
22
API Operations
User Account Operations
Return Value Type
boolean (true when successful)
Accessible
Administrator
userAPIResetMyPassword
Description
Resets the password of the user account to the new password that is provided in the request.
Parameters
String newPassword
Return Value Type
boolean (true when successful)
Accessible
Administrator/end user
userAPIResetUserPassword
Description
Resets the password of a user with the user ID and new password provided.
Parameters
• String user ID
• String newPassword
• boolean resetAPIKey
Note
If the restAPKey is set to true, Cisco UCS Director resets the REST API Key
in addition to resetting the password. If set to false, only the password will be
reset, and the REST API key remains unchanged for the given user. The user
does not have to do anything if the restAPKey is set to true. You must decide
whether to reset the REST API key when the password is reset.
Return Value Type
boolean (true when successful)
Accessible
Administrator
Cisco UCS Director REST Developer Guide, Release 5.1
23
API Operations
Account Operations
userAPIVerifyUser
Description
Authenticates the user with the given password.
Parameters
• String userId
• String passWord
Return Value Type
APILoginProfile
For an example of this JSON object, see JSON Object Parameter Types, on page 79.
Accessible
Administrator/end user
Note
See also Login Operations, on page 20.
Account Operations
userAPICreateInfraAccount
Description
Creates an infra account.
Parameters
• InfraAccountDetails infraAccountDetails
Return Value Type
boolean (true when successful)
Accessible
Administrator/End user
userAPIUpdateInfraAccount
Description
Updates an infra account.
Cisco UCS Director REST Developer Guide, Release 5.1
24
API Operations
Account Operations
Parameters
• InfraAccountDetails infraAccountDetails
Return Value Type
boolean (true when successful)
Accessible
Administrator/End user
userAPIGetAllAccounts
Description
Returns the name of all accounts.
Parameters
None
Return Value Type
List as String type
Accessible
Administrator/End user
userAPIGetAllPhysicalInfraAccounts
Description
Returns all physical infra account types.
Parameters
None
Return Value Type
List PhysicalInfraAccount
Accessible
Administrator/End user
userAPIGetAccountTypeEntryByName
Description
Returns the account type entry for the given account name.
Cisco UCS Director REST Developer Guide, Release 5.1
25
API Operations
Report Operations
Parameters
String Account name
Return Value Type
List AccountTypeEntry
Accessible
Administrator/End user
userAPIGetAccountTypeByName
Description
Displays the account type based on the account name.
Parameters
String Account name
Return Value Type
List as String
Accessible
Administrator/End user
userAPIDeleteInfraAccount
Description
Deletes an infra Account.
Parameters
String Account name
Return Value Type
Boolean (true when successful)
Accessible
Administrator/End user
Report Operations
userAPIGetAvailableReports
Description
Returns the available reports for a given context.
Cisco UCS Director REST Developer Guide, Release 5.1
26
API Operations
Report Operations
Parameters
• String contextName
• String contextValue
Return Value Type
List
Accessible
Administrator/end user
userAPIGetTabularReports
Description
Returns a tabular report for a given context and report ID.
Parameters
• String contextName
• String contextValue
• String reportId
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIGetHistoricalReport
Description
Returns a tabular report for a given context, report ID, and duration.
Parameters
• String contextName
• String contextValue
• String reportId
• String durationName
Cisco UCS Director REST Developer Guide, Release 5.1
27
API Operations
Report Operations
Return Value Type
APIHistoricalReport
Accessible
Administrator/end user
userAPIGetInstantDataReport
Description
Returns a snapshot report for a given context and report ID.
Parameters
• String contextName
• String contextValue
• String reportId
Return Value Type
APISnapshotReport
Accessible
Administrator/end user
userAPIGetTabularReportWithMetaData
Description
Provide a report that includes metadata.
Parameters
• String contextName
• String contextValue
• String reportId
Return Value Type
APITabularReport
Accessible
Administrator/end user
Cisco UCS Director REST Developer Guide, Release 5.1
28
API Operations
Approval Operations
Approval Operations
userAPIGetMyApprovalList
Description
Returns the approvals list for the logged-in user.
Parameters
None.
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIUpdateMyApproval
Description
Updates the approval status of the current user, using the provided data.
Parameters
• int requestId
• int entryId
• boolean isApproved
• String comments
Return Value Type
boolean (true when successful)
Accessible
Administrator/end user
Catalog Operations
userAPICreateCatalogItem
Description
Creates a catalog item with characteristics defined by the provided data.
Cisco UCS Director REST Developer Guide, Release 5.1
29
API Operations
Catalog Operations
Parameters
APICatalogItem item
For an example of this JSON object, see JSON Object Parameter Types, on page 79.
Return Value Type
boolean (true when successful)
Accessible
Administrator
userAPIGetAllCatalogs
Description
Returns all catalog reports.
Parameters
None.
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIGetCatalogsPerGroup
Description
Returns the catalogs that are assigned to a given group.
Parameters
String groupName
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIGetAllCatalogs
Description
Returns all catalog reports.
Cisco UCS Director REST Developer Guide, Release 5.1
30
API Operations
Chargeback Operations
Parameters
None.
Return Value Type
APITabularReport
Accessible
Administrator/end user
Chargeback Operations
userAPIChargebackDetails
Description
Returns the chargeback details for the logged-in user group.
Parameters
None.
Return Value Type
APITabularReport
Accessible
Administrator/end user
Funds Operations
userAPICheckFunds
Description
Returns the available customer's funds.
Parameters
String userID
Return Value Type
Double (available funds)
Accessible
Administrator/end user
Cisco UCS Director REST Developer Guide, Release 5.1
31
API Operations
Group Operations
Note
See also Payment Status Operations, on page 34.
Group Operations
userAPIAddGroup
Description
Adds a group with the specified data (group name, description, names, email).
Parameters
• String groupName
• String description
• String firstName
• String lastName
• String contactEmail
Return Value Type
boolean (true when successful)
Accessible
Administrator
Note
Many operations are associated with a group value, such as userAPIGetCatalogsPerGroup. For more
information, see the main operation category.
Inventory (Cloud) Operations
userAPIRequestInventoryCollection
Description
Triggers the inventory collection for the specified cloud.
Parameters
String cloudName
Cisco UCS Director REST Developer Guide, Release 5.1
32
API Operations
LOV Provider Operations
Return Value Type
boolean (true when successful)
Accessible
Administrator/end user
LOV Provider Operations
userAPIgetStaticListByName
Description
Returns the elements of a list.
Parameters
Name of the List
Return Value Type
FormLOVPair[]
Accessible
Administrator/End user
userAPIgetBMAOSList
Description
Returns the list of Cisco UCS Director Baremetal Agent OS names.
Parameters
None.
Return Value Type
FormLOVPair[]
Accessible
Administrator/End user
userAPIGetLOVProvidersList
Description
Returns the names of the available lists within the system.
Cisco UCS Director REST Developer Guide, Release 5.1
33
API Operations
Payment Status Operations
Parameters
None.
Return Value Type
List<String>
Accessible
Administrator/End user
Payment Status Operations
userAPIUpdatePaymentStatus
Description
Updates the payment status with amount and timestamp.
Parameters
APIMakePaymentParams inParams
For an example of this JSON object, see JSON Object Parameter Types, on page 79.
Return Value Type
boolean (true when successful)
Accessible
Administrator/end user
Note
See also Funds Operations, on page 31.
Resource Accounting and Limits
userAPIGetResourceAccounting
Description
Returns the resource usage for the logged-in user group.
Parameters
None.
Cisco UCS Director REST Developer Guide, Release 5.1
34
API Operations
Resource Accounting and Limits
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIGetResourceAccountingDetails
Description
Returns the resource usage details for the logged-in user group.
Parameters
None.
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIGetResourceLimits
Description
Returns the resource limits for a requested group.
Parameters
String groupName
Return Value Type
APITabularReport
Accessible
Administrator
userAPIGetResourceLimitsForMyGroup
Description
Returns the resource limits for the logged-in group.
Parameters
None.
Cisco UCS Director REST Developer Guide, Release 5.1
35
API Operations
Service Container Operations
Return Value Type
APITabularReport
Accessible
Administrator/end user
Service Container Operations
Service container APIs support both the fenced container and the APIC container. In the REST API browser,
the APIs for APIC and fenced containers are differentiated as UserAPIAPICContainer and
UserAPIFencedContainer in the resource column. In the API URL, the namespace of the APIC container and
the fenced container are mentioned as apic and fenced.
The sample API URL of an APIC container is as follows:
/app/api/rest?formatType=json&opName=apic:userAPIPowerOnServiceContainer&opData={param0:1000}
The sample API URL of a fenced container is as follows:
/app/api/rest?formatType=json&opName=fenced:userAPIPowerOnServiceContainer&opData={param0:1000}
userAPICreateServiceContainerTemplate
Description
Creates a service container template.
Parameters
For a list of parameters, see JSON Example: APIServiceContainerTemplate , on page 82.
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIUpdateServiceContainerTemplate
Description
Updates the service container template.
Parameters
container Id—ID of the service container to be updated.
Return Value Type
Boolean
Accessible
Administrator/End user
Cisco UCS Director REST Developer Guide, Release 5.1
36
API Operations
Service Container Operations
userAPIGetApplicationContainerTemplateDetails
Description
Returns the details of the Application Container template that is used for creating a service container.
Parameters
applicationContainerTemplateName—Name of the template used for the application container.
Return Value Type
APITabularReport
Accessible
Administrator/End user
userAPICreateServiceContainer
Description
Creates a service container and returns the service request (SR ID) as an integer value.
Note
To create an APIC container, use the userAPICreateAPICContainer API. For
more information, see APIC Container Operations, on page 42.
Parameters
• groupName—Name of the group to which the user belongs and for which the container provisioning
permission is allowed.
• catalogName—Name of the catalog that includes the application container template.
• serviceContainerName—Name of the service container to be created.
• Comments—Any comments for the provisioning operation.
Return Value Type
Integer
Accessible
Administrator/End user
userAPICreateServiceContainerWithoutCatalog
Description
Creates a service container without a catalog and returns the service request (SR ID) as an integer value.
Cisco UCS Director REST Developer Guide, Release 5.1
37
API Operations
Service Container Operations
Parameters
• containerId—ID of the service container.
• groupId—ID of the group to which the user belongs and for which the container provisioning
permission is allowed.
• applicationContainerTemplateName —Name of the container template that you need to use for
creating a service container.
Return Value Type
Integer (Service request ID)
Accessible
Administrator/End user
userAPIGetVNCURL
Description
Returns the virtual network computing (VNC) URL which is used for verifying if VNC is up and
running.
Parameters
vmId—ID of the virtual machine.
Return Value Type
String
Accessible
Administrator/End user
userAPIGetAllServiceContainers
Description
Returns all service containers.
Parameters
None
Return Value Type
List of Service container
Accessible
Administrator/End user
Cisco UCS Director REST Developer Guide, Release 5.1
38
API Operations
Service Container Operations
userAPIGetServiceContainerData
Description
Returns the service container data.
Parameters
Service container id—ID of the service container.
Return Value Type
ContainerDataObjects
Accessible
Administrator/End user
userAPIGetServiceContainerDetails
Description
Returns the service container details such as network summary, port mapping, virtual machine
information, event history, and so on.
Parameters
container id—ID of the service container for which you need to view the details.
Return Value Type
APITabularReport
Accessible
Administrator/End user
userAPIGetServiceContainerVirtualInfraPolicy
Description
Returns the infra policy details.
Parameters
infrapolicy name —Name of the infra policy for which you need to view the details.
Return Value Type
list
Accessible
Administrator/End user
Cisco UCS Director REST Developer Guide, Release 5.1
39
API Operations
Service Container Operations
userAPIAddVMsServiceContainer
Description
Adds the virtual machines (VMs) to a service container.
Parameters
• containerId—ID of the service container in which virtual machines can be added.
• ContainerVirtualMachine[ ]—An array of container VMs that you want to provision in the service
container. You need to pass the VM parameters. Quantity and AppName are the mandatory VM
parameters, where AppName is the VM name.
Return Value Type
Integer (Service request ID)
Accessible
Administrator/End user
userAPIPowerOnServiceContainer
Description
Turns on all the virtual machines (VMs) in a service container, one by one.
Cisco UCS Director displays the service container in different colors based on VMs condition as follows:
• None—All VMs are powered off.
• Blue—In the process of turning on the VMs.
Note
If the container remains in blue for a long time, click the service request ID to check
the VM provisioning status.
• Orange—All inactive infrastructure VMs are powered on and active application VMs are up.
• Yellow—All active application VMs and inactive application VMs are powered on.
• Green—All infrastructure VMs are powered on and all application VMs are up.
• Red—All infrastructure VMs (such as database) are powered off and active application VMs
(such as gateway (GW) VM) are down.
• Gray—All infrastructure VMs are powered off and all application VMs are down.
Parameters
containerId—ID of the service container to be powered on.
Cisco UCS Director REST Developer Guide, Release 5.1
40
API Operations
Service Container Operations
Return Value Type
boolean
Accessible
Administrator/End user
userAPIPowerOffServiceContainer
Description
Turns off all the VMs in the service container. When all the VMs are turned off and GW VM is down,
the container is displayed in red.
Parameters
containerId—ID of the service container to be powered off.
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIDeleteServiceContainer
Description
Deletes a service container.
Parameters
containerId—ID of the service container to be deleted.
Return Value Type
Integer (Service request ID)
Accessible
Administrator/End user
userAPICloneServiceContainer
Description
Creates a new service container based on the source service container.
Parameters
• sourceContainerName—Name of the service container to be cloned.
• destinationContainerName—Name of the new service container.
Cisco UCS Director REST Developer Guide, Release 5.1
41
API Operations
APIC Container Operations
Return Value Type
Integer (Service request ID)
Accessible
Administrator/End user
APIC Container Operations
userAPICreateAPICContainer
Description
Creates an APIC container and returns the service request (SR) ID as an integer value.
Parameters
• groupName—Name of the group to which the user belongs and for which the container provisioning
permission is allowed.
• catalogName—Name of the APIC catalog.
• serviceContainerName—Name of the APIC container to be created.
• Comments—Any comments for the provisioning operation.
• apicTenantName—Identity of tenant.
Note
The apicTenantName is the combination of APIC account name and tenant name. The
format of the apicTenantName is apicAccountName@TenantName.
Sample
/app/api/rest?formatType=json&opName=apic:userAPICreateAPICContainer&opData=
{param0:"Ten220",param1:"APICCatalog",param2:"SDKCont",param3:"Comments",param4:"APIC@Ten220"}
Return Value Type
Integer
Accessible
Administrator/End user
Cisco UCS Director REST Developer Guide, Release 5.1
42
API Operations
Service Category Operations
Service Category Operations
userAPIGetServiceCategory
Description
Returns all service categories.
Parameters
None
Return Value Type
List APIServiceCategoryPojo
Accessible
Administrator/End user
userAPICreateServiceCategory
Description
Creates a service category.
Parameters
• apiPojo APIServiceCategoryPojo
Return Value Type
Boolean
Accessible
Administrator/End user
userAPICloneServiceCategory
Description
Creates a new service category based on the source service category.
Parameters
• apiPojo APIServiceCategoryPojo
Return Value Type
Boolean
Cisco UCS Director REST Developer Guide, Release 5.1
43
API Operations
Service Request Operations
Accessible
Administrator/End user
userAPIModifyServiceCategory
Description
Updates the service category.
Parameters
apiPojo APIServiceCategoryPojo
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIDeleteServiceCategory
Description
Deletes a service category.
Parameters
serviceOfferingName—Name of the service offering to be deleted.
Return Value Type
Boolean
Accessible
Administrator/End user
Service Request Operations
userAPISubmitServiceRequest
Description
Submits a service request for provisioning virtual machines (VMs).
Cisco UCS Director REST Developer Guide, Release 5.1
44
API Operations
Service Request Operations
Parameters
• String catalogName—Name of the catalog.
• String vdcName—Name of the VDC.
• int durationHours— Duration of VM provisioning in hours. After the set duration, VM will be
automatically deprovisioned. Use -1 to set the duration as indefinite.
• long beginTime—Schedule the time at which you want to start provisioning a VM. For example,
January 1, 2014, 00:00:00 GMT. Use 0 or -1 to start the VM provisioning immediately.
• int qty—Quantity of VM to be provisioned.
Note
In Cisco UCS Director Release 5.x, the supported quantity is 1.
• String comments—Comment that is set as the provisioned VM label.
Return Value Type
Integer (Service Request Id)
Accessible
Administrator/end user
userAPIGetServiceRequests
Description
Returns all service requests for the user group.
Parameters
None.
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIGetServiceRequestDetails
Description
Returns service request details.
Parameters
int requestId
Cisco UCS Director REST Developer Guide, Release 5.1
45
API Operations
Service Request Operations
Return Value Type
APIServiceRequestDetails
Accessible
Administrator/end user
userAPICancelServiceRequest
Description
Cancels a service request in progress.
Parameters
int requestID
Return Value Type
boolean
Accessible
Administrator/end user
userAPIGetServiceRequestLogEntries
Description
Returns the log entries of a service request for the requested severity:
• 0—Debug
• 1—Info
• 2—Warning
• 3—Error
Parameters
• int srId
• int severity (0 to 3)
Return Value Type
ServiceRequestLogEntry[ ]
Accessible
Administrator
Cisco UCS Director REST Developer Guide, Release 5.1
46
API Operations
Service Request Operations
userAPIGetServiceRequestLogEntriesAtLevels
Description
Returns the log entries of a service request for the requested severity:
• 0—Debug
• 1—Info
• 2—Warning
• 3—Error
Parameters
• int srId
• String severityList (Comma separated severity values)
Return Value Type
ServiceRequestLogEntry[]
Accessible
Administrator
userAPIGetServiceRequestWorkFlow
Description
Returns service request workflow details.
Parameters
int requestId
Return Value Type
APIWorkFlowStatus
The values set for the different execution status of a workflow are:
• EXECUTION_STATUS_NOT_STARTED = 0
• EXECUTION_STATUS_IN_PROGRESS = 1
• EXECUTION_STATUS_FAILED = 2
• EXECUTION_STATUS_COMPLETED = 3
• EXECUTION_STATUS_COMPLETED_WITH_WARNING = 4
• EXECUTION_STATUS_CANCELLED = 5
For an example of this report, see Reports and JSON Object Response Samples, on page 90.
Cisco UCS Director REST Developer Guide, Release 5.1
47
API Operations
Service Request Operations
Accessible
Administrator/end user
userAPISubmitVAppServiceRequest
Description
Submits a service request with the virtual application catalog type and arguments.
Parameters
• String catalogName
• APINameValueList list
Return Value Type
int (service request ID)
Accessible
Administrator/end user
userAPIGetVMsForServiceRequest
Description
Returns VMs that are currently associated with the specified service request.
Parameters
int requestId
Return Value Type
APIVMList
For an example of this report, see Reports and JSON Object Response Samples, on page 90.
Accessible
Administrator/end user
userAPISubmitWorkflowServiceRequest
Description
Submits a service request with a workflow. Returns the ID of the service request.
Cisco UCS Director REST Developer Guide, Release 5.1
48
API Operations
Task Operations
Parameters
• String workflowName
• APINameValueList list
• int parentSRID
Return Value Type
int (service request ID)
Accessible
Administrator/end user
Note
For more information on operations related to service requests, such as
userAPIGetServiceRequestWorkFlow, see Workflow Operations, on page 63 .
Task Operations
You can find information about the different API operations for tasks in the REST API Browser. For more
information, see Using the REST API Browser, on page 13.
Note
See also Workflow Operations, on page 63.
VDC Operations
userAPIGetAllVDCs
Description
Returns all vDCs (virtual data centers) for the logged-in user group. No parameters are required.
Parameters
None.
Return Value Type
APITabularReport
For more information about this report, see Tabular Reports, on page 99.
Cisco UCS Director REST Developer Guide, Release 5.1
49
API Operations
VDC Operations
Accessible
Administrator/end user
userAPICreateVDC
Description
Creates a vDC (virtual data center) defined by the provided data.
Parameters
APIVDCDetails
For an example of this JSON object, see JSON Object Parameter Types, on page 79.
Return Value Type
boolean (true when successful)
Accessible
Administrator
Note
See also userAPIOnboarding in User Account Operations, on page 21 and userAPISubmitServiceRequest
in Service Request Operations, on page 44.
userAPIExportVDC
Description
Exports a vDC from Cisco UCS Director.
Parameters
vdcName—Name of the vDC that you want to export.
Return Value Type
String
Accessible
Administrator/end User
userAPIImportVDC
Description
Imports a vDC into Cisco UCS Director.
Cisco UCS Director REST Developer Guide, Release 5.1
50
API Operations
VM Operations
Parameters
vdcName—Name of the vDC that you want to import.
Return Value Type
VDC
Accessible
Administrator/end User
VM Operations
UserAPIProvisionRequest
Description
Provisions a virtual machine (VM).
Parameters
• String catalogName
• String vdcName
• String userID
• int durationHours
• int beginTime
• int quantity
• int memoryMB
• int diskGB
• int cores
• int estimatedCost
• String comments
• String additionalInfo
• int chargeFrequency
Return Value Type
int (service request ID)
Accessible
Administrator
Cisco UCS Director REST Developer Guide, Release 5.1
51
API Operations
VM Operations
UserAPIProvisionRequestWithPortGroup
Description
Provisions a VM and allows a user to select the port group name while provisioning a VM.
Note
From Cisco UCS Director Release 5.x and later releases, deprecated the
UserAPIProvisionRequestWithPortGroup API. To provision a VM, use the
userAPIVMWareProvisionRequest API. For more details on VM provisioning,
see userAPIVMWareProvisionRequest, on page 60.
Parameters
• String catalogName
• String vdcName
• String userID
• int durationHours
• int beginTime
• int quantity
• int memoryMB
• int diskGB
• int cores
• int estimatedCost
• String comments
• String additionalInfo
• int chargeFrequency
• String nicAliasName
• String nicPortGroupName
Return Value Type
int (service request ID)
Accessible
Administrator
userAPIGetAllVMs
Description
Returns all VMs for the logged-in user. No parameters are required.
Cisco UCS Director REST Developer Guide, Release 5.1
52
API Operations
VM Operations
Parameters
• int vmId
• int hostid
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIGetVMSummary
Description
Returns a summary of a specified VM.
Parameters
int vmId
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIGetVMsForServiceRequest
Description
Returns VMs that are currently associated with the specified service request.
Parameters
int requestId
Return Value Type
APIVMList
For an example report, see Reports and JSON Object Response Samples, on page 90.
Accessible
Administrator/end user
Cisco UCS Director REST Developer Guide, Release 5.1
53
API Operations
VM Operations
userAPIGetVMActionRequests
Description
Returns VM Action requests for a given context.
Parameters
• String contextName
• String contextValue
Return Value Type
APITabularReport
Accessible
Administrator/end user
userAPIGetAvailableVMActions
Description
Returns the available VM Actions for a given VM ID.
Parameters
int vmId
Return Value Type
List
Accessible
Administrator/end user
userAPIExecuteVMAction (for Generic VMs)
Description
Executes a specific Power Management Option action on a given generic VM.
Cisco UCS Director REST Developer Guide, Release 5.1
54
API Operations
VM Operations
Parameters
• int vmId
• String actionName—Values for actionName include the following:
◦discardSaveState
◦pause
◦powerOff
◦powerOn
◦reboot
◦rebuildServer
◦repairVM
◦reset
◦resume
◦saveState
◦shutdownGuest
◦standby
◦suspend
• String comments
Return Value Type
String (VM action request ID). Used to get the status of the request.
Accessible
Administrator/end user
userAPIExecuteVMAction (for VMware vSphere VMs)
Description
Executes a specific Power Management Option action on a given VMware vSphere VM.
Cisco UCS Director REST Developer Guide, Release 5.1
55
API Operations
VM Operations
Parameters
• int vmId
• String actionName—Values for actionName include the following:
• addVMvNICs
• diskResize
• reset
• assignVMToVDC
• enableVMRCConsole
• resynchVM
• configureVMVNC
• migrateVM
• saveVMAsTemplate
• convertVMToTemplate
• moveVMToVdc
• shutdownGuest
• createVMDisks
• powerOff
• standby
• customVMStackView
• powerOn
• suspend
• deleteVMDisks
• privateCloudVMClone
• testVMVNCConnection
• deleteVMvNICs
• reboot
• vmMountISOImageAsCDROM
• destroyVM
• reconfigure
• vmwareVMInventory
• String comments
Return Value Type
String (VM action request ID). Used to get the status of the request.
Accessible
Administrator/end user
userAPIExecuteVMAction (for Microsoft Hyper-V VMs)
Description
Executes a specific Power Management Option action on a given Microsoft Hyper-V VM.
Cisco UCS Director REST Developer Guide, Release 5.1
56
API Operations
VM Operations
Parameters
• int vmId
• String actionName—Values for actionName include the following:
• addHyperVvNics
• hyperVReconfigure
• powerOff
• customVMStackView
• hypervRemoveVMDisk
• powerOn
• deleteHyperVvNic
• hyperVRepair
• reset
• destroyVM
• hypervSnapshotCreate
• resume
• discardSaveState
• hypervSnapshotDelete
• saveState
• hypervAddVMDisk
• hypervSnapshotDeleteAll
• shutdownGuest
• hypervDiskResize
• hypervSnapshotRevert
• vmwareVMInventory
• hypervMarkGoldenSnapshot
• pause
• String comments
Return Value Type
Integer (Service request ID)
Accessible
Administrator/end user
userAPIReconfigureVM
Description
Resizes the specified VM.
Parameters
• int vmId
• int memorySizeInMb
• int numVCPUS—The number of virtual CPUs for a virtual machine
• String comments
Return Value Type
String
Accessible
Administrator/end user
Cisco UCS Director REST Developer Guide, Release 5.1
57
API Operations
VM Operations
userAPIGetVMActionStatus
Description
Returns the VM Action Status for a given VM Action Request.
Parameters
String requestactionId
Return Value Type
APIVMActionStatus
Accessible
Administrator/end user
userAPISetVMProperties
Description
Assigns a user label to a VM.
Parameters
• int vmId
• String userLabel
Return Value Type
boolean (true when successful)
Accessible
Administrator/end user
userAPIGetVMAccessCredentials
Description
Returns VM access credentials.
Parameters
int vmId
Return Value Type
APIVMAccess
Accessible
Administrator/end user
Cisco UCS Director REST Developer Guide, Release 5.1
58
API Operations
VM Operations
userAPIGetVMSnapshotDetails
Description
Returns VM snapshot details.
Parameters
int vmId
Return Value Type
APITabularReport
Accessible
Administrator/end user/end user
userAPICreateVMSnapshot
Description
Creates a snapshot based on the parameters provided. The snapshot is a backup of existing data on VM.
An end user can later restore to a snapshot in case of a VM failure.
Parameters
• int vmId
• String name
• String descr
• boolean isMemory—Set value to true to make a snapshot of memory
• boolean isQuiesce—Set value to true to quiesce file system
Return Value Type
String (VM action request ID)
Accessible
Administrator/end user
userAPICheckContextActionStatus
Description
Returns the status message details of the VM action.
Parameters
statusId—The string ID value used to check the status from the database that is updated from the thread
performing the VM action.
Cisco UCS Director REST Developer Guide, Release 5.1
59
API Operations
VM Operations
Return Value Type
String
API namespace
genericvm
Accessible
Administrator/End user
userAPIDeleteCatalogItem
Description
Deletes the catalog that is created for provisioning a VM.
Parameters
catalogItemName—Name of the catalog item that needs to be deleted.
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIVMWareProvisionRequest
Description
Provisions a VMware VM using a template and returns the service request (SR) ID as an integer value.
Parameters
• String catalogName—Name of the catalog.
• String vdcName—Name of the VDC.
• String vmName—Name of the VM to be provisioned.
• String comment— Comment that is set as the VM label.
• double vCpus—Number of CPUs.
• double memory—Size of memory in GB.
• String datastores—Number of VM Disks.
• String opNicPortGroup — VM networks.
Return Value Type
Integer (Service request ID)
Cisco UCS Director REST Developer Guide, Release 5.1
60
API Operations
VM Operations
Accessible
Administrator/End user
userAPIVMWareCloneVMProvisionRequest
Description
Clones a VMware VM and returns the service request (SR) ID as an integer value.
Parameters
• String vmID—ID of VM that needs to be cloned.
• String vdcName—Name of the VDC.
• String vmName—Name of VM that needs to be provisioned.
• boolean useLinkedClone—Set to true to use the linked clone feature.
• String snapshotKey—Snapshotkey that needs to be used without creating a new snapshot..
• String snapshotName – Name of a new snapshot. This parameter is used to create a new snapshot.
• String comment— Comment that is set as the VM label.
• double vCpus—Number of CPUs.
• double memory—Size of memory in GB.
• String chargeFrequency —Frequency of charge. This parameter accepts the following values:
Hourly or Monthly.
• String datastores—Number of VM Disks.
• String opNicPortGroup — VM networks.
• String credentials — This parameter accepts one of the following values:“Do not share” or “Share
after password reset” or “Share template credentials”.
• String userid
• String password
• boolean provisionDiskinSingleDatastore – Set to true to provision all disks in a single datastore.
• String vmappChargeFrequency – Frequency of vmapp charge. This parameter accepts the following
values: Hourly or Monthly.
• double activeVMCost
• double inactiveVMCost
Return Value Type
Integer (Service request ID)
Accessible
Administrator/End user
Cisco UCS Director REST Developer Guide, Release 5.1
61
API Operations
VM Operations
userAPIVMWareMoveVMProvisionRequest
Description
Moves a VM to VDC and returns the service request (SR) ID as an integer value.
Parameters
• String vmID—ID of VM that needs to be moved.
• String vdcName—Name of the VDC.
• String credentials — This parameter accepts one of the following values:“Do not share” or “Share
after password reset” or “Share template credentials”.
• String userid
• String password
• boolean provisionDiskinSingleDatastore – Set to true to provision all disks in a single datastore.
• String vmappChargeFrequency – Frequency of vmapp charge. This parameter accepts the following
values: Hourly or Monthly.
• double activeVMCost
• double inactiveVMCost
• String comment— Comment that is set as the VM label.
• double vCpus—Number of CPUs.
• double memory—Size of memory in GB.
• String datastores—Number of VM Disks.
• String opNicPortGroup — VM networks.
Return Value Type
Integer (Service request ID)
Accessible
Administrator/End user
Note
If you want to set optional inputs, pass an empty string. Do not pass sample as the dummy string.
Cisco UCS Director REST Developer Guide, Release 5.1
62
API Operations
Workflow Operations
Workflow Operations
userAPIGetWorkflows
Description
Returns the workflows in a folder.
Parameters
String folderName
Return Value Type
CustomActionDefinition[ ]
Accessible
Administrator
userAPIGetWorkflowStatus
Description
Returns the execution status code of a workflow.
Parameters
int srId
Return Value Type
int
The values set for the different execution status of a workflow are:
• EXECUTION_STATUS_NOT_STARTED = 0
• EXECUTION_STATUS_IN_PROGRESS = 1
• EXECUTION_STATUS_FAILED = 2
• EXECUTION_STATUS_COMPLETED = 3
• EXECUTION_STATUS_COMPLETED_WITH_WARNING = 4
• EXECUTION_STATUS_CANCELLED = 5
• EXECUTION_STATUS_PAUSED = 6
• EXECUTION_STATUS_SKIPPED = 7
Accessible
Administrator
Cisco UCS Director REST Developer Guide, Release 5.1
63
API Operations
Workflow Operations
userAPIGetWorkflowInputs
Description
Returns the inputs of a workflow
Parameters
String workflowName
Return Value Type
APINameValueList
Accessible
Administrator
userAPIValidateWorkFlow
Description
Validates the workflow and returns the result.
Parameters
String workflowName
Return Value Type
APIWFValidationResult
Accessible
Administrator
userAPISubmitWorkflowServiceRequest
Description
Submits a service request with a workflow. Returns the ID of the service request.
Parameters
• String workflowName
• APINameValueList list
• int parentSRID
Return Value Type
int (service request ID)
Accessible
Administrator/end user
Cisco UCS Director REST Developer Guide, Release 5.1
64
API Operations
Workflow Operations
userAPIRollbackWorkflow
Description
Rolls back the specified service request ID.
Parameters
int srId
Return Value Type
int (Service Request Id)
Accessible
Administrator
userAPIExportWorkflows
Description
Exports the specified workflows.
Parameters
String workflowNames
Return Value Type
APICustomWorkflowDefinitionList
Accessible
Administrator/end user
userAPIImportWorkflows
Description
Imports the workflow into the system.
Parameters
APIWFExport export
Return Value Type
boolean (true when successful)
Accessible
Administrator/end user
Cisco UCS Director REST Developer Guide, Release 5.1
65
API Operations
Activity Operations
Activity Operations
userAPIGetActivity
Description
Return all activities.
Parameters
None
Return Value Type
List APIActivityFormPojo
Accessible
Administrator/End user
userAPICreateActivity
Description
Creates an activity.
Parameters
• apiPojo APIActivityFormPojo
Return Value Type
Boolean
Accessible
Administrator/End user
userAPICloneActivity
Description
Creates a new activity based on the source activity.
Parameters
• apiPojo APIActivityFormPojo
Return Value Type
Boolean
Cisco UCS Director REST Developer Guide, Release 5.1
66
API Operations
Tag Operations
Accessible
Administrator/End user
userAPIModifyActivity
Description
Updates the activity.
Parameters
apiPojo APIActivityFormPojo
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIDeleteActivity
Description
Deletes an activity.
Parameters
apiPojo APIActivityFormPojo
Return Value Type
Boolean
Accessible
Administrator/End user
Tag Operations
userAPIGetTagLibrary
Description
Returns the tags that are available in the tag library.
Parameters
None
Cisco UCS Director REST Developer Guide, Release 5.1
67
API Operations
Tag Operations
Return Value Type
List APIResourceTag
Accessible
Administrator/End user
userAPICreateTag
Description
Creates a tag.
Parameters
• apiPojo APIResourceTag
Return Value Type
Boolean
Accessible
Administrator/End user
userAPICloneTag
Description
Creates a new tag based on the source tag.
Parameters
• apiPojo APIResourceTag
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIModifyTag
Description
Updates the tag.
Parameters
apiPojo APIResourceTag
Cisco UCS Director REST Developer Guide, Release 5.1
68
API Operations
Resource Group Operations
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIDeleteTag
Description
Deletes a tag.
Parameters
String tagName—Name of the tag to be deleted.
Return Value Type
Boolean
Accessible
Administrator/End user
Resource Group Operations
userAPIgetResourceGroups
Description
Returns all resource groups.
Parameters
None
Return Value Type
List APIResourceGroupMainForm
Accessible
Administrator/End user
userAPICreateResourceGroup
Description
Creates a resource group.
Cisco UCS Director REST Developer Guide, Release 5.1
69
API Operations
Resource Group Operations
Parameters
• apiPojo APIResourceGroupMainForm
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIModifyResourceGroup
Description
Updates the resource group.
Parameters
apiPojo APIResourceGroupMainForm
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIDeleteResourceGroup
Description
Deletes a resource group.
Parameters
• String rgName—Name of the resource group to be deleted.
Return Value Type
Boolean
Accessible
Administrator/End user
Cisco UCS Director REST Developer Guide, Release 5.1
70
API Operations
Application Profile Operations
Application Profile Operations
userAPIGetApplicationProfile
Description
Returns all application profiles.
Parameters
None
Return Value Type
List APIApplicationProfileConfigTemplate
Accessible
Administrator/End user
userAPICreateApplicationProfile
Description
Creates an application profile.
Parameters
• apiPojo APIApplicationProfileConfigTemplate
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIModifyApplicationProfile
Description
Updates the application profile.
Parameters
apiPojo APIApplicationProfileConfigTemplate
Return Value Type
Boolean
Cisco UCS Director REST Developer Guide, Release 5.1
71
API Operations
Tenant Profile Operations
Accessible
Administrator/End user
userAPIDeleteApplicationProfile
Description
Deletes an application profile.
Parameters
• String appprofileName
• String soff
Return Value Type
Boolean
Accessible
Administrator/End user
Tenant Profile Operations
userAPIGetTenantProfile
Description
Returns the tenant profile.
Parameters
None
Return Value Type
List APITenantProfilePojo
Accessible
Administrator/End user
userAPICreateTenantProfile
Description
Creates a tenant profile.
Cisco UCS Director REST Developer Guide, Release 5.1
72
API Operations
Tenant Profile Operations
Parameters
• apiPojo APITenantProfilePojo
Return Value Type
Boolean
Accessible
Administrator/End user
userAPICloneTenantProfile
Description
Creates a new tenant profile based on the source tenant profile.
Parameters
• apiPojo APITenantProfilePojo
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIModifyTenantProfile
Description
Updates the tenant profile.
Parameters
apiPojo APITenantProfilePojo
Return Value Type
Boolean
Accessible
Administrator/End user
userAPIDeleteTenantProfile
Description
Deletes a tenant profile.
Cisco UCS Director REST Developer Guide, Release 5.1
73
API Operations
Tenant Onboarding Operations
Parameters
String tenantName—Name of the tenant profile to be deleted.
Return Value Type
Boolean
Accessible
Administrator/End user
Tenant Onboarding Operations
userAPIInitiateTenantOnboarding
Description
Initiates the process to onboard a tenant.
Parameters
apiPojo APITenantOnboarding
Return Value Type
String
Accessible
Administrator/End user
Cisco UCS Director REST Developer Guide, Release 5.1
74
CHAPTER
5
API Request Parameters
This chapter contains the following sections:
• API Request Context Parameters, page 75
• API Request Parameters for Reports or JSON Objects, page 77
API Request Context Parameters
Cisco UCS Director REST API operations that require parameters typically require the context as a parameter.
There are a few exceptions, notably the operations that pick the context from login information.
If you want to create an API request, you have two options for finding the correct context parameter value to
use:
• Find the correct context name string in the list of standard Cisco UCS Director contexts, and copy it into
the JSON parameter specification in your API request.
• In Cisco UCS Director, navigate to a report that represents the same report data that you want to request
through the API. Find the REST API URL in Report Metadata and use the context parameter(s) that
you find there.
Timesaver
Note
If you find the URL code used to send a request in Cisco UCS Director, you can use some or all of that
API request data to create your own request.
In some scenarios, you might want to use the English (human-readable) name string for the context value
rather than the numeral string value that is provided in the Report Metadata listing of the REST API URL.
Context Field Names and Corresponding Parameter Names
In the listing below, the first element is the name of the field; the second, in quotation marks, is the context
value that you should assign to the parameter representing the context. In most requests for reports, param0
Cisco UCS Director REST Developer Guide, Release 5.1
75
API Request Parameters
API Request Context Parameters
provides the context. If another context parameter (param1) value is required, you can use the value provided
for this parameter in the Report Metadata listing of the REST API URL.
Administrative Contexts
• CONTEXT_TYPE_GLOBAL= "global";
• CONTEXT_TYPE_GLOBAL_ADMIN = "global-admin";
• CONTEXT_TYPE_GLOBAL_SERVICES = "global-services";
• CONTEXT_TYPE_CLOUD = "cloud";
• CONTEXT_TYPE_HOSTNODE = "hostnode";
• CONTEXT_TYPE_CLUSTER = "cluster";
End User Contexts
• CONTEXT_TYPE_GROUP = "group";
• CONTEXT_TYPE_VM = "vm";
• CONTEXT_TYPE_VDC = "vdc";
• CONTEXT_TYPE_SR = "servicerequest";
Data Center Contexts
• CONTEXT_TYPE_PHYSICAL_DATACENTER = "datacenter";
NetApp Report Contexts
• CONTEXT_TYPE_STORAGE_ACCOUNTS= " storage_accounts";
• CONTEXT_TYPE_STORAGE_FILERS = " netapp_filer";
• CONTEXT_TYPE_STORAGE_AGGREGATES = " storage_aggregates";
• CONTEXT_TYPE_STORAGE_VOLUMES = "storage_volumes";
• CONTEXT_TYPE_STORAGE_LUNS = "luns";
• CONTEXT_TYPE_STORAGE_VFLIERS = "netapp_v_flier";
UCS Report Contexts
• CONTEXT_TYPE_INFRA_COMPUTE_UCSM_ACCOUNT= " ucsm";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_FABRIC_INTERCONNECT = " compute_fbi";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_CHASSIS = " compute_chassis";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_SERVER = "compute_server";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_SERVICE_PROFILE = "service_profile";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_PORT_CHANNEL = "ucs_portchannel";
Cisco UCS Director REST Developer Guide, Release 5.1
76
API Request Parameters
API Request Parameters for Reports or JSON Objects
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_ORGANIZATION = "ucs_org";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_SERVICE_PROFILE_TEMPLATE =
"ucs_service-profile-template";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_BOOT_POLICY = "ucs_boot_policy";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_VNIC_TEMPLATE = "ucs_vnictemplate";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_MAC_POOL = "ucs_mac";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_UUID_POOL = "ucs_uuid";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_WWNN_POOL = "ucs_wwnn";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_WWPN_POOL = "ucs_wwpn";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_SERVICE_PROFILE_VHBA = "ucs_sp_vhba";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_SERVICE_PROFILE_VNIC = "ucs_sp_vnic";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_IOMODULE = "ucs_iomodule";
• CONTEXT_TYPE_INFRA_COMPUTE_UCS_SERVER_ADAPTER_UNIT =
"compute_server_adapter_unit";
Network Report Contexts
• CONTEXT_TYPE_INFRA_NETWORK_DEVICE= "network_device";
• CONTEXT_TYPE_INFRA_NET_DEVICE_N1K = " net_device_n1k";
• CONTEXT_TYPE_INFRA_NET_DEVICE_FAB_IC = " net_device_fab_ic";
• CONTEXT_TYPE_INFRA_NET_DEVICE_N5K = "net_device_n5k";
• CONTEXT_TYPE_INFRA_NETWORK_DEVICE_VLAN = "net_device_vlan";
• CONTEXT_TYPE_INFRA_NETWORK_DEVICE_VSAN = "net_device_vsan";
• CONTEXT_TYPE_INFRA_NETWORK_DEVICE_INTERFACE = "net_device_interface";
• CONTEXT_TYPE_INFRA_NETWORK_DEVICE_PORT_PROFILE = "net_device_port_profile";
• CONTEXT_TYPE_INFRA_NETWORK_DEVICE_ZONE = "net_device_zone";
• CONTEXT_TYPE_INFRA_NET_QOS_POLICY = "net_device_qos_policy";
API Request Parameters for Reports or JSON Objects
In addition to requesting specific data fields, Cisco UCS Director operations may include request parameters
that specify the response must be a type of report (identified by its reportId) or a JSON object identified by
name.
If you need to obtain a specific report or a given report format or a JSON object from your API request, that
requirement may be useful for identifying the API operation and parameters you need to use in your request.
• To see which API operations return the data and format you need to provide, see About the REST API
Operations, on page 20.
Cisco UCS Director REST Developer Guide, Release 5.1
77
API Request Parameters
API Request Parameters for Reports or JSON Objects
• To see which UCS Director contexts are associated with given report or report format, see List of
Available Cisco UCS Director Reports, on page 101.
If you need to process a JSON object, either as input to or output from an API operation, see JSON Object
Parameter Types, on page 79.
Cisco UCS Director REST Developer Guide, Release 5.1
78
CHAPTER
6
JSON Objects
This chapter contains the following sections:
• JSON Object Parameter Types, page 79
• JSON Example: APIVDCDetails, page 80
• JSON Example: APICatalogItem, page 81
• JSON Example: APIUserOnBoardParams, page 81
• JSON Example: APIUserOnBoardDetails, page 81
• JSON Example: APILoginProfile, page 81
• JSON Example: APIMakePaymentParams, page 82
• JSON Example: APIProvisionParams, page 82
• JSON Example: APIServiceContainerTemplate , page 82
JSON Object Parameter Types
JSON objects contain data in a consistent format that can be passed and programmatically consumed more
easily than the data in report formats. JSON objects appear in both API requests and responses.
A JSON object is an unordered set of name/value pairs, so it tends to be self-explanatory, like XML, but it is
less bulky.
Note
For examples of other data types that also carry large data payloads, see Reports and JSON Object Response
Samples, on page 90.
Parameters for JSON objects are passed in the following format: ParameterName:parameterValue. A proper
JSON object begins with a left brace { and ends with a right brace } . Each name in a pair is followed by a
colon (:) and then the corresponding value. The name/value pairs are separated by commas.
Cisco UCS Director REST Developer Guide, Release 5.1
79
JSON Objects
JSON Example: APIVDCDetails
JSON Example: APIVDCDetails
The userAPICreateVDC API uses the APIVDCDetails object to create a virtual Data Center (vDC ).
• If the vDC type is Hyper-V, provide the deployment policy name for the deploymentPolicy parameter
and the null value for the systemPolicy parameter.
• If the vDC type is VMware, provide the null value for the deploymentPolicy parameter and the system
policy name for the systemPolicy parameter.
The following sample shows examples of valid name/value pairs for this JSON object for the Hyper-V type
vDC.
"vdcName": "customerTest",
"vdcDescription": "customerTest",
"cloudName": "TestHyperV",
"groupName": "1",
"approver1": null,
"approver2": null,
"vdcSupportEmail":"[email protected]",
"vdcCustomerNoticationEmail":"[email protected]",
"systemPolicy": null,
"deploymentPolicy":"default-d",
"slaPolicy": null,
"computingPolicy": "default",
"storagePolicy": "default",
"networkPolicy": "default",
"costModel": "Default Cost Model",
"isLocked": false,
"isDeletable": false,
"isSelfServicePowerMgmt": false,
"isSelfServiceResize": false,
"isSelfServiceDeleteVM": false,
"isSelfServiceSnapshotMgmt": false,
"inactivityPeriodForDeletion": -1
The following sample shows examples of valid name/value pairs for this JSON object for the VMware type
vDC.
"vdcName":"VMware VDC",
"vdcDescription":"VMware Based VDC",
"cloudName":"DFA vCenter",
"groupName":1,
"approver1":"",
"approver2":"",
"vdcSupportEmail":"[email protected]",
"vdcCustomerNoticationEmail":"",
"systemPolicy":"SystemPolicy",
"deploymentPolicy":"",
"slaPolicy":null,
"computingPolicy":"DFA vCenter - Default Computing Policy",
"storagePolicy":"DFA vCenter - Default Storage Policy",
"networkPolicy":"DFA vCenter - Default Network Policy",
"costModel":"Default Cost Model",
"isLocked":true,
"isDeletable":true,
"isSelfServicePowerMgmt":true,
"isSelfServiceResize":true,
"isSelfServiceDeleteVM":true,
"isSelfServiceSnapshotMgmt":true,
"isSelfServiceDiskMgmt":true,
"isSelfServiceNetMgmt":true,
"inactivityPeriodForDeletion":1
Cisco UCS Director REST Developer Guide, Release 5.1
80
JSON Objects
JSON Example: APICatalogItem
JSON Example: APICatalogItem
The following table shows examples of valid name/value pairs for this JSON object.
"catalogItemId":-1,
"catalogItemName":"CATFOR API",
"catalogItemDescription":null,
"cloudName":"VMware161",
"imageId":"Linux-SJ-PROD-Template",
"groups":"QAgroup",
"isAppliedToAllGroups":false,
"supportEmail":"[email protected]",
"vdcCategoryId":1,
"appList":null,
"otherApps":null,
"os":-1,
"otherOS":null,
"templateUser":null,
"templatePassword":null,
"credentialOption":1
JSON Example: APIUserOnBoardParams
The following table shows examples of valid name/value pairs for this JSON object.
"firstName":"John",
"lastName":"Smith",
"userID":"jsmith",
"passWord":"test123",
"role":"GroupAdmin",
"contactEmail":"[email protected]",
"companyName":"test",
"vdcProfileName":"VDC smith",
"vdcName":"myvdc",
"billFrequency":"",
"additionalInfo":"test
JSON Example: APIUserOnBoardDetails
The following table shows examples of valid name/value pairs for this JSON object.
"groupID":"12"
"groupName":"test"
"vdcID":"5"
"vdcName":"myvdc"
JSON Example: APILoginProfile
The following table shows examples of valid name/value pairs for this JSON object.
"userId":"jsmith"
"firstName":"John"
"lastName":"Smith"
Cisco UCS Director REST Developer Guide, Release 5.1
81
JSON Objects
JSON Example: APIMakePaymentParams
"email":"[email protected]"
"groupName":"test"
"groupId":"12"
"role":"GroupAdmin"
JSON Example: APIMakePaymentParams
The following table shows examples of valid name/value pairs for this JSON object.
"userID":"jsmith"
"ordered":"123"
"amount":"1000"
"companyName":"Test"
"status":"success"
"timestamp":"1308647424609"
JSON Example: APIProvisionParams
The following table shows examples of valid name/value pairs for this JSON object.
"catalogName":"QA Catalog .161",
"vdcName":"QA vDC",
"userID":"SmithUser",
"durationHours":1,
"beginTime":0,
"quantity":1,
"memoryMB":512,
"cores":1,
"estimatedCost":1250,
"comments":"test",
"additionalInfo":"test"
JSON Example: APIServiceContainerTemplate
The following table shows examples of valid name/value pairs for this JSON object.
{
"templateId":1000,
"templateType":"sample",
"templateName":"test SDK TemplateName ",
"templateDescription":"test SDK templateDescription ",
"containerType":"sample",
"templateDefinitionData":"sample",
"templateConfig":{
"vInfraPolicy":"cloud82",
"networks":[
{
"networkName":"lan0",
"networkType":1000,
"vlanIDPool":"100-199",
"networkPool":1000,
"ipSubnetPool":1000,
"networkIP":"10.10.10.0",
"networkMask":"255.255.255.0",
"gatewayIP":"10.10.10.1"
},
{
Cisco UCS Director REST Developer Guide, Release 5.1
82
JSON Objects
JSON Example: APIServiceContainerTemplate
"networkName":"lan1",
"networkType":1000,
"vlanIDPool":"200-299",
"networkPool":1000,
"ipSubnetPool":1000,
"networkIP":"20.20.20.0",
"networkMask":"255.255.255.0",
"gatewayIP":"20.20.20.1"
}
],
"dfaNetworks":[
{
"networkName":"sample",
"networkRole":"sample",
"description":"sample",
"networkType":1000,
"profileName":"sample",
"gatewayIP":"sample",
"networkMask":"sample",
"dhcpServerAddress":"sample",
"gatewayIpv6Address":"sample",
"prefixLength":"sample",
"startIP":"sample",
"endIP":"sample",
"secondaryGateway":"sample"
},
{
"networkName":"sample",
"networkRole":"sample",
"description":"sample",
"networkType":1000,
"profileName":"sample",
"gatewayIP":"sample",
"networkMask":"sample",
"dhcpServerAddress":"sample",
"gatewayIpv6Address":"sample",
"prefixLength":"sample",
"startIP":"sample",
"endIP":"sample",
"secondaryGateway":"sample"
}
],
"vnmcFirewallConfig":{
"networkName":"sample",
"ipAddress":"sample"
},
"vnmcZones":[
{
"zoneName":"sample",
"zoneDesc":"sample",
"vnmcZoneRules":[
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
},
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
}
]
},
{
"zoneName":"sample",
"zoneDesc":"sample",
"vnmcZoneRules":[
Cisco UCS Director REST Developer Guide, Release 5.1
83
JSON Objects
JSON Example: APIServiceContainerTemplate
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
},
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
}
]
}
],
"vnmcAcls":[
{
"name":"sample",
"descr":"sample",
"firewallAction":"sample",
"matchCriteria":"sample",
"protocolServiceOption":"sample",
"protocol":true,
"protocalOperator":"sample",
"protocalValue":"sample",
"services":[
{
"protocalOperator":"sample",
"protocalValue":"sample",
"serviceName":"sample",
"servicePort":1000,
"errormessage":"sample"
},
{
"protocalOperator":"sample",
"protocalValue":"sample",
"serviceName":"sample",
"servicePort":1000,
"errormessage":"sample"
}
],
"srcRules":[
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"zoneAttributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
},
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"zoneAttributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
}
],
"destRules":[
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"zoneAttributeValue":"sample",
"prefixedIpAddressValue":"sample",
Cisco UCS Director REST Developer Guide, Release 5.1
84
JSON Objects
JSON Example: APIServiceContainerTemplate
"prefixedSubnetValue":"sample"
},
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"zoneAttributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
}
]
},
{
"name":"sample",
"descr":"sample",
"firewallAction":"sample",
"matchCriteria":"sample",
"protocolServiceOption":"sample",
"protocol":true,
"protocalOperator":"sample",
"protocalValue":"sample",
"services":[
{
"protocalOperator":"sample",
"protocalValue":"sample",
"serviceName":"sample",
"servicePort":1000,
"errormessage":"sample"
},
{
"protocalOperator":"sample",
"protocalValue":"sample",
"serviceName":"sample",
"servicePort":1000,
"errormessage":"sample"
}
],
"srcRules":[
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"zoneAttributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
},
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"zoneAttributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
}
],
"destRules":[
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
"zoneAttributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
},
{
"attributeType":"sample",
"attributeName":"sample",
"operator":"sample",
"attributeValue":"sample",
Cisco UCS Director REST Developer Guide, Release 5.1
85
JSON Objects
JSON Example: APIServiceContainerTemplate
"zoneAttributeValue":"sample",
"prefixedIpAddressValue":"sample",
"prefixedSubnetValue":"sample"
}
]
}
],
"vms":[
{
"templateName":"sample",
"zone":"sample",
"appName":"VM1",
"appDescription":"sample",
"imageId":"FC_Gateway",
"numVCPUs":1000,
"memoryMB":1000,
"cpuReservationMHz":1000,
"memoryReservationMB":1000,
"diskSize":1000,
"passwordResetType":1000,
"templateRootLogin":"sample",
"templateRootPassword":"sample",
"appCategory":"sample",
"isUseImageNetwork":true,
"networks":[
{
"appName":"nic1",
"networkName":"lan0",
"adapterType":"e1000",
"ipAddress":"10.10.10.1",
"enablePublicIPMapping":true
},
{
"appName":"nic2",
"networkName":"lan1",
"adapterType":"e1000",
"ipAddress":"20.20.20.1",
"enablePublicIPMapping":true
}
],
"maxQuantity":1000,
"initialQuantity":1000,
"isStorageEfficiencyEnabled":true
},
{
"templateName":"sample",
"zone":"sample",
"appName":"sample",
"appDescription":"sample",
"imageId":"sample",
"numVCPUs":1000,
"memoryMB":1000,
"cpuReservationMHz":1000,
"memoryReservationMB":1000,
"diskSize":1000,
"passwordResetType":1000,
"templateRootLogin":"sample",
"templateRootPassword":"sample",
"appCategory":"sample",
"isUseImageNetwork":true,
"networks":[
{
"appName":"sample",
"networkName":"sample",
"adapterType":"sample",
"ipAddress":"sample",
"enablePublicIPMapping":true
},
{
"appName":"sample",
"networkName":"sample",
"adapterType":"sample",
"ipAddress":"sample",
Cisco UCS Director REST Developer Guide, Release 5.1
86
JSON Objects
JSON Example: APIServiceContainerTemplate
"enablePublicIPMapping":true
}
],
"maxQuantity":1000,
"initialQuantity":1000,
"isStorageEfficiencyEnabled":true
}
],
"portMappings":[
{
"protocol":6,
"mappedPort":80,
"remoteIP":"10.10.10.2",
"remotePort":80
},
{
"protocol":1000,
"mappedPort":1000,
"remoteIP":"sample",
"remotePort":1000
}
],
"outboundACLs":[
{
"protocol":6,
"network":"lan0",
"srcCIDR":"0.0.0.0/0",
"destCIDR":"0.0.0.0/0",
"srcPortRange":"sample",
"destPortRange":"sample",
"fireallAction":0
},
{
"protocol":1000,
"network":"sample",
"srcCIDR":"sample",
"destCIDR":"sample",
"srcPortRange":"sample",
"destPortRange":"sample",
"fireallAction":1000
}
],
"policies":{
"virtualComputePolicy":"Cloud82 - Default Computing Policy",
"virtualStoragePolicy":"Cloud82 - Default Storage Policy",
"virtualNetworkPolicy":"Cloud82 - Default Network Policy",
"virtualSystemPolicy":"system test",
"costModel":"Default Cost Model ",
"userActionPolicy":"sample"
},
"options":{
"isSelfServicePowerMgmt":true,
"isSelfServiceResize":true,
"isSelfServiceSnapshotMgmt":true,
"isSelfServiceDeleteVM":true,
"isSelfServiceDeleteContainer":true,
"isConsoleAccess":true,
"supportEmails":"[email protected]"
},
"gatewayConfig":{
"gwPolicy":"sample",
"networkMapping":[
{
"network":"sample",
"networkIP":"sample",
"interfaceName":"sample"
},
{
"network":"sample",
"networkIP":"sample",
"interfaceName":"sample"
}
],
Cisco UCS Director REST Developer Guide, Release 5.1
87
JSON Objects
JSON Example: APIServiceContainerTemplate
"isConfigGateway":true
},
"workflowConfig":{
"setupWorkflow":"Fenced Container Setup"
},
"templateName":"sample"
}
}
}
Cisco UCS Director REST Developer Guide, Release 5.1
88
CHAPTER
7
Reports
This chapter contains the following sections:
• About Reports, page 89
• Reports and JSON Object Response Samples, page 90
• Using GetAvailableReports to Obtain ReportIds, page 97
• Tabular Reports, page 99
• Historical Reports, page 100
• Snapshot Reports, page 100
• List of Available Cisco UCS Director Reports, page 101
• Using the List of Available Reports, page 118
About Reports
Cisco UCS Director reports tend to be in one of three fundamental report formats: Tabular, Historical, or
Snapshot. This section includes extensive information about these three formats. This section also shows
samples of the different report types, including specialized reports such as the VM report and the
APIWorkFlowStatus report. see Reports and JSON Object Response Samples, on page 90.
Cisco UCS Director provides dynamically updated lists of the reports available to you and graphic renderings
of each type of report. For each different Cisco UCS Director context, a different set of reports (each identified
by a reportId) is available.
To create an API request for a specific report, you need to use the proper operation name and the following:
• The context of the report (for example, the values for param0 and param1 in a JSON formatted API
request with three parameters)
• The reportId value (typically, the last JSON parameter listed in an API report request)
To get the most complete and current list of reports available for a Cisco UCS Director context, use the
userAPIGetAvailableReport operation.
Cisco UCS Director REST Developer Guide, Release 5.1
89
Reports
Reports and JSON Object Response Samples
For a list of standard Cisco UCS Director contexts and the reports associated with them, see List of Available
Cisco UCS Director Reports, on page 101.
Note
Cisco UCS Director commonly generates context values that are specific to customer sites, including
contexts that refer to dynamically changing clouds of virtual machines. Workflows also depend on specific
customer set-up, so you will have to maintain and use your own workflow-related values. To view
customer-specific values, you must generate the GetAvailableReport mentioned above, or obtain the
context data from the Report Metadata associated with an existing report in Cisco UCS Director.
For fundamental information about using context and reportId data to construct an API request, see Request
Format, on page 14.
Reports and JSON Object Response Samples
In addition to the samples provided in this section, some of the JSON objects discussed in JSON Object
Parameter Types, on page 79 can also be rendered into reports.
AvailableReports (a tabular report)
This very useful report returns a comprehensive list of the reports available for a specified Cisco UCS Director
context. It includes report ID, report label and report type.
The following is a sample of this report:
{ "serviceResult":
[{"reportLabel":"Summary","reportId":"SUMMARY-V50","reportType":"tabular"},
{"reportLabel":"UCS Readiness","reportId":"UCS-READINESS-T50","reportType":"tabular"},
{"reportLabel":"Organizations","reportId":"ORGANIZATIONS-T50","reportType":"tabular"},
{"reportLabel":"Chassis
Inventory","reportId":"CHASSIS-INVENTORY-S50","reportType":"snapshot"},
{"reportLabel":"Server Inventory","reportId":"SERVER-INVENTORY-S50","reportType":"snapshot"},
{"reportLabel":"Fabric Interconnect Inventory","reportId":"FABRIC-INTERCONNECT-INVENTORY-S50",
"reportType":"snapshot"},
{"reportLabel":"Servers Associated vs Unassociated ",
"reportId":"SERVERS-ASSOCIATED-VS-UNASSOCIATED-S50",
"reportType":"snapshot"},
{"reportLabel":"Chassis","reportId":"CHASSIS-T50","reportType":"tabular"},
{"reportLabel":"Servers","reportId":"SERVERS-T50","reportType":"tabular"},
{"reportLabel":"Fabric Interconnects","reportId":"FABRIC-INTERCONNECTS-T50",
"reportType":"tabular"},
{"reportLabel":"Service Profiles","reportId":"SERVICE-PROFILES-T50","reportType":"tabular"},
{"reportLabel":"Events","reportId":"EVENTS-T50","reportType":"tabular"},
{"reportLabel":"VSANs","reportId":"VSANS-T50","reportType":"tabular"},
{"reportLabel":"VLANs","reportId":"VLANS-T50","reportType":"tabular"},
{"reportLabel":"Port Channels","reportId":"PORT-CHANNELS-T50","reportType":"tabular"},
{"reportLabel":"QOS System Class","reportId":"QOS-SYSTEM-CLASS-T50","reportType":"tabular"},
{"reportLabel":"Chassis Discovery Policy","reportId":"CHASSIS-DISCOVERY-POLICY-T50",
"reportType":"tabular"},
{"reportLabel":"Management IP
Pool","reportId":"MANAGEMENT-IP-POOL-T50","reportType":"tabular"},
{"reportLabel":"Flow Control Policies","reportId":"FLOW-CONTROL-POLICIES-T50",
"reportType":"tabular"},
{"reportLabel":"Locales","reportId":"LOCALES-T50","reportType":"tabular"},
{"reportLabel":"Faults","reportId":"FAULTS-T50","reportType":"tabular"}
],
"serviceError":null, "serviceName":"InfraMgr", "opName":"userAPIGetAvailableReports" }
Cisco UCS Director REST Developer Guide, Release 5.1
90
Reports
Reports and JSON Object Response Samples
APIReportDefinitionList
This report provides an array of three name-value pairs: reportLabel, reportId, and reportType.
The following is a sample of the JSON Object Response for this report.
[
{"reportLabel":"Summary",
"reportId":"SUMMARY-V1",
"reportType":"tabular"},
{"reportLabel":"Summary",
"reportId":"SUMMARY-V0",
"reportType":"tabular"},
{"reportLabel":"Active VM Distribution By Cloud",
"reportId":"ACTIVE-VM-DISTRIBUTION-BY-CLOUD-S0",
"reportType":"snapshot"},
{"reportLabel":"Trend: Storage Capacity, Used & Free",
"reportId":"TREND-STORAGE-CAPACITY,-USED-&-FREE-H1",
"reportType":"trend"}
]
APITabularReport
This report provides an array of rows that consist of name-value pairs of columns. The report ID can be picked
from userAPIGetAvailableReports.
The following is a sample of this report.
[
{"VMId":1,
"Month":"October, 2010",
"Active_VM_Hours":231,
"Inactive_VM_Hours":160,
"Active_VM_Cost_USD":0,
"Inactive_VM_Cost_USD":0,
"One_time_Cost_USD":0,
"Allocated_CPU_Cost_USD":0,
"Reserved_CPU_Cost_USD":0,
"Used_CPU_Cost_USD":0,
"Allocated_Memory_Cost_USD":0,
"Reserved_Memory_Cost_USD":0,
"Used_Memory_Cost_USD":0,
"Committed_Disk_Cost_USD":0,
"Uncommitted_Disk_Cost_USD":0,
"Total_Cost_USD":0}
]
APIHistoricalReport
This report provides an array of series that consist of the parameter (legend) name and the values of data
samples for a given duration. The valid values for the duration are hourly, daily, weekly, and monthly. The
reportId must be picked from userAPIGetAvailableReports.
The following is a sample of this report.
{"series":[
{"paramName":"cpuCapacityGhz",
"paramLabel":"CPU Capacity (GHz)",
"values":[
{"timestamp":1285728870845,
"min":51.734405256,
"max":51.734405256,
"avg":51.734405256},
{"timestamp":1285732492006,
"min":51.734405256,
"max":51.734405256,
"avg":51.734405256},
Cisco UCS Director REST Developer Guide, Release 5.1
91
Reports
Reports and JSON Object Response Samples
{"timestamp":1285736120878,
"min":51.734405256,
"max":51.734405256,
"avg":51.734405256},
{"timestamp":1285739726401,
"min":51.734405256,
"max":51.734405256,
"avg":51.734405256}]}]}
APISnapshotReport
This report provides an array of categories that consist of name-value pairs of data samples. This report drills
down through the data hierarchy. The reportId can be picked from userAPIGetAvailableReports.
The following is a sample of this report.
{"categoryAxisName":null,
"valueAxisName":"Active vs Inactive",
"categories":[
{"categoryName":"",
"nameValuePairs":[
{"name":"Active VMs",
"value":"17"},
{"name":"Inactive VMs",
"value":"51"}]}]}
APILoginProfile
This report provides the user ID, first name, last name, email, group name, and role.
The following is a sample of the JSON Object Response for this report.
"userId":"jsmith"
"firstName":"Smith"
"lastName":"John"
"email":"[email protected]"
"groupName":"test"
"groupId":"12"
"role":"GroupAdmin"
userAPIGetVMSummary (tabular report)
This report provides a summary report in tabular format for a specified VM.
The following is a sample of this report.
{"Overview_VM_ID":1,
"Overview_Instance_Name":"My-Instance-120",
"Overview_Status":"UNKNOWN (poweredOn)",
"Overview_IP_Address":"10.10.1.120",
"Overview_Hostname":"coud-vc",
"Overview_Image_ID":"My-Instance-120",
"Overview_Cloud_Name":"VMware Cloud A",
"Overview_Cloud_Type":"VMWare",
"Ownership_Group":"Eng Group",
"Ownership_vDC":"Eng-SJ-Prd",
"Ownership_Category":"Application Server",
"Ownership_Service_Request_ID":"",
"Ownership_Label":"vCenter 120",
"Ownership_Provisioned_Time":"",
"Ownership_Scheduled_Termination_Time":"",
"Overview_Host_Node":"10.10.1.200",
"Network_Port_Group":"VM Network",
"Network_VLAN_ID":"0",
"Network_No_of_vNics":1,
"Network_vNic_Mac_Address":"00:50:56:82:55:69",
"Network_vNic_Device_Config_Id":"4000",
Cisco UCS Director REST Developer Guide, Release 5.1
92
Reports
Reports and JSON Object Response Samples
"Overview_Boot_Time":"Sep 25, 2010 18:54:23",
"Overview_Config_Name":"vCenter-Server 120",
"Overview_VM_Version":"4",
"Resources_Resource_Pool":"Resources",
"Resources_Num_Virtual_CPUs":1,
"Resources_CPU_Reserved_MHz":2881,
"Resources_CPU_Limit_MHz":-1,
"Resources_CPU_Overhead_Limit_MHz":0,
"Resources_CPU_Shares":"4000",
"Resources_Memory_MB":2056,
"Resources_Memory_Reserved_MB":2050,
"Resources_Memory_Limit_MB":0,
"Resources_Memory_Overhead_Limit_MB":0,
"Resources_Memory_Shares":"2560",
"Storage_Total_Provisioned_GB":43.02,
"Storage_Committed_GB":15.31,
"Storage_Uncommitted_GB":27.71,
"Storage_Non_shared_GB":15.31,
"Storage_Data_Store_Names":"storage2",
"Storage_VM_Path":"[storage2] VirtualCenter-Clone_Dec_09/
VirtualCenter-Clone_Dec_09.vmx",
"Guest_Information_Guest_OS":"Microsoft Windows Server 2003,
Enterprise Edition (32-bit)",
"Guest_Information_Guest_State":"running",
"Guest_Information_Tools_Status":"guestToolsRunning",
"Guest_Information_Tools_Version":"32039",
"Options_Default_PowerOff_Type":"hard"}
userAPIGetServiceContainerDetails (tabular report)
This report lists the service container details such as network summary, port mapping, virtual machine
information, event history, and so on.
Input
/app/api/rest?formatType=json&opName=fenced:userAPIGetServiceContainerDetails&opData={param0:"ga"}
Output
{ "serviceResult":{"rows":[
{"Overview_ID":19,
"Overview_containerType":null,
"Overview_containerName":"ga",
"Overview_containerLabel":"",
"Overview_containerState":1,
"Template_Name":"temp_asa",
"Template_Group":"Default Group",
"Template_CreatedTime":"Mar 20, 2014 03:29:57 UTC",
"Template_LeasedTime":"",
"Template_ServiceRequest":193,
"Template_Initiatedby":"admin",
"Template_ServiceRequestStatus":"Complete",
"Template_OrchestrationFlow":"Fenced Container Setup",
"Policy_UserAction":null,
"Policy_VirtualCompute":"VMware-82 - Default Computing Policy",
"Policy_VirtualNetwork":"demo_akila",
"Policy_VirtualStorage":"VMware-82 - Default Storage Policy",
"Policy_VirtualSystem":"IT Sys",
"Policy_CostModel":"",
"vInfraPolicyInfo_PolicyName":"asa_pol",
"vInfraPolicyInfo_vAccount":"VMware-82",
"vInfraPolicyInfo_ContainerType":"Fenced Virtual",
"NetworkSummary_1_NetworkName":"lan0",
"NetworkSummary_1_VlanIDPool":"100-199",
"NetworkSummary_1_NetworkIP":"10.10.10.0",
"NetworkSummary_1_NetworkMask":"255.255.255.0",
"NetworkSummary_1_GatewayIP":"10.10.10.1",
"VMs_1_VMName":"asa_vm","VMs_1_ipaddress":"10.10.10.6",
"PortMapping_1_Protocol":6,"PortMapping_1_MappedPort":222,
"PortMapping_1_RemoteIP":"10.10.10.4",
"PortMapping_1_RemotePort":222,
"OutboundACL_1_Protocol":0,
Cisco UCS Director REST Developer Guide, Release 5.1
93
Reports
Reports and JSON Object Response Samples
"OutboundACL_1_Network":"lan0",
"OutboundACL_1_SrcAddress":"0.0.0.0/0",
"OutboundACL_1_DestAddress":"0.0.0.0/0",
"OutboundACL_1_SrcPortRange":"0-65535",
"OutboundACL_1_DestPortRange":"0-65535",
"OutboundACL_1_Action":"ACCEPT",
"Options_isSelfServicePowerMgmt":"true",
"Options_isSelfServiceResize":"true",
"Options_isSelfServiceSnapshotMgmt":"true",
"Options_isSelfServiceDeleteVM":"false",
"Options_isSelfServiceDeleteContainer":"false",
"Options_isConsoleAccess":"true","Options_supportEmails":""}],
"columnMetaData":null},
"serviceError":null,
"serviceName":"InfraMgr",
"opName":"fenced:userAPIGetServiceContainerDetails" }
userAPIGetAllVDCs (tabular report)
This report lists all virtual datacenters for the currently logged in user group. No parameters are required.
The following sample report lists the cloud, group, vDC, state, total number of VMs, number of active VMs,
and Custom Categories for the user group.
[
{"Cloud":"",
"Group":"Default Group",
"vDC":"Default vDC",
"State":"Locked",
"Total_VMs":67,
"Active_VMs":17,
"Custom_Categories":0},
{"Cloud":"VMware Cloud A",
"Group":"Eng Group",
"vDC":"Eng-SJ-Prd",
"State":"Ok",
"Total_VMs":1,
"Active_VMs":0,
"Custom_Categories":0},
{"Cloud":"VMware Cloud B",
"Group":"Eng Group",
"vDC":"Eng-SJ-161",
"State":"Ok",
"Total_VMs":0,
"Active_VMs":0,
"Custom_Categories":0},
{"Cloud":"VMware Cloud B",
"Group":"Prod",
"vDC":"checkign delete",
"State":"Ok",
"Total_VMs":0,
"Active_VMs":0,
"Custom_Categories":0},
{"Cloud":"VMware Cloud B",
"Group":"Eng Group",
"vDC":"Eng-Windows",
"State":"Ok",
"Total_VMs":0,
"Active_VMs":0,
"Custom_Categories":0}]
userAPIGetAllVMs (tabular report)
This report retrieves a report of all VMs for the logged in user and provides some management-level data
about each VM.
Cisco UCS Director REST Developer Guide, Release 5.1
94
Reports
Reports and JSON Object Response Samples
The following is a sample of this report.
[
{"Cloud":"VMware Cloud A",
"VM_ID":"1",
"VM_Label":"",
"Instance_Name":"vCenter-Server 120",
"Host_Name":"coud-vc.",
"IP_Address":"10.10.1.120",
"Image_Id":"vCenter-Server 120",
"Power_State":"UNKNOWN",
"Group_Name":"Eng Group",
"vDC":"Eng-SJ-Prd",
"Category":"Application Server",
"Provisioned_Time":"",
"Scheduled_Termination_Time":"",
"Last_Status_Update":"Oct 14, 2010 01:19:22"},
{"Cloud":"VMware Cloud A",
"VM_ID":"2",
"VM_Label":"",
"Instance_Name":"CentOS-53-HardenedOS",
"Host_Name":null,
"IP_Address":null,
"Image_Id":"CentOS-53-HardenedOS",
"Power_State":"UNKNOWN",
"Group_Name":"Default Group",
"vDC":"Default vDC",
"Category":"Discovered VM",
"Provisioned_Time":"",
"Scheduled_Termination_Time":"",
"Last_Status_Update":"Oct 14, 2010 01:19:22"}]
APIVMAction: userAPIGetAvailableVMActions
This report lists the available VM Actions possible for a given VM-ID.
The following is a sample of this report.
[
{"actionName":"reconfigure",
"actionLabel":"Resize VM",
"actionType":"reconfigure"},
{"actionName":"powerOn",
"actionLabel":"Power ON",
"actionType":"vmAction"},
{"actionName":"powerOff",
"actionLabel":"Power OFF",
"actionType":"vmAction"},
{"actionName":"suspend",
"actionLabel":"Suspend",
"actionType":"vmAction"},
{"actionName":"shutdownGuest",
"actionLabel":"Shutdown Guest",
"actionType":"vmAction"},
{"actionName":"standby",
"actionLabel":"Standby",
"actionType":"vmAction"},
{"actionName":"reset",
"actionLabel":"Reset",
"actionType":"vmAction"},
{"actionName":"reboot",
"actionLabel":"Reboot",
"actionType":"vmAction"}]
Cisco UCS Director REST Developer Guide, Release 5.1
95
Reports
Reports and JSON Object Response Samples
APIVMActionStatus
This status report provides advice about the specified request for action with respect to a VM, such as
information about the ActionStatus for a given VMActionRequest.Request. You can request this report with
userAPIGetVMActionStatus.
The following is a sample of this report.
{"vmId":476,
"actionName":"powerOn",
"actionLabel":"Power ON",
"comment":"Powered ON through API",
"user":"admin",
"startTime":"Oct 19, 2010 15:54:08",
"endTime":"Oct 19, 2010 15:54:19",
"status":"Completed",
"message":""}
APIVMList
This report includes the cloud name, VM ID, instance ID, host name, IP address, image ID, power status,
status message, and VM type.
The following is a sample of this report.
{ "serviceResult":
{"rows":
[
{"Cloud":"VMware-138","VM_ID":2,"User_Label":"","VM_Name":"SJ-02-Perf-vCenter05",
"Host_Name":"WIN-0EVDFER0O7E","IP_Address":"172.29.109.138",
"Image_Id":"SJ-02-Perf-vCenter05","Host_Node":"172.29.109.42","Power_Status":"ON",
"Group_Name":"Default Group","vDC":"Default vDC","Category":"Discovered VM",
"Provisioned_Time":"","Scheduled_Termination_Time":"",
"Last_Status_Update":"Nov 19, 2013 13:47:10 PST",
"Guest_OS_Type":"Microsoft Windows Server 2008 R2 (64-bit)"
}
{"Cloud":"VMware-138","VM_ID":23,"User_Label":"",
"VM_Name":"CUCSD-4.1.0.0_FuncTest_Agent_2_Jatin","Host_Name":"localhost.localdom",
"IP_Address":"172.29.109.209","Image_Id":"CUCSD-4.1.0.0_FuncTest_Agent_2_Jatin",
"Host_Node":"172.29.109.32","Power_Status":"ON","Group_Name":"Default Group",
"vDC":"Default vDC","Category":"Discovered VM","Provisioned_Time":"",
"Scheduled_Termination_Time":"","Last_Status_Update":"Nov 19, 2013 13:47:10 PST",
"Guest_OS_Type":"CentOS 4/5/6 (64-bit)"
}
],"columnMetaData":null
}, "serviceError":null, "serviceName":"InfraMgr", "opName":"userAPIGetTabularReport"
}
APIServiceRequestDetails
This report provides the request ID, request type, initiating user, group name, request time, comments, provision
quantity, provision catalog, provision vDC name, and provision duration hours.
APIWorkFlowStatus
This report provides service request workflow details with workflow status updates. APIWorkFlowStatus has
multiple parameters that are categorized by the workflow steps.
The following is a sample of this report.
stepId: "Initiated by admin",
executionStatus: 3,
statusMessage: "",
handlerId: 4,
startedTime: -1,
Cisco UCS Director REST Developer Guide, Release 5.1
96
Reports
Using GetAvailableReports to Obtain ReportIds
completedTime: 1289962148379,
validTill: -1,
startAfter: -1
stepId: "Budget Watch",
executionStatus: 3,
statusMessage: "Budget check successful.",
handlerId: 8,
startedTime: -1,
completedTime: 1289962171550,
validTill: -1,
startAfter: -1
stepId: "Check Resource Limits",
executionStatus: 3,
statusMessage: "Resource limit check successful"
handlerId: 9,
startedTime: -1,
completedTime: 1289962189739,
validTill: -1,
startAfter: -1
stepId: "Resource Allocation",
executionStatus: 3,
statusMessage: "Allocated Host: 192.168.0.129",
handlerId: 6,
startedTime: -1,
completedTime: 1289962212294,
validTill: -1,
startAfter: -1
stepId: "Provision",
executionStatus: 3,
statusMessage: "Provisioning completed",
handlerId: 3,
startedTime: -1,
completedTime: 1289963432562,
validTill: -1,
startAfter: -1
stepId: "Setup Lifecycle Schedule",
executionStatus: 3,
statusMessage: null,
handlerId: 2,
startedTime: -1,
completedTime: 1289964123734,
validTill: -1,
startAfter: -1
stepId: "Notify",
executionStatus: 3,
statusMessage: null,
handlerId: 1,
startedTime: -1,
completedTime: 1289964161227,
validTill: -1,
startAfter: -1
Using GetAvailableReports to Obtain ReportIds
If you need to request a report, the reportId is crucial. One way to get a reportId is to query the report's context
with userAPIGetAvailableReports. This yields a tabular report that contains the reportId of every report
available at the specified context level.
For example, to query all available reports available at the Cisco UCS Manager context level, use the
userAPIGetAvailableReports operation and specify that you want the UCS Account Level Reports, as
Cisco UCS Director REST Developer Guide, Release 5.1
97
Reports
Using GetAvailableReports to Obtain ReportIds
follows: http://localhost:8080/app/api/rest?/formatType=json&opName=
userAPIGetAvailableReports&opData={param0:"ucsm",param1:""}
Note
Replace localhost:8080 with the Cisco UCS Director server IP.
Here is the API response:
{ "serviceResult":[{"reportLabel":"Summary","reportId":
"SUMMARY-V50","reportType":"tabular"},{"reportLabel":
"UCS Readiness","reportId":"UCS-READINESS-T50","reportType":
"tabular"},{"reportLabel":"Organizations","reportId":
"ORGANIZATIONS-T50","reportType":"tabular"},{"reportLabel":
"Chassis Inventory","reportId":"CHASSIS-INVENTORY-S50",
"reportType":"snapshot"},{"reportLabel":"Server Inventory",
"reportId":"SERVER-INVENTORY-S50","reportType":"snapshot"},
{"reportLabel":"Fabric Interconnect Inventory","reportId":
"FABRIC-INTERCONNECT-INVENTORY-S50","reportType":"snapshot"},
{"reportLabel":"Servers Associated vs Unassociated ","reportId":
"SERVERS-ASSOCIATED-VS-UNASSOCIATED-S50","reportType":
"snapshot"},{"reportLabel":"Chassis","reportId":"CHASSIS-T50",
"reportType":"tabular"},{"reportLabel":"Servers","reportId":
"SERVERS-T50","reportType":"tabular"},{"reportLabel":
"Fabric Interconnects","reportId":"FABRIC-INTERCONNECTS-T50",
"reportType":"tabular"},{"reportLabel":"Service Profiles",
"reportId":"SERVICE-PROFILES-T50","reportType":"tabular"},
{"reportLabel":"Events","reportId":"EVENTS-T50","reportType":
"tabular"},{"reportLabel":"VSANs","reportId":"VSANS-T50",
"reportType":"tabular"},{"reportLabel":"VLANs","reportId":
"VLANS-T50","reportType":"tabular"},{"reportLabel":
"Port Channels","reportId":"PORT-CHANNELS-T50","reportType":
"tabular"},{"reportLabel":"QOS System Class","reportId":
"QOS-SYSTEM-CLASS-T50","reportType":"tabular"},{"reportLabel":
"Chassis Discovery Policy","reportId":
"CHASSIS-DISCOVERY-POLICY-T50","reportType":"tabular"},
{"reportLabel":"Management IP Pool","reportId":
"MANAGEMENT-IP-POOL-T50","reportType":"tabular"},{"reportLabel":
"Flow Control Policies","reportId":"FLOW-CONTROL-POLICIES-T50",
"reportType":"tabular"},{"reportLabel":"Locales","reportId":
"LOCALES-T50","reportType":"tabular"},{"reportLabel":"Faults",
"reportId":"FAULTS-T50","reportType":"tabular"}], "serviceError":
null, "serviceName":"InfraMgr", "opName":
"userAPIGetAvailableReports" }
The report shown above lists all of the reports in the context, providing each report ID and its report format.
To get any particular report at the Cisco UCS Manager account context level, use the reportId from the API
output above. For example, to query a chassis report at the Cisco UCS Manager account context level, call
the userAPIGetTabularReport API, as follows:
http://localhost:8080/app/api/rest?/formatType=json&opName=
userAPIGetTabularReport&opData={param0:"ucsm",param1:"ucsm
57",param2:"CHASSIS-T50"}
Note
The first through third parameters are the context, query value, and report ID; the param1 query value is
in the ID column in the following tabular report.
The following response is returned:
{ "serviceResult":{"rows":[{"ID":"ucsm 57;sys/chassis-1",
"Account_Name":"ucsm 57","DN":"sys/chassis-1","Serial_Number":
"1","Model":"N20-C6508","Power_State":"ok","Operation_State":
Cisco UCS Director REST Developer Guide, Release 5.1
98
Reports
Tabular Reports
"operable","Configuration_State":"ok","License_State":
"license-ok","Servers":4,"IO_Modules":2,"PSUs":4,"Fan_Modules":8,
"Vendor":"Cisco Systems Inc"},{"ID":"ucsm 57;sys/chassis-2",
"Account_Name":"ucsm 57","DN":"sys/chassis-2","Serial_Number":
"2","Model":"N20-C6508","Power_State":"ok","Operation_State":
"operable","Configuration_State":"ok","License_State":
"license-ok","Servers":4,"IO_Modules":2,"PSUs":4,"Fan_Modules":8,
"Vendor":"Cisco Systems Inc"}],"columnMetaData":null},
"serviceError":null, "serviceName":"InfraMgr", "opName":
"userAPIGetTabularReport" }
Similarly, you can query the available reports at each context by applying the userAPIGetAvailableReports
API to other contexts. Then, using one of the reportIds returned in the response, you can request a specific
report using the appropriate API operation and context data.
Tip
If you are missing a key piece of information necessary to create an API request for a report (the proper
operation name to use in the API request, for example), you can probably fill in that information by
referring to the List of Available Cisco UCS Director Reports, on page 101. With two or more pieces of
the crucial information (the reportId, the context, the type of report you want), the list may enable you to
fill in the information necessary to construct the necessary request. Most reports are of three basic types,
and three corresponding operations are used to request them.
Tabular Reports
This type of report is either a vertical table (which can provide summary data) or a horizontal table of multiple
rows and columns. Essentially, the tabular report is an array of rows consisting of name value pairs. You can
get the reportIds for these reports returned as summary data by the operation userAPIGetAvailableReports.
The reportIds are suffixed with -V or -T, for Vertical or Tabular (horizontal) respectively. Tabular reports
and Tabular with Action reports are both considered Tabular reports, and you must request them with the
userAPIGetTabularReport method.
Note
The Summary reports that list all available reports within a context have a tabular structure, but you request
them through the operation userAPIGetAvailableReports. As with other tabular format reports, the names
are suffixed with -V or -T.
Example of a Tabular Report
{ "serviceResult":{"rows":[
{"ID":"ucsm 57;sys/chassis-1",
"Account_Name":"ucsm 57",
"DN":"sys/chassis-1",
"Serial_Number":"1",
"Model":"N20-C6508",
"Power_State":"ok",
"Operation_State":"operable",
"Configuration_State":"ok",
"License_State":"license-ok","Servers":4,
"IO_Modules":2,
"PSUs":4,
"Fan_Modules":8,
"Vendor":"Cisco Systems Inc"},
{"ID":"ucsm 57;sys/chassis-2",
"Account_Name":"ucsm 57",
Cisco UCS Director REST Developer Guide, Release 5.1
99
Reports
Historical Reports
"DN":"sys/chassis-2",
"Serial_Number":"2",
"Model":"N20-C6508",
"Power_State":"ok",
"Operation_State":"operable",
"Configuration_State":"ok",
"License_State":"license-ok",
"Servers":4,
"IO_Modules":2,
"PSUs":4,
"Fan_Modules":8,
"Vendor":"Cisco Systems Inc"}],
"columnMetaData":null},
"serviceError":null,
"serviceName":"InfraMgr",
"opName":"userAPIGetTabularReport" }
Historical Reports
The historic report is also known as a trend report. You use this type of report to monitor trends such as the
usage of a resource, or the occurrence of events, over time. Typical trend reports present information such as
CPU or network usage, or "VM Additions & Deletions" over a given period of time. The response format,
APIHistoricalReport, is an array of series consisting of parameter (legend) names and the values of data
samples for a given duration. The valid values for the duration are "hourly", "daily", "weekly" and "monthly".
The reportId for this type of report is suffixed with -H.
Example of a Historical Report
{"series":[
{"paramName":"cpuCapacityGhz",
"paramLabel":"CPU Capacity (GHz)",
"values":[
{"timestamp":1285728870845,
"min":51.734405256,
"max":51.734405256,
"avg":51.734405256},
{"timestamp":1285732492006,
"min":51.734405256,
"max":51.734405256,
"avg":51.734405256},
{"timestamp":1285736120878,
"min":51.734405256,
"max":51.734405256,
"avg":51.734405256},
{"timestamp":1285739726401,
"min":51.734405256,
"max":51.734405256,
"avg":51.734405256}]}]}
Snapshot Reports
The snapshot report is an instant report about a resource at any given point in time. For example, the snapshot
report of a VM's CPU usage provides the current CPU utilization value. The APISnapshotReport is an array
of categories which consist of name-value pairs of data samples. Pie Chart and Bar Chart reports are considered
Snapshot reports. You must request a Snapshot report with the userAPIGetInstantDataReport method. The
reportId for this type of report is suffixed with -S.
Cisco UCS Director REST Developer Guide, Release 5.1
100
Reports
Example of a Snapshot Report
Example of a Snapshot Report
{"categoryAxisName":null,
"valueAxisName":"Active vs Inactive",
"categories":[
{"categoryName":"",
"nameValuePairs":[
{"name":"Active VMs",
"value":"17"},
{"name":"Inactive VMs",
"value":"51"}]}]}
List of Available Cisco UCS Director Reports
In the following table, reports are grouped by context. The same report (with the same reportID) may be used
for different contexts, and so may appear in multiple locations in this list.
Note
Report IDs are always single strings without character spaces. Because some of these strings are very
long, they are broken across multiple lines within individual table cells below. If you perform an electronic
search for a full, exact reportId string, it may not return a result because the break inserts a character space;
search instead for a short unique string contained within the full reportId character string.
Context
Report Name
Report ID
Report Type
AWS-EC2 cloud
Summary
SUMMARY-V0
Summary
AWS-EC2 cloud
VMs
VMS-T0
Tabular
AWS-EC2 cloud
Images
IMAGES-T0
Tabular
AWS-EC2 cloud
Deleted VMs
DELETED-VMS-T0
Tabular
AWS-EC2 cloud
Memory
MEMORY-S0
Bar Chart
AWS-EC2 cloud
VPU
CPU-S0
Bar Chart
AWS-EC2 cloud
Disk
DISK-S0
Bar Chart
AWS-EC2 cloud
Trend: Memory
TREND-MEMORY-H0
Trend
AWS-EC2 cloud
Trend: CPU
TREND-CPU-H0
Trend
AWS-EC2 cloud
Trend: CPU Usage
TREND-CPU-USAGE-H0
Trend
AWS-EC2 cloud
Trend: Disk Reads &
Writes (bytes)
TREND-DISK-READS-&
-WRITES-(BYTES)-H0
Trend
AWS-EC2 cloud
Trend: Disk Reads &
Writes (ops)
TREND-DISK-READS-&
-WRITES-(OPS)-H0
Trend
Cisco UCS Director REST Developer Guide, Release 5.1
101
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
AWS-EC2 cloud
Trend: Disk Reads &
Writes (ops)
TREND-DISK-READS-&
-WRITES-(OPS)-H0
Trend
AWS-EC2 cloud
Trend: Network Usage
TREND-NETWORK-USAGE-H0
Trend
AWS-EC2 cloud
Groups with Most CPU
Usage
GROUPS-WITH-MOST
-CPU-USAGE-T0
Tabular
AWS-EC2 cloud
VMs With Most
Trend:CPU Usage
VMS-WITH-MOST -CPU-USAGE-T0 Tabular
AWS-EC2 cloud
VMs With Over-Utilized
CPU Usage
VMS-WITH-OVERUTILIZED-CPU-USAGE-T0
AWS-EC2 cloud
VMs With Under-Utilized VMS-WITH-UNDER
CPU Usage
-UTILIZED-CPU-USAGE-T0
Tabular
AWS-EC2 cloud
Volumes
VOLUMES-X1
Tabular with
Actions
AWS-EC2 cloud
Snapshots
SNAPSHOTS-X1
Tabular with
Actions
AWS-EC2 cloud
Summary
SUMMARY-V1
Summary
AWS-EC2 cloud
SP Status
SP-STATUS-T0
Tabular
AWS-EC2 vm
CPU Usage (percent)
CPU-USAGE-(PERCENT)-S0
Bar Chart
AWS-EC2 vm
Network In
NETWORK-IN-S0
Bar Chart
AWS-EC2 vm
Network Out
NETWORK-OUT-S0
Bar Chart
AWS-EC2 vm
Trend: CPU Usage
TREND-CPU-USAGE-H0
Trend
AWS-EC2 vm
Trend: Disk Reads &
Writes (bytes)
TREND-DISK-READS
-&-WRITES-(BYTES)-H0
Trend
AWS-EC2 vm
Trend: Disk Reads &
Writes (ops)
TREND-DISK-READS
-&-WRITES-(OPS)-H0
Trend
AWS-EC2 vm
Network Usage
NETWORK-USAGE-H0
Trend
catalog
Deployability Assessment
DEPLOYABILITY-ASSESSMENT-T45 Tabular
cloud
vDCs
VDCS-T0
Tabular
cloud
Events
EVENTS-T0
Tabular
Cisco UCS Director REST Developer Guide, Release 5.1
102
Tabular
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
cloud
Number of Events by
Severity
NUMBER-OF-EVENTS
-BY-SEVERITY-S0
Bar Chart
cloud
Groups WIth Most Number GROUPS-WITH-MOST
of VMs
-NUMBER-OF-VMS-T0
Tabular
cloud
vDCs With Most Number
of VMs
VDCS-WITH-MOST
-NUMBER-OF-VMS-T0
Tabular
cloud
vDCs With Most CPU
Usage
VDCS-WITH-MOST -CPU-USAGE-T0 Tabular
cloud
vDCs With Most Memory VDCS-WITH-MOST
Usage
-MEMORY-USAGE-T0
Tabular
cloud
vDCs With Most Disk
Usage
VDCS-WITH-MOST
-DISK-USAGE-T0
Tabular
cloud, vm
VM Action Requests
VM-ACTION-REQUESTS-X0
Tabular with
Actions
compute_chassis
Summary
SUMMARY-V50
Summary
compute_chassis
Servers
SERVERS-T50
Tabular
compute_chassis
Fan Modules
FAN-MODULES-T50
Tabular
compute_chassis
IO Modules
IO-MODULES-T50
Tabular
compute_chassis
Power Supply Units
POWER-SUPPLY-UNITS-T50
Tabular
compute_chassis
Events
EVENTS-T50
Tabular
compute_fbi
Summary
SUMMARY-V50
Summary
compute_fbi
Power Supply Units
POWER-SUPPLY-UNITS-T50
Tabular
compute_fbi
Fans
FANS-T50
Tabular
compute_fbi
Ethernet Ports
ETHERNET-PORTS-X50
Tabular with
Actions
compute_fbi
Fibre Channel Ports
FIBRE-CHANNEL-PORTS-X50
Tabular with
Actions
compute_fbi
Trend: Ethernet Ports Total TREND-ETHERNET-PORTS
Kilo Bytes
-TOTAL-KILO-BYTES
Transferred/Received
-TRANSFERRED/RECEIVED-H50
Trend
Cisco UCS Director REST Developer Guide, Release 5.1
103
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
compute_fbi
Trend: Fibre Channel Ports TREND-FIBRE-CHANNEL
Total Kilo Bytes
-PORTS-TOTAL-KILO-BYTES
Transferred/Received
-TRANSFERRED/RECEIVED-H50
Trend
compute_fbi
Trend: CPU Utilization
TREND-CPU-UTILIZATION-H50
Trend
compute_fbi
Trend: Memory
TREND-MEMORY-H50
Trend
compute_fbi
Events
EVENTS-T50
Tabular
compute_fbi_port
Port Summary
PORT-SUMMARY-V50
Summary
compute_server
Local Disks
LOCAL-DISKS-T50
Tabular
compute_server
Memory Units
MEMORY-UNITS-T50
Tabular
compute_server
Processor Units
PROCESSOR-UNITS-T50
Tabular
compute_server
Interface Cards
INTERFACE-CARDS-X50
Tabular with
Actions
compute_server
Service Request Details
SERVICE-REQUEST-DETAILS-T50
Tabular
compute_server
Trend: MotherBoard Input TREND-MOTHERBOARD
Trend
Current Received
-INPUT-CURRENT-RECEIVED-H50
compute_server
Trend: MotherBoard Input TREND-MOTHERBOARD
Voltage Received
-INPUT-VOLTAGE-RECEIVED-H50
Trend
compute_server
Trend: MotherBoard
Consumed Power
TREND-MOTHERBOARD
-CONSUMED-POWER-H50
Trend
compute_server
Trend: MotherBoard Sens
IO Temperature
TREND-MOTHERBOARD
-SENS-IO-TEMPERATURE-H50
Trend
compute_server
Trend: MotherBoard Sens
Rear Temperature
TREND-MOTHERBOARD
-SENS-REAR-TEMPERATURE-H50
Trend
compute_server
Trend: Memory Unit
Temperature
TREND-MEMORY-UNIT
-TEMPERATURE-H50
Trend
compute_server
Trend: Processor Unit
Current
TREND-PROCESSOR-UNIT
-CURRENT-H50
Trend
compute_server
Trend: Processor Unit
Temperature
TREND-PROCESSOR-UNIT
-TEMPERATURE-H50
Trend
compute_server
Summary
SUMMARY-V50
Summary
Cisco UCS Director REST Developer Guide, Release 5.1
104
Report ID
Report Type
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
compute_server
Events
EVENTS-T50
Tabular
compute_server
_adapter_unit
DCE Interfaces
DCE-INTERFACES-T50
Tabular
compute_server
_adapter_unit
HBAs
HBAS-T50
Tabular
compute_server
_adapter_unit
NICs
NICS-T50
Tabular
custom_actions
Add/Edit Tasks
ADD/EDIT-TASKS-X46
Tabular with
Actions
datacenter
Storage Accounts
STORAGE-ACCOUNTS-T51
Tabular
datacenter
Top 5 Volume Total-Used
Storage
TOP-5-VOLUME-TOTAL
-USED-STORAGE-T9999
Tabular
datacenter
Top 5 Lun Total-Used
Storage
TOP-5-LUN-TOTAL-USED
-STORAGE-T9999
Tabular
datacenter
Summary
SUMMARY-V51
Summary
datacenter
Volumes: Total vs Used
VOLUMES-TOTAL-VS-USED-S51
Bar Chart
datacenter
LUNs: Total vs Used
LUNS-TOTAL-VS-USED-S51
Bar Chart
datacenter
Aggregates: Free vs Used
AGGREGATES-FREE-VS -USED-S51 Pie Chart
datacenter
UCSM Accounts
UCSM-ACCOUNTS-X50
Tabular with
Actions
datacenter
Chassis
CHASSIS-T50
Tabular
datacenter
Fabric Interconnects
FABRIC-INTERCONNECTS-T9999
Tabular
datacenter
Server Pools
SERVER-POOLS-T9999
Tabular
datacenter
Summary
SUMMARY-V50
Summary
datacenter
Service Profiles
SERVICE-PROFILES-T9999
Tabular
datacenter
Processor Units
PROCESSOR-UNITS-T9999
Tabular
datacenter
Memory Units
MEMORY-UNITS-T9999
Tabular
datacenter
Local Disks
LOCAL-DISKS-T9999
Tabular
Cisco UCS Director REST Developer Guide, Release 5.1
105
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
datacenter
IO Modules
IO-MODULES-T9999
Tabular
datacenter
Managed Network
Elements
MANAGED-NETWORKELEMENTS-X52
Tabular with
Actions
datacenter
VTP Status
VTP-STATUS-T52
Tabular
datacenter
Private VLANs
PRIVATE-VLANS-T52
Tabular
datacenter
L2 Neighbors
L2-NEIGHBORS-T52
Tabular
datacenter
Port Profiles
PORT-PROFILES-T52
Tabular
datacenter
VM Network Details
VM-NETWORK-DETAILS-T52
Tabular
datacenter
Host Network Details
HOST-NETWORK-DETAILS-T52
Tabular
datacenter
VSANs
VSANS-T52
Tabular
datacenter
VLANs
VLANS-X52
Tabular with
Actions
datacenter
HP Accounts
HP-ACCOUNTS-X50
Tabular with
Actions
datacenter
DHCP Log
DHCP-LOG-T50
Tabular
datacenter
PXE Boot Requests
PXE-BOOT-REQUESTS-X50
Tabular with
Actions
global
Summary
SUMMARY-V0
Summary
global
Clouds
CLOUDS-T0
Tabular
global
vDCs
VDCS-T0
Tabular
global
Clusters
CLUSTERS-T0
Tabular
global
VMs
VMS-T0
Tabular
global
Host Node Status
HOST-NODE-STATUS-T0
Tabular
global
Host Node Inventory
HOST-NODE-INVENTORY-T0
Tabular
global
Resource Pools
RESOURCE-POOLS-T0
Tabular
global
Events
EVENTS-T0
Tabular
global
Images
IMAGES-T0
Tabular
Cisco UCS Director REST Developer Guide, Release 5.1
106
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
global
Deleted VMs
DELETED-VMS-T0
Tabular
global
System Health
SYSTEM-HEALTH-T30
Tabular
global
Active VM Distribution
ACTIVE-VM-DISTRIBUTIONBY-CLOUD-S0
Pie Chart
global
Active VMs Public vs
Private By Clouds
ACTIVE-VMS-PUBLIC-VS
-PRIVATE-CLOUDS-S0
Pie Chart
global
Memory
MEMORY-S0
Bar Chart
global
CPU
CPU-S0
Bar Chart
global
Disk
DISK-S0
Bar Chart
global
Private Cloud Storage
Capacity
PRIVATE-CLOUD-STORAGE
-CAPACITY-S1
Pie Chart
global
Private Cloud Free Storage PRIVATE-CLOUD-FREE-STORAGE-S1 Pie Chart
global
Private Cloud Used Storage PRIVATE-CLOUD-USED-STORAGE-S1 Pie Chart
global
Storage Capacity Per
Storage Type
STORAGE-CAPACITY-PERSTORAGE-TYPE-S1
global
Used Storage Per Storage
Type
USED-STORAGE-PER-STORAGE-TYPE-S1 Bar Chart
global
Free Storage Per Storage
Type
FREE-STORAGE-PER-STORAGE-TYPE-S1 Bar Chart
global
Top 5 Datastores Most
Used
TOP-5-DATASTORES-MOST-USED-S1 Bar Chart
global
Top 5 Datastores Least
Used
TOP-5-DATASTORES-LEAST-USED-S1 Bar Chart
global
Number of Events
NUMBER-OF-EVENTS-S0
global
Trend: Number of Host
Nodes
TREND-NUMBER-OF-HOST-NODES-H0 Trend
global
Trend: Memory
TREND-MEMORY-H0
Trend
global
Trend: Storage Capacity,
Used & Free
TREND-STORAGE-CAPACITY,
-USED-&-FREE-H1
Trend
global
Trend: CPU
TREND-CPU-H0
Trend
Bar Chart
Bar Chart
Cisco UCS Director REST Developer Guide, Release 5.1
107
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
global
All VMware Activity
ALL-VMWARE-ACTIVITY-T0
Tabular
global
Summary
SUMMARY-V1
Summary
global
SP Status
SP-STATUS-T0
Tabular
global, cloud
VMs Active vs Inactive
VMS-ACTIVE-VS-INACTIVE-S0
Bar Chart
global, cloud
Trend: Number of VMs
TREND-NUMBER-OF-VMS-H0
Trend
global, cloud
Trend: VM Additions &
Deletions
TREND-VM-ADDITIONS-&
-DELETIONS-H0
Trend
global_admin
NetAppVolumesTable
NETAPPVOLUMESTABLE-T9999
Tabular
global_admin
NetAppVFilerVolumes
Table
NETAPPVFILERVOLUMES
TABLE-T9999
Tabular
global_admin
NetAppLunsTable
NETAPPLUNSTABLE-T9999
Tabular
global_admin
NetAppVFilerLunsTable
NETAPPVFILERLUNSTABLE-T9999 Tabular
global_admin
NetAppFilersTable
NETAPPFILERSTABLE-T9999
Tabular
global_admin
NetAppInitiatorGroups
Table
NETAPPINITIATORGROUPS
TABLE-T9999
Tabular
global_admin
NetAppVFilerInitiator
Groups Table
NETAPPVFILERINITIATOR
GROUPSTABLE-T9999
Tabular
global_admin
NetAppIPSpacesTable
NETAPPIPSPACESTABLE-T9999
Tabular
global_admin
NetAppVFilersTable
NETAPPVFILERSTABLE-T9999
Tabular
global_admin
NetAppAggregatesTable
NETAPPAGGREGATESTABLE-T9999 Tabular
global_admin
NetAppONTAPAccounts
Table
NETAPPONTAPACCOUNTS
TABLE-T9999
Tabular
global_admin
NetAppDFMAccounts
Table
NETAPPDFMACCOUNTS
TABLE-T9999
Tabular
global_admin
NetAppDFMFiler Table
NETAPPDFMFILERTABLE-T9999
Tabular
global_admin
NetAppONTAPFiler Table NETAPPONTAPFILERTABLE-T9999 Tabular
global_admin
NetAppONTAPvFilers
Table
Cisco UCS Director REST Developer Guide, Release 5.1
108
NETAPPONTAPVFILERS
TABLE-T9999
Tabular
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
global_admin
NetAppUnAssignedIP
SpacesTable
NETAPPUNASSIGNEDIPSPACES
TABLE-T9999
Tabular
global_admin
NetAppInterfacesTable
NETAPPINTERFACESTABLE-T9999 Tabular
global_admin
NetAppVLANPhysical
InterfacesTable
NETAPPVLANPHYSICALINTERFACES Tabular
TABLE-T9999
global_admin
NetAppInterfacesvFilers
Assigned Table
NETAPPINTERFACESVFILERS
ASSIGNEDTABLE-T9999
global_admin
NetAppDFMvFilersTable
NETAPPDFMVFILERSTABLE-T9999 Tabular
global_admin
NetAppDfmVolume
DatasetTable
NETAPPDFMVOLUMEDATASET
TABLE-T9999
Tabular
global_admin
NetAppDfmLUN
DatasetTable
NETAPPDFMLUNDATASET
TABLE-T9999
Tabular
global_admin
NetAppDfmGroupTable
NETAPPDFMGROUPTABLE-T9999
Tabular
global_admin
NetAppDfmProvision
PolicyTable
NETAPPDFMPROVISIONPOLICY
TABLE-T9999
Tabular
global_admin
NetAppDfmStorage
ServiceTable
NETAPPDFMSTORAGESERVICE
TABLE-T9999
Tabular
global_admin
NetAppUnAssigned
DatasetTable
NETAPPUNASSIGNEDDATASET
TABLE-T9999
Tabular
global_admin
NetAppAssignedDatasetTable NETAPPASSIGNEDDATASET
TABLE-T9999
Tabular
global_admin
NetAppDatasetTable
NETAPPDATASETTABLE-T9999
Tabular
global_admin
NetAppDatasetMember
LUN Table
NETAPPDATASETMEMBER
LUNTABLE-T9999
Tabular
global_admin
NetAppReourcePoolTable NETAPPREOURCEPOOLTABLE-T9999 Tabular
global_admin
NetAppGroupAssigned
VFilersTable
NETAPPGROUPASSIGNED
VFILERSTABLE-T9999
Tabular
global_admin
Provisioning Policies
PROVISIONING-POLICIES-T48
Tabular
global_admin
Protection Policies
PROTECTION-POLICIES-T48
Tabular
global_admin
Storage Services
STORAGE-SERVICES-T48
Tabular
Tabular
Cisco UCS Director REST Developer Guide, Release 5.1
109
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
global_admin
vFiler Templates
VFILER-TEMPLATES-T48
Tabular
global_admin
OnCommand Datasets
ONCOMMAND-DATASETS-T48
Tabular
global_admin
OnCommand Groups
ONCOMMAND-GROUPS-T48
Tabular
global_admin
Resource Pool
RESOURCE-POOL-T48
Tabular
global_admin
UIMenuItemTable
UIMENUITEMTABLE-T9999
Tabular
global_admin
UIOperationTable
UIOPERATIONTABLE-T9999
Tabular
global_admin
Customer Organizations
CUSTOMER-ORGANIZATIONS-X23 Tabular with
Actions
global_admin
Customer Organizations
CUSTOMER-ORGANIZATIONS-T23 Tabular
global_admin
Customer Organizations
CUSTOMER-ORGANIZATIONS-T23 Tabular
global_admin
MSP Organizations
MSP-ORGANIZATIONS-X23
Tabular with
Actions
global_admin
MSP Organizations
MSP-ORGANIZATIONS-T23
Tabular
global_admin
Login Page Branding
LOGIN-PAGE-BRANDING-X23
Tabular with
Actions
global_admin
Login Page Branding
LOGIN-PAGE-BRANDING-T23
Tabular
global_admin
Login Users
LOGIN-USERS-X23
Tabular with
Actions
global_admin
Login Users
LOGIN-USERS-T23
Tabular
global_admin
Current Online Users
CURRENT-ONLINE-USERS-X23
Other
global_admin
Virtual Accounts
VIRTUAL-ACCOUNTS-X22
Tabular with
Actions
global_admin
Virtual Accounts
VIRTUAL-ACCOUNTS-T22
Tabular
global_admin
Physical Accounts
PHYSICAL-ACCOUNTS-X24
Tabular with
Actions
global_admin
Physical Accounts
PHYSICAL-ACCOUNTS-T24
Tabular
global_admin
Catalog
CATALOG-X40
Tabular with
Actions
Cisco UCS Director REST Developer Guide, Release 5.1
110
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
global_admin
UcsOrganizationTable
UCSORGANIZATION TABLE-T9999 Tabular
global_admin
UcsServerTable
UCSSERVERTABLE-T9999
global_admin
UcsServiceProfileTable
UCSSERVICEPROFILE TABLE-T9999 Tabular
global_admin
UcsServerPoolTable
UCSSERVERPOOLTABLE-T9999
Tabular
global_admin
UcsBootPolicyTable
UCSBOOTPOLICYTABLE-T9999
Tabular
global_admin
Data Centers
DATA-CENTERS-X24
Tabular with
Actions
global_admin
Data Centers
DATA-CENTERS-T24
Tabular
global_admin
Storage Policy
STORAGE-POLICY-X47
Tabular with
Actions
global_admin
Network Policy
NETWORK-POLICY-X47
Tabular with
Actions
global_admin
vHBA
VHBA-X47
Tabular with
Actions
global_admin
vNIC
VNIC-X47
Tabular with
Actions
global_admin
Placement Policy
PLACEMENT-POLICY-X47
Tabular with
Actions
global_admin
deviceZonesTable
DEVICEZONESTABLE-T9999
Tabular
global_admin
Vendor Validated Designs
VENDOR-VALIDATEDDESIGNS-X24
Tabular with
Actions
global_admin
HpServerTable
HPSERVERTABLE-T9999
Tabular
global_admin
Reports Customization
REPORTS-CUSTOMIZATION-X20
Tabular with
Actions
global_admin
Amazon Deployment
Policy
AMAZON-DEPLOYMENT-POLICY-X41 Tabular with
Actions
global_admin
Amazon Deployment
Policy
AMAZON-DEPLOYMENT-POLICY-T41 Tabular
global_admin
VMware Deployment
Policy
VMWARE-DEPLOYMENT-POLICY-X21 Tabular with
Actions
Tabular
Cisco UCS Director REST Developer Guide, Release 5.1
111
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
global_admin
VMware Deployment
Policy
VMWARE-DEPLOYMENT-POLICY-T21 Tabular
global_admin
Resource Allocation Policy RESOURCE-ALLOCATION-POLICY-X21 Tabular with
Actions
global_admin
Resource Allocation Policy RESOURCE-ALLOCATION-POLICY-T21 Tabular
global_admin
Rackspace Deployment
Policy
RACKSPACE-DEPLOYMENT-POLICY-X41 Tabular with
Actions
global_admin
Rackspace Deployment
Policy
RACKSPACE-DEPLOYMENT-POLICY-T41 Tabular
global_admin
KVM Deployment Policy
KVM-DEPLOYMENT-POLICY-X41
Tabular with
Actions
global_admin
KVM Deployment Policy
KVM-DEPLOYMENT-POLICY-T41
Tabular
global_admin
VMware Network Policy
VMWARE-NETWORK- POLICY-X44 Tabular with
Actions
global_admin
VMware Network Policy
VMWARE-NETWORK- POLICY-T44 Tabular
global_admin
Network Provisioning
Policy
NETWORK-PROVISIONINGPOLICY-X44
Tabular with
Actions
global_admin
Network Provisioning
Policy
NETWORK-PROVISIONINGPOLICY-T44
Tabular
global_admin
VLAN Pool Policy
VLAN-POOL-POLICY-X44
Tabular with
Actions
global_admin
VLAN Pool Policy
VLAN-POOL-POLICY-T44
Tabular
global_admin
Virtual Storage Catalog
VIRTUAL-STORAGECATALOG-X43
Tabular with
Actions
global_admin
Virtual Storage Catalog
VIRTUAL-STORAGE- CATALOG-T43 Tabular
global_admin
VMware Storage Policy
VMWARE-STORAGE- POLICY-X43 Tabular with
Actions
global_admin
VMware Storage Policy
VMWARE-STORAGE- POLICY-T43
Tabular
global_admin
VMware Storage Policy
VMWARE-SYSTEM-POLICY-X41
Tabular with
Actions
global_admin
VMware Storage Policy
VMWARE-SYSTEM-POLICY-T41
Tabular
Cisco UCS Director REST Developer Guide, Release 5.1
112
Report Type
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
global_admin
VMware Computing Policy VMWARE-COMPUTINGPOLICY-X42
Tabular with
Actions
global_admin
VMware Computing Policy VMWARE-COMPUTINGPOLICY-T42
Tabular
global_admin
KVM Computing Policy
KVM-COMPUTING-POLICY-X42
Tabular with
Actions
global_admin
KVM Computing Policy
KVM-COMPUTING-POLICY-T42
Tabular
global_admin
Cost Model
COST-MODEL-X41
Tabular with
Actions
global_admin
Cost Model
COST-MODEL-T41
Tabular
global_admin
Storage Tier Cost Model
STORAGE-TIER-COST-MODEL-X41 Tabular with
Actions
global_admin
Storage Tier Cost Model
STORAGE-TIER-COST- MODEL-T41 Tabular
global_admin
OS License
OS-LICENSE-X41
Tabular with
Actions
global_admin
OS License
OS-LICENSE-T41
Tabular
global_admin
Network Services Agents
NETWORK-SERVICES- AGENTS-X24 Tabular with
Actions
global_admin
Discovered Devices
DISCOVERED-DEVICES-X24
Tabular with
Actions
global_admin
Active Modules
ACTIVE-MODULES-X26
Tabular with
Actions
global_admin
Active Modules
ACTIVE-MODULES-T26
Tabular
global_admin
Modules
MODULES-X26
Tabular with
Actions
global_admin
Modules
MODULES-T26
Tabular
global_admin
Module Snapshots
MODULE-SNAPSHOTS-X26
Tabular with
Actions
global_admin
Module Snapshots
MODULE-SNAPSHOTS-T26
Tabular
global_admin
vmwareVSwitchTable
VMWAREVSWITCH TABLE-T9999
Tabular
Cisco UCS Director REST Developer Guide, Release 5.1
113
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
global_admin
portGroups
PORTGROUPS-T9999
Tabular
global_admin
Workflows
WORKFLOWS-X46
Tabular with
Actions
global_admin
User VM Action Policy
USER-VM-ACTION-POLICY-X46
Tabular with
Actions
global_admin
Context Workflow
Mapping
CONTEXT-WORKFLOWMAPPING-X46
Tabular with
Actions
global_admin
Templates
TEMPLATES-X46
Tabular with
Actions
global_admin
Workflow Schedules
WORKFLOW-SCHEDULES-X46
Tabular with
Actions
global_admin
Custom Approval Tasks
CUSTOM-APPROVAL-TASKS-X46
Tabular with
Actions
global_admin
License
LICENSE-X20
Tabular with
Actions
global_admin
tabularlov.system.advanced.property.report TABULARLOV.SYSTEM.ADVANCED. Tabular
PROPERTY.REPORT-T9999
global_admin
Change Records
CHANGE-RECORDS-T25
Tabular
global_admin
Application Categories
APPLICATION-CATEGORIES-X20
Tabular with
Actions
global_admin
System Tasks
SYSTEM-TASKS-X20
Tabular with
Actions
global_admin
System Tasks
SYSTEM-TASKS-T20
Tabular
global_admin
LDAP Integration
LDAP-INTEGRATION-X23
Tabular with
Actions
global_admin
LDAP Integration
LDAP-INTEGRATION-T23
Tabular
global_admin
Virtual Console Servers
VIRTUAL-CONSOLE-SERVERS-X24 Tabular with
Actions
global_admin
Triggers
TRIGGERS-X46
Tabular with
Actions
global_admin,
group
vDC
VDC-X45
Tabular with
Actions
Cisco UCS Director REST Developer Guide, Release 5.1
114
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
global_admin,
group
vDC Service Profiles
VDC-SERVICE-PROFILES-X45
Tabular with
Actions
global_admin,
group
Catalog
CATALOG-T40
Tabular
group
vDCs
VDCS-T14
Tabular
group
Port Groups
PORT-GROUPS-X14
Tabular with
Actions
group
vFilers
VFILERS-X15
Tabular with
Actions
group
Servers
SERVERS-X15
Tabular with
Actions
group
Service Profiles
SERVICE-PROFILES-X15
Tabular with
Actions
group
Service Requests
SERVICE-REQUESTS-X10
Tabular with
Actions
group
Archived Service Requests ARCHIVED-SERVICEREQUESTS-X10
Tabular with
Actions
group
Users
USERS-X13
Tabular with
Actions
group
VMs
VMS-T14
Tabular
group
Resource Limits
RESOURCE-LIMITS-T13
Tabular
group
Summary
SUMMARY-V13
Summary
group
Top 5 Failure Reasons
TOP-5-FAILURE-REASONS-T10
Tabular
group
Trend: Network Usage
TREND-NETWORK-USAGE-H14
Trend
group
Trend: CPU Usage
TREND-CPU-USAGE-H14
Trend
group
Trend: Disk Usage
TREND-DISK-USAGE-H14
Trend
group
Trend: Consolidated
Resource Usage
TREND-CONSOLIDATEDRESOURCE-USAGE-H14
Trend
group
VMs Active vs Inactive
VMS-ACTIVE-VS-INACTIVE-S13
Bar Chart
Cisco UCS Director REST Developer Guide, Release 5.1
115
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
group
VLANs
VLANS-X15
Tabular with
Actions
group
Resource Accounting
RESOURCE-ACCOUNTING-T12
Tabular
group
Resource Accounting
Details
RESOURCE-ACCOUNTING-DETAILS-T12 Tabular
group
Chargeback
CHARGEBACK-T12
Tabular
group
Resource Accounting
Details
RESOURCE-ACCOUNTINGDETAILS-T85
Tabular
group
Chargeback
CHARGEBACK-T85
Tabular
group
Current Month Summary
CURRENT-MONTH-SUMMARY-V12 Summary
group
Previous Month Summary PREVIOUS-MONTH-SUMMARY-V12 Summary
group
Current Month Cost
Summary
CURRENT-MONTH-COSTSUMMARY-S12
Pie Chart
group
Previous Month Cost
Summary
PREVIOUS-MONTH-COSTSUMMARY-S12
Pie Chart
group
Current Month Top 5
Applications
CURRENT-MONTH-TOP-5
-APPLICATIONS-S12
Pie Chart
group
Previous Month Top 5
Applications
PREVIOUS-MONTH-TOP-5
-APPLICATIONS-S12
Pie Chart
group
Trend: Budget Spending
TREND-BUDGET-SPENDING-H12
Trend
group
Trend: Total Cost
TREND-TOTAL-COST-H12
Trend
group
Trend: VM Cost
TREND-VM-COST-H12
Trend
group
Trend: CPU Cost
TREND-CPU-COST-H12
Trend
group
Trend: Memory Cost
TREND-MEMORY-COST-H12
Trend
group
Trend: Network Cost
TREND-NETWORK-COST-H12
Trend
group
Payment Information
PAYMENT-INFORMATION-X10
Tabular with
Actions
group
Customer Funds
CUSTOMER-FUNDS-X10
Tabular with
Actions
Cisco UCS Director REST Developer Guide, Release 5.1
116
Reports
List of Available Cisco UCS Director Reports
Context
Report Name
Report ID
Report Type
group
Resource Accounting
Details
RESOURCE-ACCOUNTINGDETAILS-T10
Tabular
hostnode
Summary
SUMMARY-V0
Summary
hostnode
VMs
VMS-T0
Tabular
hostnode
Events
EVENTS-T0
Tabular
hostnode
Deleted VMs
DELETED-VMS-T0
Tabular
hp, datacenter
ILO Servers
ILO-SERVERS-X50
Tabular with
Actions
hp_server
Server NICs
SERVER-NICS-T50
Tabular
hp_server
Server Memory
SERVER-MEMORY-T50
Tabular
hp_server
Server Processor
SERVER-PROCESSOR-T50
Tabular
hp_server
Server Slots
SERVER-SLOTS-T50
Tabular
HyperV cloud
Trend: Number of Host
Nodes
TREND-NUMBER-OF- HOST
-NODES-H0
Trend
HyperV cloud
Trend: Memory
TREND-MEMORY-H0
Trend
HyperV cloud
Trend: CPU
TREND-CPU-H0
Trend
HyperV cloud
Summary
SUMMARY-V0
Summary
HyperV cloud
Clusters
CLUSTERS-T0
Tabular
HyperV cloud
Host Node Status
HOST-NODE-STATUS-T0
Tabular
HyperV cloud
Host Node Inventory
HOST-NODE-INVENTORY-T0
Tabular
HyperV cloud
VMs
VMS-T0
Tabular
HyperV cloud
Deleted VMs
DELETED-VMS-T0
Tabular
HyperV cloud
Data Stores
DATA-STORES-T0
Tabular
HyperV cloud
Images
IMAGES-T9999
Tabular
HyperV cloud
Memory
MEMORY-S0
Bar Chart
HyperV cloud
CPU
CPU-S0
Bar Chart
Cisco UCS Director REST Developer Guide, Release 5.1
117
Reports
Using the List of Available Reports
Context
Report Name
Report ID
Report Type
HyperV cloud
Disk
DISK-S0
Bar Chart
HyperV cluster
Summary
SUMMARY-V0
Summary
HyperV cluster
Host Node Status
HOST-NODE-STATUS-T0
Tabular
HyperV cluster
Host Node Inventory
HOST-NODE-INVENTORY-T0
Tabular
HyperV cluster
VMs
VMS-T0
Tabular
HyperV cluster
Events
EVENTS-T0
Tabular
HyperV hostnode
CPU Usage
CPU-USAGE-S0
Bar Chart
HyperV hostnode
CPU Usage(Mhz)
CPU-USAGE(MHZ)-S0
Bar Chart
HyperV hostnode
Memory Usage
MEMORY-USAGE-S0
Bar Chart
Using the List of Available Reports
If you know the context of the report you want to get, you can use the report type information in the following
List of Available Cisco UCS Director Reports, on page 101to find the reportId to use in your request, and
even to determine which operation you should use, if you are unsure. In many cases, you can use the List of
Available Reports to construct an API request that fetches the report data you need.
Useful examples of reports, including VM and WorkFlowStatus reports, are provided elsewhere in the REST
API documentation. See: Reports and JSON Object Response Samples, on page 90.
Note
If you require additional data for your API request, refer to the Report Metadata provided by Cisco UCS
Director. See Enabling the Developer Menu Options, on page 12.
Cisco UCS Director REST Developer Guide, Release 5.1
118
CHAPTER
8
Additional REST API Resources
This chapter contains the following sections:
• Creating and Testing API Request Code using XML or Java, page 119
• Importing a Custom Task, page 120
Creating and Testing API Request Code using XML or Java
Before You Begin
To use this procedure, you must have the Enable Developer Menu option selected, and you must already
have navigated to the REST API Browser tab so that the list of tasks appears. Refer to the procedure for
accessing the REST API Browser, which is provided earlier in this section.
A window featuring three tabs should appear, with the API Examples tab open, showing some API data
corresponding to your task selection. The HTTP Method and URL information should appear.
Procedure
Step 1
Step 2
Step 3
Open a task folder to display the API information, then double-click a row showing an API resource and
operation that interests you.
If the operation and resource support the creation of new API requests, the API Examples tab will provide
data entry boxes for the parameter values that you will be able to use to construct a successful request. If no
data entry box appears, then you cannot enter data to create a new API request using this procedure. If the
API Examples tab shows API data corresponding to and confirming your selection, and the HTTP Method
and URL information appear, you can use the data provided.
If a data entry box displays Select..., click it to open data search-filters and use them to sort out and select the
data you need to enter.
As necessary, define a new API request by providing the missing data (API request parameters) in theAPI
Examples tab. Refer to the Details tab for useful information about parameters.
Cisco UCS Director REST Developer Guide, Release 5.1
119
Additional REST API Resources
Importing a Custom Task
a) You can click Generate XML to see a sample of the request.
Step 4
Step 5
Step 6
Open the Details tab to see the API resource and operation name, and to see data formats and definitions for
the request and the response data.
To execute the API with the REST API Browser, click the Details tab, then click Submit.
Important
You can also use the API Examples and Sample Java Code tabs to submit API examples and
sample Java code.
To see Java code that is equivalent to your REST API request code, open the Sample Java Code tab.
What to Do Next
Keep a copy of code used to submit a successful, useful API request, and use it in your application where
appropriate.
Importing a Custom Task
Procedure
Step 1
Encode the .wfdx file of the custom task to an encoded script. For example, the HostandVMPerf.wfdx file.
To encode the .wfdx file, do the following:
a) Open the .wfdx file with a Text Editor or Notepad.
b) Copy the content of the .wfdx file and paste it to the Text to be encoded or decoded text box in the URL
Encoder/Decoder.
c) From the drop-down list, choose UTF-8.
d) Click Url Encode.
The XML is encoded to the required format to be passed through the RESTClient add-on.
Step 2
Step 3
Step 4
Invoke the RestClient add-on in the Mozilla FireFox browser.
From the Method drop-down list, choose POST.
In the URL field, enter the server URL.
The format of the server URL is: http://<server-ip-address>/cloupia/api-v2/customtaskImport.
Step 5
Enter the REST API Access key of the required server in the API request header.
For the procedure to get an API access key, see the Generating an API Access Key, on page 11.
Step 6
Step 7
Paste the encoded script in the Body field.
Add the following tags to the beginning of the encoded script:
<cuicOperationRequest>
<operationType>CREATE</operationType>
<payload>
<![CDATA[
<customtaskImport>
<importText>
---------- encoded text-------
Cisco UCS Director REST Developer Guide, Release 5.1
120
Additional REST API Resources
Importing a Custom Task
Step 8
Add the following tags to the end of the encoded script:
</importText>
</customtaskImport>
]]>
</payload>
</cuicOperationRequest>
Step 9 Click Send.
Step 10 Click the Response Headers and Response Body (Raw) tabs to verify the response header and body.
The imported custom task appears in Cisco UCS Director. Log in to Cisco UCS Director by hostname or IP
address and choose Policies > Orchestration. Click the Custom Workflow Tasks tab. The imported custom
task appears in the Custom Workflow Tasks table, and is available for use in the workflow.
Cisco UCS Director REST Developer Guide, Release 5.1
121
Additional REST API Resources
Importing a Custom Task
Cisco UCS Director REST Developer Guide, Release 5.1
122
CHAPTER
9
About the Java API
This chapter contains the following sections:
• Java API Examples, page 123
• Java Example: userAPIGetMyLoginProfile, page 123
• Java Example: userAPIGetAllVDCs, page 124
Java API Examples
Cisco UCS Director provides a Java API that provides most of the capabilities of the Cisco UCS Director
REST APIs. The source code and compiled classes are part of the Cisco UCS Director SDK, which includes
Javadocs.
To run the samples provided with the SDK, use ExampleClient.sh or ExampleClient.bat.
Automatically Generated Cisco UCS Director Java API Code
The REST API Browser enables you to generate usable Java API code. The code integrates parameters based
on your implementation of Cisco UCS Director, and in most cases, it can be used immediately to perform
API operations. For details, see Using the REST API Browser, on page 13.
Java Example: userAPIGetMyLoginProfile
The following sample shows snippets of code used by a Java Client.
ExampleClient.bat SERVER KEY userAPIGetMyLoginProfile
{
userId: "exampleUser",
firstName: "John",
lastName: "Doe",
email: "[email protected]",
groupName: "exampleGroup",
role: "Regular"
}
Cisco UCS Director REST Developer Guide, Release 5.1
123
About the Java API
Java Example: userAPIGetAllVDCs
Java Example: userAPIGetAllVDCs
The following sample shows snippets of code used by a Java Client.
ExampleClient.bat SERVER KEY userAPIGetAllVDCs
{ rows: [
{
Cloud: "",
Group: "Default Group",
vDC: "Default vDC",
State: "Locked",
Total_VMs: 20,
Active_VMs: 18,
Custom_Categories: 0
},
{
Cloud: "Acme Private Cloud",
Group: "exampleGroup",
vDC: "exampleVDC",
State: "Ok",
Total_VMs: 10,
Active_VMs: 9,
Custom_Categories: 0
} ]}
Cisco UCS Director REST Developer Guide, Release 5.1
124
APPENDIX
A
Cisco UCS Director REST API SDK Bundle
This appendix contains the following sections:
• About the Cisco UCS Director REST API SDK Bundle, page 125
• Importing the SDK Bundle Project into the Eclipse IDE, page 126
About the Cisco UCS Director REST API SDK Bundle
The Cisco UCS Director REST API SDK Bundle is part of the Cisco UCS Director REST API. In addition
to documentation, such as development guides and a readme, the SDK Bundle provides examples that you
can use with the REST API. These examples include test cases and sample code that demonstrate the use of
the SDK classes.
The SDK Bundle is delivered in an archive file named ucsd-rest-api-sdk-v2.zip. This archive
includes the following components designed to assist you in developing applications with the REST API.
Development Guides
The development guides are contained in the DevGuides folder. They include the Cisco UCS Director REST
API Developer Guide and documentation about the test cases provided with the SDK Bundle.
REST API Javadocs
The Cisco UCS Director REST API Javadocs are contained in the docs folder. The Javadocs cover all classes
provided with the SDK Bundle.
JAR file
The ucsd-rest-api-sdk-v2.0.jar file is contained in the lib folder. This file is the archive of all
classes required for managing the Cisco UCS Director and other required libraries.
Example Test Cases and Sample Code
The example test cases and sample code are contained in the src folder. These tests cases and code demonstrate
the usage of the SDK classes in the ucsd-rest-api-sdk-v2.jar file. The classes are available in the
src\com\cisco\cuic\api\examples folder.
Cisco UCS Director REST Developer Guide, Release 5.1
125
Cisco UCS Director REST API SDK Bundle
Importing the SDK Bundle Project into the Eclipse IDE
Readme
The Readme contains the lists of all components included in the SDK Bundle. It is available at the top level
of the archive.
Rest-server.properties File
This file contains the properties used by the examples in the examples folder. It is available at the top level
of the archive.
Project file
The .project file enables you to import the SDK Bundle into the Eclipse IDE. This file is required for
development purposes. It is available at the top level of the archive.
Importing the SDK Bundle Project into the Eclipse IDE
Before You Begin
Obtain the SDK Bundle archive and extract the contents to an appropriate folder.
Procedure
Step 1
In the Eclipse IDE, choose File > New > Java Project.
The Create a Java Project dialog box appears.
Step 2
Step 3
In the Project Name field, enter a name for the project.
Right click the project, and select Import.
The Import dialog box appears.
Step 4
Step 5
Step 6
Select File System and click Next.
Click Browse and navigate to the folder where you extracted the SDK Bundle.
Click Finish.
The Eclipse IDE displays the SDK Bundle project on the Project Explorer tab.
Cisco UCS Director REST Developer Guide, Release 5.1
126