How can I create Custom dashboard tools

This tutorial provides details on how to create your own tools within the Active Console 2 Dashboard.

Note

If you are an experienced dashboard user you may find full details of the required modifier paths at the bottom of this page.

Creating a basic tool Copied

We will start simple and create a basic tool in the dashboard palette. Tools are designed by adding shapes to the dashboard as though building a dashboard, then dragging them back into the palette as a new tool. The new tool can then be used like any other.

1. Create a couple of simple shapes.

2. Then area select around all the shapes.
3. Enter Tool Creation mode. Tool creation mode is necessary because we want to drag the shapes into the palette to create the new tool, but in normal mode if we try and drag the shapes we would simply be moving them. The mode allows you to drag shapes outside the dashboard and into the palette.

4. Now drag the selected shapes into the palette. This will create the new tool.
5. The Tool Properties dialog will appear, allowing you to complete the tool creation process.

6. Give the tool a suitable name (this will appear in the palette and the tool selection dialogs) and a description (which will appear in the tooltip for the tool). You can set the category as well if you wish. This will dictate the title it appears under in the palette. If you define a new category name that no tool has at this stage (such as when we renamed the category to be New Tools), then a new title called New Tools would appear in the palette.
7. To use the tool, un-toggle the Tool Creation mode, then drag the new tool from the palette into the dashboard to create a new instance. And that’s it, you have a new tool, and you have used it.

8. If you save the workspace, the new tool will be saved with it.

Some things to note about this process:

• Grouping - when the tool is created (dropped into the palette), all dragged shapes are grouped together before the tool is constructed. When the tool is used, the shapes will therefore appear as grouped.
• The tool is a stamp rather than an instance creator - when you use the tool, what it is actually doing under the bonnet is creating a set of shapes and lines. After creation, these shapes do not know they are an instance of type X. So imagine it like an ink stamp, rather than a machine that creates types of objects that will always be of that type.

Note

If you want to see the properties of an object that is within a group but do not want to go to the trouble of ungrouping, hold down the ALT key and right-click on the object of choice. This will bypass the group, allowing you to get to the lower-level object properties.

All the tools in the basic section are simply a set of polygons whose name matches the shape they represent. They were not created in code but instead by completing the above steps and adding them to the default workspace. The rectangle, for example, once used, could be freely changed into a rhomboid on the dashboard, then added back to the palette as such.

Using Modifiers Copied

The shape we created in the first tutorial does not have any connected modifiers, and thus its properties (such as colour and label text) will not update as the connected gateways change state. So what if we want a tool to embed some logic such that it will update based on some gateway table cell when used?

To do this, we need to embed modifiers into the tool. Before doing that, let’s try out some modifiers outside the scope of tools:

1. Drag a cell (with a severity colour) onto one of the dashboard objects we created previously.

2. When the dialog appears, select the Modifiers tab.

3. Hold down CTRL and select the following modifiers from the list:

   • Link background colour to severity
   • Label text linked to data item’s value

4. Click OK.

The changes will be applied - the shape will turn the colour of the severity, and the text will change to the cell value. Now let’s inspect what changes occurred to the shape:

5. Ungroup the shape by right-clicking on it and selecting Arrange > Ungroup. It may already be ungrouped; if so, skip this step.
6. Right-click on the shape with the modifiers and select Properties, then go to the Modifiers section.

From the modifiers section, you will see one entry for each modifier added through the dialog. The path to the matching data items will correspond to the data item we originally dragged onto the shape. As the severity and value of the connected cell change, the shape updates via the modifiers.

A couple of points to note on this:

• This can be achieved manually by using the modifier dialog to add modifiers and paths, but it’s fiddly and error-prone compared to drag-and-drop.

• Only one modifier can be applied to any given shape property. For example, if you link the background colour to a cell, and then drag another cell with a background colour modifier, the new one will overwrite the old.

• You can modify the paths attached to a given modifier to expand which data items match:

  • The highest severity will be taken.
  • A comma-separated list of values will be shown if multiple matches are found for text fields.

Dragging data items onto the dashboard using a tool with a context Copied

What we have done so far has been to add some basic shapes on to the dashboard, and used some modifiers to make them change as the gateway changes. Both these actions are however fairly low level, in that you are designing a dashboard bottom up from the most primitive objects (shapes and modifiers). The knowledge and skill sets involved to get to the end point (a complete and useful dashboard) are therefore greater as is the required effort.

