Cockpit

Knowage allow end users to self-build interactive cockpits through an intuitive and interactive interface, with a few clicks and simple drag and drop. This allows you to compose your analytical documents with multiple widgets and define associations among them, so that clicking on one widget data are automatically updated in other widgets.

../../_images/image1353.png

Cockpit document example.

It enables data mash-up to integrate enterprise data and externally sourced data.

Cockpit documents can be created and executed both by technical users and end users and are part of Knowage ad-hoc reporting system. A key aspect is that different widget can rely on different datasets and hence on different data sources. The only requirement needed to define associations between two or more datasets is the presence in each of them of one or more columns containing the same data.

Warning

Section structure exception

Since there are no differences between the cockpit interface reached by a final user and the one reached by a technical user, the cockpit designer is described in one unique My first Cockpit for both those kind of users. By the way, when necessary we will highlight how the same functionality can be exploited accordingly to the user’s role.

My first Cockpit

You can create your new Cockpit from the Analysis area of the Workspace by clicking on the “Plus” icon and selecting Cockpits if you enter Knowage Server as final user, while you can enter the document browser and start a new cockpit using the “Plus” icon if you enter Knowage Server as admin.

Important

Reaching the cockpit designer

We stress that the cockpit interface is reached by the final user and the administrator following two different paths.

Let us see how to build a cockpit and how the interface is displayed within the server. Once opened, the cockpit interface is an empty page with a toolbar containing different options described in Table below.

Cockpit editor toolbar.

Icon

Name

Function

../../_images/image1363.png

Cockpit menu

Configuration menu of Cockpit.

../../_images/image1373.png

Add widget

It opens a window where you can create a new chart or table, add texts, images or Knowage documents.

../../_images/image1382.png

General configuration

It opens the window where you set the general cockpit options (name, label, show menu, etc.) and widget style (header, titles, borders, etc.).

../../_images/image1392.png

Data configuration

It opens a window where you can manage the dataset, the association between datasets and the refresh frequency.

../../_images/image1405.png

Selections

It adds a widget that manages selections.

../../_images/image1415.png

Clear Cache

It cleans temporary data.

../../_images/image1424.png

Save as

It opens the window to save the cockpit document as a new document.

By clicking the button Add Widget you can add a widget containing a Text, an Image, a Chart, a Table, a Cross table, a Document,the Active selections or the Selector to your cockpit, as shown below.

../../_images/image143_bis1.png

Widget Type.

In the following we go into details of each available widget.

Text widget

By clicking the button Text Widget you can add text to your cockpit. As shown in figure below, the widget editor opens and it is divided in three tabs: the Text editor, the Style, the Dataset and the Filters tab.

../../_images/image1443.png

Text editor of text widget configuration.

On the “Text editor” tab you can type the desired text in center panel and customize it. Using the dataset tab it is possible to associate dataset values to the text and read it real time at each execution. Move to the dataset tab to add a dataset to the widget. Then, going back to the Text editor tab, the user will find the dataset columns on the right side, as well as a set of functions to eventually apply to the fields. We summed up main steps in the Figure below. To add a function to a measure first select the desired function and then the field of numeric type.

../../_images/image14546471.png

Editing a dynamic text.

It’s also possible to add variables values if at least one of them is defined. During the execution of the widget the value will be displayed based on the current variable value.

../../_images/image144b1.png

Variables in text widget.

On the “Style” tab you can customize the text widget. We have provided all details about this tab in the Table widget. On the “Dataset” tab you can add more dataset to be used in the dynamic value. Finally, the “Filters” tab can be used to extract limited output from the dataset. We put details off to the table widget subsection.

Image widget

By clicking the button Image Widget you can add images to your cockpit. As already seen the widget editor opens and it is divided in three sections.

On the Gallery tab you can upload an image, delete it or select one from the gallery. Refer to the following figure.

../../_images/image1482.png

Gallery tab of Image Widget Configuration.

On the Style tab you can configure the style of your image widget with the different options offered by this tab. Many of them are defined in the table widget that you will find later.

On the Cross tab you can define navigation to another document, as shown in figure below.

../../_images/image1492.png

Cross tab of Image Widget Configuration.

Warning

Cross navigation only for technical users

Due to the fact that parameters can only be managed by a technical user the cross navigation cannot be implemented by the final user.

For this purpose, you must activate Enable cross navigation flag and select the destination document through the list of cross navigation definition. This last flag is optional. If you select a cross navigation definition, when you launch the cross navigation it will go to the document of arrival directly. If the cross navigation definition is not defined, then when you launch the image widget cross navigation will be shown a pop up (refer to figure below) with the list of cross navigation definition that exist for this cockpit.

../../_images/image1503.png

Cross navigation multiple choices.

Chart widget

Charts are an essential representation of data, Knowage let you use many different charts type and configure them according to your needs. We have provided all details about charts type and configuration in Chart chapter.

We recall that also for chart widget it is possible to set cross navigation on elements.

Warning

Cross navigation only for technical users

Due to the fact that parameters can only be managed by technical user the cross navigation cannot be implemented by the final user.

As shown in next figure, it is mandatory to enable the cross navigation feature by using the dedicate tab of chart editor GUI. It is mandatory to choose the column element to be passed to the destination document and associate it to the right output parameter (previoulsy added to the document using the detail interface).

The cross navigation name can be left empty. In case multiple cross navigation definitions have been configured for the document, a pop up will be displayed, letting the user to choose which destination to reach (exactly as we saw earlier for Image widget in the last figure of that paragraph).

../../_images/image1514.png

Cross navigation for chart widget.

In addition, if the navigation expects other parameters to be passed, use the bottom part of the page to add the additional parameters. Figurebelow shows an example.

../../_images/image1523.png

Add all output parameters involved in the cross navigation.

It is also possible using Solr datasets and calculated fields with charts.

Dataset fields editing and configuration is possible using the first tab inside widget edit mode, in this way, for example, users can modify aggregations for measures:

../../_images/image152b1.png

In this way it is possible adding new calculated fields on chart by clicking on “Add Calculated field”, the standard calculated field editing mode will appear.

../../_images/image152c1.png

Adding new calculated fields is easy as using other measure fields, using Chart Engine Designer structure tab:

../../_images/image152d1.png

Table widget

The Widget table configuration opens and it guides you through the steps to configure the widget. The pop up opens showing the column tab, as you can see from Figure below. In details, it is mandatory to select a dataset using the combobox (only if at least one dataset has been loaded using the Data Configuration feature) or clicking on the icon image156 available just aside the combobox line. You can page the table specifying the number of rows per sheet. Consequently the user can set columns properties.

../../_images/image1543.png

Table configuration window.

In fact, the column area is divided into two parts: on the upper part there are the buttons to add a new column or a calcutated field. Also the new functionality of column grouping is available here. In the lower section, as soon as the dataset is selected, you can indicate the sorting column or modal selection column. The modal selection serves to specify which value will be passed to other widgets (if interaction is enabled) when clicking on the cell at document execution time. You can specify this field by selecting a value from the combobox. In the same way, you indicate the sorting column and the order type that steers the rows ordering. You can select the field and the order from the dedicated comboboxes.

When a dataset is added to a table widget, all of its columns are listed below. If the user doesn’t wish to show some of them, he can use the delete button available at the end of each column row, as shown below.

../../_images/image1552.png

Delete a column.

In case of accidental cancellation or new table requirements, it is possible to re-add columns. In order to add a new column you have to click on the Add Column icon on the top right of the second box. Once opened you can select one or more columns. When you have finished selecting the desired columns you can click on save button and your new columns will appear in the field list. Refer to Figure below.

../../_images/image1561.png

Add a new column.

