Thursday, November 19, 2026

Scriban in a classic Sitecore

A Sitecore Dictionary, extended with Scriban

If you have worked with Sitecore (SXA) you will know the Sitecore Dictionary.  There is a version in Sitecore, although I'm not sure if many people use it but in SXA, you probably appreciate the per-site dictionary implementation. This post is based on a non-SXA implementation using a custom-built dictionary offering very similar functionality to the SXA dictionary. The idea here will work in a SXA environment as well though. And actually, it might also work in a headless environment with JSS or SitecoreAI although it depends on your setup as Scriban does not have a javascript package but there are alternatives like Liquid.

So we do not have SXA's rendering variants available in this project, but we ran into an interesting requirement where a templating engine like Scriban turned out to be the missing piece—not in a rendering variant this time, but on top of the dictionary itself. 

Scriban

I already wrote quite some posts on scriban - /search/label/scriban. In sitecore-sxa-93-scriban I explained for instance how to use the dictionary inside Scriban. 

Scriban is a lightweight, fast, and sandboxed text templating engine for .NET, we can pass any data model into a dictionary and let Scriban render the final text.  This was ideal for our issue.


Plain dictionary texts and simple string replacements

Usually, dictionary entries are simple static strings: a button label or a validation message and so on. Sometimes when you need dynamic values in there, you add a placeholder like `{0}` and use string.Format - or maybe a named token like `{{discount}}` and a .Replace(...).

That works fine for simple cases, until your text starts depending on business data. Think about texts that explain a pricing structure, promotional rules, or shipping conditions. In many cases even those are rather general but now our customer really needed to get a changing amount of specific numbers in there - and yes, they still wanted to edit the texts. 

Simple string replacement quickly hits a wall here. Positional placeholders are fragile. One is fine, two maybe, but when you have too many editors and translators might make mistakes - causing bugs. There is also no conditional logic like if / else.  What if a sentence should only appear when a discount applies? And also, there are no loops. We do have a variable number of prices or promotions to show, so a loop is needed.
Creating multiple entries for each conditional statement, or building a list in code by concatenating dictionary fragments is not something you really want to do.


The idea: Scriban as a templating engine on top of the dictionary

Instead of keeping all that formatting and conditional logic in C#, we decided to treat the dictionary entry as a Scriban template and enrich it with structured data from code at render time.

One important caveat: this is obviously not meant for every dictionary key, nor for every regular editor. Writing templates with loops and conditions requires a bit of technical understanding. And of course, the templates are written by the developers (us) - but even to change/translate the texts inside it is best that the editors understand what is going on. 

If a dictionary entry contains no Scriban tags at all, Scriban simply outputs the plain text as-is. This means we could put it on top of all entries, but we still decided not to. 

The implementation

At the core of this solution is a small service that takes the raw text (fetched from the dictionary - although this could come from anywhere) and an IDictionary containing the data we want to expose:

using System.Collections.Generic;
using Scriban;
using Scriban.Runtime;

public interface IScribanDictionaryRenderer
{
    string Render(string templateSource, IDictionary<string, object> templateData);
}

public class ScribanDictionaryRenderer : IScribanDictionaryRenderer
{
    public string Render(string templateSource, IDictionary<string, object> templateData)
    {
        if (string.IsNullOrWhiteSpace(templateSource))
        {
            return string.Empty;
        }

        var parsedTemplate = Template.Parse(templateSource);
        if (parsedTemplate.HasErrors)
        {
            // Log parsedTemplate.Messages here
            return templateSource;
        }

        var scriptObject = new ScriptObject();
        if (templateData != null)
        {
            foreach (var entry in templateData)
            {
                scriptObject[entry.Key] = entry.Value;
            }
        }

        var context = new TemplateContext();
        context.PushGlobal(scriptObject);

        return parsedTemplate.Render(context);
    }
}


A few things to note in this code, as this is mvp material to test the idea and not ready to just copy into production. Think of it is something your AI buddy gave you - or do you just push that to live environments? ☺

There has to be a graceful handling of syntax errors. If an editor makes a typo in the Scriban template  the parsedTemplate.HasErrors will be true. This needs to be logged and handled without crashing. We are here simple returning the original template. This is handy for development, but that is probably not something you want to in production.

Every key-value pair in templateData is and pushed onto the Scriban TemplateContext. Note that if you nwat to push this even further you could also customize Scriban here by registering custom functions . I did write some posts on how to do that in a SXA context: custom SXA Scriban extensions and exposing custom objects in Scriban. 

You should be careful with Scriban's default naming convention. By default, Scriban converts PascalCase property names on your C# objects to snake_case (so a property `MinQuantity` on a C# class becomes `min_quantity` inside the template). If this is an issue, you can look at member renamers.

By default the culture will be CultureInfo.InvariantCulture. If your templates use Scriban's formatting helpers like `math.format` (probably not, but you never know) you should check the culture settings with context.PushCulture(Sitecore.Context.Language.CultureInfo) so numbers and dates match the current site language.


Example

Let's look at a real-world example. Suppose we have a product or promotion with a base price, an optional free-shipping threshold, and a dynamic list of volume discounts.

In C#, we prepare the data, fetch the template from the dictionary service and pass it to our Scriban renderer. Assuming you can write this code, let's focus on how the template could look:

<p>
  The standard price is {{ currency }}{{ base_price }} per unit.
  {{ if free_shipping_threshold > 0 }}
    Orders above {{ currency }}{{ free_shipping_threshold }} qualify for free shipping.
  {{ end }}
