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