Using Template Builder

Templates in Workflows

Workflow execution can generate large quantities of information that may be extraneous to the task at hand. For example, when interacting with CLI-driven devices, workflows often draw extended responses in the form of command output. You may only care about a few key pieces of data from such output — port number, port status, VLAN, etc. Similar use cases are seen when calling API endpoints. It becomes important, then, to have some way to filter this data down to the essentials, especially if it is being fed into workable tasks later in your workflow. Templates fulfill this function in Itential Automation Platform (IAP).

A template is a static text file that contains, in its simplest form, placeholder variables to be dynamically populated by incoming data. The exact capabilities and syntax of a template depend on the template language used. IAP supports two template types:

• Jinja2
• TextFSM

When a template task, such as Apply Template, is inserted into a workflow, it receives information from a preceding workflow task or job variable and combines that information with a designated template. The template is populated, and the filtered information can then be used by subsequent tasks.

On this page, you will learn:

• How to create a template.
• How to use the Template Builder application to define a template.
• How to use defined templates in workflows.

Prerequisite Reading

Templates created in Template Builder use either the Jinja2 or TextFSM language. As such, knowledge of the relevant language is required before proceeding. For more information, refer to the official documentation for:

• Jinja2
• TextFSM

Creating and Opening Templates

Templates are created on the Automation Studio home page. To do this:

1. Click the Create () button located at the top of the side navigation menu. The Create modal will appear.
2. Select Template from the What would you like to create? drop-down menu.
3. Enter the desired template name and group into the relevant text input fields.
4. Select which language the template should use via the Type drop-down menu.
5. Click the Create button at the bottom-left corner of the modal. Your new template will open in the Template Builder application.

Figure 1: Creating a New Template

To open a pre-existing template, simply select it from the Templates section of the side navigation menu. Alternatively, you can browse templates via the Automation Studio Collection view by clicking the Search () button located at the top of the side navigation menu.

Template Builder UI

Whether you have created a new template or selected an existing one, it will open in the Template Builder application. This application is comprised of three main components, each referenced in the following table.

Figure 2: Template Builder UI

Defining Your Template

As you can see, the application UI is largely dominated by the Data, Template, and Output fields. Indeed, nearly the entirety of Template Builder's functionality is based on how these fields interact with each other. In general:

1. Template logic is entered into the Template field (right). The syntax used varies depending on the language of the current template, which is decided during template creation via the Type drop-down menu.
2. Example data is entered into the Data field (left). This field should mimic the data structures you intend to input to this template. For example, if your template is meant to parse a particular API response, you should provide an example of that response in this field. Keep the data type expected by your template language in mind: Jinja2 expects JSON data, TextFSM expects semi-formatted text, etc.
3. The Data and Template fields are combined, populating the Output field (bottom) with the data structure that you can expect when using the template in your workflows. Changes made to the Data or Template fields are reflected here in real time.

In this way, Template Builder can be used to actively draft and troubleshoot templates for use in your workflows.

Figure 3: Jinja2 Template Evaluation

Example: Using Your Templates in Workflows

Your workflow retrieves a large number of interface entries from a network switch via API. Later on in the workflow, you would like to manually review which interfaces have a role of "voice". However, the JSON object returned by the API contains entries for dozens of interfaces; it's entirely possible that you may miss relevant entries in the noise.

To account for this, you decide to pass the API response through a Jinja2 template, filtering the results to only those entries which have a role of "voice". The filtered response is then queried and passed to the View Data task for confirmation.

{
    "interfaces": {
        "ethernet10": {
            "role": "desktop",
            "vlan": 1
        },
        "ethernet11": {
            "role": "desktop",
            "vlan": 1
        },
        "ethernet15": {
            "role": "printer",
            "vlan": 5
        },
        "ethernet22": {
            "role": "voice",
            "vlan": 10
        },
        "ethernet25": {
            "role": "voice",
            "vlan": 10
        }
    }
}

To do so:

1. Add the Apply Template task to your workflow. Define the following input parameters:
   • Set text to the location of your input data. In this scenario, the deviceResponse job variable.
   • Set template to the name of your template. In this scenario, DocsDemo.
2. Add the Query task to the workflow. Draw a success transition from Apply Template to Query. Define the following input parameters for Query:
   • Set object to the Apply Template output object, the parsed variable.
   • Set query to reference the relevant key of the selected object. In this scenario, results.
3. Add the View Data task to your workflow. Draw a success transition from Query to View Data. Define the following input parameters for View Data:
   • Set header to "Voice Interfaces" and message to "Ensure that the expected interfaces are designated as 'voice'," respectively.
   • Set body to reference the Query output object, the return_data variable.
   • Set btn_success to "Accept" and btn_failure to "Reject," respectively.
4. Draw a success transition from the View Data task to the end of your workflow.

Figure 4: Example Workflow

When working the View Data task in Operations Manager, you will be presented with the following modal shown below.

Figure 5: View Data Modal