Workspaces

Cloud CMS offers Workspaces to provide editors with a way to create their own private and shared spaces where they can work on content without stepping on each other's toes.

Workspaces are implemented using branches to provide all of those capabilities to the editorial team, including fork, merge, differencing, compare and push/pull between workspaces.

Editorial users can create workspaces for any purpose they wish. Here are a few good uses of workspaces:

  • A place to work on content that will be launched at the end of the week
  • A place to make changes to definitions or forms needed for a new launch of your mobile app
  • A place to test out some ideas that may or may not work out. If they don't work out, you just throw them away!

Workspaces let you build things and share them with others. You can instantly search and query for content or run GraphQL queries on top of them. And you can instantly preview the content on a workspace using front-end apps that switch branch IDs. Workspaces are branches under the hood!

Enable Workspaces

To enable Workspaces, go into your project and select Manage Project. You will see a Workspaces link on the left-hand side.

Click on the Workspaces link and you'll be presented with a page where you can enable the Workspaces feature.

Select the checkbox and Save your changes. Then go back to your Project and you'll see a new Workspaces tab on the left-hand side.

View your Workspaces

To see a list of all of the available workspaces, click on the Workspaces link on the left-hand page.

Your workspaces will be listed in a tree structure that reflects how workspaces inherit from their parents. When you create a workspace, you do so by spawning off from an existing workspace (in the branching mindset, this is known as "forking"). The new child workspace inherits all of the content from the parent workspace.

Create a New Workspace

To create a new Workspace, click on the Create New Workspace button. Provide your workspace with a title and pick the parent Workspace from which your new Workspace will descend.

There is also a second way to create a workspace. Select an existing workspace and then use the Selected... dropdown and click Create a Child Workspace.

Switch Between Workspaces

Once your workspace is created, you can switch between workspaces using the dropdown box that now appears on the top right of the page.

When you switch workspaces, the content that you see on the page will be the content for the workspace. As such, you can manage multiple realities at once.

Workspace Details

To view the details of your workspace, click on its title on the Workspaces page:

You can also click on the button next to the drop down.

Workspace Properties

Use the Properties page to adjust your workspace's properties. You can also set a workspace color here, if you like, which can make it easier for users to distinguish between which workspace they're working on.

Workspace Activities

As you create, update and delete content in a Workspace, Cloud CMS automatically tracks all of your activities and changes. To view the Activities, click on the Activities link on the left hand side.

Workspace Changes

You can also view the changes to content in your workspace by clicking on the Changes link.

Explore Other Workspaces

You can pull and copy content from someone else's workspace into your own. To do so, go under the Collaboration section. The Explore link will let you see other workspaces that exist with your Project.

The Selected... drop down provides actions you can take to collaborate with other workspaces.

Compare with Workspace...

To compare the contents of another workspace with your own, select the Workspace in the list and use the Selected... drop down and pick Compare Workspace.

This launches a wizard that will show you what is different in that workspace compared to your own. In effect, this gives you an idea of what content is available in that workspace should you choose to cherry pick (copy things over) or pull from that workspace.

Copy from Workspace...

To copy content from another Workspace into your own, select the Workspace in the list and use the Selected... drop down and pick Copy from Workspace.

This launches a wizard that will show you what is different in that workspace compared to your own. You can then pick which content items you'd like to copy into your workspace. Click Copy to perform the copy operation.

NOTE: This will copy those content items from the other workspace into your own. The content items you select will overwrite the changes you've made locally on your workspace.

Pull from Workspace...

To pull content from another Workspace into your own, select the Workspace in the list and use the Selected... drop down and pick "Pull from Workspace..."

This launches a wizard that will show you all of the changes that the other Workspace has relative to your own. It will then show you any Merge Conflicts that may be produced as a result of these changes being pulled.

The first screen shows you the changes that are available on the incoming Workspace:

The second screen shows you any Merge Conflicts that may occur as a result of the pull:

Pulling is a powerful option that is useful when collaborating across Workspaces where changes are being made quickly and often across the same sets of content. In these cases, its tough to avoid stepping on each other's toes. You may make a change to something that someone else also changed and you didn't know and they didn't know and its nobody's fault and we're all human. Kumbaya.

