Chapter 1. New and Changed Information for this Release

New and Changed Information

Chapter 2. Getting Started with Cisco UCS Director Open Automation

Cisco UCS Director Open Automation

Recommended Tools

Setting up Eclipse

Downloading the Open Automation SDK Bundle

Importing the Cisco UCS Director Open Automation SDK Project into the Eclipse IDE

Using EGit to Import the Open Automation SDK Bundle

Installing EGit Plug-In in Eclipse

Importing the Open Automation SDK Bundles into Eclipse

Upgrading Your Connector to the Current Release

Modules

Guidelines for Developing a Module

Creating a Module

Understanding the module.properties File

Packaging the Module

Deploying the Module on Cisco UCS Director

Preface

Audience

Conventions

Related Documentation

Documentation Feedback

Obtaining Documentation and Submitting a Service Request

Copyright Page

Chapter 1. New and Changed Information for this Release

- New and Changed Information

New and Changed Information

The following table provides an overview of the significant changes to this guide for the current release. The table does not provide an exhaustive list of all changes, or of all new features in this release.

New Features and Changed Behavior in Cisco UCS Director Open Automation, Release 5.5

Feature

Description

Where Documented

Download the open automation SDK bundle

Download the open automation SDK bundle from Cisco UCS Director.

Downloading the Open Automation SDK Bundle

Using EGit to import the open automation SDK bundle

Import the open automation SDK bundle from the Git repository into Eclipse.

Using EGit to Import the Open Automation SDK Bundle

Chapter 2. Getting Started with Cisco UCS Director Open Automation

- Cisco UCS Director Open Automation

- Upgrading Your Connector to the Current Release

- Modules

Cisco UCS Director Open Automation

You can use the Cisco UCS Director Open Automation tools to develop and integrate your own Cisco UCS Director features as modules. You can customize modules to meet your unique needs.

Using the module, you can perform the following functions:

- Develop your own Cisco UCS Director reports and report actions

- Inventory your devices

- Track changes made to the system through your module

- Develop tasks that can be used for workflows

- Develop and schedule repeatable tasks

- Set up new resource limits

The Open Automation SDK bundle includes code samples that provide models, examples, and comments. You can download the SDK bundle with the sample code from Cisco DevNet.

- Recommended Tools

- Setting up Eclipse

- Downloading the Open Automation SDK Bundle

- Importing the Cisco UCS Director Open Automation SDK Project into the Eclipse IDE

- Using EGit to Import the Open Automation SDK Bundle

Recommended Tools

We recommend you to use the following tools:

- Java version 1.8

- Eclipse (can be downloaded from www.eclipse.org)

Setting up Eclipse

Before You Begin

Java Runtime Environment (JRE) 1.8 is required.

Step 1

In Eclipse, click the Cisco UCS Director Open Automation SDK. Right-click and choose Properties.

Step 2

Set the Java Compiler to compile against 1.8 and click OK.
Note:
Make sure that you include the Cisco UCS Director Open Automation SDK jar files in your class path. Also make sure that your project setup mirrors the setup provided in the Open Automation SDK sample.

Downloading the Open Automation SDK Bundle

The Cisco UCS Director SDK binaries can be downloaded from the software download area or the DevNet site. Also, an admin user can download the SDK binaries from Cisco UCS Director.

Step 1

Log in to Cisco UCS Director.

Step 2

On the menu bar, choose Administration > Downloads.
The following files are displayed:

- REST API SDK—cucsd-rest-api-sdk-bundle.zip

- PowerShell Console—console.exe

- Open Automation SDK—cucsd-open-auto-sdk-bundle.zip

- Custom Tasks Script Samples—cucsd-cloupia-script-bundle.zip

Step 3

Choose the cucsd-open-auto-sdk-bundle.zip file and click Download. The file is downloaded to the default download location.

Importing the Cisco UCS Director Open Automation SDK Project into the Eclipse IDE

The following instructions describe how to import the Open Automation SDK bundle into Eclipse. Follow the instructions provided for your development environment, if you do not use Eclipse.

Step 1

Download the Open Automation SDK bundle from the Cisco.com download site or from Cisco DevNet. Extract the SDK bundle and save the sample SDK project zip file in to your file system.

Step 2

Launch Eclipse.

Step 3

Choose File > Import.

Step 4

In the Import dialog box, choose General > Existing Projects into Workspace.

Step 5

Click Next.

Step 6

Choose Select root directory and browse to the location where you extracted the project.

Step 7

