Chapter 1. Understanding the Automate Model

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.

1.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 Red Hat CloudForms 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.

Red Hat CloudForms contains a set of preconfigured Domains for users:

  • ManageIQ - The core domain for Red Hat CloudForms 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 Red Hat CloudForms 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 Red Hat CloudForms. Use this namespace to integrate with additional systems.

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

Note

Changing the existing classes or instances shipped with the product is not recommended because this may hinder the operation of Red Hat CloudForms. 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.

1.2. Creating a Domain

  1. Navigate to Automation → 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.

1.3. Editing a Domain

  1. Navigate to Automation → 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.

1.4. Deleting a Domain

  1. Navigate to Automation → 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.

1.5. Importing a Domain

Red Hat CloudForms adds the ability to import an Automate domain from a Git repository by specifying a repository and branch, along with user details. Currently, you can only add git domains via the Import/Export option of the user interace.

Import Datastore

  1. Navigate to Automation → Automate → Import/Export.
  2. In Import Datastore via git, enter the Git URL. Select the branch or tag to use.
  3. Optionally, enter a Username and Password.
  4. Click Submit.

The new domain is imported via Git repository. Note that the domain is validated on import.

1.6. 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 Automation → 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.

1.7. Creating a Namespace

  1. Navigate to Automation → 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.

1.8. Creating a Class

  1. Navigate to Automation → 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.

1.9. Creating a Schema for a Class

This procedure shows you how to create a schema.

  1. Navigate to Automation → 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 Provisioning Virtual Machines and Hosts.
  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.

1.10. Editing a Field in a Schema

This procedure describes how to edit schema fields.

  1. Navigate to Automation → 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.

1.11. Editing Schema Sequence

This procedure shows you how to change schema sequence.

  1. Navigate to Automation → 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.

1.12. Adding an Instance to a Class

This procedure shows you how to create an instance.

  1. Navigate to Automation → 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.

1.13. Copying a Class or Instance

  1. Navigate to Automation → 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.

1.14. 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.

1.15. Methods

Methods are pieces of code associated with a class or object to perform a task. Red Hat CloudForms allows for Ruby methods or backing a method using an Ansible playbook. 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 Red Hat CloudForms Rails Application. The Ruby gems in this set are subject to change. If you are calling gems using Automate that are no longer in this release, 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 Red Hat CloudForms.

For lists of Ruby gems included in different Red Hat CloudForms releases, see:

1.15.1. Creating a Method

This procedure shows you how to create a method.

  1. Navigate to Automation → 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.

1.15.2. Creating a Dynamic Content Dialog

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

  1. Navigate to Automation → 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

1.15.3. Creating a Playbook Automate Method

Red Hat CloudForms can choose an Ansible playbook from a repository and execute it as a method. Each playbook method can take additional input parameters specified by the user.

Important
  • You must first sync your playbook repositories before using them to create a method. See Adding a Playbook Repository in Managing Providers for information on initial playbook repository set-up.
  • Using Ansible playbooks to populate dynamic dialog fields is not recommended due to delay times caused by the overhead of interaction between systems.
  • Only users with administrator privileges can run a service dialog based on a playbook automate method.

To create a playbook automate method:

  1. Navigate to Automation → Automate → Explorer, then click on a domain under Datastore.
  2. Under a namespace, select the class for which you want to create a new method.
  3. Click the Methods tab.
  4. Click image (Configuration) then, image (Add a New Method).
  5. In the Main Info area, select playbook from the drop-down menu.
  6. Provide a Name and Display Name.

  7. Select a playbook Repository from the list.

    1. Choose a Playbook to use.
    2. Select the Machine Credential the playbook will use when it runs.
    3. From the Cloud Type list, select a cloud provider.
    4. Choose the Cloud Credential that corresponds to the selected cloud type.
  8. Specify the Hosts on which the playbook will run. Choose Localhost or provide unique values in the Specify host values field.
  9. Set the Max TTL in minutes. The Time To Live (TTL) field allows you to set the maximum execution time for the playbook to run.
  10. Select when to receive Logging Output from the options in the drop-down menu.
  11. Use the Escalate Privilege toggle switch to enable user privilege escalation if credentials are called for during the playbook run.
  12. Choose a Verbosity value to set the debug level for playbook execution.

  13. Add required Input Parameters using the fields and values available. Click the add parameter to add additional input parameters.

    Note

    Input parameters become extra vars, with substitution enabled. This overcomes the lack of a dialog which would normally allow for the input of additional information. For more information on extra vars, see the Ansible documentation.

  14. Click Add when finished.

