Content Authoring

Content production in general requires workflows to make sure that every team member gets involved in the process of creating the story. Storyblok allows you to define your own custom workflows and rules to control flow of this process. We offer you various levels of content authoring from the basic available in the Free plan to the Custom Workflows with webhooks available in the Teams and Enterprise plan.

Basic Workflows

This level of content authoring is available in the Free Plan and offers three basic stages with predefined settings. By default all stories will be set to the Undefined workflow stage after their creation. You have to manually change the workflow stage to Drafting if you want to use the benefits of the workflows. Next, you will be forced to follow the process through the Reviewing stage to the final Ready to publish stage, in which you can publish your Story.

hint:

The settings of all stages in the Basic Workflows are already predefined and can be changed in higher plans, where you can create your own workflow stage and define your own set of rules/settings.

Workflow Stage Description
Not Defined / Undefined In the case of the Free Plan, or deletion of the used workflow stage, the stage of the story will be changed to an undefined stage.
Drafting Initial state of the story if the content authoring is enabled. At this stage, users are working on the draft version of the story and are not allowed to publish.
Reviewing Story is sent to review to one or multiple reviewers (users of the space).
Ready to publish Story is ready to be published and any user of the space may publish it.

You are able to use a webhook, which will always be triggered as the stage of the story is changed. The body of the request sent to the webhook URL will look like the following JSON object:

{
    "action": "workflow_stage_changed",
    "text": "The workflow stage of story {Name of the Story} has been changed to {Name of the new stage}.",
    "story_id": 12345678, // ID of the Story
    "workflow_stage_name": "Reviewing", // Name of the new workflow stage
    "space_id": 123456 // ID of the space
}
hint:

You can easily inspect the body of the request sent to the URL of the webhook by using RequestBin.com service. Read more about it in this article.

How to Change the Stage of the Story

You can change the stage of the story in the Visual Editor of the Storyblok app with these steps:

  1. Open the Story in the Visual Editor
  2. Click on the Change the tab to Status in right-hand side from Content View
  3. Click on the Change button/link next to the name of the stage

How to Change the Stage of the Story

You can change the stage of the story in the Visual Editor of the Storyblok app with these steps:

  1. Open the Story in the Visual Editor

  2. Click on the Workflow stages {1} link.

  3. Select the desired stage from the list {2}.

  4. You can assign this new stage to a particular user {3} or role {4}.

  5. Click on the Save button {5}.

You can leave a comment when changing the stage, and also notify users about this action through email.

app.storyblok.com
An annotated screenshot of how to change the workflow stage of a story
1
2
3
4
5
hint:

You can also change the stage of the Story by using the Management API. Read more in the documentation of MAPI - Workflow Stage Changes.

How to Inspect the Stage of the Story

You see the current stage of a Story in the “Workflow Stages” menu inside the Visual Editor. You can also filter all stories of a selected stage using the filter in the Content section.

Custom Workflows

required:

Custom Workflows are available in the Teams and Enterprise Plans.

Using the Custom Workflows functionality you are able to define your own content authoring process. You are able to create multiple workflow stages and define their rules and order of them.

Create new stage

You can create a new stage in the Settings section, in the Workflow tab, by defining its name and color.

app.storyblok.com
A screenshot of how to create a new workflow stage
hint:

You can create and manage your custom workflow stage using the Managment API. Read more in the documentation of the Management API.

Customization of Workflow stages

The setup of the stage is reached by clicking on the cog icon in the same row as the name of the stage.

app.storyblok.com
A screenshot of how to customize a workflow stage

You can set up the following properties of the workflow stage:

Property Description
Stage Name A label used to identify the stage.
Color A RGB code of the color representing the stage.
Define as default stage for new items If active, all new Stories will be created within this stage.
Publishing Rights If active, you may choose a list of the stage, in which you are allowed to publish the story.
Next available stages If active, you may specify the list of stages that are available as next stages, from the current stage.
User(s)/Role(s) who can change a stage to the next available stage Specified list of users or roles, they are allowed to change the stage from the current stage to one of the next allowed stages.
warn:

You can remove the workflow stage by clicking on the trash icon at the end of the workflow stage row. In this case, the stage of all stories, with deleted stage, will be moved to Not Defined stage.

Approval

As you are changing the stage of the story you may assign a user or a role to approve the changes and move the story into the next stage. Do this by selecting user/role in the process of changing the stage in the “Workflow Stages” option in the Visual Editor.

