Form Builder

On this page:

User Guide

Form Builder allows developers to construct user entry forms which integrate with IAP (Itential Automation Platform) Workflows and Service Catalog applications. In addition to constructing forms with standard inputs, developers can create forms from imported NSO YANG Service Models using the NSO NETCONF API. This native integration with NSO Services reduces the effort of having to duplicate the development of modeling services in both IAP and NSO. With Form Builder, service models requiring changes are modified just once; changes made in NSO are automatically available for IAP to consume.

User Interface

The following figures show the user interface in Form Builder for List View and Edit View.

List View

Form Builder

Label UI Element List View Function
1 New Form Creates a new form.
2 Delete Deletes form when check-box has been selected.
3 Form List List of forms; includes the form name, who created it, when it was created, who last updated it, and when it was last updated.
4 Preview Opens form in preview mode.
5 Edit Opens form for editing.
6 Import Form Imports a form.
7 Tags Filter Filters form list results by tag.
8 Export Form Exports an individual form.
9 Export Forms Exports each form that is checked in the form list.

Edit View

Edit View

Label UI Element Edit View Function
1 Form Name User must provide unique form name.
2 Data Elements Displays list of registered NSO services.
3 Meta Data Fields Allows user to define custom fields in the form.
4 Update Updates form and leaves Form Editor open.
5 Settings Opens a modal to change the settings of the Form.
6 Preview Opens a modal to preview the Form.
7 Clone Makes a copy of the current Form.
8 Delete Form Deletes the current Form.
9 Close Closes form and returns user to Forms List.
10 Add Container Adds a Field container to the Form.
11 Delete Drag form elements to Trashcan icon to delete.

Creating a New Form

To create a new form:

  1. Open Form Builder from the Home page or the Applications menu.
  2. Click New Form (top-right corner of title bar).
  3. Give the form a unique name.
  4. Click Save.

Exporting a Form

To export a single form:

  1. Open Form Builder from the Home page or the Applications menu.
  2. Locate the form that you wish to export in the forms list.
  3. Click the export icon at the far right of a form in the list.

To export multiple forms:

  1. Open Form Builder from the Home page or the Applications menu.
  2. Click the check box for each form you wish to export.
  3. Click Export Forms (top-right corner of title bar).

Importing a Form

To import a form:

  1. Open Form Builder from the Home page or the Applications menu.
  2. Click Import Form (top-right corner of title bar).
  3. Select the form data file you wish to import.
  4. Click Open on the file dialog.

NSO Service Model Form Fields

Guidelines

  • To view device elements from a service model in Form Builder, you will need to specify where to find the YANG files. In newer versions of NSO adapter (version 4 and higher), this is configured in the yangdirs property of the adapter.
  • To view service models in older versions of NSO adapter (pre version 4), include your YANG schemas in the load-path of ncs.conf.
  • For more information on configuring the NSO adapter to get YANG, check the NSO NETCONF documentation for the adapter.

Create a Form Using NSO YANG Service Model

The following steps correspond to the labels shown in the figure below. To build a form on an NSO YANG service model:

  1. Select the appropriate service from the Data Elements dropdown list.
    • The leafs defined in the model will automatically display below the dropdown box.
  2. Drag-and-drop the fields to assign them to the form.
    • By default, the field label is the same as the leaf from the service model. See vrf_name in the example figure below.
    • To update the field label, click the field and type a new label. See owning_entity_id in the example figure, which has been updated to device.
  3. Assign the Lists defined in NSO to the form.
  4. Group the fields together within a Container.
    • Click the Add Container button to assign a Container to a Form.
    • Toggle the direction icon (double arrow in left corner) to arrange the Containers horizontally or vertically. Containers can also be nested within other Containers.
  5. Assign a name to the Form.
  6. Click Save.

Form

Meta Data Fields

In addition to creating a form using the leafs defined in an NSO Yang service model, you can assign Meta Data Fields to a form. Three field types and a checkbox are available.

  • Text Box - Allows any characters.
  • Number Field - Accepts only numerical values.
  • Checkbox - A Boolean field that can be checked or unchecked.
  • Dropdown - Accepts one selected option from a dropdown list.

