# JBoss Dashboard Builder Quick Start

Table of contents:

- What is JBoss Dashboard Builder?
- How to install and run it?
- First steps
  1. Setup data connections (data providers)
  2. Adding a new indicator to a page
  3. Creating a new dashboard page
  4. Duplicating a page
  5. Configuring filter and drill-down
  6. Managing dashboards
  7. Customizing look'n'feel

# What is JBoss Dashboard Builder?

The Dashboard Builder is a full featured web application which allows non-technical users to visually create business dashboards. Dashboard data can be extracted from heterogeneous sources of information such as JDBC databases or regular text files.

Some ready-to-use sample dashboards are provided for demo and learning purposes.

### Key features:

- Visual configuration of dashboards (Drag'n'drop).
- Graphical representation of KPIs (Key Performance Indicators).
- Configuration of interactive report tables.
- Data export to Excel and CSV format.
- Filtering and search, both in-memory or SQL based.
- Data extraction from external systems, through different protocols.
- Granular access control for different user profiles.
- Look'n'feel customization tools.
- Pluggable chart library architecture.
- Chart libraries provided: NVD3 & OFC2.

### Target users:

- Managers / Business owners. Consumer of dashboards and reports.
- IT / System architects. Connectivity and data extraction.
- Analysts. Dashboard composition & configuration.

### Distribution:

- Independent application to deploy in WAR format.

# How to install and run it

TODO:

# First steps

The purpose of this document is not to provide a full detailed explanation of the module, but to guide you through the key steps to get your first dashboards created. The following chapters will provide basic information about how to configure the system to retrieve information from existing databases or files, create new indicators and manage different dashboards.
For this guide, it's assumed the simple installation has been done, with the standard set of examples and user and role configuration. It's important to notice this configuration MUST NOT be used in production, since it provides default security credentials.

# Connecting to data

To start we enter the following address in any browser:
http://localhost:8080/dashbuilder/
The login screen will appear. Login as user demo and password demo. You'll gain access to the initial dashboard, but you will NOT be able to modify it yet. Dashboards Showcase, where we find different pages.

The first thing to do, after you have accessed the web application, is to create a data provider. On the left menu, click on the Administration page and then in the Data providers. Once there, select the option "Create new data provider".

The purpose of data providers is to gather information from any system, either a database, a file or any other, and transform it to the internal in-memory representation for building dashboards.

## Retrieving data from a file

Click on 'Create new data provider'. The following fields will be shown in the form, with some sensible defaults:

- Type: in this case - choose the CSV File
- Name: Write the name you want to give to our data provider (this field is multi-language).
- CSV file URL: Here write the path where the CSV file is located.
- Data separator:
- Quoting symbol:
- Date format: Where we can define different date formats or even hour.
- Number format: Where we can define the number format.

Once you have filled all the fields, click on 'Try', to check that everything works properly. The application will give you a message "Correct data set ..." and we continue by pressing 'Save'.

Next, a screen is shown with all the fields found while parsing the file, giving us the option to change your name or even type.

After this last step, you can save you will have your new Data Provider in the list.

## Connecting to a database

You can create a data provider to query a JDBC data base. Go to Administration > Data providers and click on 'Create new data provider'. Choose the 'SQL Query', fill the form with the data provider name and the SQL query to retrieve the data.

Once the query is typed in, you can click on 'Try', and if the query is successful you will get a message.

TODO: Explain sql_condition command.

After the query is correct, you can rename the name of the properties to provide a more user friendly name.

The data provider has been set:

# Adding new indicator to an existing page

Once the necessary data providers have been created, we'll continue by adding a new indicator to an existing page. All dashboards are created by adding indicators and other types of panels to pages, until you can compose any page similar to the following:

To be able to modify pages that you need administrator privileges onto that page or dashboard. Logout first, and then login as user 'admin' with password 'admin'

Pages can be created from scratch, or duplicating an existing one. Both options will be explained in the following sections, meanwhile we will assume the page already exists and we want to add an indicator.

Indicators are a special type of panels, which are the widgets that can be placed around the page. To add a panel or indicator:

Click on the icon "Add panel to the current page" . This will make a popup be shown with all the available panels

To add a new 'Key Performance Indicator', click on Dashboard >> Key Perfomance Indicator. Drag the 'Create panel' option and drop it into any of the page regions. You will see that they are being highlighted while you move the mouse over them, then simply drop the panel.

Once dropped, the first step is to select the Data Provider we need to use, as configured before, to feed data to the charts and reports. Select any of the data provider and then you can start creating a new indicator.

Now, you must see the chart edition panel. It's an intuitive environment which helps you configure different type of charts and reports..

- Domain (X Axis): Data that will be shown in the X axis. In this example, we choose the property 'Country'.
- Range (Y Axis): Information to be grouped and aggregated for every value in the Domain. For example, 'Amount'.
- Renderer: Graphical library that can be used. Each one will provide different features and visualization style. We can choose 'NVD3'.
- Sort intervals by: It's how the domain values can be sorted, for example, according to the Range value.
- Sort order: It can be ascending or descending.

| Bar chart Line chart Data table Pie chart

Once you have finished setting your chart, click on the close button in the top-right corner. You can modify any of these properties at any time, even changing the chart type or the data provider, by clicking on the 'Edit content' panel option.

# Creating a new page

There are two different ways of creating a page:

- Starting as a blank page
- Duplicating an existing page .

You will find these icons at the top of the page, in the administration bar.

To create a new page, click on the 'Create new page' icon , a new screen will be shown to fill in some parameters:

- Page title
- Parent page: Pages are organized in a hierarchical way. This is the parent page.
- Skin: This will select and specific look'n'feel and CSS stylesheet for this page. You can leave the default value.
- Envelope: Defines which kind of HTML template will be placed around the page layout.
- Region layout: This is the template, that is, how regions are organized to place the panels inside the page. We can choose any of the installed types, for example, "Demo - Default template with sliding".

Most of these properties will be discussed in the chapter about 'Changing look'n'feel'

When back to the dashboard, you might realize the page is still not accessible from the left menu. You can see it in the combo list in the administration toolbar:

TODO: IMAGE OF ADMINISTRATION BAR

If you want this page to be shown in the left menu, you can click on 'Edit content' and then add the newly created page to the list of options displayed in the menu.

We can click on the page that has been created. It has the same look'n'feel as the rest of the dashboard, due to the fact it's sharing the same skin and envelope setting. Now we can start adding panels to it to compose its content. As described above, all you need to do is use the "Add panel to the current page" feature , panel and from that we displayed, go dragging each and every one of the panels that we need.

Repeat until the page has all the content and panels required.

The page template is divided in regions, and these can be of three different types:

- Columns.
- Rows.
- Tabbed regions.

After dropping the panels in the right regions and configuring them, you might be able to create the following page:

### Duplicating a page

As we had mentioned earlier, another way to create new pages, is from one we already have, and we do that from clone icon, this way is much faster, and the only thing we have to take into account are those panels that we want to keep and those who want to duplicate.

At the moment we access the utility to clone page, we appear in a page similar to the image below, which as I said before, we want to select those instances duplicate and those desamos maintain.

Once done, select Duplicate page and we have our new page created.

# Configuring filter and drill-down

# Managing dashboards

### Permits portal

From here you manage permissions for different users and roles created in place to act on the selected portal. You can also set permissions at the level of pages and portlets that will apply at all on site.

As can be seen in the figure below, at the top displays a list of permissions that are currently defined on the portal, while the bottom of the screen is devoted to the assignment of permissions itself. Thus, in succession, individual users will be assigned specific permissions to access the portal, to manage, create pages, edit its properties, delete, and edit permissions and change the portlets that can be displayed in him. These can be selected in the popup window (shown in Figure 8) that appears by clicking on the link ’Choose to whom’.

### Role-default page

Each role can be assigned a default page for portal, so that when a user with this role are identified and enter the portal, this will be your home page.

This option is activated only when the site has configured its home page as property the role assigned page.

# Customizing look'n'feel

The components for graphical configuration of the portal are:

- Skins: Style sheets, images and predefined icons that serve to change the look of the portal.
- Region Layouts: Format the available predefined regions of a page, where you can place portlets.
- Envelopes: Defines which kind of HTML template will be placed around the page layout

Each chart has a field component of validity (portal or page), and is packaged in a file. Zip file that contains a property that varies with the type of component.

You can access the administration of these components from the management console (from the portal or page), select the node ’Graphic resources.’

The structure of the administration screen is the same for each area (portal or page) and graphic component (skin, wrapper, or gallery staff):

- Form to register new components with the following fields:
  - ID: It must be unique, different from all discharged so far as an existing or in case you want to overwrite.
  - File. Zip: Path of the file containing the definition of the component and its resources.
- List of components such discharge.

At the time to validate a component, verify that consist only jsp code and html tags themselves. This control is done to prevent malicious java code.

### Facilities for independent management

This application is a content management solution agile, flexible and easy to use. Offers users the ability to manage all graphic resources, as well as style sheets, templates and wrappers from any computer with an Internet connection. With this, the content manager, developer, etc. Shall not require the presence of a technician to do their job.

### Structure of the *. zip and *. properties

Each zip file has a file of statements from the elements. Depending on the type of component would be: envelope.properties (envelope), skin.properties (skin), layout.properties (template) and gallery.properties (gallery of resources).

These files. Properties have two distinct parts:

- Name of the item in different languages, to which is added a line in the following format:
  name.<idiom abbreviation(es, en, ca)> = Name of the resource in that language
- Definition of the component associated with:
  resource.<resource_id>= Path relative to the zip file.

Before detailing what each resource, it is important that these four graphic resources can ’jump' at different levels from the page, via the portal (a given) to reach the global level (all portals).

### Skins

You may see the skins added to the resource library. You can check, using the preview, look & feel that will be applied to any of them. You can download the skin you want, clicking the icon.

Also add a new skin for our library resources. You only need the zip file containing all the elements for the correct update Library resources and assign an identifier.

The modification of the skins (all styles, images and icons predefined) has an effect on the appearance of the elements contained.

The easiest way to create a new skin is to lower one of which has by default application. It amended by adding unwanted changes in appearance and saved with a different name. If you only want to modify a default skin, will have to save after the changes, with the same name.

### Region layouts

You can display the list of all the templates installed on your portal. The preview lets you see the layout of the parts to be created in a page. Any of these templates can be downloaded by clicking on the icon.

The form is located before the list of templates, allows us to add templates. To do this you must create a zip file containing all the elements required for the upgrade and, finally, assign an identifier name.

### Envelopes

You can display the list of all the envelopes installed on your portal. The preview lets you see the envelopes of the parts to be created in a page. Any of these envelopes can be downloaded by clicking on the icon.

The form is located before the list of envelopes, allows us to add envelopes. To do this you must create a zip file containing all the elements required for the upgrade and, finally, assign an identifier name.