first commit

2026-06-09 18:35:55 -03:00
commit 3581e221d0
448 changed files with 519709 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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
+
+```bash
+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
+
+```bash
+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.