Manage Columns Groups will open a menu to add or remove columns groups and to set their style. A column group is a container for more than one column that will show a common header between them.

../../_images/image156b1.png

Example column group.

Likewise, to add a calculated field you have to click on the Add Calculated field icon next to add column icon. Once opened the Calculated Field Wizard you have to type an alias for your calculated field in the dedicated area at the top corner of the wizard. Then you can choose from the left sinebar list the fields that you want to use in your formula. You can also use arithmetical functions or use the functions available in the menu (aggregations, column totals, variables). If you prefer you can create or modify the expression manually directly in the editable panel. When you are satisfied with your expression you can click on validate to check your formula sintax or save button and your calculated field appears in the field list. We provide an example in the following figure.

../../_images/image1571.png

Add a calculated field.

You can choose between dataset-level behaviour or table-level (default), that is the calculation modality that will involve table fields or dataset columns to get the result. If you choose dataset-level behaviour the calculation result will be done at dataset columns level only and the aggregation will involve the entire result of the calculation.

../../_images/image157b.png

Dataset-level behaviour

If Dataset is of type Solr, the columns displayed on the right panel are dataset columns fields and the calculated field formula elaboration is calculated on the fly.

../../_images/image158b1.png

If variables are set for the present cockpit, the variable menu button will appear, making it possible to add variable values in the calculated field expression.

../../_images/image157c1.png

Variables menu

In the bottom section of the window, you can see the table fields (with their aggregation type) listed and you also can sort columns displayed in the table by dragging them up or down, insert a column alias and customize it by adding font and style configurations using the brush shaped icon, as you can see from figure below. Here you can find configuration features to adjust the column size, max cell characters, hide column or column header options, and the row spanning toggler.

../../_images/image157d1.png

Columns Settings

If you hide the column (from this view or from the column list), the column will not be visible, but will still be used for aggregation purposes. If you enable the row span feature, all the same visible values of the column will be collapsed in one, to avoid repetitions.

If the column is a measure, more functionalities will become available:

  • Inline chart mode: you can choose the visualization type of the measure, and if you choose chart and maximum/minimum values, a chart will appear in the view to represent the cell measure.

  • Thresholds: you can choose to set some thresholds that will trigger font color, background color or will show icons if the chosen condition is satisfied.

  • Format: you can choose the prefix, suffix and the precision (i.e. 9.8 m/s). Please be aware that the data will be formatted following the locale of the user. Otherwise you can choose to treat it as string.

../../_images/image1582.png

Column settings.

Note that here you can indicate the column type and the aggregation. To add an aggregation to a column you must control the type of data that column has. An aggregation can only be added if the column value is of “number” type . The different aggregation functions are: none (you also can not add any aggregation function), Sum, Average, Maximum, Minimum, Count and Count distinct.

If a column group has been set another option will become available in order to set the optional group belonging of the column.

For all the columns, if at least one variable is set, the variables settings box will appear. Depending on the variable usage it will be possible to set a dynamic header or to hide the column conditionally.

../../_images/image158c1.png

Variable settings box.

Clicking on the plus button you can add one or more conditions. The possible actions are:

  • Hide column: the column will be shown conditionally depending on the condition set.

  • Set column header name: the column name will be replaced by the variable value.

Multiple conditions can be set, but a condition fullfilling the “=” will have higher priority.

../../_images/image158d1.png

Variable action set.

The Style tab is where you can customize the table by using the different options of style. It is divided into eight parts:

  • In the Summary section you can show the total of the column and customize it by typing the summary name and using font and style configurations. Refer to Figure below.

../../_images/image1593.png

Summary section of the Style tab.

  • In the Rows section you can set the table rows to be adapted in automatic or select a fixed height. You can also show the total of rows. While the multiselectable option allows you to select multiple values and pass them to other cockpit widgets or other external documents. Refer to figure below.

../../_images/image1603.png

Rows section of the Style tab.

  • In the Grid section you can add borders to the table and add color to alternate rows. In this section you can find different options to customize them. Refer to figure below.

../../_images/image1612.png

Grid section of the Style tab.

  • In the Header Style section you find the different options of style for the table header. Refer to Figure below.

../../_images/image1623.png

Header style section of the Style tab.

  • In the Titles section you can add the titles to the widget and modify the font size and weight. In this section you can also change the height of the widget title. Refer to Figure below.

../../_images/image1632.png

Titles section of the Style tab.

  • In the Borders section you can add a border to the widget and customize it by using the colors, thickness and style. Refer to the following figure.

../../_images/image1642.png

Borders section of the Style tab.

  • In the Other Options section you can add the shadows in the widget, you can set the background color of the widget and it is possible to disable or enable the screenshot option for that particular widget. Refer to the following figure.

../../_images/image1653.png

Other Options section of the Style tab.

Once the table style settings have been implemented you can switch to the next tab. The “Cross” tab is where the navigation to other documents is defined. It is visible to final users but yet only configurable by a technical user (like an administrator).

Finally, the “Filters” tab is where you can filter the table results by adding a limit to the rows or a conditions in the columns. the following figure shows an example of how to set the limit rows or a conditions on dataset columns.

../../_images/image1683.png

Filters tab of the table widget configuration.

Once you have finished setting the different configuration options of the table widget, then just click on “Save” and your new widget is displayed inside the cockpit.

Cross Table widget

Similar configurations are available also for the Cross Table widget. In this data visualization option, you still have the tabs: Dataset tab, Configuration tab, the Style tab and the Filters tab as you can see below.

../../_images/image1693.png

Dataset section of the crosstab widget configuration.

Using the “Dataset” tab the user can add the dataset to take values from. Consequently, it is necessary to select the fields you wish to appear as columns, those as row and measures to be exhibited in the pivot table. See figure below. Remember to set column and row fields as attributes, while measure fields as numbers.

../../_images/image1703.png

Selecting columns, rows and measures of the crosstab.

There is also the possibility to add calculated fields as measures clicking on the “Add calculated field button”. The calculated field will work exactly as in the table widget. After creating a calculated field there will be the possibility to edit, remove it or set the properties for it’s column clicking on the new measure buttons.

../../_images/image170b1.png

Calculated field detail.

Once the columns, rows and measures have been selected the style of each column can be set by clicking on the cog settings icon. A popup will open with different options for the selected columnn. See figure below.

../../_images/image2101.png

Column style popup.

It is possible to sort the crosstab according to the values of the selected column or, alternatively, according to columns not visible in the crosstab. It can also be set the style of the column, such as the font size, the font weight or the cell alignment. There is also the possibility to specify the size of the column in pixels (you can also use percent values but it is better to use pixels).

In case the selected column is of type measure, there is a dialog to configure the behaviour of that field:

../../_images/image4901.png

Measure configuration dialog.

A particular option for a measure is Exclude from Total and SubTotal: that checkbox excludes the measure from the sums of Total and SubTotal fields makin the relatives table cells empty.

../../_images/image2113.png

Measure threshold setting.

As figure above shows, you can also manage threshold. For measures only, it is possible to associate a particular icon or a specific background color to a particular measure’s value or range. To do so add a new threshold, set a condition for it to appear, and choose the icon from the list or select the color that will be changed to the cell. It is possible to add more or to remove thresholds using the add or delete button.

../../_images/image211c1.png

Variables header value.

If one or more variables are set, in column and measure settings another field will appear. It is possible to set the header name to be dynamic using one of the variables set. If one of the variables are selected in the combo as in example, the header name will be changed depending on the current variable value.

../../_images/image211b1.png

Column style.

It’s also possible to set style elements for both attributes and measures. In measures will also be possible to set the precision and prefix/suffix of the cell value. The comma and dot used for decimals and thousands will be automatically changed depending on user’s locale.

