Generative AI

Sitecore Search

JAM Stack

Developer Experience

Sitecore

Cloud Development

Frontend Development

Backend Development

Optimizely

Developer Relations

Sitecore Platform DXP

Sitecore CDP/Personalize

Sitecore Symposium Recap 2024

Welcome back, friends! In today's blog post, we're building upon my previous article where I discussed using the SDK to create a flow (also known as an Experience). We're taking it a step further by combining this topic with Generative AI. Specifically, we'll explore Function Calling—a concept that allows you to inform Generative AI about available functions and have it select the appropriate function and object based on given requirements. This powerful approach enables AI to dynamically interact with predefined functionalities.

I'm excited to announce a new repository I've been working on that leverages this capability. It's called the Sitecore Assistant. While others may have created similar tools in the past, I wanted to build something tailored for the new composable SaaS landscape—a tool you can run locally or host remotely, allowing users to interact with their Sitecore Cloud instance.

I have big dreams for this app, combining AI with the Personalize SDK and potentially more SDKs in the future. You can find the repository here: [dylanyoung-dev/sitecore-assistant: Building a local-based (or hosted) app that users can configure for their Cloud Portal environment to handle advanced use cases. (github.com)](https://github.com/dylanyoung-dev/sitecore-assistant).

It's a straightforward Next.js application. If you prefer not to use the AI capabilities, simply don't add the OpenAI API key, and it'll disable the chat feature. This project is still a work in progress, so stay tuned for future announcements.

I'm considering building a Nextron shell (since it's using Next.js) in the future, which would allow it to run as an executable on your PC or Mac. Sometimes I feel like I have too many ideas! If you're interested in contributing, reach out to me, and we can discuss the vision further.

This project represents a topic tangential to today's discussion, but one I hope to explore more in the future: how to extend Sitecore XM Cloud or other composable products with new functionality. In the past, you'd build modules and install them directly into Sitecore XM/XP, but this approach required modifying the core code—a practice that doesn't align well with our current SaaS landscape. Today's post offers a glimpse into this new project, and I plan to delve deeper into this topic in future articles. Stay tuned!

## What is Generative AI Function Calling?

Today, we'll utilize the chat interface I've built into that application, incorporating OpenAI Function Calling. This powerful concept works as follows: when a user asks a question like `Can you help me create an experience`, it sends the request to an API endpoint I've configured in Next.js. Behind the scenes, it executes a series of tasks that unfold like this:

1. Pass the current message and all available function specifications to the LLM.
2. Based on the input and available functions, it determines if any functions can be used and if it has the required input to call them. If not, it returns details to the user, prompting for more information or guiding them towards the correct function (if multiple are defined).
3. If it has all the necessary information, it returns the function and required parameters to the code running in the API request. You can then parse and run the function, or—as we'll see—use OpenAI's beta functionality to define a function structure and the function to run, allowing it to handle the function call for you.
4. Once the function returns data (such as from an API call or web scraping), it passes this back to the LLM, which formulates a response based on your original request.

This concept becomes incredibly powerful when you consider its potential. You could chain functions together, combine it with a Retrieval-Augmented Generation (RAG) approach, or even integrate it with a custom or fine-tuned Language Model (LLM) to achieve highly refined, actionable results. In today's examples, we'll leverage the Sitecore Personalize SDK—which I've been discussing over the past few months—and combine it with our Chat application. This integration will enable our Chat application to create experiences on our behalf.

## Creating an Experience in Personalize

Let's dive into our code to see how we can create an experience using a chat application. I've already shared the repository in the first part of this article, so refer there for the full source. Our application is currently built with Next.js, as I plan to host it on the web and need to keep my OpenAI key secure. This setup is crucial to understand because the chat application features a chat box (running inside a modal) where users input their commands. These commands are then sent to an API route hosted in Next.js, which handles all the OpenAI magic with Function Calling. This API route is responsible for sending code to OpenAI, managing system messages, defining and using Function Calling, and providing the functions that the code will execute. We also pass in all currently configured clients, which are used to authenticate with various services for asset creation.

Now, let's examine the API route code:

```typescript
const client = new OpenAI({ apiKey: process.env.OpenAI_API_KEY });

interface Message {
  sender: "user" | "assistant";
  content: string;
}

interface ChatRequest {
  message: string;
  messages: Message[];
  clients: ClientData[];
}

export async function POST(req: NextRequest) {
  try {
    const { message, messages, clients }: ChatRequest = await req.json();

    const combinedMessages: ChatCompletionMessageParam[] = [
      {
        role: "system",
        content:
          "You are the Sitecore Assistant which will help users create Sitecore assets in the Sitecore SaaS products.  When running Sitecore Personalize apis that require code, always use EcmaScript 5.0 javascript that would work with Server Side Nashorn Javascript Engine.",
      },
      ...messages.map((msg) => ({
        role: msg.sender,
        content: msg.content,
      })),
      { role: "user", content: message },
    ];

    console.log({ clients });

    const runner = await client.beta.chat.completions
      .runTools({
        model: "gpt-4o-mini",
        messages: combinedMessages,
        tools: [
          await CreateExperienceTool(clients),
          await GetFlowsTool(clients),
          await ListOfExperiencesTool(clients),
        ],
      })
      .on("message", (message) => {
        console.log(message);
      })
      .on("functionCallResult", (result) => {
        console.log("result", result);
      });

    const finalContent = await runner.finalContent();

    return NextResponse.json({ message: finalContent });
  } catch (error) {
    console.error("Error generating AI Response:", error);
    return NextResponse.json(
      { error: "Error generating AI Response" },
      { status: 500 }
    );
  }
}
```

Let's dissect this code. Within our API route, which processes a POST request from our chat application, we find the following crucial segment:

```typescript
const combinedMessages: ChatCompletionMessageParam[] = [
  {
    role: "system",
    content:
      "You are the Sitecore Assistant which will help users create Sitecore assets in the Sitecore SaaS products.  When running Sitecore Personalize apis that require code, always use EcmaScript 5.0 javascript that would work with Server Side Nashorn Javascript Engine.",
  },
  ...messages.map((msg) => ({
    role: msg.sender,
    content: msg.content,
  })),
  { role: "user", content: message },
];
```

This code serves two primary functions. First, it provides initial context to our Language Model (LLM), instructing it on its identity and the services it's designed to offer. It also supplies context regarding the JavaScript format required for Sitecore Personalize. Second, the code manages short-term memory considerations. This is crucial as we aim for a conversational interaction with our LLM, allowing us to craft our Personalize experience through multiple prompts.

Next, let's examine a crucial part of the code:

```typescript
const runner = await client.beta.chat.completions
  .runTools({
    model: "gpt-4o-mini",
    messages: combinedMessages,
    tools: [
      await CreateExperienceTool(clients),
      await GetFlowsTool(clients),
      await ListOfExperiencesTool(clients),
    ],
  })
  .on("message", (message) => {
    console.log(message);
  })
  .on("functionCallResult", (result) => {
    console.log("result", result);
  });
```

This code snippet is crucial for enabling AI Function Calling. We're utilizing the OpenAI Node SDK ([openai/openai-node: The official Node.js / Typescript library for the OpenAI API (github.com)](https://github.com/openai/openai-node)), specifically its new beta feature for running Tools in chat completions. We're also employing OpenAI's latest model, `gpt-4o-mini`. The real magic happens when we define our tools—in this case, three examples that perform these key actions:

- Creating a Web Experience
- Getting Back a Specific Experience/Experiment based on a ref
- Getting a List of Experiences

One fascinating aspect I discovered while working with the LLM is its ability to extract required values from unexpected sources. This capability stems from its understanding of function requirements. For instance, after creating an experience, you can prompt the LLM to retrieve additional details about it. It accomplishes this by running the GetFlowsTool, knowing that the reference ID—obtained from the experience creation—is sufficient for this task.

Now, let's examine the final crucial component: the function definition and the function that executes when all the correct parameters for creating an experience are provided. Let's take a look at the code for `CreateExperienceTool`:

```typescript
export const CreateExperienceTool = async (clients: ClientData[]) => ({
  type: 'function' as const,
  product: ProductOptions.PersonalizeCDP,
  function: {
    name: 'create_personalization_experience',
    type: 'function',
    description: 'Creates a new personalization experience in Sitecore Personalize.',
    parameters: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          description: 'The name of the personalization experience.',
        },
        type: {
          type: 'string',
          enum: ['Web', 'API', 'Triggered'],
          description: 'The type of the experience.',
        },
        channels: {
          type: 'array',
          items: {
            type: 'string',
            enum: ['Call Center', 'Email', 'Mobile App', 'Mobile Web', 'Web', 'SMS'],
          },
          description: 'The channels for the experience.',
        },
        assets: {
          type: 'object',
          properties: {
            html: {
              type: 'string',
              description: 'The HTML content for the experience, use pure HTML only.',
            },
            css: {
              type: 'string',
              description: 'The CSS content for the experience, do not use precompiled CSS, only pure CSS.',
            },
            js: {
              type: 'string',
              description:
                'The JS content for the experience which needs to use Nashorn Engine compatible ES5 Javascript.',
            },
            freemarker: {
              type: 'string',
              description:
                'This is used to define the API response information using free marker syntax for the experience.',
            },
          },
        },
      },
      required: ['name', 'type', 'channels'],
    },
    function: async (args: { params: any }, runner: any) => {
      return await createPersonalizationExperience(args, clients);
    },
    parse: JSON.parse,
  },
});
```

There's a substantial amount of code here, so let's focus on the key points rather than delving into every detail. First, we define the overall description of our function. This description informs our LLM about the function's purpose and use case. Next, we have the `parameters` section, which describes all the fields or parameters that need to be provided. There's also a separate `required` property, as some fields aren't necessary in this example. The assets—such as JavaScript, HTML, and CSS—are only needed if we have a variant. As we've discussed previously, these aren't always required to create an experience, though they're certainly valuable to have (especially when provided by our LLM). We can specifically instruct the LLM to generate the HTML, CSS, and JavaScript for our variant by requesting it to create these values.

Finally, at the bottom of the function definition, we have:

```typescript
function: async (args: { params: any }, runner: any) => {
	return await createPersonalizationExperience(args, clients);
},
parse: JSON.parse
```

Here's how it works: Once the LLM determines all the necessary parameters, it executes the function using those parameters. The `parse` function simply parses the parameters passed through the `args` parameter. After the function runs, its result is fed back into the LLM, which then generates a response based on the function's output. Let's take a quick look at the code for the `createPersonalizationExperience(args, clients)` function.

```typescript
export const createPersonalizationExperience = async (args: any, clients: ClientData[]) => {
  let personalizeClient;
  if (args !== undefined && clients !== undefined) {
    const clientDetails = clients.find((client) => (client.product = ProductOptions.PersonalizeCDP));

    if (!clientDetails) {
      return {
        status: 'error',
        message: 'You must have a client configured for Personalize/CDP to create an experience.',
      };
    }

    personalizeClient = new Client({
      clientId: clientDetails.clientId,
      clientSecret: clientDetails.clientSecret,
      region: mapRegion(clientDetails.region),
    } as IClientInitOptions);
    const flowTypeMapping = mapFlowType(args.type);

    console.log(args);

    if (!flowTypeMapping) {
      console.log(flowTypeMapping);
      return {
        status: 'error',
        message: `Invalid flow type: ${args.type} it should match one of the following: Web, API, Triggered`,
      };
    }

    const experience: IFlowDefinition = {
      name: args.name,
      friendlyId: args.name.toLowerCase().replace(/\s+/g, '_'),
      type: flowTypeMapping,
      channels: args.channels.map((channel: string) => FlowChannel[channel as keyof typeof FlowChannel]),
      status: FlowStatus.Draft,
      schedule: {
        type: FlowScheduleType.Simple,
        startDate: new Date().toISOString(),
      },
    };

    // Check if any of the fields in assets are provided
    if (args.assets && (args.assets.html || args.assets.javascript || args.assets.freemarker || args.assets.css)) {
      experience.variants = [
        {
          name: 'Default Variant',
          assets: {
            html: args.assets.html || '',
            js: args.assets.javascript || '',
            css: args.assets.css || '',
          },
          templateVariables: {},
          ...(args.assets.freemarker && {
            tasks: [personalizeClient.Flows.CreateTemplateRenderTaskInput(args.assets.freemarker)],
          }),
        },
      ];
    }

    try {
      console.log('Creating personalization experience:', experience);
      let response = await personalizeClient.Flows.CreateExperience(experience);

      return {
        status: 'success',
        message: 'Personalization experience created successfully.',
      };
    } catch (error: any) {
      return {
        status: 'error',
        message: `Failed to create personalization experience: ${error.message}`,
      };
    }
  }

  let response = await console.log('Creating personalization experience:', args.params);
  return {
    status: 'fail',
    message: 'Parameters are missing for creating a personalization experience.',
  };
};
```

I won't go through the code line by line, but I'll explain the logic to help you understand what's happening. First, we perform some type checking to ensure we have valid clients and arguments. We also verify that the available clients are for Sitecore Personalize—a specific requirement for our application that might differ depending on your use case.

After confirming the passed data, we create a `Personalize Client` instance, initializing the Sitecore Personalize SDK. We then create a new IFlowDefinition object to build our experience. We check for any asset information for our variant and include it if available. With a valid Flow Definition, we call `personalizeClient.Flows.CreateExperience(experience);`, passing in our newly created definition. The response is then used to inform the app of successful completion. We could enhance this by returning the flow definition details, which the LLM could then display. This represents the current state of our proof of concept, with more iterations and improvements on the horizon. Keep an eye on the repository for future updates—the potential use cases are only going to expand from here.

## The Flow

We've explored how to create an experience using AI Function Calling with an LLM (in our case, the OpenAI GPT model). But what does the application flow look like today? It's actually quite simple to create our asset. If you're new to running this app, you can simply ask, "What are my options?" This will return all the Function Calling definitions available to you. You could also say, "I'd love to create a web experience today." This helps the system understand that you're trying to create an experience, specifically a "Web" experience, which it can use for some of the parameters.

Now, with these basic instructions, the system would likely create an experience without a variant, which isn't particularly helpful. To enhance this, you could ask something like: `It would be great if the experience used a web popup to display that I have a discount available. Could you help me generate this?` This prompt signals to the LLM that you want help generating code for your experience, which will become your default variant. Typically, after running this, it'll generate a sample and ask if you like the output and want to proceed with creating the experience. It's quite impressive that once you confirm, it will create your experience using the function code we previously discussed.

