Add-on Tool Administration and Development

To use Seeq Add-on Tools, you must have Seeq Data Lab installed and configured. If not, please contact your Seeq Sales Representative to learn how.

Overview

Add-on Tools appear in an “Add-ons” group on the Seeq Tools panel. These tools open an app-mode SDL notebook.

 

 

 

Configuration

An admin user can enable Add-on Tools through the Administration panel from the hamburger menu in the top right of Seeq. Navigate to the “Configuration” tab, change the “Advanced” column to “yes” and switch Features/AddOnTools/Enabled to true.

 

For R22.0.49-R51, use Features/ExternalTools/Enabled in place of Features/AddOnToolsEnabled.

Managing Add-on Tools

There are currently three different notebooks that may be used for managing Add-on tools, depending on the version of Seeq and SPy. For questions regarding Add-on Tool Manager compatibility for your Seeq server, please contact Seeq support.

In order of preferred use provided the requirements are met, these are :

Option 1 - preferred

  • Requires spy.addons (SPy version : 182.22+). If using Seeq version R53.4.2+, R54.1.2+, or R55+, the SPy version is satisfied by default.

  • Note: Installation instructions are provided in the first cell of this notebook.

Option 2 - deprecated

This option is no longer receiving support and should only be used for Seeq versions between R52.1.4 and R53.4.2.

Option 3 - deprecated (ONLY for naming convention of “External Tools”)

  • No longer receiving support.

Use the following Notebook for versions up to and including 52.1.4 (Add-on Tools were previously named External Tools):

This Notebook will need to manually changed when you upgrade your Seeq server past R52.1.4.

 

Installation

To begin installation, open a Seeq Data Lab Project and Upload the Jupyter Notebook to that project:

Starting on Seeq Data Lab version R50+, appmode and nbextension are already enabled. If Seeq Data Lab is not on R50+, enable appmode using New → Terminal and executing the following commands:

1 2 3 pip install appmode jupyter nbextension enable --py --user appmode jupyter serverextension enable --py --user appmode

 

Option 1 Installation Instructions

See jupyter notebook.

 

Option 2 - Installation Instructions

Open the Jupyter Notebook. You should now see an “Appmode” button to open the Notebook in application mode. Click on this and a UI as shown below should open after the code runs:

 

 

Fill out the tool for “Add-on Tool Management as follows, using the complete URL for the current Notebook in appmode as the “Target” (see description of Target in “Installing New Add-on Tools” section below for details of adding query parameters related to the Analysis from which the Add-on Tool was opened):

Name: Add-on Tool Management
Description: Install and Modify Add-on Tools
Icon: fa fa-wrench
Target: <URL>
Link Type: window
Window Details: toolbar=0,location=0,scrollbars=1,statusbar=0,menubar=0,resizable=1,height=600,width=600
Sort Key: a
Reuse Window: checked
Allowed Groups: <user groups as desired, separated by commas>
Allowed User: <usernames as desired, separated by commas>

Press “Create New” and once the Notebook has finished executing, refresh Seeq Workbench and “Add-ons” with “Add-on Tool Management” option should now be available to the users selected in the “allowed groups/users”.

Option 3 - Installation Instructions

Seeq API can be used directly through the hamburger menu in the top right corner of Seeq. The appropriate API endpoint for Add-on Tool management is POST/system/configuration/addOnTools and requires the same inputs as listed out above in Option 1.

Installing New Add-on Tools

After installing the Add-on Management Tool as the first add-on tool, the UI can be used to install additional Add-on Tools. This section goes through the various inputs for each of the tools:

Name: The name of the tool shown in green text in the Add-on Tool button.

Description: The description shown in black text underneath the Name. Long descriptions will wrap to the next line and increase the height of the Add-on Tool button.

Icon: Any Font Awesome icon to show in green next to the Name. Potential Font Awesome icons can be found at the website https://fontawesome.com/v4.7.0/icons/ and take the form of “fa fa-<icon>”

Target: The target is the URL that you want opened. This can link to a website or most commonly is a Seeq Data Lab Notebook in appmode. In order to get the Target URL for a Seeq Data Lab Notebook, open the desired Notebook in appmode and copy the URL that includes “/apps/” that indicates the Notebook is in appmode. For example:

1 https://explore.seeq.com/data-lab/F75365B4-C764-4236-8B5B-AE3AC54FE0E6/apps/Add-on%20Tool%20Management%20UI-TEST.ipynb?

The workbookId, worksheetId, workstepId, and/or seeqVersion parameters from the launched workbook can be passed through the the URL as query parameters after the “.ipynb?”. For example:

1 https://explore.seeq.com/data-lab/F75365B4-C764-4236-8B5B-AE3AC54FE0E6/apps/Add-on%20Tool%20Management%20UI-TEST.ipynb?workbookId={workbookId}&worksheetId={worksheetId}&workstepId={workstepId}&seeqVersion={seeqVersion}

Link Type: Choose whether the Add-on Tool should launch a new tab or window.

Window Details: Choose the characteristics of the window that opens. Options are available at the website https://developer.mozilla.org/en-US/docs/Web/API/Window/open#Window_features. An example of this is shown below:

1 toolbar=0,location=0,scrollbars=1,statusbar=0,menubar=0,resizable=1,height=600,width=600

Sort Key: Add-on Tools will sort in alphabetical order based on this sort key.

Reuse Window: Only used if window is selected for Link Type. False means that a new window is opened each time the tool card is clicked.

Allowed Groups/Users: Groups and users that have permission to see and use the add-on tool. If the Add-on Tool Target points to a Data Lab Notebook, then any permissions set on the Add-on Tool will also be added to the target Data Lab Project as users are required to have at least write permissions on the Data Lab Project to run the Notebook.

Deleting Existing Add-on Tools

With the spy.addons version of the Add-on Management UI (version 2), an uninstall button is provided for uninstalling add-ons. In previous iterations this is not available, and Add-on Tools should be deleted using the API with the System Endpoint.

Navigate to System >> GET/system/configuration/addOnTools:

Hit the “Try it out!” button and go down to the response body:

You want to grab the “id” value of the Tool you want. For example, in the above, if I wanted to delete the Add-on Tool Manager add-on tool, I would take the id of 5FB4376E-103C-4C6B-8C5C-1967C9847734. Copy that ID into the DELETE/system/configuration/addOnTools/{id} endpoint and hit “Try it Out!”:

Assuming you don’t get an error response, you should be able to go back to workbench, refresh the page, and it should be removed.

Common Code Snippets for use in Add-on Tools

The following snippets can be used by Add-on Tool creators to extract and make use of the query parameters or otherwise modify the state of the Add-on Tool.

Retrieve parameters (e.g. workbook ID, worksheet ID) from Target URL:

1 2 3 4 5 6 7 import urllib.parse as urlparse from urllib.parse import parse_qs url = jupyter_notebook_url parsed = urlparse.urlparse(url) workbook_id = parse_qs(parsed.query)['workbookId'][0] worksheet_id = parse_qs(parsed.query)['worksheetId'][0]

Remove “Edit App” button in corner of appmode Notebooks: This removes the entire header. That is, it will hide the Seeq Data Lab logo, the Edit App button, and the spinner “gears” when loading

1 2 %%javascript $('#header-container').hide();

To only remove the Edit App button:

1 2 from IPython.display import display, HTML display(HTML("<style>#appmode-leave {display: none;}"))

Retrieve all items on current workbook display:

1 2 3 4 5 6 7 8 9 10 11 from seeq import spy import urllib.parse as urlparse from urllib.parse import parse_qs url = jupyter_notebook_url parsed = urlparse.urlparse(url) workbook_id = parse_qs(parsed.query)['workbookId'][0] worksheet_id = parse_qs(parsed.query)['worksheetId'][0] host = spy.client.host[:-3] URL = host+'workbook/'+workbook_id+'/worksheet/'+worksheet_id worksheet_items = spy.search(URL)

Retrieve start and end timestamps from current workbook display and store as values in ipydatetime widgets:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 from seeq import sdk from datetime import datetime import json import urllib.parse as urlparse from urllib.parse import parse_qs import ipydatetime url = jupyter_notebook_url parsed = urlparse.urlparse(url) workbook_id = parse_qs(parsed.query)['workbookId'][0] worksheet_id = parse_qs(parsed.query)['worksheetId'][0] workstep_id = parse_qs(parsed.query)['workstepId'][0] workbooks_api = sdk.WorkbooksApi(spy._login.client) data = workbooks_api.get_workstep(workbook_id=workbook_id, worksheet_id=worksheet_id, workstep_id=workstep_id).to_dict()['data'] data_dict = json.loads(data) start = data_dict['state']['stores']['sqDurationStore']['displayRange']['start'] end = data_dict['state']['stores']['sqDurationStore']['displayRange']['end'] start_time = datetime.fromtimestamp(start/1000).astimezone() end_time = datetime.fromtimestamp(end/1000).astimezone() start_select = ipydatetime.DatetimePicker(description='Start Time: ', value=start_time) end_select = ipydatetime.DatetimePicker(description='End Time: ', value=end_time)
  1. ipyvuetify

  2. ipywidgets

  3. ipydatetime

  4. ipyaggrid

  5. qgrid