Configuring topology tools

As an administrator or advanced user you can create custom topology tools, which users can then access from a topology's context menu. This functionality allows you to access properties of a selected item (such as a resource or relationship) and execute some custom functionality within the context of that item.

Access topology tools

1. As a user with the inasm_admin role, log into your DASH web application.
2. Select Administration > Topology configuration from the menu.
   The Topology configuration page is displayed with a number of configuration options.
3. Click Configure on the Topology tools card.
   The Topology tools page lists the 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, and edit or delete an existing tool.

   Tip: To reduce the number of tools displayed in the table, use the Filter table text field. The tools displayed are filtered as you enter the search text.

   • To reload the tools list, click Refresh (top right). This can be useful if other users are customizing the tools.
   • To delete a topology tool, select one or more tool in the table, then click Delete tool definition.
   • To edit a topology tool, select the tool in the table, then click Edit tool definition. The Edit topology tool page is displayed, from which you define the existing tool as you would a new tool.
   • To create a new tool, click New (top right). The New topology tool page is displayed consisting of the expandable Details, Implementation, and Conditions sections.

Details

On the Details section of the New topology tool (or Edit topology tool) page, you select the types of resource, relationship or status for which the tool will appear in their context menus. Here you define a tool's name and label as a minimum.

4. Use the following information to define the tool details.

   Name

   Unique name used as an internal reference.

   Required.

   Menu label

   The menu label is the text displayed in the context menu.

   This can be the same name as used by other tools, which is why the unique name is required.

   Required

   Description

   A description to help administrator users record the tool's purpose.

   Not displayed in the context menu.

   Optional.

   Menu priority

   The menu priority slider defines where in the context menu the tool is displayed.

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

   Available values are one to ten.

   Optional.

Implementation

On the Implementation section of the New topology tool (or Edit topology tool) page, you define the tool using valid JavaScript. The JavaScript defines the action that will occur when a user selects this option from the context menu while viewing a topology. JavaScript examples are included after these steps. To help you create tools, you have access to a number of custom helper functions.

5. Use the following information to define the tool's implementation in JavaScript format.

   asmProperties

   The tool implementation has access to the properties of the relevant resource, relationship or status via the asmProperties JavaScript object, which contains all the properties.

   You can access the properties using standard JavaScript, but you must protect against a value not being present.

   For example if you intend to use the property 'latitude', you must verify that it is present before using it. To do so, use the following check command:

   asmProperties.hasOwnProperty('latitude')

   If the property is present, the Boolean value true will be returned.

   Status tools properties

   When creating status tools, you use JavaScript that is similar to the script that you use when creating resource or relationship tools. However, the properties you use in your status tool scripts, such as asmProperties, reference the properties for the status item; unlike the properties you use in your resource or relationship tool scripts, which reference the properties for the resources or relationships. For example, if you use asmProperties.location in a status tool script, there must be a corresponding 'location' property in the status record.

   When creating status tools, the asmProperties object has a property that takes the form of an array called resources, which represents the resources in the topology with which this status is associated. Each item in the resources array is an object with properties that represent the properties of that resource. For example, if a status is associated with two resources, the uniqueId property of the first of those two resources could be referenced in the script by using asmProperties.resources[0].uniqueId

   In addition, you can access the properties of a resource against which you are running a status tool by using the asmSourceProperties object when scripting the status tool.

   asmSourceProperties

   You can access information about the source properties of any relationships or status the custom tool is acting on via the asmSourceProperties JavaScript object.

   Example of using the source resource properties in a custom relationship stroke definition:

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

   Remember: The arrows indicating a relationship point from the source to the target.

   asmTargetProperties

   You can access information about the target properties of relationships the custom tool is acting on via the asmTargetProperties JavaScript object.

   asmFunctions

   You can use a number of other helper functions, which are accessed from the asmFunctions object, which includes the following:

   showConfirmationPopup(title, message, onOk)

   Creates a popup confirmation allowing the tool to confirm an action.

   Takes a title and message, which is displayed on the popup, and a function definition, which is run if the user clicks the OK button on the popup.

   showToasterMessage(status, message)

   Shows a popup toaster with the appropriate status coloring and message.

   showPopup(title, text)

   Shows a popup with a given title and text body (including markdown), which can be generated based on the properties of the resource or relationship.

   Tip: The asmFunctions.showPopup helper function lets you use markdown to create more sophisticated HTML popups. For more information on markdown syntax, consult a reputable markdown reference site.

   showIframe(url)

   Displays a popup filling most of the page which wraps an iframe showing the page of the given URL.

   Allows you to embed additional pages.

   sendPortletEvent(event)

   Allows you to send DASH portlet events from the Topology Viewer that can be used to manipulate other DASH portlets, such as the Event Viewer within IBM Tivoli Netcool/OMNIbus Web GUI.

   Note: You can send events to other DASH portlets only if you are running Agile Service Manager within DASH (rather than in a direct-launch browser window), and if the receiving DASH portlets subscribe to the types of events being sent. See the sendPortletEvent examples topic for more information.

   getResourceStatus(<resource_id>, <callback_function>, [<time_stamp>])

   Allows you to request status information from a tool definition for a given resource using its _id parameter.

   resource_id

   Required

   Can be obtained from a resource via asmProperties._id and from a relationship using asmSourceProperties._id or asmTargetProperties._id

   callback_function

   Required

   Is called once the status data has been collected from the topology service, with a single argument containing an array of status objects

   time_stamp

   Optional

   Unix millisecond timestamp to get the status from a given point in history

   The following example prints the status information of a source resource from a relationship context to the browser console log:

   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);

   Tip: The resource properties available in the UI are status, state, severity, time, id and resource_id.

   sendHttpRequest(url, options)

   Lets you send an HTTP or HTTPS request to a remote web server using the Agile Service Manager backend server rather than the browser, thereby avoiding any browser domain-blocking.

   url

   Required

   The full URL of the remote site to be accessed.

   For example:

   https://data-svr-01.uk.com/inv?id=1892&offset=0

   Restriction: You must add any websites referenced by the url parameter to a list of trusted sites as described in the Defining advanced topology settings topic (in this example data-svr-01.uk.com).

   options

   Optional

   method

   HTTP method used:

   • GET
   • POST
   • PUT
   • DELETE

   The default is GET

   headers

   An object defining any special request headers needed

   body

   A string containing the body data for the request

   POST and PUT requests only

   autoTrust

   A flag to indicate if the remote web server can be automatically trusted

   This flag is required if the web site uses a self-signed SSL certificate with no CA, or a CA that is unknown to the Agile Service Manager server.

   True or false, with a default of false

   onSuccess

   A callback function to run if the HTTP request is successful

   This function will be passed the following three parameters:

   • Response text
   • HTTP status code
   • Response headers

   onError

   A callback function to run if the HTTP request fails

   This function will be passed the following three parameters:

   • Response text
   • HTTP status code
   • Response headers

   Options parameter script sample:

   {
       method: 'GET',
       headers: {
           Content-Type: 'application/json',
           X-Locale: 'en'
       }
       body: '{ "itemName": "myData1" }',
       autoTrust: true,
       onSuccess: _onSuccessCallback,
       onError: _onErrorCallback
   }

