Messages

Each schema field has a Message column/value that we can optionally use to identify a particular field to execute or evaluate when we call the instance. We can think of this as a filter to determine which schema values to process.

The default message is create, and if we look at the schema that we created for our /ACME/General/Methods class, we see that the default message value of create was automatically set for us for all fields (see Figure 14-1).

Figure 14-1. The schema of the /ACME/General/Methods class, showing the message

We specify the message when we create a relationship to an instance, by appending #message after the URI to the instance. If we don’t explicitly specify a message, then #create is implicitly used.

For example, we could create a relationship to run our first HelloWorld instance, using a URI of either:

/ACME/General/Methods/HelloWorld

or:

/ACME/General/Methods/HelloWorld#create

In both cases, the hello_world method would execute, as this is the method schema field “filtered” by the create message.

Specifying Our Own Messages

It can be useful to create a class/instance schema that allows for one of several methods to be executed, depending on the message passed to the instance at runtime. For example, the schema for the /Infrastructure/VM/Provisioning/Placement class allows for a provider-specific VM placement algorithm to be created (see Figure 14-2).

Figure 14-2. Schema for the /Infrastructure/VM/Provisioning/Placement class

We can therefore call any instance of the class as part of the VM provisioning state machine, by appending a message created from a variable substitution corresponding to the provisioning source vendor (i.e., redhat, vmware, or microsoft):

/Infra.../VM/Provisioning/Placement/default#${/#miq_provision.source.vendor}

In this way we are able to create a generic class and instance definition that contains several methods, and we can choose which method to run dynamically at runtime by using a message.

Assertions

One of the schema field types that we can use is an assertion. This is a Boolean check that we can put anywhere in our class schema (assertions are always processed first in an instance). If the assertion evaluates to true, the remaining instance schema fields are processed. If the assertion evaluates to false, the remainder of the instance fields are not processed.

We can see an example of an assertion (called placement) at the start of the schema for the Placement class in Figure 14-2. Placement methods are relevant only if the Automatic checkbox has been selected at provisioning time, and this checkbox sets a Boolean value, miq_provision.placement_auto. The placement assertion checks that this value is true and prevents the remainder of the instance from running if automatic placement has not been selected.

Another use for assertions is to put a “guard” field in an instance whose methods are applicable only to a single provider. For example, we might have an instance that configures VMware NSX software-defined networking during the provisioning of a virtual machine. The methods would fail if called during an OpenStack provisioning operation, but we can add an assertion field to the instance, as follows:

'${/#miq_provision.source.vendor}' == 'VMware'

This will return true if the provisioning operation is to a VMware provider but false otherwise, thereby preventing the methods from running in a non-VMware context.

Collections

As we have seen, there is a parent-child relationship between the $evm.root object (the one whose instantiation took us into the Automation Engine) and subsequent objects created as a result of following schema relationships or by calling $evm.instantiate.

If a child object has schema attribute values, it can read or write to them by using its own $evm.object hash (e.g., we saw the use of $evm.object['username'] in Chapter 4). Sometimes we need to propagate these values back up the parent $evm.root object, and we do this using collections.

We define a value to collect in the Collect schema column, using this syntax (see Figure 14-3):

/root_variable_name = schema_variable_name

&nbsp

Figure 14-3. Collections defined in the schema of a provisioning profile

This provisioning profile has several schema attributes defined, such as dialog_name and auto_approval_state_machine. The Collect value makes these attribute values available to this instance’s caller as $evm.root['dialog_name'] and $evm.root['state_machine'].

Summary

This chapter completes our coverage of the objects that we work with in the Automate Datastore. The three schema features that we’ve learned about here are used less frequently but are still very useful tools to have in our scripting toolbag.