1.16. Expression Methods

CloudForms additionally provides support for Expression Methods, that allow you to use advance search filters as Automate Methods, substituting the user input from Automate Objects. Expression methods have several distinct advantages, including: running directly in the worker appliance; removing the overhead of forking a DRb process to run the Automate Methods; no Ruby code required; and prebuilt for Dynamic Dialogs.

1.16.1. Input Parameters

Expression methods allow for substitution of user input through input parameters,

Input ParameterExplanation

arg

The argument used in the expression. Each argument should employ the prefix arg. Example: arg1: the first argument in the expression; arg2: the second argument in the expression; argn: the nth argument in the expression.

1.16.1.1. Optional Input Parameters

Note

If attributes and distinct are not specified we try to store the result in a variable called values with a hash consisting of id and name. This makes it compatible with our existing dynamic dialog result set.

Optional Input ParameterExplanation

attributes

A comma delimited list of attributes to select from the resultant objects. This should me marked as an Array Type in the Input Parameters field.

distinct

A comma delimited list of attributes which are distinct in the resultant objects.This should me marked as an Array Type in the Input Parameters field.

result_obj

The object where the result data should be stored. (default: current object)

result_attr

The name of the attribute which stores the result. (default: values)

result_type

The result type hash or array (default: dialog_hash which matches to our dynamic dialog hash. Valid values are hash, dialog_hash, array, simple

on_empty

The method behavior when the search returns an empty list.

error

Abort. (default: error)

default

The default value in case the result is empty and you select warn.

1.16.2. Creating an Expression Method

Expression methods allow you to use advance search filters as automate methods, substituting user input at runtime, and making them ideal for dynamic dialogs.

To create an expression method:

  1. Navigate to Automation → Automate → Explorer, then click on a domain under Datastore.
  2. Under a namespace, select the class for which you want to create a new method.
  3. Click the Methods tab.
  4. Click image (Configuration) then, image (Add a New Method).
  5. In the Main Info area, select expression from the drop-down menu.
  6. Provide a Name and Display Name.
  7. Select an Expression Object from the drop-down menu.

  8. In the Expression editor, create the expression by setting the controls and values used at runtime:

    1. Using the drop-down menu, select the value to use. Based on your selection, choose or input additional values from the drop-down menus or text fields that appear.
    2. In the Contains field, input a value or click User will input the value.
    3. Click image to complete the expression.

  9. Add Input Parameters for each of the user input fields required.

    1. Click image to add a new parameter.
    2. Provide a Name, Default Value and select a Data Type for each parameter.

    3. Click image to add the parameter.

      Note

      If User will input the value is checked, arguments for each input parameter names using the prefix “arg”.

      For example, if there are 3 fields then the input parameter names should be arg1, arg2, and arg3. If there are two runtime parameters arg1 and arg2 must be defined in the input parameters. In the default value for these fields values can be substituted from other objects in the Automate Workspace.

  10. Click Add.

1.17. 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.

1.17.1. Simulating an Automate Model

This procedure shows you how to simulate an automate model.

  1. Navigate to Automation → 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.

1.18. Importing, Exporting, and Resetting the Datastore

The Automate Model can be exported and imported as a YAML file. Red Hat CloudForms 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.

Note

The datastores you are exporting or importing between must use the same CloudForms version.

1.18.1. Exporting All Datastore Classes

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

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

The datastore is exported as a YAML file.

1.18.2. Importing Datastore Classes

This procedure shows you how to import datastore classes.

  1. Navigate to Automation → 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.

1.18.3. Resetting Datastore to Default

This procedure shows you how reset datastore to default.

  1. Navigate to Automation → 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.