Chapter 2. Automate Model

CloudForms Management Engine Automate enables real-time, bi-directional process integration. This provides users with a method to implement adaptive automation for management events and administrative or operational activities.

2.1. Automate Model

The Automate model is arranged to provide an object oriented hierarchy to control automation functions. The model uses the following organizational units arranged in a hierarchy:

  • Datastore - The main organization unit that stores the entire model.
  • Domains - Domains act as collection of automation functions. Functions are executed depending on the order of Domain priority, which means a function in a Domain with a higher priority overrides the same functions specified in a lower-priority Domain. This allows CloudForms Management Engine to specify a core Domain (ManageIQ) but allow users to override automate functions with custom Domains. Each Domain contains a set of Namespaces.
  • Namespaces - Containers that organize and categorize functions of the model. Namespaces can contain child Namespaces as well as Classes.
  • Classes - Templates for a specific function of the model. Each Class uses a Schema to apply to Instances to populate with default values. Each class also can contain a set of methods.
  • Instances - An instance is a version of a class populated with initial configuration data. An instance can include a collection of any number of attributes, calls to methods, and relationships.
  • Methods - Methods are functions within the model. Methods use Ruby code to execute various operations needed for a Class.

CloudForms Management Engine contains a set of preconfigured Domains for users:

  • ManageIQ - The core domain for CloudForms Management Engine Automate operations. This domain is locked with the following Namespaces:

    • Cloud - General cloud instance lifecycle from provisioning, retirement, methods, email.
    • Control - Control contains email alerts for policy controls.
    • Infrastructure - General infrastructure VM lifecycle from provisioning, retirement, methods, email.
    • Service - Service lifecycle from provisioning, retirement, methods, email.
    • System - System contains classes that can provide the start points for all CloudForms Management Engine Automate activities.

  • RedHat - Domain containing advanced operations, specifically interactions with supported cloud and infrastructure providers. This domain is locked with the following Namespaces:

    • Cloud - Red Hat-supported cloud instance lifecycle from provisioning, retirement, methods, email.
    • Infrastructure - Red Hat-supported cloud instance lifecycle from provisioning, retirement, methods, email.
    • Integration - Used to interface with systems outside of CloudForms Management Engine. Use this namespace to integrate with additional systems.

You can copy classes and instances from locked Domains into your own custom domains.

Note

Red Hat does not recommend changing any of the existing classes or instances shipped with the product as this may hinder the operation of the CloudForms Management Engine. You can link to these methods using relationships.

To reset the Automate model to default settings, navigate to Automate → Import/Export and click the Reset option.

2.2. Creating a Domain

  1. Navigate to Automate → Explorer. The default view is the Datastore.
  2. Click image (Configuration), then image (Add a New Domain).
  3. Type in a unique Name and Description. Choose if the Domain is Enabled.
  4. Click Add.

The new domain is created.

2.3. Editing a Domain

  1. Navigate to Automate → Explorer. The default view is the Datastore.
  2. Select the Domain you want to edit.
  3. Click image (Configuration), then image (Edit Selected Domain).
  4. Make the required edits.
  5. Click Save.

You have edited the selected domain.

2.4. Deleting a Domain

  1. Navigate to Automate → Explorer. The default view is the Datastore.
  2. Select the Domain that you want to delete.
  3. Click image (Configuration), then image (Remove This Domain).
  4. A window to confirm the removal of Domain appears.
  5. Click OK.

The selected Domain is deleted.

2.5. Changing Priority Order of Domains

Functions are executed depending on the order of Domain priority. Use this procedure to change the priority order of domains.

  1. Navigate to Automate → Explorer. The default view is the Datastore.
  2. Select the Domains you want to change the priority order for.
  3. Click image (Configuration), then image (Edit Priority Order of Domains).
  4. The list of Domains selected shows up. Note that you cannot change the priority of locked Domains and therefore locked Domains do not show up on the list.
  5. Select one or more consecutive groups to move up or down to change their priority as required.
  6. Click Save.

2.6. Creating a Namespace

  1. Navigate to Automate → Explorer. The default view is the Datastore.
  2. Navigate through the various Domains and Namespaces until you reach the desired location for your new Namespace.
  3. Click image (Configuration), then image (Add a New Namespace).
  4. Type in a unique Name and Description.
  5. Click Add.

The new Namespace is created.

2.7. Creating a Class

  1. Navigate to Automate → Explorer, navigate to the namespace you want to add a class to.
  2. Click image (Configuration), then image (Add a new Class).
  3. Type in a unique Name and Description.
  4. If you want to use the schema from a class that has already been created, select it from the Inherits From dropdown. If the class that the new class inherits from changes, the new class will also change.
  5. Click Add.

The new class is created and you can create a schema, add instances and methods.

Note

For each class, create a schema if you did not choose to inherit from an existing class. The schema can include attributes, methods, assertions, and relationships.

