Reading Reply

O Reading Reply trata o que uma pessoa faz com um pedido de leitura de KPI no Slack. O Daily Digest publica um checklist de leituras. Quando alguém marca um item, o Reading Reply abre um formulário, salva valor, nota e evidência como uma Observation no KPIs & OKRs e reescreve o checklist para o item aparecer como gravado. Fechar o formulário, ou um clique que ele não consegue ler, só atualiza o checklist.

O maintainer do KPIs & OKRs cuida das programações e das Observations gravadas; o maintainer do Tooling and Access cuida das contas de bot do Slack de onde o workflow pega o token.

Fluxo

Gerado da versão do n8n do quadro acima: cada caixa é um nó e cada seta é uma ligação no n8n. Pílulas rosa são gatilhos, hexágonos amarelos são nós If e Switch com as saídas nas setas, cilindros azuis leem (Airtable, Data Table, HTTP GET), cilindros verdes gravam, caixas roxas chamam outro workflow e setas tracejadas são saídas de erro.

flowchart TD
  subgraph g0["Receber e conferir"]
    n40(["Slack Interaction"]):::trigger
    n10["Config"]:::logic
    n31["Parse Payload"]:::logic
    n47{{"Valid Interaction"}}:::decision
    n1["Ack Reply"]:::logic
    n0["Ack Error"]:::logic
  end
  subgraph g1["Token do Slack"]
    n17["Get Cached Bot<br/><small>Slack — Workspace Token Cache</small>"]:::subflow
    n36["Resolve Slack Account"]:::logic
    n42{{"Token Available?"}}:::decision
    n35["Refresh Workspace in Background<br/><small>Slack — Workspace Token Cache</small>"]:::subflow
    n5{{"Can Reply to Interaction?"}}:::decision
    n37[("Restore Task Selection<br/><small>POST Slack response URL</small>")]:::write
    n28[("Notify Retry<br/><small>POST Slack response URL</small>")]:::write
  end
  subgraph g2["Rota"]
    n29{{"Open Form First"}}:::decision
    n43{{"Trigger Still Fresh?"}}:::decision
    n30[("Open Loading Modal<br/><small>POST Slack views.open</small>")]:::write
    n26["Modal Opened"]:::logic
    n2["Airtable Schema"]:::logic
    n41{{"Switch Route"}}:::decision
  end
  subgraph g3["Abrir o formulário"]
    n20[("Get Schedule<br/><small>GET KPIs Recurrence Configuration</small>")]:::read
    n16[("Find Previous Reading<br/><small>GET KPIs Observation</small>")]:::read
    n3["Build Modal"]:::logic
    n45[("Update Modal<br/><small>POST Slack views.update</small>")]:::write
    n7["Check Modal Update"]:::logic
  end
  subgraph g4["Gravar a leitura"]
    n21[("Get Submitted Schedule<br/><small>GET KPIs Recurrence Configuration</small>")]:::read
    n15[("Find Existing<br/><small>GET KPIs Observation</small>")]:::read
    n33["Prepare Observation"]:::logic
    n38[("Save Observation<br/><small>PATCH KPIs Observation</small>")]:::write
    n39["Saved Observation"]:::logic
    n22{{"Has New Files"}}:::decision
    n24["List Evidence Files"]:::logic
    n18[("Get Evidence Info<br/><small>GET Slack files.info</small>")]:::read
    n48["Validate Evidence"]:::logic
    n11[("Download Evidence<br/><small>GET Slack file download</small>")]:::read
    n12["Encode Evidence"]:::logic
    n46[("Upload Evidence<br/><small>POST KPIs Observation · Evidence Files°</small>")]:::write
    n13["Evidence Uploaded"]:::logic
    n32["Prepare Completion"]:::logic
    n9[("Complete Observation<br/><small>PATCH KPIs Observation</small>")]:::write
  end
  subgraph g5["Atualizar a mensagem do digest"]
    n14[("Fetch Digest Message<br/><small>GET Slack conversations.history</small>")]:::read
    n34["Reading Keys"]:::logic
    n19[("Get Recorded Readings<br/><small>GET KPIs Observation</small>")]:::read
    n4["Build Updated Blocks"]:::logic
    n44[("Update Digest Message<br/><small>POST Slack chat.update</small>")]:::write
    n8["Check Slack Update"]:::logic
  end
  subgraph g6["Falha"]
    n6["Capture Failure"]:::logic
    n23{{"Has Saved Record"}}:::decision
    n25[("Mark Failed<br/><small>PATCH KPIs Observation</small>")]:::write
    n27[("Notify Failure<br/><small>POST Slack chat.postEphemeral</small>")]:::write
  end
  n30 --> n26
  n30 -.->|erro| n6
  n20 --> n16
  n20 -.->|erro| n6
  n16 --> n3
  n16 -.->|erro| n6
  n45 --> n7
  n45 -.->|erro| n6
  n21 --> n15
  n21 -.->|erro| n6
  n15 --> n33
  n15 -.->|erro| n6
  n38 --> n39
  n38 -.->|erro| n6
  n18 --> n48
  n18 -.->|erro| n6
  n11 --> n12
  n11 -.->|erro| n6
  n46 --> n13
  n46 -.->|erro| n6
  n9 --> n14
  n9 -.->|erro| n6
  n14 --> n34
  n14 -.->|erro| n6
  n19 --> n4
  n19 -.->|erro| n6
  n44 --> n8
  n44 -.->|erro| n6
  n36 --> n42
  n36 -.->|erro| n35
  n26 --> n2
  n26 -.->|erro| n6
  n3 --> n45
  n3 -.->|erro| n6
  n7 --> n14
  n7 -.->|erro| n6
  n33 --> n38
  n33 -.->|erro| n6
  n39 --> n22
  n39 -.->|erro| n6
  n24 --> n18
  n24 -.->|erro| n6
  n48 --> n11
  n48 -.->|erro| n6
  n12 --> n46
  n12 -.->|erro| n6
  n13 --> n32
  n13 -.->|erro| n6
  n32 --> n9
  n32 -.->|erro| n6
  n34 --> n19
  n34 -.->|erro| n6
  n4 --> n44
  n4 -.->|erro| n6
  n8 -.->|erro| n6
  n40 --> n10
  n10 --> n31
  n31 --> n47
  n47 -->|sim| n1
  n47 -->|não| n0
  n1 --> n17
  n2 --> n41
  n6 --> n23
  n25 --> n27
  n41 -->|open| n20
  n41 -->|record| n21
  n41 -->|refresh| n14
  n22 -->|sim| n24
  n22 -->|não| n32
  n23 -->|sim| n25
  n23 -->|não| n27
  n29 -->|sim| n43
  n29 -->|não| n2
  n17 --> n36
  n17 -.->|erro| n35
  n42 -->|sim| n29
  n42 -->|não| n35
  n43 -->|sim| n30
  n43 -->|não| n5
  n35 --> n5
  n5 -->|sim| n37
  n37 --> n28
  classDef trigger fill:#fde7f3,stroke:#d6409f,color:#111
  classDef decision fill:#fff7e0,stroke:#c99a00,color:#111
  classDef read fill:#e8f1ff,stroke:#3b82f6,color:#111
  classDef write fill:#e7f8ee,stroke:#16a34a,color:#111
  classDef subflow fill:#f3e8ff,stroke:#9333ea,color:#111
  classDef wait fill:#f1f1f1,stroke:#888,color:#111
  classDef logic fill:#ffffff,stroke:#999,color:#111

