Workflows

Workflows é uma funcionalidade que busca dar controle total sobre o ciclo de vida das APIs.

Você acessa a funcionalidade em Governance  Workflows:

workflows

Na tela, é possível visualizar e criar workflows por times, além de um workflow único para a organização. Os workflows são compostos de estágios que marcam etapas de desenvolvimento das APIs, com requisitos customizáveis para definir as condições de promoção entre os estágios.

Lembre-se dos estilos diferentes de governança, adaptados às necessidades de cada time? Workflows permite com que você coloque isso em prática! Cada time pode ter estágios diferentes, com requisitos diferentes, representando as demandas diversas de desenho de API que operam em seu cenário. E, ao incluir os diferentes workflows em um mesmo local, fica fácil visualizar como cada time trabalha e como a estratégia da organização se desenrola no dia a dia das APIs.

Só é possível criar um workflow por time. Mas pode acontecer do mesmo time executar processos diferentes, por conta do tipo da API ou do tipo da demanda (por exemplo: demanda legal, demanda de inovação, demanda padrão, entre outras, e/ou APIs corporativas, APIs legadas, APIs internas, entre outras). Nesses casos, para cada processo executado, o mesmo time pode ser cadastrado várias vezes — com nomes diferentes e representativos — para ser associado aos seus respectivos workflows.

Exemplo:

Time A - Legal          ->    Workflow Time A - Legal
Time A - Inovação       ->    Workflow Time A - Inovação
Time A - Corporativo    ->    Workflow Time A - Corporativo
Time A - Legado         ->    Workflow Time A - Legado

Funcionamento e tipos de workflows

Um workflow é um organizador do ciclo de vida de uma API. Ele é formado por stages (estágios), cada um definido por uma série de requisitos. Para que uma API seja promovida para o estágio seguinte, deve estar dentro dos padrões definidos para o estágio. Tudo é totalmente personalizável: a quantidade de estágios, seus nomes e requerimentos. Com isso, times diferentes de uma mesma organização podem ter workflows adaptados à sua realidade de desenvolvimento.

Quando você clica sobre um workflow na lista em Governance  Workflows, pode visualizar os estágios diferentes que o compõem e editar o workflow e/ou seus estágios (veja mais sobre isso abaixo). Em cada estágio, você vê as APIs/API Revisions que estão em cada estágio:

workflows stages
Estágios de um workflow

Você define o estágio de uma API nas telas de edição ou criação de uma API, no campo Workflow Stage (e só poderá selecionar um estágio se a API tiver os requisitos estabelecidos para ele):

workflows api stage
Workflow Stage substitui o campo Lifecycle, utilizado nas versões do Manager anteriores à 1909 1.0.0.

Há dois tipos de workflows: Organization Workflow e Team Workflow. Para aumentar o controle a nível de empresa, só é possível existir um único Organization Workflow. É possível ter múltiplos Team Workflows, mas apenas um por time (você pode ler sobre como criar e gerenciar times aqui).

Os workflows que você criar se relacionam ao contexto de APIs, que estabelece as regras de visibilidade para cada API (você pode ver mais sobre isso aqui): O Organization Workflow será aplicado a todas as APIs que são dos contextos organization, teams ou only me que não possuam workflow próprio. Se o contexto de uma API for do tipo teams e o time tiver um workflow cadastrado, os estágios disponíveis para seleção no campo Workflow Stage serão os estágios criados dentro do workflow do time.

Gerenciando workflows

Criando um novo workflow

Só é possível ter um Organization Workflow, que já vem criado (mas que pode ser editado, ver mais sobre isso abaixo). Então, o processo de criação de workflows só se aplica a Team Workflows.

Para criar um novo Team Workflow, clique no botão + no canto inferior direito da tela. Uma janela modal se abrirá para inserção dos dados (veja a imagem abaixo). Informe o nome e uma descrição para o workflow e escolha um time para ele:

workflows create

O card de seu novo workflow estará presente na listagem de Team Workflows, com uma etiqueta identificando o time.

workflows cards

Clicando sobre o novo card, você verá que existe um estágio inicial para o seu workflow, chamado por padrão de "Stage One".

workflows new

