Skip to main content

XM Cloud - 10 Steps Of GraphQL Mutations Using Authoring APIs and Troubleshooting

 

Well, well, well

Believe me it's been tough getting my understanding around all the dots which we need to connect to make the GraphQL IDE to work, and top of it execute a successful query via it.

I am writing this blog to show what all troubleshooting i did, Couple of mistakes which i found, some new things that i had to learn along the way to make it work, Different types of APIs, and their meanings, like Preview API, Delivery API, Token API, Admin API, but all in summary, after this blog, i am sure no one should land into the issue like i did, that is the purpose.

NOTE: When you start reading out the documentation for the first time, there will be lot of confusions around what are all these APIs, and which one to use when? Different headers for different APIs, I will have a different blog explaining all of them but specially when you are working with or if you have questions around Authoring API, It is different because it does mutation operations against Sitecore CM, for CRUD operations, and other APIs like preview and delivery are to query against experience edge (GET only), This is the basic understanding you should have.

I am assuming that you already know what is GraphQL and how it is being used along with Sitecore as a new way of fetching data, i am not going to explain that because the scope is different but believe me i knew nothing about GraphQL and its syntax and where to write it, but its all part of learning that had, but i will quickly jump to the steps and issues that you will land in while trying to make GraphQL work.

Steps

We all start with the documentation which is available right? So on Walkthrough: Enabling and authorizing requests to the Authoring and Management API (sitecore.com) the steps are given and URL for IDE etc.

1) First confusion is which is the correct URL to hit in a browser, because i found two but thankfully both when hit in the browser, redirects to the same URL, Following are correct URLs you can use to open IDE

https://<<your xm cloud CM host>>/sitecore/api/authoring/graphql/ide
https://<<your xm cloud CM host>>/sitecore/api/authoring/graphql/playground 

Above both URLs are valid and will work 

2) Now, When you hit the URL, you will end up with "document not found page" or 404 page, Because by default the playground to enable authoring calls are disabled on XM Cloud, so you will have to enable it to be able to use the authoring API calls.


 3) To enable the playground On XM Cloud, On XM Cloud deploy app, From your environment, go to environment variables,and do following 

4) If it does not exist, make above entry and once done, you will need to deploy the environment again, like following


5) Now, once deployment is finished, you should hit the URL given on step-1 again, and it should load the GraphQL IDE

6) The actual problem starts now, When the IDE opens, the end point URL above is loaded and populated automatically, but it keeps giving "Server cannot be reached"

Note: I ignored it and just went ahead with other process of login and creating token and passed the token into the headers but i had no luck until i fix above

It took me couple of hours to try different things but it never was able to connect, After scratching my head for hours and pulling my hairs, i found out that, Following changes needs to be done before it starts working

  • You have to give https:// instead of http:// which is wrong in default end point If you observe above screenshot, it is http:// by default
  • You will have to remove /ide/../v1 and replace it with /v1/ (Note: without last slash also it was not working)
  • Lastly, Remove the port 80 from the URL too
  • Now, after doing all these changes, when you hit enter, the changes will take effect now this URL will work, Full modified URL is given below

https://<<Your xm cloud cm end point>>/sitecore/api/authoring/graphql/v1/ 

7)  Once you set the URL like above, you might still get following error when you try to run query 

{
  "error": "Unexpected token '<', \"<!DOCTYPE \"... is not valid JSON"
}

You just have to make sure that end point is correct like above, After that you just have to follow what is given on Sitecore documentation, of authorizing the IDE so it can make queries, login to cloud environment via command and generate the token which you can pass into header as following

8) Now, to authorize the IDE you will first have to login to cloud using command, and there are two ways to do it

  • Login via simple "dotnet sitecore cloud login" command, you can run this from the powershell window from the same path as where your Sitecore.json is located, it will use ClientID and Secret of that file (Some how my user.json does not have Secret so i did option two as below)
  • I created my own "Authentication Client" from XM Cloud portal, like following


