Using Forms with Gen 1

If you want to use different names each time you run the sample automation, manually adjusting the MyFirstName and MyLastName variable tasks would rebuild the automation each time, but it would also be highly inefficient. As a solution, it's far better to leave the automation "as is" and simply provide the name values when you run the automation. To accomplish this, you will need to use a JSON Form.

Likewise, running the automation from Automation Studio every time would not only be tedious but also require manual alterations that could unwittingly open the door to automation errors. To avoid this scenario, you will need to kick off the automation via JSON Form using Automation Catalog. More detailed user information specific to Automation Catalog and JSON Forms can be found on the docs.itential.com site.

Note: This section of the tour guide uses the Gen1 Automation Builder canvas.

Access Automation Catalog

From the IAP home page:

1. Click the Automation Catalog menu option from the left navigation menu. The main page displays.

2. Click + CREATE AN AUTOMATION.

   Note: The "automation" terminology used here is somewhat of a misnomer. You won't actually be creating an automation as you did in Automation Studio. Instead you'll be providing access to an automation that's already built.

3. Give your automation the name "GenerateFacts".

4. Provide a description (optional).

5. Click the CREATE button. The automation details form will display.

In the GenerateFacts Automation Catalog window:

1. Select the "EnlightenMe" automation from the Automation list.
2. Click SAVE (lower-left corner).
3. Under the Select Form field, click the + NEW FORM button.
4. A Create dialog will pop-up asking you to confirm what you would like to create.
5. Select JSON Form to open the JSON Form Builder.

Designing the JSON Form

To design your JSON Form:

1. Go the list of Form Elements on the right side.
2. Drag and drop the TEXT INPUT element onto the canvas.
3. Hover over the 3-dots icon and then click the cog icon to open the Configure dialog for TEXT INPUT.
4. Label the text element "FirstName".
5. Select "Yes" under the Required setting to make the "FirstName" label a required field.
6. Click SAVE.
7. Add another TEXT INPUT element and label it "LastName".
8. Make the "LastName" label a required field.
9. Click SAVE.

Figure 1. JSON Form

Applying the JSON Form

Once you build the JSON Form, navigate back to the Automation Catalog entry "GenerateFacts" that was started earlier.

1. In the Form list box, select the "GenFacts" form you created.
2. Click SAVE.

For more information on building forms, refer to the JSON Forms user guide on the docs.itential.com site.

Save the JSON Form

Once you build the JSON Form, you will return to the Automation Catalog entry "GenerateFacts" that was started earlier.

1. In the Form list, select the "GenFacts" form you created.
2. Click SAVE.

Now let's take a moment and do a checkpoint.

So far, you have created an Automation Catalog entry that will display a newly built "GenFacts" form. Next, you will need to send the form values to the "EnlightenMe" automation, but keep in mind, the automation isn't expecting to receive input from a form. In this part of the process, you will need to update the automation to use the entry values from the JSON Form instead of the "New Variable" tasks -- MyFirstName and MyLastName.

Update the Automation to Accept Form Inputs

To update the automation:

1. Click the App Grid icon in the header toolbar.

   Figure 2. App Grid

1. Select "Automation Studio" from the list.

2. Click the "Find Automation" option (center of screen).

3. Find the "EnlightenMe" automation tile.

4. Click the menu icon (lower-right corner of the tile).

5. Select Edit.

   Figure 3. Edit Automation

You are now back on the familiar Automation Builder canvas.

Set the Query Tasks

At this point, you will need to switch out the task data for "MyFirstName" and "MyLastName". The intent here is to consume the information from the GenFacts form instead of the hard-coded values contained in the "New Job Variable" tasks.

1. Click the "MyFirstName" task.

2. Click the Delete button, or the trashcan icon (upper-right corner) on the canvas, to delete the task.

3. Repeat the previous step for the "MyLastName" task. Your canvas is now missing two necessary variables.

4. In the Task Menu Sidebar, search for "Query".

5. Add two Query tasks to the canvas (to replace the tasks just deleted).

6. Add a transition from the FactURL to one of the new Query tasks.

