Content Hub Tip #33: Content Hub ONE CLI Serialization

 

Last year, I wrote about the Content Hub ONE CLI. If you haven't read those, be sure to check them out. In the first one, I wrote Content Hub Tip #31: How to install Content Hub ONE CLI and the second one Content Hub Tip #32: How can you add a tenant to Content Hub ONE CLI?. This time we'll take a deeper look into the Serialization command to interact with a Content Hub ONE instance. Next to that, how to sync multiple instances that you might have.

Remark: The Content Hub and Content Hub ONE are two separate SaaS applications. These don't share the same CLI. They both have their one version of a CLI. Their functionalities look similar but act with different commands.

Before we start you need to make sure that you have a tenant added to your CLI. To view, your current tenants execute the following command: 

ch-one-cli tenant list

When you have a tenant available, you will get something like this:

Be sure to check your Active tenant, before continuing with the next phase. If you need to correct the active tenant execute the following command:

ch-one-cli tenant select --name [name of tenant]

Check the outcome of the select command, to verify you now have selected the proper tenant. Now that we've selected our tenant we can start interacting with it. Next to the tenant, the CLI has two more base commands you can execute. It has Delivery and Serialization. With the Delivery command, you manage content and API keys. More on this in another blog post. For today, we focus on the Serialization command. With this command, you can serialize and deserialize content types and content items. Unfortunately, it's not possible (yet) to serialize media items. I hope that Sitecore will make this available in the future as well. When running the CLI with the serialization command, you get the following information.

Command: ch-one-cli serialization

Before you can start, you need to initialize the working directory that you choose. For this example, I've created a Content Hub ONE directory in the C drive. Create such a working directory, navigate to it, and then run the following command to initialize the directory:

ch-one-cli serialization initialize

When the CLI has finished you will get two folders in the directory: .sitecore and .vscode. The .sitecore folder will contain the schema files needed to interact with the Content Hub ONE instance. The .vscode folder will have a settings.json that will inform VS Code about two types of YAML files; content type and content item.

Now that we've initialised the directory, we can start pulling the resources from the instance. Before we pull any content items we would like to get their corresponding content types.

Remark: you don't actually need to pull the content types before pulling the content items, but it makes more sense to do so. If you want to push the content items to another instance, you need to make sure the content type is available and the same version at the other instance.

Pull all available content types with the following command:

ch-one-cli serialization pull content-type

This will pull all the content types that are available within the instance. If you want, you can also specify by ID. You need to add the --id [id] to the command, like so:

ch-one-cli serialization pull content-type --id "athlete"

or with a wildcard filter *

ch-one-cli serialization pull content-type --id "a*" (starts with)

or

ch-one-cli serialization pull content-type --id "*a" (ends with)

When you don't specify with the --id attribute it will default to --id *, thus getting all the content types from the instance. For now, let's get all the content types of the instance. If you run the command, it will output all the content types it has pulled out of the instance, like so:

In the background, the CLI will create a folder called contentTypes. This folder will contain a YAML file for each content type that was pulled. This file will contain the blueprint of the content type. As this is formatted in YAML, you could easily compare and merge changes in your GIT repository. Which is important to keep the changes under source control.

Based on these content types we can now start downloading the corresponding content items of the instance. The command is similar to the content type command we've just seen. Instead of content-type, we now add content-item to the command. At the moment we can't pull all content items out of an instance with one command. We need to do this for each content type. That's why it's easier to get the content types first. If you look at the command below, you can see that we need to specify the content type with the --content-type "your content type". Using a wild card with the --content-type option doesn't work yet.

ch-one-cli serialization pull content-item --content-type "athlete"

When running this command, it will output and download all the content items related to the specified content type. The content items will also be downloaded in YAML format like the content types. You need to repeat this for each content type. We can easily automate this process with an easy Powershell script.

In the script below I've automated the process of downloading all the content types of an instance, and based on these content types it will download its content items. Keep in mind to run this script from the working directory that you've initialized from the beginning of this blog post.

$contentTypesOutput = ch-one-cli serialization pull content-type

foreach ($contentTypeText in $contentTypesOutput)
{
    $contentType = $contentTypeText|%{$_.split('"')[1]}
    if($contentType)
    {
        Write-Host "####################################"
        Write-Host "#                                  #"
        Write-Host "  Pulling content-type" + $contentType
        Write-Host "#                                  #"
        Write-Host "####################################"
        ch-one-cli serialization pull content-item --content-type $contentType
        Write-Host "####################################"
        Write-Host ""
    }
}

Hope you've enjoyed this blog post. Until next time!