93 lines
3.1 KiB
Markdown
93 lines
3.1 KiB
Markdown
# 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.
|