Workflow presentations

In this recipe, you will learn how to configure the input window (the presentation) and make it not only more user-friendly, but also reduce the amount of errors a user can enter. You will learn how to link values, hide inputs on conditions, and use predefined answers.

Getting ready

We just need a working Orchestrator, and you will need the rights to create new workflows and run them. We will work with the Orchestrator Client.

How to do it...

We will split this recipe into several sections. We will only create a presentation, not a working workflow.

Preparation

This preparation is just so that we can see some results:

  1. Create a new workflow using the following variables:

    Name

    Type

    Section

    Use

    number

    Number

    IN

    This is used for presentations

    string

    String

    IN

    This is used for presentations

    boolYesNo

    Boolean

    IN

    This is used for presentations

    input

    Array of Strings

    IN

    This is used for presentations

    text

    String

    IN

    This is used for presentations

    selection

    Array of String

    Attribute

    This fills this array with strings in the order: first, second, third...

    length

    Number

    Attribute

    This sets the value to 8

  2. Drag a log task onto the schema and assign all the variables to it. This is just so that the validation of the workflow will work.

Description

  1. Switch to Presentation and click on the first variable you see.
  2. Click on General and enter some text into Description.

Each element (including Steps and Groups) in the presentation has a General tab with a Description field. In this tab, you can enter text that will be displayed when the workflow runs. Each in-parameter automatically gets the name of the respective in-parameter in Description. You can, and probably should, change this to rather more meaningful description.

The description is interpreted as HTML, but not all tags work; however, <br>, <u>, <b>, <i>, <l>, and <a href> work quite well.

There is a way to include the content of a simple variable in Description of a variable. Just add the variable in the ${variableName} form.

In-parameter properties

You can add to each in-parameter a list of different properties to change the presentation. We cannot discuss all the properties in this recipe, just the basic ones (also see the recipe Linking actions in presentations in this chapter):

  1. Click on Presentation and then on one of the in-parameters.
  2. Click on Properties and then on Add property (the blue triangle icon).

    In-parameter properties

  3. You can now add various properties, which can differ for each variable. Go and try them out. A full table of properties can be found in the How it works... section of this recipe.
  4. Make some settings and run the workflow to see the results. I really recommend that you play with the properties.

Steps and groups

Steps and groups let you sort inputs by themes, such as one page for general parameters and one for advanced inputs:

  1. In Presentation, click on the root element presentation.
  2. Click on Create new Step (the paper icon).
  3. A new step is added to the end of the presentation tree. Give it a new name by double-clicking on the step, typing a new name into the textbox, and pressing Enter.
  4. Now, click on the boolean value and drag it under the new step. Move at least three more variables underneath this step.
  5. Create a second step and drag all the rest of the variables underneath it.
  6. Now, we add a group. Click on the first step you have created and then on Create Display Group (the yellow bar icon).
  7. A new group has been added; you can rename the group as required and press Enter.
  8. Now, drag variables under the group.
  9. Create another group and drag some other variables underneath it.
  10. Run the workflow. I would also recommend experimenting with this feature.

    Steps and groups

Hiding input values

To make the input window even more user-friendly, it's sometimes better to hide some inputs, steps, or groups if they are not used. For example, a step that contains advanced parameters can be hidden:

  1. In Presentation, make sure that the boolean in-parameter is the first one in the presentation tree.
  2. Add the Default value property to it and set it to True.
  3. Click on the second step you created and add the Hide parameter input property.
  4. Click on the pencil icon on the right of the hide property. A popup will appear; select the boolean variable and click on Accept. Note that the variable is now shown in the #[variableName] format. You can also enter directly the value as True or False. You can also always put an ! before the # of the variable in order to use a NOT.

    Hiding input values

  5. Repeat these steps to link a hide property to a group and to an in-parameter variable.
  6. Run the workflow. Change the boolean value to false and watch the results. All elements that have the hide-property will respond to the value change in the boolean value.

Basic linking

We actually have already used linking in the instruction to hide inputs; now we will explore it in more detail. Linking can help you create drop-down boxes or define default values:

  1. Click on Presentation and then select one of the string in-parameters.
  2. If you have not already done so, assign it the Maximum string length property.
  3. Now, click on the drop-down menu in front of Value and select the yellow arrows (dynamic binding). The box icon represents the static binding.
  4. You will see that the Value field changes. Click on the pencil icon (Help editing OGNL), and in the pop-up window, you will see all the variables (attributes and in-parameters) that can be used in this field. Select the number attribute and click on Accept.
  5. Select a string in-parameter in Presentation, assign it the Predefined answers property, and link it to the array of strings attributes.
  6. Run the workflow and test out the results.

    Basic linking

How it works...

