Customizing Dovetail Agent

November 18, 2016

Adding customizations in Dovetail Agent, as of version 13, incorporates numerous changes that make the application easier to customize and extend.

Stepping through a simple example will demonstrate how those changes make it easy to add a customization.

 

Overview

This example shows a customization to enhance the console, adding some eye-catching color for Cases that have a severity level that needs attention. If a Case has a Medium severity, the row should be pink, orange for a High severity Case, and if a Case severity is Urgent, then make the row red.

By default, all rows in the console have a white background, so adding some colors will make those cases stand out. Cases with severity levels below Medium will still have the white background.

 

Roadmap

To accomplish this customization, the Cases with raised severity shown in the Case grid on the console need to have an extra CSS class. That class will override the background color of the grid row. The Case grid is a simple HTML table, and it has a TR element for each Case that is displayed. Adding a class to the TR element will allow the entire row background color to be changed. With that as the goal, there are three things that need to be customized:

1. add a CSS entry for each Severity color
2. add a data element for each Case that denotes a raised Severity level
3. add the class name to the TR element for each Case that has a raised Severity level

 

Adding the CSS entries

Starting with Dovetail Agent version 11.1, a folder was added to hold all of the custom CSS files.

\styleguide\styles\less\custom

In that folder, there is a custom-styles.less file, and that file is where the new CSS entries will be added. For the different Case severities, these are the custom class styles that will be used for the grid rows:

.a5-medium { background-color: rgba(255, 255, 0, 0.3); }
.a5-high   { background-color: rgba(255, 165, 0, 0.3); }
.a5-urgent { background-color: rgba(255, 0, 0, 0.3); }

Adding the extra data for each Case

Starting with Dovetail Agent version 13, filter queries were implemented to provide data for the console grid. For each tab of the console grid, there is a filter query that builds the data used to populate the grid, and it is very easy to extend as a customization. For this example, a custom filter config override will be used to extend the data query.

<filter overrides="Cases">
  <values>
    <addValue key="severityClass" value="{severity}" />
    <addTransform key="severityClass">
      <mapValues>
        <addMap from="Medium" to="a5-medium" />
        <addMap from="High" to="a5-high" />
        <addMap from="Urgent" to="a5-urgent" />
      </mapValues>
    </addTransform>
  </values>
</filter>

The override configuration shown above extends the filter for the case results. Adding a value based on Case severity level allows the data to be transformed to meet the data requirements for this customization. In this override, the severity value is transformed from its string value to a class name, i.e. “Medium” to “a5-medium”. Looking back at the CSS elements that were added, these transform statements correspond to those class names.

 

Using the extra data in the Console Case Grid

The last piece of this puzzle is to get the new filter data into the console grid, so the class name is there for a row when the Case severity level indicates that the row needs to be color highlighted.

In Dovetail Agent version 11.1, the ability to customize the baseline JavaScript code modules was made much easier. Instead of modifying the baseline code, it can be extended instead.

The baseline code for the rows in the console grid is found in the RowView.js file. The full path for that file is:

source/Agent.Console/content/scripts/app/console/grid/views/RowView.js

That is important to know for the customization, because to extend that file, it needs to be imported in the customization. It also indicates where the customization file should be placed, since the folder structure needs to replicate that baseline path. The correct location for this customization is:

source/custom/content/scripts/app/console/grid/views/RowView.js

Creating that file in the proper location will ensure it is included when the JavaScript files are bundled together for the application. The actual customization code is pretty simple, and the complete file is shown below:

import RowView from 'override/console/grid/views/RowView';

const CustomRowView = RowView.extend({
  className() {
    const severityClass = this.model.get('severityClass') || '';
    return `a5-row ${severityClass}`;
  },
});

export default CustomRowView;

The first line of the code imports the baseline version of RowView.js. For this customization, the only feature that needs to be modified is the className. The severityClass value is added to the default a5-row class, and if there is a value there the background of the Case row will be different. The new CustomRowView is exported, and will be included in the application.

 

The New Console Case Grid

Now that all the customization work has been done, the console Case grid should look like this:

The Case rows where the severity is Medium, High, or Urgent are now highlighted as expected.

 

Wrap Up

With just a few additions to the customizable aspects of Dovetail Agent, the console Case grid was modified without any changes to the baseline code. Having the customization in its own areas allows for easier Dovetail Agent upgrades, and better support for new features.

Pretty cool stuff.