Click Finish.
The project is automatically compiled.

Using EGit to Import the Open Automation SDK Bundle

Git with Eclipse (EGit) is an Eclipse plug-in to use the distributed version control system Git. EGit develops a connector plug-in in IDE to import the open automation SDK bundle into the IDE.

Most Eclipse IDE downloaded from the www.Eclipse.org site contains support for Git in their default configuration. If the Git functionality is missing in your Eclipse IDE installation, you can install it through the Eclipse installation manager. For more information on how to install the EGit plug-in, see the Installing EGit Plug-In in Eclipse.

- Installing EGit Plug-in into Eclipse

- Importing SDK files into Eclipse

- Installing EGit Plug-In in Eclipse

- Importing the Open Automation SDK Bundles into Eclipse

Installing EGit Plug-In in Eclipse

Step 1

Log in to Eclipse.

Step 2

Choose Help > Install New Software.
The Install window appears.

Step 3

Click the Add button available near the Work with field. The Add Site window appears.

Step 4

Enter the repository location name.

Step 5

In the Location field, copy and paste the following URL: http://download.eclipse.org/egit/updates/.

Step 6

Click OK to add the repository location. The Eclipse Git Team Provider and JGit package appears.

Step 7

Check the Eclipse Git Team Provider (Incubation) check box.

Step 8

(Optional)Check the JGit (Incubation) check box.

Step 9

Click Next. The packages that are chosen for installation appear for verification.

Step 10

Click Next.

Step 11

Click I accept the terms of the license agreement.

Step 12

Click Finish. All the necessary dependencies and executable are downloaded and installed.

Step 13

Accept the prompt to restart Eclipse.

What to Do Next

Import the open automation SDK bundle from the Git repository into Eclipse and run the SDK bundle.

Importing the Open Automation SDK Bundles into Eclipse

Before You Begin

Ensure that you have a Git account. If you do not have a Git account, signup for a new account in GitLab.com.

Step 1

Log in to Eclipse.

Step 2

In the Java perspective, right-click in the Package Explorer pane and click Import.

Step 3

Expand Git and click Projects from Git.

Step 4

Click Next.

Step 5

Click Clone URI.

Step 6

In the Import Projects from Git window, perform the following operations:

1. In the URI field, enter the location of the source repository.
Enter one of the following source repository locations according to the requirement:

- Repository location for the sample code is https://gitlab.com/CUCSDSDK/OpenAutomationSample.git.

- Repository location for the storage module is https://gitlab.com/CUCSDSDK/OpenAutomationStorage.git.

- Repository location for the network module is https://gitlab.com/CUCSDSDK/OpenAutomationNetwork.git.

- Repository location for the compute module is https://gitlab.com/CUCSDSDK/OpenAutomationCompute.git.

The host and repository path are autopopulated.

2. In the Authentication section, enter the Git account credential.

3. Click Next. The branches available in the repository appears.

4. Check the check box of the branches that you want to clone from the Git repository.

5. Click Next.

6. In the Directory field, enter the local destination where you want to save the open automation SDK.

7. From the Initial branch drop-down list, choose OpenAutomationSDK.
By default, the remote name is set as origin.

8. Click Finish.

The open automation SDK bundle is imported into Eclipse. You can view the SDK bundle in the project explorer.

Upgrading Your Connector to the Current Release

Cisco UCS Director uses a connector to collect the inventory of the other vendor devices for managing those devices.
For more information on upgrading, refer the Cisco UCS Director Upgrade Guide.

Modules

A module is the top-most logical entry point into Cisco UCS Director.

A module can include the following components:

Component

Description

Task

A Workflow Task that can be used while defining a Workflow.

Reports

Reports that appear in the Cisco UCS Director UI. Reports may or may not contain action buttons.

Trigger

A condition that, once satisfied, can be associated with some action. Examples: shutdown VM, start VM, and so on.

- Guidelines for Developing a Module

- Creating a Module

- Packaging the Module

- Deploying the Module on Cisco UCS Director

Guidelines for Developing a Module

When you develop a new module to support new devices, ensure that:

- You develop a module for a device family so that you have only one module to support all these devices.

- You do not develop a module that supports both a network switch and a storage controller; instead, split them into two modules. Ideally, a module must support only devices within the same category, so that a module can handle only compute devices, network devices, or storage devices.

- The devices supported by the same module must be similar.

- The same device may come in different models that are meant for distinct purposes, and it may be appropriate to use different modules to support them.

Creating a Module

