Dashboard Builder

Build dashboards using the Dashboard Builder and assemble pages based on reports and visualizations that you build using the Studio. A dashboard is a Web page that has one or more tabs each with a set of frames that can render anything you create within the Studio.

Before you begin remember that a dashboard can only include views on data that lives within a single database. The dashboard definitions themselves can (and should) reside in a separate database (the Studio database) but all views of data in the dashboard must run queries on collections in the same database. You can include views on different collections in the database.

To create dashboard follow this process:

  1. Define a find or aggregation query and save it by name.
  2. Define a chart if you want a visualization and save it by name.

3. Click on the Publish URL button in the Finder or the Aggregation Builder or the Visualization Builder.

4. Save the API by name by entering a name in the save as field in the top toolbar. This will create an API definition that you can use within the Dashboard builder.

5. Open the Dashboard Builder by clicking on the Dashboard link at the top right of the Finder or Aggregation Builder page.

  1. Give the dashboard a name.

7. Click the Add Tab button to add a tab. You can add as many tabs as you want to the dashboard.

8. For each tab enter the name of the tab (when you tab out of the name field the tab layout may jump to the first tab depending on the browser version).

9. Select a horizontal or vertical layout and the percentage occupied by the top or left panel.

10. Then add as many frames to each side of the panel. Click the Add Frame button to add a frame. Each frame specifies the API to call to render the content - based on the queries/reports/visualizations that you built in the Studio.

11. Once all your tabs are defined click on the Edit Bind Variables at the top. You must do this if your APIs are parameterized (which is normally the case). It is a good habit to always define a default for every bind variable since that means that a dashboard will always display data even upon the first render and before the user customizes it.

12. Save the dashboard (and publish it if other users should also be able to access it).

An example of the Dashboard Builder editing a dashboard with three tabs where the first tab has two frames to the left and one frame to the right is shown below.


To run and view a dashboard navigate your browser to https://<your gateway host>:8443/dboard.xhtml

Enter your login credentials and the dashboard name (and who it was published by if you are using someone else’s dashboard) and click submit. If you would like to instead use the dashboard as a URL click on the Show URL button - a pop-up allows you to copy/paste both a clear text and an encoded URL. If you include your password in the page and use the encoded URL then a user will have access to this dashboard without needing to login. Note that dashboards are always read only. The dashboard is displayed as shown below.

Don’t forget that in the login section you need to specify the database on which the data views should run as well as the Studio DB where your dashboard and API definitions reside.


When viewing the dashboard you can change the bind variable values which drive the queries and thus the display be clicking on the Edit Bind Variables button (more on that in the next section). After selecting a value click the Save button. All frames will be refreshed. Note that as you navigate to a different tab you might notice that the visualization frames have not been refreshed; this is designed to place less load on the database. Click on the frame’s refresh button to retrieve the view.

Each frame can be setup to have a refresh interval. This value in seconds will cause that frame to refresh automatically based on that interval. Note that each time the query will run and retrieve data from the server. The default refresh interval per frame is -1 which means no auto-refresh. The dashboard owner can define a different default interval when building the dashboard.

Note: Do not use more than twenty frames in a single dashboard. If you require more than twenty consult your jSonar account manager on how to do that.

Bind Variables in Dashboards

Bind variables (BVs) allow you to parameterize queries so that a user has control over what data they are viewing. When you build a dashboard you select a set of APIs to put on a single page. Before you save the dashboard the Dashboard Builder creates the full set of bind variables of the dashboard by creating the union of all the bind variables needed by all APIs on the dashboard.

When a dashboard runs it uses the bind variable values to ensure that each API/query can run fully and generate results. The initial set of BV values is derived from the defaults you save when you create the dashboard. As you are viewing the data you can change these values - causing the queries to be re-run and showing different data. This is saved in the Studio DB so that the next time you login you see the dashboard in the last state you left it.

When you define bind variables in dashboards you have more control than when you define them for APIs. In dashboards a bind variable selection can be backed by a query (either a find query or an aggregation query). These values may even be based on other bind variables, including those specified within the dashboard itself.

To base a dashboard bind variable on a query enter the query JSON expression when you edit the bind variables in the dashboard builder. The query is a JSON string in the format of:

{ns: "flights", pipeline: "dest", p: "o"}

for a saved aggregation pipeline, and in the format of:

{$ns: "flights", $q: {}, $p: "o"}

for a find query. Note that the queries and collection need to exist within the dashboard database.

As an example, suppose we have a dashboard which includes a report that filters based on an origin and a destination. The origin and destination will both be computed using an aggregation pipeline on the flights collection itself that will return the distinct possible values. Furthermore, the destination list will not include the currently selected origin value.

The pipeline for the main query might look like:

  $match: {
        "DEST": "$$dest",
        "ORIGIN": "$$origin"

Assume also that we have a pipeline named origin that looks like:

  $group: {
    _id: {ORIGIN: "$ORIGIN"}
  "$project": {
    o: "$_id.ORIGIN"

and a pipeline names dest that looks like:

  $group: {
    _id: {DEST: "$DEST"}
  "$project": {
    o: "$_id.DEST"
  $match: {
    $and: [
        "o": {
          $ne: "$$origin"

In the dashboard builder that includes the original report clicking the Edit Bind Variables button will show the $$origin and $$dest bind var entries. Enter:

{ns: "flights", pipeline: "origin", p: "o"}

for the $$origin query and:

{ns: "flights", pipeline: "dest", p: "o"}

for the $$dest query.

When you view the dashboard you will now be able to select the origin which will run the origin pipeline to get the distinct values and select the destination by running the dest pipeline to get the distinct values minus the selected origin.

You can initialize dashboard variables using the $$LMRM_NOW-/+<millis> syntax. For example, if you set a bind variable to a value of $$LMRM_NOW in the default (while defining the dashboard) then when a user first uses the dashboard the value will be initialized to the current time.

Adding an “ALL” Value to Drop Downs

When you are using JSON Studio to access data in SonarW, each pull down in a dashboard is appended with a special value – ALL –.

In order to use this value your $match conditions should contain an $or of the form:

$or: [{"country" : "$$COUNTRY"}, {$expr: {$eq: ["$$COUNTRY", "-- ALL --"]}}]

rather than only:

"country" : "$$COUNTRY"

This way users can ask to see all data rather than a single value.


The factor value behaves differently in different visualization types. In most, it is a factor that affects both the height and width of the vizualization in the same way - i.e. it is a multiplier. For standard charts (line, bar, column, scatter, pie etc) factor affords more control. If the value is over 10 then it is used to determine the width and height of the chart. For example, a values of 800.5 means a width of 800px and a height of 500px. A factor under 10 will have no effect for these chart types.

Gateway Prefix

The Gateway and dashboards may sometimes be embedded within another Web server or used within a framework that redirects to open dashboards. In such cases you might want to have URLs for the dashboard frames have a prefix (e.g. /sonarFinder/Gateway rather than /Gateway). In web.xml change the gateway.prefix entry to add your prefix:


Table Of Contents

Previous topic


Next topic

JSON Data Pump (jPump)

Copyright © 2013-2016 jSonar, Inc
MongoDB is a registered trademark of MongoDB Inc. Excel is a trademark of Microsoft Inc. JSON Studio is a registered trademark of jSonar Inc. All trademarks and service marks are the property of their respective owners.