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 Premium 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 StageDescription
Not Defined / UndefinedIn 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.
DraftingInitial 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.
ReviewingStory is sent to review to one or multiple reviewers (users of the space).
Ready to publishStory 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 Editor of the Storyblok UI with these steps:

  1. Open the Story in Editor view
  2. 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

Visual Editor with open Status tab on the right-hand side

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 the Story in multiple places.

PlaceWhere to find the current stage
Visual Editor / Form-only EditorOn the right-hand side under the tab `Status`.
Content TreeThe stage is shown by a colored line on the left side of the Story name. You can see the name of the stage by hovering over the line.
FilterYou can filter all stories of a selected stage using the filter in the Content section.

Custom Workflows

required:

Custom Workflows are available in the Premium 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 of your space by defining its name and color.

Creation of the new 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.

List of the stage with described icons - (1) Cog - show stage settings, (2) Trash can - Delete stage

You can setup the following properties of the workflow stage.

PropertyDescription
NameA label used to identify the stage.
ColorA RGB code of the color representing the stage.
DefaultIf active, all new Stories will be created within this stage.
Publishing RightsIf active, you may choose a list of the stage, in which you are allowed to publish the story.
Next available stagesIf 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 stageSpecified 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.

Commenting

Storyblok offers commenting on each story with the option to leave the notes for later or to go directly to your co-editors. To reach the comments you open the Story in the Visual or Form-only Editor and then open the Status tab in the right-hand part of the view. There you can click into the comments input and write you comment using the markdown editor.

Example of conversation with open comment as markdown editor

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 status tab in Editor view of the Story.

Example of the changing the stage of the story with filled role to approval

Storyblok will notify the user(s) assigned to the Story by email if you activate the checkbox Notify users via email at the bottom of the form. 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.

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 Premium plan and as any other app has to be install in the App Store.

How to Create the Release

In the Content section of the Storyblok UI click on the button (tab) called + New release. In the following overlay window fill in the name of the release and an optional release date. You can always change the release date later or release the changes manually.

Overlay popup with field to create new release. (1) - Button to create new release, (2) - Name of the release, (3) - Release date (optional)

A new tab with the name of the release is shown on the top of content tree after clicking the Create button. Inside this tab you will see all of the changes made in this release.

learn:

If you want to change the name, release date or any other settings of the release, click on the pen icon next to the name of the release in 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 Stories changed in this release. If you want to see only the Stories edited in this release, activate the checkbox Show only items from this release above the content.

Shows the Stories in the release tab. (1) - Release tab switcher, (2) - Checkbox to show only edited Stories of the release

To edit any Story in this release, open the Story as usual in the Editor and execute your changes. After you are done with editing, you can save the changes in the draft version (Save button), or schedule the changes with the Schedule button.

Visual Editor view with showing the (1) - Save as draft version, (2) - Schedule the changes in the release

Approval Process of the Release

After you are done with all the changes, you may ask one or more users to approve the release. Do this by using the Request approval button in the header of the release.

Showing the content area with the header of release and the button Request Approval

How to Merge Changes of the Release

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

Release with planned release date-time. (1) - Release date, (2) - Release now button

IMPORTANT:

By merging the release only the schedules changes will be merged to the master content. The changes saved as a draft version will not be merged and will be lost in the releasing process.

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:

TermDefinition
PipelineEach 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 StagePipeline 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” stageThis 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 Store (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 settings of your Storyblok space.

Definition of the New Pipeline Stage

Setup of the pipeline stages is found in the Settings of your space under the General 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 of the stage and hitting the add button.

Showing the Pipeline stages settings with input for creation of new one.

To permanently delete the pipeline stage, click the trash icon. To open the following settings of the stage, click the cog icon.

OptionDescription
NameEnables you to edit the name of the pipeline
Preview URLOverrides the URL used in the Visual Editor, if the content from that stage is open in it.
Source of SyncDefines 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 the content to the next stage, enter the tab of that stage to the location where you want to deploy it. Next, hit the Deploy from source 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.

Shows open tab of “staging” pipeline stage and the position of the deploy button.

learn:

Pipeline is a one-way process where content is editable only in the first 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 API-keys. With this API-key you can define the Access level of the key, as well as the Pipeline stage (called Branch in the old times) you want to access. This way you can create an API-key for each Pipeline Stage and be 100% sure that you are not changing or viewing unwanted content.

Shows the API-keys tab with open dropdown for the pipeline stage on API-key form

hint:

If you want to know why we changed the name from Branches to Pipeline App, check out this FAQ entry.

A Real World Scenario

If you want to define a strict multi-stage deployment workflow to 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 stage to the STAGING stage. This process will freeze the content on the STAGING stage 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 the STAGING stage 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 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.

Deploying content to “Staging stage and selecting the releases, which should be deployed with.

Combining Pipeline Stages with Workflow Stages

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