Interestingly it was not envisioned during the design of the dashboard component that this would be the normal method of creating dashboards. Instead, it was expected that users would drag data items from other dockables (such as the State Tree or Entities view), and then select a tool for how to represent that item.

1. To use a tool drag a data item from the state tree onto the dashboard.
2. A tool selection dialog will appear from which you should select a tool.
3. Click OK, then the representation will be created.

In the background the dashboard is creating an instance of the tool (in the same way as when we used the tool in the first tutorial directly from the palette), and then setting the path on the connected modifiers to be equal to the path of the item that was dropped. In the example above the background and gradient fill linked to the severity of the connected path (data item), and the label text equal to the data item’s name. These mappings were decided by the ‘designer’ of the tool, based on the modifiers they had added at design time.

If you drag another item onto the dashboard and scan through the available tools you will notice that the tool you created in the first tutorial is not presented as an option. This is because it has not got modifiers on any of the constituent objects, and therefore will not update based on changes to the dragged and dropped data item. Because without modifiers the objects will not change, only tools with embedded modifiers are shown in the tool dialog; therefore, the one you created earlier will not appear.

Using modifiers with tools Copied

If you want to make tools more useful by updating their values and properties based on connected data items then you need to embed modifiers into the tool. Only tools which have embedded modifiers will appear in the tools dialog on a drag and drop. This section steps you through how to do this.

1. Assuming you have followed the instructions so far you will have an instance of a tool (ungrouped) with two modifiers on one of the shapes (as shown in figure 6).
2. Now enter Tool Creation Mode again, area select around your shapes and drag them into the palette to create a new tool.
3. This time the Tool Creation dialog will have an additional section called paths.
4. Give the tool a name and description.

The new tool has been created. As we are aware as well as the two basic shapes, there are also 2 modifiers present on one of the shapes. These modifiers remain present in the tool. The function they perform remains unchanged; they influence the background colour and label text. However, the paths within the modifiers are changed.

All the paths are changed from some specific path to a path with contents of droppeditem.

The droppeditem path is a special path that is used when a tool is used with a context (as discussed in the previous tutorial). All the tools in the palette that have modifiers embedded have droppeditem paths and not the paths of the data items from which they were originally created.

When a tool is used (via the tools dialog in the previous tutorial) these droppeditem paths are subsequently replaced with the path of the drag and dropped item (hence the name). Upon replacement, the modifiers are evaluated and the properties of the objects in the tool instance updated with the matching data item properties.

Working with relative paths in dashboard tools Copied

In the previous tutorial we looked at how modifiers can be embedded into tools, and what happens with the paths when those tools are created and used. While this method is fine for simplistic tools it is limiting for more sophisticated use cases. Let’s consider the following:

We then create a tool as we have done before:

If we then use the tool by pulling in a different training course (via a cell in the course date column) then we get the result as shown in the figure:

It is unlikely that this is what the user of the tool expected or the designer of the tool intended. What has occurred is that all droppeditem paths have been replaced with the path of the cell we dragged into the dashboard, in this case the Course date. While this is fine for the date object (the white rectangle on the right of the tool), it is not correct for the colour and value on the available space object which has also been linked to the date cell (its grey because the course date has no severity).

What we need to do is build in additional logic to the dashboard tool, that modifies the paths at the point it is used, and directs the modifiers at paths relative to the dragged item, rather than the dragged item itself. This is quite a complicated statement, so let me try and relate it to the previous example:

This modification of the paths is achieved by changing the droppeditem paths in the tool with additional logic. The change can be done when the tool is first designed, or at a later date. We will review the change at design time first. The figure below provides a summary, but the full steps are then detailed below.

Rather than relying on the Dropped item path being added automatically on tool creation we are going to manually set it AND add additional logic to be applied when the tool is used. In this case replace the Column name with the correct one.

1. Before creating the tool (dragging it into the palette), go into the properties of the shape with the modifier whose paths you want to change when the tool is subsequently used.

2. Locate the path connected to the modifier, and edit the path via the path editor.

   1. Clear the path.
   2. Drag in the droppeditem URL component.
   3. Followed by the Replace URL component.
   4. Then the table cell element, which you will drop into the Replace element.
   5. You need to remove the Rows and Row elements, so now right click in the editor and toggle OFF the Auto Complete function.
   6. Now delete the Rows and Row element via the blue crosses in their top left hand corner.
   7. Click OK.
   8. The path will now be equal to droppeditem()/replace(/cell(@column=Course Date))

