---
name: fluig-eventos-processo
description: "Eventos de workflow BPM Fluig (afterProcessCreate, afterTaskComplete, beforeTaskSave, beforeSendData, calculateAgreement). Use quando precisar controlar ciclo de vida do processo, gravar dados ao completar tarefa, validar antes de salvar ou configurar analytics/consenso. Ativa com: 'evento de processo', 'afterTaskComplete', 'workflow script', 'beforeTaskSave', 'calculateAgreement'."
license: MIT
metadata:
  author: Nevoa
  version: "1.0.0"
  category: development
  platform: totvs-fluig
---

# Skill: Eventos de Processo/Workflow Fluig

Gera scripts de workflow (pasta `workflow/scripts/`) que controlam o ciclo de vida do processo BPM.

## Convencao de Nomes

Scripts de workflow seguem o padrao: `{CodProcesso}.{nomeEvento}.js`
Exemplo: `WF-0041.afterTaskComplete.js`

## Eventos Cobertos

| Evento | Quando Executa | Uso Principal |
|---|---|---|
| `afterProcessCreate` | Processo criado | Gravar nrSolic, data abertura, situacao |
| `afterTaskCreate` | Tarefa atribuida | Gravar responsavel atual, calcular prazo |
| `beforeTaskSave` | Antes de salvar tarefa | Validar anexos, chamar ERP |
| `afterTaskSave` | Apos salvar tarefa | Transformar dados, popular campos auxiliares |
| `beforeTaskComplete` | Antes de completar | Gravar auditoria JSON, validar regras |
| `afterTaskComplete` | Tarefa completada | Gravar aprovador, data, chamar integracoes |
| `afterProcessFinish` | Processo finalizado | Marcar situacao "Finalizado" |
| `afterCancelProcess` | Processo cancelado | Marcar situacao "Cancelado" |
| `beforeSendData` | Antes de enviar analytics | Popular customFields para BI |
| `calculateAgreement` | Consenso multi-aprovador | Controlar roteamento por votos |

## API Principal: hAPI

Todos os eventos de workflow usam `hAPI` para interagir com o formulario. Metodos essenciais:
- `hAPI.getCardValue("campo")` / `hAPI.setCardValue("campo", "valor")` — ler/gravar campos
- `hAPI.listAttachments()` / `hAPI.attachDocument(docId)` — anexos
- `hAPI.startProcess(...)` — sub-processos
- `notifier.notify(...)` — email

Variaveis de contexto: `getValue("WKNumState")`, `getValue("WKUser")`, `getValue("WKNumProces")`, `getValue("WKDef")`, etc.

> Referencia completa de hAPI, variaveis WK e notifier: [references/hapi-e-variaveis-contexto.md](./references/hapi-e-variaveis-contexto.md)

## 1. afterProcessCreate â€” Inicio do Processo

### Padrao de Producao
```javascript
function afterProcessCreate(processId) {
    var nrSolic = processId.toString();

    hAPI.setCardValue("nrSolic", nrSolic);
    hAPI.setCardValue("dtAberturaSolic", fnBuscarDataHora("data"));
    hAPI.setCardValue("hrAberturaSolic", fnBuscarDataHora("hora"));
    hAPI.setCardValue("situacaoSolic", "Aberto");

    // Data em formato EN para ordenacao
    var aux = fnBuscarDataHora("data").split("/");
    hAPI.setCardValue("dtAberturaSolic_EN", aux[2] + "-" + aux[1] + "-" + aux[0]);
}
```

## 2. afterTaskCreate â€” Tarefa Atribuida

### Padrao de Producao
```javascript
function afterTaskCreate(colleagueId) {
    var WKCurrentState = getValue("WKCurrentState");

    if (WKCurrentState != 4) { // Nao gravar na primeira atividade
        hAPI.setCardValue("atividadeAtual", WKCurrentState);
        hAPI.setCardValue("loginRespAtual", colleagueId);
        hAPI.setCardValue("descAtividadeAtual", fnDescAtividade(WKCurrentState));
    }

    // Gravar data de inicio da atividade
    hAPI.setCardValue("vDataIniAtiv_" + WKCurrentState, fnBuscarDataHora("data"));
}
```

