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.

[object Object]

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

[object Object]

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.

[object Object]

View your Workspaces

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

[object Object]

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.

[object Object]

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.

[object Object]

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.

[object Object]

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:

[object Object]

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

[object Object]

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.

[object Object]

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.

[object Object]

Workspace Changes

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

[object Object]

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.

[object Object]

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

[object Object]

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.

[object Object]

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.

[object Object]

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:

[object Object]

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

[object Object]

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 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:

[object Object]

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

[object Object]

Pending Merges

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

[object Object]

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:

[object Object]

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.

[object Object]
  • 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:

[object Object]

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":

[object Object]

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

[object Object]

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:

[object Object]

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:

[object Object]