Once the dataset has been properly configured, you can proceed to the “Configuration” tab.

The latter is made up of three sections: General, On rows and On columns, as Figure below shows.

../../_images/image1713.png

Configuration tab interface.

In the “General” section you can set the following features:

  • define the maximum cell number to show;

  • decide to hook measures to columns or rows;

  • decide to show percentages of measures related to columns or rows.

Thanks to the “On rows” feature, you can easily compute totals or subtotals on rows. Figure below exhibit an example.

../../_images/image1723.png

Computing totals and/or subtotals on rows.

Otherwise, thanks to the “On columns” feature, you can easily compute totals or subtotals on columns. Figure below exhibit an example.

../../_images/image1734.png

Computing totals and/or subtotals on columns.

Selecting the “Hide rows on just null values” will hide all the rows with just 0 or null values, avoiding space waste if unneeded.

The “Fix attribute’s columns” will pin to the left the columns containing the attributes, so side scrolling will be available without losing those columns.

../../_images/image173b1.png

Pinned columns example.

The “expand/collapse” functionality will add a + and - button in your rows, in order to easily aggregate your data. In the widget menu you will also find the expandall/collapse all buttons, in order to reset closing or opening your whole widget.

Be aware that to use this functionality columns subtotal should be selected. If not the functionality check will enable it automatically.

../../_images/image173c1.png

Expand/collapse example.

Switching to the “Style” tab you can find the general style settings available for the crosstab.

  • Crosstab General Options where the rows’ height, the general font and font size can be set; in particular, the layout combo determines how the columns resize themselves in respect of the contained value;

../../_images/image1743.png

General style options for crosstab.

  • Crosstab Headers Font Options where you can configure the header style settings as color, background, font, etc.

../../_images/image1753.png

Crosstab Headers Font Options for crosstab.

  • Measures Font Options where you can configure several style options for measures, such as color, background, font size, etc.

../../_images/image1764.png

Measures Font Options for crosstab.

  • Using the Grid section you can mark (or not) grid borders, decide for border style, thickness and color. You can also alternate row indicating different colors.

../../_images/image1774.png

Grid Options for crosstab.

  • In the Measures Headers section you can configure different style option for measure headers, such as color, background, font size, etc.

../../_images/image1782.png

Measures Headers Option for crosstab.

  • In the Total section you can set color and background of totals (if any).

../../_images/image1792.png

Color settings for Totals.

  • In the Subtotal section you can set color and background of subtotals (if any).

../../_images/image1801.png

Color settings for Subtotals.

  • In the Titles section you can add titles to widget and customize them using different styles.

../../_images/image1813.png

Title settings.

  • In the Borders section you can add borders to widgets and customize them using different styles.

../../_images/image1821.png

Border settings.

  • In the Other Options section you can add a shadow to widget layout and indicate its measure, color the widget background at convenience and it is possible to disable or enable the screenshot option for that particular widget.

../../_images/image1831.png

Other Options for crosstab.

Once some or all (at least the mandatory) of the above mentioned setting features have been set you can save and the widget will be inserted into the cockpit area.

../../_images/image4981.png

Cross navigation for cross table widget.

In addition to other cross-navigations, for cross table widget it is possible to set as a dynamic value the name of the selected measure column or the selected category. The choice is available from the combobox.

Document section

The Document widget allows to add an external document into the cockpit area. This widget supports documents like reports, graphs, maps, etc.

Use the Data configuration button to add a document source to the cockpit. Click on the “Plus” icon on the right half of the page to choose among all available documents.

The Document Widget configuration is divided into two parts: Custom tab and Style tab as you can see from Figure below.

../../_images/image1851.png

Custom tab of the Document widget.

The Custom tab is the place where the document is uploaded while the Style tab is where all style options are set.

Selection widget

This widget is related to the association concept so in this subsection we give information on how to add and custom the Selection Widget into the cockpit area and its functioning, while we refer to the dedicated Document section for details on how to set (global) associations.

To enable the Selection widget, which means the possibility to have all associations listed and accessible on a widget, the user must open the “Selection” feature through the “Add widget” functionality and configure the demanded options. Figure below shows the “Selection widget configuration” interface.

../../_images/image1861.png

Selection widget configuration.

The Selection Widget will display the elements selected by the user. Figure below shows an example.

../../_images/image1871.png

Selection widget outlook.

If global associations have been set, clicking on table, cross table or chart elements will update all corresponding widgets. Otherwise, only the widget on which selection has been made Selector Widget will be updated. In both cases the Selection widget will display the highlighted attribute values.

Selector Widget

The Selector Widget is useful when an end user (a user with a USER tole type) wants to add a parameter to the document.

Note

Selector widget

A technical user can use the association with an Analytical Driver to filter on cockpit.

../../_images/image1881.png

Selector widget outlook.

In detail, use the Columns tab to select the dataset and the dataset column on which you want to apply the filter. Then custom the Select modality options; for instance, choose between single or multivalue or to use a list or a combobox. Note that for the list option you can further choose among “vertical”, “horizontal” or “grid”. You can also decide to add a default value, chosen from main column’s first item, main column’s last item or to simply assign a static value. Finally, by clicking on the Wrap Text option it is possible to wrap the text shown in the selector; this option is useful when the categories to choose from are sting of long dimensions.

In the case of the selector of type list “grid” it is also possible to set the grid columns width.

../../_images/image3041.png

Grid columns width.

Move to the Style tab to set the widget style in terms of: label, titles, borders, shadows and background color. Figure below shows a customization example.

../../_images/image1891.png

Selector widget configuration.

Finally use the Filters tab to handle pagination or filter on a dataset column.

../../_images/image1901.png

Selector filters.

The Selector widget works effectively as a ready-to-use filter panel.

../../_images/image1912.png

Selector widget execution example.

HTML Widget

The HTML widget allows to add customized HTML and CSS code to add very custom dynamic elements to the cockpit. This widget supports all HTML5 standard tags and CSS3 properties.

Warning

For security reasons no custom Javascript code can be added to html tags. Every tag considered dangerous will be deleted on save by the filter.

The Edit section of the widget is composed by five tabs: the dataset, HTML editor, style, cross and filters. In the editor tab is possible to add the code that will be shown in the widget. Clicking on the top expander section in the tab, the one named “CSS” also the CSS editor will be available.

Important

A CSS property will be extended to all the classes in the cockpit with the same name, to apply the property only to the current widget use the id prefix shown in the info panel of the CSS editor

../../_images/image2081.png

HTML widget editor

In the right side of the editor is possible to take available tags to copy inside the code, those tags will be explained in details in the following paragraphs. Is not possible to add custom JavaScript code inside the html editor, so the available tags are the tools to make the widget dynamic and to use the dataset data.

The Dataset tab allows the user to select a dataset to make the Widget dynamic and to bind it to dataset data. After choosing a dataset the list of available columns will be show. Those names will be useful inside the dynamic tags. Here it is also possible to order the dataset according to a column and to select the ordering type (ascending or descending).

../../_images/image2091.png

Dataset selection

By clicking on the icon image302 of a specific column the dataset will be ordered by that column by default by ascending order. In order to select the descending ordering type you have to click another time on the icon (the icon will be now like this image303).

Available Tags

[kn-column='COLUMN-NAME' row='COLUMN-ROW-NUMBER' aggregation='COLUMN-AGGREGATION' precision='COLUMN-DECIMALS']

The kn-column tag is the main dynamic HTML Widget tool, it allows to select a column name from the selected dataset and to print its value. The value of the kn-column attribute should be the name of the column value you want to read in execution.

The row attribute is optional and is a number type attribute. If no row is selected the first row column value will be shown.

