fluigcli request — solicitações de workflow

O grupo request consulta, inicia, movimenta, cancela e observa solicitações direto do terminal. Uma solicitação é uma instância de processo. Este é o primeiro grupo de Operação da CLI. Você usa a plataforma no dia a dia. Você não faz deploy de artefatos aqui. Os comandos usam a REST v2 process-management. O start com anexo usa o SOAP startProcess, pois a REST não tem upload de anexo. O observe usa o fluigcliHelper, pois a REST não tem comentário sem movimentar.

`fluigcli request list [flags]`

Este comando busca solicitações do servidor. Ele lista das mais recentes para as mais antigas. A tabela mostra número, processo, etapa atual, status, SLA, solicitante e início. O comando obtém a etapa atual da movimentação corrente. As solicitações OPEN aparecem em verde.

Flag	Uso
`--process <id>`	filtra pelo processo (`processId` do `workflow list`)
`--status s`	`open`, `canceled` ou `finalized`
`--sla s`	`on_time`, `warning` ou `expired`
`--assignee <login>`	responsável atual pela tarefa
`--requester <login>`	solicitante
`--limit N`	máximo de solicitações (default 50; 0 = todas)

fluigcli request list --process compras_solicitacao --status open
fluigcli request list --assignee jsilva --sla expired
fluigcli request list --limit 0 --json          # todas, para agentes/CI

Compatibilidade Fluig 1.8 × 2.0

A CLI obtém a "etapa atual" de formas diferentes conforme a versão do servidor. Ela detecta a versão por /api/public/wcm/version. No Fluig 2.0+, a etapa vem do expand currentMovements. No Fluig 1.8, esse campo não existe na API. Neste caso, a CLI usa o expand activities e considera a atividade ativa (active=true). O resultado (currentSteps no --json) é idêntico nas duas versões. Nada muda para quem consome o comando.

`fluigcli request show <número>`

Este comando mostra uma solicitação. Ele mostra processo/versão, status, solicitante, período e etapa atual. Ele também mostra a tabela de movimentação. Esta tabela é o histórico completo de tarefas. Ela traz responsável, status e datas. A tarefa em aberto aparece em verde.

fluigcli request show 196522
fluigcli request show 196522 --json    # request + tasks estruturados

Solicitação inexistente → exit 4.

`fluigcli request start <processId> [flags]`

Este comando inicia uma solicitação. Ele abre e envia a solicitação. Ele preenche o formulário com os --field. Os eventos do processo rodam no servidor normalmente. Um throw de evento volta como mensagem de erro (exit 5).

⚠️ Os eventos do formulário não rodam

A CLI grava o card pela API REST. Neste caminho, o servidor não executa os eventos do formulário. O displayFields e o validateForm ficam de fora. O beforeSendValidate é client-side e também não roda. Os eventos do processo, esses sim, rodam.

O card recebe só os valores que você enviou. Uma solicitação com os campos obrigatórios vazios é aceita sem crítica. Por isso, não use este comando para testar a validação do formulário. O teste passa e você conclui, errado, que a validação está correta. Para exercitar a validação, use o navegador ou o fluigcli dev.

O mesmo vale para o request move e para o form records create e form records update (ver form).

Flag	Uso
`--field campo=valor`	campo do formulário (pode repetir; sobrepõe o `--fields-file`)
`--fields-file <arq \| ->`	campos em JSON plano `{"campo":"valor"}`; `-` lê do stdin
`--attach <arquivo>`	anexa o arquivo à solicitação (pode repetir)
`--comment "..."`	comentário do movimento
`--target-state N`	etapa de destino (sequence); com `--attach`/`--no-send` informe-a
`--assignee <login>`	responsável pela próxima atividade (precisa ser apto pelo mecanismo)
`--no-send`	cria sem enviar — fica na atividade inicial, com você

fluigcli request start compras_solicitacao --field descricao="Teclado novo" --comment "via CLI"
fluigcli request start compras_requisicao_abastecimento \
  --field codEquipamento=1084 --field quantidade=10 ... \
  --attach hodometro.png --target-state 5

Campos por JSON (`--fields-file`)

