# Workflows

Learn about default and custom workflows in Hygraph

## 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.

**Pro Tip:**

You can make it so custom roles with specific permissions can take content through different stages, ensuring only the users assigned to a certain role can perform a set of actions according to your configuration.

This is really useful, for instance, in approval workflows where the users who write the content are not the same users who approve it for publishing.

## 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 workflow](https://hygraph.com/images/classic-docs/user-guides/project-guides/basic-workflow.png)

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 stages](https://hygraph.com/images/classic-docs/user-guides/project-guides/approval-flow-2-stages.png)

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.

**Pro Tip:**

In this setup, the **Author** would have create permissions and only the **Editor** would have publish permissions to take the content from `DRAFT` to `PUBLISHED`. This prevents publishing unsupervised content by accident.

- [Click here to learn more about roles & permissions](https://hygraph.com/classic-docs/developer-guides/project/roles-and-permissions)
- [Click here to check out our API Reference on permissions](https://hygraph.com/classic-docs/api-reference/basics/permissions)

### 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.

[Video](https://www.youtube.com/watch?v=Fw45CRd8_CM)

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 box](https://hygraph.com/images/classic-docs/user-guides/project-guides/roles-oob-upgraded.png)

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 permissions](https://hygraph.com/images/classic-docs/user-guides/project-guides/contributor-role-permissions.png)

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 permissions](https://hygraph.com/images/classic-docs/user-guides/project-guides/no-publish-permissions.png)

## 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 stages](https://hygraph.com/images/classic-docs/user-guides/project-guides/approval-flow-3-stages.png)

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.

**Pro Tip:**

In this setup, the **Author** would have publish permissions from stage `DRAFT` to `APPROVAL`, which would allow them to work on draft content that can be set for revision when it's ready. The **Editor** would have publish permissions to take the content from all stages to all stages; this way, they can publish content that is ready, but also send content that needs further work back to the `DRAFT` stage.

- [Click here to learn more about roles & permissions](https://hygraph.com/classic-docs/developer-guides/project/roles-and-permissions)
- [Click here to check out our API Reference on permissions](https://hygraph.com/classic-docs/api-reference/basics/permissions)

Creating a **Custom view** showing only the content entries in the `APPROVAL` stage will make it easier for our **Editor** to access the content they need to review.

- [Click here to learn more about creating custom views](https://hygraph.com/classic-docs/developer-guides/content/content-views#custom-views)

### 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.

[Video](https://www.youtube.com/watch?v=BsNTco-efdA)

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

|Field          |Input                                                                          |
|---------------|-------------------------------------------------------------------------------|
|Display name   |Review                                                                         |
|API ID         |REVIEW                                                                         |
|COLOR          |Use 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 permissions](https://hygraph.com/images/classic-docs/user-guides/project-guides/content-permissions-author3stages.png)

|Permission              |Details                                                                                          |
|------------------------|-------------------------------------------------------------------------------------------------|
|`Read`                  |Select this permission for all models on all stages and for all locales                          |
|`Create`                |Select this permission for all models for all locales                                            |
|`Update`                |Select this permission for all models for all locales                                            |
|`Publish`               |Select this permission for all models, from stage `DRAFT` to stage `REVIEW`, and for all locales |
|`Unpublish`             |Select this permission for all models on stage `REVIEW`, and for all locales                     |
|`Read versions`    |Select this permission for all models                                                            |

**Pro Tip:**

The `Model` selection dropdown is for all permissions being added at one time. In this case, you selected it only once and then selected the permissions with their corresponding locales and stages.

If some of your permissions apply to certain models only, you will have to add them separately by repeating the process.

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:

[Video: User can publish to REVIEW but not to PUBLISHED](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9wgl7jad707w5i27lx3o2)