1. Sitecore Authoring and Management GraphQL API

Query examples for management operations

The Authoring and Management GraphQL API allows you to extend Experience Manager with custom dialogs and user interfaces. You can use the API to perform tasks previously possible only through the Sitecore user interface.

You can perform management operations using queries and mutations for the following GraphQL types:

  • Archiving
  • Database
  • Indexing
  • Job
  • Language
  • Publishing
  • Security
  • Workflow
  • Rules

For a complete list of available types and operations, refer to the built-in documentation in the GraphQL IDE.

Trigger an index rebuild

You can use the rebuildIndexes mutation to run an index rebuilding operation.

Query

graphql
mutation {
  # Rebuild all indexes if indexName input is not specified.
  rebuildIndexes(
    input: { indexNames: ["sitecore_master_index", "sitecore_core_index"] }
  ) {
    jobs {
      name
      handle
      status {
        total
        messages
        processed
        jobState
      }
      done
    }
  }
}

Result

json
{
  "data": {
    "rebuildIndexes": {
      "jobs": [
        {
          "name": "Index_Update_IndexName=sitecore_master_index",
          "handle": "3224a43a-0bb1-4be5-ac2f-91e781415be0;2AD160A8BF9F-Default Web Site",
          "status": {
            "total": -1,
            "messages": [
              "Job started: Index_Update_IndexName=sitecore_master_index"
            ],
            "processed": 0,
            "jobState": "RUNNING"
          },
          "done": false
        },
        {
          "name": "Index_Update_IndexName=sitecore_core_index",
          "handle": "e06da2e4-c129-4273-86be-945c5fbb5078;2AD160A8BF9F-Default Web Site",
          "status": {
            "total": -1,
            "messages": [],
            "processed": 0,
            "jobState": "RUNNING"
          },
          "done": false
        }
      ]
    }
  }
}

Check a job status by job name

You can query the job details by the job name or job handle returned from the result using Job API.

Query

graphql
query {
  # If both jobName and handle parameters are specified, the jobName parameter is ignored
  job(input: { jobName: "Index_Update_IndexName=sitecore_master_index" }) {
    name
    handle
    status {
      messages
      processed
      jobState
    }
    done
  }
}

Result

json
{
  "data": {
    "job": {
      "name": "Index_Update_IndexName=sitecore_master_index",
      "handle": "61519bfb-ff49-44bd-8957-9ef4ba4404a2;2AD160A8BF9F-Default Web Site",
      "status": {
        "messages": [
          "Job started: Index_Update_IndexName=sitecore_master_index"
        ],
        "processed": 4630,
        "jobState": "RUNNING"
      },
      "done": false
    }
  }
}

Check a job status using wildcards

You can use a wildcard to get details about available jobs.

You can query by wildcard alone or use the wildcard before or after a job name fragment. Specifically:

  • * - returns the status for all jobs.
  • *myjob - returns the status for jobs where the name ends with myjob.
  • myjob* - returns the status for jobs where the name starts with myjob.
  • *myjob* - returns the status for jobs where the name contains myjob.

Query

graphql
query{
  jobs(input: { jobName: "\*index" }
){
    nodes {
      name
      handle
      status {
        messages
        processed
        jobState
      }
      done
    }
  }
}

Result

json
{
  "data": {
    "jobs": {
      "nodes": [
        {
          "name":
"Index_Update_IndexName=sitecore_master_index",
          "handle":
"970372d7-df5a-418f-a603-d6c0b40ed52c;2AD160A8BF9F-Default Web Site",
          "status": {
            "messages": [
              "Job started: Index_Update_IndexName=sitecore_master_index"
            ],
            "processed": 1578,
            "jobState": "RUNNING"
          },
          "done": false
        },
        {
          "name": "Index_Update_IndexName=sitecore_core_index",
          "handle": "b009bb91-aeae-4d86-86b5-fac785f1861d;2AD160A8BF9F-Default Web Site",
          "status": {
            "messages": [
              "Job started: Index_Update_IndexName=sitecore_core_index"        
            ],
            "processed": 307,
            "jobState": "RUNNING"
          },
          "done": false
        }
      ]
    }
  }
}

