Managing Modules

This chapter contains the following sections:

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 as part of a Workflow.

Report

A report that appears in the Cisco UCS Director UI. Reports may (but are not required to) contain clickable actions.

Trigger

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

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.

Procedure

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.

The Open Automation SDK Bundle

The following files and directories are supplied in the Open Automation SDK Bundle. The listed files and directories are for an example Compute module. The Open Automation SDK Bundle also includes three other modules:

  • A Storage module

  • A Network module

  • A dummy example module called "foo."

These other modules have similar file and path names, differing only in the module type (compute, storage, network, or foo).

.classpath
The .classpath file lists the project's source directory, output directory, and classpath entries such as other projects in the workspace, JAR files, and so on.
.project
The .project file is maintained by the core Eclipse platform. It describes the project from a generic, plugin-independent Eclipse view.
src
The src directory contains the Java source files and internationalization resource bundles for compilation in Eclipse.
resources
The resources directory contains the images to build in the zip file.
compute.feature
The compute.feature file defines Open Automation feature metadata for the compute project.
lib
The lib directory contains libraries needed for Eclipse to compile the Java source files.
Poddefinition
This directory contains the pod.xmlfile.
cloud sense
The cloud sense directory contains the compute.report and compute.xml files. These files are required to build the zip file.
moresources
the moresources directory contains the .mo and .properties REST API files.

Understanding the module.properties File

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

Here is a sample module.properties file: 


moduleID=foo
version=1.0
ucsdVersion=6.5.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:

Table 1. New Module.Properties (module.properties)
Name Description

moduleID

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

Example:

moduleID=foo
Tip 

We recommend that you restrict this ID to a string of 3 to 5 lowercase alphabetic ASCII 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=6.5.0.0

category

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

Example:

category=/foo
Note 

The category parameter is the full path to the location where your tasks are placed. If the tasks module is not validated, the path is set to Open Automation Community Tasks/Experimental. If the tasks module is validated, the tasks are placed relative to the root folder. For example, you can use /Physical Storage Tasks/foo, /Open Automation Community Tasks/Validated/foo, or /foo. In the last case, there is a folder at root level called foo. This feature 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 

1.0 is the only acceptable value here.

name

A user-friendly string that identifies your module in the Open Automation reports.

Example:

name=Foo Module

description

A user-friendly description of 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

Modifying any mandatory properties invalidates your module. If you change any of the mandatory properties, you must request validation again. 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 classes, dependent JAR files, a module.properties file, and a .feature (pronounced "dot-feature") file. The .feature file is placed in the same folder as the root of the project. The .feature file shows the JAR associated with this module and the path to the dependent JAR files. The name of the .feature file is <moduleID>.feature.


Note

The package name must start with com.cloupia.feature. For example, Package com.cloupia.feature.oabc.OABCModule.

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" ]
}

Before you begin

We recommend that you use the Apache ANT build tool that comes with Eclipse. You can use any build tool or create the build by hand, but you must deliver a package with the same characteristics as one built with ANT.

SUMMARY STEPS

  1. If your module depends on JARs that are not provided with the sample source code, include the jars in the build.xml file so that they are packaged in the zip file.
  2. From the build.xml file, run the ANT target build.

DETAILED STEPS

  Command or Action Purpose
Step 1

If your module depends on JARs that are not provided with the sample source code, include the jars in the build.xml file so that they are packaged 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. We recommend that you put 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" ]
}

When you list the jars in the .feature file, ensure that the jars start with features/; this is mandatory. This convention 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. We recommend that you put your module jar first, followed by its dependencies, to ensure that your module loads.

Step 2

From the build.xml file, run the ANT target build.

The zip file is generated and saved to the base directory of your project. (We recommend that you create your own project directory for your module. For convenience, in this example we assume that the sample project is the base directory for your project.)

Deploying a 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

Only zip-formatted files can be uploaded using the Open Automation controls.

Before you begin

Acquire shell administrator access on the Cisco UCS Director VM. You can get this access from your system administrator. To use the Cisco UCS Director Shell Menu as a shell administrator, use SSH to access Cisco UCS Director, using the login shelladmin with the password that you got from the administrator.

For SSH access in a Windows system, use PuTTY (see http:/​/​www.putty.org/​). On a Mac, use the built-in terminal application's SSH utility.

Procedure

Step 1

Choose Administration > Open Automation.

Step 2

On the Open Automation page, click Modules.

The Modules page 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

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 was uploaded.

Status

The status of the module. Possible statuses are: Enabled, Disabled, 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 throwing an 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 missing from the module.

Validated

Indicates whether the module is validated or not.

Note 

To enable module activation on upload, ensure that the .feature file in your module is named after your module ID. For example: If moduleId is myFeatureName, then name your feature file myFeatureName.feature.

The Cisco UCS Director framework identifies and loads the .feature file by name, based on the module ID. If the name of the .feature file and the module ID are different, the .feature file does not load and the module is not activated. If you choose to give the module ID and the .feature file different names, you must restart Cisco UCS Director to activate the module.

Step 3

Click Add to add a new module.

The Add Modules dialog box appears.

Step 4

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

Step 5

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

Step 6

Wait while Cisco UCS Director activates the module.

Note 

Restarting Cisco UCS Director is not required to add and enable a module. Whereas, restarting Cisco UCS Director is required to disable, delete, or modify a module.

What to do next

Once the module is active, you can test the module.

Enabling Modules

Restarting Cisco UCS Director is no longer required to enable a module. However, you must restart Cisco UCS Director to modify, disable, or delete the new module.

An Open Automation module is enabled when you upload it to Cisco UCS Director. In previous versions of Cisco UCS Director, enabling a new Open Automation module required restarting the Cisco UCS Director server.

This is a short technical description of how a module is enabled when you upload the module to Cisco UCS Director.

When you upload an Open Automation module, the following events occur:

  • The module class and its resources are loaded using a new URLClassLoader. The new URLClassLoader is used for all classes loaded into the JVM.

  • Components of the Open Automation module are entered into various registries without restarting Cisco UCS Director.

  • The FeatureFileUploadEntry table is updated with the zip file name, timestamp, and status.

  • The system reloads the Pod Definition and Menu xml files, if they are available.

  • The system reloads the REST API resource files, recreates the MoPointer objects, and reloads the MoPointers into their respective collections.

  • The system recreates reports, workflow tasks, LOVs, system tasks, and other objects.

Deactivating a Module

To deactivate a module you must stop and restart the Cisco UCS Director services for your change to take effect.

Procedure

Step 1

Choose the module you need to deactivate in the Modules table, then click the Deactivate control.

Step 2

Stop and restart the Cisco UCS Director services. Follow the same procedure that you use after activating a module.