Alguns formulários têm muitos campos. Nestes casos, passe os campos como um objeto JSON plano em vez de repetir --field. Este formato também ajuda agentes de IA e CI. A CLI converte valores numéricos e booleanos para a string que a API espera. A CLI rejeita objetos e arrays aninhados com erro claro.

# 1. arquivo — bom para versionar a solicitação de teste no Git do projeto
cat > requisicao.json <<'EOF'
{
  "codColigada": 1,
  "codCCusto": "001.002.020.0001",
  "codEquipamento": 1084,
  "veiculoEquipamento": "(1084) FIAT UNO ECONOMY",
  "codMotorista": 206,
  "codPontoAbast": 2,
  "hodometro": 45210,
  "codMaterial": 3,
  "quantidade": 10
}
EOF
fluigcli request start compras_requisicao_abastecimento \
  --fields-file requisicao.json --attach hodometro.png --target-state 5

# 2. stdin — o modo natural para pipelines e agentes
echo '{"descricao":"Teclado novo","quantidade":"1"}' | \
  fluigcli request start compras_solicitacao --fields-file -

# 3. template + variação: o arquivo é a base e o --field sobrepõe um campo
fluigcli request start compras_requisicao_abastecimento \
  --fields-file requisicao.json --field quantidade=20 --attach h.png --target-state 5

Linhas de tabela-filha (`campo___N`)

O JSON continua plano quando o formulário tem tabela-filha. Escreva o nome do campo com o sufixo ___<linha> (três underscores). O índice da linha começa em 1. Esta é a convenção do próprio Fluig. A API usa o mesmo sufixo quando você lê o card (ver form).

json

{
  "numeroNotificacaoAuto": "TESTE-001",
  "anxNotificacaoFileId___1": "1247035",
  "anxNotificacaoNome___1": "Notificação nº TESTE-001.pdf",
  "anxNotificacaoFileId___2": "1247099",
  "anxNotificacaoNome___2": "Anexo 2.pdf"
}

Cada índice cria uma linha. O exemplo acima cria duas linhas na tabela. Você não informa o nome da tabela: o Fluig descobre a tabela pelo nome do campo.

Confira o resultado com form records show <form> <cardId>. As linhas saem agrupadas por tableId, com o rowId que casa com o índice que você enviou.

Este é o caminho para testar um processo que exige anexo em tabela-filha.

O request move aceita as mesmas flags (--fields-file/--field). Use-as para atualizar campos do formulário no movimento.

echo '{"aprNivel1":"aprovado","comentarioNivel1":"ok"}' | \
  fluigcli request move 196542 --target-state 13 --fields-file -

⚠️ --assignee em atividade de pool: se a atividade destino usa Pool (Papel/Grupo), ela recebe o pool, não uma pessoa — o servidor recusa com "Usuário selecionado não encontrado", mesmo com o login certo e o usuário no papel. A CLI explica o caso: no move, ela consulta os candidatos reais e nomeia o pool; no start, dá a orientação geral. A correção é omitir--assignee (a tarefa nasce no pool; assuma depois com task assume).

⚠️ Anexos: a REST v2 não tem upload de anexo de solicitação. Ela só faz download. Alguns processos exigem anexo no início. Um exemplo é o hAPI.listAttachments() no beforeTaskSave. Estes processos só iniciam com --attach. Neste caso, a CLI troca para o SOAP startProcess automaticamente. A atividade seguinte pode exigir a escolha de responsável (HTTP 412). Neste caso, a CLI lista as opções e pede --assignee.

`fluigcli request move <número> [flags]`

Este comando conclui a tarefa corrente e envia a solicitação adiante. Sem --movement, a CLI descobre a tarefa em aberto sozinha. Flags: --target-state, --assignee, --comment, --field (atualiza campos do formulário no movimento) e --movement.

⚠️ Como no request start, os eventos do formulário não rodam neste caminho. Os eventos do processo rodam.

fluigcli request move 196542 --target-state 5 --comment "enviado via CLI"
fluigcli request move 196542 --target-state 13 --field aprNivel1=aprovado

