How to use status transitions and workflows in OpenProject

OpenProject is a powerful tool, but with great power comes the complexity of customization. If you’re new to OpenProject and having trouble setting up statuses for workflows, you’re not alone. Once you understand how status transitions work in OpenProject and how they depend on roles and work package types, you’ll appreciate their full potential.

Read this article to learn…

• what statuses, roles and workflows are and how they work together,
• why your project management will be much more powerful and efficient with custom workflows,
• how to add a new status and set up a workflow for it.

Let’s dive in!

Nota

April 2026: This article has been updated to reflect the latest improvements in workflow configuration in OpenProject.

Know your terms: Status, role and workflow

Let’s start with some terminology. You will be much faster to create your very own workflows with OpenProject, if you speak its language. So, what are statuses, roles and workflows? And how do they come together?

What is a status in OpenProject?

The status is a key element in every project management. In OpenProject, the status is also an essential attribute of a work package. Based on the status, everyone knows immediately how far the respective work package has progressed.

By default, statuses such as New, In progress or Closed are activated in OpenProject. However, depending on the type of work package, other statuses may be useful. For example, a work package of the type Feature needs the status In test, a work package of the type Blog post rather needs the status In review.

See our system admin guide to learn more about status management for OpenProject.

What are roles in OpenProject?

Roles in OpenProject are extremely important in order to provide each person with exactly the permissions they need - no more, no less. In addition to default roles, administrators can create their own roles and assign them fine-grained permissions.

In addition to permissions for features or project views, admins can also assign specific permissions for status changes in OpenProject roles. Exactly these settings then define a workflow in OpenProject – which we will take a closer look at in the next section.

What is a workflow in OpenProject?

Let’s get back to our example from above: Firstly, we have the status In test, which should be selectable by default for features. Then we have the In review status, which should not be selectable for features, but for work packages of the blog post type.

Now let’s take it a step further and look at the roles and permissions: Let’s say, Luke is a developer and regularly works on features. However, he is not authorized to test features - there is a separate QA team for this. Now it’s suddenly no longer enough to just assign a set of statuses to the work package type Feature, we also need different permissions to activate a status, depending on the role.

This is where workflows come into play. In OpenProject, a workflow defines which status changes are allowed depending on the role and the work package type. In other words: It is not only important what type of work package you are working on, but also who you are. For example, a developer might be allowed to move a work package from In development to Needs testing, while a QA team member can move it from Needs testing to In testing.

With workflows, administrators can control exactly which role is allowed to set which status for which work package.

Nota

Status changes for workflows are configured on a global level via the administration panel: Administration → Work packages → Workflows.

This flexibility is what makes workflows in OpenProject so powerful — but also more complex at first. Instead of having a fixed process, workflows adapt to your roles and work package types, allowing you to model real-life responsibilities in your projects.

The power of customization: Simplify the work for project members

As an administrator, you have the power of defining specific workflows for each role so that project members can perform exactly the status changes they need. The more you customize as an admin at the top, the easier the work becomes for other roles further down in the project.

And remember: You only have to configure these settings once for them to work for years. So grab a coffee and block out a morning to take a closer look at status transitions in OpenProject. Your colleagues and your future work will benefit greatly!

Here’s an example of a typical work setting where status transitions with workflows will be much appreciated:

Let’s take Luke, the developer, from the example above. Now his admin Ivan wants Luke to be able to set work packages of the type Feature from New to In development and then to Needs testing. However, while Luke’s QA colleague Maya should be able to change work package statuses of the type Feature from Needs testing to In testing, this should not be possible for Luke. A role-based permission setting like this allows both the developer Luke and Maya from QA to do their jobs while preventing them from accidentally setting a status for which they have no permission.

This is how the example workflow for the role Developer and the type Feature would look like in OpenProject:

Step-by-step guide: How to add a new status and set up a workflow

Finally, let’s go through the entire process step by step: What settings does admin Ivan need to configure to define the workflows for the work package type Feature – so that each role can perform exactly the status transitions they need to do their job?

Step 1: Create the roles, the status and the work package type you need

If you are specifically looking to create a workflow, you might already have set up the roles, the status and the work package types you need. For our example, admin Ivan would first have to create a work package type called Feature under: Administration → Work packages → Types → New type.

Then he would have to make sure the statuses we described above exist (e.g. Needs testing) – and create new ones, if needed.

He would also have to set up two roles - Developer and QA. This setting can be found under Administration → Users and permissions → Roles and permissions → New role.

Dica

To save some time when creating a new role, we advise you to copy an existing workflow. Please make sure that the new role has the right to change a work package status (or edit work packages, which includes changing the status). You can also copy an existing workflow between roles. For example, you could copy the workflow from the role Developer for the type Feature to the role QA and then adjust only the transitions related to testing.

Step 2: Create and configure the workflow

Now that we have created the roles and the work package type that we want to customize, we can start creating a new workflow under Administration → Work packages → Workflows. For our example, Ivan would have to choose the type Feature.

Next, Ivan needs to select Developer from the dropdown of available roles. He now either sees the statuses that were set for this role in the past. Or, if it’s a completely new role, no status transitions are configured yet, and he can configure them by clicking the + Status button.

Once all required statuses are selected, you’ll see a table with the current status in the rows and the new statuses in the columns.

Please note that all statuses appear twice in the table: the rows show the current status, and the columns show the new status. If the cell at the intersection is checked, the transition is allowed. So, if you want the role to be able to change statuses in both directions, e.g. from New to In progress and also from In progress to New, you have to check the corresponding cells in both directions.

In our example, Ivan wants to make sure that a person with the role Developer cannot set or change a status from or to anything related to testing. If Ivan now unchecks every box that is related to testing, the screen would look like this:

The table shows status transitions enabled or disabled for developers (role) on work packages of the type Feature. As testing features should only be done by QA, these statuses are disabled in the screenshot.

Dica

OpenProject allows admins to define different status transitions depending on whether the user is the author or assignee of the work package. These options can be configured using the tabs at the top of the workflow view and allow you to define more flexible or stricter workflows depending on the situation.

Now, don’t forget to click Save and your workflow is ready!

Dica

You can also use the Summary view to get an overview of all configured status transitions across roles and types.

Wrapping up: More information on how to set up and customize your OpenProject

You have now learned what status, role and workflow mean in OpenProject and how to set up status transitions to support your project and task management. Here’s a quick overview of the tips in this article:

• Before creating a workflow, make sure you have the needed role, status and work package type.
• When creating a new role, copy an existing workflow to save time.

More information on how to set up your OpenProject instance can be found in the system admin guide – on this page you will find a guide to create custom workflows.

OpenProject is an open source project management tool with a wide range of features and a powerful set of customization options. It offers you the tool to create a custom project management just as you need it. And once it’s set up, working with status transitions and other custom features and actions will be fun because it will work easily and be crowned with success.