Configure the Drupal Connector

Use this guide after reviewing Ingesting Data with a CMS DXP Connector. It covers the Drupal-specific installation, indexing, SearchStax settings, and verification steps.

Configure the Drupal Connector

Follow these steps to connect Drupal to your SearchStax Site Search App and send published content to your index.

Prerequisites

In addition to the prerequisites listed above, you’ll need:

• The ability to install modules via Composer or your standard deployment process.
• The API endpoints and tokens for environment-specific Search Apps that you’ll target, if your site has multiple environments (e.g., staging and production)

Note: If you’re an Acquia Cloud customer migrating from Acquia Search or another Solr service, follow the migration guide from Acquia to move the existing server, index, and views to Site Search. The migration submodule is supported only on Drupal 8+.

1. Install and Enable Required Modules

1. Install Search API, Search API Solr, and SearchStax modules.
2. Enable the modules in Extend.

Composer is recommended for installation. Use your standard process for enabling modules in your environment.

2. Create the Search API Server

1. Go to Configuration > Search and metadata > Search API.
2. Select Add server.
3. Enter a name and make sure Backend is set to Solr.

4. Configure the server:

   • Solr connector: SearchStax Cloud with Token Auth
   • Endpoint: Your app’s Update endpoint (from Site Search App Settings All APIs Search & Indexing)
   • Read & write token: Your app’s Read & write token (same location as above)

   Click Save.
   
   

   Note: If you use Drupal or host your site through Acquia, use a separate SearchStax App for each environment. When multiple Drupal environments share the same App, tasks in any connected environment can delete or replace data in that App. For help investigating missing data, see Troubleshoot Missing Drupal App Data.

5. Confirm success messages after save:
   • Server Connection: “The server could be reached.”
   • Core Connection: "The Solr core could be accessed," with a latency value.
     
     

3. Create the Index and Choose Fields

1. From Search API, select Add index.
2. Name the index, set Data sources to Content. Under Server, select the server you just created. Choose Save and add fields.
3. Select fields to index. Recommended starting set:
   • rendered_item
   • langcode
   • status
   • uid (author)
   • content
   • body
   • title
   • published date
4. Only fulltext fields are searchable. Ensure the fields you want to search are marked as fulltext where applicable.
5. In the Processors tab, check HTML filter, then Save.
6. Index content:
   • Cron will index automatically, or
   • Open the index, then click Index now for immediate results.

Tip: Index the fields you intend to show in results. At minimum, index title, body/description, URL/path, published date, and content type. Exact field names vary by schema and language. You can still map later, but unmapped fields won’t populate the prebuilt results card in SearchStax.

4. Configure the SearchStax Module

Note: Analytics is optional. If your app has no Analytics tab, skip the analytics fields.

1. Go to Administration > Configuration > Search and metadata > SearchStax settings.
2. Configure as needed:
   • Analytics Credentials: If your SearchStax plan includes Analytics, enter the Analytics URL and Global analytics key for your Site Search app. In SearchStax, go to App Settings > All APIs > Analytics to find these values. If you use the Drupal Key module, select the key that contains your SearchStax Analytics credentials. Otherwise, select Do not use Key module and enter the credentials directly.
   • (Optional, requires Search API Autocomplete) Auto-suggest core: Go to Configuration > Search and metadata > Search API > Servers and edit the server that uses the SearchStax Cloud with Token Auth connector. In the Auto-suggest core field, enter or select the core name from App Settings Search & Indexing, then click Save. If you use the Drupal Key module, this field may be a Key selector.
   • Re-route searches via Site Search configurations: Check this setting if you want Drupal searches to use the Site Search search handler and you want Site Search configurations to control supported search behavior. When you check this setting, additional feature settings appear below it. Fulltext keys, filters, and paging parameters are always passed to SearchStax and aren’t affected by this setting.
   • If you checked Re-route searches via Site Search configurations, choose which Drupal settings Site Search should control:
     • Check Parse mode and searched fields to let Site Search control query parsing and searched fields.
     • Check Highlighting settings to use Site Search highlighting instead of Drupal highlighting.
     • Check Spellcheck settings to use Site Search spellcheck instead of Drupal spellcheck.
3. Click Save configuration.

Note: Leave Re-route searches via Site Search configurations unchecked if you want Drupal Search API, Drupal Views, or custom Drupal search logic to keep controlling query parsing, searched fields, highlighting, or spellcheck behavior. See When to Ignore Drupal Settings for SearchStax Site Search for more information.

Advanced Settings

Optional analytics and protection settings are available on the Advanced Settings tab. Use this tab to exclude Drupal roles from search behavior tracking, configure EU Cookie Compliance, or turn on Flood Protection. After you change these settings, click Save configuration.

Additional Considerations

• Tracking search results: Site Search tracks results automatically for searches known to the Drupal Search API module. If you use a custom search implementation and tracking doesn’t appear in Site Search Analytics, you may need to expose that search through a Drupal Search API Display plugin. See Drupal Module Functionality for more information.
• Click tracking verification: Works out of the box for Views and Search API Pages. Verify by running a search, clicking a result, and checking the Network tab for /api/v2/track/?data=… containing "event":"_searchclick". For other setups, use the _searchstax_add_tracking() helper. See Drupal Module Functionality for more information.
• Auto-suggest: Requires Search API Autocomplete. On the relevant Search API server configuration (SearchStax Cloud with Token Auth), set Auto-suggest core to the Solr suggest core from your Auto-Suggest endpoint (final path segment before /emsuggest), then click Save.
• Custom search UI option: Planning a custom search UI in Drupal? Use a Search UI Kit (React, Vue, or Angular) and follow the build and packaging guidance for fixed filenames and a single target DOM element. See Building Drupal Pages with Search UI Kit for more information.
• Edge cases: If you use custom entities, add fields to the Solr schema and then reload the schema in Site Search so they’re returned. For faceting, either use Site Search facets with fields indexed as strings, or use the Drupal Facet component for the UI while filters still apply on the Site Search side. See Drupal FAQ for more information.
• Manual migration: Expect search downtime during reindex. Synonyms and stopwords aren’t migrated. Language variations aren’t auto-created; configure them manually. Then move each index to the new server and reindex. See Migrate Drupal Manually for more information.
• Hit highlighting: If you route searches through Site Search, highlighting is generated by Site Search. If you keep Drupal-side highlighting, mark fields as fulltext and include the HTML filter. See Drupal Hit-Highlighting for more information.

Map Drupal Fields to Site Search

Map your Drupal fields so search results render correctly. In Site Search, go to Basic configurations > Results fields and assign Drupal fields to positions like Title, Description, etc.

If fields don’t display as expected or you need help interpreting Drupal field machine names, see Understanding Drupal field names in SearchStax for more information.

What's next?

After you verify the Drupal index, preview your search in SearchStax.