2.8. Creating a Schema for a Class

This procedure shows you how to create a schema.

  1. Navigate to Automate → Explorer, and click the class you want to define a schema for.
  2. Click on the Schema tab.
  3. Click image (Configuration), then image (Edit selected Schema).
  4. Click image (Click to add a new field) to create a new field.
  5. Type in a Name for the new field.
  6. From Type, select Assertion, Attribute, Method, Relationship, or State.
  7. If applicable, select a Data Type and set a Default Value.
  8. Type in a user friendly Display Name and Description.
  9. Check Sub to enable the substitution syntax of ${}. Uncheck it if you want to use that syntax as a regular string.
  10. Fill in Collect and Message as required. Collect is used to roll up values from resolved relationships. For example, a relationship can resolve to a large object tree. Use collect to specify how to pull out data from those child objects into the current object. If you give collect a name value, it will store the method result in an attribute of the current object with that name.
  11. On Entry, On Exit, On Error, Max Retries, and Max Time are fields used mostly for state machines. Leave blank if not applicable. For more information, see the Provisioning Virtual Machines and Hosts guide, available from https://access.redhat.com/documentation/en/red-hat-cloudforms/.
  12. Click image (Add this entry) to confirm the fields values.
  13. For each new field, repeat steps 4 through 10.
  14. When you have created all of the fields, click Save.

The class schema is created, and you can now add instances to it.

Note

You may need to edit a class schema to reorder, add, edit, or remove a field. Classes define the order in which fields are processed and you may need to process some items before others.

2.9. Editing a Field in a Schema

This procedure describes how to edit schema fields.

  1. Navigate to Automate → Explorer.
  2. Click the class you want to define a schema for.
  3. Click the Schema tab.
  4. Click image (Configuration), then image (Edit selected Schema).
  5. Make required changes to any of the definitions for the field.
  6. To remove a field, click image (Click to delete this field from the schema).
  7. Click Save when you are finished editing the schema.

Once the schema is created, you can add instances and methods to the class.

2.10. Editing Schema Sequence

This procedure shows you how to change schema sequence.

  1. Navigate to Automate → Explorer.
  2. Click the class you want to change the schema sequence for.
  3. Click the Schema tab.
  4. Click image (Configuration), then image (Edit Sequence).

  5. In the Class Schema Sequencing area, click the field you want to change the sequence for.

    • To move a field up in the order of resolving an instance, click image (Move selected field up).
    • To move a field down in the order of resolving an instance, click image (Move selected field down).
  6. Click Save when you are finished editing the sequence.

2.11. Adding an Instance to a Class

This procedure shows you how to create an instance.

  1. Navigate to Automate → Explorer.
  2. Click the class you want to define a schema for.
  3. Click the Instances tab.
  4. Click image (Configuration), then image (Add a new Instance).
  5. In the Main Info area, type in a Name, Display Name and Description.
  6. In the Fields area, type in an appropriate value for each field, leave the field blank if no value is required, or use the default value.
  7. Click Add.

2.12. Copying a Class or Instance

  1. Navigate to Automate → Explorer. The default view is the Datastore.
  2. Navigate through the various Domains and Namespaces until you reach the desired class or instance to copy.
  3. Click image (Configuration), then either (Copy this Class) or (Copy this Instance) depending on the object chosen.
  4. Choose the target Domain in the To Domain drop-down menu.
  5. The object retains the same path as the From Domain and overrides the class in From Domain if the To Domain has a high priority. You can also untick the Copy to same path option to specify a new Namespace.
  6. Click Add.

2.13. Relationships

Relationships are used to connect to other instances in the Automation Datastore. Relationships are formed using URI syntax. The following can also be passed through a relationship:

  • Use # to set the message to send to the item in the relationship.
  • To pass an input to the method use ? followed by the item to pass.
  • If you want to use a substitution, the syntax is $\{} with the substitution located between the brackets.
ExampleExplanation

/Cloud/VM/Provisioning/Naming/Default#create

This relationships uses the Default instance of the Naming class, which provides a means for other classes to name virtual machines. The relationship sends the create message to the class.

/Cloud/VM/Provisioning/StateMachines/VMProvision_VM/AcquireMACAddress#$\{#ae_message}

This relationships substitutes the message to send to the AcquireMACAddress instance of the VMProvision_VM class with the value in ae_message.

/Cloud/VM/Retirement/Email/vm_retirement_emails?event=vm_retired

Invokes the vm_retirement_emails instance of the Email class. Also sends the value vm_retired in the event attribute, which is used in the vm_retirement_emails method.