⚠️ Você só movimenta a sua tarefa. A solicitação cuja tarefa aberta é de outro usuário responde 404. Neste caso, o servidor a esconde. Este é o comportamento real. Para movimentar a tarefa de outro responsável, use --manager (abaixo).

Modo gestor (`--manager`)

--manager conclui a tarefa corrente mesmo quando ela não é sua. Ele usa o SOAP saveAndSendTask com managerMode=true. Este é o único caminho para destravar uma solicitação parada em atividade automática (service task) que já executou e falhou na transição de saída. Por exemplo: o beforeStateEntry da etapa de destino lançou erro. O motor não reagenda essa atividade. O request move normal responde NO_HUMAN_TASK.

fluigcli request move 228691 --manager                     # destino = única saída da etapa
fluigcli request move 228691 --manager --target-state 80   # destino explícito
fluigcli request move 228691 --manager --yes --json        # agentes/CI

Regras do modo gestor:

Sem --target-state, a CLI lê o diagrama da versão do processo e usa a única saída da etapa corrente. Com mais de uma saída, ela lista as opções e responde exit 2 com data.options[] (targetState, label, default).
O motor avalia gateways normalmente a partir do destino informado. Por isso, a etapa final pode ser outra. O resultado traz nextState (onde a solicitação parou), nextAssignee e processLink.
Os eventos de processo da etapa de destino rodam (beforeStateEntry...). ⚠️ O "usuário corrente" desses eventos vem vazio. Ele não é o solicitante.
O comando pede confirmação. Em modo não-interativo, use --yes.
--manager não aceita --field, --fields-file nem --assignee. A tarefa segue como está. Use --thread para um ramo paralelo (default 0).
Requer permissão de gestor do processo ou administrador.

Para achar as solicitações nesse estado, use fluigcli task list --automatic.

Quando o 404 não quer dizer "não existe"

O servidor responde 404 no move em três situações diferentes. A CLI consulta as tarefas da solicitação e devolve um código próprio para cada uma. O exit code é 4 nos três casos.

Código no envelope	Significado	O que fazer
`POOL_TASK_NOT_ASSIGNED`	a tarefa está num pool e ninguém a assumiu	`fluigcli task assume <número>` (requer pertencer ao pool)
`NO_HUMAN_TASK`	a etapa corrente é automática (service task)	se a atividade ainda executa, aguarde; se ela já executou e a transição falhou (veja `log tail --grep <número>`), use `request move <número> --manager`
`NOT_FOUND`	a solicitação não existe, ou a tarefa é de outro usuário	confira o número

A mensagem traz a etapa e o nome do pool:

json

{"code":"POOL_TASK_NOT_ASSIGNED",
 "message":"a tarefa corrente da solicitação 230702 (etapa 21, \"Acompanhar Retornos\")
            está no pool Sucesso do Cliente (Pool:Role:sucesso_cliente) e ninguém a assumiu;
            assuma com: fluigcli task assume 230702"}

A consulta extra roda só quando o move falha. O caminho de sucesso não muda.

Quando a CLI pede `--movement`

A etapa corrente pode ter mais de uma tarefa no mesmo movimento. Um exemplo é a tarefa do pool mais a tarefa do usuário que a assumiu. Isto é comum: numa medição em produção, 53 de 200 solicitações abertas estavam assim. Neste caso não existe ambiguidade. A CLI segue com esse movimento sem perguntar.

A CLI pede --movement somente quando existem movimentos diferentes em aberto, ou seja, atividades paralelas. Neste caso ela lista as opções com responsável e status, e sai com exit 2.

┌───────────┬─────────────────────┬─────────────────────┬────────────────────────────┬─────────┐
│ Movimento │ Etapa               │ Responsável         │ Status                     │ SLA     │
├───────────┼─────────────────────┼─────────────────────┼────────────────────────────┼─────────┤
│ 15        │ Corrigir Integração │ João Silva (jsilva) │ TRANSFERRED/NOT_COMPLETED  │ ON_TIME │
│ 16        │ Aprovar Diretoria   │ Maria Souza         │ NOT_COMPLETED              │ EXPIRED │
└───────────┴─────────────────────┴─────────────────────┴────────────────────────────┴─────────┘

O responsável e o status vêm das tarefas da solicitação. Uma tarefa de pool não tem responsável. Neste caso a CLI mostra (pool, sem responsável). Com --json, as mesmas opções vão no envelope em data.options[], com {movement, stateName, assignee, status, slaStatus}. Assim um agente escolhe o movimento sem ler texto.

Tempo limite no move e no start

O Fluig continua processando depois que a CLI para de esperar. Uma movimentação que salva um formulário grande passa de um minuto. Em produção, um move levou ~80 s, estourou o tempo limite do cliente e a movimentação aconteceu. Por isso:

As operações de escrita usam no mínimo 2 minutos de tempo limite. O --timeout que você informar sempre vence, para mais ou para menos.
No tempo limite estourado, o comando sai com exit 5 e error.code = "TIMEOUT". O código é próprio porque o resultado é desconhecido.
O move relê o estado da solicitação e diz o que encontrou. O campo data.outcome do --json traz o veredicto: moved (a tarefa alvo saiu de aberto — não repita), not_moved (a tarefa continua aberta — repita com --timeout maior) ou unknown (a releitura também falhou).
O start não tem número de solicitação para conferir. Ele devolve o comando de verificação em data.checkCommand.

⚠️ Nunca repita uma escrita às cegas depois de um TIMEOUT. Verifique o estado primeiro. Repetir um move que já passou movimenta a solicitação duas vezes.

fluigcli request move 196542 --movement 15 --timeout 5m

`fluigcli request cancel <número>... [flags]`

Este comando cancela solicitações. Ele fecha o ciclo de teste "criar → verificar → descartar" sem sair da CLI.

NOVA=$(echo '{}' | fluigcli request start meu_processo --fields-file - --json | jq .data.result.requestId)
fluigcli request show $NOVA --json          # verificar
fluigcli request cancel $NOVA --comment "solicitação de teste" --yes

O cancelamento é permanente: o status vira CANCELED e não há reabertura. Por isso o comando pede confirmação. Em modo não-interativo, ele exige --yes. O --comment vai para o histórico da solicitação.

Quem pode cancelar: o solicitante ou o gestor do processo. Ser admin não basta — a regra é da plataforma. A recusa volta como exit 5, com a mensagem do servidor. A CLI confirma o efeito: ela relê a solicitação e valida o status CANCELED (o resultado sai em data.results[].status).

Em lote, cada número tem o próprio resultado em data.results[]. Falha parcial vira exit 6.

Recusas comuns (exit 5, com a mensagem do servidor):

você não é o solicitante nem o gestor do processo;
a solicitação já está cancelada ou finalizada ("A solicitação é invalida ou está inativa");
a solicitação não existe.

`fluigcli request assignees <número> [--target-state N]`

Este comando lista quem pode assumir a próxima atividade. O diagrama pode ter mais de um destino. Neste caso, o servidor exige a etapa. Informe --target-state.

`fluigcli request attachments <número> [flags]`

Este comando lista os anexos de uma solicitação e baixa os arquivos. O próprio formulário aparece na lista como (formulário). O --download baixa apenas os arquivos anexados. O download é byte a byte fiel ao que subiu via request start --attach.

Flag	Uso
`--download`	baixa todos os arquivos anexados (o formulário fica de fora)
`--seq N`	baixa só o anexo com esse sequence
`--dir <pasta>`	diretório de destino (default: o atual)

fluigcli request attachments 196540                       # lista
fluigcli request attachments 196540 --download --dir ./anexos
fluigcli request attachments 196540 --seq 2               # um específico

Sequence inexistente → exit 4. A CLI valida o sequence contra a lista antes de baixar.

O nome do anexo vem do servidor. Por isso, o caractere que o sistema de arquivos não aceita (por exemplo /) vira _. Dois anexos de mesmo nome não se sobrescrevem: o segundo recebe o sufixo (2). Cada item de data.results[] traz o sequence, o fileName gravado e o path absoluto. A falha de gravação em disco sai como LOCAL_IO_ERROR, com exit 1.

`fluigcli request observe <número> [flags]`

Este comando registra uma observação no histórico da solicitação. A solicitação não se move. Ela continua na mesma etapa e com o mesmo responsável. A observação sai em nome do usuário autenticado. Ela aparece no Fluig nas observações da atividade.

O caso de uso é um agente ou um script que registra um laudo e deixa a decisão para a pessoa responsável.

Flag	Uso
`--text <s>`	texto da observação (HTML simples permitido)
`--text-file <arq>`	lê o texto de um arquivo; `-` lê do stdin
`--state N`	etapa (`stateSequence`) da tarefa; exige `--movement`
`--movement N`	movimento (`movementSequence`) da tarefa; exige `--state`
`--thread N`	thread da tarefa (default 0, o fluxo principal)

Informe --text ou --text-file. O teto do texto é 8.000 caracteres. Acima disso, o servidor recusa com exit 5.

Sem --state e --movement, a observação vai para a tarefa corrente. Se a solicitação tem tarefas paralelas, o servidor exige os dois. Veja as tarefas com request show. Solicitação finalizada ou cancelada não aceita observação. O comando responde exit 5 com o motivo.

fluigcli request observe 235189 --text "Laudo: documentação conferida."
cat laudo.html | fluigcli request observe 235189 --text-file - --json
fluigcli request observe 235189 --text "ok" --state 34 --movement 5

Com --json, data.observation traz o registro criado: id, stateSequence, movementSequence, threadSequence, colleagueId e observationDate em ISO-8601 com o fuso do servidor. O colleagueId é o userCode do autor. É a mesma convenção das observações feitas pela tela do Fluig. A tela mostra o nome.

Requer o fluigcliHelper 0.11.0 ou superior

A REST do Fluig não tem comentário sem movimentação. O SOAP setTasksComments exige a senha do usuário. Um usuário de app OAuth não tem senha. Por isso a observação vai pelo SDK do Fluig, de dentro do helper. Instale ou atualize com fluigcli server install-helper <servidor> --force. Helper ausente ou antigo responde exit 7.

Solicitação inexistente → exit 4. O servidor de produção pede confirmação (--yes em modo não-interativo), como toda escrita.

`fluigcli request observations <número> [flags]`

Este comando lista as observações de uma etapa da solicitação. Ele é a conferência do observe. A tabela mostra data, autor, etapa, movimento e o texto sem as tags HTML. O --json traz o texto íntegro.

Flag	Uso
`--state N`	etapa (`stateSequence`); default = tarefa corrente
`--thread N`	thread da tarefa (default 0)

fluigcli request observations 235189
fluigcli request observations 235189 --state 34 --json

Sem --state, o comando usa a tarefa corrente. Solicitação finalizada, cancelada ou com tarefas paralelas exige --state. Neste caso o comando responde exit 5 e cita a flag. A coluna Data mostra a hora do servidor. O comando também requer o fluigcliHelper 0.11.0 ou superior.

Status e SLA (valores da API)

status: OPEN (em andamento), CANCELED, FINALIZED.
slaStatus: ON_TIME, WARNING (perto do prazo), EXPIRED (estourado).
Status de tarefa (no show): NOT_COMPLETED (em aberto), PENDING_CONSENSUS, COMPLETED, TRANSFERRED, CANCELED.

As flags aceitam os valores em minúsculas. A CLI valida os valores antes de consultar.

fluigcli request — solicitações de workflow ​

fluigcli request list [flags] ​

fluigcli request show <número> ​

fluigcli request start <processId> [flags] ​

⚠️ Os eventos do formulário não rodam ​

Campos por JSON (--fields-file) ​

Linhas de tabela-filha (campo___N) ​

fluigcli request move <número> [flags] ​

Modo gestor (--manager) ​

Quando o 404 não quer dizer "não existe" ​

Quando a CLI pede --movement ​

Tempo limite no move e no start ​

fluigcli request cancel <número>... [flags] ​

fluigcli request assignees <número> [--target-state N] ​

fluigcli request attachments <número> [flags] ​

fluigcli request observe <número> [flags] ​

fluigcli request observations <número> [flags] ​

Status e SLA (valores da API) ​