Release notesBreaking changes

Service Catalog and Service Catalog Builder removed

The Service Catalog and Service Catalog Builder applications have been removed from Itential Platform in the Platform 6 release. Previously, the two applications worked in tandem to provide 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 can no longer be created, and any existing services will be lost on upgrade.

This notice guides you in migrating any existing Service Catalog and Service Catalog Builder use cases to Operations Manager. The migration involves three steps:

  1. Create a replacement form using JSON Form Builder.
  2. Create a new manual trigger in Operations Manager.
  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 execute workflows on demand and prepend workflow execution with user input forms. These user inputs are transferred to their respective workflows via job variables. However, Operations Manager uses JSON forms, whereas Service Catalog used legacy forms. This means that workflows launched via Operations Manager receive a differently formatted job variable than those launched via Service Catalog. Operations Manager is therefore incompatible with workflows designed for use with Service Catalog unless those workflows are appropriately adapted. The easiest way to adapt such workflows is to translate the job variable into the expected format via JSON schema transformation (JST).

Service model compatibility

The use case examined throughout this document employs a simple service model. As service models increase in complexity, so will their corresponding JSON forms. Exceptionally complex service models may require functionalities that do not currently exist in JSON forms. Such use cases lie outside the scope of this documentation.

Transition from Service Catalog to Operations Manager

Before you begin

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

Create an NSO-based JSON form

First, model the legacy form of your use case as a JSON form. Legacy forms and JSON forms are relatively similar — you select a service model to base your form on and pull its fields into your form.

1

Open JSON Form Builder

Open JSON Form Builder.

2

Select a service model

Select the YANG Models dropdown from the right-hand Form Elements bin. Click the dropdown that appears and type the path of the NSO service model you will be sourcing fields from into the filter bar. Select your desired service model. Its fields populate under the YANG Models header.

3

Build the form

Drag service model fields onto the form as you would any other elements in the bin. This form will be used to launch a manual trigger in Operations Manager.

ServiceModelPath

NSO-based legacy forms automatically infer and output the appropriate service model path depending on what model the form was based on. JSON forms do not natively mimic this functionality. To compensate, you must supply JSON forms with a manually created, dynamic dropdown field named ServiceModelPath. Configure it as follows:

  • Method: GET
  • Base route: /service_management
  • API route: /service_models
  • Source property: /
  • Property key: /name
  • Dropdown label: Value as label

When filling in the form at runtime, the dropdown field options populate based on any NSO service models discovered by the system. Select the model that your form and workflow are designed to interact with.

Create 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.

You will launch your workflow via an automation in Operations Manager. A manual trigger runs the workflow on demand and can have a JSON form assigned to it. Your form’s input is sent to the workflow in a job variable. In Service Catalog, this variable was instance. In Operations Manager, it is formData. The format of this job variable differs between legacy forms and JSON forms.

Create the automation

1

Open Operations Manager

Open Operations Manager and click Create in the side navigation. The Create Automation modal appears.

2

Configure and create

Select Workflow as the automation type from the dropdown. Enter a name and, optionally, a description. Click Create. Your newly created automation opens.

Configure the manual trigger

1

Assign the workflow

Use the Workflow dropdown to select the workflow your automation will run — the one previously run by your service.

2

Create a trigger

Click the Create Trigger button in the Triggers toolbar. The Create Trigger panel appears on the left.

3

Configure the trigger

Enter a name and, optionally, a description. Select Manual from the Type dropdown. Select the JSON form you created in the previous section from the Form dropdown.

4

Enable legacy compatibility

Check the Workflow contains legacy “formData” variable checkbox.

5

Pre-fill optional fields and save

Optionally pre-fill any form fields you would like automatically populated at runtime — it may be useful to pre-fill ServiceModelPath. Hover over Save Changes and select Save from the menu that appears.

Adapt an NSO-integrated workflow

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

The format the job variable form input is sent in differs between legacy forms and JSON forms:

  • Both variable values are JSON objects in which each form field has its own corresponding key (referred to 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:

1{
2    "instance": {
3        "Make_FieldKey": [
4            "Toyota"
5        ],
6        "Model_FieldKey": [
7            "Corolla"
8        ],
9        "Used_FieldKey": [
10            true
11        ]
12    }
13}

When rendering a JSON form with the same field structure:

1{
2    "formData": {
3        "Make_FieldKey": "Toyota",
4        "Model_FieldKey": "Corolla",
5        "Used_FieldKey": true
6    }
7}

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

  • The legacy form 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, when rendering a legacy form for the EBH service model:

1{
2    "instance": {
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}

When rendering a JSON form with a similar field structure (see Create an NSO-based JSON form for the differences):

1{
2    "formData": {
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 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 Create the transformation below.

Create the transformation

The following transformation translates the JSON form input job variable into a format mimicking that of a legacy form input job variable, meeting your legacy workflow’s requirements.

We will be translating the following data:

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

This example demonstrates the general concepts behind the transformation. It is not a one-size-fits-all solution — you will need to tailor it to fit your own environment.

1

Open JST Designer

Open JST Designer.

2

Add an incoming schema

On the left side of the window, hover over the Add + button beneath the Incoming Schemas header and click Incoming Schema. The Add Incoming Schema modal opens, pre-populated with:

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

Replace the JSON schema with the following:

1{
2    "$id": "formData",
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}

Click Save.

3

Add a templateLiteral method

Use the search bar above the workbench on the right side of the window to locate the templateLiteral method. Drag it onto the canvas and click edit template. Construct a template string that mimics the legacy format, using the ${} delimiter for variables:

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

Click Update.

4

Connect incoming schema values

Connect your incoming schema values to the appropriate templateLiteral parameters: serviceModelPath → ModelPath, name → instanceName, device → deviceName, etc.

This substitutes the values into the string, transforming the template into:

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}

At this stage, this data is still a string. The next step converts it to a JSON object.

5

Add a parse method

Use the search bar to locate the parse method. Drag it onto the canvas and connect the templateLiteral return parameter to the text parameter on parse. This converts the string output back into a JSON object.

6

Add an outgoing schema

On the right side of the window, hover over the Add + button beneath the Outgoing Schemas header and click Outgoing Schema. Set the value of $id to the name of the job variable used by the legacy form you are replacing — in this example, instance. Set type to object. Click Save.

7

Connect and save

Connect the parse return parameter to the export outgoing schema. Save your changes using the canvas toolbar.