Exploring the Possibilities of Sitecore Connect and GraphQL Mutation: My First Steps

Before jumping into the use case for this article, let me briefly introduce two important concepts, this article would be based on. The fist one is GraphQL and It's mutation and another one is Sitecore Connect. Let's catch out what are those and how it can be used in our use case.

GraphQL mutation is important because it allows clients to modify data on the server. Without mutations, GraphQL would only be able to retrieve data from the server, but not modify it. Mutations enable clients to create, update, or delete data on the server using a single request.

This is particularly useful for applications that require real-time updates, as mutations can be used to push updates to the server and receive immediate responses. Additionally, mutations provide a more efficient way of updating data, as only the fields that have been modified need to be sent to the server, rather than the entire object.

On the other hand, Sitecore Connect, a middle ware, is a powerful integration tool that allows for seamless connections between Sitecore and other third-party systems. This tool is essential for businesses that rely on multiple platforms to manage their operations, as it enables them to easily exchange data and automate processes across different systems. With Sitecore Connect, businesses can streamline their workflows, improve data accuracy, and enhance customer experiences. Whether you're looking to integrate your CRM, ERP, or marketing automation system with Sitecore, Sitecore Connect is the solution you need to achieve a truly unified digital experience.

I just started exploring Sitecore Connect, when it officially included as an App into the Cloud Portal. As soon as I first saw it, I got curiosity on, how quickly I can make use of Sitecore Connect to do something nice in XM Cloud instance.

The first and simplest use case could be creating or deleting any Sitecore item. To achieve this, the obvious way is to use GraphQL Mutation. Delete (archive) operation is much more easier than creating an item as this need only one parameter which is the Item ID. So let's starting preparing the very first Sitecore Connect recipe to achieve this.

Prerequisites

To support our use case, we have to enable the Authoring query request for GraphQL and to do that, we need to follow below points.

1. In XM Cloud Deploy app,?create an environment variable?named?Sitecore_GraphQL_ExposePlayground?

And set the value as true.

Once you make any change into the environment variables, you have to initiate "Build and Deploy" by triggering the first action from Option drop down.

Automation Client

Next, We have to generate an automation client for an XM Cloud environment. You can enable custom tools and integrations to access your XM Cloud environment API by generating an automation client.

Go to the Deploy app https://deploy.sitecorecloud.io/ and from the menu bar of the XM Cloud Deploy App, click?Authentication Clients.

On the?Authentication Clients?page, on the?Environment?tab, click Generate, ?Automation client.

Once we get the Client ID and Client Secret, next step is to get the access token to pass it while making a call to GraphQL.

Get the Access Token

To authorize the GraphQL IDE or HTTP requests to perform operations against the Authoring and Management API endpoint, you must obtain an access token.

curl
--request POST?
--url "https://auth.sitecorecloud.io/oauth/token"?
--header "content-type: application/x-www-form-urlencoded"?
--data audience=https://api.sitecorecloud.io?
--data grant_type=client_credentials?
--data client_id=<REPLACE WITH YOUR CLIENT ID>?
--data client_secret=<REPLACE WITH YOUR SECRET>?        

To get the token, let's execute the curl command as mentioned above after replacing your client id and client secret in the last step.

To quickly execute curl command, i used this very useful application https://reqbin.com/curl

Paste the curl script into the left section and hit the Run button. If command gets successful execution, you should get status as 200 with access token in response back along with some other details.

Test the access token

Copy the access_token from response and let's continue to verify the access token using GraphQL IDE.

Open the GraphQL IDE with the instance url post fixed with /sitecore/api/authoring/graphql/ide/

This will look like below url

https://instance-url/sitecore/api/authoring/graphql/ide/

In the query section, pass the query like below.

query 
{
? sites {
? ? name
? }
}        

and add the authorization parameter in the header along with the access token we got from curl query execution in our last step.

{?
 ? "Authorization": "Bearer PASTE-YOUR-ACCESS-TOKEN-HERE"
}        

If everything goes well, you should be able to get response back as depicted above GraphQL IDE image.

Get the Item to be archived

Let's identify the item in Sitecore to be archived for our mutation operation.

Up to this step, we are all good to go for actual recipe creation in Sitecore Connect. So let's access the Sitecore Connect now.

