This tutorial provides details on how to create your own tools within The Active Console 2 Dashboard.
Note that 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
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.
- Firstly create a couple of simple shapes as below
Figure 1
2. Then area select around all the shapes
3. And 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 therefore to drag shapes outside the dashboard and into the palette.
Figure 2
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
Figure 3
6. Give the tool a suitable name (this will appear in the palette and the tool selection dialog's), and a description (which will appear in the tool tip 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 (I.E. 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.
Figure 4
8. If you save the work space 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 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 which creates types of objects which will always be of that type.
TIP: 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 then hold down the ALT key and right click on the object of choice, this will by pass the group allowing you to get to the lower level object properties. |
A SECRET: 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 work space. 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
The shape we created in the first tutorial does not have any connected modifiers, and thus its properties (colour, label text etc) 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 this lets try out some modifiers outside the scope of tools.
- Drag a cell (with a severity colour) onto one of the dashboard objects we created previously,
- when the dialog appears select the modifiers tab
- Hold down control and select the following modifiers from the list
- Link Background colour to severity
- Label text linked to data items value
- Then click ok
Figure 5
The changes will be applied, with the shape turning the colour of the severity and the text changing to the cell value. Now lets inspect what changes occurred to the shape.
5. Ungroup the shape, by right clicking on it and selecting arrange --> ungroup (it may already be un grouped in which case ignore this step)
6. Now right click on the shape you put the modifiers on and select 'Properties', go to the modifiers section.
Figure 6
As you will see from the modifiers section there will be one modifier entry for each modifier we selected via the dialog. The path(s) to the matching data items will be equal to the data item that we dragged top of the shape. As the severity and value of the connected cell changes, so will the shape, via the modifiers.
A couple of points to note on this:
- This can be achieved manually by going into the modifier dialog and adding modifiers and paths, but its fiddly and error prone when compared with the drag and drop method
- Only one modifier can be present for any given property of the shape. For example if you link its background colour to a cell, and then drag and drop another cell and select a modifier that changes background colour, then the second will replace the first since only one modifier can exist for background colour.
- You can modify the paths connected to a given modifier, generally this would be to broaden the number of matching data items for a modifier. Where this is the case:
- The highest Severity is taken
- A comma separated list of values will be used where they are multiple matches if the text is being influenced
Dragging data items onto the dashboard (using a tool with a context)
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 etc), and then select a tool for how to represent that item.
- To use a tool drag a data item from the state tree onto the dashboard
- a tool selection dialog will appear from which you should select a tool
- Click ok, then the representation will be created.
Figure 7
In the background the dashboard is creating an instance of the tool (in the same way as when 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 items name. These mapping 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 drag 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
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.
- Assuming you have followed the instructions so far you will have an instance of a tool (un-grouped) with two modifiers on one of the shapes. (as shown in figure 6).
- Now enter 'Tool Creation Mode' again, area select around your shapes and drag them into the palette to create a new tool.
- This time the Tool Creation dialog will have an additional section called paths.
- Give the tool a name and description
Figure 7
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, I.E. 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'.
Figure 8
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.
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. lets 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 below.
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 example above:
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.
- 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
- Locate the path connected to the modifier, and edit the path via the path editor
- Clear the path
- Drag in the 'droppeditem' URL component
- followed by the 'Replace' URL component
- then the table cell element, which you will drop into the 'Replace' element
- You need to remove the Rows and Row elements, so now right click in the editor and toggle OFF the Auto Complete function
- Now delete the Rows and Row element via the blue crosses in their top left hand corner
- Click OK
- The path will now be equal to droppeditem()/replace(/cell[(@column="Course Date")])
- Click OK on the modifier dialog, and the dashboard object will update since now the path matches nothing
- We then repeat the process on then 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:
- Having modified the paths in the tool as per the previous steps, create a tool out of these objects
- 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:
- You drag a cell from the data view onto the dashboard
- You select the new tool
- The tool is created, the 'droppeditem' element is replaced as before with the path of the data item you dragged onto the dashboard
- 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
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 relativity complex subject.
Lets look at the 'droppeditem' element and each of the functions that can be used in conjunction with it
Droppeditem
The 'droppeditem' path is replaced at the point a tool is used with the full path of the item dragged into the dashboard. I.E.
droppeditem
is replaced with
/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
The replace element will literally replace all instances of the named element in a path, An example replace path may be:
droppeditem()/replace(/cell[(@column="AvailableSpace")])
When the tool is used there are therefore two stages
- Switch out the dropped item path
- droppeditem --> /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")])
- 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")]
- /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 completed and replace it with the one defined. Thus if the original element had other predicates they would be lost, I.E.
/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
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(s) 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")]
Where as the Replace function would have removed the Active Status as well the merge function simply builds the super set 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 a Snoozed = false into the entity element:
droppeditem()/merge(/managedEntity[(state("snoozed")="0")])
If we run it on this path then
/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
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")]
would create
/geneos/gateway[(@name="System Alerts")]/directory/probe[(@name="Myprobe")]/managedEntity[(@name="MyEntity")]/sampler[(@name="MySampler")]/dataview[(@name="MyDataview")]
Chaining together path modifications
It is possible to chain together multiple path modifications into the same dropped item path, for example take the following
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 finally a replace. they occur in order from left to right, so if we assume the dropped path was
/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
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
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
To import tools go to file --> import in the console and select the .adt file. Note tools cannot have duplicate names, so if this would be the case the new tools have a name extension equal to an incremental number.
Comments
0 comments
Please sign in to leave a comment.