It will give you ClientID and Secret, Make sure to keep it safe somewhere because secret will not be shown second time, you will need to generate a new authentication client if you loose it.

9) Now, Login with this details from powershell like following 

dotnet sitecore cloud login --client-credentials --client-id <your-client-id> --client-secret <your-client-secret> --allow-write true --xmcloudhost <your-xmcloud-host> --authority <authority-url> --audience <audience-url>

You can replace other parameter by taking reference from user.json file or from Sitecore documentation i have given above on start of this blog

Once login is successful it will just return to a prompt, now you should be good to use same ClientID and Secret to get token like following

10) Generate token use following CURL command and hit it from the postman

curl --location --request POST '<authority-url>/oauth/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=<your-client-id>' --data-urlencode 'client_secret=<your-client-secret>' --data-urlencode 'audience=<audience-url>' --data-urlencode 'grant_type=client_credentials'

you can use import option of postman, and use raw option and paste above command with proper values replaced before running it, and create the call into postman 

Now, You are good to use GraphQL IDE and pass this token in the authorization header as shown below, and now if you create any GraphQL mutation query to do any authoring query, Like for example, i just created simple Blog item of my blog template type under the Blogs parent, you can see it below that it successfully created item into Sitecore.


And you can also see in my Sitecore, That item is created.

Being honest, but i was very happy to achieve this, As i did not know GQL, did not know Authentication Client, Did not know lot of things before and because there were some issues in URLs and processes, i was in never ending loop, But happy that its resolved now

Off for the day now, will enjoy the rest of the evening with family :)


Comments

Popular posts from this blog

Sitecore XM Cloud - 5 ways to create No code web site components with XM Cloud Component Builder

Hi People, First of all congratulations to all 2024 MVPs, Last year has been a community year where we saw lot of new MVPs and lot of new content coming from lot of people, Good learnings. I wanted to share some articles on the real discoveries and headless implementation we did and journey we had and what all things were involved in it etc. but i will bring that later on. Today i am going to talk about "Component Builder", Amazing tool of Sitecore XM Cloud, Last year i did lot of research and hands on to "XM Cloud Component Builder", Very powerful futuristic tooling provided by Sitecore. At that time it was still in "Early Access" phase, but now the offering is fully available, i wanted to revisit and provide almost all the info related to it and will also show, How to create fully functional website without writing any code, yes " It is low code / no code ". Last year i presented at SUGCON-2023-India on "FeaaS - Front End As A Service"

An error occurred while receiving the HTTP response to This could be due to the service endpoint binding not using the HTTP protocol. This could also be due to an HTTP request context being aborted by the server (possibly due to the service shutting down). See server logs for more details.

You have noticed many times that everything was working fine and suddenly the below error starts coming and you find no way to work it out An error occurred while receiving the HTTP response to This could be due to the service endpoint binding not using the HTTP protocol. This could also be due to an HTTP request context being aborted by the server (possibly due to the service shutting down). See server logs for more details. The reason for this is the receiving size of WCF service is smaller then the data which is coming from service It was working before because it was small,So you will have to try to increase the receiving setting in your end point,Possible settings can be following maxStringContentLength="2147483647" maxReceivedMessageSize="2147483647" maxBufferSize="2147483647" maxArrayLength="2147483647" That would definately help you!!!

One or more exceptions occurred while processing the subscribers to the 'item:creating' event

I was recently installing the packages from one of the QA environment to my local Sitecore instance, "Media library package" to be precise, And it started giving me this below error One or more exceptions occurred while processing the subscribers to the 'item:creating' event Looking at the sitecore logs, it gave me more info on the context and the actual inner exception was following Solution: 'Name' should consist only of letters, digits, dashes or underscore Now it was evident that some of my file names were violating the naming rule, I could see in the log just before exception from where the installer stopped creating items, and that file name had round braces "(" and ")" at the end of it, with my surprise I was able to create the item with those name in the content tree, but below was the solution for it, Solution I am using SC 9.0.1 and in that Go to Sitecore.Marketing.config file residing in "App_Config\Sitecore\Mar