## Conclusion

AI Function Calling is undoubtedly impressive, but there are some obvious challenges with this approach. What if we wanted to incorporate all the different actions available in the Sitecore Personalize SDK? That would require defining even more functions, which would consume additional tokens to store this context. However, Function Calling offers even more possibilities. I'll be back soon to explore more topics related to this tool as I develop a highly effective LLM tool for Sitecore Personalize, and eventually for other products in the Sitecore Composable stack.

Revolutionizing Sitecore Personalize: Unleashing the Power of Generative AI Function Calling

Welcome back, folks! Today, I'm continuing my mini-series on the Sitecore Personalize SDK I created, which wraps the Sitecore Personalize APIs detailed in the documentation here: [https://doc.sitecore.com/personalize/en/developers/api/rest-apis.html](https://doc.sitecore.com/personalize/en/developers/api/rest-apis.html). I'll be focusing on the REST APIs related to creating a Flow in Sitecore Personalize.

A flow in Sitecore Personalize is essentially a single object type representing two distinct types of functionality: an Experience or an Experiment. In my SDK, I've split the creation of Experiences and Experiments into separate functions. Why? To provide more control over the required fields of the Flow Definition.

Behind the scenes, I use Zod to manage which fields are absolutely required for creating an Experience or Experiment. It's worth noting that an Experiment needs more fields than an Experience. Also, creating a basic experience or experiment requires fewer fields than what's realistically needed. For instance, to create a true `experience` like a Web Experience, you'd want to include template assets as well. I'll dive deeper into this later in this post.

In this post, I'll focus specifically on Experiences, as the SDK is still being developed to fully support both experiences and experiments. As mentioned earlier, I aim to make this SDK user-friendly for creating either flow type. Consequently, significant effort is being invested in Zod schema definitions to achieve this goal. It's important to note that the required data will vary depending on the flow type, such as triggered flows or web/full stack flows. Additionally, incorporating a decision model or condition into the flow can significantly impact the required fields.

If you haven't already, make sure to pull the latest SDK from [https://www.npmjs.com/package/sitecore-personalize-tenant-sdk](https://www.npmjs.com/package/sitecore-personalize-tenant-sdk). To create experiences, you'll need version 0.4.5 or newer.

## Creating a Simple Experience with the SDK

Let's dive into creating a simple experience using the SDK. This basic example highlights the essential fields needed to create an experience. However, as mentioned earlier, there are many more fields involved in a flow, which can vary depending on the scenario. I'll document these in detail on the repo's README and supporting documents, as it would be too extensive to cover every scenario here. As with previous blog posts, ensure you have a Node-based repository and have installed the latest version of the SDK. Once that's set up, you'll need to initialize the SDK as discussed in the series. Here's the code to get started:

```typescript
const config: IClientInitOptions = {
	clientId: "<ClientId>",
	clientSecret: "<ClientSecret>",
	region: RegionOptions.EU
};

const personalizeClient = new Client(config);
```

Where can you obtain the Client ID and Secret? I won't delve into that in this post, but you can refer to my previous blog: [Sitecore Personalize: New Developer Focused API Keys (dylanyoung.dev)](https://dylanyoung.dev/insights/sitecore-personalize-new-developer-focused-api-keys/), where I covered this topic in detail. For our current use case, let's assume you're creating keys scoped to `Multiple resources`.

Once we've initialized the SDK, creating an experience is quite straightforward. However, it's crucial to keep in mind which fields are absolutely required. Let's examine the code we'll use to create our Experience:

```typescript
const testExperience: IFlowDefinition = {
	name: 'Test Blog Experience',
	friendlyId: 'test_blog_experience',
	type: FlowType.WebFlow,
	channels: [ FlowChannel.Web ],
	status: FlowStatus.Draft,
	schedule: {
		type: FlowScheduleType.Simple,
		startDate: new Date().toISOString(),
	}
}

let testExperienceResponse = await personalizeClient.Flows.CreateExperience(testExperience);

console.log(JSON.stringify(testExperienceResponse));
```

If all goes well with that code and you've initialized `personalizeClient` correctly above, you should now see the experience `Test Blog Experience` in your Sitecore Personalize tenant. But what about creating a more advanced experience that we can start using right away? Well, this is where adding the correct fields gets a bit trickier. Let's dive into this topic in the next section.

## Using a Web Experience with a Decision Model

Now that we've explored creating a simple experience in Sitecore Personalize, let's dive into a more advanced use case. We'll assume we have an existing `Decision Model` in our Sitecore Personalize tenant. As of this writing, the SDK offers limited support for Decision Models. However, a future scenario might involve creating a Decision Model via API, then using the APIs to create an Experience powered by that Decision Model. Why would anyone want to do this? Well, that's a teaser for some upcoming content in the pipeline—I've got some exciting ideas about potential applications, but we'll dive into those later.

Let's start by examining the code required to create our more complex use case. Then we'll work backwards to break down the new additions to this Web Experience.

