Skip navigation

Skip to main content

On September 25th, 2024, we released v2 of the Apps SDK. To learn what’s new and how to upgrade, see Migration FAQ and Migration guide.
API reference
Intents: design
API reference

prepareDataConnector

API reference for the intents prepareDataConnector method.

Prepares a DataConnector Intent.

Usage

import { prepareDataConnector } from "@canva/intents/data";


prepareDataConnector({
 getDataTable: async (params) => {
   // Implement the logic to fetch the data table
 },
 renderSelectionUi: (params) => {
   // Implement the UI for the data table selection
 },
});
TSX

Parameters

implementationDataConnectorIntent
Required

Main interface for implementing the Data Connector intent.

Implementing the Data Connector intent enables apps to import external data into Canva. This allows users to select, preview, and refresh data from external sources.

getDataTablefunction
Required

Gets structured data from an external source.

This action is called in two scenarios:

  • During data selection to preview data before import (when RenderSelectionUiRequest.updateDataRef is called).
  • When refreshing previously imported data (when the user requests an update).

Example: Getting data from an external source

import type { GetDataTableRequest, GetDataTableResponse } from '@canva/intents/data';


async function getDataTable(request: GetDataTableRequest): Promise<GetDataTableResponse> {
  const { dataSourceRef, limit, signal } = request;


  // Check if the operation has been aborted.
  if (signal.aborted) {
    return { status: 'app_error', message: 'The data fetch operation was cancelled.' };
  }


  // ... data fetching logic using dataSourceRef, limit, and signal ...


  // Placeholder for a successful result.
  return {
    status: 'completed',
    dataTable: { rows: [{ cells: [{ type: 'string', value: 'Fetched data' }] }] }
  };
}
TS

Parameters

requestGetDataTableRequest
Required

Parameters for the data fetching operation.

dataSourceRefDataSourceRef
Required

Reference to the data source to fetch.

This contains the information needed to identify and retrieve the specific data that was previously selected by the user.

Use this to query your external data service.

sourcestring
Required

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestring
Optional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

limitDataTableLimit
Required

Maximum row and column limits for the imported data.

Your app must ensure the returned data does not exceed these limits.

If the requested data would exceed these limits, either:

  • Truncate the data to fit within limits, or
  • Return a 'data_table_limit_exceeded' error
rownumber
Required

The maximum number of rows allowed.

Your app should ensure data does not exceed this limit.

columnnumber
Required

The maximum number of columns allowed.

Your app should ensure data does not exceed this limit.

signalAbortSignal
Required

Standard DOM AbortSignal for cancellation support.

Your app should monitor this signal and abort any ongoing operations if it becomes aborted.

Returns

A promise resolving to either a successful result with data or an error. This is a Promise that resolves with the following object:

Successful result from getDataTable action.

statusstring

Indicates the operation completed successfully

This must be "completed".

dataTableDataTable

The fetched data formatted as a data table.

rowsDataTableRow[]

The data rows containing the actual values.

Each row contains an array of cells with typed data values.

cellsDataTableCell<DataType>[]

Array of cells containing the data values.

Each cell must have a type that matches the corresponding column definition (if provided).

columnConfigsColumnConfig[]
Optional

Column definitions with names and data types.

These help Canva interpret and display your data correctly.

namestring | undefined

Name for the column, displayed as header text.

If undefined, the column will have no header text.

typeobject

Expected data type for cells in this column.

Use a specific DataType for columns with consistent types, or 'variant' for columns that may contain mixed types.

Data types supported for table cells.

Available values:

  • "string"
  • "number"
  • "date"
  • "boolean"
  • "media"

This must be "variant".

metadataDataTableMetadata
Optional

Optional metadata providing additional context about the data.

descriptionstring
Optional

A human-readable description of the dataset.

This description helps users understand what data they are importing.

providerInfoobject
Optional

Information about the data provider or source.

namestring

Name of the data provider.

urlstring
Optional

URL to the provider's website or related resource.

Error results that can be returned from getDataTable method.

GetDataTableError indicating the data source reference is no longer valid. This will trigger a re-selection flow for the user.

statusstring

The data source reference is no longer valid.

Return this error when the DataSourceRef cannot be used to retrieve data, for example:

  • The referenced dataset has been deleted
  • Access permissions have changed
  • The structure of the data has fundamentally changed

This will trigger a re-selection flow, allowing the user to choose a new data source.

This must be "outdated_source_ref".

GetDataTableError indicating failure to fetch data from the external source. Typically due to network issues or API failures.

statusstring

Failed to fetch data from the external source.

Return this error for network issues, API failures, or other connectivity problems that prevent data retrieval.

This must be "remote_request_failed".

GetDataTableError indicating custom error occurred in the app's implementation. This can be used to indicate specific issues that are not covered by other error types.

statusstring

A custom error occurred in your app.

Return this for application-specific errors that don't fit the other categories. Include a descriptive message explaining the error to the user.

This must be "app_error".

messagestring
Optional

Optional message explaining the error.

renderSelectionUifunction
Required

Renders a user interface for selecting and configuring data from your external sources.

Example: Rendering a data selection UI

import type { RenderSelectionUiRequest } from '@canva/intents/data';


