Configuring custom tools

As an administrator or advanced user, you can create custom topology tools, which users can then access from within 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.

To access the Topology Tools page, you must have the admin role inasm_admin assigned to you. See the Configuring DASH user roles topic for more information.
You must be proficient in JavaScript to define custom tools.

Custom tools are written in JavaScript, and accessed through the right-click (context) menu in the UI. All inasm_operator users can access the tools, but only inasm_admin users can customize them.

Trouble:

Some topology tools fail to load external content

New security measures implemented in recent versions of Firefox and Chrome to prevent click-jacking and similar risks may also prevent the loading of third party content over HTTPS into an iframe.

This mechanism may be used by custom Agile Service Manager topology tools to display contextual information, and as such may be affected.

Workaround:

Firefox: The browser presents the option to load the content in a separate window.
Chrome: None

Tip: The Refresh icon reloads the tools list. This can be useful if other users are customizing the tools.

As the admin user, log into your DASH web application.
Select Administration from the DASH menu.
Select Topology Tools under the Agile Service Management heading.
Use the following information to complete the Topology Tools - Details page.

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.

Navigation

You can move to the next page by using the page selector.

The minimum requirement to save the tool and open the Topology Tools - Implementation page is the name and label.
Use the following information to complete the Topology Tools - Implementation page.
Here you create the JavaScript implementation for the tool, which defines the action that will occur when a user selects this option from the menu. JavaScript examples are included after these steps. To help you create custom Agile Service Manager tools, you have access to the following custom JavaScript helper functions:
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);

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 }
Use the following information to complete the Topology Tools - Conditions page.
Here you define the resource or relationship conditions under which this tool is available.
Applicable item type for tool definition

From this drop-down, select the types to which the tool is applicable: Resource, Relationship, Resource and Relationship, or Status.

Depending on your selection, a number of check boxes are displayed, which you use to configure which resources, relationships or states are included.

All types / All states

Select this option if you want the tool to be displayed for all resource and relationship types, or all states (for Status).

The tool will also be displayed for any specific types not listed here.

Resource types

Select one or more resource types from the list displayed.

Relationship types

Select one or more relationship types from the list displayed.

Status
Select from the following possible states for which the tool will be available:
- Open
- Clear
- Closed
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.

Once you have saved your changes, you must close the Topology Viewer and then reopen it to make the new tools available (tools will be available for use depending on the conditions set).

Example of a lookup tool based on a 'person' resource with the properties 'name' and 'email'.

You first set the Topology Tools - Conditions page to use Resource as the applicable item type, and then select the person resource type only to ensure that the custom tool is only displayed for 'person' resources.

This example demonstrates the JavaScript for a tool that checks for properties, makes an HTTP request, and handles the response either by creating a popup with the response, or by showing an error message.

Note: The function asmHelperFunctions.showToasterMessage accepts the following values for the status:

information
normal
warning
escalated
critical

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

Example of a tool using the asmFunctions.sendHttpRequest(url, options) function: This example sends an HTTP GET request for external REST data, and then displays the retrieved information in a popup dialog.

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