```typescript
const testExperience: IFlowDefinition = {
        name: "Test API Experience5",
        friendlyId: "test_api_experience5",
        type: FlowType.WebFlow,
        channels: [ FlowChannel.Web ],
        status: FlowStatus.Draft,
        schedule: {
            type: FlowScheduleType.Simple,
            startDate: new Date().toISOString(),
        },
        variants: [
            {
                name: 'Variant API Test',
                isControl: false,
                assets: {
                    html: "\n\n<div id=\"pers-transition-card\">\n    <div class=\"img-container\">\n        <div class=\"img-container__image\"></div>\n    </div>\n    <div class=\"pers-transition-card__body\">\n        <h3>[[Title | string | Title | {required:true, group: Title, order: 1}]]</h3>\n        <p>[[Description | text | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt | {required:true, group: Description, order: 1}]]</p>\n        <div class=\"options-container\">\n            <a id=\"pers-transition-card--secondary\" class=\"options-container__secondary\">[[Dismiss Text | string | No Thanks | {required:true, group: Secondary Button, order: 1}]]</a>\n            <a id=\"pers-transition-card--primary\" class=\"options-container__primary\">[[CTA Text | string | Yes Please | {required:true, group: CTA Button, order: 1}]]</a>\n        </div>\n    </div>\n</div>",
                    css: "/*\n[[Background Colour | colour | #fff| {equired: true, group: General, groupOrder: 1, order: 3}]]\n[[Background Image Colour | colour | #F3F5F7| {equired: true, group: General, order: 4}]]\n[[Image URL | string || {required:true, group: General, order: 1}]]\n[[Font | enum(Arial,Arial Narrow,Brush Script MT,Calibri,Cambria,Candara,Copperplate,Courier,Courier New,Didot,Garamond,Geneva,Helvetica,Lucida Bright,Monaco,Optima,Perpetua,Times,Times New Roman,Verdana) |Arial|{group: General, order: 2}]];\n[[CTA Colour | colour | #000 | {equired: true, group: CTA Button, groupOrder: 4, order: 2}]]\n[[CTA Text Colour | colour | #fff | {equired: true, group: CTA Button, order: 3}]]\n[[CTA Hover Color | colour | #9e9e9e |{ required: true, group: CTA Button, order: 4} ]]\n[[CTA Text Hover Color | colour | #fff | { required: true, group: CTA Button, order: 5} ]]\n[[Secondary Colour | colour | #F3F5F7 | {equired: true, group: Secondary Button, groupOrder: 5, order: 2}]]\n[[Secondary Text Colour | colour | #000 | {equired: true, group: Secondary Button, order: 3}]]\n[[Secondary Hover Color | colour | #fff |{ required: true, group: Secondary Button, order: 4} ]]\n[[Secondary Text Hover Color | colour | #000 | { required: true, group: Secondary Button, order: 5} ]]\n[[Title Text Colour | colour | #4D4D4D | {group: Title, groupOrder: 2, order: 2}]]\n[[Title Text Font Size | number | 36 | { group: Title, order: 3 }]]\n[[Description Text Colour | colour | #4D4D4D | { group: Description, groupOrder: 3, order: 2 }]]\n[[Description Text Font Size | number | 16 | { group: Description, order: 3 }]]\n*/\n\n#pers-{{ref}} a,\n#pers-{{ref}} p,\n#pers-{{ref}} span {\n  font-family: [[ Font ]];\n  font-weight: 400;\n  line-height: 1.2;\n}\n\n#pers-{{ref}} #pers-transition-card {\n    position: fixed;\n    width: 435px;\n    right: 0;\n    bottom: -1000px;\n    z-index: 999999;\n    transition: bottom .6s ease-in-out;\n    margin-bottom: 0;\n    border-radius: 4px;\n    background-color: [[Background Colour]];\n    overflow: hidden;\n    box-shadow: 0 0.2rem 0.4rem 0.2rem rgba(0,0,0,.1);\n    font-size: initial;\n}\n\n#pers-{{ref}} #pers-transition-card.open {\n    bottom: 0;\n}\n\n#pers-{{ref}} #pers-transition-card .img-container {\n    width: 100%;\n    height: 250px;\n}\n\n#pers-{{ref}} #pers-transition-card .img-container__image {\n    margin: 0;\n    background: [[Background Image Colour]];\n    height: 100%;\n    display: flex;\n    justify-content: center;\n    align-items: center;\n    font-size: var(--font-size-h4);\n    background-image: url(\"[[Image URL]]\");\n    background-position: center;\n    background-repeat: no-repeat;\n    background-size: cover;\n}\n\n#pers-{{ref}} #pers-transition-card .pers-transition-card__body {\n    padding: 37px 34px;\n}\n\n#pers-{{ref}} #pers-transition-card .pers-transition-card__body h3 {\n    margin-top: 28px;\n    line-height: 1.5;\n    font-size: [[ Title Text Font Size ]]px;\n    font-weight: bold;\n    text-align: center;\n    margin: 0;\n    color: [[Title Text Colour]];\n    font-family: [[Font]];\n}\n\n#pers-{{ref}} #pers-transition-card .pers-transition-card__body p {\n    padding: 12px 0;\n    margin: 0;\n    font-size: [[ Description Text Font Size ]]px;\n    line-height: 28px;\n    text-align: center;\n    color: [[Description Text Colour]];\n    font-family: [[Font]];\n}\n\n#pers-{{ref}} #pers-transition-card .options-container {\n    display: flex;\n    justify-content: center;\n}\n\n#pers-{{ref}} #pers-transition-card .options-container__primary {\n    display: inline-block;\n    border-radius: 4px;\n    color: [[CTA Text Colour]];\n    background-color: [[CTA Colour]];\n    padding: 10px 30px;\n    cursor: pointer;\n    font-size: [[Font]];\n}\n\n#pers-{{ref}} #pers-transition-card .options-container__primary:hover {\n  color: [[CTA Text Hover Color]];\n  background-color: [[CTA Hover Color]];\n}\n\n#pers-{{ref}} #pers-transition-card .options-container__secondary {\n    display: inline-block;\n    border: 1px solid #C1C9D0;\n    border-radius: 4px;\n    color: [[Secondary Text Colour]];\n    background-color: [[Secondary Colour]];\n    padding: 10px 30px;\n    margin-right: 13px;\n    cursor: pointer;\n    font-size: [[Font]];\n}\n\n#pers-{{ref}} #pers-transition-card .options-container__secondary:hover {\n  color: [[Secondary Text Hover Color]];\n  background-color: [[Secondary Hover Color]];\n}",
                    js: "// Adds a unique variant identifier to CSS when deployed to ensure CSS does not impact styling of other elements.\nvar compiledCSS = Engage.templating.compile(variant.assets.css)(variant);\nvar styleTag = document.getElementById('style-' + variant.ref);\nif (styleTag) {\n    styleTag.innerHTML = compiledCSS;\n}\n// End Adds a unique variant identifier to CSS when deployed to ensure CSS does not impact styling of other elements.\n\n// make space in the body for the experience\ninsertHTMLAfter('body', 'pers-');\nvar persContent = document.querySelector(\"#pers-\"+variant.ref+ \" #pers-transition-card\");\n\nsetTimeout(function() {\n    persContent.classList.add(\"open\");\n    sendInteractionToPersonalize(\"VIEWED\");\n});\n\nvar persCardClose = document.body.querySelector(\"#pers-\"+variant.ref+ \" #pers-transition-card--secondary\");\npersCardClose.onclick = function() {\n    sendInteractionToPersonalize(\"DISMISSED\");\n    persContent.classList.remove(\"open\");\n}\n\nvar persCardCta = persContent.querySelector(\"#pers-\"+variant.ref+ \" #pers-transition-card--primary\");\npersCardCta.onclick = function() {\n    sendInteractionToPersonalize(\"CLICKED\");\n    window.location.href = \"[[CTA destination URL | string || {required:true, group: CTA Button}]]\";\n}\n\nfunction sendInteractionToPersonalize(interactionType) {\n    const type = \"[[ Experience ID | String | CORNER_POPUP | {required: true}]]_INTERACTION\";\n    const eventData = {\n        \"channel\": \"WEB\",\n        \"pointOfSale\": Engage.settings.pointOfSale,\n        \"interactionID\": \"PERS_CORNER_POPUP\",\n        \"interactionType\": interactionType\n    };\n\n    window.engage.event(type, eventData);\n}"
                },
                templateVariables: {
                    "Title": "Title",
                    "Description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt",
                    "Dismiss Text": "No Thanks",
                    "CTA Text": "Yes Please",
                    "Font": "Arial",
                    "CTA Colour": "#000",
                    "Secondary Colour": "#F3F5F7",
                    "Title Text Colour": "#4D4D4D",
                    "Description Text Colour": "#4D4D4D",
                    "Background Colour": "#fff",
                    "CTA Text Colour": "#fff",
                    "Secondary Text Colour": "#000",
                    "Title Text Font Size": "36",
                    "Description Text Font Size": "16",
                    "Background Image Colour": "#F3F5F7",
                    "CTA Hover Color": "#9e9e9e",
                    "Secondary Hover Color": "#fff",
                    "CTA Text Hover Color": "#fff",
                    "Secondary Text Hover Color": "#000",
                    "Experience ID": "CORNER_POPUP"
                },
                tasks: [
                    personalizeClient.Flows.CreateTemplateRenderTaskInput('<#-- Construct the API request body using Freemarker -->\n<#-- For your Experience to run your API tab must have, at a minimum, open and closing brackets -->\n{  <#-- Freemarker will go here -->   }'),
                    personalizeClient.Flows.CreateDecisionModelTaskInput([ "1885d8c9-d32d-4bf3-975d-f8dbd91882bc"])
                ]
            }
        ]
    }

    let testExperienceResponse = await personalizeClient.Flows.CreateExperience(testExperience);

    console.log(JSON.stringify(testExperienceResponse, null, 2));
```