3. Click OK on the modifier dialog, and the dashboard object will update since now the path matches nothing.

4. We then repeat the process on the two modifiers on the Available space object, ending up with a path of droppeditem()/replace(/cell(@column=AvailableSpace)).

Paths embedded in modifiers that are already equal to droppeditem paths are NOT replaced or changed when the tool is created, this means that when we now create a tool from these objects the paths retain the logic we have just embedded (they are not replaced as in previous tutorials with a simple droppeditem path). We can prove this to ourselves by the following steps:

1. Having modified the paths in the tool as per the previous steps, create a tool out of these objects.
2. Now drag the tool from the palette back onto the dashboard, un-group the shapes and interrogate the paths in the modifiers, they should be as you defined them, with the replace logic still present after the droppeditem element.

For the record if you want to modify the paths at a later date you do this by dragging the tool from the palette into the dashboard, modifying the paths or shape design etc, then dragging it back in as a new tool. You would most likely remove the tool you originally used rather than have a duplicate.

When we now use the tool, the additional logic embedded in the paths takes effect:

1. You drag a cell from the data view onto the dashboard.
2. You select the new tool.
3. The tool is created, the droppeditem element is replaced as before with the path of the data item you dragged onto the dashboard.
4. The replace logic is then applied which tells the system to replace all instances of cell within the path with a new cell element containing the specified column name, therefore resulting in the correct path, be it modified from the one that was dragged in.

Understanding path modification in more detail Copied

In the previous tutorial we introduced how you can change and influence the paths embedded in the modifiers of a tool when it is used. This allows the creation of more complex tools which can link many relative data items into the same dashboard from a single drag and tool selection. We only discussed the Replace element, and even then did not really go into any detail about how it works. This section will provide more detail and narrative on this relatively complex subject.

Let’s look at the droppeditem element and each of the functions that can be used in conjunction with it.

Droppeditem Copied

The droppeditem path is replaced at the point a tool is used with the full path of the item dragged into the dashboard, such being droppeditem is replaced with the following:

/geneos/gateway[(@name="Support Training Management")]/directory/probe[(@name="Training Probe")]/managedEntity[(@name="Training Course Management")]/sampler[(@name="Training Courses")][(@type="")]/dataview[(@name="Training Courses")]/rows/row[(@name="4")]/cell[(@column="Course Date")]

Replace Copied

The replace element will literally replace all instances of the named element in a path. An example replace path:

droppeditem replace cell column=AvailableSpace

When the tool is used, there are two stages:

1. Switch out the droppeditem path

/geneos/gateway[(@name="Support Training Management")]/directory/probe[(@name="Training Probe")]/managedEntity[(@name="Training Course Management")]/sampler[(@name="Training Courses")][(@type="")]/dataview[(@name="Training Courses")]/rows/row[(@name="4")]/cell[(@column="Course Date")]/replace(/cell[(@column="AvailableSpace")])

2. Run the replace function

/geneos/gateway[(@name="Support Training Management")]/directory/probe[(@name="Training Probe")]/managedEntity[(@name="Training Course Management")]/sampler[(@name="Training Courses")][(@type="")]/dataview[(@name="Training Courses")]/rows/row[(@name="4")]/cell[(@column="AvailableSpace")]

So creating the final path. The replace function will remove the same named element completely and replace it with the one defined. Thus, if the original element had other predicates, they would be lost. For example:

/geneos/gateway[(@name="System Alerts")]/directory/probe[(@name="gateway")]/managedEntity[(@name="gateway")]/sampler[(@name="clientConnectionData")][(@type="Gateway")]/dataview[(@name="clientConnectionData")]/rows/row[(@name="2")]/cell[(@value>40)][(state("active")="1")][(state("snoozed")="0")][(@column="releaseAge")]

Then run the replace function:

/replace(/cell[(@column="AvailableSpace")])

You would get:

/geneos/gateway[(@name="System Alerts")]/directory/probe[(@name="gateway")]/managedEntity[(@name="gateway")]/sampler[(@name="clientConnectionData")][(@type="Gateway")]/dataview[(@name="clientConnectionData")]/rows/row[(@name="2")]/cell[(@column="AvailableSpace")]

Merge Copied

The merge function will take the predicates from the named element and insert them into all instances of the same named element. Take for example:

droppeditem()/merge(/cell[(state("snoozed")="True")][(@column="MyColumn")])

If run on this path:

