Clear Upload Failures no Consumer Goods Cloud: Tutorial Completo do Sync Management

O app mobile do Salesforce Consumer Goods Cloud (CGC) é offline-first: o representante comercial trabalha contra um banco SQLite local no dispositivo, e um motor de sincronização envia e recebe dados do Salesforce em segundo plano. Quando um upload falha de forma persistente, o registro fica preso na fila, retentando infinitamente e podendo travar a sincronização. É exatamente aqui que entra o Clear Upload Failure Request.

Neste tutorial você vai entender, de ponta a ponta, o que acontece por baixo dos panos quando o procedimento Clear Upload Failures (Limpar Falhas de Upload) é acionado na tela de Remote Request do app Sync Management. Este é um guia conceitual + operacional.

O que é o Clear Upload Failures?

Durante o ciclo normal, quando o usuário cria ou edita um registro (visita, pedido, inventário, anexo…), esse registro entra em uma fila de upload. O motor de sync tenta enviá-lo para o Salesforce. Na maioria das vezes dá certo. Mas às vezes falha e quando falha de forma persistente, o registro fica preso, retentando infinitamente e podendo bloquear a sincronização.

O Clear Upload Failure Request é o mecanismo administrativo que remove esses registros presos, devolvendo à fila de upload um estado limpo e desbloqueando a sincronização.

É uma “válvula de escape” administrativa para limpar uploads que falharam de forma persistente e travaram a fila de sincronização.

Como funciona por baixo dos panos

Para entender o que o Clear Upload Failures faz, precisamos olhar três peças do motor de sincronização.

1. O estado de sincronização de cada registro (_syncStatus)

Cada registro local carrega uma coluna de controle chamada _syncStatus, que representa em qual estágio da sincronização ele está:

O fluxo normal de gravação é:

usuário salva registro
   │
   ▼  marca como "sujo" (DIRTY) + persistido
save local (SQLite)
   │
   ▼  registro entra na fila de upload
background replication
   │
   ├── sucesso → _syncStatus: 1 → 0   (Synced)
   └── erro    → _syncStatus: 1 → 2   (Failed)  ← fica preso aqui

usuário salva registro
   │
   ▼  marca como "sujo" (DIRTY) + persistido
save local (SQLite)
   │
   ▼  registro entra na fila de upload
background replication
   │
   ├── sucesso → _syncStatus: 1 → 0   (Synced)
   └── erro    → _syncStatus: 1 → 2   (Failed)  ← fica preso aqui

O estado 2 (Failed) é o “beco sem saída”: o registro fica retentando, sem nunca sair dali. É exatamente esse estado que o Clear Upload Failures ataca.

2. Os objetos Salesforce do CG Cloud Sync (namespace cgc_sync__)

Todo o mecanismo de sincronização do CGC é regido por objetos customizados sob o namespace cgc_sync__. Os mais relevantes para esta funcionalidade:

💡 Dica: O flag clearUploadFailures é uma propriedade definida por objeto rastreado (dentro de Sync_Tracked_Object_Config__c). Ele determina se o mecanismo de Clear Upload Failures deve agir sobre aquele objeto específico. Confirme que está habilitado para os objetos que te interessam.

3. O ciclo de vida do Remote Request (Pending → entregue)

Um Remote Request é uma instrução criada no servidor (lado admin) que o dispositivo móvel executa durante sua próxima sincronização. O ciclo é:

[Criado]  →  [Pending]  →  [baixado pelo device]  →  [executado no device]  →  [concluído]

[Criado]  →  [Pending]  →  [baixado pelo device]  →  [executado no device]  →  [concluído]

Enquanto o request está Pending, ele ainda não chegou ao dispositivo. Só deixa de ser Pending quando o app móvel sincroniza, baixa o request e o processa.

Fluxo de ponta a ponta

┌─────────────────────────────────────────────────────────────────┐
│  LADO DO ADMINISTRADOR (Salesforce Cloud)                       │
│  App Launcher → Sync Management → aba Remote Request → New      │
└─────────────────────────────────────────────────────────────────┘
   1. Escolhe o tipo "Clear Upload Failure"
   2. Salva
      │
      ▼  Cria registro em: cgc_sync__Sync_Remote_Request__c
         Status: "Pending"

┌─────────────────────────────────────────────────────────────────┐
│  LADO DO DISPOSITIVO MÓVEL (app offline,  próxima sincronização)│
└─────────────────────────────────────────────────────────────────┘
   3. App sincroniza → baixa o Remote Request "Pending"
   4. Motor CG Cloud Sync processa o request:
        ├── localiza registros com _syncStatus = 2 (Failed)
        ├── remove/limpa esses registros de upload presos
        └── desbloqueia a fila de sincronização
   5. Marca o Remote Request como processado (deixa de ser Pending)
   6. A fila de upload volta a um estado limpo

┌─────────────────────────────────────────────────────────────────┐
│  LADO DO ADMINISTRADOR (Salesforce Cloud)                       │
│  App Launcher → Sync Management → aba Remote Request → New      │
└─────────────────────────────────────────────────────────────────┘
   1. Escolhe o tipo "Clear Upload Failure"
   2. Salva
      │
      ▼  Cria registro em: cgc_sync__Sync_Remote_Request__c
         Status: "Pending"

