Form Builder Removed

Breaking Change Notice

This breaking change affects Form Builder in Platform 6.

Form Builder has been removed from the Itential Platform following its deprecation in the 2023.2 version. With this removal, users are no longer able to create legacy forms; however, existing legacy forms will continue to work for the time being.

What Should I Do?

JSON Form Builder has taken the place of Form Builder. To maintain functionality, users must replace instances of legacy forms with JSON forms, where possible. JSON forms and legacy forms are structured differently by workflows, so some alterations may be necessary to this end. In particular, legacy forms based on NSO service models may require some effort to replace, especially if they are sending their input to the SaveInstances task.

For instructions on how to adapt NSO-based JSON forms to a workflow expecting legacy forms, refer to the sections on:

• Creating an NSO-Based JSON Form
• Adapting an NSO-Integrated Workflow

How to Replace Legacy Forms Based on NSO Service Models

To adapt NSO-based JSON forms to a workflow expecting legacy forms you must first create a JSON form to replace the legacy form and then make the existing workflow compatible with the new JSON form.

Prerequisite Reading

Ensure you are familiar with each of the following before proceeding:

• JSON Forms
• JST Designer
• Workflows

Creating an NSO-Based JSON Form

First, you must create a JSON form to replace the legacy form in question. NSO-based JSON forms are constructed in much the same way that legacy forms are:

1. Open JSON Form Builder.
2. Select the YANG Models dropdown from the right-hand Form Elements bin. A new dropdown appears, stating, "Select a service model."
3. Click the dropdown. A filter bar appears.
4. Type the path of the NSO service model you will be sourcing fields from into the filter bar. Any service models matching your filter display.
5. Select your desired service model. Fields made available by that service model populate under the YANG Models header.
6. Drag service model fields onto the form as you would any other elements in the bin.

Adapting an NSO-Integrated Workflow

Next, you must make your existing workflow compatible with your new JSON form. Two tasks — ShowFormByName and ShowJSONForm — are responsible for rendering legacy forms and JSON forms in a workflow, respectively. Each of these tasks outputs a different data structure to any subsequent tasks (or job variables) in the workflow. Such differences between these tasks are the main source of difficulty in replacing service model-based legacy forms with their JSON form counterparts.

While the task outputs for both are structured as JSON objects, the particulars vary:

• Each task output has a root key named export. The value of this key is a JSON object, in which each form field has its own corresponding key, referred to hereafter as a field key.
• ShowFormByName (legacy) wraps the value of each field key in an array.
• ShowJSONForm (JSON) does not wrap the value of each field key in an array.

For example, the ShowFormByName task may output the following when rendering a legacy form that represents an apple:

{
    "export": {
        "Name_FieldKey": [
            "Apple"
        ],
        "Color_FieldKey": [
            "Red"
        ],
        "Ripe_FieldKey": [
            true
        ]
    }
}

Meanwhile, the ShowJSONForm task will output the following when rendering a JSON form with the same field structure:

{
    "export": {
        "Name_FieldKey": "Apple",
        "Color_FieldKey": "Red",
        "Ripe_FieldKey": true
    }
}

Furthermore, note that the following caveats apply to service model-based legacy forms:

• The ShowFormByName task nests all fields sourced from an NSO service model in the value of a field key named after that service model's path.
• In general, each of these fields is represented as a primitive key-value pair. For example, "name": "ios1_Device".
• The device field is the main exception. It is represented as a reference key-value pair; specifically, an array. For example, "device": ["cisco_CSR_181"].

To demonstrate, the ShowFormByName task may output the following when rendering a legacy form that represents the EBH service model:

{
    "export": {
    "/ncs:services/EBH:EBH": [
    {
    "name": "ios1_Device",
    "device": [
    "cisco_CSR_181"
    ],
    "evc-even": "2",
    "evc-odd": "1"
    }
    ]
    }
}

