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

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:

1. Sandboxed Execution — Your extension runs in an isolated iframe environment
2. Secure Communication — All interactions with Sitecore APIs are mediated through the parent application
3. 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:

1. Your extension uses the ClientSDK's messaging system to request operations
2. The ClientSDK sends messages to the parent Sitecore application via postMessage
3. The parent application validates the request against user permissions
4. The parent app executes the GraphQL query using the authenticated session
5. 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

1. Application Context — Always retrieve the application context first to get the sitecoreContextId
2. GraphQL Structure — Use standard GraphQL syntax within the query string
3. 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

1. Input Structure — Mutations require an input object with specific parameters
2. Field Updates — Each field update specifies name, value, and reset properties
3. Item Identification — You can identify items by itemId, path, or both
4. Response Handling — Mutations typically return the updated item data
5. Error Handling — Always implement proper error handling for mutation operations

Best Practices

When working with Sitecore XM Cloud Marketplace extensions:

1. Always Check Initialization — Ensure the ClientSDK is properly initialized before making requests
2. Handle Application Context — Retrieve and validate the application context for every operation
3. Implement Error Handling — GraphQL operations can fail for various reasons — handle them gracefully
4. Escape User Input — When including user-provided values in GraphQL strings, properly escape them
5. Use Specific Field Selection — Only query the fields you actually need to improve performance
6. 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