Service Catalog & Service Catalog Builder Removed

Breaking Change Notice

The Service Catalog and Service Catalog Builder applications have been removed from Itential Platform, effective in the Platform 6 release version. Previously, the two applications worked in tandem to provide users with an entry point for interacting with NSO service models via workflow.

Service Catalog Builder allowed users to create services, which consisted of:

• An NSO service model.
• A workflow developed to effect changes on instances of that service model.
• A (legacy) form, displayed on service execution, that collected user input and passed it to the respective workflow via job variable.

Service Catalog then displayed and executed the services created with Service Catalog Builder.

With this removal, all functionality provided by services has been replaced by Operations Manager. Services are no longer able to be created, and any existing services will be lost on upgrade.

This breaking change notice has been issued not only to inform you of this removal, but to guide you in migrating any of your existing use cases for Service Catalog and Service Catalog Builder to Operations Manager. To this end, we will:

1. Create a replacement form using JSON Form Builder.
2. Create a new manual trigger in Operations Manager (used to launch the workflow).
3. Adapt your Service Catalog workflows via JST to accept JSON forms as input.

What Should I Do?

Migrate all Service Catalog and Service Catalog Builder use cases to Operations Manager.

Operations Manager is similar to Service Catalog in that it allows you to both execute workflows on demand and prepend workflow execution with user input forms. These user inputs are then transferred to their respective workflows via job variables. However, Operations Manager makes use of JSON forms, whereas Service Catalog used legacy forms. This means that workflows launched via Operations Manager will be presented with a differently formatted job variable compared to those launched via Service Catalog. Operations Manager is therefore incompatible with workflows designed for use with Service Catalog unless the workflows are appropriately adapted. The easiest way to adapt such workflows is to translate the job variable sent to them into their expected format via JSON schema transformation (JST).

For instructions on how to migrate your use cases to Operations Manager, refer to the sections herein on:

• Creating an NSO-Based JSON Form
• Creating a Manual Trigger
• Adapting an NSO-Integrated Workflow

How to Transition from Service Catalog to Operations Manager

To migrate all Service Catalog and Service Catalog Builder use cases to Operations Manager you must first create a JSON form to model the legacy user input form and then create a manual trigger to run your automation in Operations Manager.

Prerequisite Reading

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

• JSON Forms
• JST Designer
• Operations Manager
• Workflows

Creating an NSO-Based JSON Form

First, you must model the legacy form of your use case as a JSON form. Legacy forms and JSON forms are relatively similar. You will still be selecting a service model to base your form off of and pulling its fields into your form.

To do so:

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. This form will now be used to launch a manual task in Operations Manager.

Creating a Manual Trigger

In Operations Manager, an automation is roughly analogous to a service — it is the vehicle that contains both the workflow to be run and that workflow's associated form. The JSON form used by automations is comparable to the legacy forms used by services.

In summary, you will launch your workflow via an automation in Operations Manager. In Operations Manager terms, an automation is a workflow and a number of triggers can launch that workflow. Manual triggers run the workflow on demand. Manual triggers also can have a JSON Form assigned to them. Your form's input is sent to the workflow in a job variable. By default, this was instance in Service Catalog. In Operations Manager, it is formData. Essentially, this differs from how it used to be when working with Service Catalog/legacy forms, because the format the job variable takes differs.

Create the Manual Task

To create your manual task:

1. Open Operations Manager.
2. Click Create on the side navigation. The Create Automation modal appears.
3. Select Workflow (automation type) from the dropdown.
4. Enter a name and, optionally, a description for your automation into the relevant fields.
5. Click Create button at the bottom-left corner of the modal. Your newly-created automation opens in the current browser tab.

Configure the Manual Task

Now that your manual task is created, you must configure it. To do so:

1. Use the Workflow dropdown to select which workflow your automation will run — the one that used to be run by your service.
2. Click the Create Trigger button on the Triggers toolbar. The Create Trigger panel will appear on the left-hand side of the window.
3. Enter a name and, optionally, a description for your trigger into the relevant fields.
4. Select Manual from the Type dropdown. The Form dropdown appears directly beneath.
5. Select a JSON form that will be used to gather input from the Form dropdown. This is the form you created in the previous section that is replacing your legacy Service Catalog form. Two items appear directly beneath on the panel:
   1. The Workflow contains legacy "formData" variable check box.
   2. The Default Form Data fields.
6. Check the Workflow contains legacy "formData" variable check box.
7. Optionally, pre-fill any form fields you would like. Any fields you fill out here will automatically be filled in when you run the trigger. It may be useful to at least fill in the ServiceModelPath.
8. Hover over Save Changes at the bottom-left of the modal, then select Save from the menu that appears.

Once your workflow has been adapted, you will use this automation to launch your workflow.

Adapting an NSO-Integrated Workflow

Finally, you must adapt the workflow your service ran to accept the new JSON form input.

Recall from the previous section that the format the job variable form input is sent in differs between legacy forms and JSON forms

While both variables are structured as JSON objects, the particulars vary:

• Both variable values are a JSON object, in which each form field has its own corresponding key, referred to hereafter as a field key.
• Legacy forms wrap the value of each field key in an array.
• JSON forms do not wrap the value of each field key in an array.

For example, when rendering a legacy form that represents a car:

{
    "instance": {
        "Make_FieldKey": [
            "Toyota"
        ],
        "Model_FieldKey": [
            "Corolla"
        ],
        "Used_FieldKey": [
            true
        ]
    }
}

 
Meanwhile, when rendering a JSON form with the same field structure:

{
    "formData": {
        "Make_FieldKey": "Toyota",
        "Model_FieldKey": "Corolla",
        "Used_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, when rendering a legacy form that represents the EBH service model:

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

 
However, when rendering a JSON form with a similar field structure (noting the differences outlined in Creating an NSO-Based JSON Form:

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

 
If your workflow was originally designed to accept data via a service model-based legacy form, it expects 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 JSON form input job variable into a format mimicking that of a legacy form input job variable. By doing so, it meets your legacy workflow's requirements.

We will be translating the following data:

{
    "formData": {
	    "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": "formData",
           "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 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 name of the job variable value used by the legacy form you are replacing; in this example, instance. 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.