Integration

Seamlessly Integrate notebook into external services. (This feature is currently under private preview)

How to Set Up

Prepare integration

  • Prepare API Key and Secret

    • Open "Workspace settings" and click menu "API Keys".

    • Click the "New API Key" button and create new API Key.

    • Make a note of the API Key and API Secret (they will be used later for API calls).

  • Open the Notebook

    • Open the notebook you want to share.

    • Click the "Share" button in the header and select "Integration".

  • Select Pages

    • Choose the pages you want to publish.

  • Publish

    • Click the "Publish" button.

  • Configure integration settings.

    • Add API Key to use in "Permitted API Keys" section.

    • If you want to overwrite parameter values via the API, configure them in the Externalized Params section

Issue token from server

  • The following API is used to issue a token

    • The required arguments for calling the API can be found on the Integration settings page.

    • Perform the API call on the server side to prevent the API Secret from being exposed externally.

    • Issue a token for each user session, and do not reuse it (it expires after 1 hour).

Embed notebook

  • Create an iframe element and load Integration URL and pass token to authenticate.

  1. Create an iframe element with Integration URL as the src attribute

  2. Wait for a {type: "READY_FOR_TOKEN"} message from the iframe via postMessage

  3. Send {type: "SET_TOKEN", token: "{{ TOKEN_HERE }}"} message back to the iframe via postMessage

// Sample

const NOTEBOOK_ORIGIN = 'https://app.codatum.com';
const ingegrationUrl = 'https://app.codatum.com/protected/workspace/xxx/notebook/xxx';
const token = '{{ TOKEN_HERE }}';  // Issued token here

// Store iframe window reference
let notebookWindow: Window | null = null;

// Create and insert iframe
function createDashboard(containerId: string) {
  const container = document.getElementById(containerId);
  if (!container) return;

  const iframe = document.createElement('iframe');
  iframe.src = ingegrationUrl;
  iframe.allow = 'fullscreen;clipboard-write';
  // Set iframe style
  iframe.style.width = '100%';
  iframe.style.height = '100%';

  container.appendChild(iframe);
  notebookWindow = iframe.contentWindow;
}

// Handle messages from iframe
function handleMessage(event: MessageEvent<{type: 'READY_FOR_TOKEN'}>): void {
  // Verify origin and source
  if (event.origin !== NOTEBOOK_ORIGIN || event.source !== notebookWindow) {
    return;
  }

  // Send token when iframe is ready
  if (event.data.type === 'READY_FOR_TOKEN') {
    const message = {
      type: 'SET_TOKEN',
      token: token,
    };    
    notebookWindow?.postMessage(message, NOTEBOOK_ORIGIN);
  }
}

function cleanup() {
  window.removeEventListener('message', handleMessage);
  notebookWindow = null;
}

export function createEmbeddedNotebook(containerId: string) {
  window.addEventListener('message', handleMessage);
  createDashboard(containerId);
  return cleanup;
}

Pattern2. Passing token via URL parameter

  1. Append token as a query parameter to the Integration URL (?token=xxx)

  2. Create an iframe element with the modified URL as the src attribute

// Sample

const ingegrationUrl = 'https://app.codatum.com/protected/workspace/xxx/notebook/xxx';
const token = '{{ TOKEN_HERE }}';  // Issued token here

// Create URL with token
function createUrlWithToken(baseUrl: string, token: string): string {
  const url = new URL(baseUrl);
  url.searchParams.set('token', token);
  return url.toString();
}

// Create and insert iframe
function createNotebook(containerId: string) {
  const container = document.getElementById(containerId);
  if (!container) return;

  const iframe = document.createElement('iframe');
  iframe.src = createUrlWithToken(ingegrationUrl, token);
  iframe.allow = 'fullscreen;clipboard-write';
  // Set iframe style
  iframe.style.width = '100%';
  iframe.style.height = '100%';

  container.appendChild(iframe);
}

export function createEmbeddedNotebook(containerId: string) {
  createNotebook(containerId);
}

Appendix: Message list

Messages can be exchanged using the iframe's postMessage function.

  • The messages are also output to console.debug(), so you can check the actual message content there.

  • For example, this functionality can be used to:

    • Persist parameter information modified by users.

    • Share parameters across different integrations or pages.

Below is a list of messages that can be sent and received.

Messages to the iframe

typedescription

SET_TOKEN

Set the authentication token and start rendering notebook. This message must be sent after receiving the READY_FOR_TOKEN message.

Messages from the iframe

typedescription

READY_FOR_TOKEN

Notification that the notebook is ready to receive the token.

PARAM_CHANGED

Sent each time the user modifies a parameter within the notebook.

EXECUTE_SQLS_TRIGGERED

Sent when 'Run all' is executed within the notebook.

Last updated