Elastic Notion Connector reference

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 8.13, compatible with Elastic 8.13).

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:

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.

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:

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.13.4.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.

Note the following configuration fields:

Refer to content extraction

The connector syncs the following objects and entities:

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

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:

Indexing every page where the title contains Demo Page:

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

Indexing every database where the title contains Demo Database:

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

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

Indexing all pages in the workspace:

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

Indexing all the pages and databases connected to the workspace:

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

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

Indexing all rows of a specific database:

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

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

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.

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

See Troubleshooting.

See Security.