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 "Setup guide" tab.

    • 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).

post

/api/notebook/issueToken

Body
api_keystring · min: 24 · max: 24required

API Key. Can be issued from 'Workspace settings > API Keys'

Example: 6729a28bc7100424ad4e2e5d
api_secretstring · min: 32 · max: 32required

API Secret. Generated when issuing 'API Key'

Example: c711defdff5f4e3e8e53d4f408579b9a
integration_idstring · min: 24 · max: 24required

Integration ID. Can be obtained from the notebook integration settings

Example: 671ef14b0d08cf6c657df7da
page_idstring · min: 24 · max: 24required

Page ID to be displayed in the notebook. Can be obtained from the notebook integration settings

Example: 671ecbbf2990c63fea3b3a26
token_user_idstring · min: 1required

Specify the user ID within the application where the notebook is embedded. Ensure that the token can uniquely identify the token user for security reason.

expires_ininteger · min: 1 · max: 86400

Token expiration time in seconds. Default is 3600 seconds (1 hour)

Example: 3600
cache_max_ageinteger · max: 86400

Cache max age in seconds. Default is 86400 (24 hours)

Example: 86400
paramsobject[]required
Responses
curl -L \
  --request POST \
  --url 'https://api.codatum.com/api/notebook/issueToken' \
  --header 'Content-Type: application/json' \
  --data '{
    "api_key": "6729a28bc7100424ad4e2e5d",
    "api_secret": "c711defdff5f4e3e8e53d4f408579b9a",
    "integration_id": "671ef14b0d08cf6c657df7da",
    "page_id": "671ecbbf2990c63fea3b3a26",
    "token_user_id": "text",
    "expires_in": 3600,
    "cache_max_age": 86400,
    "params": [
      {
        "param_id": "6722c7061b02448a4056d84d",
        "param_value": "\"Hello world\""
      }
    ]
  }'
{
  "token": "(Generated-token)"
}

Embed iframe

Embed HTML into your service using the Integration URL.

You can set display options along with the token. Please check the "Setup guide" in for details.

  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 (Optionally, you can also send displayOptions)

// 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
const displayOptions = {
  "theme": "LIGHT",
  "sqlDisplay": "SHOW",
  "expandParamsFormByDefault": false
};

// 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';
  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,
      displayOptions: displayOptions
    };    
    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. Optionally, append displayOptions as a query parameter (The value should be encodeURIComponent(JSON.stringify(displayOptions)))

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

// Sample

<iframe
  src="https://app.codatum.com/protected/workspace/xxx/notebook/xxx?token={{ TOKEN_HERE }}&displayOptions={{ ENCODED_DISPLAY_OPTIONS_HERE }}"
  allow="fullscreen; clipboard-write" 
/>

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

type
description

SET_TOKEN

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

{type: "SET_TOKEN", token: "..."}

Messages from the iframe

type
description

READY_FOR_TOKEN

Notification that the notebook is ready to receive the token.

{type: "READY_FOR_TOKEN"}

PARAM_CHANGED

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

{
  type: "PARAM_CHANGED",
    params: [
        {
            param_id: "662a5e9fce6482ca0231f06f",
            param_value: "\"Hello codatum\""
        },
    ]
}

EXECUTE_SQLS_TRIGGERED

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

{
    type: "EXECUTE_SQLS_TRIGGERED",
    params: [
        {
            param_id: "662a5e9fce6482ca0231f0aa",
            param_value: "123"
        }
    ]
}

Last updated

Was this helpful?