Você pode editar o nome desse estágio clicando sobre ele e pode também adicionar novos estágios clicando no botão +:

workflows new stages

Para voltar à página que mostra todos os workflows, clique em VIEW ALL WORKFLOWS.

Clonando um Team Workflow

Esta funcionalidade está disponível a partir da versão 4.6.1.0.

É possível clonar um Team Workflow já existente clicando no ícone icon clone no canto inferior esquerdo do card do workflow a ser clonado.

Esse procedimento criará um novo Team Workflow com os estágios já configurados conforme o workflow clonado.

Ao clicar no ícone icon clone, uma janela modal se abrirá para que sejam informados nome, descrição e o time a qual o novo workflow estará associado:

workflows cloning
O nome do workflow a ser criado deve ser único.
Além disso, o time a ser associado ao novo workflow não pode já estar associado a outro workflow.

Editando um workflow

Todos os workflows podem ser editados, seja o Organization Workflow ou Team Workflows. Para editar um workflow, clique sobre seu card em Governance  Workflows. Você será direcionado à tela de visualização dos estágios, e poderá alterar os campos com texto e os requisitos de cada estágio.

Os campos com texto (nome, time e descrição do workflow e nome dos estágios) são diretamente editáveis. Ou seja, basta clicar sobre o texto desejado para modificá-lo:

workflows edit names

Um workflow não pode existir sem nenhum estágio, então você pode deletar quaisquer estágios, menos o primeiro (que pode, contudo, ser editado). Para deletar um estágio, clique no ícone icon delete grey ao lado do nome.

Não é possível deletar um estágio se ele contiver alguma API.

Editando os requisitos de cada estágio

O ícone icon settings abre a janela de edição dos requisitos do estágio:

workflows stage rules

Nesta janela, você pode definir as condições mínimas para que uma API seja incluída em cada estágio. Os campos de requisitos são:

  • Interceptors: campo para inserir interceptores que devem estar no fluxo das APIs.

  • Environments: campo para selecionar os ambientes em que a API deve ter sido implantada para poder estar no estágio.

  • Attributes: você pode inserir aqui um atributo como necessário às APIs no estágio.

  • API Maturity: campo para determinar a porcentagem mínima de Interface Completeness para as APIs no estágio.

Além dessas regras, é possível determinar ambientes que podem ser habilitados para implantar as APIs que estejam no estágio. Para incluir ambientes em que as APIs podem ser implantadas, adicione-os no campo Deployable Environment.

Sempre que for realizada alguma modificação nas regras de um estágio de um workflow, os times de APIs devem ser notificados para ajustarem as APIs com as novas regras. Algumas dicas para fazer isso:

  • Entre nas APIs daquele estágio e salve-as novamente, fazendo com que a nova regra seja aplicada a elas.

  • Se uma API estiver em produção, não faça os ajustes, espere existir uma nova demanda de evolução e crie uma nova versão da API que conterá as novas regras.

Excluindo workflows

O Organization Workflow não pode ser excluído.

Para remover um Team Workflow, clique no ícone icon delete grey, no card do workflow, na listagem de Governance  Workflows. Isso abrirá uma janela para a confirmação da ação, feita pelo botão Confirm.

Não será possível remover um workflow se ele estiver aplicado a alguma API.
workflows cards

Dicas de uso

Estas não são regras absolutas, mas sim sugestões de uso da funcionalidade:

  • É uma boa prática deixar o estágio de entrada de um workflow (ou seja, o primeiro estágio) sem requerimentos. Assim, todos poderão criar APIs sem restrições. A partir daí, os estágios seguintes podem ter requerimentos progressivamente mais restritivos, que sigam a sua estratégia de APIs e o processo de desenvolvimento do time.

  • Uma regra que ajuda muito a manter o fluxo de "desenvolvimento → homologação → produção" é usar os ambientes de implantação como premissa para criar os estágios dos workflows.

  • Quando fizer alguma modificação nas regras de um estágio que contenha APIs, lembre-se de salvar essas APIs novamente (mesmo que você não faça nenhuma alteração nelas). Isso é necessário para que a nova regra seja aplicada às APIs que já faziam parte do estágio.

Thanks for your feedback!
EDIT

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