/geneos/gateway[(@name="System Alerts")]/directory/probe[(@name="gateway")]/managedEntity[(@name="gateway")]/sampler[(@name="clientConnectionData")][(@type="Gateway")]/dataview[(@name="clientConnectionData")]/rows/row[(@name="2")]/cell[(@value>40)][(state("active")="1")][(state("snoozed")="0")][(@column="releaseAge")]

It would merge into the Cell element the @column and snoozed state, while leaving other predicates in the cell element unchanged, thus:

/geneos/gateway[(@name="System Alerts")]/directory/probe[(@name="gateway")]/managedEntity[(@name="gateway")]/sampler[(@name="clientConnectionData")][(@type="Gateway")]/dataview[(@name="clientConnectionData")]/rows/row[(@name="2")]/cell[(@value>40)][(state("active")="1")][(state("snoozed")="True")][(@column="releaseAge")]

Whereas the replace function would have removed the active status as well, the merge function simply builds the superset of predicates for the cell element. Where there is an existing predicate in the path and the same named predicate in the merge function, the entry in merge will take precedence.

Here is another example, in this case we are going to insert snoozed = 0 into the entity element:

droppeditem()/merge(/managedEntity[(state("snoozed")="0")])

If we run it on this path:

/geneos/gateway[(@name="Support Training Management")]/directory/probe[(@name="Training Probe")]/managedEntity[(@name="Training Course Management")]/sampler[(@name="Training Courses")][(@type="")]/dataview[(@name="Training Courses")]/rows/row[(@name="4")]/cell[(@column="Course Date")]

We get:

/geneos/gateway[(@name="Support Training Management")]/directory/probe[(@name="Training Probe")]/managedEntity[(@name="Training Course Management")][(state("snoozed")="0")]/sampler[(@name="Training Courses")][(@type="")]/dataview[(@name="Training Courses")]/rows/row[(@name="4")]/cell[(@column="Course Date")]

Append Copied

The append function is the simplest. It just adds the path fragment to the end of the dropped item path. For example:

droppeditem()/append(/managedEntity[(@name="MyEntity")]/sampler[(@name="MySampler")]/dataview[(@name="MyDataview")])

If run on this path:

/geneos/gateway[(@name="System Alerts")]/directory/probe[(@name="Myprobe")]

This would create the following:

/geneos/gateway[(@name="System Alerts")]/directory/probe[(@name="Myprobe")]/managedEntity[(@name="MyEntity")]/sampler[(@name="MySampler")]/dataview[(@name="MyDataview")]

Chaining together path modifications Copied

It is possible to chain together multiple path modifications into the same dropped item path. For example:

droppeditem()/append(/sampler[(@name="mySampler")]/dataview[(@name="myDataView")])/merge(/managedEntity[(attr("Country")="London")])/replace(/probe)

There are 3 operations here: an append, then merge, and a replace. They occur in order from left to right. So if we assume the dropped path was the following:

/geneos/gateway[(@name="Support Services")]/directory/probe[(@name="supportServices_probe001")]/managedEntity[(@name="Helpdesk Issues")]

First the append would be applied:

/geneos/gateway[(@name="Support Services")]/directory/probe[(@name="supportServices_probe001")]/managedEntity[(@name="Helpdesk Issues")]/sampler[(@name="mySampler")]/dataview[(@name="myDataView")]

Then the merge:

/geneos/gateway[(@name="Support Services")]/directory/probe[(@name="supportServices_probe001")]/managedEntity[(@name="Helpdesk Issues")][(attr("Country")="London")]/sampler[(@name="mySampler")]/dataview[(@name="myDataView")]

And finally, the replace:

/geneos/gateway[(@name="Support Services")]/directory/probe/managedEntity[(@name="Helpdesk Issues")][(attr("Country")="London")]/sampler[(@name="mySampler")]/dataview[(@name="myDataView")]

Sharing tools Copied

As you may now have gathered the process of creating tools is an advanced function of the console. It exists specifically to stop basic users having to create dashboards from scratch but rather work from tools. For this to be practical tools need to be shared. This is fairly easy to achieve as described in this section.

Exporting tools Copied

Select the tools you want to export in the palette. If there are many tools, hold down CTRL during selection. Then right-click on one of the selected tools and select Export tool. This creates an .adt file.

Importing tools Copied

To import tools, go to File > Import in the console and select the .adt file. Note that tools cannot have duplicate names, so if this would be the case the new tools have a name extension equal to an incremental number.