Form Builder removed

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

What should I do?

JSON Form Builder has replaced Form Builder. To maintain functionality, replace instances of legacy forms with JSON forms where possible. JSON forms and legacy forms are structured differently within workflows, so some alterations may be necessary. In particular, legacy forms based on NSO service models may require some effort to replace, especially if they send input to the SaveInstances task.

For instructions on adapting NSO-based JSON forms to a workflow expecting legacy forms, see:

• Replace legacy forms based on NSO service models
  • Before you begin
  • Create an NSO-based JSON form
  • Adapt an NSO-integrated workflow
  • Create the transformation

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.

Before you begin

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

• JSON Forms
• JST Designer
• Workflows

Create an NSO-based JSON form

NSO-based JSON forms are constructed in much the same way as legacy forms.

Adapt an NSO-integrated workflow

Next, 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 outputs a different data structure to subsequent tasks or job variables. These differences are the main source of difficulty in replacing service model-based legacy forms with JSON form counterparts.

Both task outputs are structured as JSON objects, but 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 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, ShowFormByName may output the following for a legacy form representing an apple:

1
{
2
    "export": {
3
        "Name_FieldKey": [
4
            "Apple"
5
        ],
6
        "Color_FieldKey": [
7
            "Red"
8
        ],
9
        "Ripe_FieldKey": [
10
            true
11
        ]
12
    }
13
}

ShowJSONForm outputs the following for a JSON form with the same field structure:

1
{
2
    "export": {
3
        "Name_FieldKey": "Apple",
4
        "Color_FieldKey": "Red",
5
        "Ripe_FieldKey": true
6
    }
7
}

The following caveats also apply to service model-based legacy forms:

• ShowFormByName 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 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 (an array) — for example, "device": ["cisco_CSR_181"].

For example, ShowFormByName may output the following for a legacy form representing the EBH service model:

1
{
2
    "export": {
3
        "/ncs:services/EBH:EBH": [
4
            {
5
                "name": "ios1_Device",
6
                "device": [
7
                    "cisco_CSR_181"
8
                ],
9
                "evc-even": "2",
10
                "evc-odd": "1"
11
            }
12
        ]
13
    }
14
}

ShowJSONForm outputs the following for a JSON form with a similar field structure (noting the differences from Create an NSO-based JSON form):

1
{
2
    "export": {
3
        "serviceModelPath": "/ncs:services/EBH:EBH",
4
        "name": "ios1 Device",
5
        "device": "cisco CSR 181",
6
        "evcEven": "2",
7
        "evcOdd": "1"
8
    }
9
}

If your workflow was originally designed to send data to the SaveInstances task via a service model-based legacy form, it expects output in the former format. Your workflow must use a transformation to convert the output of the new JSON form to that of a similar legacy form. See Create the transformation below.

Create the transformation

The following transformation translates the output of the ShowJSONForm task into a format mimicking that of the ShowFormByName task, ensuring the output conforms to the SaveInstances task’s requirements.

We will be translating the following data:

1
{
2
    "export": {
3
        "serviceModelPath": "/ncs:services/EBH:EBH",
4
        "name": "ios1 Device",
5
        "device": "cisco CSR 181",
6
        "evcEven": "2",
7
        "evcOdd": "1"
8
    }
9
}

1
{
2
    "$id": "",
3
    "type": ""
4
}

1
{
2
    "$id": "export",
3
    "type": "object",
4
    "properties": {
5
        "serviceModelPath": {
6
            "type": "string",
7
            "examples": ["/ncs:services/EBH:EBH"]
8
        },
9
        "name": {
10
            "type": "string",
11
            "examples": ["ios1_Device"]
12
        },
13
        "device": {
14
            "type": "string",
15
            "examples": ["cisco_CSR_181"]
16
        },
17
        "evcEven": {
18
            "type": "string",
19
            "examples": ["2"]
20
        },
21
        "evcOdd": {
22
            "type": "string",
23
            "examples": ["1"]
24
        }
25
    },
26
    "required": []
27
}

1
{
2
    "${ModelPath}": [
3
        {
4
            "name": "${instanceName}",
5
            "device": [
6
                "${deviceName}"
7
            ],
8
            "evc-even": "${evenValue}",
9
            "evc-odd": "${oddValue}"
10
        }
11
    ]
12
}

1
{
2
    "/ncs:services/EBH:EBH": [
3
        {
4
            "name": "ios1_Device",
5
            "device": [
6
                "cisco_CSR_181"
7
            ],
8
            "evc-even": "2",
9
            "evc-odd": "1"
10
        }
11
    ]
12
}