Building a Worksheet from URL Query Parameters
Overview
You can create an entire Seeq worksheet by passing query parameters to a special URL endpoint in Seeq Workbench.
How it Works
The worksheet builder creates or updates a worksheet in Seeq by reading a special URL from a browser. The URL is routed to a special endpoint, /workbook/builder, on the Seeq server, which processes the query parameters (see below) to construct or update a worksheet. To construct the builder URL, first open Seeq Workbench to a workbook that is not in a folder; then copy the URL, starting with https:// or http:// (this may be hidden by the browser), followed by the Seeq server domain name or machine name, and ending with the text /workbook. (For the curious, the random string of characters after /workbook/ is the workbook ID - followed by /worksheet/, and then, you guessed it, the worksheet ID. The ID is called a GUID or UUID. If you didn't follow the instructions and opened up a workbook in a folder, your URL will have a GUID for the folder before the /workbook part. Moving on...) Thus, if your Seeq server is at the domain name seeq.company.site, your builder URL might look like
https://seeq.company.site/workbook/builderOnce you have a valid path to the builder, it's time to add some query parameters. Query parameters are used to explain to the builder which workbook and worksheet to use or create, which items should be in the Details pane, and what times to use for the display and investigate ranges.
Query Parameters
The following query parameters are parsed and processed by the Seeq Workbench builder endpoint. Modern browsers can URL encode special characters like spaces and question marks, so you probably don't need to add these yourself. Some of the example below use URL encoding while others do not. You can see the encoded/decoded versions of the URLs by passing the decoded/encoded URLs, respectively, into a parser like https://meyerweb.com/eric/tools/dencoder/. You will need to place a question mark (?) after the builder URL you constructed above before adding the query parameters. These are added in the form
parameterName=parameterValue and are separated by ampersands (&). You can use the trendItems parameter as many times as necessary to add the items you wish to add to the worksheet.
Workbook and Worksheet
workbookName
The name of the workbook to create or the name of an existing workbook to add the new worksheet to. If you have access to multiple workbooks with the same name, you can specify the workbook ID as the "name" passed into workbookName.
Default value = Generated Workbook
Example: workbookName=TestWorkbook
workbookFilter
By default the search for a workbook using workbookName is restricted to those that are owned by the current user. The following options can be used:
SHARED: only workbooks where the current user has been given access will be searched.
ALL: all workbooks the current user has access to will be searched.
CORPORATE: all workbooks in the Corporate Drive
worksheetName
The name of the worksheet to create or update. It can also be the ID of the worksheet. It is unlikely you will need to use the worksheet ID, since worksheets are usually uniquely named within workbooks.
Default value = worksheet
Example: worksheetName=TestWorksheet
Worksheet Contents
trendItems
Specifiers for items to be added to the trend. This parameter can be used more than once. Items can be specified several different ways:
Name. A string will find any items that match by name.
Example: trendItems=item
Matching/Filtering. A more advanced search can use filters to match on fields other than name, using the syntax available in the filters parameter in the /items API.
Example: trendItems=name~=item && datasource id==example data
Full Asset Path. An item can be specified by its asset path, with >> delimiting each level of the path.
Example: Example >> Cooling Tower 1 >> Area A >> Temperature
Multiple queries can be specified using multiple trendItems query parameters.
Example: trendItems=trendOne&trendItems=trendTwo
If there is a need to retrieve items that have the property unsearchable, you can add trendItems=@includeUnsearchable as one of the parameters
If you know the item's ID you can use that to specify the item.
Example: trendItems=FDEFF938-8854-4313-A312-BB29E8CB9769
Note that the items matched will be limited to those that are scoped to the workbook or are in the global scope (which is the same behavior when searching for items in an Analysis).
expandedAsset
A single asset for which to show the child Items in the Data tab. The asset can be specified by name, ID, or full path.
Example: expandedAsset=Area A
Example: expandedAsset=Example >> Cooling Tower 1 >> Area B
Example: expandedAsset=FDEFF938-8854-4313-A312-BB29E8CB9769
assetSwap
A single asset to which all Items in the Details panel will be swapped, if possible. Asset can be specified by name, ID, or full path.
Example: assetSwap=Area B
Example: assetSwap=Example >> Cooling Tower 1 >> Area B
Example: assetSwap=FDEFF938-8854-4313-A312-BB29E8CB9769
Dates and Times
The following four parameters relate to the dates and times. These parameters can be specified in one of two forms:
ISO-8601 format. Example: 2016-06-08T08:00:00Z
Relative to now (*). To specify a date for days in the past from the current time: *-4d
investigateStartTime, investigateEndTime
Date and time strings that represent the start and end time for the investigation range. If only one parameter is specified, the other is automatically calculated by adding or subtracting 2 months.
Example: investigateStartTime=2016-01-01T00:00:00-07:00&investigateEndTime=2016-04-01T00:00:00-07:00
displayStartTime, displayEndTime
Date and time strings that represent the start and end time for the display range. If only one parameter is specified, the other is automatically calculated by adding or subtracting 7 days.
Example: displayStartTime=*-14d&displayEndTime=*
Other Parameters
startFresh
If true, the workstep will be built using only what is provided by the builder parameters. If false, it will build upon the most recent workstep of the worksheet; this enables the use of a worksheet as a template for new worksheets for related assets.
Default value = true
Example: startFresh=false with workbookName=A11319EC-8B3C-4CEA-8AE4-08857D731168
viewMode
Controls whether the worksheet is launched in edit, view-only, or presentation mode. When launched in view-only or presentation mode no permanent changes will be made to the worksheet (i.e. no new worksteps created).
Default value = edit
Example: viewMode=view
Example: viewMode=present
selectedTab
Controls which tab the worksheet will open on. The options are SEARCH (asset tree view), INVESTIGATE (tool pane), and ANNOTATE (journal).
Default value = SEARCH
Example: selectedTab=INVESTIGATE
Example: selectedTab=ANNOTATE
Examples
Example 1: workbook name, multiple trend items by name/description string search, expanded asset by name, fixed investigate and display ranges
https://seeq.company.site/workbook/builder?workbookName=Test%20Workbook&trendItems=Area%20A_Temperature&trendItems=Area%20A_Compressor%20Power&investigateStartTime=2016-01-01T00%3A00%3A00Z&investigateEndTime=2016-04-01T00%3A00%3A00Z&displayStartTime=2016-02-01T00%3A00%3A00Z&displayEndTime=2016-03-01T00%3A00%3A00Z&expandedAsset=Area%20A
Example 2: workbook and worksheet name, trend items by name/description string search, fixed investigate and display ranges
https://seeq.company.site/workbook/builder?workbookName=Test%20Workbook&worksheetName=Test%20Worksheet&trendItems=Area%20A_Compressor%20Power&investigateStartTime=2016-01-01T00:00:00Z&investigateEndTime=2016-04-01T00:00:00Z&displayStartTime=2016-02-01T00:00:00Z&displayEndTime=2016-03-01T00:00:00Z
Example 3: single trend item by asset path
https://seeq.company.site/workbook/builder?trendItems=Example>>Cooling%20Tower%201>>Area%20A>>Compressor%20Power
Example 4: trend items by advanced item filter
https://seeq.company.site/workbook/builder?trendItems=Description%7E%3DArea+A+%26%26+Datasource+ID%3D%3DExampleData
Example 5: Add a couple of items to a workbook/worksheet pair by path; then swap to a new Asset (N.B.: for this to work, the equivalent swap in Workbench must not necessitate the modal; no modal is necessary if all items in the Details panel are children of or derived from children of the same parent)
https://seeq.company.site/workbook/builder?workbookName=SwapByBuilder&worksheetName=SwappableWorksheet&trendItems=Example>>Cooling Tower 1>>Area B>>Compressor Power&trendItems=Example>>Cooling Tower 1>>Area B>>Temperature
https://seeq.company.site/workbook/builder?workbookName=SwapByBuilder&worksheetName=SwappableWorksheet&startFresh=false&assetSwap=Example>>Cooling Tower 1>>Area C