## 3. afterTaskComplete â€” Tarefa Completada

### Padrao de Producao
```javascript
function afterTaskComplete(colleagueId, nextSequenceId, userList) {
    var nrAtividade = getValue("WKNumState");

    // Gravar quem completou e quando
    hAPI.setCardValue("vUserSpan_" + nrAtividade, colleagueId);
    hAPI.setCardValue("vDateSpan_" + nrAtividade, fnBuscarDataHora("data"));

    // Logica por atividade
    if (nextSequenceId == 5) {
        hAPI.setCardValue("loginAprovador", colleagueId);
        hAPI.setCardValue("dataAprovacao", fnBuscarDataHora("data"));
    }
}
```

## 4. beforeTaskSave â€” Validacao Pre-Save

### Padrao de Producao
```javascript
function beforeTaskSave(colleagueId, nextSequenceId, userList) {
    // Validar anexos obrigatorios
    if (nextSequenceId == 11) {
        var anexos = hAPI.listAttachments();
        if (anexos.size() == 0) {
            throw "Obrigatorio anexar um documento nesta atividade.";
        }
    }

    // Chamar ERP antes de salvar
    if (nextSequenceId == 27) {
        var c1 = DatasetFactory.createConstraint("param", valor, valor, ConstraintType.MUST);
        var ds = DatasetFactory.getDataset("dsIntegracao", null, new Array(c1), null);
    }
}
```

## 5. afterProcessFinish / afterCancelProcess â€” Encerramento

### Padrao de Producao
```javascript
function afterProcessFinish(processId) {
    hAPI.setCardValue("situacaoSolic", "Finalizado");
    hAPI.setCardValue("dtFimSolic", fnBuscarDataHora("data"));
    hAPI.setCardValue("hrFimSolic", fnBuscarDataHora("hora"));
}

function afterCancelProcess(colleagueId, processId) {
    hAPI.setCardValue("situacaoSolic", "Cancelado");
    hAPI.setCardValue("dtFimSolic", fnBuscarDataHora("data"));
    hAPI.setCardValue("userCancelamento", colleagueId);
}
```

## 6. beforeSendData â€” Analytics/BI

### Padrao de Producao
```javascript
function beforeSendData(customFields, customFacts) {
    customFields[0] = hAPI.getCardValue("empresa");
    customFields[1] = hAPI.getCardValue("filial");
    customFields[2] = hAPI.getCardValue("area");
    // Ate 15 customFields disponiveis
}
```

## 7. calculateAgreement â€” Consenso Multi-Aprovador

### Padrao de Producao
```javascript
function calculateAgreement(currentState, agreementData) {
    if (hAPI.getCardValue("aprovacao") == "N") {
        // Reprovado: encerrar imediatamente
        agreementData.put("currentPercentage", 100);
        agreementData.put("currentDestState", ESTADO_REPROVADO);
        agreementData.put("currentDestUsers", "System:Auto");
    }
    // Se 100% aprovaram, segue fluxo normal
}
```

## 8. Email via Notifier

### Padrao de Producao (VIPal)
```javascript
// Dentro de qualquer evento de workflow
var remetente = getValue("WKUser");
var url = fluigAPI.getPageService().getServerURL();

var parametros = new java.util.HashMap();
parametros.put("processo", processId);
parametros.put("solicitante", hAPI.getCardValue("solicitante"));
parametros.put("subject", "Solicitacao #" + processId);
parametros.put("tituloEmail", "Nova Solicitacao");
parametros.put("link", '<a href="' + url + '/portal/p/1/pageworkflowview?app_ecm_workflowview_detailsProcessInstanceID=' + processId + '">' + processId + '</a>');

var destinatarios = new java.util.ArrayList();
destinatarios.add("login.destinatario");

notifier.notify(remetente, "TEMPLATE_EMAIL", parametros, destinatarios, "text/html");
```

