Appboard/2.5/tutorials/getting started tutorial

Audience

The audience of this guide is a beginning AppBoard dashboard developer, or anyone interested in learning about the basic capabilities of AppBoard.

Overview

The overall goal of the tutorial is to build an interactive sales dashboard and use this to present an overview of major features within AppBoard. The tutorial is limited in scope and should be possible to complete within 30 minutes, however the underlying data contains more information that is used and will allow for additional exploration beyond the tutorial instruction.

Prerequisites

To complete this tutorial the following is required:

1. AppBoard installed and running. Refer to the Installation documentation for more information on installing.
2. Connectivity to the AppBoard server, and administrator access. Refer to the Accessing AppBoard documentation for more information.
3. A supported web browser with a supported version of the Adobe Flash Player installed. Refer to the System Requirements for a list of supported browsers and Flash versions.
4. Internet access to use the Tile Map widget (alternatively use the Vector Map).

Part One

Exercise Summary

In part one of this tutorial the focus will be on bringing up some basic content. This will consist of:

• Log into AppBoard as an administrator
• Setting up some Data Sources
• Creating a Data Collection
• Creating a Stack (top-level dashboard)
• Adding Widgets

Log into AppBoard

The first step is to log into AppBoard as an administrator. If using a clean install on your local system then the default access and credentials are as follows:

• URL: http://localhost:8080
• User Name: administrator
• Password: administrator
• Domain: System

AppBoard credentials are case sensitive.

Data Sources

The first step in creating a dashboard is defining a data source that will be used by the Widgets. The Data Sources Builder Mode displays the Data Sources panel, where you can add and edit data sources.

Data Sources connect AppBoard to external sources of data such as files, databases, web services, 3rd party connectors, and custom commands. The basic purposes of a Data Source are to define a connection to the outside data, define the sets of data returned by the source (Data Source entities), define associations between different Data Source entities, and other properties such as caching.

In this section you will create a data source for a directory containing comma-separated-values (CSV) files. One file contains US state information, and the other includes a breakdown by counties for each state.

Perform these steps:

1. Select the Data Sources builder mode
2. Click the Add button to create a new data source:
   1. Name: getting_started
   2. Select an adapter type: File -> CSV Directory
   3. Click the Add Data Source button.
3. The Data Source Wizard will now display the Connect step, complete the following fields:
   1. Directory: click the magnifying glass and select TODO
   2. Header Meta Delimiter: Asterisk
   3. Click the Next button.
4. The Explore step should now be shown. There should be two entities, state_counties and states. Expand these out to see the fields and field types. Also take notice of the Primary Key column. Click the Next button.
5. The Associate step can be used to associate one data source entity to another. They can be from completely different data sources. For now leave this blank and click the Finish button.

Let's also create a summary for each sales region. Since this information is not in the CSV files we can use the Sub-Query adapter to perform this function:

1. Select the getting_started data source just created above.
2. Click the Create Sub-Query button to create a new sub-query data source:
3. This launches straight into the Sub-Query Data Source Wizard:
   1. Name: getting_started.region_summary
   2. Source: select getting_started.states
   3. Click the Simple Select toggle, it should switch to the green Advanced Transform state.
   4. Select the Transform option:
   5. Use the Add button to add the following transforms:
      1. Group By -> SalesRegion
      2. Aggregation -> StateCode -> Count
      3. Aggregation -> TotalSales -> Summation
   6. Click Next and then Finish to save the data source.

That's it. We now have a derived data source with a count of states and a total sales figure grouped by region.

Data Collections

By default a data collection is automatically created for each data source entity using the same name. Select the Data Collections builder mode to view the data collections and the following should be visible:

• getting_started.region_summary
• getting_started.state_counties
• getting_started.states

You can preview the data returned for each of these data collections by clicking the blue icon in the preview column.

On our dashboard we're going to want a Top 5 chart showing the states with the strongest states. We can create a custom data collection to order and limit the result set:

1. Click the Add button to create a new data collection.
   1. Name: getting_started.top5_states
   2. Data Source: getting_started.states
   3. Select the Server Side Sort option:
      • Use the Add button to create a sort on TotalSales -> Descending.
   4. Select the Limit Row Count options:
      • Server Side Row Limit: 5
2. Click the OK button to close and save this data collection.
3. Preview the new data collection.

Part Two

Exercise Summary

In part two the focus is on adding some interaction and building out additional context sensitive content. This will mainly focus on:

