Ingesting Data with a CMS/DXP Connector

Drupal Connector Setup

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 host your site through Acquia, choose the Search App for the same environment as your Drupal site. Don’t point multiple environments at a single App.

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.

Sitecore Connector Setup

Use the Sitecore module to send published Sitecore content to your SearchStax Site Search app and stand up a functional search page fast. This guide walks you through installing the module, connecting it to your app, indexing content, and creating a basic search page.

Prerequisites

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

• Sitecore 9.1–10.4 with admin access.
• Permission to install packages and run Control Panel tasks.
• A SearchStax Site Search app with Auto‑suggest enabled.
• One Sitecore index per Site Search app (a single Sitecore server can have multiple indexes).

Tip: You can index multiple content roots. List each root path when you configure the index.

Upgrading? If you're moving from Sitecore module 2.0.0, follow the official upgrade guide. In short: back up SearchStax.Connector.Provider.config, remove the old App_Config/Modules/SearchStax files, install 3.0.x with Overwrite selected, reapply any custom config, recreate and rebuild indexes, then republish. See Upgrade to Module 3.0.X for more information.

Using Docker/containers? If your Sitecore runs in containers, use the Docker-specific guide to layer the SearchStax module images in your cm/cd Dockerfiles, set the SEARCHSTAX_* env vars, update docker-compose.override.yml, and disable the default health check for local dev. See Sitecore Module with Docker for more information.

Multiple publishing targets? For staging vs. production or other targets, create a separate Site Search app and index core for each target and repeat the module setup per app. See Multiple Publishing Targets for more information.

1. Download the Correct Module Package

1. Identify your Sitecore version.
2. Download the Sitecore Module package for your version from the Sitecore module page. For a complete list of Sitecore versions and links to corresponding packages, see Sitecore Module 3.0.2.
3. If you use SXA, also download the SXA Module.

2. Install the Module in Sitecore

1. In Sitecore, open Desktop > Development Tools > Installation Wizard.
2. Upload the module package you downloaded.
3. Select Install and wait for completion.
4. When prompted, continue to configuration.

3. Open the Module Configuration

1. From the Launchpad, select SearchStax Site Search > SearchStax Studio Configuration.
2. Next, enter your SearchStax username and password and select Load accounts (1).
3. Choose the Site Search account (2) and then the Search app (3).
4. Select Create an index (4).

4. Set Index Properties

If your app doesn’t use Basic authentication:

1. On Index properties, set one or more Root item(s) to crawl. By default the module indexes under /sitecore/content/home/.
2. Click Save, then confirm to apply configuration files.

If your app uses Basic authentication:

1. Set Root item(s) as above.
2. Enter Read Only Solr Password and Admin Solr Password. These are your Read & Write and Read-Only tokens in SearchStax under Site Search App Settings All APIs Search & Indexing.
3. (Optional) Enable Reset index when rebuilding to clear the index before a rebuild. This causes empty results during the rebuild.
4. Click Save, then confirm.

Why this step matters: Sitecore uses the configured root paths to scope indexing. Adding multiple roots lets you include additional sites or sections.

Indexing multiple sites? See Multi-Site Search for more information.

Need to configure multiple root items in config? See Multi-Root Crawling for more information.

5. Populate the Solr Managed Schema, Then Rebuild

1. In Sitecore, go to Control Panel Indexing Populate Solr Managed Schema.
2. Select the new SearchStax index and choose Populate. Wait for success.
3. Go to Control Panel Indexing > Indexing Manager.
4. Select the same index and choose Rebuild.

6. Reload the App Schema in Site Search, Then Rebuild Again

Reloading the schema in Site Search aligns the app’s Solr collection with the Sitecore‑generated schema so queries and highlights work correctly.

1. In Site Search, open your Search App.
2. Go to App Settings All APIs and select Reload schema at the bottom of the page.
3. Back in Sitecore, open Indexing Manager and Rebuild the index again.

7. Configure Fields for Your Search Experience

In SearchStax, map Sitecore fields to your Result Card, then publish.

1. In Site Search, go to Configurations > Basic Configurations > Results Fields.
2. Add the default mapped fields and assign Sitecore fields:
   • Title: resulttitle_t, itemdisplayname_s, search_title_t, itemtitle_t, or title_s.
   • Ribbon: Sitenamelabel_s, asset_type_s, _templatename, or contenttype_sm.
   • Paths:Domainpageurl_t or _fullpath.
   • Date: Itemupdatedate_tdt, _updated, or date_tdt.
   • Description: Renderedcontent_t, metadescription_t_en, or search_description_t.
   • URL: Domainpageurl_t or resulturl_s.
3. Click Publish.
4. Open Configurations > Basic Configurations > Search Fields. Add the fields users should be able to query. Click Publish.

Personalizing search by audience or behavior? Start with the Sitecore personalization guide and Search Profiles (aka “Search Models” in Sitecore). See Sitecore Personalization for more information.

Adding facets and sorting? Configure Faceting and Sorting in Site Search. If facet values split or sorting is unavailable, use a non‑tokenized string/docValues field. See Field for Faceting/Sorting in Sitecore for more information.

8. Create a Search Page in Sitecore

1. In Sitecore Content Editor, create a page from /sitecore/templates/Feature/SearchStax/SearchPage/SearchStaxPage.
2. Set the SearchStax Index field to the index you created.
3. Publish the page to test your search.

Prefer a custom MVC search page? See How to Create a SearchStax Custom Search Page for more information.

Using Sitecore SXA? See Create an SXA Search Page for more information.

9. Computed Fields Included by the Module

The module ships with computed fields that improve relevance and default rendering. You can remove or replace them as your project matures.

• ResultTitle: Uses DisplayName, falling back to Name. Update /Views/SearchStaxPage/Index.cshtml if you change the title field.
• ResultURL: Resolves item URLs, including media via MediaManager.GetMediaUrl and content via LinkManager.GetItemUrl in the current site context. Update /Views/SearchStaxPage/Index.cshtml if you change the URL field.
• RenderedContent: Indexes text fields for the page and its rendering data sources, excluding IDs listed in <renderedContentFieldExcludedRenderings in App_Config/Modules/SearchStax/SearchStax.Cloud.config.

Note: Computed fields add CPU load. Minimize custom computed fields and add them carefully in App_Config/Modules/SearchStax/SearchStax.Connector.Provider.config.

Need to change module configs? See Modify Configs for more information.