Publish an item to the edge

You can use the publishItem mutation to publish an item to the edge. If you want to check the operation status, return the operationId property of the publish operation.

Query

graphql
mutation {
  publishItem(input: {
    sourceDatabase: "master"
    targetDatabases: ["experienceedge"]
    rootItemIds: ["{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"]
    publishSubItems: true
    publishRelatedItems: false
    publishItemMode: FULL
    languages: ["en", "da"]
    displayName: "Publish home item and descendants"
  }) {
    operationId
  }
}

Result

json
{
    "data": {
        "publishItem": {
            "operationId": "4e8ed033-cb59-4484-aa86-a6a165711710;xmc"
        }
    }
}

Input fields

FieldTypeRequiredDescription
sourceDatabaseStringYesThe source database from which items are published, usually "master".
targetDatabases[String!]!YesOne or more target databases to which items are published, for example, ["experienceedge"].
rootItemIdIDNoThe GUID of the root item to publish.
rootItemIds[ID]NoA list of root item GUIDs to publish. If provided, overrides rootItemPaths.
rootItemPathStringNoThe Sitecore path, for example, "/sitecore/content/Home" of the item to publish. Ignored if an ID is provided.
rootItemPaths[String]NoMultiple root item paths to publish. Ignored if rootItemId or rootItemIds is provided.
publishSubItemsBooleanNoWhether to include child items in the publish operation. Default: false.
publishRelatedItemsBooleanNoWhether to include related items, for example, referenced media or linked items. Default: false.
publishItemModePublishItemModeYesThe publishing mode. Common values: FULL, SMART.
languages[String!]!YesThe languages to publish, for example, ["en"]).
displayNameStringNoA friendly name for this publish request.

Typical scenarios

ScenarioExample input
Publish a single item by IDrootItemId: "GUID"
Publish multiple items by IDrootItemIds: ["GUID1", "GUID2"]
Publish an item by pathrootItemPath: "/sitecore/content/Home"

Check the publishing status

You can query the status of a publishing operation using the operation identifier returned by the publishItem mutation.

Query

graphql
query {
  publishingStatus(
    publishingOperationId: "cbbcaf09-ec02-42c8-bad6-df60ef05cc42;F497611F492C-Default Web Site"
 ) {
    state
    isDone
    isFailed
    languages {
      name
    }
    processed
    targetDatabase {
      name
    }
  }
}

Result

json
{
  "data": {
    "publishingStatus": {
      "state": "RUNNING",
      "isDone": false,
      "isFailed": false,
      "languages": [
        {
          "name": "en"
        }
      ],
      "processed": 1,
      "targetDatabase": {
        "name":
"experienceedge"
      }
    }
  }
}

Query locked items

You can check to see which items are locked and who is locking them. Items are locked when a content author edits them in the Content Editor.

Query

graphql
lock{
      isLocked
      lockedBy
      user(username: <username>) {
        canLock
        hasLock
        canUnlock
      }
    }

Result

json
{
  "data": {
    "item": {
      "lock": {
        "isLocked": true,
        "lockedBy": "sitecore\\\\[email protected]",
        "user": {
          "canLock": false,
          "hasLock": true,
          "canUnlock": true
        }
      }
    }
  },
  "extensions": {}
}

Check publishing permissions for an item

You can use the canPublish field with the item query to get publishing permissions for an item. You can check all the publishing permissions for the item, or query an individual user to check their permissions for the item.

Query

Query all the publishing permissions of an item:

json
query{
  item(where: {path: "<item path>"}) {
      canPublish
  }
}

Query

Query the publishing permission of a specific user for an item:

json
query{
  item(where: {path: "<item path>"}) {
    access(username:"<username>"){
      canPublish
    }
  }
}

Result

json
{
  "data": {
    "item": {
      "access": {
        "canPublish": false
      }
    }
  },
  "extensions": {}
}
If you have suggestions for improving this article, let us know!