As you can see, considerably more code is needed to create this use case because we need to create a variant for our Experience. When I first learned Sitecore Personalize, you could have more than one variant per experience. However, that's no longer the case—now your main variant will receive 100% of the traffic.

The variant includes HTML, CSS, and JavaScript, typically derived from a template or custom-built. If we were creating this experience from local templates, we'd pull the template source to build out these three properties. The API output is stored in a different location, where I use `personalizeClient.Flows.CreateTemplateRenderTask('Pass in your Free marker here')` to easily create this object (as there's much more involved behind the scenes). I'm working on more helper functions like this, aiming to hide the boilerplate code and simplify experience creation.

The `templateVariables` is a key-value pair object where the keys are strings. This structure allows us to inject data into our template (although technically, we're not using a true template here). Our understanding of templates in Personalize evolves as we delve into the underlying code. In essence, the template functions more like a snippet—a reusable piece of code that drives the variants themselves.

I also created another task helper, `personalizeClient.Flows.CreateDecisionModelTaskInput([ "decision-model-ref"])`, which simplifies this object. As mentioned earlier, you need to create the Decision Model first. I hope to cover these multi-resource scenarios soon.

There you have it! Our experience is now successfully created in our tenant:

![](https://cdn.sanity.io/images/lanua4su/production/22fb52a7ed58cb0137ecc6f54f88b861c79cbbce-1385x764.jpg)

## Teaser

You might wonder why you'd want to create an experience using this SDK. Well, my next blog in this mini-series will showcase a compelling scenario—leveraging Generative AI. But that's just the tip of the iceberg. I'm excited to explore numerous other valuable use cases in the coming months. So, stay tuned for these upcoming articles—you won't want to miss them!

Creating an Experience with the Sitecore Personalize SDK

Today, I have a real treat for you: an in-depth comparison between Optimizely's new Headless SaaS CMS and Sitecore's XM Cloud product. This is one of the biggest perks of working at a large partner—exclusive access to the latest products. With extensive experience in Headless SaaS CMS products ([Sanity.io](http://sanity.io/), Storyblok, Contentful, XM Cloud, Content Hub One) and significant hands-on time with XM Cloud, I'm excited to compare these two market contenders.

This isn't a deep dive into Optimizely's new SaaS CMS; however, since I have access, I'll likely create more content on this topic in the future. It's important to note that unlike Sitecore, which has been on the market for several years, Optimizely's offering was recently released. This is crucial to keep in mind, as it will influence our final comparison today.

## An Overview

Before we dive into our comparison between these two SaaS CMS platforms, let's clarify what a SaaS-based Enterprise CMS is and explore more about these two companies and their products.

A SaaS-based Enterprise CMS is a cloud-hosted content management system that offers scalability, flexibility, and reduced maintenance for large organizations. These platforms provide robust content creation, management, and delivery capabilities without the need for on-premises infrastructure. Now, let's delve into Optimizely and Sitecore, two major players in this space.

Both Optimizely and Sitecore's SaaS CMS offerings embrace a more modern architectural approach, departing from the monolithic structure where all systems were tightly coupled. The most common grievance I've heard from developers on both platforms is the inability to extend them—but I argue that's precisely the point. You can't extend these platforms using traditional methods from non-SaaS tools, and that's by design. Modifying the platforms would compromise the SaaS model, necessitating a complete rethink of architecture. The new paradigm focuses on integrating external systems with these headless tools, rather than directly altering the platforms themselves.

The traditional approach involved directly modifying the existing platform. In contrast, the modern approach focuses on extending functionality through external options—which we'll discuss shortly—and building around the product using hooks and APIs.

Now that we have a better understanding of how these products compare to each other and fit into the existing Headless SaaS CMS ecosystem, let's evaluate various aspects to determine which of these two products excels in each area. Let's dive in.

## Ability to Learn

This category assesses how easy or difficult it is for developers, marketers, and end users to navigate and utilize the product. It considers both newcomers to the platform and existing users who may have experience with the company's on-premises offerings.

From Optimizely's perspective, their new SaaS platform introduces several features not present in the on-premises version. For instance, `Experiences`—which I initially mistook for a competitor to Sitecore XM Cloud's personalization capabilities—actually adds more presentation-like information to your page and enables the `Visual Builder`, another new feature in this SaaS product. I must admit, the `Experiences` and `Visual Builder` feel somewhat disconnected. The requirement to change a Page to an Experience to enable the Visual Builder, rather than having it available for all pages, seems a bit confusing. For a new user, aside from this quirk, the platform is relatively easy to grasp. In contrast to XM Cloud, which I'll discuss shortly, this product more closely resembles a traditional SaaS and Headless CMS.

Sitecore has always presented a steep learning curve for newcomers to the content management space. Users face a barrage of terminology, even for simple tasks. Take, for example, SXA (Sitecore Experience Accelerator) and its newer iteration, "headless SXA"—a term that, in my view, doesn't quite fit, given that it and the Component Builder are now the sole building methods in XM Cloud. Beyond grasping product concepts and new XM Cloud apps, developers must also wrestle with additional terms like JSS (JavaScript Services) when implementing Sitecore solutions.

This steep learning curve is further complicated by the existence of "right" and "wrong" ways to implement a Sitecore solution. Even seasoned Sitecore developers face new challenges with XM Cloud. They must master the Component Builder, grasp the nuances between headless SXA and traditional SXA, and adapt to feature changes that differ from the on-premises XM and XP versions.

Furthermore, implementing the "head" (front-end) of XM Cloud demands additional learning. In contrast to Optimizely, which offers a .NET Core example for its SaaS product implementation, Sitecore solely recommends Next.js for the host application. While it's challenging to determine if Optimizely's .NET Core version is feature-complete, it's essential to recognize these substantial learning obstacles in the Sitecore XM Cloud ecosystem.

**Winner**: Optimizely SaaS CMS

## Features

Before comparing the features and capabilities of these two offerings, it's important to note that Sitecore's product has been on the market longer than Optimizely's SaaS offering. This extended presence gives Sitecore the advantage of having more time to develop and refine its capabilities.

As previously mentioned, Optimizely's new SaaS CMS reminds me more of a traditional headless CMS compared to XM Cloud. This is because it lacks many capabilities you'd find in XM Cloud. I'm sure Optimizely, now that it has a SaaS CMS product, will eagerly embark on a journey of rolling out new features. However, one additional drawback is that this product has fewer features than XM Cloud had in its early days.

XM Cloud, on the other hand, is packed with features. As I mentioned, this is largely due to user demand and XM Cloud's continuous addition of new capabilities since its launch. I expect Optimizely will follow a similar trajectory. Let's take a moment to explore some of the capabilities that exist in XM Cloud but are currently absent from Optimizely's SaaS CMS.

### Forms

Sitecore XM Cloud frequently received requests for a forms feature in the year following its release. Without it, customers migrating from XP or XM, who were accustomed to these capabilities, would have had to use other providers. Sitecore has now delivered, offering Forms as a SaaS option with ongoing improvements. Since its initial release, which had numerous issues, they've enhanced the product's stability and added new features like conditional fields. Unfortunately, Optimizely doesn't offer a comparable option in their SaaS CMS. While a forms engine may exist somewhere in their product lineup, it's not available in the Optimizely SaaS CMS without additional licensing costs.

### Personalization

Sitecore XM Cloud offered basic personalization capabilities out of the box from its launch, without requiring additional licensing. This is a compelling reason to choose XM Cloud, as many customers are just beginning their personalization journey. The platform provides an excellent opportunity for users to start personalizing content without investing in full-fledged personalization tools. Additionally, A/B testing (experimentation) is on the horizon. XM Cloud now also features edge-side personalization for scenarios where decisions can be made at the edge. Optimizely has significant ground to cover to match these capabilities.

The only downside to this is that the added benefit of personalization likely increases the cost of XM Cloud. Some customers may not want this additional feature, either because they don't plan to use it or they're already using another personalization solution. This highlights a potential drawback of XM Cloud: it might be too expensive for some, partly because it's trying to do too much. While I won't delve into pricing details (as I'm not certain how these products compare), it's an important consideration when choosing between these platforms. Do you want a content management system that excels at its core function, allowing you to add forms or personalization engines as needed? Or do you prefer a solution with all these capabilities built-in, potentially at a higher price point?

### Analytics

Analytics complements Personalization by leveraging Sitecore Personalize (CDP) capabilities behind the scenes. To my knowledge, Optimizely lacks a comparable feature. While this functionality is useful, I believe there are superior options available in the market, such as Google Analytics. Collecting this data can be beneficial if you plan to purchase Personalize in the future. However, I must admit that this is another instance where Sitecore may be adding capabilities that increase costs without delivering substantial value to their customers. Nonetheless, Sitecore offers this capability while Optimizely does not.

### Components

I won't delve too deeply into this topic. While XM Cloud's `Components` feature doesn't have a direct counterpart in Optimizely, it feels somewhat underdeveloped. It now competes with SXA components, which remain the recommended approach for development teams. It's an intriguing concept, but perhaps it was released prematurely. Nevertheless, having additional options is always beneficial.

### A Better Visual Builder

Although some may argue that Sitecore XM Cloud's visual builder (called Pages) isn't as feature-rich as the older Experience Editor, it's definitely superior to Optimizely's editor in my opinion. The main issue I have with Optimizely's editor is that you must configure it for pages, which likely means some marketers won't fully understand the steps to set it up. In contrast, Pages works seamlessly with any site you've set up in XM Cloud. This ease of use makes it superior, in my view. It feels like Optimizely hastily added this new capability, whereas XM Cloud built it as an integral feature from the ground up.

**Winner**: Sitecore XM Cloud

## Identity / Portal

Currently, when you log into the Optimizely SaaS CMS portal, it only contains the CMS. This contrasts with XM Cloud, which allows you to access and use SSO with their other SaaS composable options. Both products offer integration with external Identity providers (such as Azure or Okta), so they're equal in this respect. Neither platform provides a way to add apps to their portals—a feature that would be very useful. Sitecore XM Cloud gains an edge here because more of their SaaS composable products are now available in the Cloud Portal, creating a more unified interface.

**Winner**: Sitecore XM Cloud

## Extensibility

At first glance, XM Cloud appears to have an advantage with its deploy app. However, a closer look reveals that Sitecore actually discourages deploying .NET code customizations to the CMS. This approach aligns with SaaS best practices, as allowing direct platform modifications by customers or partners can be risky. Given the frequent upgrades inherent to SaaS products, such customizations could cause problems. Instead, SaaS architecture typically favors platform extension over modification. Interestingly, neither Optimizely SaaS CMS nor Sitecore XM Cloud currently provides a clear method for extending their platforms.

That said, I wouldn't be surprised if either platform provides clearer direction for extensibility in the future. For example, customers might want to create custom fields or launchpad apps—will either platform offer a way to do this? Alternatively, they may never provide these capabilities, leaving developers to use various APIs for creating external integrations and applications that work across different systems. At this point, both platforms could use more guidance for the community. While Sitecore has offered some direction, neither has clearly outlined how to achieve the customizations that customers were accustomed to with their non-SaaS products. This may be intentional, suggesting that customers seeking a highly customizable platform might need to stick with on-premises options.

**Winner**: Tie

## Developer Experience + Developer Choice

Developer choice is crucial in headless architecture. Both CMSs offer a hosted platform delivering content via API (REST or GraphQL), so it's vital for developers to have ample support for various frameworks or languages they might use to build their `head` application.

With the release of Optimizely’s SaaS CMS, example repositories were made available—though I haven't used them yet. They support a wide range of options, including .NET Core, Next.js, React, and Gatsby. For a complete list, check out the repository here: [https://github.com/episerver/content-graph-js-sdk/tree/main/samples](https://github.com/episerver/content-graph-js-sdk/tree/main/samples). This stands in stark contrast to Sitecore, which essentially provides just one fully functional example for XM Cloud. Although JSS (the SDK for Sitecore’s APIs) offers more options, many features like Multisite and Personalization in XM Cloud only work with Next.js. This is disappointing for a headless CMS, which by nature should offer framework choices. You could theoretically use something other than Next.js, but you’d need to build those XM Cloud features yourself. This is especially frustrating given that Optimizely’s offering is new, while XM Cloud has been around for years. I've heard talk of expanding support for other frameworks and languages, but as of now, that's not possible, making the winner in this category clear.

**Winner**: Optimizely SaaS CMS

## Stability + Maturity

This is an easy win for Sitecore XM Cloud. As with any new product in its infancy, Optimizely's SaaS CMS must learn to improve processes for running a SaaS business. It's different from running an on-premises option, as any issues are magnified when they arise, with immediate impacts. Gone are the days when you could build and release a product, then wait several months to receive feedback from customers beginning to build on the platform.

**Winner**: Sitecore XM Cloud

## The Ultimate Winner

I don't believe there are clear winners in this case, except perhaps the customers who now have another option for modern, enterprise-grade infrastructure. However, it's important to note that a SaaS enterprise CMS isn't always the right choice for every customer. When selecting a platform, carefully consider whether SaaS is the best fit for your business. While SaaS offers significant benefits that warrant thorough consideration, it does limit some direct customization options. For developers who've worked with these platforms over the past decade, the new Composable SaaS products demand a fundamental shift in approach. Building for these platforms now requires a focus on API utilization rather than direct customizations.

In summary, these products are evenly matched, with Sitecore XM Cloud having a slight advantage due to its longer time on the market. However, it's important to note that Optimizely's offering will likely mature rapidly, thanks to the continuous innovation and improvement inherent in SaaS platforms. When choosing between these products, your decision will ultimately depend on the specific features you're looking for. It's also crucial to recognize that both products exist within larger ecosystems. The choice isn't just about selecting the best CMS, but about finding the right combination of products that work well together to meet your needs.

I hope you've enjoyed this comparison! Stay tuned for more content on Optimizely and other SaaS CMS platforms coming soon to my channel.

Optimizely SaaS CMS vs Sitecore XM Cloud

Welcome back, friends! A few weeks ago, I introduced a new SDK I created for testing Sitecore Personalize. If you missed it, check out the original post: [Introduction to Sitecore Personalize SDK and Testing (dylanyoung.dev)](https://dylanyoung.dev/insights/introduction-to-sitecore-personalize-sdk-and-testing/). Today, we're diving deeper into Web Template automated integration tests using the SDK. We'll also explore the current APIs that make this approach possible.

As mentioned in my previous blog post, Sitecore Personalize offers various asset types, each requiring different integration testing methods. While our current testing capabilities are limited, they provide a solid foundation for ensuring the quality of our personalization efforts.

## Web Template Testing

The new SDK introduces numerous ways to test Sitecore Personalize after successful deployment or on a periodic basis. For web templates specifically, there are two APIs—and consequently, two methods—accessible through the SDK that facilitate testing templates post-deployment:

- TestNewTemplate ([Preview template code | Sitecore Documentation](https://doc.sitecore.com/personalize/en/developers/api/preview-template-code.html))
- TestExistingTemplate ([Preview templates | Sitecore Documentation](https://doc.sitecore.com/personalize/en/developers/api/preview-templates.html))

### TestNewTemplate

While this method may not be essential for integration testing, it proves invaluable for local integration testing when developing a new template. This approach assumes you've adopted a workflow where templates are built locally in source control and then deployed to your Personalize tenant. The function allows you to input your template's structure along with template parameters. It then returns the rendered result and indicates any issues encountered during template execution.

Let's take a closer look at how to use this method with the SDK. Here's an example:

```typescript
const templateElements: ITemplateElement[] = [
  {
    id: "js",
    template: "<script>console.log('Hello from template')</script>",
  },
  {
    id: "html",
    template: "<h1>Hello [[Title | string]]</h1>",
  },
];

const templateResult = await personalizeClient.Templates.TestNewTemplate(
  templateElements,
  { Title: "London" }
);

if (templateResult?.templates) {
  console.log(JSON.stringify(templateResult.templates));
}
```

This code showcases the TestNewTemplate method from the Sitecore Personalize SDK for testing a new web template. It creates template elements using HTML and JavaScript, then invokes the method with these elements and a parameter. If templates are returned, the result is logged. For guidance on initializing the Personalize SDK, [check out my previous article where I delved into this topic](https://dylanyoung.dev/insights/introduction-to-sitecore-personalize-sdk-and-testing/).

The results of that request are shown below. As you can see, because I passed in template variables with `Title` set to `London`, this value now appears in the response.

```typescript
[
  { id: "js", template: "<script>console.log('Hello from template')</script>" },
  { id: "html", template: "<h1> Hello London</h1>" },
];
```

### TestExistingTemplate

This method proves more valuable for post-deployment or ongoing integration testing scenarios. You can find the documentation for this endpoint (also available in the SDK) here: [Preview templates | Sitecore Documentation](https://doc.sitecore.com/personalize/en/developers/api/preview-templates.html). The method focuses on templates already existing within Sitecore Personalize. It allows you to input custom template variables, enabling you to verify that the rendered template—with your specified variables—aligns with your expectations.

So lets explore how we would call this in the Personalize SDK:

```typescript
const templateResults = await personalizeClient.Templates.TestExistingTemplate(
  "example_web_template",
  { "Alt Description": "London" }
);

console.log(JSON.stringify(template?.renderedTemplates));
```

For this scenario, we need an existing template. We can use the template's friendly ID (only) to reference it. The HTML of the web template I used looks like this:

```html

<div>[[Alt Description | text | | {order: 1, required: false} ]]</div>


```

This means when I passed in `Alt Description`, it was injected into my Web Template, providing a valid response. This approach is valuable as it allows you to test and verify that an existing template functions as expected. I'll delve into specific strategies for integration testing in a future post. Below, you can see the output of the code we just discussed:

```typescript
{
    "test": [
        {
            "id": "js",
            "template": "// You can choose how you want to add your HTML by using insertHTMLBefore, insertHTMLAfter, or replaceHTML methods\n// e.g insertHTMLAfter('.someClassName'); or insertHTMLAfter('body'); or replaceHTML('#myPageId')\n\n/*\n\n(function () {\n  // Add statements here\n})();\n\n*/"
        },
        {
            "id": "css",
            "template": "/** style your Experience with CSS */"
        },
        {
            "id": "html",
            "template": "\n<div>London</div>\n\n\n"
        },
        {
            "id": "freemarker",
            "template": "<#-- Construct the API request body using Freemarker -->\n<#-- For your Experience to run your API tab must have, at a minimum, open and closing brackets -->\n{  <#-- Freemarker will go here -->   }"
        }
    ]
}
```

As demonstrated above, when we set the `Alt Description` parameter to `London` in our `TestExistingTemplate` request, the template output reflects this change—replacing the placeholder with "London" in the rendered HTML.

## Flow (Experience/Experiment) Testing

### TestTemplate

I considered omitting this endpoint, but it could be a valuable feature for some developers. It's not currently supported by the SDK because the API doesn't work with the new developer-generated API tokens I've discussed in a previous post: [Sitecore Personalize: New Developer Focused API Keys (dylanyoung.dev)](https://dylanyoung.dev/insights/sitecore-personalize-new-developer-focused-api-keys/). Due to this lack of support, the only way to use it is by authenticating with your personal login—which isn't ideal if you're aiming to automate your development workflow.

What makes this API noteworthy—and potentially worth exploring in a future blog post—is its ability to execute your code, not just process template variables like the two examples above. If you have conditions or other logic, it will parse the code and output any errors that arise, as well as any debug messages you've included in your code (e.g., `print('some message');`).

That wraps up today's topic. Stay tuned for more content showcasing the capabilities of the SDK!

Create Web Template and Flow Integration Tests with Sitecore Personalize

Hello friends! This post emerged from another topic I started writing last week. I realized it would be more sensible to take a step back and cover an introductory topic before diving into a mini-series on related subjects.

Today, I'm excited to introduce a project I've been working on: the Sitecore Personalize Tenant SDK, available on NPM here: [sitecore-personalize-tenant-sdk - npm (npmjs.com)](https://www.npmjs.com/package/sitecore-personalize-tenant-sdk). This SDK focuses on wrapping the freely available APIs for managing assets in Sitecore Personalize. While still a work in progress, it's already proving valuable for those handling testing scenarios or exploring other use cases with Sitecore CDP/P.

The SDK primarily targets Personalize, but it's worth noting that CDP and Personalize were originally a single product built by Boxever. As such, this tool is designed to streamline working with both products, making it easier to consume and interact with their features.

# Who is the SDK for?

This SDK is intended for anyone who wants to create, read, update, or delete Sitecore Personalize assets (such as flows, decision models, templates, and conditions). Some specific use cases include creating an Experience in Sitecore Personalize based on an action in another system, using a chat application with AI to generate experiences, or—as with the Serializer (which will soon use the SDK)—enabling new development approaches with Sitecore Personalize.

# Who is it not for?

To clarify, this SDK is not designed for data ingestion into Sitecore CDP/P. For those needs, use the Engage SDK if you're not on XM Cloud or JSS 21.6+. If you are, opt for the Cloud SDK. For non-Web/Node platforms, you'd still interact directly with the Stream APIs or use the Engage Script.

# Getting Started with the SDK

Getting started with the SDK for Sitecore Personalize is straightforward. You can pull the latest version from NPM using the following command:

```javascript
$ npm install sitecore-personalize-tenant-sdk@latest
```

This SDK is not a CLI, so you'll need to install it in your Node project. Once installed, you can interact with it by initializing the Client. The Client expects an object of `ClientInitOptions`, which requires a client ID, client secret, and the region for your Sitecore Personalize tenant. Keep in mind that this tool only supports tenants on Cloud Portal. If your tenant still requires access from a Boxever domain, you won't be able to use this SDK. Since most tenants will be migrated to the Cloud Portal soon, you'll need to wait until your tenant is converted before using this SDK.

Creating the Client ID and Secret is now straightforward. I've written a blog post about it here: [Sitecore Personalize: New Developer Focused API Keys (dylanyoung.dev)](https://dylanyoung.dev/insights/sitecore-personalize-new-developer-focused-api-keys/). You can also find more information in the Sitecore documentation: [Create an API key | Sitecore Documentation](https://doc.sitecore.com/personalize/en/developers/api/create-an-api-key.html). In my original article about creating New Developer Focused API Keys, I explored the potential of using the REST APIs—which I've incorporated into my SDK—to implement some of the use cases mentioned in the "Who is this for?" section. For now, let's focus on how to start using the client. You can use the code below as an example. While you might want to initialize the client using environment variables in practice, this example demonstrates the basic setup:

```typescript
import { Client, IClientInitOptions, RegionOptions } from "sitecore-personalize-tenant-sdk";

const clientOptions: IClientInitOptions = {
	clientId: "<Client Key Generated from Sitecore Personalize>",
	clientSecret: "<Client Secret Generated from Sitecore Personalize>",
	region: RegionOptions.US
}

const client = new Client(clientOptions);

// Now you can start using the Client
```

One nice feature of the client is that you don't have to worry about authentication—it's all handled for you. So if you want to get all the Web Templates from your tenant, you can simply run the following command. This will return a `Promise<IResponse<ITemplate[]> | undefined>`.

```typescript
import { IResponse, ITemplate, TemplateType } from "sitecore-personalize-tenant-sdk"

let templates: IResponse<ITemplate[]> | undefined = await client.Templates.GetAll(TemplateType.Web)
```

That covers the basics for now. I'll explore more use cases in the SDK documentation and upcoming blog posts.

# Testing Use Cases

Now that we've explored how to use this new SDK, let's discuss its potential applications in Sitecore Personalize for various testing scenarios.

## Unit Tests

This scenario is quite complex, as it's not directly about the SDK itself but rather how it enables a new workflow for building assets in Sitecore Personalize. Using the SDK, you could leverage a tool like the Serializer to implement a CI/CD process. This allows you to create code for Sitecore Personalize locally. You can then run unit tests on this local code to verify that your functionality works as intended. I'll delve deeper into this use case in future posts.

## Integration Tests

Integration testing verifies that the code you've written remains intact and functions as intended. The approach varies depending on the types of assets you're working with in Sitecore Personalize.

### Web Templates or Flows

What exactly can you test with a Web Template or Flow? The answer is somewhat complex. Ideally, you'd want to test the Experience or Experiment on your own website, but that's quite complicated and, to my knowledge, not currently possible. Instead, you may want to see how Sitecore Personalize renders the contents of your Web Template or the Experience/Experiment based on your inputs. I can confirm this is achievable and can be done with the SDK (which I'll cover in a future blog post). You can learn more about the available APIs here:

https://doc.sitecore.com/personalize/en/developers/api/preview-templates.html - This API allows you to test existing Templates. You can pass a friendly ID or ref for a web template along with template params, and it'll return a collection of HTML, CSS, and JavaScript output.

https://doc.sitecore.com/personalize/en/developers/api/preview-template-code.html - This API differs slightly from the one above. It lets you test the assets and template params before they actually exist, allowing for a final check in a local source control system before pushing changes to the environment.

Another crucial form of testing involves verifying that your local changes still align with what's been deployed to your tenant. This ensures proper governance and prevents customers or developers from making unauthorized changes directly in Personalize.

### Conditions

A Sitecore Personalize Condition is a newer concept, but it's essentially a type of template you can define in Sitecore Personalize. These conditions were designed to replace audience templates on Flows (Experiences and Experiments). They're probably the closest equivalent to XP personalization rules, though they don't fully replace that functionality. Conditions allow you to define small code segments that represent specific decisions you want to make. For instance, you could create a condition that determines whether the current session user is a Visitor or a Known Guest.

Integration tests for these conditions are available using the undocumented endpoint: `/v2/callFlows/testTemplate`. This endpoint accepts a specific set of parameters, enabling you to debug and verify if your condition's code works as expected in your environment. However, it's important to note that this endpoint doesn't function quite as you might expect. Rather than testing the template itself, it tests a flow and determines if it works based on the template it's using. One major challenge with this approach is that to test the integration of a Condition, you need a dummy experience to run this endpoint.

For Conditions, unit testing is likely your best approach. It allows you to test your code against mock data to ensure it performs as expected. However, the process isn't always straightforward. Sitecore Personalize uses ES5 syntax and requires a specific JavaScript format. Even if you write your code correctly locally, it might not work in Personalize. This is where integration tests prove valuable—they can help bridge the gap between local development and the Personalize environment.

### Decision Models or Decision Templates

When creating a Decision Model with Programmables or Decision Templates, testing individual components directly isn't possible. Instead, you must test the entire Decision Model. This approach, similar to Conditions, requires "dummy" decision models that incorporate your Programmables or Decision Templates. It's worth noting that JS Modules, which are only used alongside Programmables, can only be tested in this manner during integration testing. While this method is necessary for integration tests, I see value in running unit tests locally. These local tests can give you a general idea of how your components will perform before deploying them to an environment. The SDK includes a function called `TestDecisionModelVariant`, which accepts a guestContext object (I'll explain this further in my next blog post), a Decision Model Ref, and a Variant Ref. This function allows you to pass a custom Guest to your Decision Model Variant, enabling integration tests for specific outcomes.

### Conclusion

This concludes our overview of the SDK and introduction to integration versus unit testing for Sitecore Personalize. As mentioned throughout this post, I'll be releasing more content soon detailing how to use the SDK for specific integration testing scenarios. While it's still a work in progress, I plan to apply the SDK to the serializer and explore several unit testing scenarios. I'll also demonstrate how combining these with the Serializer can revolutionize your development workflow with Sitecore Personalize.

Hello

Latest posts

Sitecore Symposium Recap 2024

Revolutionizing Sitecore Personalize: Unleashing the Power of Generative AI Function Calling

Creating an Experience with the Sitecore Personalize SDK

Optimizely SaaS CMS vs Sitecore XM Cloud

Create Web Template and Flow Integration Tests with Sitecore Personalize

Introduction to Sitecore Personalize SDK and Testing