Welcome back friends, today I’m happy to announce a new feature in Sitecore Personalize, which is a new capability of creating access tokens (JWT Tokens) for specific purposes.  To learn more about this release, check out this link here from the Developer Portal Change Log: [https://developers.sitecore.com/changelog/personalize/developers-can-now-create-api-keys-to-access-personalize-rest-apis](https://developers.sitecore.com/changelog/personalize/developers-can-now-create-api-keys-to-access-personalize-rest-apis).  Today’s article is going to spend some time reviewing exactly what this change means for developers.  Also, the new documentation pages for Sitecore Personalize include specific use cases for these new user-generated tokens: [https://doc.sitecore.com/personalize/en/developers/api/index-en.html](https://doc.sitecore.com/personalize/en/developers/api/index-en.html#UUID-ac90ff74-4b6e-95e6-3e15-aeba2d72db73).

## What are User Generated Tokens

So before we get into what they are, let’s talk a little about why they were needed.  Those familiar with the early days of the Sitecore acquisition of Boxever and the existing Boxever product are aware of the concept of a Key to rule them all.  This was a single key you would use for almost anything you desired.  Unfortunately this key also, with its broad scope, created many security concerns, because once you had the key, it was very difficult to reset it, because you only had one.  So if you reset the key, all your services that relied on that key would break at the same time.  Furthermore, the key was seen by practically everyone and that created issues when you had partners or developers working on your tenant, but when they left, they still had access to that token.  There were many issues with this approach and so that’s why there needed to be a better way of handling this.

This is why there is now a self-service interface to create tokens for specific use cases.  What is great about this approach, is that no one can see the key except for the developer/admin that created the key.  Furthermore, if that developer leaves the company or the partner that the developer works for leaves the organization, another developer/admin can create a new key, update the key for the automated process and then remove the old key with no issues with downtime during that process.  Also, these keys are no longer configured to do anything/everything with the product but are limited to specific use cases.  So if you are a developer and you want to configure automated unit tests (which I’ll get to a little bit more about in a second) you can now create a specific key for this specific purpose, which then locks that key from accessing `Guest Context` or `Templates` since the token that you’ve created is limited to a very specific use case.

Sounds great, so how do I use it?

## Create Your First Token

Before we get ahead of ourselves, there are some limitations, first off, this change specifically relates to Sitecore Personalize and only tenants on the cloud portal.  If you are an existing Boxever tenant, don’t worry, likely your tenant will be migrated to the Cloud Portal soon and then you can enjoy these new benefits of the product.

To get to create a new token, the steps are quite simple, you need to log in to your new tenant, which is straight forward because you can log in directly via the cloud portal: [https://portal.sitecorecloud.io/](https://portal.sitecorecloud.io/).  Log in using your cloud portal login credentials.  Once you are logged in, navigate to your Personalize tenant:

![](https://cdn.sanity.io/images/lanua4su/production/ea1ab7067018cd36b35bc57661a6c93d90640b72-1188x405.jpg)

Once you are in your tenant, it’s quite easy to start managing your API keys, you just need to make sure that your access role is set to either `Developer` or `Admin` roles.  To get to the new API keys section, you’ll navigate to the header part of the webpage (top portion of the web page) and you’ll hover over and click on `Developer Center` and select `API Keys` to navigate to this new page.  You should now see a list of keys generated by anyone on your tenant.  Keep in mind, you only have the ability to delete these keys, and once you create the key, that will be your only opportunity to copy the key to use for your purposes.  Let’s jump into the next section where I’ll cover the latest release of the Sitecore CDP (Personalize) Serializer version 1.8.0 and how you can create a key for the Serializer specifically.

## Sitecore Personalize Serializer

Those that are familiar with the content of this blog, are aware that last year at Sitecore Symposium I announced a Node-based Serialization tool for Sitecore Personalize, which uses hidden/lesser-known APIs that would allow a developer to store in a repository all their Sitecore Personalize assets (templates, connections, etc) and then build and deploy those changes using a CI/CD pipeline into Sitecore Personalize.  This announcement directly relates to this tool, because it now allows a user of Sitecore Personalize to create a token with the type of “Multiple Resources”, which will cover this specific use case (among others).

When you create your API key, make sure you give it a descriptive name, so that others managing the set of active API Keys have a better understanding of their purposes.

![](https://cdn.sanity.io/images/lanua4su/production/03ba6c5ad42c3486485cb8925608d444d7e4fe8c-613x454.jpg)

Also make sure to select the `Multiple resources` above, so that you can manage many different types of developer elements in the product.  Specifically, Multiple Resources include CRUD operations on Connections, Templates, Decision Models, Flows (Experiences and Experiments), Conditions, and JS Modules.  The only thing at the time of this writing that you can’t control with this access token is the ability to create Offer Templates, but hopefully, in the future, this will be improved/added as well.

Once you have your key, which consists of the Client Key and Secret, you’ll copy these values for future use.  You should never share these keys with anyone else, and where ever you plan to use them, such as a GitHub Secret or Azure Key Vault, you should move them directly to that location, so that the risk of someone getting access to those keys is minimal.

Recently I released a new version of the serializer, currently called `Sitecore CDP Serializer` however I’m considering changing it to the Sitecore Personalize Serializer since the serializer mostly deals with Personalize assets rather than CDP assets.  The latest version 0.2.1 includes a new parameter during the `auth login` where you would pass `-c` if you want to authenticate with Cloud Portal.  The authentication method with these new API Keys is completely different than the traditional [api.boxever.com](http://api.boxever.com) authentication.

```bash
> npx sitecore-cdp-serializer auth login -id "<Your Client Key>" -s "<Your Client Secret>" -l "US" -c
```

The new authentication uses Client Credentials instead of the password grant type moving forward.  So if you are building directly with the APIs keep that in mind.  With that change came another improvement within the product.  Prior to this release, if you made client credential changes, inside the Personalize interface you would see `Unknown` if you created elements that made it tough to determine who was making those changes, or really which API keys made those changes.  With this new release, however, it’ll now show the key’s name in the listing of elements when you make changes with a key:

![](https://cdn.sanity.io/images/lanua4su/production/5e3cabd9afb320d2cbd5c77e3b47fa500a0737e7-1454x266.jpg)

## Additional Use Cases

In addition to using it with my very own tool, the serializer, there are actually quite a lot of useful use cases that could make sense here.  I wanted to provide a few details about those below, with the hopes that I’ll create further content on these in the future.

### Unit Testing / Automated Integration Testing

This is actually the use case I had originally planned to create a video to talk about but haven’t been able to prepare that video by the time of writing this content.  Sitecore Personalize provides a great way to create tests of various decision models, detailed in this guide here: [https://sitecore.cdpknowledgehub.com/docs/decision-models-automated-testing-guide](https://sitecore.cdpknowledgehub.com/docs/decision-models-automated-testing-guide).  That guide is great although is even greater now if you create a new API key with the Feature of `Decision model testing` selected.  Now you’ll be able to create a key specifically for your use case.  I would recommend only selecting that option if it’s the only thing you need to do.  If you plan to deploy your decision models to a tenant and then test, then you’ll likely want to select `Multiple resources` because otherwise you’ll need two keys and need to authenticate twice.

### Other Automated Use Cases

Another great use case for these new REST APIs and the API keys is to use them to create use cases on the fly.  If you have an external system, that you’d like to use to create an `Experience` or a `Decision Model` based on something in your system, this would be now a great way to achieve this.  One use case I think would be extremely valuable at some point, is to create a Generative AI example, of creating experiences/experimentation on the fly.  Definitely hope to cover this use case in the future.

Well that sums this up, if you haven’t already, you should plan to check this feature out today and write a blog about your specific use case!

Sitecore Personalize: New Developer Focused API Keys

For those that did not read my first blog post: [https://dylanyoung.dev/insights/sitecore-cdp-personalize-capture-additional-data-in-a-view-event/](https://dylanyoung.dev/insights/sitecore-cdp-personalize-capture-additional-data-in-a-view-event/), I covered the topic of adding additional details to our View Event when someone navigates our website, and in this blog post I’m going to take that information further and show how it can be useful to make smart decisions for experiences that we may be trying to create.  In our example, I wanted to capture additional page information, and include the Sanity unique identifier for the pages that the user is visiting.  This then allows me to pull details of that page into the decision model and make a judgment about what kinds of information that user may be looking to find on our website.  The quick overview is that because the user in the last session or even the current session is looking at Sitecore CDP/Personalize content, we might want to suggest in various parts of our site, hints into other content they might want to see on that same category.  This blog will take a step closer to that goal, and then later we’ll start to explore even more complex decisions, potentially using AI as we try to understand the user and what they are viewing and how we can use that information to guide the user to what they might be really looking for on our website.

## Using Sanity ID in a Decision Model Programmable

So the next part of this exercise, now that we have been collecting this additional information for some time, is to start working on creating an experience to display based on information that we will pull and parse in our Decision Model.  The first step to getting to that point will be to access this guest’s session data and their Sanity ID for their last visit.  I wrote the code below that can help us achieve that:

```javascript
function getLatestSessionEvents() {
    var lastSanityId = '';
    
    for (var i = 0; i < guest.sessions.length; i++) {
        var currentSession = guest.sessions[i];
        
        if (currentSession.sessionType === 'WEB') {
            var events = currentSession.events;

            for (var j = 0; j < events.length; j++) {
                var currentEvent = events[j];

                if (currentEvent.type === 'VIEW' && currentEvent.arbitraryData && currentEvent.arbitraryData.ext.sanity_id) {
                    lastSanityId = currentEvent.arbitraryData.ext.sanity_id;

                    break;
                }
            }
        }

        if (lastSanityId) {
            break;
        }
    }

    return lastSanityId;
}

(function () {
    var lastSanityId = getLatestSessionEvents();

    return lastSanityId;
})();
```

The code above is using the data that we stored from our last blog on this topic, to pull that information out and then return the ID if there is one.  Now I’ll admit that just having the ID of the article last visited, isn’t all that special, but we’ll combine that with a `Connection` to our Sanity CMS to get back additional information about that page in a second so that then we can make decisions with that information.

We are obviously skipping some details with that script.  Before we get to writing our programmable, we’ll need to also configure our Decision Model and then the Programmable that this code will go into.  So let’s start by defining our Decision Model.  That is pretty straightforward, as you can navigate to your Personalize tenant and click on `Decisioning` and then `Decision models` and then finally click on `Create Decision Model` and provide your decision model a valid name so that you can begin creating our first decision model.  When you first create that decision model, you’ll land on a page that appears to have different swim lanes or columns that represent the state.  Unlike anything else (currently) inside Personalize, creating a decision model consists of variants, which those variants go through the workflow.  What’s great about this workflow, is you wouldn’t want to have a decision model in production that needs tweaking and run into a scenario where you must stop that decision model in order to work on it.  Especially considering that a decision model could be used across **many** experiences or experiments.  So with our first one, we’ll create a variant, which we’ll also give a name.  I think generally a best practice here is to give your variant a form of version so that you can keep track of what named version is in production and what is in testing/draft.  For example, imagine later on in this world of decision models where you might have primary v1 in the `Production` state, while primary v2 is in Test, and even maybe primary v3 is in the draft.  That can be a pretty powerful process so that you never have untested variants running in production at any given moment.

Anyways enough of that let’s get into creating our variant, click on `Add Variant` and give our variant a name, I’ll call mine `primary v1`, but you are welcome to give yours any name that you see fit. Once you have your variant created let’s go ahead and click on the little card that it created now sitting in the draft state.  Keep in mind, if you had been creating a new variant with others already existing in this decision model, you could’ve had the variant created from an existing variant, but like I said we’ll cover that at some point in the future in another blog post.

## Creating Our Decision Model Variant

![](https://cdn.sanity.io/images/lanua4su/production/4325f2d8682e45e9175ad2c49a18656b8fb246a3-1264x1321.jpg)

So we are starting with the blank variant shown above, but what we actually need is to place the programmable where we displayed the code above.  When you place the programmable, you must give the programmable a name, output reference, and the type of output reference.  This is so that we can then use this information later (such as in the Connection to an external Data System that we’ll talk about shortly.  For our programmable, I’m going to return a string, because the Sanity ID is alphanumeric, and the output reference will be called “SanityId”.  The programmable name is irrelevant, just call it something meaningful to you, so you know what this programmable is doing.  Now we are ready to drop in our code.  In a future blog, I’ll create some more content on exactly how you would come to write something like this.

Another gotcha for me was realizing that when creating that programmable, I do not need to specify the input data blocks above to pass that data to the programmable, we can just access the `guest` and its `sessions` and `events`. The only thing to watch out for is to make sure you are using the singular or plural form correctly.  Once you’ve dropped the code into your programmable, you can now test the canvas to make sure it’s working.  Obviously, at this point, you must complete the details in the first blog, or else, you’ll have nothing coming back, but once you have the programmable code dropped in, plus the first blog contents complete, you can now navigate back to your blog/website, and navigate the site.  Collect your `browser_id` from your site or even collect the guest id by following the contents of this blog, where I show [how to get the guest id from the Google Chrome console](https://dylanyoung.dev/insights/getting-the-guestref-in-the-browser-with-sitecore-cdp-personalize/).  Once you have that, you can navigate back to your decision model, the correct variant, and the programmable that you created, and then click on `Test Canvas`, and instead of selecting a known guest, paste in your guest ref.  It has to be the guest ref and not the browser id, also make sure you have visited a page that would’ve logged a view event with the arbitrary data about that page content id, and make sure the code you used in your programmable matches what you used in your arbitrary data in the `View` event.  Now click on `Test Canvas` and you should see something like this:

![](https://cdn.sanity.io/images/lanua4su/production/30c711a2a795b338d5d67aa2b4a98db6aa6bf3c0-822x456.jpg)

As you can see our programmable is succeeding.  If you have any `print()` in your code (which in my version we don’t), you will see more details in logs, which we’ll talk about more in detail in a future blog post.  You have at least two ways to see the output of this test, first, you can click on the little arrow that points left in the screenshot above, next to the test, which will show the result of the test.  The second is by clicking on `Full Response` which will show all the details of what was run and what was returned, including in this case the `Sanity ID` for this test.

## Extra Credit

For today’s post, this will conclude with how to use the data that we are tracking in a programmable, but in my next post, I’ll show how to use this information to pull the post from Sanity.  As I’ve previously mentioned, this could also easily be done using another CMS like Sitecore XM Cloud or Content Hub ONE, which I may do a mini-series into at some point.  But before we wrap up for today, there is one last bit to this exercise that I want to bring up.  Look at our screenshot of our Test of our programmable, and there is a timing of how long are test took to run.  This is important to keep in mind, because these run server-side in Sitecore Personalize when you’re navigating a page on your site, to determine if this experience that is using this decision model variant should run.  It’s vital that these decision models are built to run as efficiently as possible, which we’ll look into more next time because we’ll be calling into a second system.  You should always consider how important is it that this test run will show a personalized result?  If for some reason we call into another system and that system takes 10 seconds to return a result then that’s unacceptable and we should look at alternative ways to add this capability or cut the connection off if it’s taking too long to respond.  So just wanted to call this out before I close out this post.  

Thank you and see you next time!

Part Two: Using Extended View Event Data in a Sitecore Personalize Decision Model

I’m currently working on a real-world use case for this blog, to fully demonstrate how to create a real decision model (and why you would do so with Sitecore Personalize), and in that journey, I have found that I need to collect more data about the pages that users visiting my website are viewing.  The goal is to use this data, to make educated guesses about what kind of content they would like to see more of in the future.  For example, if the user comes in and looks at CDP/Personalize content, there is a decent possibility they want to see more content in the future.  For now, this is a simple use case, one which we will build upon in the future.

## The Specific Use Case

The goal that I’m hoping to achieve is to track these blog posts, which are being driven from the CMS, in my case I use Sanity IO as the CMS, but in theory, this approach could be used by any CMS system including Sitecore XP or XM Cloud.  Ideally, I want to track the page and additional schema information about that page to display full-stack and/or web experiences in Sitecore CDP/Personalize from those views.  The specific use case I’m thinking about now relates to a recent change I made to my home page, which now includes categories of blog posts.  I want to store in addition to a page view, additional metadata about the page.  I could theoretically have it store category information or tags directly, which theoretically could save me an additional request to an external system in my decision model (but that’ll be a blog post for another time), but instead, I want to just store the sanity unique identifier, that way no matter what data I need at any point now or in the future, I can do that without any extra fuss.  Storing the category or something arbitrary could work, but what if I add additional details (such as persona attributes to each of the articles, etc) to that item in the future and want to use it to make decisions?  Well with storing only the ID and using a connection during the decision model process, I’ll be able to cover future use cases easily.

Also before I jump too deeply into this topic, I wanted to mention that this covers the existing CDP JS library and not the new Sitecore Cloud SDK with Engage modules that I recently covered in this video: [https://www.youtube.com/watch?v=LdxNRo22Vf8](https://www.youtube.com/watch?v=LdxNRo22Vf8) on Discover Sitecore.  I will have more content coming up on that topic in the coming blogs.  

## Custom Event vs View Event

How should we store this additional information?  This led to a dilemma because there were essentially two different ways to achieve the same outcome.  But the custom event had some major drawbacks including an additional request to the stream APIs which would lead to even more code needing to be written to achieve the same thing.  Plus we really wanted the View of the page to have those additional details.  We could’ve potentially created a meta event or something to track the additional data, but then it’s not specifically tied to a view event.  It was decided that the View event was the right decision.

The complexity with the View event is that you need a way to store the extra data, and turns out Sitecore documentation calls out two different ways to do this.  There is a way to pass in [Session Data with additional attributes](https://doc.sitecore.com/cdp/en/developers/sitecore-customer-data-platform--data-model-2-1/send-session-data-to-the-sitecore-cdp.html), as well as [passing extension data with attributes](https://doc.sitecore.com/cdp/en/developers/sitecore-customer-data-platform--data-model-2-1/send-additional-event-data-to-sitecore-cdp.html).  However, with both methods, the documentation examples are a little unclear, made worse by the fact that if you have Sitecore CDP with the Guest Profile dashboard, and you are viewing the page events, it just tracks the page on the default view, without the additional information.  Furthermore, it’s unclear which of these approaches is the better choice and why, so I had to make sense of it, and provide a response below about what I chose to do and why.  Later in a future blog, I will walk through using these attributes in a decision model and potentially other use cases.

Let’s start by taking a closer look at both of these options, the code that is required, and how to view the data within CDP.  Keep in mind the code below, isn’t the full story here because I’m avoiding the initialization of the CDP JavaScript library.  For information about adding that, just refer to this reference in Sitecore documentation: [https://doc.sitecore.com/cdp/en/developers/sitecore-customer-data-platform--data-model-2-0/javascript-tagging-examples-for-webpages.html#activating-the-boxever-javascript-library_body](https://doc.sitecore.com/cdp/en/developers/sitecore-customer-data-platform--data-model-2-0/javascript-tagging-examples-for-webpages.html#activating-the-boxever-javascript-library_body).

### Using Session Data Attributes

This is quite simple, and really just requires passing in any additional attribution with a custom object with Session data:

```javascript
function sendCustomPageEvent(page: string, attributes: any) {
    if (!window._boxever) return;
    window._boxeverq.push(function () {
        let customPageViewEvent = {
            browser_id: window.Boxever.getID(),
            pos: window._boxever_settings.pointOfSale,
            channel: window._eventSettings.Channel,
            language: window._eventSettings.Language,
            currency: window._eventSettings.Currency,
            sessionData: {
                attributes
            },
            type: 'VIEW',
            page: page
        };

        customPageViewEvent = window.Boxever.addUTMParams(customPageViewEvent);

        window.Boxever.eventCreate(customPageViewEvent, function (data: any) {}, 'json');
    });
}
```

I created this as a function so that I could reuse it for various purposes later.  My code base is also using TypeScript/React/Next.js so disregard the typing information in the function if you are using vanilla JavaScript.

Really the important part here is the `sessionData: {}` which allows you to now pass in arbitrary session data for what I assume is the current session.  It’s a little unclear if this just tracks this to the session data or just the event.  In our case, that is unclear and really we want to make sure these attributes are only to the current event in the current session (which leads to why I chose to go with the next option below).  To view this data inside CDP, there is a really good way to do this.  You’ll first want to go to your browser and type in `Boxever.getID()` as I’ve covered in other blogs in the past.  Then navigate over to your CDP tenant, click on Guests under the `Customer data` section of the navigation, and type in `bid: {id}` from the command in the console above.

![Click the Eye next to a triggered event to view the JSON data of that event.](https://cdn.sanity.io/images/lanua4su/production/115f5f047f5f3a0777210f9fdd896732ae95e427-1360x1087.jpg)

### Additional Event Data

So the second option, which is the option I opted for with my own implementation, looks like the following:

```javascript
function sendCustomPageEvent(page: string, attributes: any) {
    if (!window._boxever) return;
    window._boxeverq.push(function () {
        let customPageViewEvent = {
            browser_id: window.Boxever.getID(),
            pos: window._boxever_settings.pointOfSale,
            channel: window._eventSettings.Channel,
            language: window._eventSettings.Language,
            currency: window._eventSettings.Currency,
            ext: attributes,
            type: 'VIEW',
            page: page
        };

        customPageViewEvent = window.Boxever.addUTMParams(customPageViewEvent);

        window.Boxever.eventCreate(customPageViewEvent, function (data: any) {}, 'json');
    });
}
```

As you can see, there really isn’t a huge difference in how this data is stored, the difference is that I think this method is meant for Event data vs the other option having the hard-to-comprehend `sessionData` attributes, where I don’t want multiple session data with the same attribute values.

The big difference with the above is just the new attribute of `ext: attributes,` added where you can send a custom object to that `ext` attribute. 

To view this information, there are a couple of options, but I like seeing the data input via the Event Debugger:

![Click the Eye next to a triggered event to view the JSON data of that event.](https://cdn.sanity.io/images/lanua4su/production/e153a2bac758411624de3177b348d6ab87d5146f-1370x1086.jpg)

### Conclusion

To summarize, there are some great ways to store additional attributes in Sitecore CDP, and I opted for the path which allows me to track per event trigger.  In my use case, I wanted to track additional metrics about the pages that the user is navigating through and we’ll discuss in my next blog how that information is useful in a decision model to determine the next best action for a user.

Capturing Additional Data in a View Event in Sitecore CDP/Personalize

Well, I have wrapped up from Sitecore Symposium last week.  Not fully recovered, but I wanted to blog about the topic for my session at Sitecore Symposium 2022 in Chicago.  Now the topic that I did, was on Developing for the Engagement Cloud, but one of the topics I covered that I want to talk about/recap here today, is the PoC (Proof of Concept) that I had built for this presentation for CDP/Personalize.  This PoC was meant to show a new and I will admit better way of building things in your tenant, using the tool that every developer is familiar with, which is Source Control.

## Where Did This Idea Come From

So a couple of months ago, I was told about some APIs that could be used for migration.  Now after exploring these APIs I realized they only covered a few specific use cases and that there was a greater need.  At the time, I knew that customers were delivered a UAT and a Production tenant, but everything was manual to move items between those environments.  However, the APIs that had been delivered was only for Decision Models, and not for what I considered developer tasks (I think this is a larger discussion for another blog post in the future).  So I started to dig in and research if there were any more APIs that could be used to solve my challenges.  This is when I stumbled upon a set of APIs that are being used by the frontend application of the tenant, but these same APIs are not currently documented anywhere.  These APIs are very powerful, and open up the door for a bunch of different use cases:

- Using Source Control
- Migration
- One-Off Accelerator Deployments

## What are these APIs?

As I just mentioned they are not currently in the official Sitecore documentation.  I’ve worked to try to determine why that is, and it’s simply because the APIs aren’t officially supported by Sitecore currently.  But does that mean you should avoid them? I don’t think that’s the case, and in fact, they open up and allow for automation scenarios that are too great to ignore.  So how do you find out about these APIs?  Well, it’s quite simple, if you log in to a CDP/Personalize tenant, open up `Chrome Tools` and view the network tab, you’ll notice as you interact with the interface, there are a lot of interactions taking place asynchronously, including with all of the APIs that I’m describing today.  Now I’ve spent some time documenting what I’ve found here and created a very rough draft Swagger document of these APIs: [https://dylanyoung-dev.github.io/sitecore-cdp-personalize-api-spec/](https://dylanyoung-dev.github.io/sitecore-cdp-personalize-api-spec/).  Just keep in mind that these are unofficial and something that I’ve personally spent time creating.  These undocumented APIs are listed under `Tenant Management`, this isn’t an official name for these, but these are the ones that are taking place in the browser.

## How to Start Using these APIs?

Okay, so now you know about the `hidden` APIs, but what do you do with them and how do you start using them?  Well, the first major hurdle you’ll deal with when using these APIs is authentication.  It’s different from the Batch, Stream, and Interactive APIs that you would typically use to ingest data to CDP/Personalize.  These APIs use OAuth to handle authentication, and there are two core ways to authenticate and get back the access token that you’ll use as a bearer token in the rest of the API requests.  There is the `password` grant type, which is where you would use your username and password for the tenant, to authenticate to use these APIs.  The problem with this approach is that if you have Multi-Factor Authentication (MFA) enabled, which is likely the case in a production environment, then you’ll need to pass in your MFA code as well.  This presents issues when you are trying to have a system run an automated process, such is the case during CI/CD DevOps deployments.  The second method is the preferred method of using `client credentials` grant type, which will use the `Client Key` and `API Token` from the API access panel in your tenant:

![](https://s3.us-west-2.amazonaws.com/secure.notion-static.com/2654d617-7be6-4274-86d0-7d1d7deee1e3/API-Access-panel.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221028%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221028T174406Z&X-Amz-Expires=3600&X-Amz-Signature=615258348bbed9cbb22f0ee8aeec7c0b6a32e798ec47e5b177155af88a07ef8f&X-Amz-SignedHeaders=host&x-id=GetObject)

## Proof of Concept

So let’s talk a little more about the Proof of Concept (PoC) that I worked on that utilizes the APIs above.  I had this crazy idea in my head, maybe 6 months ago, that source control could be used instead to create and control the flow of various assets to a specific tenant.  Something like the diagram below was what I was envisioning.  At the same time that I was dreaming up this new approach, the product team was talking about how it would be nice to test these further, but in my mind, how do you just test a tenant’s assets directly?  I didn’t think the use case of randomly testing what was there, really made sense, and I thought it would make much more sense in a DevOps flow, where before you deploy to a tenant, you run unit tests and confirm they pass before you deploy, and then Automation tests could be done post-deploy to confirm if the changes were deployed successfully.

![](https://github.com/dylanyoung-dev/cdp-personalize-examples/raw/main/docs/images/Using-Source-Control.jpg)

Now as of this writing, I have only some simple examples of Unit Testing, and no examples of how to handle automation testing, but rest assured, that is the next part of what I’ll be working on next.  I now have two repositories that I’ll describe and link to below, but the serializer application needs to be broken apart into the SDK parts for calling the APIs, and then I should be able to share the Automated Testing scenarios utilizing that SDK.  So more on that to come.

But before I get into the projects, just wanted to describe the illustration above.  Simply put, a developer will no longer develop their changes directly in the tenant and instead will set up a repository with the serialized assets that they would build locally, and then there would be a process to deploy those changes to their tenant.  That’s where we would get into the repositories and their use cases.  Today all the examples use GitHub and Mocha for Unit testing, but my intention is for this PoC to be tech agnostic, so if you wanted to deploy changes, you could use Azure DevOps or GitLab, or any other Source Control Management system.  I plan to create a lot more content coming up on different scenarios that could be done for this PoC.  But with my PoC it is meant to be a community project, and thus all the repositories below are open source and I suspect will get way more traction as the community builds them out and other scenarios that these APIs can handle.

## Serializer Repository

This is the brains of the operation and where all the magic happens.  It takes everything that is in physical form (in a source control repository) and moves that (via a `deploy` command) using a Node CLI and moves that to a CDP/Personalize tenant.  Currently, the PoC that was originally created only includes examples for Decision, Audience, and Web Experience templates, but the plan is that it really should support anything that you would create in your tenant directly.  I always like to build things like this, to be unopinionated as possible, so those teams that have specific use cases should be able to handle their specific use cases using the same project.  So for example, if your organization is structured in a way where everything is done by developers and directed by a marketing team then your developers can configure as much as they desire in Source Control and have those assets deployed to their tenants.  Another use case, which I would assume is likely more common is that only certain assets are considered `developer` assets, such as templates, and then only those assets are in source control, while everything else falls outside of that and can be freely created in Source Control.

GitHub Repository: [https://github.com/dylanyoung-dev/sitecore-cdp-serializer](https://github.com/dylanyoung-dev/sitecore-cdp-serializer)

Available on NPM: [https://www.npmjs.com/package/sitecore-cdp-serializer](https://www.npmjs.com/package/sitecore-cdp-serializer)

## Examples Repository

This is the repository that shows how all this comes together to achieve the diagram above.  Now it’s opinionated because it uses a specific set of technology, such as Mocha and Super test for Unit/Automated tests and it also uses VS Code and GitHub Workflow for CI/CD deployments.  But it’s really easy to either create a template from this project and start creating it based on your own scenarios, or it’s also configured as a `template` repository, so when you land on the link below, you can click on `Use template` and you can start building based on this repository for your scenarios today. 

GitHub Repository: [https://github.com/dylanyoung-dev/cdp-personalize-examples](https://github.com/dylanyoung-dev/cdp-personalize-examples)

## Extra Credit

So all of this is great for customers but this opens up a new world for the community or partners that want to build out starter kits or accelerators for a specific industry.  For example, partner A builds experiences all the time for specific verticals like energy or health care, and could now use this strategy to either build a bunch of items for a specific industry so that those customers can get off the line faster.  Now I don’t have any specific examples of this today, but I challenge the community to contribute to these projects and start to create out these use cases.

Introducing Sitecore CDP/Personalize Serializer/CLI Tool

This week there was a question on the Sitecore slack, about how to recover a previously deleted experience/experiment.  It was pretty clear that the experience/experiment was still there, because when you tried to create a new experience/experiment with the exact same friendly id, it wouldn’t allow you to create the experience/experiment with that same friendlyId.  I had seen this before when working on my POC for Sitecore Symposium, that typically Sitecore Personalize will actually archive an item, instead of deleting it.  From my understanding, this is done to preserve analytical data that may have been collected about that experience/experiment.  However the UI doesn’t give the user any way to recover an archived experience/experiment.  It’s also, nice that it archives the item, instead of deleting it, because it makes it easy to recover the item at any point.  But in the UI it can be frustrating, if you wanted to use the specific name for an experiment/experience.

## APIs to the Rescue

Luckily during the work on the POC, that I’ll be introducing at Sitecore Symposium and on this blog in a few weeks as well, I discovered a bunch of kind of like management APIs for the tenants assets, which will come to the rescue in this case.  Now as of today these are not currently documented anywhere, except for possibly these [connection APIs](https://doc.sitecore.com/cdp/en/developers/sitecore-customer-data-platform--data-model-2-1/sitecore-cdp-connection-functions-rest-api.html), but unfortunately they don’t fully explain authentication, because authentication is different when working with this new set of APIs.  It uses oAuth to authenticate against `/v2/oauth/token`.  There is really two primary ways (grant types) for authentication to this API, but the result is the same, to get back a JWT access token that you would then use with additional endpoints.  To start authentication, I’ve provided a [Gist of a Postman collection](https://gist.github.com/dylanyoung-dev/8aa265cdc5c2d51810663886db3fd112) with the three authentication endpoints that I’ll detail below.

### Password Grant Type

The password grant type method, allows you to use your own CDP/Personalize username and password to authenticate to the tenant.  You will get back an access token and a refresh token.  The refresh token can be used with the Refresh Token endpoint that I also provided in the postman collection.

There is one challenge with this type of grant type, and that is MFA (multi-factor authentication).  If your tenant is a production tenant, it will likely require MFA, and in that case, you’ll have to pass the `code` parameter, with the value from your MFA device, in addition to the username/password combination.  That may not seem like a challenge, but it would be, if you are hoping to use this login to automate functionality, which was the case in my Sitecore Symposium presentation and POC.  

### Client Credentials Type

The second type of authentication is using client credentials which is very similar to the REST APIs used for ingestion, except you would pass these to the same `/v2/oauth/token` endpoint to get back a JWT access token.  Now that is all you will get back, there is no refresh token when using this method.  But the great thing about this grant type is that even if your tenant requires MFA, it does not require it with this grant type.  So if you want to achieve automation in some form, this is the grant type in a lot of cases that you’ll be looking for.

There are some issues, which are getting fixed, with this grant type.  The biggest is that this grant type doesn’t always work for all of the endpoints I’m about to talk about, including today’s Experiences and Experiment (Flow) endpoints.  But there are plans to add support for this grant type in the future for those APIs that throw errors when using this grant type.

## Using the APIs to View Our Deleted Experience/Experiment

Now that we’ve explained how you can authenticate, now we need to start querying data to see what information we have access to.  We’ll focus more on the topics of today’s blog, since there are many other APIs that can be used to achieve very many things.  I’ve created the following [Postman collection for these Flow APIs](https://gist.github.com/dylanyoung-dev/107afa7582739b291847191359937f19), that we’ll use in the next few paragraphs.  Before we get to far, at a minimum you will need to know either the `friendlyId` for the item you deleted, or its unique GUID.  I find it’s quite useful in most situations, to use the `friendlyId` since that uniquely identifies our items.

The first thing you’ll want to do is run a `GET` to Retrieve Flow Definition, which is at `/v3/flowDefinitions/:flowDefinitionId`, as previously mentioned, the flowDefinitionId can be its GUID or a `friendlyId`.  When you get the result set back, you should notice that you are being returned your deleted item, and that it’s set to archive: 

![](https://cdn.sanity.io/images/lanua4su/production/a7d389b354fbe787614cfcc02efd8fcdbfb3c7fb-1286x1031.jpg)

All we need to do, is use the `PUT` request (Update Flow Definition) that I provided in the Postman collection, by providing the `flowDefinitionId` which is like before, either the GUID or the `friendlyId` for the flow (Experience/Experiment) in Sitecore Personalize.  And then in the body, we’ll copy the contents of our `GET` request earlier, and inject those into the `BODY` as JSON.  Then update archive equals true, to now false.  Then run the request, and upon success, refresh your browser, you should now see the item in the UI.  Because the item was archived the name of the flow is now showing the previous name plus archived with a time stamp.  So if you are planning to use this existing flow, then you’ll need to ensure that you remove that name and update the flow to match your use cases.

## Additional Consideration

It’s important to note that this is a way around accidently deleting a flow (experience/experiment), but there may be other risk factors that aren’t entirely clear at this point.  You should do thorough testing to ensure that your experiment or experiences are working as expected after an item was archived.

Also these APIs described above are not in Sitecore documentation.  There is work to get them added, and once documentation is available I’ll include links to the documentation.  Also I've created an unofficial [Sitecore CDP/Personalize API Swagger reference](https://dylanyoung-dev.github.io/sitecore-cdp-personalize-api-spec/) that you can view on GitHub, that I'll likely use in future blog content.

Sitecore Personalize: How to Recover an Archived/Deleted Experience or Experiment

As the excerpt described, I have been working on a video for the Discover Sitecore YouTube channel related to Sitecore CDP/Personalize with the use of Real-time, also referred to as the Stream APIs typically used by the Sitecore CDP JavaScript library to track events in the browser.  Technically by using the API’s I am in essence mimicking the behavior you might trigger if another system wanted to track behavior such as a Mobile application or maybe even a third-party system.

As was the case with Sitecore XP, it was always great if you could kill the .NET session, especially when you wanted to test the output of something you might be demonstrating to a customer in real-time or content for a video/blog.  Unlike in the days of the .NET development and the .NET application with XP, where you might need to build a custom admin page that you could call while logged in to kill the session, in the realm of Sitecore CDP, you have a way to do this at any point, as long as you have a Browser Ref.  In a previous blog topic on my blog about [Getting the Guest Ref from the Browser Ref](https://dylanyoung.dev/insights/getting-the-guestref-in-the-browser-with-sitecore-cdp-personalize/), I talked a little more about these different references.  So you could theoretically kill the session at any point for the user by writing some JavaScript, but I’ll cover today how to do this using an API request using Postman.  You might be in the middle of a demonstration like I was when creating the YouTube content, and need to show the browsed session versus the open session in Sitecore CDP (keeping in mind that CDP is the only way to view your guest data).

I’m going to show this in postman, but anything could work here to make these requests including CURL.

You can view the postman request script here if you would like to import this into Postman: [Gist Postman Script](https://gist.github.com/dylanyoung-dev/021d15d6662bca74635624c474a72866).

Or you can just refer to the screenshots below.  You’ll need to create an environment for your specific Tenant of CDP/Personalize and then you’ll need values for the following:

- API Endpoint - This is for your region such as `api-us` if you are accessing a tenant in the US
- ClientKey - This is the public key for accessing your tenant.
- Message - This should be left blank and filled with your pre-request script details
- POS - This is the point of sale that you specified earlier when you set up your tenant and start ingesting data.
- Browser ID - This is a variable that you should’ve defined previously.  Such as when you created the session you would want to store this Browser Ref for future requests, however, if you just want to use an arbitrary value, that can be done as well.

![Includes Request Details to Close or Kill the Session in Postman for Sitecore CDP/Personalize](https://cdn.sanity.io/images/lanua4su/production/add1b2d9c611e2f511ee150b789fdef64bb00e99-950x570.jpg)

![Includes details for the creation of the {{message}} variable for the request in Sitecore CDP/Personalize.](https://cdn.sanity.io/images/lanua4su/production/495fa4382aa50c85a8ede42e2c49bb7734b60c82-950x570.jpg)

Closing a Session in Sitecore CDP with the Stream API Using Postman

A quick little post as I'm playing around with Sitecore CDP/Personalize.  I've been playing around with the API's to get guest data.  But I found that if I run this command in the developer console:

```
Boxever.getID()
```

This returned ID, is not the same thing as the Guest Ref, it's actually the Browser Id, and typically associated with the Cookie.  You can use this ID inside your CDP/Personalize tenant and get the Guest Ref, but I've always found this a little confusing.  It's funny how it all makes a little more sense now.  When you search in the CDP/Personalize tenant with the Boxever Browser ID, it'll show a different ID in the Guest Profile, than you would expect to see.  I just wrote this off and thought it could be a bug.  But actually, this ID is the Guest Ref:

![Boxever.getID() vs guestRef](https://cdn.sanity.io/images/lanua4su/production/9eb08025c17dafead05f3909f717a82dc2a45a4a-1232x647.jpg)

Now that I finally know that these are two different things, what if I wanted to get the guestRef from the browser.  There is a way, and I found this from [Sarah O'Reilly](https://sitecore.stackexchange.com/a/30991/1000):

```
Boxever.browserShow(Boxever.browser_id, Boxever.client_key, function(data) 
{ 
  console.log(data)
}, 'json');
```

Why do you need the guestRef? Well if you plan to do anything with the APIs, you'll need to know the guestRef in order to interact with them.