Using the "desc" Description Parameter of a Sisense Dashboard via the REST API

[JeremyFriedel]

Using the "desc" Description Parameter of a Sisense Dashboard via the REST API and the Dashboard Javascript Object

The description parameter ("desc") of the Sisense dashboard object is notable for its somewhat unique characteristic – it's not accessible or editable through the Sisense Web GUI. Consequently, this parameter can only be programmatically accessed and modified. Despite this limitation, the "desc" parameter proves valuable for storing dashboard descriptions, facilitating programmatic interactions, or embedding usage.

Editing the "desc" Parameter

The "desc" parameter, part of the dashboard API and available within the Javascript dashboard object, is primarily edited using the REST API. Unlike other dashboard parameters, there is currently no graphical user interface (GUI) method to edit or view this parameter.

To edit the "desc" parameter, utilize standard dashboard APIs such as the PATCH dashboard API. The PATCH API requires a full dashboard object, obtainable through the GET dashboard API. After editing the "desc" parameter, use the modified object in the PATCH API endpoint.

The API endpoint for modifying the "desc" parameter with a minimal payload is as follows:

PATCH ${SisenseServerDomain}/api/dashboards/{dashboardID}

with a JSON payload solely of the new description parameter with the format:

{
"desc": "Description of Dashboard Here"
}

Reading the "desc" Parameter

The description parameter can be accessed via the standard GET dashboard API endpoints or through the dashboard JS object. The "desc" parameter is available through the desc property in the JS object.

Republishing Changes

Republishing Dashboard Changes

If a dashboard is shared with other users, republish the dashboard for the changes to be visible to all other users who have access to the dashboard. Using the standard GUI republish button or the Republish (shares) API, following the same procedure as any other dashboard change in other parameters (such as in dashboard widgets).

Dashboard republishing uses the standard shares API. An example endpoint for republishing:

POST /api/shares/dashboard/${dashboardID}

The payload of this request is a standard dashboard sharesTo object. 

Accessing the "desc" Parameter Using the Javascript Dashboard Object 

The path to the `desc` parameter when viewing a dashboard in the web-native UI is available with the JS path:

prism.activeDashboard.desc

prism.activeDashboard refers to the current active dashboard object on the prism object.

Use Cases of the Description Parameter

Although not extensively used within the Sisense UI, the "desc" parameter proves beneficial for web applications hosting Sisense in an embedded form, including Sisense.js and EmbedSDK. These applications can utilize the "desc" parameter for displaying descriptions as required or programmatically interacting with them.

In Sisense.js, the dashboard object mirrors the console's dashboard object and can be used for both display and programmatic purposes. In EmbedSDK, a modified dashboard object is accessible through the asynchronous getCurrent EmbedSDK function , providing the current dashboard state.

Similar steps apply to modifying other dashboard parameters via the API, and these parameters can also be read from the JS API dashboard object.

Share your experience in the comments!