app.storyblok.com
A screenshot of how to assign a user to a workflow stage

Storyblok will notify the user(s) assigned to the Story by email if you activate the checkbox Notify users via email. Otherwise, the assigned user(s) will find the notification in the Assigned to me section of the Dashboard only. Learn more about the Dashboard in the Understanding the UI chapter of this guide.

hint:

You can assign multiple users/roles in the approval process.

You may restrict the list of users who have permission to change each stage in the settings of the stage. Read more in the chapter Customization of Workflow stages.

Commenting and Discussions

Storyblok offers the possibility of commenting on each story. You can leave notes for later, or start discussions with your co-editors.

You can leave a new comment at any time, related to any block or field of a story, by clicking on the Start a discussion {1} button inside the Visual Editor. You can also tag another user of the space by typing "@" + their name. Multiple comments can be added to the same discussion, in order to collaborate with other people during the content creation process.

If you want to review all the discussions related to a particular story, you can click on the Discussions {2} link at the top of the Visual Editor.

app.storyblok.com
An annotated screenshot of how to start a discussion on a story
1
2

Schedule Content

Content planning is considered one of the main features of any CMS. Because of this, Storyblok offers multiple ways to schedule the content on multiple levels. The basic approach is to define a special Date/Time field for this purpose, and the more complex way is to use the Releases App, where you can schedule a group of content.

Schedule Content Using the Date/Time Field

In this approach you will define a field which you will use to filter the result of the API in the time of generating your website/app. To achieve this, you need to define a field called Scheduled of type Date/Time in the schema of the content type you want to schedule. Then this field can be used to filter the list of your Stories in the API request. Use the filter queries lt-date and gt-date of Storyblok Delivery API to get the published Stories. You will find an example of this approach in our Delivery API documentation.

hint:

This approach is not dependent on any pricing plan and its complexity depends on solution you need to cover.

Releases App

The Releases app is meant to be used for more advanced workflows and allows you to create/plan a release containing a bundle of content changes, which then can go through different approval stages.

Imagine you want to prepare a group of specific changes in your Stories and release them in three weeks. To do this you can create a release where your changes will live. You can specify a date-time when the release will be published or you are able to trigger the release manually.

required:

Releases is an app available for Teams plan and as any other app has to be installed in the App Store.

How to Create the Release

In the Content section of the Storyblok UI click on the + New release {1} button. In the following overlay window fill in the name of the release {2} and an optional release date and time {3}. You can always change these details later.

app.storyblok.com
An annotated screenshot of how to create a new release
1
2
3
4

A new tab with the name of the release is shown on the top of the content tree after clicking on the Create {4} button. Inside this tab, you will see all the changes made and content created for this release.

learn:

If you want to change the name, release date or any other settings of the release, click on the three dots button next to the name of the release inside the tab.

How to Edit Content in the Release

In the Content section of the Storyblok UI, switch to the tab representing the release you want to add changes in. By default, you will see all stories - not only the ones changed in this release. You can check the Show release content only option If you want to see only the stories created or edited in this release.

app.storyblok.com
A screenshot of how to edit a release

To edit any story in this release, open it in the Visual Editor and apply your changes. After you are done with editing, you can save the changes with the Save & Schedule button.

app.storyblok.com
A screenshot of how to edit a story in a release

How to Merge the Changes of the Release

You can publish the scheduled changes with the master (current) content automatically by planning the release time, or manually by clicking the Publish now button. If any release date-time is planned, you will see it in the box above your content in the release tab.

app.storyblok.com
A screenshot of how to merge the changes from a release

How to Setup a Preview for the Release

The content of a release can be accessed from the Content Delivery API using the draft token and appending the parameter from_release with the release id. In the following example you can see how to get the Story of Home with id 29 in the draft version.

curl -X GET \
'https://api.storyblok.com/v1/cdn/stories/home?from_release=29version=draft&token=miQeEopSce7bklQFVbBozQtt'

We recommend previewing the content of the release using the Storyblok UI and the Preview Tab Functionality in the Visual Editor. If you need to cover a special case that requires a programmatic approach, you can get the full list of all releases from your space using the Management API.

learn:

Check this FAQ answer, for how to access the edited version of a story from a release.

Schedule Part of the Story

If you want to release only a part of the Story, for a short time, consider creating a wrapper component with a date-time field that defines the period when this content is publicly available. You can read more about this approach in the article Render dynamic component depending on dates in Vue.js.

Pipeline

