Appboard/old/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 a URL such as http://appboardhost:8080/visualizer/Appboard_Builder.html. 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.

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 Source Administration 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 against the incoming data.

Action: Click Data Sources to display the Data Source Administration panel

There are many different types of data sources that are supported by AppBoard. You can also write your own custom data adapters, if needed. In this guide, a sample CSV (comma separated value) 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 “filePath”, 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 USA_States, select “StateID”
9. Click Next. The “Associate” screen will be displayed
10. Click Finish. On the Main Menu, click Data Sources again to display the Data Source Administration panel and 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 that defined 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. Data Collections allow 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.

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”
5. Click Next. The “Client Side Filter” screen will be displayed
6. Click the “+” next to Add Rule 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 Finish
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.

Stacks and Boards

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

Action: Perform the following steps to create a Stack:

1. Click Stacks and Boards to display the Stacks and Boards Administration panel
2. In the left panel, under “Quick Actions”, click the “Add Stack” item
3. For “Top-Level Board 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 and Boards Administration 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 Widgets wizard or the Boards step of the Stacks & Boards wizard. These wizards are invoked via links in the left side tool palette of the Appboard Builder interface.

Action: Perform the following steps to create a Widget:

1. Click Widgets to display the Widgets Administration panel
2. Click the “Add” button to create a new Widget
3. In the “Name” box, enter “Northern_States_Map”
4. For “Board”, select “USA_States_Stack”
5. Select the widget type “Maps” and select “USA”
6. Click “Add Widget”
7. Perform the following on the “Configure” panel to configure the widget:
   • For “Data Collection”, select “sample.Northern_States”
   • 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 pane to the left
   • Zoom in on the map and drag as needed so it shows the United States
   • Select a “Default Color” for the node markers on the map
   • Click “Next”. The “Options” screen will be displayed
   • Click “Next”. The “Actions” screen will be displayed
   • Under “Mouse Click”, click the “+” next to “Add Event” and select “Mouse Click”
   • For “On data of type”, select “sample.USA_states”
   • For “perform action”, select “Apply a Filter to a Data Collection”
   • For “Filter data collection”, select “sample.Northern_States”
   • Click the “+” next to “Add Rule” 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 Finish
8. On the main panel, click “Builder” to display the “USA_States_Stack” stack. Observe the widget displaying the Northern states. Zoom as desired.
9. Click on a node in the map to activate the event which will filter the map to only display capitals for northern states with Population > 2,000,000
10. Click the Edit button to additionally edit the widget colors and other presentation elements

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

1. Click Widgets to display the Widgets Administration panel
2. Click the “Add” button to create a new Widget
3. In the “Name” box, enter “Northern_States_Info”
4. For “Board”, select “USA_States_Stack”
5. Select the widget type “Tables” and select “Basic Table”
6. Click “Add Widget”
7. Perform the following on the “Configure” panel to configure the widget:
   • For “Data Collection”, select “sample.Northern_States”
   • Under “Columns”, click “Add”
   • Under “Data Field”, select “State”
   • Repeat steps B-C, until all of the fields are added and shown in the Preview panel below
   • Click Next, 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

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 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 is 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. Under “Board Options” in the left panel, choose “FreeFlowLayout”
4. Drag the widgets around to any desired layout configuration
5. 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, which will present Widgets containing data that is filtered or more detailed in some way.

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. Create a Data Collection called “sample.CountyData” with Data Source = “sample.USA_Counties”
3. Click Builder to display USA_States_Stack, containing a map and table widget
4. On the USA_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:
   • Under “Mouse Click”, click the “+” next to “Add Event” and select “Mouse Click”
   • For “On data of type”, select “sample.USA_states”
   • For “perform action”, select “Switch To a Board”
   • Click the “Add Board” button
   • For “Title”, enter “County Table”
   • For “Parent Board”, select “USA_States_Stack”
   • For “Context Data Type”, select “sample.USA_States”
   • For “Context Label Field”, select “StateLabel”
   • Click “Add Board” to exit the Add Board dialog
   • Under “Mouse Click”, click the “+” next to “Add Event” and select “Mouse Click”
   • For “On data of type”, select “sample.USA_States”
   • For “perform action”, select “Apply a Filter to a Data Collection”
   • For “Filter data collection”, select “sample.CountyData”
   • Click the “+” next to “Add Rule” and select “Widget Interaction Comparison”
   • Select the following for the widget interaction properties:
     • “When event”: “Last Mouse Click”
     • "For": "sample.USA_States"
     • “on Widget”: “Northern_States_Map”
     • “has a Property”: “StateLabel” “=”
     • “local property”: “StateLabel”
7. Click “Finish” 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” of type Basic Table
9. Configure the Widget to display one or more fields from the Data Collection “sample.CountyData”
10. Click Next, 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 node in the map, and observe that AppBoard launches a child board displaying the county data for those counties in the state that you selected