Setting up the connector requires work on both the Signals side and within the connector itself. These two parts are Signals configuration and connector configuration. The connector must be configured to enable communication with TDP and with Signals Notebook. Once the connector is configured, the DataWeave tab offers tools for setting up the desired external action in Signals Notebook. Finally, when a DataWeave template is ready, you must set up a corresponding external action in Signals Notebook.

Connector Admin Configuration

🚧

Admin Role Required

This screen is only available to users with the admin role.

If the connector is started and neither SSO nor TDP logins are configured, you will be given a bootstrap role that has admin access. Once you have configured either SSO (in step 2) or TDP login (in step 3), you will be asked to authenticate.

Pre-Requisites

To receive access the TetraScience Signals Connector, please contact your TetraScience account or support representative.

Instructions for initial installation can be found here: Installation Guide

Step 1: Access the connector

If the connector is running from the previous step, entering http://<hostname>:3003/ or https://<hostname>:3003/ to the browser should connect.

• A fresh install of the connector will not have SSL certificates set up, so the initial setup will be done through the http://<hostname>:3003/ URL.
• After providing the connector with the appropriate SSL certificates and keys, and checking the Use HTTPS? option, future interactions will occur through https://<hostname>:3003/.
• The screenshot above shows the Connector pane where the SSL certificate and private key are entered. The certificate is provided and Use HTTPS? checkbox marked.
• This pane also provides options to export (or import) the entire configuration as a JSON document. Sensitive fields (such as access tokens for TDP or Signals Notebook) are removed from the export and would need to be re-entered upon import.

Step 2 (Optional): Configure SSO and role mapping

The SSO Configuration screen (available to users with the admin role) shows the details required to use single sign-on (SSO) via Amazon Cognito.

• If configured and enabled, SSO will authorize you to use the connector after authenticating with your identity provider.
• If SSO is not fully configured and enabled, the connector requires you to authenticate directly with TDP.
• Authenticating through TDP grants you permissions that reflect your TDP role (read-only, member, admin).

The following settings are updated from this screen:

• Use single sign-on? When this box is checked and all of the other fields are completed, the SSO authentication is enabled.
• Amazon Cognito Domain: The domain used to reach the Amazon Cognito endpoints. It is configured in the Cognito user pool settings, by navigating to App integration > Domain name.

• User Pool ID: The ID of the user pool in Amazon Cognito, used to download the public keys for user token verification. It can be found in the Cognito user pool settings, under General settings.

• OAuth Settings: These settings are used to securely perform the authentication handshake with Amazon Cognito.
  • Client ID: The client ID can be found in the Cognito user pool settings, under General settings > App clients. It is automatically generated when the app client is added to the Cognito user pool.
  • Client Secret: The client secret can also be found in the same place as the client ID. The secret is like a password; it is also automatically generated when the app client is added to the Cognito user pool.

• Redirect URI: The URL to which Amazon Cognito redirects you after a successful third-party authentication. This should always be using HTTPS and must match what is configured in the Cognito user pool settings under App integration > App client settings.

• Role Mapping: This defines how the connector determines which groups in Cognito map to which roles within the connector. Currently, only a one-to-one mapping is possible. Users who have multiple groups will map to the highest level of access that any of their groups give them (readonly < member < admin). Groups are configured in the Cognito user pool settings under General settings > Users and groups.
  • Read-Only (DataWeave): Users in this group will be assigned the readonly role in the connector.
  • DataWeave Administrator: Users in this group will be assigned the dataweave-admin role in the connector.
  • Administrator: Users in this group will be assigned the admin role in the connector.

Click Save Settings on the Connector Settings page to save any changes.

If you are currently logged in using TDP authentication and you enable SSO authentication, you will remain logged in until you manually log out or your session expires.

Step 3: Setup TDP connection

The TDP Configuration screen shows the details required to connect to and authenticate with the Tetra Data Platform. This screen is only available to users with the admin role.

The following settings can be updated from this screen:

• Domain: This is the root domain for the Tetra Data Platform instance to which the connector should connect. Make sure to leave off any "api." prefix or "https://", these are added automatically when needed.
• Subdomain: For multi-tenant deployments of TDP, you may have an assigned “subdomain” for your tenant. This can be entered here. If you do not have one, leave this field blank.
• Organization: This is the “slug” of the organization within the Tetra Data Platform that this connector is associated with. This is used for connecting to Tetra Data Platform for data lake queries as well as authenticating users to the connector and determining their role when SSO is not being used.
• Service User Token: This is a user token that the connector uses when sending Elasticsearch queries or downloading files from the data lake. It should be associated with a service user with at least read-only access.