• Create widget actions
• Filtering Data Collections via action.

Exercise Summary

In this exercise, you will go through all of the major steps for building a visualization suite in AppBoard:

1. Connecting to a data source
2. Creating a filtered data collection
3. Creating a dashboard
4. Adding Widgets to a dashboard
5. Re-arranging the layout of a dashboard
6. Configuring actions to trigger changes to a Widget and launching other dashboards

For this example, two sample data files are provided as part of the AppBoard product installation. One file lists the states in the United States of America and contains data such as population and map coordinates of the state capital. The other file lists the counties within each state, along with sample data for each county. This data provides an easy way to get started with AppBoard, without having to spend time gathering database information or connecting to a server.

The goals of this exercise are the following:

1. Create a Board displaying a US map, with pins on the state capitals, as well as an associated data grid displaying detailed information about each state
2. Configure an action to filter the pins on the map to only display for Northern states with a large population
3. Re-arrange the layout of the Widgets
4. Configure an action to launch a new Board when a pin is clicked on the US map, displaying a data grid listing the counties in the state that was clicked

Data Sources

The first step in creating a dashboard is defining a data source that will be used by the Widgets. The “Data Sources” Builder Mode displays the Data Sources panel, where you can add and edit data sources.

Data Sources define connections to data warehouses, such as databases, file systems, web services and system APIs. The basic purposes of a Data Source are to define a connection to the outside data, provide an AppBoard "namespace" for the data, and provide security measures such as filtering the incoming data.

In this section, you will create a mapping in AppBoard to a data source file. The file is a table of comma-separated-values (CSV) that lists the states in the United States of America and contains data such as population and map coordinates of the state capitals.

Action: Click Data Sources to display the Data Sources panel

AppBoard supports a variety of data sources. You can also write your own custom data adapters, if needed. In this guide, a sample CSV file will be used as a data source.

Action: Perform the following steps to add a data source:

1. Click the Add button
2. In the “Name” box, enter “sample.USA_States”
3. For the adapter type, select “File”
4. Under the file type, select “CSV File”
5. Click the “Add Data Source” button. The “Connect” screen will be displayed.
6. Under “File Path”, enter “${application.home}/data/pkg/appboard/test/stateCapitals.csv”
7. Click Next. The “Explore” screen will be displayed with a list of data files found.
8. Under “Primary Key” for the "stateCapitals" folder, click the Edit button and select “StateID”
9. Click OK.
10. Click Next. The “Associate” screen will be displayed
11. Click Finish. On the Data Sources page under the Data Sources panel, confirm that the Data Source “sample.USA_States” is now listed.

Associations are logical connections between two pieces of data; often referred to as "foreign-keys" in databases. For example, a collection of records about the individual states within the United States could be associated with a collection of records about the individual counties in each state. The county would have a "stateId" field would define the state in which the county resides. Therefore a one-to-many association can be created between a state and counties.

Data Collections

A "Data Collection" is a group of data sources that are available for the Widgets in the system to use. Every time a Data Source is created, a Data Collection is made using all of the data from the data source. Creating your own Data Collections allows you to configure filtered data sets from the raw data in a Data Source. For example, you can create server-side or client-side filters that restrict the data that will go into your Widgets.

In this section, you will create a filtered data collection from your raw data source. The filter will select the states in the Northern part of the USA.

Action: Perform the following steps to add a Data Collection:

1. Click Data Collections to display the Data Collections panel
2. Click the Add button
3. In the “Data Collection Name” box, enter “sample.Northern_States”
4. For Data Source, select “sample.USA_States.StateCapitals”
5. Click the “Configure Client Side” tab at the top. The “Client Side Filter” screen will be displayed
6. Click the "Add Rule" button and select “Simple Property Comparison”
7. For “Property”, select “Latitude”
8. For the comparison type, select “>”
9. In the “Value” box, enter 40
10. Click OK
11. In the Data Collections panel, confirm that the “sample.Northern_States” collection is listed
12. Click the “Preview” button in the row of the new data collection to launch the data viewer. Observe that there are 23 rows representing states with latitude greater than 40.
13. Click Close

Stacks & Boards

A "Board" represents a dashboard of information. Each Board will consist of one or more Widgets. A Board typically displays a suite of information that is related in some meaningful way, and which will be appropriate to present as a visualization to an AppBoard end-user.

