Topology tools reference

This reference topic describes the Agile Service Manager topology tools functionality.

Topology tools

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

To access topology tools from DASH, click Administration > Topology configuration on the menu, then 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.

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.

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.

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.