Reading time: 5 min read
Sitecore XM Cloud Marketplace: Reading and Changing Items with GraphQL
How to use Sitecore ClientSDK to read and mutate items in a Sitecore Marketplace Application
How to Use Sitecore ClientSDK to Read and Mutate Items in a Sitecore Marketplace Application
Working with Sitecore XM Cloud through the Marketplace platform opens up powerful possibilities for content management extensions. In this post, we'll explore how the Sitecore ClientSDK performs GraphQL queries and mutations within a marketplace extension.
Note: This blog post focuses specifically on how to read and manipulate Sitecore items using the ClientSDK and Authoring API. We won't be covering how to set up a marketplace application from scratch — instead, we'll concentrate on the core concepts of working with Sitecore content through GraphQL operations once your marketplace extension is already established.
Sample Repository
You can find a complete working example of the concepts discussed in this blog post in our sample repository:
Sitecore XM Cloud Marketplace Sample – Item Query & Mutation
This sample repository demonstrates the XM Cloud Full Screen integration point, showing how to build a complete marketplace extension that can read and modify Sitecore content items.
Architectural Overview: How ClientSDK Works with GraphQL
Before diving into code examples, it's crucial to understand the architecture behind Sitecore XM Cloud Marketplace Extensions.
The Micro-Frontend Architecture
Sitecore XM Cloud Marketplace Extensions operate as micro-frontends that run inside the Sitecore authoring environment as iframes.
This architecture provides several key benefits:
- Sandboxed Execution — Your extension runs in an isolated iframe environment
- Secure Communication — All interactions with Sitecore APIs are mediated through the parent application
- Authentication Inheritance — Your extension leverages the existing user session and permissions
How GraphQL Queries Work
The ClientSDK acts as a communication bridge between your extension (iframe) and the parent Sitecore XM Cloud interface.
Here's how the flow works:
Your Extension (iframe) → ClientSDK → Parent Sitecore App → Sitecore APIs
When you want to perform GraphQL operations:
- Your extension uses the ClientSDK's messaging system to request operations
- The ClientSDK sends messages to the parent Sitecore application via
postMessage - The parent application validates the request against user permissions
- The parent app executes the GraphQL query using the authenticated session
- The response is sent back to your extension through the same secure channel
This API communication can be visualized in the in the Browser’s Development Tool Console. At the time of writing this post, I could not find a way to disable that console logging.
Security Model Benefits
This architecture provides several security advantages:
- No Direct API Access — Your extension never directly authenticates with Sitecore APIs
- Permission Enforcement — All operations are subject to the logged-in user's permissions
- No CORS Issues — API calls originate from the same domain as Sitecore
- Credential Protection — Tokens and credentials are never exposed to your extension
Querying Items with GraphQL
Let's look at how to perform GraphQL queries to read content items from Sitecore XM Cloud.
It's important to note that we're working with the Authoring API here, not the Delivery API.
This means you cannot use the Sitecore GraphQL Playground to validate these queries, as the playground uses the Delivery API which has a different schema and capabilities.
Basic Query Example
import { useMarketplaceClient } from "@/src/utils/hooks/useMarketplaceClient";
export function QueryExample() {
const { client, isInitialized, error } = useMarketplaceClient();
const fetchItemData = async (itemPath: string) => {
if (!client || !isInitialized) return;
// First, get the application context
const contextResponse = await client.query("application.context");
const appContext = contextResponse.data as ApplicationContext;
// Extract the Sitecore Context ID
const sitecoreContextId = appContext.resourceAccess?.[0]?.context?.preview;
// Define your GraphQL query
const graphqlQuery = {
query: `
query {
item(
where: {
database: "master",
path: "${itemPath}"
}
) {
itemId
name
path
fields(ownFields: true, excludeStandardFields: true) {
nodes {
name
value
}
}
}
}
`
};
// Execute the query through the ClientSDK
const response = await client.mutate("xmc.authoring.graphql", {
params: {
query: {
sitecoreContextId,
},
body: graphqlQuery,
},
});
return response.data?.data?.item;
};
}
Key Query Concepts
- Application Context — Always retrieve the application context first to get the
sitecoreContextId - GraphQL Structure — Use standard GraphQL syntax within the query string
- Field Selection — Specify exactly which fields you need to minimize data transfer
Mutating Items with GraphQL
Now let's explore how to modify content items using GraphQL mutations.
Basic Mutation Example
const updateItemField = async (
itemId: string,
itemPath: string,
fieldName: string,
newValue: string
) => {
if (!client || !appContext) return false;
try {
const sitecoreContextId = appContext.resourceAccess?.[0]?.context?.preview;
const mutationQuery = {
query: `
mutation {
updateItem(
input: {
fields: [
{
name: "${fieldName}",
value: "${newValue.replace(/"/g, '\\"')}",
reset: false
}
]
database: "master"
itemId: "${itemId}"
language: "en"
path: "${itemPath}"
version: 1
}
) {
item {
name
itemId
fields(ownFields: true) {
nodes {
name
value
}
}
}
}
}
`
};
const response = await client.mutate("xmc.authoring.graphql", {
params: {
query: {
sitecoreContextId,
},
body: mutationQuery,
},
});
return response.data?.data?.updateItem?.item;
} catch (error) {
console.error("Mutation failed:", error);
return false;
}
};
Key Mutation Concepts
- Input Structure — Mutations require an
inputobject with specific parameters - Field Updates — Each field update specifies
name,value, andresetproperties - Item Identification — You can identify items by
itemId,path, or both - Response Handling — Mutations typically return the updated item data
- Error Handling — Always implement proper error handling for mutation operations
Best Practices
When working with Sitecore XM Cloud Marketplace extensions:
- Always Check Initialization — Ensure the ClientSDK is properly initialized before making requests
- Handle Application Context — Retrieve and validate the application context for every operation
- Implement Error Handling — GraphQL operations can fail for various reasons — handle them gracefully
- Escape User Input — When including user-provided values in GraphQL strings, properly escape them
- Use Specific Field Selection — Only query the fields you actually need to improve performance
- Respect User Permissions — Remember that all operations are subject to the user's Sitecore permissions
References:
- https://doc.sitecore.com/mp/en/developers/marketplace/introduction-to-sitecore-marketplace.html
- https://doc.sitecore.com/mp/en/developers/sdk/latest/sitecore-marketplace-sdk/make-a-graphql-query.html
- https://doc.sitecore.com/xp/en/developers/latest/sitecore-experience-manager/query-examples-for-authoring-operations.html#update-an-item