1. Watershed LRS
  2. API Reference
  3. Watershed APIs

Dashboard and Report API

Avatar
Peter Dobinson

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

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

 Please note: This guide is designed to compliment 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.

Concepts

Reports / Card

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

"Card" is the term we used to use for reports in Watershed. The term "card" has been replaced with "report" thoroughout our user interface, but we still use "card" in our API. To keep things simple and because we're talking about the API, the rest of this article uses the term "card", but be aware that cards and reports are just two different names for exactly the same thing.

 Reports vs. Cards: "card" is the term we used to use for reports and still use in our API. Both terms mean exactly the same thing.

Card types (aka templates)

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

One special card type that does not appear in the report-type 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.  This API is only accessible to those with Administrative Credentials.

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 parameters

Parameter

Details

tenantId

The Id of the organization that the card is on.

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.

Example using Python 3:

import json
import requests

# Build the card configuration IDENTICAL to a report advanced configuration. 
config = '''{
"quickFilters": {
"activities": {
"type": "all"
},
"people": {
"type": "all"
},
"verbs": {
"type": "all"
},
"dates": {
"type": "all"
}
},
"filter": {
"activityIds": null,
"personIds": null,
"groupIds": null,
"dateFilter": {
"dateType": "none",
"trailingAmount": 1,
"trailingType": "days",
"customDateFrom": null,
"customDateTo": null
},
"includeRelatedActivities": false
},
"type": "leaderboard",
"dimensions": [
{
"type": "STATEMENT_PROPERTY",
"statementProperty": "actors.person.id"
}
],
"measures": [
{
"name": "Interaction Count",
"aggregation": {
"type": "COUNT"
},
"valueProducer": {
"type": "STATEMENT_PROPERTY",
"statementProperty": "object.id"
},
"id": 101,
"measureCategoryName": "None",
"menuPosition": 0
}
]
}'''

# Build the body of the request
## Of special note, the config above must be converted to json.
data = {
"configuration": json.loads(config),
"organization": {"id": 1234},
"template": {"name": "leaderboard"},
"title": "My New Leaderboard",
"description": "This is a description of the card",
"summary": "This is a summary of the card"
}

# Send the request to watershed
uname = "your_watershed_username"
pword = "your_watershed_password"
url = "https://sandbox.watershedlrs.com/api/cards"
r = requests.post(url, auth=(uname, pword), json=data)

# The response to a successful request is as follows:
{'id': 120315,
 'created': '2021-10-27T14:23:08Z',
 'updated': '2021-10-27T14:23:08Z',
 'version': 1,
 'template': {'id': 332,
  'created': '2016-02-01T18:49:39Z',
  'updated': '2019-01-22T13:59:16Z',
  'version': 4,
  'name': 'leaderboard',
  'title': 'Leaderboard',
  'description': 'This report allows a user to group and list data from statements.',
  'cardType': 'activity',
  'assetLocation': 'modules/app/lister/lister-card.html',
  'configurationAssetLocation': 'modules/app/lister/config/lister-config.html',
  'imageUrl': './img/card-templates/leaderboard.png',
  'hasDetailPage': True,
  'sharingEnabled': True,
  'explorable': True},
 'organization': {'id': 9991,
  'created': '2020-11-17T17:37:14Z',
  'updated': '2021-10-27T13:01:04Z',
  'version': 286,
  'name': 'Your Watershed Org',
  'lastAccessDay': '2021-10-27',
  'hasStatements': True,
  'markedStale': False,
  'settingsCacheKey': 'organization-settings-9991',
  'expired': False},
 'title': 'My New Leaderboard',
 'cardGroupIds': [],
 'configuration': {'filter': {'dateFilter': {'dateType': 'none',
    'trailingAmount': 1,
    'trailingType': 'days',
    'olderThanAmount': 0,
    'olderThanType': 'none',
    'fieldName': 'timestamp'},
   'includeRelatedActivities': False},
  'version': 3,
  'cachingMinutes': 5,
  'quickFilters': {'verbs': {'type': 'all'},
   'activities': {'type': 'all'},
   'people': {'type': 'all'},
   'dates': {'type': 'all'}},
  'colors': [],
  'dimensions': [{'type': 'STATEMENT_PROPERTY',
    'statementProperty': 'actors.person.id',
    'caseSensitive': True}],
  'measures': [{'id': 101,
    'name': 'Interaction Count',
    'aggregation': {'type': 'COUNT'},
    'valueProducer': {'type': 'STATEMENT_PROPERTY',
     'statementProperty': 'object.id'},
    'measureCategoryName': 'None',
    'menuPosition': 0}],
  'includePeopleWithoutStatements': False,
  'displayAxisDecimals': True,
  'hiddenMeasures': [],
  'showSentence': False,
  'hideDimension': False},
 'description': 'This is a description of the card',
 'summary': 'This is a summary of the card'}