The following items must be in place for your custom module to work:

- A class extending AbstractCloupiaModule.

- Override the OnStart method in the Module Class that extends the AbstractCloupiaModule.

- A .feature file specifying your dependent jars and module class.

- A module.properties file is required in the custom module.

Before You Begin

Refer to FooModule in the sample project of the open automation SDK bundle.

Step 1

Extend the AbstractCloupiaModule class and register all your custom components in this class.

Step 2

Create a .feature file that specifies the dependent jars and module class. This file must end with an extension of .feature; see foo.feature for reference. The best practice is to name this file with your module ID. For more details about the .feature file, see Packaging the Module.

Step 3

Add the necessary custom jar files to the lib folder.

Step 4

Package the properties file at the root level of your module jar. Cisco UCS Director provides you with a properties file for validation purposes. The SDK sample provides you with a build file that handles the packaging process.
Note:
The content of the module.properties file is described in Understanding the module.properties File.

Step 5

In the module.properties file, replace the moduleID with the ID of the custom module.

Step 6

From the Eclipse IDE package explorer, right-click the build.xml file and run the ANT target build. This action generates the module zip file and save the file to the base directory of your project.

- Understanding the module.properties File

Understanding the module.properties File

The module.properties file exposes the module to the platform runtime. This file defines certain properties of the module.

Here is a sample module.properties file:

moduleID=foo
version=1.0
ucsdVersion=5.4.0.0
category=/foo
format=1.0
name=Foo Module
description=UCSD Open Automation Sample Module
contact=support@cisco.com
key=5591befd056dd39c8f5d578d39c24172

The contents are described in the following table:

New Module.Properties (module.properties)

Name

Description

moduleID

The unique identifier for the module. This property is mandatory.

Example:

moduleID=foo
Tip:
The recommended best practice is to restrict this ID to a string of 3 to 5 lowercase ASCII alphabet characters.

version

The current version of your module. This property is mandatory.

Example:

version=1.0

ucsdVersion

The version of Cisco UCS Director designed to support your module (with which your module works best). This property is mandatory.

Example:

ucsdVersion=5.4.0.0

category

The path (/location) where all your tasks must be placed. This property is mandatory.

Example:

category=/foo
Note:
Category is the full path to the location where your tasks are placed. If the tasks module is not validated, the path is set under Open Automation Community Tasks/Experimental. If the tasks module is validated, the tasks are placed anywhere relative to the root folder. For example, you can use /Physical Storage Tasks/foo, so that, the tasks are under that folder or under /Open Automation Community Tasks/Validated/foo or under /foo. In theory, for this last case, there is a folder at root level called foo. This change enables developers to place tasks in categories that are not under open automation or in its categories.

format

The version of the format of this module. This property is mandatory. By default, 1.0 version is set for the custom module.

Example:

format=1.0
Restriction:
As of Cisco UCS Director Release 5.0.0.0, "1.0" is the only acceptable value here.

name

A user-friendly string that is used to identify your module in the open automation reports.

Example:

name=Foo Module

description

The user-friendly text that describes what your module does.

Example:

description=UCSD Open Automation Sample Module

contact

An email address that consumers of your module can use to request support.

Example:

contact=support@cisco.com

key

An encrypted key that the Cisco UCS Director Open Automation group provides for validating the module.

Example:

key=5591befd056dd39c8f5d578d39c24172

Note

If you attempt to modify the mandatory properties, the updates make your module invalidate. If you change any of the mandatory properties, you must request validation again. In contrast, the name, description, and contact values, which are not mandatory, can be modified or omitted without revalidation.

Packaging the Module

A module is packaged with all the necessary dependent JAR files, classes, and a module.properties file along with a .feature file. The .feature (pronounced "dot-feature") file is placed in the same folder as the root of the project. This file shows the JAR associated with this module and the path to the dependent JAR files. The name of the .feature file is <moduleID>-module.feature.

We recommend you to use the Apache ANT™ build tool that comes with Eclipse. You can also use any other build tool or create the build by yourself, but you have to deliver a package with the same characteristics as one built with ANT.

The following example shows the content of a .feature file:

{
jars:  [ "features/feature-chargeback.jar",
"features/chargeback/activation-1.1.jar",
"features/chargeback/axis2-jaxbri-1.5.6.jar",
"features/chargeback/bcel-5.1.jar",
"features/chargeback/jalopy-1.5rc3.jar",
"features/chargeback/neethi-2.0.5.jar",
"features/chargeback/antlr-2.7.7.jar",
"features/chargeback/axis2-jaxws-1.5.6.jar",]
features: [ "com.cloupia.feature.oabc.OABCModule" ]
}

