vCenter Orchestrator Blog: Configuration Elements revisited #vmware

vCenter Orchestrator Blog: Configuration Elements revisited:

What are Configuration Elements?

A configuration element is a list of attributes you can use to configure constants across a whole Orchestrator server deployment. That’s what the vCO documentation states. In other words, the configuration elements are the easiest way offered by vCO to organize and establish a set of constant values which will be accessible from any key element of vCO (workflows, policies and web views).

A configuration element is a vCO entity composed basically of a list of attributes which are defined by a name, a type, and (once it’s configured) a value. Moreover, configuration elements support versioning, user permissions and access rights like other vCO entities.

How to create Configuration Elements

The creation of configuration elements is detailed on the official documentation, so there’s no need to describe it here (see http://pubs.vmware.com/vsphere-50/topic/com.vmware.vsphere.vco_dev.doc_42/GUID1A027CCA-B462-4580-A7E5-F0431CF75C3A.html).

How to use Configuration Elements

As example let’s define a workflow with some inputs, attributes and a scripting block that require to access to some configuration element to get the value from its attributes. The sample workflow would be used to send e-mail notifications from vCO, for example when some external event occurs or some specific condition is satisfied.

So on the one hand the workflow “Send notification message” defines these inputs:

• To: the addressee of the notification (an e-mail address)


• Subject: the subject of the notification e-mail


• Body: the notification message itself

Also it contains this attribute:

• From: the sender of the notification (a default e-mail address)

And furthermore, before sending the notification the workflow attaches a predefined footer to the body of the e-mail.

On the other hand the configuration element “Email” defines these attributes:

• default_sender: the sender’s e-mail address, which will be different for different environments (e.g. development, integration or production)


• default_subject: the default subject of the notification e-mail


• default_footer: the default footer of the notification message, which may contain for example a legal notice text

Now let’s match the workflow elements with the configuration element attributes.

To set the value of an attribute
In that case it’s a workflow attribute but it’s exactly the same process for attributes of policies and web views.
You have to go to the General tab of the workflow in edit mode and select the option of linking the value of the attribute to a configuration element attribute. Then you choose the proper configuration element and the desired attribute.

Once you select the attribute it appears linked on the workflow’s attribute value.

In this way you linked the attribute “from” of the workflow to the value of the attribute “default_sender” of the configuration element “Email”. And after that you can use the attribute “from” like any other attribute inside the workflow.

To set the default value of an input parameter
The easiest way starts like setting the value of an attribute. You create an attribute called “default_subject” in the workflow and you link it to the value of the attribute “default_subject” of the configuration element “Email”. After that you go to the Presentation tab of the workflow in edit mode, select the input “subject” and add the property ”Default value”. Then you link the value of that property to the workflow attribute “default_subject” that you have just created.

Once you select the attribute it appears set on the “Default value” property value.

In this way you linked the input “subject” of the workflow to the value of the attribute “default_sender” of the configuration element “Email”.

To set the value of a variable inside a scripting block
The easiest way again starts like setting the value of an attribute. You create an attribute called “footer” in the workflow and you link it to the value of the attribute “default_footer” of the configuration element “Email”. After that you go to the “Schema” tab of the workflow in edit mode, select the Scriptable task element and add as a local input parameter the workflow attribute “footer”.

In this way you linked the scripting task input “footer” to the value of the attribute “default_footer” of the configuration element “Email”.

And once you have all the inputs of the Scriptable task element set properly you can actually write the code that will send the email (for example you could use the Mail plug-in and its EmailMessage object).

How to access Configuration Elements directly via scripting

The previous section describes how you can access to configuration elements via workflow attributes. That’s the easiest way but it has some minor drawbacks (or major if you use configuration elements a lot from your workflows). The two main drawbacks are:

• You must define an extra workflow attribute for each configuration element attribute that you want to use inside that workflow.


• You must set those workflow attributes as input parameters of each Scriptable task which you can get the attribute’s value from.

Alternatively, to avoid using extra workflow attributes, you can make us of a custom action that implements the logic for accessing to the proper configuration element attribute and getting its value. For example you can define an action like this, inside the module “org.company.mymodule”:

This action receives as parameters the path to find the configuration element, the name of the configuration element and the name of the attribute that you want to get from the configuration element. With that information the action tries to find the proper configuration element and return the value of the desired attribute.

The best is that you can invoke the action very easily from the presentation of a workflow (e.g. the case of the “Default value” property):

And you can invoke it also very easily from inside any Scriptable task without passing any extra input parameter to the Scriptable task itself:

The main benefits of that method are:

• You avoid the extra workflow attributes.


• You can invoke the action directly from workflow presentation elements.


• You can invoke the action directly from any Scriptable task.


• You could replace the logic of the action that gets the values from the configuration elements and use, for example, an external properties file or a database. Since you are writing the code here you have infinite possibilities.

And the only drawbacks are:

• You have to make sure that the action is included inside your package.


• You have to make sure that the proper configuration elements are included inside your package as well.

How to import/export Configuration Elements

You can import/export configuration elements in two ways:

• Import/export a single configuration element


• Import/export a set of configuration elements inside a package

The first way, import/export a single configuration element, is not very common. Here you probably want to import or export some specific configuration settings at development time to try them somewhere else. In that case, when you export the configuration element you get a file which contains the definition of the configuration element with both the list of attributes (names and types) and the values for those attributes. And when you import that file you create a new configuration element in vCO with again both the list of attributes and their values.

The second way, import/export a set of configuration elements inside a package, is the most usual because the configuration elements are used from other vCO entities. That’s why if you create a package containing a workflow, action, policy, or web view that uses an attribute from a configuration element, vCO automatically includes the configuration element in the package. Nevertheless there is a small difference with exporting a single configuration element, the difference is that in that case the values of the attributes are not exported! In another words, if you import a package containing a configuration element into another vCO, the configuration element attribute values are not set. This is because the configuration elements are supposed to define vCO server-specific settings. And for example, if you set the server-specific attributes directly in a workflow, the workflow probably won’t work with the same settings if you import it into a different server or environment. That’s why after importing a package that contains configuration elements you have to set them with values appropriate to the new server, otherwise some elements could fail (workflows, policies, etc.) because they might not find the attribute values that are required.

Conclusion

The configuration elements are a powerful mechanism offered by vCO to define constant values across multiple vCO entities. They are easy to create and easy to use in many common scenarios. And the only thing to be aware of is that when exporting and importing them inside a package, their attributes need to be set to the proper values of the new environment.