Conditions

On the Conditions section of the New topology tool (or Edit topology tool) page, you select the types of resource, relationship or status for which the tool will appear in their context menus. You can define additional conditions for resource and relationship types (but not status) using JavaScript.

6. Use the following information to define the conditions under which this tool is available.

   Applicable item type for tool definition

   From this drop-down, select the items to which the tool is applicable.

   Depending on your selection, a number of check boxes are displayed based on the types of resource, relationship or status that exist in the topology database. Select (from) these to specify for which of them the tool is available.

   Tip: You can select All types to make the tool available to all types of resource, relationship or status. The tool will also be displayed for any specific types that are not yet in the database, and therefore are not yet listed here.

   Resource or relationship only

   If you select Resource, Relationship, or Resource and Relationship (and not Status), a JavaScript editor is displayed, letting you define additional conditions for the display of the topology tools.

   Select either All types, or one or more options from the available Resource or Relationship types, and then define the JavaScript definitions in the Additional condition function box. This functionality is useful in providing only the required tools for access from the context (right-click) menu in a topology.

   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 called 'kubernetes_namespace':

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

   Status

   If you select Status, the JavaScript editor is not displayed.

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

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

   Remember: When creating status tools, the properties you use in your status tool scripts reference the properties for the status item, while the properties you use in your resource or relationship tools reference the properties for the resources or relationships.

// Check that the resource has the properties email and name 
if(asmProperties.hasOwnProperty('email') && asmProperties.hasOwnProperty('name')){
    var emailAddress = asmProperties.email;
    var personName = asmProperties.name;

    // Build a http request to collect information from another service using the email
    var request = new XMLHttpRequest();
    var url = 'https://my-lookup-service?email=' + emailAddress;
   
    request.open('GET', url, true);
   
    request.onreadystatechange = function() {
        if (request.readyState === 4) {
            if (request.status === 200) {
                // On successful request show popup in UI window with custom title and the json response from the request
                var title = personName + ' Details:';
                var content = JSON.stringify(JSON.parse(this.responseText), null, 4);
                asmFunctions.showPopup(title, content);
            } else {
               // On request error show popup in UI with custom message.
                var messageStatus = 'critical';
                var message = 'API error, '+ this.responseText
                asmFunctions.showToasterMessage(messageStatus, message);
            }
        }
    };
   
    request.send();
} else {
   
    // If resource doesn't have the expected properties, show toaster message with warning.
    var messageStatus = 'warning';
    var message = 'Unable to load service information, email address not provided.';
    asmFunctions.showToasterMessage(messageStatus, message);
}

// 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);
    }
}