Como configurar Stage Gates para Workflows de Sistemas Externos

Escopo deste artigo: Este artigo aborda gates de Fluxo de Trabalho Externo onde nenhuma aprovação do Fluid está configurada — o sistema externo tem controle total sobre a abertura e o fechamento do gate. Se você deseja combinar um gate de Fluxo de Trabalho Externo com uma aprovação do Fluid (para que o sistema externo acione o fechamento, mas um aprovador do Fluid precise dar o aval antes que o gate seja efetivamente fechado), consulte Gates de Fluxo de Trabalho Externo Combinados com Aprovações.

Os gates de Fluxo de Trabalho Externo são um tipo de gate de fase cujo status aberto/fechado é controlado por um sistema externo — não por usuários dentro do Fluid. Eles são projetados para cenários em que uma aprovação, validação ou decisão ocorre em outra plataforma (como Power Apps, Power Automate, ServiceNow, Jira ou Azure DevOps) e essa plataforma grava o resultado de volta no Fluid via API.

Características principais:

• Os Gerentes de Projeto não podem fechar o gate manualmente — ele é somente leitura no workspace do Fluid.

• Se a configuração 'Habilitar Bloqueio de Gates de Fase' estiver ativada, o gate bloqueia a progressão de fase até que o sistema externo o feche.

• Um hiperlink opcional pode ser configurado para fornecer ao GP um link clicável para o sistema externo onde a ação ocorre.

• O gate suporta três estados: Aberto, Em Andamento e Fechado. O sistema externo controla as transições entre esses estados via API.

Isso torna os gates de Fluxo de Trabalho Externo ideais para cenários de governança onde você precisa impedir substituições manuais e garantir que a decisão do gate seja tomada em um processo externo controlado.

Os gates de Fluxo de Trabalho Externo têm três estados que refletem o ciclo de vida de uma revisão ou aprovação externa:

Um fluxo típico é assim:

1. O gate começa como Aberto (estado 0) — sem bloqueio, não fechado.

2. O sistema externo assume o gate e o define como Em Andamento (estado 1) — agora bloqueando a progressão de fase se o bloqueio de gate de fase estiver habilitado.

3. Assim que a revisão/aprovação for concluída, o sistema externo o define como Fechado (estado 2) — a fase pode progredir.

Dica: Se o seu processo externo não precisar da etapa "Em Andamento", você pode ir diretamente de Aberto (0) para Fechado (2).

1. Navegue até Console de Administração > Gates de Fase.

2. Selecione um gate de fase existente ou crie um novo.

3. Adicione ou edite um gate dentro de uma fase.

Defina o campo Modo do Gate como Fluxo de Trabalho Externo.

O hiperlink fornece ao Gerente de Projeto um link direto para o sistema externo que gerencia este gate. A Expressão de Hiperlink é uma expressão dinâmica que resolve para uma URL. Ela pode incluir campos do projeto e variáveis específicas do gate.

Salve o gate. As alterações entrarão em vigor quando o gate for aplicado a todos os projetos. Os gates que já estão fechados em projetos existentes não serão afetados.

Ao configurar o hiperlink ou construir sua integração externa, você trabalhará com dois identificadores principais:

Em resumo: GateGuid identifica qual definição de gate é esta (consistente entre projetos). GateId identifica este gate específico neste projeto específico (único por projeto).

A Expressão de Hiperlink é uma expressão dinâmica que resolve para uma URL quando o gate é exibido em um projeto. Você pode referenciar qualquer campo do projeto usando a sintaxe [NomeDoCampo], além das duas variáveis específicas do gate [GateGuid] e [GateId].

• Envolva texto literal (incluindo partes da URL) entre aspas duplas: "https://example.com/"

• Referencie campos com colchetes: [Id], [GateGuid], [GateId]

• Concatene partes com +

Você pode identificar o projeto usando qualquer um destes campos:

Ambos estão disponíveis no contexto de expressão. Escolha aquele que corresponde ao endpoint da API que seu sistema externo irá chamar.

Suponha que você tenha um aplicativo Power Apps que coleta uma aprovação de gate. O aplicativo precisa do Id do projeto e do Id do gate para poder chamar o endpoint da API de workflow e atualizar o estado do gate quando a aprovação for concluída.

Expressão de Hiperlink:

"https://apps.powerapps.com/play/e/your-environment-id/a/your-app-id?projectId=" + [Id] + "&gateId=" + [GateId]

Quando um GP visualiza o gate em um projeto com Id 100 e o Id do gate no nível do projeto é 42, a URL resolvida será:

https://apps.powerapps.com/play/e/your-environment-id/a/your-app-id?projectId=100&gateId=42

Dica: O editor de expressões na UI de Administração de Stage Gate valida sua expressão em tempo real e mostra quais campos estão sendo referenciados.

Assim que seu workflow externo avançar, o sistema externo deve chamar a API do Fluid V3 para atualizar o estado do gate. Esta é a única forma de alterar um gate de Workflow Externo.

Há dois endpoints de API disponíveis:

Opção 1 — Endpoint de workflow com suporte a três estados (recomendado)

Este endpoint permite definir o gate para qualquer um dos três estados (Aberto, Em Andamento ou Fechado) usando um único valor numérico na URL. Ele utiliza o Id numérico do projeto ([Id]).

Código

PUT /rest/api/stagegates/workflow/{projectId}/{gateId}/{state}

Nenhum corpo de requisição é necessário — todos os parâmetros estão no caminho da URL.

