Get the latest insights, best practices, and tips from power users

Hygraph
Docs

Workflows

#Overview

Creating workflows is essential to managing larger teams and ensuring that errors do not slip through the cracks when teams create and update content using a CMS. Hygraph is no different.

Your workflow is the set of steps your content goes through, from creation to publication or removal. It's a systematic way of managing the lifecycle of content.

Hygraph offers a default workflow where content goes from DRAFT to PUBLISHED, which uses our default roles - Admin & Editor.

Depending on your plan, we also offer the possibility to create custom workflows with additional custom stages - like Review -, roles - such as Contributor & Developer - and even custom roles.

#About Hygraph content stages

Content in Hygraph that has been saved but has never been published, exists only in the DRAFT stage.

When promoted to the PUBLISHED stage, content will exist in that stage, and also in DRAFT.

When you update a content entry and save without publishing, that new content will be saved in DRAFT and the entry will show a blue Published pill on the content table, indicating that it's outdated.

Content being outdated means that the version currently saved in the DRAFT stage contains changes that have not yet been promoted to PUBLISHED.

#What you can do

  • You can create secure workflows by using Custom Roles. Custom roles allow teams to give specific permissions depending on the person's role on the project. This ensures that team members don't interact with functionality that's not relevant, and prevents them from prematurely publishing something.
  • You can use the Content Staging and Content Versioning features to create workflows.
  • You can use Content Staging to compare and revert changes between content in DRAFT and PUBLISHED stages. This workflow can be further empowered by setting up a Custom View, which allows you to see all content that matches certain criteria in the DRAFT or PUBLISHED stage.

#Basic workflow

Out of the box, every Hygraph project includes two content stages - DRAFT and PUBLISHED - and two roles, Admin and Editor.

These are system content stages and roles, which cannot be edited.

Basic workflowBasic workflow

Users assigned to the Admin role can manage teams and create/update projects, while users assigned to the Editor role, can create, update and delete content.

Since these roles are not custom, you cannot customize user authorities and permissions on content models, locals, stages, etc.

This means that all users that you add to the project can move content from DRAFT to PUBLISHED.

#Approval flow with 2 stages

The following example is an approval flow with 2 content stages - DRAFT & PUBLISHED - but with custom roles, which in this case we've named Author and Editor.

Approval flow with 2 stagesApproval flow with 2 stages

As you can see, the Author role creates the content, which is then supervised by the Editor role. The Author can only save the content as DRAFT, while the Editor can either choose to publish the content to PUBLISHED, or else leave it as DRAFT and add comments for the Author to keep working on it.

#Set up approval flows with 2 stages

This workflow uses the default content stages, as well as the system Editor role, and the system Contributor role we get out of the box with a plan upgrade.

After upgrading your plan, if you navigate to Project settings > Access > Roles & Permissions, you'll see the following roles available out of the box:

Four roles out of the boxFour roles out of the box

If you go over to the Contributor role, click on the three-dots context menu and select View permissions you'll see the following:

Contributor role permissionsContributor role permissions

As you can see, this role can create content but not publish it. This means they can save to DRAFT but not to PUBLISHED.

All you have to do is make sure that you assign your content authors to the Contributor role, and then assign the users who will go into that DRAFT content, supervise and save it to PUBLISHED to the Editor role.

As a result of this configuration, users that you assign to the Contributor role, will see the button to save content in the UI, but not the button to publish it:

User without publish permissionsUser without publish permissions

#Approval flow with 3 stages

This example is similar to the previous one, except we have added a custom content stage called APPROVAL.

Approval flow with 3 stagesApproval flow with 3 stages

Now the Author has permissions to move the content stage from DRAFT to APPROVAL when it's ready for review.

The Editor can then look into the content entries on stage APPROVAL and supervise like in the previous example, deciding which content is ready and can be published to the PUBLISHED stage, versus which content needs to still be working on and move it back to DRAFT so the Author can keep working on it.

#Set up approval flows with 3 stages

This workflow uses the system Editor role, and adds custom stages, and a custom Author role with permissions that are similar to but more limited than the Editor role.

To set up a custom stage, navigate to Project settings > Access > Roles & Permissions, click on + Add stage, and use the following information:

FieldInput
Display nameReview
API IDREVIEW
COLORUse the dropdown menu to pick a color for your custom stage. We picked Brown

To set up the custom role, navigate to Project settings > General > Content stages, and click + Add custom role in the Custom roles section of the screen.

Give your role a Name - in this case we're using Author - and optional Description, and click Add to save. The role is now on the list of custom roles, but still needs to have its permissions configured. To do this, click on the three-dots context menu of your new role and select View permissions.

In the Content Permissions section, click on + Add permission and use the following information:

Approval flow with 3 stages: Content permissionsApproval flow with 3 stages: Content permissions

PermissionDetails
ReadSelect this permission for all models on all stages and for all locales
CreateSelect this permission for all models for all locales
UpdateSelect this permission for all models for all locales
PublishSelect this permission for all models, from stage DRAFT to stage REVIEW, and for all locales
UnpublishSelect this permission for all models on stage REVIEW, and for all locales
Read versions  Select this permission for all models

Now, move on to the Management API Permissions screen section and click Edit permissions. We only need to add two more permissions here so our Authors will be able to create entries and save them to DRAFT.

Look for and select the checkboxes of the following permissions:

  • Create new entries
  • Update existing non-published entries
  • Update published entries
  • Publish non published entries

The list is quite long, but you can use ctrl/cmd+f to find the permissions.

As a result of this configuration, users that you assign to the Author role, will be able to create and save entries in the DRAFT stage, and save them to the REVIEW stage when they are ready to be revised by the Editor role.

In this flow, Authors are not able to save content to PUBLISHED, but Editors are.

In the UI, Authors can save content that needs to remain in the DRAFT stage, and then publish the content to the REVIEW stage when it's ready for the Editor to take over:

User can publish to REVIEW but not to PUBLISHEDUser can publish to REVIEW but not to PUBLISHED