Return to Workshop

Exercise 1.18 - “Hello, World!” Automation Script

Exercise Description

Let’s jump right in and start writing our first automation script. In time-honored fashion we’ll write “Hello, World!” to the Automate Engine logfile.

Before we do anything, we need to ensure that the Automation Engine server role is selected on our CloudForms appliance. We do this from the Configure → Configuration menu, selecting the CloudForms server in the Settings accordion.

Setting the Automation Engine server role

The Automation Engine Role

Setting the Automation Engine role is necessary to be able to run queued Automate tasks. Automate actions initiated directly from the WebUI—such as running instances from Simulation, or processing methods to populate dynamic dialogs—are run on the WebUI appliance itself, regardless of whether it has the Automation Engine role enabled.

Section 1: Creating the Environment

Before we create our first automation script, we need to put some things in place. We’ll begin by adding a new domain called ACME. We’ll add all of our automation code into this new domain.

Step 1. Goto Automate → Explorer, then Configuration → Add a New Domain.

Adding a new domain

Step 2. Name the domain ACME, type in the Description ACME Corp., and ensure that the Enabled checkbox is selected.

ACME Domain

Section 2: Adding a Namespace

Step 1. Add a namespace into this domain, called General. Highlight the ACME domain icon in the sidebar, and click Configuration → Add a New Namespace.

Adding a new namespace

Step 2. Give the namespace the name General and the description General Content.

General namespace

Section 3: Adding a Class

Step 1. Now we’ll add a new class, called Methods.

Step 2. Highlight the General domain icon in the sidebar, and click Configuration → Add a New Class.

Adding a new class

Step 3. Give the class the name Methods and the description General Instances and Methods. We’ll leave the display name empty for this example.

Methods class

Section 4: Editing the Schema

Step 1. Now we’ll create a simple schema. Click the Schema tab for the Methods class, and click Configuration → Edit selected Schema.

Editing the schema

Step 2. Click New Field, and add a single field with name execute, type Method, and data type String.

Adding a new schema field

Step 3. Click the checkmark in the lefthand column to save the field entry, and click the Save button to save the schema. We now have our generic class definition called Methods set up, with a simple schema that executes a single method.

Save schema field

Hello, World!

Step 4. Our first Automate method is very simple; we’ll write an entry to the automation.log file using this two-line script:

$evm.log(:info, "Hello, World!")
exit MIQ_OK

Section 5. Adding a New Instance

Step 1. First we need to create an instance from our class. In the Instances tab of the new Methods class, select Configuration → Add a New Instance.

Adding a new instance to our class

Step 2. We’ll call the instance HelloWorld, and it’ll run (execute) a method called hello_world.

Entering the instance details

Step 3. Click the Add button.

Section 6. Adding a New Method

Step 1. In the Methods tab of the new Methods class, select Configuration → Add a New Method.

Adding a new method to our class

Step 2. Name the method hello_world, and paste our two lines of code into the Data window.

Entering the method details

Step 3. Click Validate and then Add.

Section 7: Running the Instance

Step 1. We’ll run our new instance using the Simulation functionality of Automate. Before we do that, log in to CloudForms again from another browser or a private browsing tab and navigate to Automate → Log.

Automate log file

Alternatively, ssh into the CloudForms appliance as root and enter:

tail -f /var/www/miq/vmdb/log/automation.log

In the simulation, we actually run an instance called Call_Instance in the /System/Request/ namespace of the ManageIQ domain, and this in turn calls our HelloWorld instance using the namespace, class, and instance attribute/value pairs that we pass to it.

Step 2. From the Automate → Simulation menu, complete the details.

Completing the Simulation details

Step 3. Click Submit.

If all went well, we should see our “Hello, World!” message appear in the automation.log file:

Invoking [inline] method [/ACME/General/Methods/hello_world] with inputs [{}]
<AEMethod [/ACME/General/Methods/hello_world]> Starting
<AEMethod hello_world> Hello, World!
<AEMethod [/ACME/General/Methods/hello_world]> Ending
Method exited with rc=MIQ_OK

Or, like so from a private browser session:

“Hello World!” log message

Success!

Section 8: Exit Status Codes

In our example we used an exit status code of MIQ_OK. Although with simple methods such as this we don’t strictly need to specify an exit code, it’s good practice to do so. When we build more advanced multi-method classes and state machines, an exit code can signal an error condition to the Automation Engine so that action can be taken.

There are four exit codes that we can use:

MIQ_OK (0)
  Continues normal processing. This is logged to automation.log as:
  Method exited with rc=MIQ_OK
MIQ_WARN(4)
  Warning message, continues processing. This is logged to automation.log as:
  Method exited with rc=MIQ_WARN
MIQ_ERROR / MIQ_STOP (8)
  Stops processing current object. This is logged to automation.log as:
  Stopping instantiation because [Method exited with rc=MIQ_STOP]
MIQ_ABORT (16)
  Aborts entire automation instantiation. This is logged to automation.log as:
  Aborting instantiation because [Method exited with rc=MIQ_ABORT]

MIQ_STOP stops the currently running instance, but if this instance was called via a reference from another “parent” instance, the subsequent steps in the parent instance would still complete.

MIQ_ABORT stops the currently running instance and any parent instance that called it, thereby terminating the Automate task altogether.

Summary

In this exercise we’ve seen how simple it is to create our own domain, namespace, class, instance, and method, and run our script from Simulation. These are the fundamental techniques that we use for all of automation scripts!

Return to Workshop