Accessing Dashboards from Your Application
This chapter describes how to access DeepSee dashboards and the DeepSee User Portal from your application. It discusses the following topics:
Accessing a Dashboard
To access a dashboard, use a URL of the following form:
http://localhost:57772/csp/samples/_DeepSee.UserPortal.DashboardViewer.zen?DASHBOARD=dashbdname.dashboard
Where localhost:57772 is the server and port on which Caché is running, samples is the namespace in which the dashboard is defined, and dashbdname is the name of the dashboard, including the folder to which it belongs, if any.
More generally, use a URL of the following form:
http://localhost:57772/csp/samples/_DeepSee.UserPortal.DashboardViewer.zen?parmstring&parmstring&parmstring...
Where parmstring is a parameter, followed by an equals sign, followed by a value. For example:
DASHBOARD=Drill%20Options.dashboard
As shown previously, use an ampersand (&) to combine multiple parameter strings. For example:
DASHBOARD=Drill%20Options.dashboard&NOMODIFY=1
URL Encoding
Certain characters have reserved meanings in a URL and others are disallowed. To include such a character in parmstring, replace the character with the URL-encoded version (also called percent-encoded). The easiest way to do this is as follows:
-
Identify all the strings that could potentially include reserved or disallowed characters.
-
For each such string, do the following in sequence:
-
Convert to UTF-8 encoding
-
Create a URL-encoded version of the string.
If you are performing these transformations on the server, you can use an ObjectScript function such as $ZCONVERT or $TRANSLATE. For example:
set UTF8db=$ZCONVERT(dashboardname,"O","UTF8") set escapeddb=$ZCONVERT(UTF8db,"O","URL") set url=baseurl_"DASHBOARD="_escapeddb
If you are performing these transformations on the client, use a suitable client function. For example, if the client uses JavaScript, use the encodeURI()Opens in a new tab function.
-
Or use other logic such as the $TRANSLATE function. Some of the most commonly used characters are these:
Character | URL-Encoded Version |
---|---|
space character | %20 |
& | %26 |
, | %2C |
You can find lists of URL-encoded characters on the Internet; one resource is Wikipedia (http://en.wikipedia.org/wiki/Percent-encodingOpens in a new tab).
Available URL Parameters
You can use the following case-sensitive parameters within the dashboard URL. Note that for some parameters, you can use either a plain-text version or an encrypted version. For example, the dashboard URL can include an encrypted version of the dashboard name.
DASHBOARD=dashbdname.dashboard
This parameter specifies the dashboard to display. You must specify either this parameter or the XDASHBOARD parameter.
dashbdname is the name of the dashboard, including the folder to which it belongs, if any. For example:
DASHBOARD=Dashboards/Dashboard%20with%20Filters%20and%20Listing%20Button.dashboard
Here %20 represents a space character; see “URL Encoding,” earlier in this chapter.
XDASHBOARD=encryptedvalue
Encrypted version of the DASHBOARD parameter. You can use parameter only within the context of a CSP session. You must specify either this parameter or the DASHBOARD parameter.
To create encryptedvalue, start with the name of the dashboard, including the folder to which it belongs, if any. For example:
Dashboards/Dashboard with Filters and Listing Button.dashboard
Do not include URL escaping; for example, leave a space as a space character.
Then use the Encrypt() class method of %CSP.PageOpens in a new tab to encrypt this value. Use the value returned by Encrypt() as the value of the XDASHBOARD parameter.
EMBED=1
If this parameter is 1, the dashboard is displayed in embedded mode. This is equivalent to setting NOTITLE=1, NOMODIFY=1, NOBORDER=1, and WORKLISTS=0.
XEMBED=encryptedvalue
Encrypted version of the EMBED parameter. You can use parameter only within the context of a CSP session.
To create encryptedvalue, start with the value you would use for EMBED. Then use the Encrypt() class method of %CSP.PageOpens in a new tab to encrypt this value. Use the value returned by Encrypt() as the value of the XEMBED parameter.
NOTITLE=1
If this parameter is 1, the dashboard is displayed without a title area. The title area is the top area, as in the following example:
![generated description: settings dashboard title area](images/d2imp_settings_dashboard_title_area.png)
NOMODIFY=1
If this parameter is 1, the dashboard cannot be modified. This option removes items from Menu. It also suppresses the edit options on widgets, so that a widget includes only minimize, maximize, and remove options in the upper right.
NOBORDER=1
If this parameter is 1, the dashboard is displayed without the border.
RESIZE=boolean
Specifies whether the widgets can be resized and moved. If boolean is 1 (the default), the widgets can be resized and moved. If boolean is 0, they cannot.
WORKLISTS=n
Where n is 0, 1, or 2. This parameter specifies the number of worklist areas to display on the left.
XWORKLISTS=encryptedvalue
Encrypted version of the WORKLISTS parameter. You can use parameter only within the context of a CSP session.
To create encryptedvalue, start with the value you would use for WORKLISTS. Then use the Encrypt() class method of %CSP.PageOpens in a new tab to encrypt this value. Use the value returned by Encrypt() as the value of the XWORKLISTS parameter.
SCHEME=schemename
Specifies the color scheme for the dashboard (if you do not want to use the default). For schemename, specify a scheme as listed in the General tab of the Settings page. See “Specifying Basic Settings,” earlier in this book.
SETTINGS=name1:value1;name2:value2;name3:value3;...;
Where name1, name2, name3, and so on are names of dashboard settings, as described in the next section, and value1, value2, value3, and so on are the values for the settings.
You can include this parameter multiple times in the URL.
For example, to pass values to all widgets in a dashboard, use a URL of the following form:
basic_dashboard_url&SETTINGS=name:value;name:value;name:value;...;
To pass values to a specific widget in a dashboard, use the following variation:
basic_dashboard_url&SETTINGS=TARGET:widgetname;name:value;name:value;name:value;...;
To pass values to multiple widgets in a dashboard, use the following variation:
basic_dashboard_url&SETTINGS=...;&SETTINGS=...;&SETTINGS=...;...;
A setting for a specific widget always takes precedence over settings for all widgets. Otherwise, the settings are applied in the order in which they are specified; if one setting is inconsistent with another setting, the later setting takes effect. These settings do not take precedence over any user settings.
XSETTINGS=encryptedvalue
Encrypted version of the SETTINGS parameter. You can use parameter only within the context of a CSP session.
To create encryptedvalue, start with the value that you would use with SETTINGS. Then use the Encrypt() class method of %CSP.PageOpens in a new tab to encrypt this value. Use the value returned by Encrypt() as the value of the XSETTINGS parameter.
CacheUserName=myuser&CachePassword=mypass
Where myuser is a Caché username and mypass is the corresponding password. Include these parameters if the user has not yet logged in to Caché.
AUTOSAVE
Requests the autosaved version of the dashboard. For information on the autosave feature, see “Specifying Basic Settings,” earlier in this book.
Options for the SETTINGS Parameter
For the SETTINGS URL parameter, you can use settings given in the following list. Any SETTINGS string either applies to all widgets or applies to a specific widget. Include as many SETTINGS strings as you need. For example:
basic_dashboard_url&SETTINGS=...;&SETTINGS=...;&SETTINGS=...;...;
When Caché parses a SETTINGS parameter, it assumes that any semicolon is a delimiter between two different settings strings. To include a semicolon and not have it treated as a delimiter, you must replace it with %3B%3B (this sequence is two URL-encoded semicolons; it is necessary to use two URL-encoded semicolons because of how the parsing is performed).
TARGET:widgetname
Specifies the widget to which this set of settings applies. If you want the settings to apply to all widgets, omit this parameter from the SETTINGS string.
FILTER:filter_name.filter_values
Specifies how to filter the given widgets. The arguments depend upon the details of the target widget as follows:
Scenario | filter_name | filter_values |
---|---|---|
Target widget displays a pivot table | URL-encoded version of [dimension].[hierarchy].[level] | URL-encoded version of the allowed filter values that are shown in “Allowed Default Values for Filters” in the chapter “Configuring Settings” |
Target widget displays a KPI | URL-encoded version of the name of a filter defined in that KPI | URL-encoded version of an allowed value for this filter, as defined in the KPI |
For information on creating URL-encoded strings, see “URL Encoding,” earlier in this chapter.
Notes:
-
You can use the special token $$$FILTERS in place of filter_name.filter_value. This is useful if you use the URL in a custom navigate action (which accesses another dashboard from a given dashboard; see “Displaying a Different Dashboard,” elsewhere in this book). In this scenario, $$$FILTERS is replaced with the current filter values of the original dashboard. For example:
FILTER:$$$FILTERS
The target dashboard should include the same filters.
-
You can use multiple filter specifications; to do so, separate them with a tilde (~). For example:
FILTER:filterspec1~filterspec2
Where each filterspec is filter_name.filter_values
-
Each target widget must also be configured to include a filter control (possibly hidden) that uses the same filter. For example, suppose that a widget includes a Cities filter control, and has no other filter controls. You can include &SETTINGS=FILTER:[Cities].%26[Centerville] in the dashboard URL and that will filter this widget. If you include &SETTINGS=FILTER:[ZIP].%26[34577], that does not affect the widget.
-
To use multiple members of the same filter together, use a set expression that lists those members; see “Allowed Default Values for Filters” in the chapter “Configuring Settings.” (If you include the same filter multiple times within the SETTINGS string, DeepSee uses the last value that you provide; this is probably not the behavior that you want.)
VARIABLE:variable_name.variable_value
Specifies the value of the given pivot variable. For information on pivot variables, see “Defining and Using Pivot Variables” in Using the DeepSee Analyzer.
You can use the special token $$$VARIABLES in place of variable_name.variable_value. This is useful if you use the URL in a custom navigate action (which accesses another dashboard from a given dashboard; see “Displaying a Different Dashboard,” elsewhere in this book). In this scenario, $$$VARIABLES is replaced with the current values of the given pivot variables, as specified in the original dashboard. For example:
VARIABLE:$$$VARIABLES
ROWCOUNT:n
Specifies the maximum number (n) of rows to display; this applies only when members are displayed as rows.
COLCOUNT:n
Specifies the maximum number (n) of columns to display; this applies only when members are displayed as columns.
ROWSORT:measure
Specifies the measure by which to sort the rows. Here measure is the MDX identifier for the measure. For example:
ROWSORT:[MEASURES].[mymeasure]
Note that you cannot omit the square brackets of these identifiers (in contrast to other uses of MDX in DeepSee).
COLSORT:[MEASURES].[my measure]
Specifies the measure by which to sort the columns. Here measure is the MDX identifier for the measure; see ROWSORT.
ROWSORTDIR:sortkeyword
Specifies how to sort the rows. Here sortkeyword is one of the following:
-
ASC — Sort in ascending order but preserve any hierarchies.
-
DESC — Sort in descending order but preserve any hierarchies.
-
BASC — Sort in ascending order and break any hierarchies.
-
BDESC — Sort in descending order and break any hierarchies.
COLSORTDIR:sortkeyword
Specifies how to sort the columns. See ROWSORTDIR.
PORTLET:portlet_setting.value
Specifies the value for a portlet setting, to override any configured value for that setting. As with the other SETTINGS options, this setting is applied to all widgets listed by the TARGET parameter (or all portlet widgets if TARGET is not specified).
Here portlet_setting must be the name of the setting as defined in the portlet, and value must be the URL-encoded version of an allowed value for this setting. For information on creating URL-encoded strings, see “URL Encoding,” earlier in this chapter.
You can use multiple portlet specifications; to do so, separate them with a tilde (~). For example:
PORTLET:portletspec1~portletspec2
Where each portletspec is portlet_setting.value
For information on defining portlets, see the chapter “Creating Portlets for Use on Dashboards.”
To see an example, display the dashboard Widget Examples/Custom Portlet, which displays a round clock, and then add the following to the end of the URL in the browser:
&SETTINGS=PORTLET:CIRCLE.0~SIZE.200
Then press Return. You should see the clock change into a square, slightly larger than it had previously been.
For example, the following limits the column count to 3 for most widgets but limits the column count to 1 for the widget RegionVsYear.
&SETTINGS=TARGET:RegionVsYear;COLCOUNT:1;&SETTINGS=COLCOUNT:3;
These settings are not supported for custom widgets or custom controls.
Embedding a Dashboard in a Zen Page
To embed a dashboard in a Zen page:
-
Place an <iframe> element within the Zen page.
-
For the <iframe> element, set the src attribute equal to _DeepSee.UserPortal.DashboardViewer.zen along with the appropriate URL parameters as described earlier in this chapter. Within this value, substitute & for any ampersand, and substitute < for any left angle bracket.
For example:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"] { <page xmlns="http://www.intersystems.com/zen" title=""> <iframe width="1000" height="800" src="_DeepSee.UserPortal.DashboardViewer.zen?DASHBOARD=Basic Dashboard Demo.dashboard" /> </page> }
For another example:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"] { <page xmlns="http://www.intersystems.com/zen" title=""> <iframe width="1000" height="800" src="_DeepSee.UserPortal.DashboardViewer.zen?DASHBOARD=Dashboards/Sample Meters B.dashboard&EMBED=1" /> </page> }
Accessing Other DeepSee Pages from Your Application
Your application can also provide direct links to other DeepSee web pages, such as the Analyzer and User Portal.
The URLs for the DeepSee web pages have the following general structure.
http://localhost:57772/csp/samples/_Package.Class
Where localhost:57772 is the server and port on which Caché is running, samples is the namespace in which you are running DeepSee, and _Package.Class is the name of the package and class that defines the page, with an underscore instead of a percent sign at the start of the package name. When you access the Analyzer or other DeepSee, this URL is shown in the toolbar or your browser.
You can use any of the applicable URL parameters with these pages; see “Available URL Parameters,” earlier in this chapter. When you use the URL for the Analyzer, you can also specify the PIVOT URL parameter, which indicates the pivot table to display. For example:
http://localhost:57772/csp/samples/_DeepSee.UI.Analyzer.zen?PIVOT=Pivot%20Features%2FConditional%20Formatting.pivot
Note that if you use the URL for the Analyzer, and you specify the AUTOSAVE URL parameter but not the PIVOT parameter, the Analyzer displays the most recently viewed item.
As with the dashboard viewere, you can embed these pages in Zen pages. The subsection shows an example.
Example: Embedding the Analyzer in a Zen Page
The following example shows the XData block for a Zen page class that embeds the DeepSee analyzer in an <iframe>:
XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{
<page xmlns="http://www.intersystems.com/zen" title="">
<iframe width="1000" height="800"
src="_DeepSee.UI.Analyzer.zen?$NAMESPACE=SAMPLES&EMBED=1" />
</page>
}