Formulários — Studio IDE

Depois de publicado no Process Studio, cada User Task com Form Key ui:form:* passa a ser um artefacto do processo. No Studio IDE esses artefactos viram passos (steps): componentes React gerados no teu projeto Next.js, desenhados no Page Builder como qualquer página. Em runtime, o Process Management abre o passo certo para cada tarefa.

O fluxo tem quatro partes:

1. Ligar o separador BPMN do projeto ao Process Studio.
2. Gerar um passo por artefacto e desenhar o formulário.
3. Escrever o handleComplete, que devolve as variáveis ao processo.
4. Instalar o bundle Process Management UI, que traz as páginas de runtime.

O exemplo continua o Registo de Entidade, num projeto Next.js chamado registos.

Ligar o Studio IDE ao Process StudioCopy Anchor Link

No projeto, abre o separador BPMN e clica em API → Add. A configuração aponta para o API do Process Studio, através do gateway do workspace.

Clica em Test Connection e depois em Save.

Escolher o processoCopy Anchor Link

Em Select Project escolhe o projeto do Process Studio (Registos · REGISTOS). A lista mostra só os processos publicados, com a versão e o número de artefactos.

Clica no processo para ver os Process Artifacts: um por cada User Task com ui:form:*, com o ID da tarefa, a versão e a Form Key.

Gerar o passoCopy Anchor Link

Num artefacto novo o botão diz Generate Step. Ao clicar, confirma a descrição e o nome do componente:

O Studio cria dois ficheiros e o botão passa a Open Editor:

No exemplo: (registo-entidade)/pedido.v1.tsx e (registo-entidade)/qualificacao.v1.tsx.

Desenhar o formulárioCopy Anchor Link

Open Editor abre o passo no Page Builder. Começa por arrastar um Form (em Contentores): traz um Headline e uma Grid. Depois arrasta os campos para a grid e configura cada um na roda dentada da barra do componente — o nome (primeiro campo do painel) é a chave do valor no formulário, e é esse nome que chega ao processo como variável.

Associar o Form a um esquema (obrigatório)Copy Anchor Link

Seleciona o Form (pela margem) e abre Binding Config na barra do componente. Em New, com Definição → Auto, o Studio propõe um esquema com os campos que já estão no Form: dá-lhe um nome (pedido, qualificacao) e marca os obrigatórios. Guardar alterações gera o esquema zod e liga-o ao Form (schema={pedido}).

O Select Decisão tem as opções que o gateway espera: RECTIFICAR, CONFIRMAR e REJEITAR.

Devolver as variáveis ao processoCopy Anchor Link

Cada passo gerado regista dois métodos no runtime: saveStep (guardar sem concluir) e completeStep (concluir a tarefa). Eles chamam as funções handleSave e handleComplete, que se editam em Código Personalizado → Functions (lápis).

O handleComplete lê os valores do Form e devolve-os como variáveis:

const data = formform1Ref.current?.getValues();

const variables = data
  ? Object.entries(data).map(([key, value]) => ({
      name: key,
      value: value as string,
    }))
  : [];

return {
  success: true,
  variables,
  forms: undefined,
};

Ao concluir a Qualificação, a variável decision fica no processo e o gateway escolhe o caminho: RECTIFICAR volta ao Pedido, CONFIRMAR ou REJEITAR terminam.

As variáveis ficam disponíveis em todos os passos seguintes:

• Gateways — nas condições (${decision == 'RECTIFICAR'}).
• Service Tasks — como parâmetros dos delegates.
• Outros passos — em config.variables, para pré-preencher ou mostrar dados de passos anteriores.

Grava com Salvar para regenerar o .tsx.

Instalar o runtime de processosCopy Anchor Link

Os passos são só componentes; quem os abre é a página process/[...process] da app. Essa página vem no bundle Process Management UI: no projeto, separador Bundles → Discover → Process Management UI → Instalar.

O bundle adiciona os pacotes @igrp/platform-process-management-client-ts, -client-ui e -types e copia para src/app/(igrp)/(generated)/process/:

A app precisa de saber onde está o API do Process Management:

# Rota do gateway para o process-management-api (sem /api/v1: os recursos ficam na raiz)
PROCESS_MANAGEMENT_CLIENT_BASE_URL=http://<slug>:2575/gateway-api/<serviço>-process-management-api
# Para onde volta o botão "Voltar" depois de concluir (Minhas Tarefas do Process Management)
IGRP_APP_PAGE_TASK=http://<slug>:2575/apps/igrp-process-management

Para avisar quem trata a etapa seguinte (IN_APP), a app precisa também do acesso ao Notification Service — ver Notificações de tarefas.

allowBuilds:
  '@parcel/watcher': false
  '@swc/core': false

overrides:
  '@igrp/igrp-framework-react-design-system': 0.2.0-beta.8

Executar a tarefaCopy Anchor Link

Quando o Process Management abre uma tarefa, a app mostra o cabeçalho do processo (número da instância, Guardar e Concluir Tarefa), a barra de passos e o formulário do passo atual:

Guardar chama saveStep; Concluir Tarefa chama completeStep — o teu handleComplete — e envia as variáveis. Na Qualificação, a decisão escolhida segue o caminho do gateway:

Com Retificar, o Pedido volta a ficar ativo com os valores anteriores; com Confirmar ou Rejeitar, a instância termina. As variáveis ficam visíveis no detalhe da instância.

Próximo passoCopy Anchor Link

Com os passos gerados e o runtime instalado, associa o processo a uma área cuja Aplicação seja esta app e inicia instâncias no Process Management.