## Regras

- MUST: ES5 obrigatorio (todos os eventos rodam no servidor)
- MUST: Usar hAPI para ler/gravar campos (NAO form.getValue)
- MUST: try/catch em integracoes externas
- MUST: Log com log.info/log.error em cada evento
- SHOULD: Verificar `colleagueId != "System:Auto"` antes de gravar usuario
- SHOULD: Gravar data em formato EN (yyyy-mm-dd) alem de BR
- MUST NOT: Usar jQuery ou DOM (roda no servidor)
- MUST NOT: Hardcodar URLs (usar fluigAPI.getPageService().getServerURL())

## Checklist de Geracao

- [ ] afterProcessCreate.js com nrSolic, data, situacao
- [ ] afterTaskCreate.js com responsavel e data inicio
- [ ] afterTaskComplete.js com aprovador e data por atividade
- [ ] beforeTaskSave.js se houver validacao de anexos ou ERP
- [ ] afterProcessFinish.js com situacao "Finalizado"
- [ ] afterCancelProcess.js com situacao "Cancelado"
- [ ] beforeSendData.js se usar Fluig Analytics
- [ ] calculateAgreement.js se houver multi-aprovacao
- [ ] Campos hidden no HTML: nrSolic, situacaoSolic, dtAberturaSolic, etc.

## Prompts Estrategicos Disponiveis

- `gerar-pacote-scripts-workflow-por-fluxo.md` - Geracao de pacote de scripts de workflow por fluxo BPM.
- `diagnosticar-erro-workflow-escolha-evento.md` - Diagnostico de erro e escolha correta do evento de processo.
- `implementar-before-send-data-analytics-sla.md` - Analytics/SLA via `beforeSendData`.
- `implementar-calculate-agreement-multiaprovacao.md` - Consenso de multiaprovacao com `calculateAgreement`.

Use estes prompts para cobrir criacao, diagnostico, analytics e roteamento avancado de workflow.
## Skills Relacionadas

- [fluig-formularios](../fluig-formularios/SKILL.md) — HTML base e eventos basicos (displayFields, validateForm)
- [fluig-eventos-formulario](../fluig-eventos-formulario/SKILL.md) — inputFields, gravaHistorico, afterSaveNew
- [fluig-scripts-avancados](../fluig-scripts-avancados/SKILL.md) — Sub-processos, email, GED
- [fluig-process-reader](../fluig-process-reader/SKILL.md) — Mapear atividades do .process

## Templates Disponiveis
- [afterProcessCreate-base.js](./templates/afterProcessCreate-base.js) â€” Inicio do processo
- [afterTaskComplete-base.js](./templates/afterTaskComplete-base.js) â€” Completar tarefa com auditoria
- [afterProcessFinish-base.js](./templates/afterProcessFinish-base.js) â€” Finalizacao e cancelamento
- [beforeSendData-base.js](./templates/beforeSendData-base.js) â€” Analytics com prazo calculado

## Recursos Adicionais
- Para templates base, consulte os arquivos em [templates/](./templates/)
- Para exemplos de implementaÃ§Ã£o real, consulte [examples/](./examples/)
### Exemplos recomendados
- [exemplo_01_aprovacao_pedido_analytics_consenso](./examples/exemplo_01_aprovacao_pedido_analytics_consenso/): workflow com `beforeSendData`, `calculateAgreement` e regras de consenso.
- [exemplo_02_rnc_beforeTaskSave_responsavel_proxima_atividade](./examples/exemplo_02_rnc_beforeTaskSave_responsavel_proxima_atividade/): persistencia de proximo responsavel em `beforeTaskSave`.
- Para referÃªncia tÃ©cnica detalhada, consulte [references/](./references/)

---

## Curadoria de Contexto Local

Para buscar exemplos reais no acervo local `Contexto`, consulte [references/contexto-curadoria.md](./references/contexto-curadoria.md).
Abra essa referencia quando a tarefa exigir aderencia a legado/producao ou comparacao com implementacoes existentes.