/Service/Lifecycle/Retirement?service_id=$\{process#service_id}

Invokes the Retirement instance of the Lifecycle class and send a replacement value in process#service_id to the service_id attribute.

2.14. Methods

Methods are pieces of code associated with a class or object to perform a task. CloudForms Management Engine allows for Ruby methods. You can create your own methods or use relationships to link to pre-existing ones.

Red Hat CloudForms ships with a core set of Ruby gems used by the CloudForms Management Engine Rails Application. The Ruby gems in this set are subject to change, and have changed since CloudForms 3.1 (CloudForms Management Engine 5.3). If you are calling gems using Automate that are no longer in the CloudForms Management Engine Appliance, you can install them by using the gem install command.

While gems can be imported into automation methods using require, it is recommended that the authors of the automation methods clearly document the use of gems either in the core set or a custom set. It is the responsibility of the author of such custom automation to own the life cycle of any gem being referenced in those methods.

The Release Notes list Ruby gems that have been added, updated, or removed in the latest version of CloudForms Management Engine.

For lists of Ruby gems included in different CloudForms Management Engine releases, see the following article:

2.14.1. Creating a Method

This procedure shows you how to create a method.

  1. Navigate to Automate → Explorer, navigate to the class where you want to create a method.
  2. Click the Methods tab.
  3. Click image (Configuration), image (Add a New Method).
  4. In the Main Info area, type in a Name and Display Name.
  5. For Location, select inline. Once selected, you will be presented with a Data area in which to write or copy the script.
  6. Click Validate to check the syntax.
  7. Click Add.

2.14.2. Creating a Dynamic Content Dialog

The procedure describes the steps to create a dynamic content dialog.

  1. Navigate to Automate → Explorer.

  2. From the accordion menu, click DOMAIN → Cloud → VM → Operations → Methods.

    Note

    DOMAIN must be a user-defined Domain and not the locked ManageIQ Domain. If necessary, you can copy the class from the ManageIQ domain into a custom domain.

    This example uses the Cloud Namespace but can also use the Infrastructure namespace.

  3. Click image (Configuration), then image (Add a new Instance).
  4. In the Main Info area, enter Name = dynamic_list, replacing dynamic_list with an appropriate name for the method.
  5. Enter a Display Name and Description.
  6. In the Fields area, enter Value = dynamic_list. Leave the other fields blank or use the default values.
  7. Click Add.
  8. Navigate to Methods tab.
  9. In the Main Info area, enter Name = \\dynamic_list and populate the Data section with the example automate method below.
  10. Click Add.

  11. Set the automate entry point for the dialog control; use the new instance created in step four. You can create a new domain and copy the method to that domain. 

    #  Automate Method

dialog_field = $evm.object

# sort_by: value / description / none
dialog_field["sort_by"] = "value"

# sort_order: ascending / descending
#dialog_field["sort_order"] = "ascending"

# data_type: string / integer
dialog_field["data_type"] = "integer"

# required: true / false
# dialog_field["required"] = "true"

dialog_field["values"] = {1 => "one", 2 => "two", 10 => "ten", 50 => "fifty"}
dialog_field["default_value"] = 2

2.15. Simulation

2.15.1. Simulation

After your model is designed, use the simulate page to test it. It allows you to see the results in tree and XML view.

2.15.2. Simulating an Automate Model

This procedure shows you how to simulate an automate model.

  1. Navigate to Automate → Simulation.

  2. In Object Details, select a type of object from /System/Process/ that will initiate the model. The Message should be create. Type in the name of the Request where you are starting from.

    image

  3. Select the Type of item you want to run the simulation on. Then, select a specific one to use as the example.

    image

  4. Check Execute Methods if you want to perform the model and not just simulate it.

    image

  5. Type in the Attribute/Value Pairs fields if applicable.
  6. Click Submit.

Click on the Tree View or XML View tabs to see results.

2.16. Importing, Exporting, and Resetting the Datastore

2.16.1. Importing, Exporting, and Resetting the Datastore

The Automate Model can be exported and imported as a YAML file. CloudForms Management Engine allows you to back up your model by export. Red Hat may provide you with new or updated classes, and provides an import function for either a class or the entire model. Finally, you can reset the datastore to its default. Always be sure to export the current datastore before importing or resetting.

2.16.2. Exporting All Datastore Classes

This procedure shows you how export datastore classes as an XML file.

  1. Navigate to Automate → Import/Export.
  2. Click image (Export all Datastore classes and instances to a file).
  3. Follow your browsers prompts to save the file.

The datastore is exported as a YAML file.

2.16.3. Importing Datastore Classes

This procedure shows you how to import datastore classes.

  1. Navigate to Automate → Import/Export.
  2. Export the datastore so that you have a backup.
  3. Click Browse to navigate to the location of the file to import.
  4. Click Upload.

The datastore is imported from the YAML file.

2.16.4. Resetting Datastore to Default

This procedure shows you how reset datastore to default.

  1. Navigate to Automate → Import/Export.
  2. Export the datastore so that you have a backup.
  3. Click image (Reset all Datastore custom classes and instances to default).
  4. Read the prompt warning you that communication with the datastore will be lost and all classes and instances will be cleared and reset.
  5. After reading the prompt, click OK.