Salesforce

O conector Salesforce lê contatos, contas, oportunidades, leads, casos e usuários de uma org Salesforce pela API REST, autenticado por OAuth 2.0 Client Credentials, e os grava no Data Catalog.

​

Capacidades

• Traz ao Data Catalog seis objetos padrão do CRM, com tabelas clean prontas para cada um. Os casos fechados e os usuários internos ganham uma tabela clean própria, recortada da tabela principal.
• Alimenta o Memory pelo fragmento de ontologia do conector. Contatos viram Customer, contas viram Company, oportunidades viram Deal, e leads, casos e usuários internos viram Lead, Case e Agent. Os nós só entram no grafo depois que a ontologia unificada é aplicada.
• Unifica entidades com outros conectores: contatos pelo e-mail com os de outros CRMs e ferramentas, contas pelo domínio do site, e usuários internos pelo e-mail.
• Monta a linha do tempo de contas e contatos com três eventos: caso aberto, caso fechado e mudança de oportunidade.
• Declara os campos com dado pessoal. Email e Phone de contacts, leads e users vêm marcados como e-mail e telefone, e Description de cases vem marcado para ocultação. A política é aplicada quando você a liga no Data Catalog.

​

Recursos disponíveis

Todo recurso lê só os campos listados acima. Campos e objetos customizados (__c) não entram. No Data Catalog, os seis recursos e as tabelas clean começam desligados. Você escolhe o que carregar e em que modo depois de conectar. Em users, só os usuários com UserType igual a Standard viram Agent no Memory. Usuários de portal e comunidade ficam na tabela, mas não se unem aos funcionários vindos de outros conectores.

​

Permissões (ACL)

Esta fonte não define permissões por registro, então todo mundo que puder usar o conector vê todos os registros. Quem pode usar o conector é definido em Quem pode usar este conector: “Todos os usuários” ou “Apenas times específicos”. O Comportamento dos dados deste conector é sempre “Aberto”.

​

Como a fonte define acesso

No Salesforce, o que cada pessoa vê resulta do padrão da org para cada objeto (OWD), da hierarquia de papéis, das regras de compartilhamento e dos compartilhamentos manuais. A Salesforce expõe essas concessões por registro, mas o conector ainda não as lê.

​

Como a Strattum traduz o acesso

A Strattum não grava permissão por item. Toda chamada roda como o Run As user do app, então o conector lê o que esse usuário vê. Essas linhas ficam visíveis para quem pode usar o conector, inclusive registros que a pessoa não veria no próprio Salesforce. O conector não oferece Exigir login na fonte como prova de identidade.

​

Quando a identidade não é encontrada

Não se aplica: nenhuma linha depende da identidade de quem consulta.

​

Quando a permissão é atualizada

Não há permissão da fonte para atualizar. O acesso depende só de Quem pode usar este conector.

​

Pré-requisitos

• Uma org Salesforce com My Domain, no endereço https://<seu-dominio>.my.salesforce.com. Valem também os domínios .develop., .sandbox. e .scratch..
• Um administrador da org para criar o External Client App (ou Connected App) e definir o Run As user.
• Um usuário de integração para ser o Run As user, com leitura nos objetos e nos campos que você vai carregar.
• Cota de API disponível na org. As chamadas do conector contam no mesmo limite diário das outras integrações.
• Uma só conexão Salesforce por instalação da Strattum.

​

Autenticação e escopos

A autenticação usa o fluxo OAuth 2.0 Client Credentials. O conector troca a Consumer Key e o Consumer Secret por um token em POST /services/oauth2/token, no My Domain da org. Não há usuário, senha nem security token. O endereço precisa ser o My Domain. login.salesforce.com e test.salesforce.com são recusados, porque o fluxo Client Credentials não funciona nesses hosts. Endereços da interface, como *.lightning.force.com e *.my.site.com, também são recusados.

​

Configuração no Console

Para trocar as credenciais depois, preencha as três juntas no editor do conector, ou deixe as três em branco para manter as que estão guardadas.

​

Como a sincronização funciona

