Appboard/2.4/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 Getting Started guide will present an overview of the major components in the AppBoard system, and walk you through creating your first dashboard. This guide is designed to provide a quick survey of the system, and it should take no more than 30 minutes to run through the examples provided. Links will be provided to more detailed documentation for each component of the system.

Installation

The AppBoard system requires that a turnkey server is installed on an AppBoard server by a system administrator. This guide assumes that the installation has been completed and you are able to access the AppBoard builder in a web browser. For help with Installing AppBoard, see Installation.

The requirements for running the AppBoard Builder are:

1. A supported web browser running a supported version of Flash player. To check the supported versions, see System Requirements
2. Connectivity to the AppBoard data server

Accessing the Builder

In your browser, you can navigate to the home URL of your AppBoard system. This will be a URL such as http://appboardhost:8080/enportal/ab/home. If you are prompted to log in, use the following default administrator credentials:

Username: administrator

Password: administrator

Domain: System

Case is important when logging in to AppBoard

Action: In your browser, navigate to the AppBoard home URL and log in to AppBoard.

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.