The aggregation attribute is optional and is a string type attribute. If inserted the value shown will be the aggregation of all column rows values. The available aggregations are: AVG|MIN|MAX|SUM|COUNT_DISTINCT|COUNT|DISTINCT COUNT.

The precision attribute is optional and is a number type attribute. If added and if the result value is a number, the decimal precision will be forced to the selected one.

[kn-parameter='PARAMETER-NAME']

The kn-parameter tag is the tool to show a dataset parameter inside the widget execution. The value of the kn-parameter attribute should be the name of the set attribute.

[kn-calc=(CODE-TO-EVALUATE) precision='VALUE-PRECISION']

The kn-calc tag is the tool to calculate expressions between different values on widget execution. Everything inside the brackets will be evaluated after the other tags substitution, so will be possible to use other tags inside.

The precision attribute is optional and is a number type attribute. If added and if the result value is a number, the decimal precision will be forced to the selected one.

<div kn-repeat="true" limit="LIMIT-NUMBER"> ... REPEATED-CONTENT ... </div>

The kn-repeat attribute is available to every HTML5 tag, and is a tool to repeat the element for every row of the selected dataset.

This attribute is naturally linked to kn-column tag. If inside a kn-column tag without a row attribute is present, the kn-repeat will show the column value for every row of the dataset.

Inside a kn-repeat is possible to use the specific tag [kn-repeat-index], that will print the index of the repeated column row.

The limit attribute is optional and is a number type attribute. If added the number of row repeated will be limited to the selected number. If no limit is provided just the first row will be returned. If you want to get all records, you can set it to -1, but be careful because big datasets can take a while to load completely.

<div kn-if="CODE-TO-EVALUATE"> ... </div>

The kn-if attribute is available to every HTML5 tag and is a way to conditionally show or hide an element based on some other value. The attribute content will be evaluated after the other tags substitution, so will be possible to use other tags inside. If the evaluation returns true the tag will be shown, otherwise it will be deleted from the execution.

<div kn-cross> ... </div>

The kn-cross attribute is available to every HTML5 tag and is a way to make the element interactive on click. This attribute generates an on click event on the element to open the cross navigation set. If there is no cross navigation set this tag will not work.

<div kn-preview="DATASET-TO-SHOW"> ... </div>

The kn-preview attribute is available to every HTML5 tag and is a way to make the element interactive on click. This attribute generates an on click event on the element to open the dataset preview dialog. The attribute value will be the dataset label of the dataset that you want to open. If a dataset is not specified the cockpit will use the one set for the widget. If no dataset has been set and the attribute has no value this tag will not work.

<div kn-selection-column="COLUMN-NAME" kn-selection-value="COLUMN-VALUE"> ... </div>

The kn-selection-column attribute is available to every HTML5 tag and is a way to make the element interactive on click. This attributes generates an on click event on the element to set the chosen column and value in the cockpit selections. The default will use as a selection the first row value for the column.

The kn-selection-value attribute is optional and will add a specific value to the column selection.

[kn-variable='VARIABLE-NAME' key='VARIABLE-KEY']

The kn-variable tag is the tool to read the runtime value of one of the defined variables. It will change depending on the current value and can be used inside kn-if and kn-calc.

The key attribute is optional and will select a specific key from the variable object if the variable is “Dataset” type, returning a specific value instead of a complete dataset.

Warning

Banned Tags In order to avoid Cross-site scripting and other vulnerabilities, some tags are not allowed and will automatically be removed by the system when saving the cockpit:

  • <button></button>

  • <object></object>

  • <script></script>

If you need to simulate a button behaviour use a div (or another allowed tag) and replicate the css style like in the following example:

1<div class="customButton">Buttonlike div</div>
1.customButton {
2     border: 1px solid #ccc;
3     background-color: #ededed;
4     cursor: pointer;
5 }
6 .customButton:hover {
7     background-color: #d8d8d8;
8 }

Warning

Whitelist Base paths to external resources (images, videos, anchors, CSS files and inline frames) must be declared within TOMCAT_HOME/resources/services-whitelist.xml XML file inside Knowage Server, otherwise those external links will be removed by the system. This whitelist file contains safe and trusted websites, to restrict end users of providing unsafe links or unwanted web material. Knowage Server administrator can create or edit it (directly on the file system) to add trusted web sites. Here below you can see an example of services-whitelist.xml file; as you can see, its structure is quite easy: baseurl attributes refer to external services, relativepath must be used for Knowage Server internal resources instead:

 1<?xml version="1.0" encoding="UTF-8"?>
 2<WHITELIST>
 3   <service baseurl="https://www.youtube.com" />
 4   <service baseurl="https://player.vimeo.com" />
 5   <service baseurl="https://vimeo.com" />
 6   <service baseurl="https://media.giphy.com" />
 7   <service baseurl="https://giphy.com" />
 8   <service baseurl="https://flic.kr" />
 9   <service relativepath="/knowage/themes/" />
10   <service relativepath="/knowage/icons/" />
11   <service relativepath="/knowage/restful-services/1.0/images/" />
12</WHITELIST>

Like other widgets the “Style” tab and the “Filters” tab are available in order to set the general style options for the widget and to filter the results displayed in the HTML widget.

Map Widget

The Map Widget is useful when a user needs to visualize data related to a geographic position. The widget supports multiple layers, one for every dataset added to widget configuration, and one data field for every layer: the user can switch on-the-fly between all data available on the layer.

../../_images/image4751.png

Map widget.

In Map Widget configuration a user can add and remove layers, set the format of the spatial attribute to use and specify the attributes to display on map and on the detail popup:

../../_images/image4761.png

Map widget configuration.

Every dataset with a spatial attribute is eligible to become a layer in map widget. Only one layer of the widget can be susceptible to user selection: that layer will be the only one with Target slide set to on. For each layer a user can also specify its default visibility with Default visibile slide. Enabling Static switch on a layer make it visible and non clickable, useful when a user wants a fixed background layer with dynamic data from a dataset. With buttons image478 and image479 the user can set the metadata and the layer style respectively.

In layer’s metadata, the user can add calculated fields (more on that later) and set the spatial attribute of the dataset that will be used to display a markers on the map. Actually, many spatial attribute types are supported:

  • String format: where the value specify two decimal numbers representing latitude and longitude separated by a space;

  • JSON: where the value is a text string in GeoJSON format;

  • WKT: where the value is a text string in Well-known Text format;

Important

Geographic coordinates format

For every format above user have to specify what is the format of geographic coordinate: user have to specify if latitude comes first or vice versa.

The first field listed in metadata is the spatial attribute and Knowage let the user to set if the spatial attribute need to be part of the aggregation or not: this let the user to create special query; for example, you may need to just list all the records of a dataset without any aggregations and in this case you can simply uncheck all the aggregate by checks and clean up the aggregation function for the spatial attribute; another example is where the spatial attribute at database side is of a special type like CLOB on Oracle, in that case the user cannot use that field for the aggregation but the user can exclude the spatial attribute from the aggregation, converting the field to measure and setting an aggregation function.

Every field of the dataset, except for the spatial one, can have a custom alias to show on map widget: just double click the label to edit it. A user can also specify if a field have to be shown on detail popup.

For measures a user could specify the aggregation function, if it has to be shown on detail popup and if it has to be shown on map: at least one field has to be shown on map.

For attributes a user could specify if it has to be shown on detail popup or if it has to be show as a filter: in that case, the attribute will be available in the control panel with its all distinct values to let the user to have an immediate evidence of which markers have the selected value for the measure

The user could also select if a specific attribute should be displayed in the tooltip that will be shown when the user hovers a specific feature on the map.

The 3-dots-menu on the right of each column of the dataset contains additional functionalities: for measures, for example, there is the possibility to specify thresholds.

