OpenDashboard

A web application that provides a framework for displaying data visualizations.

What is OpenDashboard?

OpenDashboard is a web application that provides a framework for displaying analytics visualizations and data views called “cards”. Cards represent a single discrete visualization or data view but share an API and data model. OpenDashboard was built to fill the need for a highly flexible and pluggable dashboard framework for an open learning analytics environment. The OpenDashboard web application provides access via IMS Learning Tool Interoperability, direct login and single sign-on with SAML.

Features

Get Started

Technical Overview

OpenDashboard is a Java web application built with Spring Boot.

Requirements

To build and run OpenDashboard you will need, at a minimum, the following:

  • Java 7 or higher (either JDK)
  • Maven 3 or higher
  • MongoDB

Building and Running OpenDashboard

To get started quickly for testing or demo purposes you can run OpenDashboard with the default profile.

              
// Just build the jar file
mvn clean package
// this produces the opendash.jar file in the target folder
              
            
              
// Run in place
mvn clean package spring-boot:run
// this starts the application on port 8081
              
            
              
// Run in place using the jar file
// as an alternative to using spring-boot:run
// you can build the jar file using mvn clean package
// and then run
java -jar target/opendash.jar
// this starts the application on port 8081
              
            

Now that you have OpenDashboard up and running watch the video below to learn how to configure it.

First configure some data providers. Data providers enable cards to access core learning entity (e.g., courses, rosters, etc) from a variety of sources.

Then setup access to OpenDashboard via IMS LTI.

Remember the default LTI tool launch endpoint is

http://localhost:8081/lti
and the default key and secret is opendash

Branches

Master Branch

The OpenDashboard master branch will always contain the most stable version of the code base. If you are just starting out with OpenDashboard we recommend that you start with the master branch and, of course, if you plan to deploy OpenDashboard in a pilot or production environment use the master branch.

Development Branch

The OpenDashboard development branch contains that latest code changes and any experimental features that have not yet been deemed production ready.

GH Pages Branch

The OpenDashboard gh-pages branch contains the HTML and supporting assets for this web page.

Properties

Developing a new Card

Step-by-step instructions with examples for developing a new OpenDashboard card.

Pick a type for your card

OpenDashboard relies heavily on convention over code so your card type is important - choose wisely. In our example we'll be building a learning activity radar chart. To see the end result, see src/main/resources/public/cards/activityradar.

All cards are located within the directory public/assets/cards. The first thing you should do is navigate to that directory and a create a new folder with a name that matches your card type. In our example, we choose the name activityradar as our card type so we would create a new folded called activityradar.

Create the AngularJS Module for your card

This file contains the supporting Javascript for your card. Create a file called module.js in your card type directory (e.g., src/main/resources/public/cards/activityradar/module.js). Use this file to define the AngularJS module and any supporting controllers and services.

Also use this file to register your card with OpenDashboard and define its configuration data.