A "Stack" is a collection of Boards that contain related information. For example, a Stack named "States" might have two boards, one that lists all of the states in the US and another Board that shows only the details of a single state. Stacks are generally used for drill-down purposes. Clicking on a state in the US level Board would reveal the details of that state in the single state details Board.

In this section, you will create a Stack (and a Top-Level Board) that will be used for displaying Widgets with information about the states in the USA.

Action: Perform the following steps to create a Stack:

1. Click Stacks & Boards to display the Stacks & Boards panel
2. In the left panel, under “Quick Actions”, click the “Add Stack” item
3. Under "Title”, enter “USA_States_Stack”
4. Click the "Add Stack" button
5. Confirm that the Stack “USA_States_Stack” is now listed in the Stacks & Boards panel
6. In the left panel, click “Builder” to display the empty Stack

Widgets

A "Widget" is a visual element that can be placed on a Board. For example, the "Data Grid Widget" gives a visual representation of tabular data in a familiar spreadsheet format. Boards contain one or more Widgets, each displaying part (or all) of the data to be visualized. Widgets are viewed by the Widget wizard or during the Boards step by the Stacks & Boards wizard. These wizards are invoked via links in the left side tool palette of the Appboard Builder interface.

In this section, you will create a map Widget that displays a USA map. You will place pins on the map where the state capitals are located for the northern states only.

Action: Perform the following steps to create a Widget:

1. Click Widgets to display the Widgets panel
2. At the top, For “Board”, select “USA_States_Stack”
3. Click the “Add” button to create a new Widget
4. Select the Widget type “Maps” and select “Vector Map”. Click “Use Selected”
5. For “Data Collection”, select “sample.Northern_States”
6. In the “Widget Name” box, enter “Northern_States_Map”
7. Click “Next”. The “Visualization” screen will be displayed
   • For "Map Type" select "US"
   • For “Adornment Label Field”, select “Capital”
   • For “Latitude Field”, select “Latitude”
   • For “Longitude Field”, select “Longitude”
   • Observe that some data points are now displayed in the preview panel
   • You may change the default pin shape and color here. You may also add filters that determine the pin appearances.
   • Click “Next”. The “Trouble Bubble” screen will be displayed
   • Click “Next”. The “Options” screen will be displayed
   • Click Finish
8. On the main panel, click “Builder” to display the “USA_States_Stack” stack. Observe the Widget displaying a US map with pins showing the capitals of the Northern states.
9. Click the Edit button to additionally edit the widget colors and other presentation elements

In this section, you will create a data grid Widget to be displayed beneath the map Widget. It will show details about each state.

Action: Perform the following steps to create a second Widget:

1. Click Widgets to display the Widgets panel
2. At the top, For “Board”, select “USA_States_Stack”
3. Click the “Add” button to create a new Widget
4. Select the Widget type “Lists & Table” and select “Table”. Click “Use Selected”
5. For “Data Collection”, select “sample.Northern_States”
6. In the “Name” box, enter “Northern_States_Info”
7. Click “Next”. The “Visualization” screen will be displayed
   • Under “Columns”, click “Add Column”
   • Under “Data Field”, select “State”
   • For the "Renderer" column, use the default values (no changes needed)
   • Repeat steps 7.1-7.3, until all of the fields are added and shown in the Preview panel below
   • Click Next, and Finish to exit the Widget configuration panels
8. Click Builder and observe that the Board now shows a map Widget and table Widget

Actions

In addition to just visualizing data, Widgets allow you to configure "Actions". For example, you can contextually filter one widget based on a selection in another, or you can Drill Down into a child board that shows details based on an item selected in the parent. The key is knowing that when you click on a Widget, you're actually clicking on the piece of data that's being represented by the widget. Actions allow you to use this piece of data as context to alter client or server side filters for any Data Collection inside AppBoard. This flexibility allows for extremely powerful interactions.

In this section you will then configure an action to filter the display when one of the pins is clicked, to only show northern states with a total population that is greater than 2,000,000 residents.

Action: Perform the following steps to create an Action:

