Adhering to certain certain practices when developing the different components of your Orchestrator plug-ins helps you to improve the quality of the plug-ins.

Table 1. Useful Practices in Plug-In Implementation

Component

Item

Description

General

Access to third-party API

Plug-ins should provide simplified methods for accessing the third-party API wherever possible.

Interface

Plug-ins should provide a coherent and standard interface for users, even when the API does not.

Action

Scripting objects

You should create actions for every creation, modification, deletion, and all other methods available for a scripting object.

Description

The description of an action should describe what the action does instead of how it works.

Scripting

When you use scripting to get the properties or methods of an object, you can check whether the object value is different from null or undefined.

Deprecation

If an action is deprecated, the comment or the throw statement should indicate the replacement action, or the action should call a new replacement action so that solutions that are built on the deprecated version of the action do not fail.

Workflow

User interface operations in the orchestrated technology

You should create a workflow for every operation that is available in the user interface of the orchestrated technology.

Description

The description of a workflow should describe what the workflow does instead of how it works.

Presentation property mandatory input

You must set the mandatory input property for all mandatory workflow inputs.

Presentation property default value

If you develop a workflow that configures an entity, the workflow presentation should load the default configuration values for this entity. For example, if you develop a workflow that is named Host Configuration, the presentation of the workflow must load the default values of the host configuration.

Presentation property Show in inventory

You must set the Show in inventory property so that you have contextual workflows on inventory objects.

Presentation property specify a root parameter

You should use this property in workflows when it is not necessary to browse the inventory from the tree root .

Workflow validation

You must validate workflows and fix all errors.

Object creation

All workflows that create a new object should return the new object as an output parameter.

Deprecation

If a workflow is deprecated, the comment or the throw statement should indicate the replacement workflow, or the deprecated workflow should call a new replacement workflow to ensure that solutions that are built on previous versions of the workflow do not fail.

Inventory

Host disconnection

If your inventory contains a connection to a host and this host becomes unavailable, you should indicate that the host is disconnected. You can do this either by renaming the root object by appending - disconnected or by removing the tree of objects underneath this object, in the same manner as the vCloud Director plug-in does.

Select value as list property

An inventory object must be selectable as treeview or a list.

Host manager

If the plug-in implements a host object for the target system, then a parent hostmanager root object should exist with properties for adding, removing, or editing host properties.

Getting or updating objects

If a query service is running on the orchestrated technology, you should use it for getting multiple objects.

Child discovery

If you need to retrieve child objects separately, the retrieval process must be multithreaded and non-blocking on a single error.

Orchestrator object change

All workflows that can change the state of an element in the inventory must update the inventory to avoid having objects out of synchronization.

External object change

You can use a notification mechanism to notify about changes in the orchestrated technology that occur as a result of operations that are performed outside of Orchestrator. In case such operations lead to removal of objects from the orchestrated technology, you must refresh the inventory accordingly to avoid failures or loss of data. For example, if a virtual machine is deleted from vCenter Server, the vCenter Server plug-in updates the inventory to remove the object of the removed virtual machine.

Finder object

Finder objects should have properties that can be used to differentiate objects. These are typically the properties that are present in the user interface.

Scripting object

Implementation

The equals method must be implemented to insure that == operation works on the same object as in some cases the object might have two instances.

Plug-in object properties

Objects that have parent objects should implement a parent property.

Plug-in object properties

Objects that have child objects should implement GET methods that return arrays of child objects.

Inventory objects

Inventory objects should be searchable with Server.find.

All inventory objects should be serializable so they can be used as input or output attributes in a workflow.

Constructor and methods

In most cases, scriptable objects should have either a constructor, or should be returned by other object attributes or methods.

Object ID

Objects that have an ID that is issued from an external system should use an internal ID to ensure that no ID duplication occurs when you are orchestrating more than one server.

Searching for objects

search or find methods should implement a filter so that the specified name or ID can be found instead of just all objects. For example, the Orchestrator server has a Server.FindForId method that allows finding a plug-in object by its ID. To do this, the method must be implemented for each findable object in the plug-in.

Trigger

If possible, triggers should be available for objects that change so that Orchestrator can have policies triggered on various events. For example, to determine when a new virtual machine is added, powered on, powered off, and so on, Orchestrator can monitor a trigger or an event in the vCenter plug-in on the Datacenter object.

Object properties

Objects that reside in other plug-ins should have properties for being easily converted from one plug-in object to another. For example, virtual machine objects need to have a moref (managed object reference ID).

Session manager

If you are connecting to a remote server that can have a different session, the plug-in should implement a shared session and a session per user.

Trigger

Trigger

All long operations and blocking methods should be able to start asynchronously with a task returned, and generate a trigger event on completion.

Enumerations

Enums

Enumerations for a given type should have an inventory object that allows selecting from the different values in the enumeration.

Logging

Logs

Methods should implement different log levels.

Versioning

Plug-in version

The plug-in version should follow standards and be updated along with the plug-in update.

API documentation

Methods

Methods that are described in the API documentation should never throw the exception no xyz method / property on an object. Instead, methods should return null when no properties are available and be documented with details when these properties are not available.

vso.xml

All objects, methods, and properties must be documented in vso.xml.