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

Externalized parameter values. Can be configured in the notebook integration settings

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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\""}]}'

200

400

401

200

{
  "token": "(Generated-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.

[Recommended] Pattern1. Passing token via postMessage

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" } ] }