Working with the API

To be efficient in programming using Orchestrator plugins, one needs to know how to work with the Orchestrator API. In this recipe, we showcase how to access and get information from the Orchestrator API.

Getting ready

We only need the Orchestrator Client with rights to edit a workflow.

How to do it...

We will split this recipe into several sections.

Searching for items in the API

The first step is to have a look at the API. To access the API, follow these steps:

  1. Open the Orchestrator Client.
  2. Navigate to Tools | API Explorer:

    Searching for items in the API

The API Explorer opens, and you have four sections, as marked in the preceding screenshot:

  • A (search): Here, you can enter a search word, such as virtualmachine, as well as select what kinds of results you are after
  • B (search results): This section shows you the result of the search: the name, the type (refer to the How it works... section of this recipe), and a short description
  • C (API tree): Double-clicking on a search result in section B will browse the selected result and open the API tree on that element
  • D (detail): Clicking on an item in section C will show a more detailed description of the item in the API

Programming help from the API

This part will showcase how the Orchestrator API can help us program. In this showcase, we will begin to write a program similar to the one that we will create in the recipe Working with mails in Chapter 9, Essential Plugins. Please note that this is only a showcase and won't result in a working program:

  1. Create a new workflow.
  2. Add a scriptable task to the schema.
  3. Edit the element and click on Scripting.
  4. On the right-hand side, you can see the API tree, and you can explore it by browsing it. Try it!
  5. Click on Search (the magnifying glass icon) and enter mailclient in the pop-up search window.
  6. Click on SEARCH, mark the only result, and then click on Go to selection. This will display the MailClient object in the API tree:

    Programming help from the API

  7. Close the search window.
  8. Right-click on the MailClient() constructor (the C symbol) and select Copy. If there is no dedicated constructor, you can always copy the object (the green circle) directly.
  9. In the script area, right-click again and select Paste to auto-create a new constructor for the MailClient object. See the preceding screenshot. This will create an instance of the MailClient type and assign it to the myMailClient variable.
  10. In the API tree, scroll down to and click on connect() method. In the detail area underneath, you will see details for this command, such as what inputs are needed and of what type. The method needs a host, a port, a username, and a password.
  11. Now, copy and paste the connect() method as you did in steps 8 and 9 into a new line in the scripting area. Orchestrator automatically fills in some parts, and the new line will look like this:
          connect(?String_host , ?number_port , ?String_username , 
      ?String_password)
  12. To make this line work, we will need to put an object before it; in this case, it's the MailClient object we created in step 9. Just add myMailClient before connect with a period between them. This will enact the method connect on the MailClient instance. The result will look like this:
          myMailClient.connect(?String_host , ?number_port , ?String_username , 
      ? String_password).
  13. The next step is to substitute each of the placeholders (the ?names) with either Orchestrator variables or values. Replace the first placeholder, ?String_host, with a mail host address, such as mail.mylab.local.
  14. As we want to showcase the API a bit more, we will get the value for the ?number_port placeholder a bit differently. Insert a new line above the connect line.
  15. Use the API search to search for getDefaultPort. You will see that it is an action in the module called com.vmware.libary.mail and needs the input of a type string (a protocol name). Its return value is a number (the port). If you like, take a look at the action itself and its script. This will help you understand how it works and what input it requires.
  16. Now, copy and paste the action from the API tree to the scripting area, as done previously. You will see that additional code is created and looks like this:
          System.getModule("com.vmware.library.mail").getDefaultPort(protocol)
  17. We want the output of the action to be put into a local variable, so insert var port = before System.getModule.
  18. Now, we need to tell the action what protocol we want, so replace protocol with imap. This will save the default port for IMAP into the variable port.
  19. Next, replace the ?number_port placeholder in the connect line with the port variable.
  20. Last but not least, let's add an Orchestrator variable to the connect line. In the scriptable task, create an in-parameter of a type string called userName.
  21. Replace the ?String_username placeholder with userName. Notice the color change of userName when it matches the in-parameter.

At this stage, we leave the showcase, as we have explored the interesting parts. Your little script should look something like this:

var myMailClient = new MailClient(); 
var port = System.getModule("com.vmware.library.mail").getDefaultPort("imap"); 
myMailClient.connect("192.168.220.4" , port , userName, ?String_password);

The full working script can be found in the recipe Working with mails in Chapter 9, Essential Plugins.

How it works...

The Orchestrator API contains all types, methods, attributes, objects, and so on that can be used for programming. All the content comes from Orchestrator or its plugins and gives the Orchestrator programmer a wide range of tools to use.

As you can see in the preceding showcase, the items in the API are color-coded; the following table shows you all the item colors along with a short description of their meaning:

Icon

Name

Usage

Gray bullet

Type

Types are complex variables.

Purple bullet

Function set

A set of functions that centers on certain topics, for instance, the System function set that contains the .log and .warn methods.

Blue bullet

Primitive

A primitive is a basic variable type. These are array, function, number, object, secure string, string, Boolean, and char. String and array contain methods.

Green bullet

Object

Objects contain attributes, constructors, and methods.

Gray and blue gear

Module

Modules contain actions. We worked with actions and modules in the recipe Creating actions in this chapter.

Color icons

SDKModule

SDKModule is part of the plugins and contains types and objects.

C-shaped icon

Constructor

A constructor creates a new entity of a given type. Sometimes, there is no constructor; in this case, you can try to copy and paste the parent object.

Empty square

Attribute

An attribute is a property of an object; it can be either read-only or read-write.

Filled square

Method

The function (action) that is implemented with the object and acts on the object.

See also

In the recipe Working with the vCenter API (to change a VM's HA settings) in Chapter 12, Working with Vsphere, we will explore the vCenter API integration in Orchestrator.

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

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