Skip to main content

Notion

Notion is a collaboration and productivity platform that allows users to create, manage, and share a wide range of content and information. Turbine streaming apps can pull all pages and databases shared to an integration within an authorized Notion workspace via the records function.

The Notion Resource is currently in developer preview. To gain access, you will need to opt-in to the Notion Resource Developer Preview and a member of our team will reach out to get you acquainted with the current capabilities of the Notion Resource.

Setup

Resource Configuration

Use the meroxa resource create command to configure your Notion resource. You will need a Notion integration token in order to proceed.

The following example depicts how this command is used to create a Notion resource named my-notion with the minimum configuration required.

$ meroxa resource create my-notion \
--type notion \
--token $NOTION_INTEGRATION_TOKEN

In the example above, the $NOTION_INTEGRATION_TOKEN is all that is required to authorize access to a chosen Notion Workspace.

Notion Integration Creation

To get the $NOTION_INTEGRATION_TOKEN you will need to create a Notion integration by visiting https://www.notion.so/my-integrations in your browser.

Depending on your use case you can choose to create an internal integration or public integration in Notion. By default, internal integration is used.

Follow these steps to create a Notion integration token required to configure your Notion Resource on the Meroxa Platform.

  1. Make sure you are authenticated with a user account that has Admin level access to the Notion workspace you wish to connect to.
  2. Visit https://www.notion.com/my-integrations in your preferred web browser.
  3. Click the + New integration button.
  4. Name the integration something obvious (e.g., Meroxa Connection).
  5. Under Content Capabilities, you will need to enable Read content. This allows the Notion Connector to request content from your Notion workspace.
  6. Click the Submit button to create the integration.
  7. You’ll find your Notion integration token, also called an API key. This can be used to configure your Notion Resource.
  8. Share the newly created Notion integration with the appropriate Notion pages. Any member with access to the Notion workspace will be able to share pages and databases they have access to with the Notion integration. How to Share Notion Pages With Integration
  9. In the event you need to find your Notion integration token after leaving the page, you can return to https://www.notion.com/my-integrations and click View integration.

Notion Internal Integration

The internal integration allows users with access to the Notion workspace to manually share pages and databases with the Notion integration, in order to make content available through the integration.

This means that if you do not share a page or database with the integration, your Meroxa Resource will not be able to access that information. This policy is best if you want to have tight control over what gets shared with the integration.

Notion Public Integration

The public integration allows users with Admin level access to a selected Notion workspace to share all pages and databases with the integration. This means you will not have to manually share pages or databases to give the integration access.

This is the best option in the event you want to share everything in the Notion workspace with the integration.

You will need to take the following additional steps to set up a Notion Public Integration.

  1. Make sure you're on the details page for your integration in Notion. See step 9 under Notion Integration Creation.
  2. Under Basic Information > Integration Type select Public integration.
  3. Fill out each field in the OAuth Domain and URIs section according to Notion's instructions. These must be valid or you will run into errors.
  4. Click the Submit button to create the public integration.

Now that your Notion public integration is created, you will need to set up the authorization flow, in order to extract the access token from Notion.

  1. Follow the instructions documented by Notion in setting up your public integration for authorization.
  2. The access_token at the end of Notion's instructions is what you will use in the token field to create your Notion Resource in Meroxa.

Advanced Configuration

pollInterval

By default Notion used as a Source in Turbine streaming apps will poll events every 1 minute. This interval can be adjusted, but cannot be lower than 1 minute. Time is incremented and defined like so: 1m, 2m, 1h, 24h, etc.

In the following example, we show you how to set pollInterval to 5 minutes with TurbinePy:

source = await turbine.resources("my-notion")
# ...
records = await source.records("*",{"pollInterval": "5m"})

Note: As Notion does not have collections, you can simply use an empty string instead. This is required by the records function.

Data Record Format

Data records from Notion using Notion API events will take on the following format:

{
  "plaintext": "This is the page representing the Customer Success Meeting from last week!\n",
  "metadata": {
    "notion.createdTime": "2022-12-15T22:12:00Z",
    "notion.createdBy": "{\"object\":\"user\",\"id\":\"jn982h2-6db2-4805-87d0-3ca250h82h28\"}",
    "notion.title": "Customer Success Meeting",
    "notion.url": "https://www.notion.so/Customer-Success-Meeting-jn982h2-6db2-4805-87d0-3ca250h82h28",
    "notion.lastEditedBy": "{\"object\":\"user\",\"id\":\"91hjdc50-6db2-4805-87d0-3ca2501f7773\"}",
    "notion.lastEditedTime": "2022-12-15T22:20:00Z",
    "notion.parent": "{\"type\":\"page_id\",\"page_id\":\"r48u6870-7124-4028-ac58-3232405042405\"}",
    "notion.archived": "false"
  }
}