Dashboard API

The Watershed Dashboard API can be used to manage the cards that appear on an organization’s dashboard. This guide outlines the functional components of the API and provides an example.

Please note: this guide is designed to complement a conversation with us. If you're looking to implement the Dashboard API and need assistance, please let us know and we will be glad to help.

This guide consists of 4 sections:

Please note: this article does not include examples. To see cards and groups in action, we recommend that you create, edit, delete and group some cards in your Watershed sandbox and inspect the API calls made in your browser’s network tab.

Concepts

Cards

When you log in to Watershed, the first thing you see is a collection of cards displayed on the dashboard. A card is a visualization of data based on configuration of filters, dimensions and measures.

Card types (aka templates)

Watershed supports a variety of different types of card, which you can see presented in the carousel in Explore. Each card type has a unique template id that can be used when creating cards. These ids are listed in the Entity Model section below.

One special card type that does not appear in the Explore carousel is the group card. This card is used to present groups of cards to the user.

Card groups

A collection of cards intended to be viewed together. Card groups can be presented to the user by using a group card. It’s also possible during API transactions for a card group to exist which is not attached to a group card and not visible to the user.

Normally cards only belong to one group. There are two exceptions:

  1. Cards that have been configured to exist on multiple dashboards (dashboards are a special type of group).
  2. Cards that have been placed in multiple groups via the API.

Having a card appear in multiple places can be confusing for the user as changes to the card in one location affect that card everywhere. We recommend you avoid putting cards in multiple groups.

Card groups do not normally contain group cards (except card groups that are dashboards). To avoid confusing your users, we do not recommend putting group cards into card groups via the API.

Dashboards

A dashboard is a special type of card group that is presented to the user on the dashboard menu if they have permission to view it. Dashboard groups are not normally attached to group cards, but can be via the API.

API

This section outlines the allowed resources and methods of the Dashboard API.

Create Card

Creates a new hidden card. Newly created cards should be added to a dashboard or other card group after being created.

Request URL: /api/cards
Method: POST
Expected response code: 201 Created

Request content

The request should contain a JSON formatted card object (see Entity Model). This object does not need to include an id.

Response content

A successful request will return a complete card object including id.

Update Card

Request URL: /api/cards/[card-id]
Method: PUT
Expected response code: 204 No Content

Request content

The request should contain a complete JSON formatted card object including card Id (see Entity Model).

Response content

No content.

Please note: you can also update cards by custom id using the /api/cards resource and customId parameter.

Get Card by Id

Request URL: /api/cards/[card-id]
Method: GET
Expected response code: 200 OK

Request content

No content.

Response content

A successful request will return a complete card object including id.

Get Cards

Request URL: /api/cards
Method: GET
Expected response code: 200 OK

Request content

No content.

Response content

A successful request will return a collection of cards relating to the organization.

Delete a Card

Request URL: /api/cards/[card-id]
Method: DELETE
Expected response code: 200 OK

Request content

No content.

Response content

A successful request will return the complete deleted card object including id.

Get Card Data

It is possible to use the card API to fetch the data behind the card. The request required for this and the format of the result returned varies from card to card and is not documented here.

Please note: you can also use the Aggregation API to get data similar to that produced by cards, but without needing to create a card.

Group two cards

This is a helper call to facilitate easy and safe grouping of two cards with a single API call. It groups one card (the source) with another (the target). If the target is not a group, this call will create a new group and a group card to display that new group. If the target is in a group, this call will move the source into that group with the target. In all cases, the source will be removed from any groups (including dashboards) it is already in.

Request URL: /api/cards/[source-card-id]/group-with/[target-card-id]
Method: POST
Expected response code: 200 OK

Request content

No content.

Response content

A successful request will return the card object representing the group card that the source card has been moved into.

Move a card

This is a helper call to facilitate easy and safe moving of cards with a single API call. It moves the card into a target group, removing it from all other groups (or a single source group if one is specified).

Request URL: /api/cards/[card-id]/group-with/[target-group-id]
Method: POST
Expected response code: 200 OK

Request content

No content.

Request parameters

Parameter

Details

sourceGroupId

The Id of a card group which the card is already in. If provided, the card will be removed only from this group. If not provided, the card will be removed from all groups that it belongs to.

Response content

A successful request will return the card object representing the card that has been moved.

Create card group

Creates a card group containing specified card ids. This call does not remove cards from existing groups. Nor does it create a group card to display the card group. Take care to avoid creating card groups that are not displayed anywhere in Watershed or listing cards in multiple groups.

Request URL: /api/card-groups
Method: POST
Expected response code: 201 created

Request content

The request should contain a JSON formatted card group object (see Entity Model). This object does not need to include an id.

Response content

A successful request will return a complete card object including id.

Create group card

Creating the group card follows the same pattern as for creating any other card as outlined above. The template id for group cards is 281 and the configuration object contains a single property, cardGroupId. The value of cardGroupId is the id of the card group you want the group card to display.

Update card group

Updates a card group. Normally used to edit the list of cards included in the group. This call does not remove cards from existing groups, nor does it put removed cards anywhere else. Take care to avoid listing cards in multiple groups, or leaving cards without any group at all. Cards belonging to no group will not be displayed to the user.

Request URL: /api/card-groups/[card-group-id]
Method: PUT
Expected response code: 204 No Content

Request content

The request should contain a JSON formatted card group object including id (see Entity Model).

Response content

No content

Please note: you can also update card groups by custom id using the /api/card-groups resource and customId parameter.

Get card groups

Request URL: /api/organizations/[org-id]/card-groups/
Method: GET
Expected response code: 200 OK

Response content

No content.

Request parameters

Parameter

Details

name

Return only the named card group

customId

Return only this customId

user.id

Return the 'Your Dashboard' of a user with this id.

Response content

A successful request will return a collection of card groups relating to the organization and filter parameters specified.

Get dashboards

Request URL: /api/organizations/[org-id]/dashboards/
Method: GET
Expected response code: 200 OK

This call is identical to ‘get card groups’ except that only dashboards are returned. ‘Get card groups’ will return all groups including dashboards.

Entity Model

Card

Property

Value

id

Numerical id of the card. This is set by watershed so is not required when creating cards.

customId

An optional custom id for the card. Cards can be fetched by customId using the customId parameter.

configuration

Object identical to the advanced configuration JSON required to create the card using Activity Explorer.

organization.id

id of the Watershed organization in which the card will be created.

template.name

Name representing the card type to be created. See the list below.

template.id

Deprecated - use template.name instead. Id representing the card type to be created.

title

String - title of the card. Displayed on both dashboard and report views.

description

String - description of the card. Displayed at the top of the report.

summary

String - summary of the card. Displayed on the dashboard.

Card types and template ids

The list below lists the names of the different types of card available in Watershed. You can get a complete and up to date list of card types at any time by making a GET request to the api/card-templates/ resource.

  • accomplishment
  • activity
  • bar
  • correlation
  • heatmap
  • interactions
  • leaderboard
  • line
  • person
  • program
  • range
  • scatter
  • spider
  • card-group

Card group

Property

Value

id

Id of the card group. This is set by watershed so is not required when creating the card group.

name

Name of the card group. This is not displayed to the user anywhere and can be thought of as an alternative developer-readable id.

dashboard

true or false. If true, the group will be listed as a dashboard.

cardIds

An array of card ids to include in the group.

organization.id

The organization to create the group inside.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

If you can't find what you need or you want to ask a real person a question, please contact customer support.