Sistemas que ele toca

As chamadas ao Airtable são nós HTTP Request com a credencial “Airtable PAT (Fully Scoped)” e leem e gravam por ID de campo. O Airtable Schema guarda o mapa de IDs de base, tabela e campo que os nós de código usam; ele também lista tabelas do Communication e do Tooling, mas nenhum nó lê ou grava nelas.

As chamadas ao Slack usam a credencial “Systems Slack Automation - Dynamic”, que usa o token de bot que o Token Cache devolveu para o workspace da pessoa. O workflow chama views.open, views.update, conversations.history, chat.update, chat.postEphemeral e files.info, baixa os arquivos de evidência e posta na response URL da interação.

Gatilho e assinatura

O Slack Interaction aceita um POST da URL de interatividade do app do Slack e guarda o body cru. Ele só responde pelo Ack Reply ou pelo Ack Error, então o Slack recebe a resposta depois que o Parse Payload conferiu a requisição e antes de qualquer chamada ao Airtable.

O Config define os valores que o resto do workflow lê:

O Parse Payload recusa a requisição com uma mensagem, que o Ack Error devolve ao Slack, quando:

• o body falta, o header x-slack-request-timestamp falta ou tem 300 segundos ou mais, ou o HMAC-SHA256 do x-slack-signature não bate (comparação em tempo constante);
• o payload não pode ser decodificado;
• testSlackUserId está preenchido e a pessoa é outra (“Collection is being tested; please try again later”);
• o item é de outra pessoa, o ID do workspace não é um team ID do Slack, ou a programação, a membership ou o período do item têm formato errado;
• o canal ou a mensagem original são desconhecidos.

Numa submissão de formulário, o Ack Error mostra o erro no campo de quantidade ou de evidência.

O que o Parse Payload lê da interação

A quantidade precisa ser um número não negativo (inteiro enquanto allowDecimalValue é false). Até quatro arquivos, cada um com no máximo maxUploadBytes. O Occurrence Key de um item é <registro da programação>:<período> e o Submission Key é <registro da programação>:<período>|<registro da membership>.

Token do Slack

Depois do Ack Reply, o Get Cached Bot chama o Slack — Workspace Token Cache com o ID do workspace. Na rota open ele pede só o token em cache; em record e refresh deixa o cache carregar do Tooling quando preciso. O Resolve Slack Account só aceita a resposta quando é do mesmo workspace, tem token e não expira no próximo segundo.

Sem token utilizável, o Refresh Workspace in Background pede ao cache para recarregar este workspace e não espera. Quando o Slack mandou uma response URL, o Restore Task Selection devolve o checklist como estava e o Notify Retry avisa “The form is not ready yet. Please click the task again in a few seconds. No response was recorded.”