📘

Service User Token

A normal user token will work, but the short time before expiration makes them impractical for use here. For details on how to create a TDP service user and obtain a token, see how toManage Service Users .

• TDP Agent ID: This is only used when the connector performs an upload action to TDP. If you are using the connector purely for retrieve actions, you can leave this blank. To use this feature, from the Data Sources > Agents page on TDP, create a new user-defined agent. The agent ID associated with this user-defined agent – available from the Agents page – is what you should enter in this connector setting field.

Click Save Settings to save any changes.

Step 4: Signing in

There are two options to sign in: single sign-on, or TDP Username and password.

Option 1: Use of single sign-on (SSO)

If you are using this option, the dialog box associated with your SSO provider will appear here.

Option 2: Use of TDP Username and password

• When using TDP authentication, the User Login screen prompts for an email and password and attempts to authenticate the user to the Tetra Data Platform using the supplied credentials, via the connector backend. No communication from the browser directly to the Tetra Data Platform is initiated.

• If there is an error connecting to the Tetra Data Platform or the credentials are not valid, a relevant error message is displayed on the login form.
• If successful, the user information, including the user's role in the appropriate TetraScience organization, is stored in the session.
• The content of the page will automatically update based on the user’s role as described above.

Step 5: Setup Signals Notebook connection

The Signals Configuration screen shows the details required to connect to and authenticate with Signals Notebook

The following settings can be updated from this screen:

• Server URL: This is the root URL (including the port number if a nonstandard value is used) that is used to access the Signals Notebook API. The address should be reachable from the server on which the connector container is hosted.
• API key: Currently, authorization to read and write to Signals Notebook is done using a Signals Notebook API key. The API key, once generated, is available from Signals Notebook System Configuration > System Settings > API Key.

As soon as you begin editing any of the settings, the button at the bottom will switch from a disabled Saved button to an enabled Save Settings button. Click Save Settings to save the changes.

Signals Notebook Admin Configuration

Configuring external actions in Signals Notebook

📘

DataWeave Templates Required

To configure the external actions in Signals Notebook, you must have first created the associated DataWeave template and scripts in the Connector DataWeave Settings.

Suppose we have a DataWeave template example-round-trip-template that we want to associate with external actions in Signals Notebook. Below is a screenshot of such a template in the DataWeave Explorer. The expanded view comes from clicking anywhere other than the name (which links to DataWeave Editor) on that row of the table.

The Round-trip template type has two associated actions: one for sending a command to TDP, and one for retrieving data later. To be useful, the DataWeave transformations need to know the expected format of the data within Signals Notebook. So it is useful to assign these actions to specific admin-defined table templates that are compatible with the DataWeave.

External actions are customizable through Signals Notebook System Configuration. From the configuration page, click External Actions. The sidebar on the left will have an option to create a new external action, which will lead to something like the screenshot below:

Reviewing the fields in this form:

• Name: This is what will be visible to end users when they want to initiate the external action.
• Description: This is visible in the external actions configuration window.
• URL: Signals Notebook implements external actions as HTTP requests to some address. The URL and search params here correspond to starting the intended external action in the connector.
  • Generating URL string: In the DataWeave Explorer, there is a sharing icon next to each template. Clicking this icon will bring up a window explaining the intended use of that type of DataWeave template, and URLs corresponding to the necessary external actions. Copy and paste one of these into the URL field of the External Action configuration form.
• Submit method: The HTTP method used in the request to the URL. For the connector, this should be left as HTTP GET.
• Parameter name: Signals Notebook will append the entity ID of the object that initiates the external action as a search param to the URL. The parameter name controls what that is called. For the connector, this should be left as the default value: __eid.
• Apply to: This sets what type of Signals Notebook entity the external action can be initiated from. For the Round-trip template type, this should be Table. When Table is chosen, a checkbox appears to the right of this field to allow all tables to use this action. We recommend unchecking this and instead choosing specific templates in the next field.
• Apply to templates: This field becomes visible when the “Apply to all templates” checkbox is unchecked. Multiple table templates can be selected here, and the external action can be executed from all selected.
• Open in a dialog: When unchecked, the external action will open in a new tab. When checked, the action instead opens in a window within the Signals Notebook page as a modal. The connector can work with both configurations.

🚧

Signals Notebook Dialog Modal Requires HTTPS

For the connector to work properly within a Signals Notebook modal, you must have the connector configured to use HTTPS.

• Require write access: This will restrict access to the given external action to people who have write access to the requesting entity.

When finished, click the Create External Action button in the bottom right.