The threshold menu open a dialog where the user can customize marker color by value range: that’s very useful when a user wants to immediately identify a marker by it’s value.

../../_images/image4821.png

Threshold dialog.

For all the attributes that are filters, a user could select the relative value from the control panel:

../../_images/image4991.png

Filter selection.

As said, Map widget supports calculated fields, a way for a user to calculate additional data to show on map or to display into popup detail:

../../_images/image5031.png

Add calculated field button in layer’s metadata.

From the calculated field’s dialog a user can combine measures and operations to add more data to the layer. The user can use a SQL-like syntax to create a statement that describe the new calculated field:

../../_images/image5041.png

Calculated Field’s dialog.

The newly calculated field added by the user is shown as a measure in layer’s dataset: from the 3-dots menu on the right of the field a user can update or delete the calculated field.

../../_images/image5051.png

The 3-dots menu on calculated field.

For every layer, a user can specify the way the data will be displayed on map: the user can choose between a markers, cluster, heatmaps and choroplet.

../../_images/image4771.png

Style configuration for every layer.

For marker there are multiple choices between a user can select. The first one is the standard marker, where a user can select only the marker color:

../../_images/image4831.png

Standard marker configuration.

The second possibility is to use a custom color and custom scale with a custom marker, for example and icon available in Font Awesome catalog:

../../_images/image4841.png

Custom marker configuration.

A user can also use an image from Knowage media as a marker:

../../_images/image4851.png

Marker from Knowage images.

Finally a user can use an image from external URL as a marker:

../../_images/image4861.png

Marker from Knowage images.

Cluster visualization renders circles of different size where every circle aggregating positions by relative values. A user can zoom in to disaggregate the cluster until he see the single data. For this type of visualization, a user can set size and color of the circle and the size and the color of the font used to display the aggregated value:

../../_images/image4871.png

Cluster configuration.

When heatmap is selected, a user can display values by areas colored by a color range from green to red where the values are respectively lower and higher. Setting the radius and the blur, a user can specify the scale of the areas and the scale of the blur around it:

../../_images/image4881.png

Heatmap configuration.

The choroplet visualization allows a user to precisely associate values to areas, very useful when spatial attribute specify a geometry instead of a single point. The classes method specify the subdivision algorithm and the classes number specify how many subdivision to make; the colors specify the start and the end of the range color that will follow the same range of the values:

../../_images/image4891.png

Choroplet configuration.

Discovery Widget

../../_images/image4801.png

The Discovery Widget is used to easily use and navigate into a Solr Dataset using facets aggregation and a table results. In order to make searches, aggregations using facets and so on, after selecting the Solr dataset it is possible to choose the fields that should be shown as the result. The table result can also be configured to show a limited set of fields, please open edit mode:

../../_images/image4811.png

Settings

The settings tab contains the management of the 3 elements that compose a directive:
  • Data table: enabled by default is the grid containing data. You can choose the number of item per page.

  • Facets: if enabled the sidepanel with the facets will appear. It is also possibile to configure facets options:
    • enable selection on facets, if enabled a user click on the facets will throw a cockpit selection instead of just filtering the table.

    • closed by default, if enabled the facets will be visible as closed groups by default.

    • facets column width, this setting allows to choose the dimension of the facets column in px, rem or percentage values.

    • facets max number, this setting allows to choose the maximum number of facets visible for every field.

  • Text search: if enabled a searchbar will appear at the top of the widget. It is possible to set a default search for widget initialization.

../../_images/image481b1.png

Important The options “show column” and “show facets” are only frontend side. They don’t affect the real backend Solr query, discovery widget will search for every field even though they are frontend omitted.

Facets column ordering

../../_images/image4911.png

It is possible to change the facets column ordering, for example if there is the need to move up a field.

As shown in this example, “aggregazione” should be shown upper, just go to the edit widget section:

../../_images/image4921.png

And change the columns order dragging the field to the right position.

../../_images/image491b1.png

Changing Date Format for discovery table date columns

It is also possibile to change the format used to show date columns inside discovery table: In order to do that, click on style for date columns fields in edit mode

../../_images/image4931.png

And change the “date format” property

../../_images/image4941.png
../../_images/image4951.png

Python/R Widget

The Python/R widgets allow to directly embed Python or R scripts inside the cockpit in order to create advanced custom analytics.

In the editor tab it is possible to add the script that will be sent to the execution engine.

../../_images/PythonEditor1.png

Before writing the code it is necessary to specify the type of the output produced by the script. Knowage has support for two different output types:

  • Image

  • HTML

It is also necessary to specify the name of the file in which the script will save its output.

The Dataset tab allows the user to select a dataset that will be accessible directly from the code. After choosing a dataset the list of available columns will be shown. Here it is also possible to order the dataset according to a column and to select the ordering type (ascending or descending).

../../_images/DatasetTab1.png

Dataset selection

Once a dataset has been choosen, it will be possible to access it directly from the code via a dataframe variable. This variable will have the same name of the dataset label.

The Environment tab allows the user to choose among a list of available Python/R evironments previously defined inside the Configuration Management. To support this kind of choice a list of available libraries is displayed for each selected environment.

../../_images/EnvironmentTab1.png

Environment selection

Inside Python and R scripts it is possible to access analytical drivers by the usual placeholder syntax $P{}.

Warning

This widget is sensible to associative logic, meaning that the widget is updated every time that an association is changed, but it DOES NOT trigger associative logic itself.

Custom Chart Widget

../../_images/image5001.png

The Custom Chart allows the user to directly embed html,css and js code using a supported external chart library and integrating with Knowage data and interactions using custom API.

This widget will be available only if the create custom chart widget option is set for the specified role.

The Edit section of the widget is composed by five tabs: dataset, editor, style, cross and filters.

The dataset tab allows to select a specific dataset to use as a refferral for the API. Once the dataset has been selected a table with the columns list will appear below. In the table will be possible to change column alias, the column aggregation for measures and delete columns interacting with the selected column line. Clicking on add column or add calculated field buttons on top a popup will appear allowing to choose one of the dataset column to add or to insert the calculated field formula.

../../_images/image5011.png

The Editor tab allows to insert custom code and it’s splitted into three components: CSS, HTML, JavaScript.

../../_images/image5021.png

The CSS component allows to insert css classes that will be used by the HTML code of the widget. It’s also possible to use @import command if the referred url is inside the whitelist.

The HTML component allows to insert HTML tags in order to create a structure to host the custom chart and additional structural informations.

The JavaScript component is the code section, and allows to insert the custom chart code, custom Javascript code and the API usage.

To use the api the keyword is datastore. datastore is object that contains the actual data; it has methods to iterate over results and get all values, as the Java counterpart, plus some other methods as the following:

getDataArray

returns: data array
params: custom user function
example:
1datastore.getDataArray(function(record){
2    return {
3    name: record.city,
4    y: record.num_children_at_home
5    }
6})
result:
 1[
 2        {
 3                name:'New York',
 4                y: 5
 5        },
 6        {
 7                name:'Boston',
 8                y: 3
 9        }
10]

getRecords

returns: array of objects; each object has nameOfDsColumn: value
params: no params
example:
1datastore.getRecords()
result:
 1[
 2        {
 3                city:'New York',
 4                total_children: 5,
 5                country: 'USA'
 6        },
 7        {
 8                name:'Boston',
 9                total_children: 3,
10                country: 'USA'
11
12        }
13]

getColumn

returns: array of unique values for one dataset column
params: dataset’s column name
example:
1datastore.getColumn('country')
result:
1['USA','Mexico','Canada']

getSeriesAndData

