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.

Adding a New Domain

In the Automate Explorer, highlight the Datastore icon in the sidebar, and click Configuration → Add a New Domain (see Figure 3-2).

Figure 3-2. Adding a new domain

We’ll give the domain the name ACME, give it the description ACME Corp., and ensure that the Enabled checkbox is selected.

Adding a Namespace

Now we’ll add a namespace into this domain, called General. Highlight the ACME domain icon in the sidebar, and click Configuration → Add a New Namespace (see Figure 3-3).

Figure 3-3. Adding a new namespace

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

Adding a Class

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

Note

Naming a class Methods may seem somewhat confusing, but many of the generic classes in the ManageIQ and RedHat domains in the Automate Datastore are called Methods to signify their general-purpose nature.

Highlight the General domain icon in the sidebar, and click Configuration → Add a New Class (see Figure 3-4).

Figure 3-4. Adding a new class

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

Editing the Schema

Now we’ll create a simple schema. Click the Schema tab for the Methods class, and click Configuration → Edit selected Schema (see Figure 3-5).

Figure 3-5. Editing the schema

Click New Field, and add a single field with name execute, type Method, and data type String (see Figure 3-6).

Figure 3-6. Adding a new schema field

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.

Hello, World!

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

Adding a New Instance

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 (see Figure 3-7).

Figure 3-7. Adding a new instance to our class

We’ll call the instance HelloWorld, and it’ll run (execute) a method called hello_world (see Figure 3-8).

Figure 3-8. Entering the instance details

Click the Add button.

Adding a New Method

In the Methods tab of the new Methods class, select Configuration → Add a New Method (see Figure 3-9).

Figure 3-9. Adding a new method to our class

Name the method hello_world, and paste our two lines of code into the Data window (see Figure 3-10).

Figure 3-10. Entering the method details

Click Validate and then Add.

Tip

Get into the habit of using the Validate button; it can save you a lot of time catching Ruby syntactical typos when you develop more complex scripts.

Running the Instance

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

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 (see Chapter 11).

From the Automate → Simulation menu, complete the details (see Figure 3-11).

Figure 3-11. Completing the Simulation details

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

Success!

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 multimethod 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]

Summary

In this chapter 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 our automation scripts, and we’ll use this knowledge extensively as we progress through the book.

We’ve also discovered the status codes that we should use to pass our exit status back to the Automation Engine.