Sitecore Connect

To access the Sitecore Connect, easiest way is to use cloud portal. The Cloud portal provides a front door not only for Sitecore’s tools but other tools as well.

On successful login, you should be able to see all available apps?along with Sitecore Connect. Just click on the app and open it into separate tab.

Here we go. This is the Dashbaord of Sitecore Connect, where it is showing the analytics around your recipes, jobs and connections.

Create a Project

Let's create a project first. A project is logical separation of all your recipes or connections.

Let's create a new project called GraphQLMutation

In my case, i had created a project SitecoreConnectTest and you can see the list of all recipes and connection under the this project i had created during testing.

Let's create a new recipe for our newly created project for our use case.

Create the recipe

A recipe is?an automated workflow that connects your apps. Each recipe is comprised of a trigger and one or more actions. When you turn on your recipe, it waits for a triggering event to run the actions.

Let's hit the Create action button from top right and select Recipe from dropdown.

While you are creating a new recipe, you also need to give the starting point for the recipe to define when this recipe should trigger itself, along with recipe name and the location (the project). To make it very simple, lets go ahead with default selection which is "Trigger form an app" and hit the Start building button.

Next, we have to tell the app from which we want to trigger the recipe. Select the Trigger from left pane and search for an app in the search box from right.

Again, to keep this very simple, let's configure a Scheduler to trigger the recipe. Search for the Scheduler and you should see the app called "Scheduler by Workato", select the app for further configuration.

Selecting this, you can define the time unit i.e. minutes and interval i.e. 15. Keep the default settings for the scheduler and continue for the next step.

Configuring an Action

To configure an action, just hit the + sign right below the trigger. You should see something like below.

From available actions, click on "Action in an app" and look for GraphQL from the right pane. If you don't see this app, start searching it from the search box.

The app will ask you to select a particular action you want to perform on GraphQL app as following.

Per our use case, we want to perform Mutation on the Sitecore Item, so let's select the "Mutate records" from the available actions.

Next, we need to select an connection for the GraphQL. If there is no connection previous made, you can create a new connection by clicking on "New Connection" link. Let's configure the connection now.

Setting up the Connection to GraphQL

For setting up connection to GraphQL, we need two main parameter values along with Name and Connection Type.

GraphQL endpoint: As we will be querying the GraphQL Authoring and Management API using the GraphQL, the endpoint would be different then usual. Per the documentation, below is the endpoint we will be targetting.

https://<your-instance>/sitecore/api/authoring/graphql/v1/

Access Token: This is the time, where we will be using the access token we got few steps back form the curl query response. Paste that token in the Header Authorization field like below.

And hit the connect button. If everything goes well, you are good to go for next step in the flow. If not, probably we need to execute the curl query again to get new access token.

Select the Mutation

Once connection is made, next step is to configure the Mutation type. There are multiple options available to perform mutation as you can see in the screen shot.

In our case, we are going to configure Archive Item. This would just need one single field to set and that is an Item Id, that we want to archive.

Setting up fields

We already got it while creating an item for this use case. Copy the Item ID from Sitecore content tree and paste it into the field.

That is it, Bit lengthy but very simple. Now it's a time to test the recipe we made.

Test the recipe

To test the recipe, you just need to trigger the Test button from top right action button.

You might connection error like below.

This means, your token has expired and you have to regenerate you access token again. To do that, you can simply trigger the curl command again mentioned earlier.

Execution Logs

For each test execution, you can see exactly what is being passed to the GraphQL endpoint as an Input, what was the Output and also Debug information for the request in the right section.

Check the Input

The input section, it is recording what was the exact data that was passed to the request in json format.

Check the Output

The Output section, we can see what was the Output of the operation we performed.

Check the Debug

And in Debug section, we can see the network trace with request method, response code and endpoint url.

Validation

As per the successful execution of the recipe, to archive the item in Sitecore, item should be removed from the content tree.

Let's check whether the item is deleted from the Sitecore or not.

Yupp. We can see that the item is no more visible there in the content tree and it has been removed from the instance.

Now the recipe is ready to be published and it will execute itself as per the scheduler configured.

I kept it very simple as it is my crawling phase on Sitecore Connect and Recipe but In the next article I am sure, we will go much more deeper with proper use case on Sitecore Connect.