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:

Autenticação com API key
Escolha do tipo de entidade (nível) — lista completa ou filtro por texto
Filtro de objetos — todos, por State (se o tipo tiver lifecycle), ou cláusula WHERE em CZQL
Escolha do campo — cada opção mostra label, nome e tipo
Exibição de exemplo de preenchimento conforme o tipo
Informe o novo valor (ou limpe o campo, se nullable)
Busca dos objetos conforme o filtro
Confirmação com resumo (tipo, filtro, campo, valor, quantidade)
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.

Campos PickList

Campos com presentationType: PickList (listas de opções customizadas ou do sistema) exibem uma lista carregada da API com nomes legíveis (ex: Conteúdo). O app envia o ID como string ("/C_GenericTaskSetor/Edição"), não como objeto {"id":"..."} — formato exigido pela API do Adaptive Work para PickList.

Campos de referência (ReferenceToObject, ex: User, Project) continuam exigindo objeto {"id":"/Tipo/guid"} ou /Tipo/guid convertido para { id }.

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.

Log de execução

Após cada atualização concluída, o app gera run-log-<timestamp>.json na pasta do projeto com o registro completo da execução:

data/hora e duração
usuário autenticado
tipo de entidade, filtro, campo e valor aplicado
resumo (total, atualizados, erros)
lista de cada objeto com status: "updated" ou status: "error"

Exemplo resumido:

{
  "executedAt": "2026-06-09T15:30:00.000Z",
  "durationMs": 45230,
  "userId": "/User/abc123",
  "operation": {
    "typeName": "Task",
    "filter": "Todos",
    "fieldName": "C_MeuCampo",
    "value": "/C_GenericTaskSetor/Edição",
    "valueLabel": "Conteúdo (/C_GenericTaskSetor/abc123)"
  },
  "summary": { "total": 10, "updated": 9, "errors": 1 },
  "results": [
    { "id": "/Task/...", "displayName": "Tarefa 1", "status": "updated" },
    { "id": "/Task/...", "displayName": "Tarefa 2", "status": "error", "message": "..." }
  ]
}

O caminho do arquivo é exibido no terminal ao final: Log da execução: ...

Erros

Objetos que falharem na atualização também aparecem no run-log-*.json. Além disso, um arquivo errors-<timestamp>.json é gerado quando há falhas, contendo só os erros para reprocessamento.

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.

4.7 KiB Raw Blame History