7. Double-click the Query task to edit the properties.

8. Change the Summary to "Form-FirstName".

9. Change the Description to a short comment that will make sense in the canvas tooltip. For example: "Isolate FirstName from form".

   The tool tip description should be clear and give the user a hint as to the purpose of that specific task.

10. Set the pass_on_null Reference task variable to "False".

11. Set the query Reference task variable to "firstName", which is the name of the field in the JSON Form you created.

    For compliance purposes, the "FirstName" field label on the "GenFacts" form is automatically converted to camelCase, making it firstName instead.

Change the Object Variable

You will need to change the obj variable manually:

1. Change the Reference task to job.
2. For the Reference variable, click the EDIT button.
3. Manually type the word "formData" (without quotes and case-senstive).
4. Click outside of the text entry box when finished.
5. Click SAVE to return to the canvas.

The first Query task is now configured to understand that it will be obtaining content from a JSON form. Now let's move on to the second Query task.

1. Add a transition from the "Form-FirstName" query task that was just altered to the second Query task you added.

2. Configure the second Query task to be "Form-LastName".

   This query variable will search for lastName. Remember, the "LastName" field label is converted to camelCase on the "GenFacts" form.

3. Set the pass_on_null variable to "False".

4. Notice that formData is now an option in the job variable list for obj. Select it from the list.

5. Add a transition from the "Form-LastName" query task to the FirstName-Update (replace) task.

You should now have a series of nine (9) workflow tasks on the canvas.

1. START
2. FactURL
3. Form-FirstName (Query)
4. Form-LastName (Query)
5. FirstName-Update
6. LastName-Update
7. FetchFact
8. Query (IsolateFact)
9. END

Figure 4. Workflow Tasks

Update the Replace Tasks

Next, you will need to update the replace tasks to consume and work with the form values collected in the Query tasks you added.

1. Update the Firstname-Update task properties:
   • Set the newSubstr Reference task variable to the "Form-FirstName" task.
   • The Reference variable should automatically change to return_data.
2. Click Save.
3. Update the Lastname-Update task properties:
   • Set the newSubstr variable Reference task to the "Form-LastName" task.
   • The Reference variable should automatically change to return_data.
4. Click Save.

Note: After updating all the tasks, you could try to manually run the automation, but it will likely result in an error. This is because the automation is now expecting input from a JSON form; however, up until now you have not directly indicated "what form" the automation should expect input values from. You'll recall that the form name was specified within the "GenerateFacts" entry in Automation Catalog.

Test Run the Automation Catalog Entry

1. At this point, you should have saved the entire automation.

2. Click the App Grid icon in the header toolbar.

3. Select "Automation Catalog" from the list of options.

4. Click Find Automation.

5. Find the "GenerateFacts" automation tile.

6. Click the Play icon (lower-right corner).

7. The "GenFacts" form displays in a modal window.

8. Provide FirstName and LastName values.

9. Click START (lower-left corner). The modal window is replaced with a Run Automation notification window.

   Figure 5. Notification Message

1. Click the VIEW button to open the Jobs (Operations Manager) page.
2. Find the IsolateFact task in the job list.
3. Click the book icon to view the OUTGOING value.

You should observe that "Chuck Norris" has been replaced by whatever name input you gave in the "GenerateFacts" Automation (form) initiated from Automation Catalog.

Summary Wrap-Up

Kudos, what great work you've done! You completed all the sections of this quick start tour from start to finish. Let's review all that you've accomplished on your journey:

• Created an automation that utilizes tasks to obtain data from a remote system.
• Viewed active jobs in Jobs (Operations Manager) and navigate to the Outgoing tab to view task results.
• Used additional task inputs that interacted with values presented by other tasks in the automation.
• Customized an automation to accept user input.
• Created an Automation Catalog entry that uses a custom JSON Form to obtain input that's passed to an automation.

After completing this guide, you should be well on your way to using all the the basic capabilities of your IAP instance. To expand your knowledge further, refer to the Itential Automation Platform User Guides that are available on the docs.itential.com site.