With Storyblok’s pipeline, stages define a strict content staging workflow in your space. This is crucial if you want to create a reliable production environment. You can define multiple stages, each with its own API access token for your content, to preview and test before it goes live.

Storyblok Pipleline

warn:

Don’t confuse the Pipeline stages with Git Branches functionality. This is a very misleading comparison!

Definition of the terms

To better understand the pipeline and the pipeline stages functionality, you should first understand the terms of this section. Please check out the following definition table:

Term Definition
Pipeline Each space can have only one pipeline and every pipeline consist of at least 2 stages. Only the first one, called “Preview” stage, is editable.
Pipeline Stage Pipeline stage contains a frozen content and with the exception of the “Preview” stage, the content of the stage is NOT EDITABLE. The main function of the Pipeline Stage is to preview that frozen content.
“Preview” stage This is the default Pipeline Stage. The content of this stage can be edited and deployed to one or multiple pipeline stages.

Installation

You will find the Pipeline app in the Apps Directory and can install it by clicking the Install button. After the installation is completed, you will notice changes in the Content Area of the Storyblok UI and additional options in the Settings of your Storyblok space.

Definition of the New Pipeline Stage

The setup of the pipeline stages is found in the Settings of your space under the Pipelines {1} tab. You can create, edit and delete all custom pipeline stages except for the Preview Stage. A new pipeline stage can be created by defining the name {2} of the stage and hitting the Add {3} button.

app.storyblok.com
A screenshot of how to create and edit a pipeline stage
1
2
3
4
5

To permanently delete the pipeline stage, click the trash {4} icon. To edit the following settings of the stage, click the cog {5} icon:

Option Description
Name Enables you to edit the name of the pipeline
Preview URL Overrides the URL used in the Visual Editor, if the content from that stage is open in it.
Source of Sync Defines the source pipeline stage, the stage from which (copied) content will be deployed to the stage.

Deploying the Content Between the Stages

It is important to understand that the Pipeline is, from its definition, one way to process the content. Each stage has defined the source stage or, we could say, the point of origin. If you want to deploy content to the next stage, select the stage where you want to deploy it {1}. Next, hit the Deploy from source {2} button and the system starts deploying the content

learn:

The id of the stories will change between the different pipeline stages. If you want to track the story between the pipeline stage, use uuid instead. To learn the difference between the uuid, id and _uid read this FAQ.

app.storyblok.com
A screenshot of how to deploy content between stages of a pipeline
1
2
learn:

Pipeline is a one-way process where content is editable only in the Preview stage and frozen in all other stages.

How to Get an Access Token for the Pipeline Stage

The Pipeline app introduces a new level of specification to the access tokens. With it, you can define the Access level of the key, as well as the Pipeline you want to access. This way you can create an API-key for each Pipeline Stage and be sure that you are not changing or viewing unwanted content.

app.storyblok.com
A screenshot of how to get an access token for a certain pipeline stage

A Real World Scenario

If you want to define a strict multi-stage deployment workflow for your content, use the Pipeline app. The process you are trying to design should be similar to this: Your editors and reviewers are creating the content in the Preview stage. As soon as they are finished with it, the responsible person will deploy the content from the Preview to the Staging stage. This process will freeze the content on Staging and trigger the deployment of the preview app/website. After that, you can share the preview link with the people in your company who do the final decision.

If the final decision is positive, the content can be deployed from Staging to the Live stage. This will make it publicly accessible and the production app/website will be rebuilt/redeployed with new content.

If the final decision is negative, the whole process will return back to the Preview stage, where the editors and reviewers rework the content. The process basically starts from the beginning again.

Flow chart for pipeline handling

warn:

The Pipeline app is not meant to be used to test different versions of the content. You may use the Releases app for that.

Combining Pipeline with Releases App

The Pipeline app was developed with the Releases app in mind. You can select which release should be deployed to the stage in the deployment process of the content. This way you can keep unfinished releases in the Preview stage and also present future release on different pipeline stages.

Illustration pipelines with releases

learn:

You can learn more about the Releases App in this chapter of documentation.

app.storyblok.com
A screenshot of how to pick a release when deploying to a pipeline stage

Combining Pipeline Stages with Workflow Stages

The workflow stage of a story is set to the initial value on the new pipeline stage when deploying the content to it. This generally means that if the workflow stage of the story in Preview is Ready to publish, then we deploy this story to the Staging stage. The workflow stage of the story in Staging will now be set as the initial value of the workflow.