</p>

<p>Volume discounts:</p>
<ul>
  {{ for tier in tiers }}
    <li>Buy {{ tier.min_quantity }} or more: {{ currency }}{{ tier.unit_price }}/unit</li>
  {{ end }}
</ul>

Notice how much flexibility the editor gets here without requiring a single code deployment. But also, how we managed to limit the number of dictionary texts and custom coding replacing texts.


Conclusion

Putting Scriban on top of a Sitecore dictionary is a small piece of code -literally one lightweight class-that unlocks a lot of power when static text or simple token replacement just isn't enough.

Of course, just like with Scriban in SXA rendering variants, the key is balance: keep simple labels simple, make sure the people editing these dictionary templates understand the templates, be ready for syntax errors and reserve this approach for cases where dynamic data, conditions, and loops genuinely save you from hardcoding text-building logic in C#.


Wednesday, November 18, 2026

xConnect-Only in the SearchStax Cloud Connector for Sitecore

 xConnect-Only Deployments in the SearchStax Managed Search Connector for Sitecore

People who read my blog posts know I still have a few projects on good old Sitecore XP. This is a post that has been hanging around for a while. Earlier this year I was involved in an upgrade process where we also moved the indexes from Azure Search to Solr.  As you probably know Sitecore stopped support for Azure Search completely in 10.2. Although you can host your own Solr instance, there are other options with companies that take away some of the burden and manage that Solr for you. SearchStax is one of them and quite familiar in the Sitecore community. So while setting up the latest Sitecore version for the upgrade (10.4 at that time) we also switched to SearchStax Managed Search.  

We bumped into a small issue - and have a fix for it so it's worth sharing. Although I must admit the issue was also caused by something we did wrong - but we're human, so that happens :) 


If you are using SearchStax Managed Search (Solr-as-a-Service) with Sitecore XP, the SearchStax Cloud Connector for Sitecore is a huge time-saver. Instead of manually uploading ZooKeeper configs, creating collections, and configuring aliases, the PowerShell script (sitecore-searchstax-connector.ps1) automates the heavy lifting based on a config.yml file. The documentation on this config file is pretty good and it has lots of options to set everything exactly as you need - including custom indexes.

Due to my own mistake, I ran into a scenario where I needed to configure only xConnect indexes —without touching the standard Sitecore XP platform indexes again. Of course, I could remove everything and start all over but according to the SearchStax documentation, this should work out of the box. In practice, however, running the script in XCONNECT-only mode hit a subtle bug.


The configuration modes

In config.yml, the configurationMode setting supports three values:

  • XP – Sets up the Sitecore platform and marketing indexes only.
  • XCONNECT – Sets up the xDB search indexes (xdb / xdb_rebuild) only.
  • XP|XCONNECT – Sets up both at the same time.

When the script initializes, it check the configurationMode and sets boolean flags to determine later on what to do. 

The issue

When I set configurationMode: "XCONNECT", the script failed. Apparently it was unable to resolve the Solr version which of course broke the code in a later phase.

Right after initialization, the script maps sitecoreVersion to the corresponding $solrVersion (for example, 10.0.* → 8.4.0, 10.4.* → 8.11.2).  The catch was that this version-mapping logic only lived inside the XP branch and was not executed when this flag was not true.

Which is the case when configurationMode is set strictly to "XCONNECT". As a result, the script skipped the version check and left $solrVersion empty.  Even though the script later entered the the code to perform all tasks needed for the xDB indexes, passing an empty $solrVersion broke the execution there.

The Fix

To support XCONNECT-only execution properly, I added an extra block in sitecore-searchstax-connector.ps1 to resolve the solr version in this case:

elseif($global:isConfigureXConnect -eq "true") {
    if ($sitecoreVersion -eq "9.0.2") {
        $solrVersion = "6"
        $global:isUniqueConfigs= $true
    } elseif ($sitecoreVersion -eq "9.1.1") {
        $solrVersion = "7.2.1"
    } elseif ($sitecoreVersion -eq "9.2.0") {
        $solrVersion = "7.5.0"
    } elseif ($sitecoreVersion -eq "9.3.0") {
        $solrVersion = "8.1.1"
    } elseif ($sitecoreVersion -like "10.0.*") {
        $solrVersion = "8.4.0"
    } elseif ($sitecoreVersion -like "10.1.*") {
        $solrVersion = "8.4.0"
    } elseif ($sitecoreVersion -like "10.2.*") {
        $solrVersion = "8.8.2"
    } elseif ($sitecoreVersion -like "10.3.*") {
        $solrVersion = "8.11.2"
    } elseif ($sitecoreVersion -like "10.4.*") {
        $solrVersion = "8.11.2"
    }
   ....
}


With $solrVersion populated, running the connector with configurationMode: "XCONNECT" now executes properly, uploading only the xConnect ZooKeeper configuration, creating the xdb collections, wiring up the aliases, and updating the xConnect schema.


When to use...

Being able to run XCONNECT independently is probably not something you regularly do but it can be helpful helpful when you really want to distribute everything - or if you screwed up and you want to redo just the xdb indexes :) 


Links

If you need this before it's merged, you can use my updated version or review the the pull request:


Also do check the SearchStax Documentation because as you know we already have 10.5 now so my version is outdated. But I do assume the issue is still in there. 

Good luck with your SearchStax solr's - except for this minor issue it worked like a charm for us.