Meta Data Fields

Preview a Form

Once a form is saved, click the Form Preview button (eye icon) in the title bar to preview the form.

Form Preview Button

All form fields are editable in Preview mode, even those configured as a lead reference or enumeration in the YANG service model, just as they are when the form is allocated to a Workflow. The figure below illustrates the dropdown list generated by an NSO leaf reference.

Form Preview

Edit Form Field Properties

Once a field has been allocated to a form, you can configure some of its properties.

  1. Hover your mouse over the field.
  2. Click the Configure Properties icon (top-right corner). The Configure dialog box opens.

Configuration Button

Configuration Dialog

Property Description
Custom Label Adds a custom label above the field.
Field Key An internal value that identifies the field from the underlying workflow engine code. Update this value only for a Meta Data Field. Do not modify this value when the field is part of an NSO YANG service model.
Field Type When a Field Type is selected, the form will require that type of input. An error message will display if the input does not match the required type.
Info/ Tool Tip Adds a custom tool tip that displays when your cursor is placed over the field.
Required When checked, a Form cannot be submitted unless a value has been entered in the Number field that displays.
Read-Only When checked, the field is visible to users but they will not be able to modify the value.
Hide Field When checked, the field is hidden from users. The field will still be available to the underlying Workflow Engine code.
Min Length The minimum number of characters a Text field must contain before it can be submitted. Requires the user to define a numeric value.
Max Length The maximum number of characters a Text field may contain before it can be submitted. Requires the user to define a numeric value.
Regex Patterns Does not apply to any fields that have been assigned an NSO leaf reference or enumeration.
Custom Error Message Adds a custom error message that displays when user input is invalid. Requires that Field Type be defined.

Delete a Form Field

To remove a Form Field, click and drag the field to the Trashcan icon (bottom left). This is illustrated in the example form.  

Remove Form Field

Add a Form Builder Task to a Workflow

This section discusses how to add a Form Builder task to a workflow. It does not describe the functionality of the Workflow Builder application.

Note: If you are not familiar with the Workflow Builder application, consult the relevant user guide for clarification on any of the information discussed in this section.

You can use Form Builder to add a Form to a workflow. This allows the user to enter information as part of the business process.

To add a form to a workflow:

  1. Create a new workflow, or open an existing one.

  2. Select FormBuilder in the Source Application dropdown list.

  3. Select ShowFormByName and add it to the workflow.

    Example Task

    formWorkflow Task

  4. Configure the manual task.

    • Enter an appropriate summary and description
    • Assign it to the relevant User Group.
  5. Configure the variables for the ShowFormByName task.

    • form_name This variable is the name of the Form.

      • Select static as the Reference task.
      • Enter the name of the Form as the Reference variable.
    • instance_data If the form values are entered by the user and are not populated by a previous task or external system, configure the following:

      • Select static as the Reference task.

      • Enter {} as the Reference variable.

        Edit Task

        Edit Task

  6. Click Update.

  7. Save the workflow

  8. Click the Start workflow button.

  9. Navigate to the Work queue to view the task in the Available Tasks list.

  10. Click the task to initiate the work.

Example VRF Form from Workflow

VRF Form Form Workflow Example

Outgoing Data Format Example

{
  "/ncs:services/ip_vrf:ip_vrf": [
    {
      "owning_entity_id": "mgracl_iosxr0",
      "vrf_name": "Test-vrf",
      "address_family_type": "ipv4",
      "rd": "65001:1",
      "asn": "65001",
      "rt": [
        {
          "fp_direction": "import",
          "route_target": "65001:56"
        },
        {
          "fp_direction": "export",
          "route_target": "65001:56"
        }
      ]
    }
  ]
}

Note: The internal reference to the Form Field retains the original value before it was renamed. For example, the device field in the above figure maintains the label of 'owning_entity_id' as specified in the Yang service model.