The presentation section of a workflow allows us to change the general layout of the input window that a user encounters when they start the workflow. With the different properties that can be defined, it is easy to create a presentation that helps the user interact with the workflow and make sure that they enter the correct (or expected) values. This can dramatically reduce the number of errors a user is able to cause by making incorrect entries. A typical example of this is to provide the user with a list of predefined answers they can choose from, making sure that only the correct values are entered.

It is important to understand that the presentation is WYSIWYG only in the Orchestrator Client. The presentation may not work the same for Orchestrator Client, vCenter, vRA, or REST. For example, vRA will not be able to use Show root element, or the list view doesn't show properties in vSphere Web Client. One should develop workflows for a given consumer.

Please note that presentations that are configured with the workflow work fine within the vSphere Web Client and in vRA integration, but not in REST calls that launch a workflow. You can test the behavior with the example workflow, 07.05.1 Presentations test.

In the previous example, we linked several properties to different variables. If you have a look at the value field, you will notice that Orchestrator will use the # symbol to mark a variable. In the example workflow, we used a Boolean named boolYesNo, which shows up in the hide-property as #boolYesNo. The entries that we can make in these value fields follow OGNL (Object-Graph Navigation Language). We will have a closer look at OGNL in the recipe Linking actions in presentations in this chapter.

General properties

The following is an almost complete list of common properties:

Property

Type

Explanation

Show/hide parameter input

All

Hide or show an input

Mandatory input

All

The user has to enter a value before the workflow can be started. An error will be displayed if this variable is empty (NULL).

Default value

All

This value is displayed when the input window is displayed.

Data binding

All

Binds data

Predefined answers

Predefined list of elements

All

This is a list of elements that you can select from. A drop-down list will be displayed.

Answers let you define an array of string; Elements let you link an array of strings

Custom validation

All

This property allows for the use of OGNL to perform your own validation on an input. (see the There's more... section in the recipe Linking actions in presentations in this chapter).

Minimum (string length)

Number, String, Path

This is the minimum length/value. You will receive an error message if you exceed the maximum.

Maximum (string length)

Number, String, Path

This is the maximum length/value. You will receive an error message if you are under the minimum.

Number format

Number

This defines a format in which numbers are displayed. #

Matching regular expression

String

This uses a regular expression to check the content. An error is displayed if the content isn't part of the regular expression.

Multi-lines text input

String

This displays a larger text window instead of one line, where more text can be entered.

Valid internet address

String

Validates an input if it's a host or IP address (v4 or v6)

Allow same values

Array

Allow only unique elements in Array

Input date before

Date

Last possible date

Input date after

Date

First possible date

Plugin-specific properties

Certain plugin objects (such as the vCenter plugin) come with additional properties that can be extremely useful. We will now have a look at the most commonly-used properties that come with the base plugins.

select value as

The select value as property has three choices: Tree, List, and Dropdown. This property makes it easier to manage what the input of an object looks like:

select value as

show in inventory

The show in inventory property is quite a powerful property. When you start a workflow from vSphere Web Client, the object you started the workflow on will be passed to the workflow as an in-parameter. We will discuss this in more detail in the recipe Using Orchestrator through the vSphere Web Client in Chapter 7, Interacting with Orchestrator.

This property also makes the workflow accessible from the Orchestrator inventory. This means that you can right-click on an object in the inventory and then select a workflow to be executed onto it.

Specify a root object to be shown in the chooser

This setting lets you define a certain start point for your searches. For example, if you choose an ESXi cluster as the root element, then a user can only select objects under this cluster. To use the root element, you need to link an action or a variable to this property. The following is an example:

Specify a root object to be shown in the chooser

Authorized only

Adding this property to an in-parameter will make sure that only an authorized user can access this in-parameter.

There's more...

Custom validation can be used to check a value against a more complex set of rules. For an example, let's create a custom validation that checks if a given VM name already exists in vCenter:

  1. Create an action called checkExistingVMName.
  2. The action has a string as return value and an in-parameter of vmName:
          allVMs=System.getModule("com.vmware.library.vc.vm").getAllVMs(); 
      for each (vm in allVMs) { 
         System.log(vm.name); 
         if (vm.name.toUpperCase() == vmName.toUpperCase()) { 
               return "A VM with the name "+vm.name+" allready exists"; 
               break; 
         } 
      } 
      return null;
  3. Create a new workflow with an in-parameter.
  4. Add the presentation parameter Custom validation, and link the action you just created to it.

Also see the example workflow, 05.06.02 Custom validation.

See also

Learn regular expressions at the following links:

The example workflow, 05.05 Workflow Presentations and  05.06.02 Custom validation, and the checkExistingVMName action.

The recipe Integrating Orchestrator workflows as XaaS Blueprints in Chapter 13, Working with vRealize Automation.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset