update_field_api/README.md

Atualização em massa de campo — Clarizen

App terminal em Node.js para escolher um tipo de entidade e um campo via metadata do Adaptive Work, e atualizar esse campo em massa nos objetos do tipo selecionado (com filtros opcionais).

Pré-requisitos

• Node.js 18+
• API key do Adaptive Work (CLARIZEN_API_KEY)
• Biblioteca @arco/clarizen-lib compilada no diretório irmão (../clarizen-lib)

Instalação

cd ../clarizen-lib && npm install && npm run build
cd ../update_field_API
cp .env.example .env
# Edite .env com CLARIZEN_BASE_URL e CLARIZEN_API_KEY
npm install

Uso

npm start

Fluxo interativo:

1. Autenticação com API key
2. Escolha do tipo de entidade (nível) — lista completa ou filtro por texto
3. Filtro de objetos — todos, por State (se o tipo tiver lifecycle), ou cláusula WHERE em CZQL
4. Escolha do campo — cada opção mostra label, nome e tipo
5. Exibição de exemplo de preenchimento conforme o tipo
6. Informe o novo valor (ou limpe o campo, se nullable)
7. Busca dos objetos conforme o filtro
8. Confirmação com resumo (tipo, filtro, campo, valor, quantidade)
9. Atualização em massa com barra de progresso, porcentagem e ETA

Filtros de objetos

Após escolher o tipo de entidade, você pode limitar quais registros serão atualizados:

Opção	Descrição
Todos os objetos	Sem filtro (comportamento original)
Filtrar por State	Disponível quando a metadata expõe validStates (ex.: Active, Completed)
CZQL WHERE	Informe só a cláusula WHERE; o app valida contra a API antes de continuar

Exemplos de cláusula WHERE (CZQL)

State = 'Active'
Name LIKE 'Projeto%'
State = 'Active' AND Name LIKE 'Test%'

A cláusula é aplicada via entityQuery com filtro CZQL. Comandos de modificação (DELETE, UPDATE, etc.) são rejeitados.

Exemplos de valor por tipo de campo

Tipo	Como preencher no terminal
Boolean	true, false, sim, não
String	texto livre, ex: Meu valor
Integer / Long	42
Double	3.14
DateTime	2026-06-09 ou 2026-06-09T14:30:00Z
Date	2026-06-09
Entity	/User/abc-123 ou {"id":"/User/abc-123"}
Duration	{"value":5,"unit":"Days"}
Money	{"value":100,"currency":"BRL"}

Campos nullable permitem limpar o valor escolhendo "Limpar campo (null)" ou digitando null.

Variáveis de ambiente

Variável	Descrição
CLARIZEN_BASE_URL	URL base da API (padrão: https://api.clarizen.com)
CLARIZEN_API_KEY	API key (alternativa: API_KEY_AW)

O app também tenta carregar ../clarizen-lib/.env se não houver .env local.

Erros

Objetos que falharem na atualização são listados ao final. Um arquivo errors-<timestamp>.json é gerado na pasta do projeto com os detalhes.

Observações

• Apenas campos atualizáveis são listados (exclui calculados, create-only e internos).
• A atualização usa bulk.execute em lotes de 20, com fallback individual em caso de falha no lote.
• Rate limit da API: ~25 requisições/segundo por organização.