Cómo configurar Stage Gates para flujos de trabajo de sistemas externos

Alcance de este artículo: Este artículo cubre las puertas de Flujo de trabajo externo en las que no hay ninguna aprobación de Fluid configurada — el sistema externo tiene control total sobre la apertura y el cierre de la puerta. Si desea combinar una puerta de Flujo de trabajo externo con una aprobación de Fluid (de modo que el sistema externo active el cierre, pero un aprobador de Fluid deba dar su visto bueno antes de que la puerta se cierre realmente), consulte Puertas de Flujo de trabajo externo emparejadas con aprobaciones.

Las puertas de Flujo de trabajo externo son un tipo de Stage Gate en el que el estado abierto/cerrado es controlado por un sistema externo — no por los usuarios dentro de Fluid. Están diseñadas para escenarios en los que un visto bueno, una aprobación o una decisión ocurre en otra plataforma (como Power Apps, Power Automate, ServiceNow, Jira o Azure DevOps) y esa plataforma escribe el resultado de vuelta en Fluid a través de la API.

Características clave:

• Los Gerentes de Proyecto no pueden cerrar la puerta manualmente — es de solo lectura en el espacio de trabajo de Fluid.

• Si la 'Enabled Blocking Phase Stage Gates' está activada, la puerta bloquea el avance de fase hasta que el sistema externo la cierra.

• Se puede configurar un hipervínculo opcional para darle al GP un enlace en el que se puede hacer clic hacia el sistema externo donde se realiza la acción.

• La puerta admite tres estados: Abierto, En progreso y Cerrado. El sistema externo controla las transiciones entre estos estados a través de la API.

Esto hace que las puertas de Flujo de trabajo externo sean ideales para escenarios de gobernanza en los que necesita evitar la anulación manual y garantizar que la decisión de la puerta se tome en un proceso externo controlado.

---

Las puertas de Flujo de trabajo externo tienen tres estados que reflejan el ciclo de vida de una revisión o aprobación externa:

Un flujo típico es el siguiente:

1. La puerta comienza como Abierto (estado 0) — sin bloquear, sin cerrar.

2. El sistema externo toma la puerta y la establece en En progreso (estado 1) — ahora bloquea el avance de fase si el bloqueo de Stage Gate está habilitado.

3. Una vez que la revisión o aprobación finaliza, el sistema externo la establece en Cerrado (estado 2) — la fase puede avanzar.

Sugerencia: Si su proceso externo no necesita el paso "En progreso", puede pasar directamente de Abierto (0) a Cerrado (2).

---

1. Navegue a Consola de Administración > Stage Gates.

2. Seleccione un Stage Gate existente o cree uno nuevo.

3. Agregue o edite una puerta dentro de una fase.

Configure el campo Modo de puerta en Flujo de trabajo externo.

El hipervínculo le da al Gerente de Proyecto un enlace directo al sistema externo que administra esta puerta. La Expresión de hipervínculo es una expresión dinámica que se resuelve en una URL. Puede incluir campos del proyecto y variables específicas de la puerta.

Guarde la puerta. Los cambios surtirán efecto cuando la puerta se aplique a todos los proyectos. Las puertas que ya estén cerradas en proyectos existentes no se verán afectadas.

---

Cuando configure el hipervínculo o desarrolle su integración externa, trabajará con dos identificadores clave:

En resumen: GateGuid identifica qué definición de puerta es esta (coherente entre proyectos). GateId identifica esta puerta específica en este proyecto específico (único por proyecto).

---

La Expresión de hipervínculo es una expresión dinámica que se resuelve en una URL cuando la puerta se muestra en un proyecto. Puede hacer referencia a cualquier campo del proyecto usando la sintaxis [FieldName], además de las dos variables específicas de la puerta [GateGuid] y [GateId].

• Encierre el texto literal (incluidas las partes de la URL) entre comillas dobles: "https://example.com/"

• Haga referencia a los campos con corchetes: [Id], [GateGuid], [GateId]

• Concatene las partes con +

Puede identificar el proyecto usando cualquiera de estos campos:

Ambos están disponibles en el contexto de la expresión. Elija el que coincida con el endpoint de la API que su sistema externo va a llamar.

Suponga que tiene una app de Power Apps que recopila el visto bueno de una puerta. La app necesita el Id del proyecto y el Id de la puerta para poder llamar al endpoint de la API de flujo de trabajo y actualizar el estado de la puerta cuando el visto bueno se complete.

Expresión de hipervínculo:

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

Cuando un GP ve la puerta en un proyecto con Id 100 y el Id de la puerta a nivel de proyecto es 42, la URL resultante será:

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

Sugerencia: El editor de expresiones en la interfaz de administración de Stage Gate valida su expresión en tiempo real y le muestra qué campos se están referenciando.

---

A medida que su flujo de trabajo externo avanza, el sistema externo debe llamar a la API V3 de Fluid para actualizar el estado de la puerta. Esta es la única forma en que se puede cambiar una puerta de Flujo de trabajo externo.

Hay dos endpoints de la API disponibles:

Opción 1 — Endpoint de flujo de trabajo con compatibilidad para tres estados (recomendado)

Este endpoint le permite establecer la puerta en cualquiera de los tres estados (Abierto, En progreso o Cerrado) usando un único valor numérico en la URL. Utiliza el Id numérico del proyecto ([Id]).