returns: array of series with data for each series
params: serie/measure name, custom user function
example:
1datastore.getSeriesAndData('PRODUCT_FAMILY',function(record){
2    return {
3        y: record.UNIT_SALES,
4        name: record.QUARTER
5    }
6})
result:
 1[
 2        {
 3                name:'Drink',
 4                data: [
 5                        {
 6                                y: 5000,
 7                                name: 'Q1'
 8                        },
 9                        {
10                                y: 7000,
11                                name: 'Q2'
12
13                        }
14                ]
15        },
16        {
17                name:'Food',
18                data: [
19                        {
20                                y: 6000,
21                                name: 'Q1'
22                        },
23                        {
24                                y: 4000,
25                                name: 'Q2'
26
27                        },
28                        {
29                                y: 3000,
30                                name: 'Q3'
31
32                        }
33                ]
34        }
35]

sort - angular sort service (sorting is executed on the client side)

returns: datastore sorted by dataset’s column/s
params: dataset’s column name
optional: sort type object {column:’asc/desc’}
example1:
1datastore.sort('STORE_ID') //by default, it is asc
2OR:
3datastore.sort({'STORE_ID':'asc'})

filter - angular filter service (filtering is executed on the client side)

returns: datastore filtered by some value for dataset’s column/s
params: object that contains dataset’s columns names for properties -> value to be filtered, an optional boolean to enable the strict comparison (false as default)
example:
1datastore.filter({'QUARTER':'Q1','STORE_ID':'1'}, true)

hierarchy

returns: hierarchy object with its functions and tree
params: object that contains property levels -> array of dataset’s columns names
optional: same object with optional property measures -> object that contains dataset’s columns names for properites -> aggregation function (sum, min, max)
example:
1var hierarchy = datastore.hierarchy({'levels':['QUARTER','PRODUCT_FAMILY'],'measures': {'UNIT_SALES':'SUM'}})
result:
 1[
 2        {
 3                "name": "Q1",
 4                "children": [
 5                        {
 6                                "name": "Non-Consumable",
 7                                "children": [],
 8                                "UNIT_SALES": 7.4571
 9                        },
10                        {
11                                "name": "Food",
12                                "children": [],
13                                "UNIT_SALES": 12
14                        }
15                ],
16                "UNIT_SALES": 19.4571
17        },
18        {
19                "name": "Q2",
20                "children": [
21                        {
22                                "name": "Non-Consumable",
23                                "children": [],
24                                "UNIT_SALES": 9.9429
25                        },
26                        {
27                                "name": "Food",
28                                "children": [],
29                                "UNIT_SALES": 7.2
30                        }
31                ],
32                "UNIT_SALES": 17.1429
33        }
34]

getChild

returns: node of hierarchy (node is Node object)
params: index of child in hierarchy
example:
1hierarchy.getChild(0)
result:
 1{
 2        "name": "Q1",
 3        "children": [
 4                {
 5                        "name": "Non-Consumable",
 6                        "children": [],
 7                        "UNIT_SALES": 7.4571
 8                },
 9                {
10                        "name": "Food",
11                        "children": [],
12                        "UNIT_SALES": 12
13                }
14        ],
15        "UNIT_SALES": 19.4571
16}

getLevel

returns: array of nodes of hierarchy on specific level
params: index of level in hierarchy
example:
1hierarchy.getLevel(0)
result:
 1[
 2        {
 3                "name": "Q1",
 4                "children": [
 5                        {
 6                                "name": "Non-Consumable",
 7                                "children": [],
 8                                "UNIT_SALES": 7.4571
 9                        },
10                        {
11                                "name": "Food",
12                                "children": [],
13                                "UNIT_SALES": 12
14                        }
15                ],
16                "UNIT_SALES": 19.4571
17        },
18        {
19                "name": "Q2",
20                "children": [
21                        {
22                                "name": "Non-Consumable",
23                                "children": [],
24                                "UNIT_SALES": 9.9429
25                        },
26                        {
27                                "name": "Food",
28                                "children": [],
29                                "UNIT_SALES": 7.2
30                        }
31                ],
32                "UNIT_SALES": 17.1429
33        }
34]

node is an instance of Node object. It has convenient functions to explore the node:

1var node = hierarchy.getChild(0)
result:
 1{
 2        "name": "Q1",
 3        "children": [
 4                {
 5                        "name": "Non-Consumable",
 6                        "children": [],
 7                        "UNIT_SALES": 7.4571
 8                },
 9                {
10                        "name": "Food",
11                        "children": [],
12                        "UNIT_SALES": 12
13                }
14        ],
15        "UNIT_SALES": 19.4571
16}

getValue

returns: a measure’s value for a specific hierarchy’s child(node)
params: dataset’s measures’s name
example:
1node.getValue('UNIT_SALES')
result: 19.4571

getChild

returns: a specific node’s child
params: index of nodes’s child
example:
1node.getChild(0)
result:
1{
2        "name": "Non-Consumable",
3        "children": [],
4        "UNIT_SALES": 7.4571
5}

getParent

returns: a node parent of specific child
params: no params
example:
1node.getChild(0).getParent()
result:
 1{
 2        "name": "Q1",
 3        "children": [
 4                {
 5                        "name": "Non-Consumable",
 6                        "children": [],
 7                        "sales": 7.4571
 8                },
 9                {
10                        "name": "Food",
11                        "children": [],
12                        "sales": 12
13                }
14        ],
15        "sales": 19.4571
16}

getChildren

returns: an array of node’s children
params: no params
example:
1node.getChildren()
result:
 1[
 2        {
 3                "name": "Non-Consumable",
 4                "children": [],
 5                "sales": 7.4571
 6        },
 7        {
 8                "name": "Food",
 9                "children": [],
10                "sales": 12
11        }
12]

getSiblings

returns: an array of node siblings to a specific child
params: no params
example:
1node.getChild(0).getSiblings()
result:
 1[
 2        {
 3                "name": "Non-Consumable",
 4                "children": [],
 5                "sales": 7.4571
 6        },
 7        {
 8                "name": "Food",
 9                "children": [],
10                "sales": 12
11        }
12]

variables

returns: a key/value object with all the declared variables and values
params: no params
example:
1var myvariables = datastore.variables;
result:
1 {
2     variableCity: 'New York',
3     variableNum: 100
4 }

profile

returns: a key/value object with all the declared profile attributes for the user
params: no params
example:
1 var user = datastore.profile;
result:
1 {
2     name: 'My Name',
3     tenant: 'Knowage',
4     customProfileAttribute: 'Test value',
5     role: 'user'
6 }

It is also possible to interact with the other cockpit widgets, to do so it’s possible to use the clickManager:

1 datastore.clickManager(columnName, columnValue);
This method can be added everywhere the code is managing a click event, and will notify Knowage about the interaction.
The default case (if no cross-navigation or preview-navigation is set) will throw a selection with the dataset column name and column value set in the method.
If a cross-navigation or a preview has been set in the cross tab, those will have priority on the selection and will throw the set interaction. The dynamic values used will be the ones set in the method arguments.

Important

Chart libraries

As a default Knowage supports natively Chart.js (version 1.0.2) for the Community edition and Highcharts.js (version 7.1.1) for the Enterprise Edition. In CE and EE, Knowage supports d3.js library (version 3.5.5). It is possible also to include other libraries adding the CDN script tag in the html Editor. Be aware that url not set in the whitelist will be deleted on save. To use this import use the kn-import tag like the following example:

1<kn-import src="yourCDNurl"></kn-import>

Warning

