Contentful

BotDojo can index published entries from a Contentful space with the read-only Content Delivery API.

Requirements

• Your Contentful Space ID
• The Environment ID to sync, such as master
• A Content Delivery API access token that can access that environment
• The space's data residency: US or EU

To create a token, open the space in Contentful, go to Settings → API keys, create an API key, and make sure it can access the environment you intend to sync. See Contentful's authentication guide for details.

Connect Contentful

1. In BotDojo, go to Integrations → Data.
2. Select Contentful.
3. Enter the Space ID, Environment ID, Content Delivery API access token, and data residency.
4. Select Test Connection, then Connect after the test succeeds.

Create a Data Loader

1. Go to Data and select Import Data.
2. Choose or create the destination folder, then select Contentful as the source.
3. Choose the connected Contentful integration.
4. Optionally select one or more content types. Leave the selection empty to sync all content types.
5. Optionally set the Locale of the indexed text, such as de-DE. Leave it empty to use the space's default locale.
6. Optionally add Platform URL Rules so citations link to the page where people read each entry (see below).
7. Configure the update schedule and save the loader.

Each published entry is indexed as readable text: its display field as the title, then its text, number, and rich text fields, with HTML converted to Markdown. A field that links to other entries shows their display names, and the names are also stored by field under contentful.linkedTitles in the document metadata, so you can filter on them, for example {"contentful.linkedTitles.jurisdiction": ["Georgia"]}. Use the dotted path: a nested object matches only when the whole object is equal. Linked entries are resolved from the same space even when their content type is not selected. A linked entry's new name reaches the index when an entry that links to it changes. Assets are not included in the text. The text uses the loader's locale, or the space's default locale when none is set; a field with no value in that locale uses its only value, or the space's default locale when it has several, and is left out when neither exists. The locale is recorded under contentful.locale, and changing it re-indexes every entry on the next run. The complete entry, with every localized field value and its Contentful metadata, is kept in the document metadata under source_meta, so you can filter and query on any field. Document metadata is copied to every chunk, so filters and results carry the names and the entry for any part of a long entry. Later successful runs reconcile the destination with Contentful, so entries that are unpublished or deleted are removed when previous records are not retained.

Platform URL rules

By default, the reference_url of each entry points at the Contentful editor, and citations link there. If your content is published on a site or portal, add Platform URL Rules to the loader. When a rule matches an entry, its reference_url becomes the address where people read the entry, so citations from the Search Index tool and the Index MCP link to that page. The Contentful editor link stays available on every entry under contentful.editorUrl.

The setting is a JSON object with an optional baseUrl and a list of rules. The URLs become citation links, so baseUrl must be an http or https URL, and each rule's url must start with {baseUrl}, http://, or https://. Invalid rules stop the sync before it starts. The first rule that matches an entry wins. A rule matches when its contentType is the entry's content type ID (omit it to match every content type) and, when field is set, the field's value equals equals or contains contains, ignoring case. Templates use {baseUrl}, {sys.<path>}, and {fields.<path>} placeholders; a step into an array without an index takes the first item. A rule whose placeholders are missing on an entry is skipped, so you can add a fallback rule after it. An entry that matches no rule keeps the Contentful editor link as its reference_url.

{
  "baseUrl": "https://portal.example.com",
  "rules": [
    { "contentType": "law", "url": "{baseUrl}/laws/{sys.id}/details" },
    { "contentType": "document", "field": "documentType", "equals": "Policy", "url": "{baseUrl}/policies/{sys.id}/details" },
    { "contentType": "document", "field": "documentType", "contains": "safety", "url": "{baseUrl}/safety/{fields.categories.0.sys.id}/{fields.topic.sys.id}/{sys.id}/details" },
    { "contentType": "document", "url": "{baseUrl}/documents/{sys.id}/details" }
  ]
}

Changing the rules reprocesses every entry on the next sync. The text does not change, so the index refreshes the metadata without embedding again, and every chunk picks up the new reference_url.

:::note The loader uses the Content Delivery API. It does not index drafts, binary asset files, or content from linked spaces. :::