Exemplos:

Definir o gate como Em Andamento:

PUT https://your-fluid-instance.com/rest/api/stagegates/workflow/100/42/1

Definir o gate como Fechado:

PUT https://your-fluid-instance.com/rest/api/stagegates/workflow/100/42/2

Reabrir o gate para Aberto (por exemplo, se a revisão foi rejeitada):

PUT https://your-fluid-instance.com/rest/api/stagegates/workflow/100/42/0

Opção 2 — Endpoint baseado em GUID (somente aberto/fechado)

Este endpoint suporta apenas a definição do gate como aberto ou fechado (sem estado "Em Andamento"). Ele utiliza o GUID do projeto ([PrincipalGuid]).

Código

PUT /rest/api/stagegates/{projectGuid}/{gateId}

Corpo da Requisição:

JSON

{ "isClosed": true }

Para reabrir o gate:

JSON

{ "isClosed": false }

Requisitos (ambos os endpoints)

• A chamada de API deve incluir um token de autenticação válido.

• A identidade que faz a chamada deve ter pelo menos acesso de nível Editor ao projeto.

Você pode recuperar todos os gates de um projeto para verificar o estado atual:

GET /rest/api/stagegates/{projectGuid}

Isso retorna uma lista de todos os gates, incluindo seus Id, GateMode, IsClosed, IsBlocking e outras propriedades.

Para determinar o estado atual a partir da resposta:

Aqui está um exemplo completo e detalhado que une tudo:

1. Administrador cria um gate chamado "Revisão de Risco Externo" no template, define o Modo do Gate como Workflow Externo e configura:

   • Título do Gate: Concluir Revisão de Risco

   • Expressão de Hiperlink: "https://apps.powerapps.com/play/e/default-env/a/risk-review-app?projectId=" + [Id] + "&gateId=" + [GateId]

2. O gate é propagado para os projetos. No Projeto Alpha (Id do Projeto: 100), o gate recebe o GateId 42. O gate começa no estado Aberto.

3. O Gerente de Projeto do Projeto Alpha vê o gate como Aberto com um link clicável: "Concluir Revisão de Risco". Ao clicar, abre: https://apps.powerapps.com/play/e/default-env/a/risk-review-app?projectId=100&gateId=42

4. O Power App abre o formulário de revisão de risco. O revisor inicia sua avaliação. Ao carregar o formulário, o Power App define o gate como Em Andamento para que a fase fique bloqueada enquanto a revisão ocorre:

   PUT https://your-fluid-instance.com/rest/api/stagegates/workflow/100/42/1
   

5. O revisor conclui sua avaliação e envia. Ao enviar, o Power App (ou um fluxo do Power Automate acionado) define o gate como Fechado:

   PUT https://your-fluid-instance.com/rest/api/stagegates/workflow/100/42/2
   

6. O gate agora está Fechado no Fluid. A fase pode avançar.

Alternativa usando o endpoint baseado em GUID: Se o seu processo externo não precisar do estado Em Andamento, você pode usar o endpoint baseado em GUID. Na Etapa 5, o Power App chamaria:

Código

PUT https://your-fluid-instance.com/rest/api/stagegates/abc-123/42
Body: { "isClosed": true }

Isso vai diretamente de Aberto para Fechado em uma única chamada.

Um Gerente de Projeto pode fechar manualmente um portão de Fluxo de Trabalho Externo? Não. O portão só pode ser alterado via API. Isso é intencional para garantir o controle de governança.

Quais são os três estados do portão? Aberto (estado 0) — o portão não está bloqueando e não está fechado. Em Andamento (estado 1) — se o bloqueio do portão de fase estiver ativado, o portão está bloqueando a progressão de fase enquanto a revisão externa está em andamento. Fechado (estado 2) — a revisão está concluída e a progressão de fase está desbloqueada.

Preciso usar os três estados? Não. Se o seu processo externo não precisar de uma etapa "Em Andamento", você pode ir diretamente de Aberto (0) para Fechado (2). Você também pode usar o endpoint baseado em GUID com isClosed: true que fechará o portão em uma única chamada.

O que acontece se a definição do portão for alterada após a propagação? Os portões que já estão fechados em projetos existentes não serão afetados. Os portões abertos adotarão a nova configuração.

Posso usar o mesmo mecanismo de expressão de hiperlink em portões Informativos? Sim — os portões Informativos e de Fluxo de Trabalho Externo suportam Expressão de Hiperlink. A diferença é que os portões Informativos são não bloqueantes e fechados automaticamente, enquanto os portões de Fluxo de Trabalho Externo bloqueiam a progressão de fase e exigem uma chamada de API para fechar.

Quais campos posso usar na expressão? Qualquer campo de nível de projeto disponível no contexto da expressão, além de [GateGuid] e [GateId] que são específicos do portão.

Qual é a diferença entre os dois endpoints de API? O endpoint de fluxo de trabalho (/rest/api/stagegates/workflow/{projectId}/{gateId}/{state}) suporta os três estados (Aberto, Em Andamento, Fechado), usa o Id numérico do projeto e não requer corpo de requisição. O endpoint baseado em GUID (/rest/api/stagegates/{projectGuid}/{gateId}) suporta apenas aberto/fechado (sem estado Em Andamento) e requer um corpo de requisição JSON.

Posso reabrir um portão fechado? Sim. Usando o endpoint de fluxo de trabalho, envie o estado 0 (Aberto). Usando o endpoint baseado em GUID, envie { "isClosed": false }.