Whitelist For security reasons no dangerous Javascript code can be added to html tags. Every tag considered dangerous will be deleted on save by the filter. Base paths to external resources (images, videos, anchors, CSS files and inline frames) must be declared within TOMCAT_HOME/resources/services-whitelist.xml XML file inside Knowage Server, otherwise those external links will be removed by the system. This whitelist file contains safe and trusted websites, to restrict end users of providing unsafe links or unwanted web material. Knowage Server administrator can create or edit it (directly on the file system) to add trusted web sites. Here below you can see an example of services-whitelist.xml file; as you can see, its structure is quite easy: baseurl attributes refer to external services, relativepath must be used for Knowage Server internal resources instead:

 1<?xml version="1.0" encoding="UTF-8"?>
 2<WHITELIST>
 3   <service baseurl="https://www.youtube.com" />
 4   <service baseurl="https://player.vimeo.com" />
 5   <service baseurl="https://vimeo.com" />
 6   <service baseurl="https://media.giphy.com" />
 7   <service baseurl="https://giphy.com" />
 8   <service baseurl="https://flic.kr" />
 9   <service relativepath="/knowage/themes/" />
10   <service relativepath="/knowage/icons/" />
11   <service relativepath="/knowage/restful-services/1.0/images/" />
12</WHITELIST>

Like other widgets the “Cross”, “Style”, and the “Filters” tab are available in order to set the general style options for the widget and to filter the results displayed in the HTML widget.

Cross Navigation

Warning

Cross tab is only for technical users

Due to the fact that parameters can only be managed by technical user the cross navigation cannot be implemented by the final user.

All widgets (except selector and active selections) have the Cross tab available, that allows the user to interact with the widget in different ways: - setting a Cross-navigation between different documents - setting a Preview of a specific dataset to popup - opening an external link The interactions are mutually exclusive, so just one type can be chosen for every widget.

Cross-navigation

The cross-navigation gives the possibility to connect two documents clicking on a widget as a starting point, opening the second one as arrival and showing the breadcrumbs on top.

../../_images/image2122.png

Table widget cross-navigation configuration.

To enable one first of all is necessary to set a cross navigation inside the “cross-navigation definition” functionality. There is possible to set the starting/arrival point and to set the connection between different output/input parameters.

After this passage you will have the possibility to enable the cross-navigation in the tab and choose the user interaction that will start the navigation, if more than one are available.

The most complex example is the table widget cross-navigation, because it allows 3 different interactions:

  • Click on the whole row, where the interaction will start clicking on any row

  • Click on a single column, where the editor will choose a specific column that will start the interaction (the user will see the column values underlined)

  • Click on an icon, where the editor will choose an icon positioned to the right side that will start the interaction.

Once the interaction has been chosen you will be able to select the cross-navigation created before. If you created more than one related to that document you will be able to choose between them. If you leave this field blank the user will be able to choose that himself.

Preview

../../_images/image2143.png

Table widget preview configuration.

The preview configuration is very similar to the cross-navigation one. First of all you will need to enable the navigation using the switch button. After you will need to choose an interaction type and a target dataset. the selected dataset will be opened in a popup window but, if you check the “Direct download” property you will be able to get the dataset preview directly in the download list.

../../_images/image2162.png

Preview example.

Cross and Preview Parameters

../../_images/image2132.png

Parameters example.

Both cross-navigation and preview navigation share the parameters management. If one or more output parameters are available, you will find the list below the navigation page. You can choose which values to use clicking on the checkbox at the right side of the name, than you will have the possibility to choose between different modes to get the value:

  • Static, entering a static value

  • Dynamic, passing the value of the column at the selected row (or passing the column name if Selected Column Name is chosen)

  • Selection, passing the current value of the selection for the specified dataset and column. Warning: the selection is not triggered clicking on the navigation, so to pass this value the selection must already be present.

Once the user will click on the widget, those parameters will be evaluated before the navigation.

Link

The link configuration is very similar to the cross-navigation one too. First of all you will need to enable the link navigation using the switch button. Then you will be able to create one or more link navigations. You will need to choose an interaction type and a base url. The base url will be the url opened by the user click. You can also decide the type of link between the opening of a new page or the document replace opening in the same page.

../../_images/image2152.png

Link configuration with JSON parameter example.

Link Parameters

The link parameters are different from the previous because they will be used to make the baseurl selected more precise. The resulting example url will be something similar: http://www.knowage-suite.com?**parameter1**=value&**parameter2**=value2

To do so you will have to create and name different parameters, the selected name will be the one used in the url construction. You can choose how to get the parameter value with the following modes:

  • Static, entering a static value

  • Dynamic, passing the value of the column at the selected row (or passing the column name if Selected Column Name is chosen)

  • Selection, passing the current value of the selection for the specified dataset and column. Warning: the selection is not triggered clicking on the navigation, so to pass this value the selection must already be present.

  • Analytical Driver, passing a page parameter (input driver)

  • JSON, passing an escaped JSON inside the url parameter. You can use the editor to create the desired JSON and use the placeholder to set the value at runtime. The placeholders are the usuals $F{field} for the fields, $P{parameter} for the parameters, $V{variable} for the variables.

  • JWT, passing the JWT token of the user

Widget properties

Once one or more (above mentioned) widgets have been implemented, the technical user has some more options exploring the icon available at the right top corner of the widget itself, as Figure below highlights.

../../_images/image1921.png

Widget properties.

Here the user can:

  • move the widget in the cockpit area at convenience;

  • modify its dimension;

  • delete it;

  • activate the on-click interaction of the widget with the other ones;

  • activate the updating of widget data due to the interaction with other widgets.

When executing the cockpit in visualization mode, the user has also some more options for widgets. For all widget the user can use the icon image197 to expand the widget to all page and use the icon image198 to reduce it again. There are also two new widget options: using th icon image300 it is possible to capture the screenshot of the widget and clicking on the icon image301 the data plotted on a chart or displayed in a table or crosstab are exported in an excel file.

Chart widget are endowed with an additional option that allows the user to change the chart type, as you can see in Figure below.

../../_images/image1952.png

Change chart type button.

Referring to figure below, the available chart types are: parallel, scatter, wordcloud, line, radar, bar and pie.

../../_images/image1962.png

Available chart types.

Pay attention though to the fact that when grouping functions have been used, the change chart type may not report the same level of aggregation. In fact, not all type of chart allows the grouping function. Refer to Chart types in detail to read more about each chart type configuration. Pay also attention when a two-series chart is chaned with a single-series one. For instance the parallel chart works only when (at least) two series have been set, while the wordcloud works with only one series.

General configuration

This option allows the user to manage all cockpit general settings that we are going to describe through images of the interface. Clicking on the General configuration button the window in figure below opens. This contains the General Settings tab and the Widget Style tab.

../../_images/image1971.png

General configuration window.

Editing the fields of the first tab you can add or change the name and/or the description of your cockpit; moreover here you can choose the sheet color or a background image and its size. In particular, in order to add a background image for the sheets, firstly you have to add the image to the catalogue of the image widget and then copy the link of the image. It is also possible to decide to enable the menu and the widgets functionalities when the document runs in display mode or to disable the screenshot functionality for every widgets.