However, the ShowJSONForm task will output the following when rendering a JSON form with a similar field structure (noting the differences outlined in the previous section on Creating an NSO-Based JSON Form:

{
    "export": {
    "serviceModelPath": "/ncs:services/EBH:EBH",
    "name": "ios1 Device",
    "device": "cisco CSR 181",
    "evcEven": "2",
    "evcOdd": "1"
    }
}

If your workflow was originally designed to send data to the SaveInstances task via a service model-based legacy form, it is constructed to accept output in the former format. For continued use, your workflow must use a transformation to convert the output of your new service model-based JSON form to that of a similar legacy form. See the next section on Creating the Transformation for more information.

Creating the Transformation

The following transformation is designed to translate the output of the ShowJSONForm task into a format mimicking that of the ShowFormByName task. By doing so, it ensures that the output conforms to the SaveInstances task's requirements.

We will be translating the following data:

{
    "export": {
    "serviceModelPath": "/ncs:services/EBH:EBH",
    "name": "ios1 Device",
    "device": "cisco CSR 181",
    "evcEven": "2",
    "evcOdd": "1"
    }
}

To begin:

1. Open JST Designer.

2. On the left-hand side of the window, hover over the Add + button beneath the Incoming Schemas header. A menu appears.

3. Click Incoming Schema. The Add Incoming Schema modal opens. The Add Incoming Schema modal is pre-populated with the following JSON schema:

    {
       "$id": "",
       "type": ""
   }
   

   
   

4. Replace the JSON schema with an appropriate incoming schema. In this example, we will use the following:

   {
           "$id": "export",
           "type": "object",
           "properties": {
               "serviceModelPath": {
                   "type": "string",
                   "examples": [
                       "/ncs:services/EBH:EBH"
                   ]
               },
               "name": {
                   "type": "string",
                   "examples": [
                       "ios1_Device"
                   ]
               },
               "device": {
                   "type": "string",
                   "examples": [
                       "cisco_CSR_181"
                   ]
               },
               "evcEven": {
                   "type": "string",
                   "examples": [
                       "2"
                   ]
               },
               "evcOdd": {
                   "type": "string",
                   "examples": [
                       "1"
                   ]
               }
           },
           "required": []
       }
   

   
   

5. Click the Save button at the bottom-left corner of the modal when you are finished.

6. Use the search bar above the work bench on the right-hand side of the window to locate the templateLiteral method. Drag it onto the canvas.

7. Click the edit template button. The Edit Template Literal modal appears.

8. Construct a template string that mimics the format you would like to transform your data to. Define variables using the ${} delimiter; these will be replaced by your incoming schema values. For example:

   {
           "${ModelPath}": [
               {
                   "name": "${instanceName}",
                   "device": [
                       "${deviceName}"
                   ],
                   "evc-even": "${evenValue}",
                   "evc-odd": "${oddValue}"
               }
           ]
       }
   

   
   

9. Click the Update button at the bottom-left corner of the modal when finished. The templateLiteral now provides input parameters based on the variables you defined in the template string.

10. Connect your incoming schema values to the appropriate templateLiteral parameters. In the example shown below, the incoming serviceModelPath value connects to the ModelPath parameter on templateLiteral, the name value connects to instanceName, and device connects to deviceName, etc.

    This will substitute these values into the string, transforming this string ...

        {
            "${ModelPath}": [
                {
                    "name": "${instanceName}",
                    "device": [
                        "${deviceName}"
                    ],
                    "evc-even": "${evenValue}",
                    "evc-odd": "${oddValue}"
                }
            ]
        }
    

    
    

    ... into this string:

    {
            "/ncs:services/EBH:EBH": [
                {
                    "name": "ios1_Device",
                    "device": [
                        "cisco_CSR_181"
                    ],
                    "evc-even": "2",
                    "evc-odd": "1"
                }
            ]
        }
    

    
    
     Note, however, that at this stage, this data is still a string; it needs to be a JSON object.

11. Use the search bar above the work bench on the right-hand side of the window to locate the parse method. Drag it onto the canvas.

12. Connect the templateLiteral return parameter to the text parameter on parse. The parse converts the output of templateLiteral back into a JSON object.

13. On the right-hand side of the window, hover over the Add + button beneath the Outgoing Schemas header. A menu appears.

14. Click Outgoing Schema. The Add Outgoing Schema modal opens.

15. The Add Outgoing Schema modal is pre-populated with the following JSON schema:

    {
        "$id": "",
        "type": ""
    }
    

    
    

16. Set the value of $id to the same value used for the incoming schema; in this example, export. Set type to object.

17. Click the Save button at the bottom-left corner of the modal when finished.

18. Connect the parse return parameter to the export outgoing schema.

19. Save your changes to the transformation using the canvas toolbar.