Workflows

Workflows is a feature that seeks to give total control over the API lifecycle.

You access it on Governance Workflows:

On the screen, you can view and create workflows by teams, in addition to a single workflow for the organization. Workflows are composed of stages, which mark API development steps, with customizable requirements to define promotion conditions between stages.

Remember the different governance styles, adapted to the needs of each team? Workflows allows you to put that into practice! Each team can have different stages, with specific requirements, representing the different API design demands that operate in their scenario. And, by including the different workflows in the same place, it is easy to see how each team works and how the organization’s strategy unfolds in the day to day lives of APIs.

It is only possible to create one workflow per team. But it may happen that the same team executes different processes, due to the type of API or the type of demand (for example: legal demand, innovation demand, standard demand, among others, and/or corporate APIs, legacy APIs, internal APIs, among others). In these cases, for each process executed, the same team must be registered several times — with different and representative names — to be associated with their respective workflows.

Example:

Team A - Legal        ->    Workflow Team A - Legal
Team A - Innovation   ->    Workflow Team A - Innovation
Team A - Corporate    ->    Workflow Team A - Corporate
Team A - Legacy       ->    Workflow Team A - Legacy

Types of workflows and how they work

A workflow organises the API lifecycle. It consists of stages, each defined by a series of requirements. For an API to be promoted to the next stage, it must be within the standards defined for the stage. Everything is fully customizable: the number of stages, their names and requirements. With that, different teams from the same organization can have workflows adapted to their development reality.

When you click on a workflow in list on Governance Workflows, you see the different stages that comprise it and you can edit the workflow and/or its stages (see more about this below). At each stage, you see the APIs/Revisions that are at it:

Stages of a workflow

You define the stage of an API on an API’s editing or creation screens, in the field Workflow Stage (and you can only select a stage if the API has the requirements set for it):

Workflow Stage replaces the Lifecycle field, used in Manager versions prior to 1909 1.0.0.

There are two types of workflows: Organization Workflow and Team Workflow. To increase control at the company level, there can only be a single Organization Workflow. You can create multiple Team Workflows, but only one per team (you can read about creating and managing teams here).

The workflows you create relate to API context, which establishes the visibility rules for each API (you can see more about that here): The Organization Workflow will be applied to all APIs set to organization, teams or only me contexts that do not have their own workflow. If the context of an API is set to teams and the team has a registered workflow, the stages available for selection in the Workflow Stage field will be the stages created within the team’s workflow.

Managing workflows

Creating a new workflow

There can only be one Organization Workflow, which comes by default (but which can be edited, see more about it below). Thus, the workflow creation process only applies to Team Workflows.

To create a new Team Workflow, click on the + button in the bottom right corner of the screen. A modal window will open up for you to enter the data (see the image below). Enter the name and description for the workflow and choose a team for it:

A card for your new workflow will be present in the list of Team Workflows, with a tag identifying the team.

By Clicking on the card, you’ll see that there is an initial stage for your workflow, called "Stage One" by default.

You can edit the name of this stage by clicking on it and you can also add new stages by clicking the + button:

To return to the page showing all workflows, click on VIEW ALL WORKFLOWS.

Cloning a Team Workflow

This feature is available from version 4.6.1.0.

It is possible to clone an existing Team Workflow by clicking on the icon icon clone in the lower left corner of the card of the workflow to be cloned.

This will create a new Team Workflow with the stages already configured according to the cloned workflow.

By clicking on the icon icon clone , a modal window will open so that you can enter the name, description and the team to which the new workflow will be associated:

The name of the workflow to be created must be unique.
In addition, the team to be associated with the new workflow cannot already be associated with another workflow.

Editing a workflow

All workflows can be edited, the Organization Workflow or Team Workflows. To edit a workflow, click its card on Governance Workflows. You will be taken to the stage display screen, and you can modify the text fields and requirements for each stage.

Text fields (name, team and workflow description, and name of stages) are directly editable (just click on the desired text to modify it):

A workflow cannot exist without any stages, so you can delete all stages but the first (which can, however, be edited). To delete a stage, click the icon delete grey icon next to its name.

A stage can’t be deleted if it contains an API.

Editing the requirements for each stage

The icon settings icon opens the stage requirements edit window:

In this window, you can define the minimum conditions for an API to be included at each stage. The requirement fields are:

Interceptors: field to select interceptors that must be in API flows.
Environments: field to select the environments to which the API must have been deployed to be in the stage.
Attributes: you can enter attributes that APIs on the stage must have.
API Maturity: field to determine the minimum Interface Completeness percentage for the APIs in the stage.

In addition to these rules, it is possible to determine environments that can be enabled to deploy APIs that are in the stage. Add these environments to the Deployable Environment field.

Whenever a change is made to the rules of a workflow stage, the API teams should be notified to adjust the APIs to the new rules. Some tips on how to do this:

Enter the APIs of that stage and save them again, causing the new rule to be applied to them.
If an API is in production, don’t make adjustments, wait for a demand for a new evolution and create a new version of the API that will contain the new rules.

Deleting workflows

The Organization Workflow can’t be deleted.

To delete a Team Workflow, click on the icon delete grey icon, inside the workflow’s card on Governance Workflows. This will open a window to confirm the action.

A workflow can’t be deleted if it contains APIs.

Tips

These are not fundamental rules but suggestions on how to use the feature:

It’s good practice to leave the entry stage of a workflow (i.e., the first stage) without requirements. Thus, everyone will be able to create APIs with no initial restrictions. From there, the following stages should have progressively restrictive requirements, following your API strategy and the team’s development process.
A helpful rule of thumb to keep the "development → staging → production" flow easier to maintain is using deployment environments as a premise to create workflow stages.
If you make any changes to the requirements of a stage that contains APIs, remember to save those APIs again (even if you don’t modify them). Only then will the new rule apply to the APIs that were already at that stage.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]