┌─────────────────────────────────────────────────────────────────┐
│  LADO DO DISPOSITIVO MÓVEL (app offline,  próxima sincronização)│
└─────────────────────────────────────────────────────────────────┘
   3. App sincroniza → baixa o Remote Request "Pending"
   4. Motor CG Cloud Sync processa o request:
        ├── localiza registros com _syncStatus = 2 (Failed)
        ├── remove/limpa esses registros de upload presos
        └── desbloqueia a fila de sincronização
   5. Marca o Remote Request como processado (deixa de ser Pending)
   6. A fila de upload volta a um estado limpo

Pré-requisitos

1. Acesso e permissões

• Conta Salesforce com acesso ao app Sync Management
• Permissão para criar registros em cgc_sync__Sync_Remote_Request__c
• Perfil que enxergue a aba Remote Request

2. O dispositivo-alvo

• O app Consumer Goods Cloud Offline Mobile App precisa estar instalado no dispositivo do usuário afetado
• O dispositivo precisa conseguir sincronizar (ter conectividade, ao menos no momento da próxima sync)

3. Configuração do objeto

⚠️ Atenção: Verifique se o objeto afetado tem clearUploadFailures habilitado em Sync_Tracked_Object_Config__c. Se estiver desligado, o request é processado, mas o objeto pode não ser limpo como esperado.

Quando usar o Clear Upload Failures

Use este procedimento quando observar estes sintomas:

• ✅ A Sync Card do usuário mostra registros “não enviados por upload” que não saem mesmo após várias sincronizações
• ✅ Há registros travados com falha de upload persistente (anexos, fotos, arquivos grandes que nunca sobem)
• ✅ A sincronização está lenta ou aparentemente travada por causa de itens repetindo erro na fila de upload
• ✅ O usuário reporta que “o pedido/visita não aparece no sistema” porque ficou preso no upload

Quando NÃO usar

• ❌ Como rotina preventiva (não é necessário em operação saudável)
• ❌ Para resolver erros de download (use Resupply Request nesse caso)
• ❌ Sem antes investigar a causa raiz da falha (ver troubleshooting)

💡 Dica: Existem dois tipos de Remote Request no CG Cloud Sync: Resupply (baixa/refresha dados para o device) e Clear Upload Failure (limpa uploads com falha). Não confunda os dois.

Passo a passo: como disparar o Clear Upload Failure

Passo 1 — Abrir o Sync Management

1. No Salesforce, clique no App Launcher (grade, canto superior esquerdo)
2. Digite Sync Management
3. Selecione o app Sync Management

Passo 2 — Ir para a aba Remote Request

1. Dentro do app Sync Management, clique na aba Remote Request
2. Clique em New (Novo)

Passo 3 — Escolher o tipo de request

1. No tipo de registro, selecione Clear Upload Failure
2. Clique em Next

Passo 4 — Preencher e salvar

1. Preencha os campos solicitados (usuário-alvo, objeto, etc., conforme o formulário do seu ambiente)
2. Salve o registro

✅ Critério de sucesso: O registro de Remote Request é criado e aparece na lista de Pending Remote Requests com status Pending.

Passo 5 — Aguardar a próxima sincronização do dispositivo

Nada mais é feito do lado admin. O request fica Pending até que o dispositivo móvel do usuário sincronize.

1. Peça ao usuário para abrir o app e forçar uma sincronização (ou aguarde a próxima sync automática / FSOD — First Sync of the Day)
2. Durante a sync, o app baixa o request e processa a limpeza

✅ Critério de sucesso: O status do Remote Request deixa de ser Pending (foi entregue/processado pelo dispositivo).

Como monitorar e verificar

Verificar pelo lado admin (Salesforce)

Verificar pelo lado do dispositivo

Troubleshooting

⚠️ Atenção: O Clear Upload Failures trata o sintoma, não a causa. Se a causa raiz persistir, os registros vão falhar de novo. Sempre investigue o porquê do erro em Sync History Detail / Sync Message antes de recorrer à limpeza.

Objetos envolvidos (resumo)

• cgc_sync__Sync_Remote_Request__c — onde o request é criado (Clear Upload Failure)
• cgc_sync__Sync_Tracked_Object_Config__c — contém o flag clearUploadFailures (por objeto)
• cgc_sync__Sync_History__c — histórico de sincronizações
• cgc_sync__Sync_History_Detail__c — detalhe de cada execução (erros)
• cgc_sync__Sync_Message__c — mensagens de erro exibidas no device
• cgc_sync__Sync_ID_Mapping__c — mapeamento IDs locais ↔ Salesforce
• cgc_sync__Sync_Config__c — configuração geral de sync

No banco SQLite local do dispositivo, cada registro rastreado carrega a coluna de controle _syncStatus — cujo valor 2 (Failed) é o alvo da limpeza.

Checklist final

• ☐ Confirmei que o sintoma é realmente upload preso (não download)
• ☐ Verifiquei o erro em Sync History Detail / Sync Message (causa raiz)
• ☐ Confirmei que clearUploadFailures está habilitado para o objeto-alvo
• ☐ Criei o Remote Request → Clear Upload Failure no Sync Management
• ☐ O request aparece como Pending
• ☐ Solicitei ao usuário que sincronize o dispositivo
• ☐ O request saiu de Pending (foi entregue/processado)
• ☐ A Sync Card não mostra mais os registros presos
• ☐ Se a causa raiz existia, ela foi tratada (senão o erro volta)

Conceitos aplicados

Referências

• Salesforce Help — Clear Upload Failures
• Salesforce Help — Sync Process (visão de alto nível)
• Salesforce Help — Sync Errors no CG Cloud Offline Mobile App
• Salesforce Help — Remote Request (conceito)
• Salesforce Help — Resupply Requests
• Salesforce Help — Criar um Tracked Object