Update Card

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

Request parameters

Parameter

Details

tenantId

The Id of the organization that the card is on.

Request content

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

Response content

No content.

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

Example using Python 3:

# Building from the example under "Create Card"
## let's assume we have modified the card configuration

data = {
"configuration": json.loads(updated_config),
"organization": {"id": 1234},
"template": {"name": "leaderboard"},
"title": "My New Leaderboard",
"description": "This is a description of the card",
"summary": "This is a summary of the card"
}

# Send the request to watershed
uname = "your_watershed_username"
pword = "your_watershed_password"
url = "https://sandbox.watershedlrs.com/api/cards"
r = requests.put(url, auth=(uname, pword), json=data)

Get Card by Id

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

Request parameters

Parameter

Details

tenantId

The Id of the organization that the card is on.

Request content

No content.

Response content

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

Example using Python 3:

# Get Card by ID
headers = {"X-Experience-API-Version": "1.0.3", 'Content-type': 'application/json'}
url = "https://sandbox.watershedlrs.com/api/cards/120315?tenantId=1234"
r = requests.get(url, auth=(uname, pword), headers=headers)

Get Cards

Request URL: /api/organizations/[org-id]/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.

Example using Python 3:

# Get all cards
url = "https://sandbox.watershedlrs.com/api/organizations/1234/cards"
r = requests.get(url, auth=(uname, pword))

Delete a Card

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

Request parameters

Parameter

Details

tenantId

The Id of the organization that the card is on.

Request content

No content.

Response content

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

Example using Python 3:

# Delete a card by ID:
url = "https://sandbox.watershedlrs.com/api/cards/120315"
r = requests.delete(url, auth=(uname, pword))

Get Card Data

It is possible to use the card API to fetch the data behind the card. The method to do so is documented in our Data Export API help article.

 Hint: 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 parameters

Parameter

Details

tenantId

The Id of the organization that the card is on.

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.

Example using Python 3:

# Group Cards
url = "https://sandbox.watershedlrs.com/api/cards/2551/group-with/2581?tenantId=1234"
r = requests.post(url, auth=(uname, pword))

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]/move-to-group/[target-group-id]
Method: POST
Expected response code: 200 OK

Request content

No content.

Request parameters

Parameter

Details

tenantId

The Id of the organization that the card is on.

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.

Example using Python 3:

# Move a card
url = "https://sandbox.watershedlrs.com/api/cards/2551/move-to-group/5678?tenantId=1234&sourceGroupId=7890"
r = requests.post(url, auth=(uname, pword))

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 parameters

Parameter

Details

tenantId

The Id of the organization that the card is on.

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.

Example using Python 3:

# Create Card Group
data = {
"name": "Name of the card group",
"organization": {"id": 1234},
"dashboard": True,
"cardIds": [2581, 2521, 2341],
"description": "This is a description of the card",
"summary": "This is a summary of the card"
}

# Send the request to watershed
uname = "your_watershed_username"
pword = "your_watershed_password"
url = "https://sandbox.watershedlrs.com/api/card-groups"
r = requests.post(url, auth=(uname, pword), json=data)

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 parameters

Parameter

Details

tenantId

The Id of the organization that the card is on.

Request content

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

Response content

No content

Example using Python 3:

# Update Card Group
data = {
"name": "Name of the card group",
"organization": {"id": 1234},
"dashboard": True,
"cardIds": [2581, 2521, 2341],
"description": "This is a description of the card",
"summary": "This is a summary of the card"
}

# Send the request to watershed
uname = "your_watershed_username"
pword = "your_watershed_password"
url = "https://sandbox.watershedlrs.com/api/card-groups"
r = requests.put(url, auth=(uname, pword), json=data)

 Hint: 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

tenantId

The Id of the organization that the card is on.

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.

Example using Python 3:

# Get all card groups
url = "https://sandbox.watershedlrs.com/api/organizations/1234/card-groups"
r = requests.get(url, auth=(uname, pword))

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.

Example using Python 3:

# Get all card groups
url = "https://sandbox.watershedlrs.com/api/organizations/1234/dashboards"
r = requests.get(url, auth=(uname, pword))

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 the report builder.

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

Related articles

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