Managing a single non-prod Sitecore Search Sandbox alongside two non-prod XM Cloud environments can be frustrating, especially when you need separate configurations for each environment. Ideally, each environment would have its own sandbox, but that’s not always the case. And creating separate widgets for each environment? That’s just not practical.

The challenge? It becomes difficult to test when your search result listings show data from both UAT and QA environments, making it hard to validate environment-specific configurations properly.

Luckily, there’s a solution—Site Context Variables. By leveraging these variables, you can dynamically adjust configurations based on the environment, streamlining the process without the headache of managing multiple widgets manually. Let’s dive into how Site Context Variables can make your setup more efficient and manageable.

The Challenge: News Listing in a Shared Sandbox

In Sitecore Search, when you want to display a listing component—such as a news listing that pulls all article detail pages—you typically need to create a widget in Sitecore Search. This widget is responsible for querying and displaying the relevant content on your site.

However, when working with a shared Sitecore Search sandbox across multiple non-prod environments (UAT and QA), things get tricky. Since both environments use the same search index, the listing component can retrieve mixed data from both environments. This makes it difficult to validate environment-specific configurations, as search results may include articles from both UAT and QA instead of just the intended environment.

A Smarter Approach: Using Site Context Variables

To solve this, we can leverage Site Context Variables in Sitecore Search. These allow us to dynamically adjust search queries based on the environment, ensuring that the news listing only displays data relevant to the current site environment.

Here’s how it works:

  1. Define a Site Context Variable that identifies the environment (e.g., uat or qa).
  2. Modify your search query to filter results based on this variable.
  3. Ensure each environment passes the correct context value, so UAT retrieves only UAT data, and QA retrieves only QA data.

By implementing this approach, you avoid data mixing between environments and maintain accurate, environment-specific search results, making testing and validation much smoother.

Defining the Site Context Variable

To ensure that your search results only display data from the correct environment, you need to define a Site Context Variable in Sitecore Search. Here’s how you can do it:

  1. Go to Administration in Sitecore Search.
  2. Navigate to Domain Settings > Attributes.
  3. Click Create a New Attribute and name it Environment.
  4. Scroll down to the Properties section.
  5. Ensure the checkbox for “Available for Site Context” is selected.

By doing this, you make the Environment attribute available as a Site Context Variable, allowing you to dynamically control search queries based on the active environment (UAT or QA).

Modifying Your Search Query to Use Site Context

Now that we’ve defined the Environment attribute as a Site Context Variable, we need to apply it to our search queries to ensure they only retrieve results from the correct environment.

Here’s how to do it:

  1. Open your widget in Sitecore Search.
  2. Navigate to the Rules section.
  3. Click Add Rule.
  4. In the left tabs, select Context.
  5. Under Context, choose Site Context and then click Add Context Rule.
  6. Select the Environment attribute.
  7. Choose the “is” condition.
  8. In the value field, enter the appropriate environment, e.g., UAT.
  9. Finally click on save

Filtering Out Unwanted Content with a Blacklist Rule

Now that we’ve added a Site Context Rule for the Environment, we need to ensure that only content belonging to the selected environment is displayed. To do this, we can apply a Blacklist Rule to exclude content from other environments.

Steps to Add a Blacklist Rule:

  1. In the same rule where Environment = “uat” is applied:
  2. Click the Strategy tab.
  3. Choose Blacklist Rules.
  4. Click on + Add Attribute.
  5. Select the content_source attribute (this must be previously populated in the corresponding source, meaning we may need a separate source for UAT content and another for QA content).
  6. Choose the “is not” condition.
  7. Enter uat as the value.
  8. Finally Publish your changes

You will see a summary like this:

Important Note: If you need to do same on all widgets you can move the rules to a Global Widget as Follows

Passing the Correct Context Variable in Your Next.js Application

To ensure that each environment correctly passes the Site Context Variable, we need to set up an environment variable in our Next.js application.

1. Define the Environment Variable

In your .env.local file, add:

NEXT_PUBLIC_SEARCH_ENVIRONMENT=uat


This variable will dynamically specify which environment the search requests should be associated with.

2. Set the Context in Your React Application

If you wrap your application in a React Context, such as a SearchProvider component, you need to ensure the correct environment is passed when instantiating the WidgetsProvider.

In the same component where WidgetsProvider is being called, add the following code:

const context = PageController.getContext();
context.setPage({
  ...context.getPage(),
  custom: {
    ...context.getPage()?.custom,
    environment: process.env.NEXT_PUBLIC_SEARCH_ENVIRONMENT,
  },
});

A Word on context.setPage()
Using context.setPage() to inject the environment variable was a bit tricky. The documentation doesn’t explicitly clarify how Site Context Variables are being mapped on the Sitecore Search side. This made it more difficult to understand how to pass context from the frontend to ensure the correct filtering based on the environment.
For reference, you can check the documentation here: Sitecore Search JS SDK for React Context.
How This Works
  • PageController.getContext() retrieves the current search context.
    • 


  • context.setPage() updates the context, injecting the environment value from the Next.js environment variable.
    • 


  • Now, whenever a search request is made, Sitecore Search will receive the correct environment variable (uat or qa), ensuring that only the relevant content is retrieved.
This ensures that UAT and QA environments remain separate, avoiding data mix-ups in search results.
Behind the scenes it pass the context variable under context params as follows:
Conclusion
Managing a shared Sitecore Search sandbox across multiple non-prod environments, like UAT and QA, can pose significant challenges—especially when you need to ensure that search results are environment-specific. However, with the right approach, you can streamline the process and avoid mixing data between environments.
By defining Site Context Variables and utilizing Blacklist Rules, you can effectively filter content based on the active environment, ensuring that each environment retrieves only the relevant data. Additionally, integrating environment variables within your Next.js application and properly configuring the context.setPage() function allows you to dynamically set and pass the environment context to Sitecore Search, making it possible to tailor search results to each specific environment.
While implementing these steps can be tricky, especially when the documentation doesn’t offer clear guidance on how Site Context Variables are mapped on the Sitecore side, this solution provides a clean and efficient way to manage your search results across environments.
By following this approach, you can ensure accurate testing, prevent data contamination, and streamline the process of working with Sitecore Search in multi-environment setups. Happy coding! 🚀