Process Management · SDK TypeScript

O Process Management UI e as apps que executam tarefas falam com o Process Management API através de três pacotes:

Numa app gerada pelo Studio, o bundle Process Management UI instala os três e as páginas de runtime — ver Formulários BPMN.

Cliente HTTPCopy Anchor Link

import { ProcessManagementClient } from "@igrp/platform-process-management-client-ts";

const pm = ProcessManagementClient.create({
  baseUrl: process.env.API_GATEWAY!, // rota do gateway, SEM /api/v1
  timeout: 30000,
  headers: { Authorization: `Bearer ${accessToken}` },
});

O Process Management UI cria um cliente novo por pedido, no servidor, com o token da sessão (auth.getAccessToken()): guardar o cliente num módulo partilharia o token entre utilizadores.

Cada método devolve Promise<ApiResponse<T>> = { data, status, statusText }. As listas vêm em PaginatedResponse<T> (content, pageNumber, pageSize, totalElements, totalPages, first, last).

pm.processesCopy Anchor Link

pm.tasksCopy Anchor Link

pm.areas e pm.activitiesCopy Anchor Link

getAreas, getAreaById, createArea, updateArea, deleteArea, getAreaProcesses, associateProcessToArea, removeProcessFromArea (/areas…); getActivityInstances(instanceId), getActivityProgress(instanceId), getActivityById(id) (/activities…).

Exemplo — iniciar, assumir e concluirCopy Anchor Link

import { ProcessManagementClient, ApiClientError } from "@igrp/platform-process-management-client-ts";

const pm = ProcessManagementClient.create({ baseUrl, headers: { Authorization: `Bearer ${token}` } });

const { data: instance } = await pm.processes.createAndStartProcess({
  processKey: "registo-entidade",
  applicationBase: "registos",
  variables: [{ name: "nomeEntidade", value: "Exemplo Serviços, Lda." }],
});

const { data: tasks } = await pm.tasks.getTasksByProcessInstance(instance.id);
const pedido = tasks.content[0];

try {
  await pm.tasks.claimTask(pedido.id);
  await pm.tasks.completeTask(pedido.id, {
    variables: [{ name: "nif", value: "123456789" }],
  });
} catch (e) {
  if (e instanceof ApiClientError) console.error(e.status, e.details);
}

ErrosCopy Anchor Link

ApiClientError (exportado) tem status (HTTP; 0 em falha de rede ou timeout), message (HTTP Error: <status> <statusText>) e details (corpo da resposta).

Runtime de tarefas (client-ui)Copy Anchor Link

O client-ui desenha a página de uma tarefa: cabeçalho com o número da instância, Guardar e Concluir Tarefa, a barra de passos e o passo atual. As apps usam-no através das páginas do bundle; o essencial:

// process/[...process]/layout.tsx (servidor) — /process/<processKey>/<instância>/<tarefa>/<id>
const config: IGRPProcessClientConfig = {
  baseUrl: process.env.PROCESS_MANAGEMENT_CLIENT_BASE_URL ?? "",
  accessToken: token?.accessToken ?? null,
  taskReturnUrl: processManagementAppHref("my-tasks", process.env.IGRP_APP_PAGE_TASK),
  summaryPage: "/process/resumo",
};

// process/[...process]/page.tsx (cliente)
<IGRPProcessProvider params={params} config={config} resolveStepComponent={resolve}>
  <IGRPProcessPage />
</IGRPProcessProvider>

IGRPProcessProvider recebe params (processKey, processInstanceId — UUID ou número —, userTaskKey, userTaskInstanceId), config, resolveStepComponent e mode (execution | consultation; sem userTaskInstanceId assume consulta só de leitura). Dentro dele, useIGRPProcessContext() dá acesso a stepConfig, completeTask, saveTask, getFormDataForTask, getVariableForTask, readOnly…

Que passo abre — Form KeyCopy Anchor Link

getFormDiscovery(form) traduz a Form Key da tarefa:

Contrato de um passoCopy Anchor Link

O passo recebe { config: IGRPStepComponentConfig } — processKey, processInstanceId, userTaskInstanceId, processName, processNumber, variables, readOnly, onRegisterMethods — e regista dois métodos:

config.onRegisterMethods?.({
  saveStep: async () => ({ success: true, variables, forms }),
  completeStep: async () => ({ success: true, variables, forms }),
});

A página usa o resultado assim: com success: true, envia variables (para o processo) e forms (dados do formulário, { name, value }[]) para saveTask/completeTask; com success: false, mostra error. Os passos gerados pelo Studio já trazem este esqueleto; tu escreves o corpo em handleSave/handleComplete.

DependênciasCopy Anchor Link

• Peers: next 15.5, next-auth 4.24, react/react-dom 19.2.
• Depende diretamente do Design System 0.2.0-beta.3 — numa app com outra versão, força uma só com overrides (ver Formulários BPMN).
• Estilos próprios em @igrp/platform-process-management-client-ui/styles.css (as páginas do bundle não o importam; usam os estilos do Design System da app).