In The Service Provisioning State Machine we saw that two of the service provisioning state machines instances are called CatalogItemInitialization and CatalogBundleInitialization. These two state machines greatly simplify the process of creating service catalog items and bundles, fronted by rich service dialogs, without the need for any Ruby scripting.

A service catalog item generally provisions a single type of virtual machine (although it may result in multiple VMs of the same type being provisioned). A service catalog bundle can provision multiple service items in one go, allowing us to deploy multitier server workloads from a single click.

In this chapter we’ll take a look at these two state machine instances in detail. We’ll see how they allow us to name our service dialog elements in such a way that values are automatically passed into the provisioning workflow, with no need for further automation scripting.


We can specify the CatalogItemInitialization state machine as the provisioning entry point when we create a service catalog item.

The state machine has been written to simplify the process of customising the provisioned VMs, using values read from the service dialog. It does this by setting options hash values or tags in the child and grandchild miq_request_task objects, from specially constructed service dialog element names. It also allows us to specify a new unique name and description for the resulting service.

The schema for the CatalogItemInitialization instance is shown in The fields of the CatalogItemInitialization state machine instance.

Figure 1. The fields of the CatalogItemInitialization state machine instance

We can see that the schema uses the pre1 state to add a dialog parser (common between the CatalogItemInitialization and CatalogBundleInitialization state machines). It also uses the pre2 state to specify the CatalogItemInitialization method, which sets the child object options hash values and/or tags accordingly.

The CatalogItemInitialization method itself relies on the dialog inputs having been parsed correctly by dialog_parser, and this requires us to use a particular naming convention for our service dialog elements.

Service Dialog Element Naming Convention

To perform the service dialog → options_hash or tag substitution correctly, we must name our service dialog elements in a particular way.

Single options hash key

The simplest service dialog element to process is one that prompts for the value of a single options hash key. We name the service dialog element as:

option_0_key_name_ (for backwards compatibility with CloudForms 3.1/ManageIQ Anand)

or just

key_name (valid for CloudForms 3.2/ManageIQ Botvinnik and later)

For example we can create a service dialog element as shown in Service dialog element to prompt for an options hash key.

Figure 2. Service dialog element to prompt for an options hash key

The resulting value input from this dialog at runtime will be propagated to the child task’s options hash as:


The '0' in the dialog name refers to the item sequence number when provisioning. For a service dialog fronting a single catalog item this will always be zero. For a service dialog fronting a catalog bundle comprising several items, the sequence number indicates which of the component items the dialog option should be passed to (an element with a name sequence of '0' will be propagated to all items).

Several key_name values are recognised and special-cased by the CatalogItemInitialization method. We can name a text box element as either vm_name or vm_target_name, and the resulting text string input value will be propagated to all of:


If we name a text box element as service_name, then the resulting service will be named from the text value of this element.

If we name a text box element as service_description, then the resulting service description will be updated from the text value of this element.

Single tag

We can also create a text box service dialog element to apply a single tag. The naming format is similar to that of naming an option, but using a prefix of "tag_", and a suffix of the tag category name.

For example we can prompt for a tag in the department category by naming the service dialog element as tag_0_department (see Service dialog element to prompt for a tag value).

Figure 3. Service dialog element to prompt for a tag value

The value input into the service dialog element at runtime should be a tag within this tag category. When an element of this type is processed by the CatalogItemInitialization method, if either the category or tag doesn’t currently exist, it will be created.


The CatalogBundleInitialization state machine should be specified when we create a service catalog bundle.

The schema for the CatalogBundleInitialization instance is the same as for CatalogItemInitialization, except that the pre2 stage calls the CatalogBundleInitialization method.

The CatalogBundleInitialization method passes the service dialog element values on to each catalog item’s CatalogItemInitialization method, which is still required in order to set the miq_request_task’s options hash keys for the provision of that catalog item.


This chapter has introduced the two service provision state machines that we can use to create service catalog items and bundles, with no need for any Ruby scripting. We can create simple but impressive service catalogs in minutes using these entry points, and we see a practical example of this in Creating a Service Catalog Item.

Further Reading

It is worth familiarising ourselves with the three methods that perform the parsing and transposing of the dialog values. These are DialogParser, CatalogItemInitialization and CatalogBundleInitialization.

results matching ""

    No results matching ""