Configuring custom tools

Before you begin

Ensure that you are proficient in JavaScript. You must use JavaScript to define custom tools.

About this task

Custom tools can be accessed through the right-click context menu in the UI. All users with permission to access topologies can access the tools, but only administrators with permission to manage topology tools can customize them.

Note: Some topology tools might fail due to browser restrictions, such as when the tool needs to load external content. Security measures for Firefox and Chrome, which prevent click-jacking and similar risks, can also prevent the loading of third-party content over HTTPS into an iframe. An iframe mechanism can be used by custom topology tools to display contextual information, and as such can be affected. As a workaround for Firefox browsers, users can select an option to load the content in a separate window.

Procedure

1. Log in to the IBM Cloud Pak for AIOps console.

2. From the main navigation, click Resource management, then access a topology.

3. In the navigation toolbar for a topology, click the Settings icon. From the drop-down menu, click Topology configuration. The Topology configuration page is displayed. The page includes cards for each category of topology elements and settings that can be configured or customized.

4. On the Topology tools card, click Configure. The Topology tools page is displayed, listing all of your defined tools in table format in sortable columns. These are the tool name, menu label, last update, the items the tool applies to, whether special conditions exist, and its description.

   From here you can create a new topology tool, or select existing tools in the table and edit or delete them.

   Tip: To reduce the number of items displayed in the table, use the Filter table text field. The table is filtered as you enter the search text. You can also click Refresh (upper right) to reload the items displayed, which can be useful if other users are customizing them.

5. Click New to create a new tool. The New topology tool page is displayed consisting of the expandable Details, Implementation, and Conditions sections.

6. In the Details section, enter the general details for your new tool:

   • Name

     Required. Enter a unique internal name for your tool. This name is used as an internal reference for identify individual tools.

   • Menu label

     Required. The menu label is the text that is shown in the context menu. This can be the same name as used by other tools, which is why the unique name is required.

   • Description

     Optional. A description to help administrative users record the tool's purpose. This text does not display in the context menu.

   • Menu priority

     Optional. The menu priority slider defines where in the context menu the tool is displayed. Available values are one to ten.

     For example, tools with a priority of two will be displayed higher in the menu than tools that have a priority of four.

7. In the Implementation section, define the JavaScript implementation for your tool.

   If needed, you can click Example to view example JavaScript to show you how to format your code. The code for your tool runs when the tool is accessed by an operator, such as when a user from the context menu of a topology.

   To help you create tools, you have access to custom helper functions

8. In the Conditions section, select any conditions for using the tool.

   Select the resources, relationships, and status for which the tool applies. A user must select one of these items for the tool to display in the context menu.

   Use the Applicable item type for tool definition field to select between the types of topology items for which the tool is applicable:

   • Resource

     Select one or more resource types from the list displayed.

   • Relationship

     Select one or more relationship types from the list displayed.

   • Resource and Relationship

     Select one or more resource or relationship types from the combined list.

   • Status

     Select from the following possible states for which the tool will be available:

     • Clear
     • Indeterminate
     • Information
     • Warning
     • Minor
     • Major
     • Critical

   Depending on your selection, a number of checkboxes are displayed, which you can use to configure which resources, relationships or states are included. If you select Resource, Relationship, or Resource and Relationship (but not Status), a JavaScript editor is displayed, letting you define additional conditions for the display of the topology tools.

   The following relationship example creates a tool that shows only relationships that have source resources with the name 'kafkaService', or relationships that have target resources with 'entityType' properties that also include 'container':

   if (asmSourceProperties.name === "kafkaService" || asmTargetProperties.entityType.includes("container")) { return true; } else { return false;}
   

   The following relationships and resources example is for relationships and resources that have a property that is called 'kubernetes_namespace':

   if (asmProperties.kubernetes_namespace) { return true; } else { return false; }
   

   For each category, you can also select All types if you want the tool to be displayed for all types under the selected category. The tool also displays for any specific types under the selected category that is not listed.

   Remember: When you are creating status tools, the properties that you use in your JavaScript reference the properties for the status item. The properties that you use in your resource or relationship tools reference the properties for the resources or relationships.

9. Click Save to save your configuration and create the tool.

   Once you save your changes, you must close the Topology Viewer, and then reopen the UI to make the new tool available. Tools are also available on the context menu of a topology only when the configured conditions are met.

Custom helper functions

To help you create custom topology tools, you can use the following custom JavaScript helper functions:

asmProperties.hasOwnProperty('latitude')

if (asmSourceProperties.myProp === 'high') {
    return 'blue';
} else {
    return 'black';
}

let printStatusCallback = function(statuses) {
    statuses.forEach(function(status) {
        console.log('status:', status.status,
                    'state:', status.state,
                    'severity:', status.severity,
                    'time:', new Date(status.time));
    })
}
asmFunctions.getResourceStatus(asmSourceProperties._id, printStatusCallback);

Example tools

Use the following examples to help you create the JavaScript implementation for your own custom topology tools. This implementation needs to define the action that occurs when a user selects the tool from the context menu.

// Get the unique id from the resource and use it to send a REST request
var extId = asmProperties.uniqueId;
if (!extId || extId === '') {
    asmFunctions.showToasterMessage('warning', 'The resource does not have a unique identifier.');
} else {
    var options = {
        method: 'GET',
        onSuccess: _onSuccess,
        onError: _onError
    };
    asmFunctions.sendHttpRequest('https://api.data.uk/resource/' + extId, options);
}

function _onSuccess(response, status, headers) {
    // Start to build text for the info dialog
    var output = 'Here are details for ' + asmProperties.name + ':\n\n';

    var data;
    try {
        data = JSON.parse(response);
    } catch (e) {
        data = {};
    }
    var props = data.additionalProperties;
    if (!props || props .length === 0) {
        asmFunctions.showToasterMessage('information', 'No information exists for this resource.');
    } else {
        for (var idx in props) {
            var prop = props[idx].key;
            var val = props[idx].value;
            if (!prop.endsWith('Id')) {
                output += props[idx].key + ' = ' + props[idx].value + '\n';
            }
        }

        // Show the output in an ASM popup dialog
        asmFunctions.showPopup('External Details', output);
    }
}

function _onError(response, status, headers) {
    if (!response || response === '') {
        asmFunctions.showToasterMessage('critical', 'HTTP request failed with status code ' + status);
    } else {
        asmFunctions.showToasterMessage('critical', 'HTTP request failed: ' + response);
    }
}