async function renderSelectionUi(request: RenderSelectionUiRequest): Promise<void> {
  // UI rendering logic.
  // Example: if user selects data 'ref123'.
  const selectedRef = { source: 'ref123', title: 'My Selected Table' };
  try {
    const result = await request.updateDataRef(selectedRef);
    if (result.status === 'completed') {
      console.log('Selection valid and preview updated.');
    } else {
      console.error('Selection error:', result.status);
    }
  } catch (error) {
     console.error('An unexpected error occurred during data ref update:', error);
  }
}
TS

Parameters

requestRenderSelectionUiRequest
Required

Configuration and callbacks for the data selection UI.

invocationContextInvocationContext
Required

Context information about why the data selection UI is being launched.

Use this to adapt your UI for different scenarios:

  • 'data_selection': Initial data selection or editing existing data
  • 'outdated_source_ref': Previous reference is no longer valid, guide user to reselect
  • 'app_error': Custom error occurred, show error message and recovery options

When dataSourceRef is provided, pre-populate your UI with this selection.

InvocationContext indicating initial data selection flow or edit of existing data.

reasonstring
Required

Initial data selection or editing existing data.

This is the standard flow when:

  • A user is selecting data for the first time
  • A user is editing a previous selection

If dataSourceRef is provided, this indicates an edit flow, and you should pre-populate your UI with this selection.

This must be "data_selection".

dataSourceRefDataSourceRef
Optional

If dataSourceRef is provided, this is an edit of existing data flow and UI should be pre-populated.

sourcestring
Required

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestring
Optional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

InvocationContext indicating an error occurred because the previously selected data source reference is no longer valid. Triggered when getDataTable returned 'outdated_source_ref' during data refresh. UI should guide the user to reselect or reconfigure their data.

reasonstring
Required

Previously selected data source reference is no longer valid.

This occurs when getDataTable returned 'outdated_source_ref' during a refresh attempt. Your UI should guide the user to select a new data source or update their selection.

The outdated reference is provided to help you suggest an appropriate replacement.

This must be "outdated_source_ref".

dataSourceRefDataSourceRef
Optional

The outdated data source reference that caused the error during refresh.

sourcestring
Required

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestring
Optional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

InvocationContext indicating a custom error occurred during data refresh. Triggered when getDataTable returned 'app_error' status. UI should display the error message and help users recover.

reasonstring
Required

A custom error occurred during data refresh.

This occurs when getDataTable returned 'app_error' during a refresh attempt. Your UI should display the error message and help users recover from the specific issue.

This must be "app_error".

dataSourceRefDataSourceRef
Optional

The data source reference that caused the error during refresh.

sourcestring
Required

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestring
Optional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

messagestring
Optional

The error message to display to the user.

limitDataTableLimit
Required

Maximum allowed rows and columns for the imported data.

Your UI should inform users of these constraints and prevent or warn about selections that would exceed them. This helps users understand why certain data sets might not be available for selection.

rownumber
Required

The maximum number of rows allowed.

Your app should ensure data does not exceed this limit.

columnnumber
Required

The maximum number of columns allowed.

Your app should ensure data does not exceed this limit.

updateDataReffunction
Required

Callback to preview selected data before finalizing import.

Call this function when the user selects data to:

  1. Show a preview of the selected data to the user
  2. Validate that the selection meets system requirements

Calling this function will trigger your getDataTable implementation. Wait for the promise to resolve to determine if the selection is valid.

Throws

Will throw CanvaError('bad_request') if

  1. DataSourceRef.source exceeds 5kb.
  2. DataSourceRef.title exceeds 255 characters.
  3. GetDataTableCompleted.dataTable exceeds DataTableLimit or contains invalid data.

Parameters

dataSourceRefDataSourceRef
Required

Reference object identifying the selected data

sourcestring
Required

Information needed to identify and retrieve data from your source.

This string should contain all the information your app needs to fetch the exact data selection later. Typically, this is a serialized object with query parameters, identifiers, or filters.

You are responsible for encoding and decoding this value appropriately.

Maximum size: 5KB

titlestring
Optional

A human-readable description of the data reference.

This title may be displayed to users in the Canva interface to help them identify the data source.

Maximum length: 255 characters

Returns

Promise resolving to success or an error result. This is a Promise that resolves with the following object:

Successful result from the RenderSelectionUiRequest.updateDataRef callback.

statusstring

The data selection was successful and can be previewed.

This must be "completed".

Error results that can be returned from getDataTable method.

GetDataTableError indicating the data source reference is no longer valid. This will trigger a re-selection flow for the user.

statusstring

The data source reference is no longer valid.

Return this error when the DataSourceRef cannot be used to retrieve data, for example:

  • The referenced dataset has been deleted
  • Access permissions have changed
  • The structure of the data has fundamentally changed

This will trigger a re-selection flow, allowing the user to choose a new data source.

This must be "outdated_source_ref".

GetDataTableError indicating failure to fetch data from the external source. Typically due to network issues or API failures.

statusstring

Failed to fetch data from the external source.

Return this error for network issues, API failures, or other connectivity problems that prevent data retrieval.

This must be "remote_request_failed".

GetDataTableError indicating custom error occurred in the app's implementation. This can be used to indicate specific issues that are not covered by other error types.

statusstring

A custom error occurred in your app.

Return this for application-specific errors that don't fit the other categories. Include a descriptive message explaining the error to the user.

This must be "app_error".

messagestring
Optional

Optional message explaining the error.

Returns

void

Returns

void