The second tab (Figure below allows to configure some style options of the cockpit, like borders, shadows, titles and background color.

../../_images/image1982.png

Widget style tab.

The third tab allows overriding the common css properties for the whole cockpit. The editor will highlight possible sintax errors.

../../_images/image4971.png

Css editor tab.

Data configuration

This feature manages the data storage and usage. In fact, here there is the possibility to save data in cache, create associations between datasets, create indexes on cached data, schedule the (data) refresh frequency and so on. Referring to the figure below, the feature is implemented through several tabs: the Source tab, the Associations tab, the indexes, the Frequency and the Template tab.

../../_images/image199_b1.png

Data configuration window.

Source

The Source tab is split into two areas. On the left side the user can find the list of those dataset that are currently used by the cockpit. Here it is possible to add new dataset that will be passed to widgets. In other words, datasets inserted in this area will be listed in the dataset combobox of widgets like the Table, the Pivot Table and the Chart one. Note that the user can delete datasets as well.

Parametric sources management

If the user is adding a parametric dataset the window will exhibit them in an expandable box right below. It is also mandatory to give default values or to associate proper drivers to the document to secure its correct execution. By the way, a final user has no access to parametric dataset and he/she cannot handle analytical drivers, therefore parametric sources can be managed only by an admin user. We stress that the user must also type the driver name in the field box as highlighted in Figure below. You can type it manually or use the look up just aside the parameter line.

../../_images/image2004.png

Dataset management.

On the right side of the window the user finds the list of external documents that can be added to the cockpit (through Document widgets), or as well as for the dataset case, of documents that are already in use in (previously set) Document widgets. In the occurrence of Associations parametric documents, parameter boxes are shown below. Note that it is mandatory to link them to analytical drivers (previously hooked to the document) or be assigned a fixed (default) value.

Associations

If your goal is to show data from a single dataset, it is not necessary to define any association. Associations should be set within the designer when widgets are built on different datasets. Associations can be set with the elements: dataset columns, dataset parameters and document parameters. Note that to implement an association the user must have at least one column. We show some examples in the following.

The following figure shows the association between two datasets. In this case the user must detect one field from the first dataset, the same field (in terms of values) in the other one. The relation will appear right below. Click on the save button to confirm the association. If the associations rely on multiple columns the user must add them one by one.

../../_images/image2014.png

Associations between dataset columns.

The same procedure can be done in the case of dataset columns and dataset parameters, as shown below.

../../_images/image2022.png

Associations between dataset column and dataset parameter.

Another example is supplied in Figure below. Here the association is performed between a dataset Frequency column and document parameter.

../../_images/image2032.png

Associations between dataset column and document parameter.

Once you have defined the associations, as soon as you refresh one widget, all related widgets are refreshed simultaneously on data update.

Auto Detect fuctionality

To correctly set up meaningful associations, the user must have knowledge of extracted data contained in each dataset. There might be though possible matches between datasets that are not known by the user or the columns used are not so similar as thought. Therefore the user can demand to Knowage to retrieve all possible columns that match, to report the percentage of matching values and get knowledge of other possible unexpected matches.

In the “Data cockpit settings” seen in the previous section, we fnd the “Auto Detect” button that redirects the user to the auto dectect page. The button is at the right top corner of the association list area.

../../_images/image5071.png

Auto Detect button.

Here the user can decide a minimum percentage of match that Knowage will use to compute and return matching columns. For instance a 20% of similarity means that the values contained by two or more columns of different datasets are the same at least for the 20% of them. Following the example shown in Figure below, we can read that between the three dataset, only two of them have possible associations. The user can use a 100% similarity match using the “produt_family” field, which means that the two columns contained in two different dataset return exaclty the same list of distinct values. Or the user can set an association with a 75.23% similarity using “the_date” field which means that some values of one column are not contained in the other column. The minimum length allows the user to specify the lowest number of datasets to be joined.

../../_images/image5061.png

Auto Detect page.

To select one of suggested associations, simply click on the specific row and then on the save button. Save the settings and save the dashboard. The new association is ready to be used.

Indexes

If you want that cockpit loading be faster, you can create indexes on cached data. This feature is available only for cached dataset.

If you want to create an index on a column you have to choose that column by clicking. The name of the column will appears in the Indexes List section of the page. If you want to confirm your choose, click on the save icon. If you want to cancel it, click on the cross icon. After saving a index you’ll see in the list surrounded by a continuous border.

../../_images/image3051.png

Indexes settings example

For example, in the figure above index on the column “customer_id” of ALL_CUSTOMERS dataset is already saved. “store_name” column of “SPARKSQL_STORE” dataset is selected. If you want to create an index on it, you have to save it.

Frequency

The Frequency tab defines a schedulation over dataset involved in the associations. An example is supplied in the next figure. This means that associations are activated automatically and data are reloaded according to this feature. In particular, groups of realtime datasets that compose one or more associations can have different update frequencies. We stress that, in order to secure the right document execution, the group frequency do not affect the other ones and each group is reloaded at different times. In addition, realtime dataset that are not involved in any association can have their own frequency.

../../_images/image2042.png

Frequency settings example.

Variables

In this tab the user can define the variables that will be available inside the cockpit.

../../_images/image4961.png

Variables tab

Every variable needs a name that will be used to call it and get the value, a type and a value. The available types are the following:

  • Static: a static number or string.

  • Dataset: the value of a selected dataset column. If a column is not selected a set of variables key/value will be created using the first two columns of the selected dataset.

  • Profile: a set of profile attributes available. (ie. the username)

  • Driver: the value of a selected analytical driver.

The variables will be available inside the widgets with the $V{variablename} format.

Template

In this tab the user can find the json code (at the current stage of the work) which composes the template. Figure below shows an example.

../../_images/image2052.png

Template example.

Selections

Adding the Selections to your widgets, namely the possibility to reload all widget data according to selection made through the click on a specific item of the cockpit (cell value, chart bar, etc.). Moreover, thanks to this functionality the user can reproduce the drill down feature that we introduced in Chapter of Chart. You can check which selections are active on your cockpit at anytime thanks to the Selection functionality. In Section 7.1 we already described how to add the “Selection” widget inside the cockpit area. If the user do not wish for the widget to stay visible, selections can still be accessed and managed through the menu configuration bar. Clicking on the “Selection” menu icon you can enter the “Selections” window. Here all selections and associations are listed, as shown in Figure below. The “Delete” button is available just aside each row to let the user to remove that specific selections. Click on the “Cancel” button to exit the window.

../../_images/image2061.png

Selection window.

Clear cache

The Clear cache button lets you realign the data shown in your widget to the ones in your database. When you create your widget and associate your datafields, a photo of data is made and stored in temporary tables. This means that your cockpit will display the same data at each execution until you clean the chace by clicking on the dedicated button and execute the document again. Now your data are refreshed and updated to the one contained in your database at last execution time. As discussed before this button is available also in “Read only” modality.

Save

You can save the cockpit by clicking on the save button in the right-top corner. The document will be saved in the personal folder (technical users) or in the My Analysis section. We remember that it is possible to share the new cockpit with other users clicking on the dedicated icon. You can also choose in which folder, among the ones visible to your role, to place your shared document.

Multisheet functionality

Cockpit allows to manage data visualization splitting it in two or more sheets. In each layer the user can find and employ the features shown above. Indeed, it is possible to perform a new analysis (as highlighted in Figure below) selecting different datasets and gadgets.

../../_images/image207_bis1.png

Multisheet cockpit example.

A user can take advantage of the “move widget” functionality we saw in My first Cockpit to bring widget from one sheet to another.

Furthermore it is possible, but not mandatory, to set associations between datasets underlying different sheets. The multisheet functionality is particularly useful to focus the analysis in a single spot and have a general overview over it in few clicks at the same time.

Export cockpit

Cockpit document allows to export data into csv file without executing document. This is very useful when you produce data using a heavy query. This option is available if your document has parameters. When you start execution of your document, you will get opened filter panel so you can fill values. To start export, you should click on drop down menu, next to execute button, as on image below.

../../_images/exportCockpitDrop1.png

Export cockpit into csv.

After process is finished, you will get notification on download icon download and you can find your file in Download manager section.

Clicking on download icon, Download manager will open, and you will be able to download zip file that contains csv file/files, depends of how many widgets (chart or table) you have in your document.

../../_images/downloadManager1.png

Download manager section.