In those cases, you can pull and Cloud CMS will create Merge Conflicts. These identify where you're stepping on each other toes and then give you the option to work with the other person to figure out which changes should be kept. It's neat and organized and, essentially, lets you defer the problems until the point that you actually push or pull.

Merge Conflicts

If you pull from another Workspace, it's possible for Merge Conflicts to be created. A Merge Conflict is created when there was a change on the other Workspace that conflicts with a similar change on your own Workspace. In this case, Cloud CMS doesn't know which change to keep. It lets you make that decision.

Merge Conflicts are normal. They don't mean that something did not work. In fact, quite the opposite. They mean that Cloud CMS understands that you're trying to bring someone else's changes into your own. However, to do so, Cloud CMS needs to resolve a conflict.

Let's consider an example. Suppose that there is a Article out there with a title on it, like this:

{
    "title": "My Article"
}

Two workspaces are created. On Workspace A, the title is changed to My Article A. And on Workspace B, the title is changed to My Article B.

Now suppose Workspace A tries to pull in the changes from Workspace B. Cloud CMS will attempt to do so by seamlessly stitching the content from Workspace B into Workspace A. In this case, however, the article on Workspace B cannot be seamlessly stitched into Workspace A because both workspaces have a conflicting change to the article. Specifically, both Workspaces have changed the title property.

Thus, Cloud CMS doesn't know which one you want keep. It can't keep both. One must win out over the other.

As such, a Merge Conflict will be created. The managers of both Workspaces will see this Merge Conflict and will have the option to resolve it. They may resolve it by keeping one value or the other. Or they may resolve it by changing it to the a third value.

Pulling a Workspace

When you pull the contents of another Workspace into your own, the Pull wizard will inform you whether any Merge Conflicts will be created:

When you click "Pull", the Pull Wizard will let you know that Merge Conflicts were created:

Pending Merges

If your Workspace has merge conflicts, you'll see a new menu option on the left-hand menu:

Click on "Pending Merges" to view the other workspaces that have pending Merge Conflicts. These indicate an incomplete merge and show you places where work remains to be done:

Click on "Resolve Conflicts" to work on the conflicts on a per-document basis.

Pending Merge Conflicts

This screen shows you all of the content items that are in conflict. You must resolve these conflicts on a per-document basis in order to complete the merge.

  • The left-hand column ("Local") shows you information about the content item as it exists in your workspace.
  • The center column ("Conflicting") shows you information about the content item as it exists in the other workspace.

You will also see details that inform you about exactly which properties are in conflict.

  • Any details in red identify properties that are unresolved.
  • Any details in green identify properties that are resolved.

Click on the "Resolve..." button to work on a conflict.

To resolve a conflict, you must manually compare the differences between the content in your Workspace (Local) and the other Workspace (Conflicting). There are two ways to do this:

  • Visual Conflict Resolution
  • Manual Conflict Resolution

Visual Conflict Resolution

The first option is Visual Conflict Resolution. Click on the "Visual" tab to see this:

The issue is described on the left-hand side. You are then presented with the option to keep the Local value or the Conflicting value.

To keep your own value, click on "Keep My Version":

To keep the value from the other Workspace, click on "Keep Their Version":

Once you've picked your resolutions, click on "Save Resolutions".

Manual Conflict Resolution

The second option is Manual Conflict Resolution. Click on the "JSON" tab to see this:

The right-hand side shows the content (in JSON format) for the conflicting version. This is read-only. The left-hand side shows your local content. You can change this.

Make adjustments to your content and then click "Save Local Changes" to apply them.

Re-Attempting the Merge

After you've picked your resolutions (using the Visual approach) or adjusted your local content (either via the JSON tab or via other means), you can re-attempt the merge.

Click on the "Retry Merge" button to re-attempt the merge.

In the majority of cases, you may need to retry the merge a few times before you get all your Merge Conflicts resolved. This is perfectly fine. You're free to make adjustments, retry the merge and iterate like that as you whittle down your Merge Conflicts.

Eventually, the Merge will succeed and you'll get a message like this: