Created: 22 Aug 2024, last update: 9 Nov 2024
Using the Sitecore APIs with Sitecore Commander
Introduction
In this blog post, we will explore how to leverage Sitecore Commander, a powerful tool designed for developers and administrators to manage Sitecore instances efficiently. We’ll delve into how Sitecore Commander integrates with Sitecore’s RESTful and GraphQL APIs, making complex content management tasks easier and more automated.
Over the course of several projects, I developed multiple content migration tools, each tailored for specific tasks. Initially, these migration scripts were quite specific, built to handle particular requirements of each project. However, after numerous migrations, I realized that much of the code could be generalized to handle a broader range of tasks. This led to the evolution of my codebase into something more flexible and reusable. Moreover, there was an increasing need to execute various other scripts using the Sitecore APIs. All of this culminated in the refactoring of my work into what is now known as the Sitecore Commander project.
If you've been following my previous blogs on content migration, you’ll find this tool particularly useful as it extends those capabilities with enhanced scripting, automation, and authentication features.
What is Sitecore Commander?
Sitecore Commander is a C# Visual Studio project built for managing Sitecore environments through visual studio and the command-line interface (CLI). It's designed to work seamlessly with Sitecore’s APIs, allowing you to execute complex scripts and manage long-running tasks. It is especially beneficial for tasks that require automation, bulk content management, and intricate scripting. It is not a just a tool to download and execute but a Visual Studio project and you need to program to use.
Why Use Sitecore Commander?
The key advantage of Sitecore Commander is its ability to integrate with Visual Studio, enabling you to write, debug, and execute scripts in C#. This integration is invaluable for developers who need to handle complex logic, automate repetitive tasks, and manage Sitecore environments efficiently. The tool’s design also emphasizes enhanced security, making it safer to execute scripts without the risks associated with elevated PowerShell permissions. For security reasons, Sitecore PowerShell Elevation is recommended only for local environments.
Improved Login Process with Sitecore CLI
One of the significant improvements in the latest version of Sitecore Commander is the streamlined login process. By utilizing the Sitecore CLI's connect command, you no longer need to manually manage or copy access tokens like the code from the blog Seamless Content Migrating with GraphQL
The Sitecore CLI handles token management, including refreshing tokens and managing multiple logins across different environments.
Once you’ve logged in using the CLI, Sitecore Commander reads the credentials directly from the .sitecore/user.json file, eliminating the need for manual token handling. This approach not only simplifies the authentication process but also leverages the CLI's capability to manage multiple environments, making it easier to switch between them using the --environment-name option.
Using the GraphQL API
As discussed in my previous blog on content migration, the GraphQL API is a powerful API for importing content into Sitecore. With Sitecore Commander, you can automate these processes more efficiently than with tools like postman and Firecamp.dev. For example, you can script the import of content items, manage layouts. Writing a content migrator require a lot of custom code let start simple.
Example Command: Here’s a sample code to delete a specific language from a tree using Sitecore Commander:
var env = Login.GetSitecoreEnvironment();
//Example DeleteItemLanguageVersionFromSubtree
var status = await DeleteItemLanguageVersionFromSubtree.RemoveAsync(env, "/sitecore/content/xxxx", "en");
Example Command: Here’s a sample code to migrate a single multi language item from Sitecore XP to XM Cloud with Sitecore Commander:
//Example migrate item from sitecore with REST api to XM Cloud with GraphQL api
var restApiCookies = SscItemService.SourceLogIn();
var sourceItem = SscItemService.GetItem("/sitecore/content/Home/test", restApiCookies, "en");
const string SxaHeadlessPageTemplateId = "{4829027E-F126-4192-ACE6-F0F2E3BE2A26}";
Guid HomeGuid = Guid.Parse("{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}");
// place the sourceItem below Home and use template SxaHeadlessPageTemplateId beside language "en", try to add "de" and "nl" version if exist.
// adjust the CreateMigratedSxaPage to map the fields you need, and write logic for converting the layout.
var status = await CreateMigratedSxaPage.CreateLabelPageItem(env, restApiCookies, CancellationToken.None, "migratedHome2", HomeGuid, sourceItem, SxaHeadlessPageTemplateId, new string[] { "de", "nl" });
Note: The CreateLabelPageItem methode contains all logic for mapping field you can adjust that for your situation, also you can create some code to migrate the layout and renderings and the datasources. One thing the GraphQL Api is not supporting giving your own id, so migrated items get a new id.
Call to Action
Explore the full potential of Sitecore Commander. For more detailed examples and demo code, visit my GitHub repositories, and don’t forget to check out my previous blogs for deeper insights into Sitecore APIs.
Links
Sitecore Commander GitHub
Seamless Content Migrating with GraphQL
Migrating Your Content Seamlessly: A Comprehensive Tech Guide from WordPress to Sitecore XM Cloud