Código

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

No se requiere un cuerpo de solicitud — todos los parámetros están en la ruta de la URL.

Ejemplos:

Establezca la puerta en En progreso:

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

Establezca la puerta en Cerrado:

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

Vuelva a abrir la puerta a Abierto (por ejemplo, si la revisión fue rechazada):

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

Opción 2 — Endpoint basado en GUID (solo abrir/cerrar)

Este endpoint solo admite establecer la puerta como abierta o cerrada (sin el estado "En progreso"). Utiliza el GUID del proyecto ([PrincipalGuid]).

Código

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

Cuerpo de la solicitud:

JSON

{ "isClosed": true }

Para volver a abrir la puerta:

JSON

{ "isClosed": false }

Requisitos (ambos endpoints)

• La llamada a la API debe incluir un token de autenticación válido.

• La identidad que realiza la llamada debe tener al menos acceso de nivel Editor al proyecto.

---

Puede recuperar todas las puertas de un proyecto para consultar el estado actual:

GET /rest/api/stagegates/{projectGuid}

Esto devuelve una lista de todas las puertas, incluyendo su Id, GateMode, IsClosed, IsBlocking y otras propiedades.

Para determinar el estado actual a partir de la respuesta:

---

A continuación, un ejemplo completo que reúne todo lo anterior:

1. El administrador crea una puerta llamada "Revisión de riesgo externa" en la plantilla, establece el Modo de puerta en Flujo de trabajo externo y configura:

   • Gate Title: Completar revisión de riesgo

   • Expresión de hipervínculo: "https://apps.powerapps.com/play/e/default-env/a/risk-review-app?projectId=" + [Id] + "&gateId=" + [GateId]

2. La puerta se propaga a los proyectos. En Proyecto Alfa (Id de proyecto: 100), a la puerta se le asigna el GateId 42. La puerta comienza en el estado Abierto.

3. El Gerente de Proyecto en Proyecto Alfa ve la puerta como Abierto con un enlace en el que se puede hacer clic: "Completar revisión de riesgo". Al hacer clic, se abre: https://apps.powerapps.com/play/e/default-env/a/risk-review-app?projectId=100&gateId=42

4. La Power App abre el formulario de revisión de riesgo. El revisor comienza su evaluación. Al cargarse el formulario, la Power App establece la puerta en En progreso para que la fase quede bloqueada mientras se realiza la revisión:

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

5. El revisor completa su evaluación y la envía. Al enviarla, la Power App (o un flujo de Power Automate activado) establece la puerta en Cerrado:

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

6. La puerta ahora está Cerrado en Fluid. La fase puede avanzar.

Alternativa usando el endpoint basado en GUID: Si su proceso externo no necesita el estado En progreso, puede usar en su lugar el endpoint basado en GUID. En el paso 5, la Power App llamaría a:

Código

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

Esto pasa directamente de Abierto a Cerrado en una sola llamada.

---

¿Puede un Gerente de Proyecto cerrar manualmente una puerta de Flujo de trabajo externo? No. La puerta solo se puede cambiar mediante la API. Esto es intencional para garantizar el control de gobernanza.

¿Cuáles son los tres estados de la puerta? Abierto (estado 0) — la puerta no está bloqueando ni cerrada. En progreso (estado 1) — si el bloqueo de Stage Gate está activado, la puerta bloquea el avance de fase mientras la revisión externa está en curso. Cerrado (estado 2) — la revisión se completó y el avance de fase queda desbloqueado.

¿Tengo que usar los tres estados? No. Si su proceso externo no necesita el paso "En progreso", puede pasar directamente de Abierto (0) a Cerrado (2). También puede usar el endpoint basado en GUID con isClosed: true, lo que cerrará la puerta en una sola llamada.

¿Qué sucede si la definición de la puerta cambia después de la propagación? Las puertas que ya estén cerradas en proyectos existentes no se verán afectadas. Las puertas abiertas adoptarán la nueva configuración.

¿Puedo usar el mismo mecanismo de expresión de hipervínculo en las puertas Informativas? Sí — tanto las puertas Informativas como las de Flujo de trabajo externo admiten la Expresión de hipervínculo. La diferencia es que las puertas Informativas no bloquean y se cierran automáticamente, mientras que las puertas de Flujo de trabajo externo bloquean el avance de fase y requieren una llamada a la API para cerrarse.

¿Qué campos puedo usar en la expresión? Cualquier campo a nivel de proyecto disponible en el contexto de la expresión, además de [GateGuid] y [GateId], que son específicos de la puerta.

¿Cuál es la diferencia entre los dos endpoints de la API? El endpoint de flujo de trabajo (/rest/api/stagegates/workflow/{projectId}/{gateId}/{state}) admite los tres estados (Abierto, En progreso, Cerrado), usa el Id numérico del proyecto y no requiere cuerpo de solicitud. El endpoint basado en GUID (/rest/api/stagegates/{projectGuid}/{gateId}) solo admite abrir/cerrar (sin el estado En progreso) y requiere un cuerpo de solicitud JSON.

¿Puedo volver a abrir una puerta cerrada? Sí. Con el endpoint de flujo de trabajo, envíe el estado 0 (Abierto). Con el endpoint basado en GUID, envíe { "isClosed": false }.