From the build.xml file, run the ANT target build. This action generates the necessary zip file and save it to the base directory of your project. (This assumes that you are using the sample project as the base of your own project. Although using the sample project in this way is not recommended, it is the basis of this demonstration.)

If your module depends on JARs that are not provided with the sample source code, include the jars in the build.xml file to have them in the zip file.

The following example shows a module layout with a third-party JAR:

feature-oabc
feature oabc.jar
oabc
lib
flex
flex-messaging-common.jar
oabc.feature

The module jar and .feature are at the top level of the zip file. Place the third-party jars under the /moduleID/lib/ folder path. Although it is not required, the best practice is to place the third-party jars under the /moduleID/lib folder path, then any other sub directories you may want to add.

{
jars:  [ 'features/feature-oabc.jar", features/oabc/lib/flex-messaging-common.jar ],
features: [ "com.cloupia.feature.oabc.OABCModule" ]
}

References to the jar files must always start with features/. When you list the jars in the .feature file, ensure that the jars start with features/. This action enables you to include the path to the jar. The path of each jar must be the same path that is used in your zip file. The best practice is to lead with your module jar, followed by its dependencies, to ensure that your module gets loaded.

Deploying the Module on Cisco UCS Director

The Cisco UCS Director user interface provides Open Automation controls that you can use to upload and manage modules. Use these controls to upload the zip file of the module to Cisco UCS Director.

Note

For uploads, only the zip file format is supported.

Before You Begin

To enable or activate a module, restart the Cisco UCS Director services, for which you require shell admin access. You can get this access from your system administrator. To use the Cisco UCS Director Shell Menu as a shell administrator, you have to use SSH to access Cisco UCS Director, using the login shelladmin with the password that you got from the administrator. For the SSH access in a Windows system, use PuTTY; (see Click Here ); on a Mac, use the built-in SSH utility.

Step 1

In Cisco UCS Director, choose Administration > Open Automation.
The Modules table appears and displays the following columns:

Column

Description

ID

The ID of the module.

Name

The name of the module.

Description

The description of the module.

Version

The current version of the module. The module developer must determine how to administer versioning of the module.

Compatible

Displays which version of Cisco UCS Director best supports this module.

Contact

The contact information of the person responsible for technical support for the module.

Upload Time

The time at which the module is uploaded.

Status

The status of the module. The status includes: Enable, Disable, Active, and Inactive.

You can control whether a module is enabled or disabled. If enabled, Cisco UCS Director attempts to initialize the module; if disabled, Cisco UCS Director ignores the module. A module is set to the Active state only when Cisco UCS Director is able to successfully initialize the module without exception.
Note:
Active does not necessarily mean that everything in the module is working properly; it merely indicates that the module is up. Inactive means that when Cisco UCS Director tried to initialize the module, a severe error prevented it from doing so. Typical causes for the Inactive flag are: the module is compiled with the wrong version of Java, or a class is not included in the module.

Validated

Indicates whether the module is validated or not.

Step 2

Click Add to add a new module.
The Add Modules dialog box appears.

Step 3

Choose the module zip file from your local files and click Upload to upload the module zip file.

Step 4

Enable the module by choosing the module in the Modules table and clicking Enable.

Step 5

Activate the module by restarting Cisco UCS Director.

Step 6

In Cisco UCS Director, navigate to Administration > Open Automation and verify that the module status is Active.

Preface

- Audience

- Conventions

- Related Documentation

- Documentation Feedback

- Obtaining Documentation and Submitting a Service Request

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.

[ ]

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.

Note

Means reader take note. Notes contain helpful suggestions or references to material not covered in the document.

Caution

Means reader be careful. In this situation, you might perform an action that could result in equipment damage or loss of data.

Tip

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.

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

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: Click Here .

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: Click Here .

For a complete list of all C-Series documentation, see the Cisco UCS C-Series Servers Documentation Roadmap available at the following URL: Click Here .

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 ucs-director-docfeedback@cisco.com. We appreciate your feedback.

Obtaining Documentation and Submitting a Service Request

For information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gathering additional information, see What's New in Cisco Product Documentation.

To receive new and revised Cisco technical content directly to your desktop, you can subscribe to the What's New in Cisco Product Documentation RSS feed. RSS feeds are a free service.

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: Click Here . 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)