1. In the upper right hand corner of the "Northern_States_Map" Widget click the arrow to expand the tool bar to show additional options.
   • Click the Actions icon (lightning bolt) to open the Actions editor in the Widget Wizard.
   • Click the “Add Action” button and select "Apply a Filter to a Data Collection" from the drop-down list
   • Next to “On selection of”, make sure "any" and “sample.USA_states.StateCapitals” are selected
   • For “Filter data collection”, select “sample.Northern_States”
   • Click the “Add Rule” button and select “Simple Property Comparison”
   • For “Property”, select “Population”
   • For the comparison type, select “>”
   • In the “Value” box, enter 2000000
   • Add a second Rule in the same manner, setting “Latitude” “>” “40”
   • Click Close
2. Click on a pin in the map to activate the event which will filter the map to only display capitals for northern states with a Population > 2,000,000

Layout

Since you have created a dashboard with two Widgets, you may want to organize how the Widgets are presented on the screen.

Action: Perform the following steps to modify the layout of a Board:

1. Grab the upper-left corner of the label bar of the lower Widget and drag the lower Widget above the upper Widget until you observe a change in color. Release the Widget and observe that the order of the Widgets has been swapped.
2. Grab the label bar of the lower Widget and drag the lower Widget to the right of the upper Widget until you observe a change in color. Release the Widget and observe that the Widgets are now side by side.
3. Drag the Widgets around to any desired layout configuration
4. Grab the lower-right corner to make the Widgets bigger or smaller

Switching to a Child Board

Every stack in AppBoard begins with a Top-Level Board, sometimes referred to as a “Parent Board” or “Summary Board”. The Board you created in the exercises above is a Top-Level Board. You will often want actions on the Top-Level Board to launch "Child Boards". Child Boards present Widgets containing data that is filtered or more detailed in some way.

In this section, you will modify the action that occurs when the user clicks on a pin in the map. Earlier, you configured the click action to filter the map to only display pins for states with a population greater than 2,000,000 residents. Now you will modify the action so that a new Board is launched when a pin is clicked. The new Board will display a data grid listing all of the counties for the state that was clicked on the map.

Action: Perform the following steps to create an action that will switch to a Child Board:

1. Click Data Sources and create a new Data Source called “sample.USA_Counties” from the CSV file stateCounties.csv, with Primary Key = “CountyID”.
2. Under "File Path", enter "${application.home}/data/pkg/appboard/test/stateCounties.csv".
3. Click Builder to display USA_States_Stack, containing a map and table Widget
4. On the Northern_States_Map Widget, click the Actions (lightning bolt) icon to open the Actions editor in the Widget Wizard
5. Click “x” to delete all of the existing actions
6. Perform the following steps to define a new action:
   • Click the “Add Action” button and select "Switch to a Board" from the drop-down list
   • Next to “On selection of”, make sure you have selected "any" and “sample.USA_states.StateCapitals”
   • Click the “Add Board” button
   • For “Title”, enter “County Table”
   • For “Parent Board”, select “USA_States_Stack”
   • Click “Add Board” to exit the Add Board dialog
   • Select the new board from the “Board” drop-down list
   • Check the box next to “Use Context Label Field”, select “StateLabel”
   • Click the “Add Action” button and select "Apply a Filter to a Data Collection" from the drop-down list
   • For “On selection of”, select "any" and “sample.USA_States.StateCapitals”
   • For “Filter data collection”, select “sample.USA_Counties.stateCounties”
   • Click the “Add Rule” button and select “Widget Interaction Comparison”
   • Select the following for the Widget interaction properties:
     • “Selected Data has a Property”: “StateLabel” “=”
     • “filtered data property”: “StateLabel”
7. Click “Close” to exit the Actions editor in the Widget Wizard
8. Click Widgets and create a new Widget called “County Data Table” on the Board “County Table” and select the "Table" Widget Type under the "Lists & Table" tab
9. Configure the Widget to display one or more fields from the Data Collection “sample.USA_Counties.stateCounties”
10. Click Next and Finish to exit the Widget configuration panels
11. Click Builder to again display USA_States_Stack, containing the map and table Widget
12. Click on a pin in the map, and observe that AppBoard launches a child Board displaying the county data for those counties in the state that you selected

Conclusion

In this exercise, you have connected to data sources, created boards, and configured actions. This is the essence of AppBoard. Hopefully you have seen that data visualizations can be easily built and modified using the AppBoard Builder.

Next, you may want to create some data files that replicate the type of data that you will be using to build AppBoard visualizations. Once you have created some visualizations from sample data, you can then change the data source to be your live data source or feed, and exercise the full capability of AppBoard.

Next Steps

To create users in the system, and assign the USA States sample stack to those users, refer to the Provisioning Overview documentation.