Local Storage

1. Visão Geral

O componente Local Storage (local-storage) funciona como um pequeno "cofre" de dados em memória, guardando valores em pares chave/valor para reaproveitar em outros pontos do fluxo. Ele tem dois modos de vida (escopo): dados que existem só durante a execução atual, ou dados compartilhados entre execuções diferentes da aplicação, com um tempo de expiração.

Use quando precisar guardar um valor temporariamente para uso posterior no mesmo fluxo, ou quando precisar compartilhar informação entre execuções diferentes (por exemplo, um cache simples ou um contador). Não use para armazenamento permanente ou de grandes volumes de dados — isso deve ir para um banco de dados de verdade.

2. Pré-requisitos

Não há credenciais externas. Internamente, o escopo "compartilhado entre execuções" usa uma instância de armazenamento em memória distribuída (Hazelcast), criada automaticamente pela própria plataforma na primeira utilização — não exige configuração manual do usuário.

3. Autenticação e Conexão

Não aplicável — não há conexão com sistemas externos configurável pelo usuário.

4. Configuração / Operações Suportadas

O componente suporta três operações, controladas pelo campo operation.

Campo	Obrigatório	Tipo	Descrição	Exemplo
operation	Não	Texto: GET, PUT ou DELETE	Operação a ser executada. Valor padrão: GET. Qualquer valor não reconhecido é tratado como GET.	"PUT"
scope	Não	Texto: EXECUTION ou APPLICATION	Define o alcance do dado. EXECUTION (padrão): o valor só existe durante a execução atual do fluxo. APPLICATION: o valor é compartilhado entre execuções diferentes, com tempo de expiração.	"APPLICATION"
key	Sim	Expressão	Chave usada para guardar/buscar/apagar o valor.	"contadorPedidos"
value	Sim (para PUT)	Expressão	Valor a ser armazenado. Só é usado na operação PUT.	"10"
expiration	Não	Texto (milissegundos)	Tempo de vida do valor, aplicável apenas ao escopo APPLICATION. Valor padrão: "600000" (10 minutos).	"3600000" (1 hora)

Comportamento por operação:

• GET: busca o valor da chave informada. Se não existir, devolve corpo vazio (não gera erro).
• PUT: grava o valor na chave informada. No escopo APPLICATION, aplica o tempo de expiração configurado.
• DELETE: remove o valor da chave informada, se existir.

Comportamento em caso de erro: se key não for informado, a execução falha com o erro "Missing key. Please specify a key to LocalStorage."

5. Exemplos Práticos

Exemplo simples: dentro de uma única execução de fluxo, um componente grava o CPF do cliente em uma chave (operation: PUT, scope: EXECUTION), e um componente mais adiante no mesmo fluxo recupera esse valor (operation: GET) sem precisar buscar novamente na origem.

Entrada:

{
  "cliente": { "cpf": "123.456.789-00" }
}

Configuração do componente (gravando o valor):

{
  "componentName": "local-storage",
  "configurations": {
    "operation": "PUT",
    "scope": "EXECUTION",
    "key": "cpfCliente",
    "value": "{$.body.cliente.cpf}"
  }
}

Configuração do componente (lendo o valor mais adiante no mesmo fluxo):

{
  "componentName": "local-storage",
  "configurations": {
    "operation": "GET",
    "scope": "EXECUTION",
    "key": "cpfCliente"
  }
}

Resposta do GET (o corpo da mensagem passa a ser o valor gravado):

"123.456.789-00"

Exemplo avançado: um contador de tentativas de processamento precisa ser compartilhado entre diferentes execuções do fluxo (por exemplo, para limitar quantas vezes um mesmo pedido pode ser reprocessado em um período). Nesse caso, usa-se scope: APPLICATION com um tempo de expiração de uma hora (expiration: "3600000"), garantindo que o contador expire automaticamente depois desse período mesmo sem ser explicitamente apagado.

Configuração do componente:

{
  "componentName": "local-storage",
  "configurations": {
    "operation": "PUT",
    "scope": "APPLICATION",
    "key": "tentativas-pedido-981",
    "value": "1",
    "expiration": "3600000"
  }
}

Resposta:

"1"

6. Pontos de atenção

• O escopo EXECUTION não sobrevive ao fim da execução — os dados somem quando o fluxo termina.
• O escopo APPLICATION fica em memória; se a aplicação reiniciar, os dados são perdidos mesmo antes de expirarem.
• Os valores são tratados como texto simples, sem suporte nativo a estruturas complexas.
• Indicado para dados temporários e de volume moderado, não para armazenamento permanente ou grandes volumes.

7. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"Missing key. Please specify a key to LocalStorage."	O campo key não foi preenchido.	Preencher key com um valor válido em qualquer uma das três operações.
Valor sempre vazio ao usar GET	A chave nunca foi gravada antes, ou o valor expirou (no escopo APPLICATION), ou foi gravado em um escopo diferente do usado na leitura.	Confirmar se o scope usado no GET é o mesmo usado no PUT, e se o dado ainda não expirou.
Dado esperado no PUT não aparece em outra execução	Foi usado scope: EXECUTION, que não persiste entre execuções.	Usar scope: APPLICATION para compartilhar dados entre execuções diferentes.