The Notion connector is built with the Elastic connectors Python framework and is available as a self-managed connector client. View the source code for this connector (branch main, compatible with Elastic 8.15).

Availability and prerequisitesedit

This connector was introduced in Elastic 8.13.0, available as a self-managed connector client.

To use this connector, satisfy all connector client prerequisites. Importantly, you must deploy the connectors service on your own infrastructure. You have two deployment options:

Usageedit

To use this connector in the UI, select the Notion tile when creating a new connector under Search → Connectors.

For additional operations, see Using connectors.

Connecting to Notionedit

To connect to Notion, the user needs to create an internal integration for their Notion workspace, which can access resources using the Internal Integration Secret Token. Configure the Integration with following settings:

Deploy with Dockeredit

You can deploy the Notion connector as a self-managed connector client using Docker. Follow these instructions.

curl https://raw.githubusercontent.com/elastic/connectors/main/config.yml.example --output ~/connectors-config/config.yml

# When connecting to your cloud deployment you should edit the host value
elasticsearch.host: http://host.docker.internal:9200
elasticsearch.api_key: <ELASTICSEARCH_API_KEY>

connectors:
  -
    connector_id: <CONNECTOR_ID_FROM_KIBANA>
    service_type: notion
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA> # Optional. If not provided, the connector will use the elasticsearch.api_key instead

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/enterprise-search/elastic-connectors:8.15.0.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

Refer to DOCKER.md in the elastic/connectors repo for more details.

Find all available Docker images in the official registry.

Configurationedit

Note the following configuration fields:

Content Extractionedit

Refer to content extraction.

Documents and syncsedit

The connector syncs the following objects and entities:

Sync rulesedit

Basic sync rules are identical for all connectors and are available by default.

Advanced sync rulesedit

The following section describes advanced sync rules for this connector, to filter data in Notion before indexing into Elasticsearch. Advanced sync rules are defined through a source-specific DSL JSON snippet.

Advanced sync rules for Notion take the following parameters:

Examplesedit

Example 1edit

Indexing every page where the title contains Demo Page:

  {
    "searches": [
      {
        "filter": {
          "value": "page"
        },
        "query": "Demo Page"
      }
    ]
  }

Example 2edit

Indexing every database where the title contains Demo Database:

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    }
  ]
}

Example 3edit

Indexing every database where the title contains Demo Database and every page where the title contains Demo Page:

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    },
    {
      "filter": {
        "value": "page"
      },
      "query": "Demo Page"
    }
  ]
}

Example 4edit

Indexing all pages in the workspace:

{
  "searches": [
    {
      "filter": {
        "value": "page"
      },
      "query": ""
    }
  ]
}

Example 5edit

Indexing all the pages and databases connected to the workspace:

{
  "searches":[
    {
      "query":""
    }
  ]
}

Example 6edit

Indexing all the rows of a database where the record is true for the column Task completed and its property(datatype) is a checkbox:

{
  "database_query_filters": [
    {
      "filter": {
          "property": "Task completed",
          "checkbox": {
            "equals": true
          }
      },
      "database_id": "database_id"
    }
  ]
}

Example 7edit

Indexing all rows of a specific database:

{
  "database_query_filters": [
    {
      "database_id": "database_id"
    }
  ]
}

Example 8edit

Indexing all blocks defined in searches and database_query_filters:

{
  "searches":[
    {
      "query":"External tasks",
      "filter":{
        "value":"database"
      }
    },
    {
      "query":"External tasks",
      "filter":{
        "value":"page"
      }
    }
  ],
  "database_query_filters":[
    {
      "database_id":"notion_database_id1",
      "filter":{
        "property":"Task completed",
        "checkbox":{
          "equals":true
        }
      }
    }
  ]
}

Connector Client operationsedit

End-to-end Testingedit

The connector framework enables operators to run functional tests against a real data source, using Docker Compose. You don’t need a running Elasticsearch instance or Notion source to run this test.

Refer to Connector testing for more details.

To perform E2E testing for the Notion connector, run the following command:

$ make ftest NAME=notion

For faster tests, add the DATA_SIZE=small flag:

make ftest NAME=notion DATA_SIZE=small

By default, DATA_SIZE=MEDIUM.

Known issuesedit

Refer to Known issues for a list of known issues for all connectors.

Troubleshootingedit

See Troubleshooting.

Securityedit

See Security.