A frequência vem do passo Sincronização. O padrão é uma execução a cada 2 horas, em UTC. Verificação inicial. Cada execução começa emitindo o token e consultando um registro de User. Se essa consulta falhar, a execução para antes de ler qualquer recurso. Ordem. O conector lê os recursos selecionados um por um: contacts, accounts, opportunities, leads, cases e users. Recurso desligado no Data Catalog não é lido. Depois da leitura, as tabelas clean são reconstruídas. Paginação. Cada recurso é uma consulta SOQL ordenada por SystemModstamp e Id. A Salesforce devolve até 2.000 registros por página, e o conector segue o nextRecordsUrl até a página marcada como a última. Ele mantém uma página por vez na memória e só segue o próximo endereço se ele estiver na mesma org. Full refresh (padrão). O recurso é lido inteiro e a tabela é reescrita. Um registro apagado no Salesforce some da tabela nessa execução. Incremental. Opcional por recurso, no Data Catalog. A execução pede só o que tem SystemModstamp maior que o último valor visto e mescla o resultado pelo Id. SystemModstamp muda a cada alteração, inclusive as feitas pelo próprio Salesforce. Um registro cuja transação fez commit depois da consulta anterior pode chegar com um carimbo mais antigo que o último valor visto. Por isso, enquanto o último valor visto estiver a menos de 10 minutos do início da leitura anterior, a consulta recua 10 minutos e relê essa janela. Fora dela, não há releitura. Remoção. Num recurso em incremental, um registro apagado no Salesforce continua na Strattum até o recurso voltar para full refresh. O conector não lê a lixeira nem a lista de apagados. Sessão. O token é guardado durante a execução. Se a Salesforce recusar a sessão (401), o conector emite um token novo uma vez e repete a mesma chamada, mesmo no meio da paginação. Uma segunda recusa seguida encerra a execução. Falhas. Uma recusa de permissão, um campo sem FLS ou um objeto inexistente na primeira página de um recurso falha só aquele recurso. A tabela dele fica como estava, e os outros seguem. Se todos os recursos selecionados falharem, a execução termina com falha. Qualquer outro erro, como cota esgotada, sessão recusada, falha de rede ou erro numa página depois da primeira, encerra a execução, e as tabelas clean não são reconstruídas nela.

​

API da fonte

Todas as chamadas vão ao My Domain da org e só leem dados. A versão da API é fixa em v62.0. Rate limits. A Salesforce limita o total de chamadas de API por org numa janela móvel de 24 horas, compartilhada com todas as integrações da org. A Developer Edition tem 15.000 chamadas por 24 horas. A Enterprise Edition parte de 100.000 e soma um valor por licença. Esgotada a cota, a API responde com o erro REQUEST_LIMIT_EXCEEDED. Cada página de até 2.000 registros custa uma chamada: um full refresh de 1 milhão de linhas usa cerca de 500 chamadas. O conector não limita o próprio ritmo e envia uma chamada por vez, com tempo limite de 60 segundos e sem seguir redirecionamento. No fim de cada recurso, o log registra o consumo informado pela Salesforce no cabeçalho Sforce-Limit-Info (api-usage=usadas/limite). Diante de REQUEST_LIMIT_EXCEEDED, a execução para sem nova tentativa, porque repetir só gasta mais cota. Erros 5xx, quedas de conexão e falhas de rede ao emitir o token são repetidos: a verificação inicial até 2 vezes, depois de 30 e 60 segundos, e a leitura de cada recurso até 3 vezes, depois de 30, 60 e 120 segundos. Referência oficial: API Request Limits and Allocations, REST API, Query e OAuth 2.0 Client Credentials Flow

​

Limitações conhecidas

• Sem permissão por item: todo usuário que pode usar o conector vê tudo o que o Run As user alcança, inclusive registros que ele não veria no próprio Salesforce. Para restringir, limite Quem pode usar este conector.
• O Run As user decide o universo do conector. Objeto, campo ou registro que ele não lê não chega à Strattum.
• Só os seis objetos padrão da tabela de recursos, com os campos listados. Ficam de fora campos e objetos customizados (__c), tarefas, eventos, campanhas e os papéis de contato da oportunidade.
• Num recurso em incremental, registros apagados no Salesforce só saem da Strattum quando o recurso volta para full refresh.
• Se um full refresh falhar depois das primeiras 100.000 linhas de um recurso, por cota, sessão ou rede, a tabela bruta desse recurso fica parcialmente reescrita até o próximo full refresh bem-sucedido. A execução termina com falha e as tabelas clean não são reconstruídas a partir dela.
• As chamadas do conector consomem a cota diária de API da org. Em orgs com cota pequena, como a Developer Edition, um full refresh frequente de objetos grandes pode esgotar a cota de outras integrações.
• Os valores de oportunidade ficam na moeda corporativa da org, sem conversão de multimoeda.
• Um registro cujo dono é uma fila não ganha dono no Memory. Só donos que são usuários viram a relação com Agent.
• Uma conexão Salesforce por instalação.
• Uma conexão criada antes da troca para Client Credentials, com usuário, senha e security token, não sincroniza. Exclua a conexão e crie outra pelo assistente.

​

Troubleshooting

​

Próximos passos

Desenvolvimento local

O conector não lê variáveis do .env. As credenciais são informadas no Console e ficam no cofre de segredos da plataforma, sob os nomes SALESFORCE_INSTANCE_URL, SALESFORCE_CONSUMER_KEY e SALESFORCE_CONSUMER_SECRET. Para testar localmente, crie um External Client App numa Developer Edition e crie a conexão pelo Console da stack local.