Abrir o formulário

O Slack só aceita um formulário aberto em até três segundos depois do clique. O Trigger Still Fresh? só deixa a rota open seguir em até 2,5 segundos do clique; depois disso ela vai para a mensagem de nova tentativa acima.

1. O Open Loading Modal abre na hora um formulário “Loading reading”, e o Modal Opened guarda o view ID dele.
2. O Get Schedule lê a Recurrence Configuration e o Find Previous Reading procura uma Observation com o mesmo Submission Key.
3. O Build Modal para quando o Accountable Membership* da programação não inclui a membership da pessoa. Depois monta o formulário: nome da programação, período, meta (“At least”, “At most” ou “Target”, a partir de Target (Value) e Target (Direction)), um campo de quantidade em Target (Unit Text), uma nota e um campo de evidência (até 4 imagens ou PDFs). Uma leitura anterior preenche quantidade e nota.
4. O Update Modal troca o formulário de carregamento, e o Check Modal Update falha quando o Slack recusa.
5. Em seguida o fluxo atualiza a mensagem do digest (abaixo), então o checkbox que a pessoa acabou de marcar volta ao estado gravado.

Gravar a leitura

1. O Get Submitted Schedule lê a Recurrence Configuration e o Find Existing procura Observations com o Submission Key.

2. O Prepare Observation para quando:

   • a programação não é da membership;
   • mais de uma Observation tem aquele key (“Duplicate collection keys need reconciliation”);
   • a existente está em Processing há menos de dois minutos;
   • a programação não tem Target (Metric).

   Depois monta o upsert com Collection Status* Processing e descobre quais arquivos são novos, comparando com Slack File IDs e com os nomes de arquivo já em Evidence Files°.

3. O Save Observation faz o upsert pelo Submission Key e o Saved Observation guarda o ID do registro.

4. Quando há arquivos novos, cada um passa por Get Evidence Info, Validate Evidence, Download Evidence, Encode Evidence e Upload Evidence. Só são aceitas URLs files.slack.com, de no máximo 5 MB, dos tipos png, jpg, jpeg, gif, webp ou pdf. Eles são guardados como <ID do arquivo no Slack>__<nome>.

5. O Prepare Completion confere que todos os arquivos novos foram enviados, e o Complete Observation põe Recorded.

6. Em seguida o fluxo atualiza a mensagem do digest.

Atualizar a mensagem do digest

O Fetch Digest Message lê a mensagem original, e o Reading Keys lista os Submission Keys dos checkboxes dela. O Get Recorded Readings lê essas Observations, até 100.

Depois o Build Updated Blocks redesenha o checklist:

• Os itens gravados aparecem riscados, com o horário no fuso do Config.
• O cabeçalho mostra “<n> of <total> responses recorded”.
• “All responses in this message are recorded.” é acrescentado quando todos os itens estão feitos.

O Update Digest Message grava a mensagem de volta, e o Check Slack Update falha quando o Slack recusa.

Caminho de falha

A partir do Open Loading Modal, toda chamada ao Airtable e ao Slack e todo nó de código, exceto o Airtable Schema, mandam seus erros para o Capture Failure. O Capture Failure guarda os primeiros 400 caracteres do erro e remove o que parece token do Slack. Ele também descobre se algum registro foi salvo:

• Salvo mas não concluído: o Mark Failed põe Collection Status* em Failed com o erro em Collection Error, e o Notify Failure avisa “Your reading could not be completed. Please try again.”
• Concluído, e depois a atualização da mensagem falhou: o Notify Failure diz que a leitura foi salva mas a mensagem não pôde ser atualizada.
• Nada salvo na rota open: o Notify Failure diz que o formulário não pôde ser aberto e que nada foi gravado.

O Notify Failure é uma mensagem privada no canal.

Campos gravados

Observation

Nenhuma gravação usa typecast, então uma opção de Collection Status* renomeada faz a gravação falhar em vez de criar opção nova.

Recurrence Configuration (só leitura)

Nós

O workflow tem 50 nós: 49 que executam e uma nota adesiva. Num nó If, a saída 0 é verdadeiro e a saída 1 é falso. Num nó com saída de erro, a saída 1 é o erro.

Ligações

Configurações e tratamento de erro

O n8n não guarda dados de execução deste workflow, então uma falha não deixa rastro no n8n: olhe Collection Status* e Collection Error na Observation. As únicas execuções salvas são falhas de uma versão anterior, de 20/10/2026.

Lacunas conhecidas

Estas vêm da configuração dos nós; nenhuma execução da versão atual está salva no n8n.

Recuperar uma gravação parcial

Veja a Observation com o Submission Key do item antes de pedir para a pessoa tentar de novo.

Manter esta página em dia

O quadro no topo mostra a versão do n8n que esta página descreve. Abra o workflow no n8n: quando o último salvamento dele é mais novo que a data do quadro, esta página está desatualizada até a próxima revisão. Todos os nós e todas as ligações dessa versão estão em Nós e Ligações.