For example:

              
(function(angular) {
  angular
    .module('od.cards.activityradar', 
      ['OpenDashboardRegistry', 'chart.js'])
        .config(function(registryProvider){
          registryProvider.register('activityradar', {
            title: 'Learing Activity Radar',
            description: 'Student Activity is 
              displayed in radar chart format.',
            cardType: 'activityradar',
            styleClasses: 'od-card col-xs-12',
            config: [],
            requires: [],
            uses: []
        });
      })
              
            

Note, cardType must match the name of your card type directory.

Create the HTML for your card

In src/main/resources/public/cards/YOURCARDTYPE (e.g. src/main/resources/public/cards/activityradar) create an html file called view.html. view.html should contain the UI markup for your card and reference the controller you created in your module.js file. OpenDashboard supports Bootstrap 3 by default but if you wanted to use different styling you would do that here as well.

            
<div class="col-xs-12" ng-controller="RadarCardController">
  <h1>Radar Card</h1>
</div>
				
            

Update the AngularJS application to include your module

Open src/main/resources/public/framework/od-app.js and add your card module to the application dependencies. For example:

              
// in our example our module is called od.cards.activityradar
angular.module('OpenDashboard', 
  ['ngRoute', 'OpenDashboardFramework','angularCharts',
    'od.cards.lti', 'od.cards.openlrs', 'od.cards.roster', 
    // add yours to the end like this
    'od.cards.activityradar'])
              
            

Add your module.js file to the main page and pom.xml

Open src/main/resources/templates/od.html and add a script tag at the bottom of the page pointing to your module.js file. For example:

              
<script src="../static/cards/activityradar/module.js" 
  th:src="@{/cards/activityradar/module.js}"></script>
              
            

Open pom.xml. Locate the jasmin-maven-plugin. Add the card to the plugin.

              
<plugin>
<groupId>com.github.searls</groupId>
<artifactId>jasmine-maven-plugin</artifactId>
<configuration>
    <preloadSources>
        <source>src/main/resources/public/cards/activityradar/module.js
        </source>
    </preloadSources>
</configuration>             
              
            

Note, any third party libaries that you are using in your card will also need to be added to the main page and pom.xml files.

Deeper dive into card registration and the card object

A little more detail on the registry and card object. OpenDashboard determines the available cards by interogatting the OpenDashboardRegisty (see src/main/resources/public/assets/js/app.js). The registry stores a map of each card where the key is a unique identifier for the card (e.g., od.cards.activityradar) and the value is the card object. See an example below.

              
{
  title: 'Learing Activity Radar',
  description: 'Student Activity is displayed in radar chart format.',
  cardType: 'activityradar',
  styleClasses: 'od-card col-xs-12',
  config: [],
  requires: [],
  uses: []
}          
              
              

Each key value pair must be defined and must not be null. title and description are used throughout the application. As mentioned above, cardType is used throughout the application and must follow application conventions.

The config is used if you need specialized configuration for your card (this is rare). Each object in the config array represents an input field that will allow for card specific configuration. The object has the following keys:

field:
unique identifier for the field
fieldName:
deprecated see translatableLabelKey
fieldType:
input type
required:
boolean, sets ng-required
tranlatableLabelKey:
Set custom labels keys here that have a JSON value pair. See the translation section.

requires and uses denote which data providers are used by the card. Currently Opendashboard supports six data providers: ASSIGNMENT, COURSE, EVENT, FORUM, OUTCOME, and ROSTER. If your card uses/requires any of the data sources, add it to the appropriate array. Alternatively, if none is necessary set the object to an empty array.

Translation

OpenDashboard uses the popular ng-translate library for internationalization and localization. If you are not familiar with ng-translate see: https://angular-translate.github.io/

Translation files for each supported locale can be found in the src/main/resources/assets/translations directory. Within each locale directory, you'll find several files. framework.json contains the language specific translation for the general OpenDashboard user interface (e.g., anything that is not a card such as welcome messages, forms, etc). Each card also has it's own translation file named using the convention cardType-card.json (e.g., demo-card.json where demo matches an existing card type).

When developing a card that uses translations there are two important items to remember. One, make sure that you inject $translate and $translatePartialLoader into your card's controller. Two, make sure you load your card specific translations in your card controller. See an example of this below.

              
.controller('DemoCardController', function($scope, $log, 
  $translate, $translatePartialLoader,
  SessionService, RosterService, OutcomesService, AssignmentService, 
  ForumDataService, CourseDataService) {
  
    $translatePartialLoader.addPart('demo-card');
    $translate.refresh();

...
              
              

Preconfigured Dashboards

Preconfigured dashboards allow an institution to preconfigure the default set of dashboards and cards users will interact with. Watch the video below to see preconfigured dashboards in action.

Javascript Services

OpenDashboard provides access to the underlying server-side framework and data services through Javascript AngularJS Services. Framework services provide access core framework data such as the user session, dashboards, cards and context mapping (i.e., the relationship between an external context such as a course section and a collection of dashboards and cards). Framework services can be found in /src/main/resources/public/assets/js/framework-services.js. Unless you are making updates to the underlying OpenDashboard framework it is unlikely that you will need to interact with framework services. However if you are developing your own custom OpenDashboard cards it is very likely that you will need to interact with data services. Think of data services as the client-side Javascript clients to the data providers that you have configured. There is a corresponding Javascript AngularJS Service for each of the support data provider types. Currently this includes:

  • ProviderService
    • getProviderTypes()
    • getProviders(type)
    • getProvider(type,key)
    • getProviderDataByKey(type,key)
    • getProviderDataByType(type)
    • create(provider)
    • update(provider)
    • remove(provider)
  • AssignmentService
    • getAssignments(options)
  • CourseDataService
    • getContexts(options)
    • getContext(options,key)
  • EventService
    • getEventsForCourse(options, courseId, page, size)
    • getEventsForUser(options, userId, page, size)
    • getEventsForCourseAndUser(options, courseId, userId, page, size)
  • ForumDataService
    • getForums(options)
    • getMessages(options,topicId)
  • ModelOutputDataService
    • getModelOutputForCourse(options,courseId,page,size)
    • getModelOutputForUser(options,userId,page,size)
  • OutcomesService
    • getOutcomesForCourse(options)
  • RosterService
    • getRoster(options)

Security Modes

OpenDashboard supports two security modes: basic and saml. The active mode is controlled via the feature flag features.saml. If features.saml is true then OpenDashboard expects an appropriately configured saml.xml file and keystore. You can find these files in src/main/resources/saml. If features.saml is false then OpenDashboard will use Basic HTTP for authentication. As will all feature flags these are set via properties (see application.yml) and can be overriden via all of the means supported by Spring Boot.

License

OpenDashboard is released under the terms of the Educational Community License, Version 2.0 (ECL-2.0). ECL-2.0 is a slightly less permissive Apache2 license. More details at http://opensource.org/licenses/ECL-2.0

Mailing Lists

To subscribe or unsubscribe send an email to the relevant email address by adding "+subscribe" or "+unsubscribe" to the email address.