Gatilho do Salesforce

Aviso: o Application Integration já está disponível para seu projeto do Google Cloud. Agora é possível usar a Apigee Integration e o Application Integration no mesmo projeto do Google Cloud. Saiba mais

O gatilho do Salesforce permite detectar eventos Change Data Capture (CDC) ou Enterprise Messaging Platform. Ao usar esse gatilho, é possível iniciar sua integração com base em qualquer um dos eventos de CDC (Criar, Atualizar, Excluir ou Cancelar exclusão) ou os eventos da plataforma na instância do Salesforce.

Antes de começar

Nesta seção, descrevemos as etapas necessárias para conectar e configurar uma instância do Salesforce e usar eventos de Change Data Capture (CDC) ou Platform para fazer streaming das alterações para a integração da Apigee de maneira pub/sub. As etapas a seguir precisam ser concluídas antes de configurar qualquer tarefa ou gatilho relacionado ao Salesforce na Apigee:

• Definir um usuário de integração
• Configurar um conjunto de permissões
• Configurar um token de segurança
• Criar um app conectado

Observação: para concluir essas etapas, é necessário ter acesso de administração do sistema à instância do Salesforce. Se você não tiver acesso de administrador, compartilhe estas instruções com o administrador do Salesforce.

Neste tutorial, fornecemos instruções detalhadas, mas recomendamos que você entenda as opções de configuração do Salesforce. O Salesforce oferece uma documentação para o desenvolvedor detalhada para ajudar você a começar.

Definir um usuário de integração

Observação: se você já tiver um usuário de integração e souber a senha, pule para a próxima etapa. Se você precisar redefinir a senha, consulte a Etapa 6 abaixo.

Configure um usuário de integração com as seguintes etapas:

1. Faça login na instância do Salesforce com as credenciais de sysadmin.
2. Clique no ícone de engrenagem e selecione Configuração, como mostrado na imagem abaixo:
3. Clique em Usuários > Usuários no menu Administração.
4. No painel Usuários, selecione o botão Novo usuário.
5. Na caixa de diálogo Edição do usuário, preencha os seguintes detalhes:
   1. Nome: nome do usuário de integração.
   2. Sobrenome: o sobrenome do usuário de integração.
   3. Endereço de e-mail: e-mail do usuário da integração. O ideal é que seja um e-mail de grupo.
   4. Nome de usuário: nome de usuário de acordo com as convenções de nomenclatura no nível da organização.

      Para criar um novo usuário de integração, use o seguinte formato: EMAIL.SALESFORCE_ORG_NAME.SANDBOX_NAME

      Se você já tiver um usuário de integração, confirme se o nome de usuário foi inserido aqui.

   5. Papel: selecione uma opção no menu suspenso.
   6. Licença do usuário: digite Salesforce ou, se usar uma organização de avaliação, digite Salesforce Platform.
   7. Perfil: selecione o perfil de permissões para os usuários de integração na lista suspensa.

      Recomendamos a atribuição de um perfil sem permissões para proteger o acesso do Salesforce ao usuário de integração contra uso não autorizado.

   8. Clique em Save.
6. Para atualizar a senha do novo usuário de integração, siga estas etapas:
   1. Clique no botão Redefinir senhas no painel Usuários. Um e-mail de redefinição de senha é enviado para o endereço de e-mail associado ao usuário.
      Observação: confirme se você tem acesso à conta de e-mail associada ao usuário da integração antes de acionar o fluxo de redefinição de senha. Além disso, se você tiver ativado o SSO para esse usuário, não será possível redefinir a senha. Para ativar a opção de redefinição, acesse Perfil > Permissões do sistema e desmarque a opção Login com SSO ativado.
   2. Siga as etapas de redefinição de senha na conta de e-mail. Anote a nova senha, porque você precisará dela para uma etapa posterior.

Configurar um conjunto de permissões

Se você já tiver acesso a um conjunto de permissões adequado para um usuário de integração, pule esta etapa e prossiga para Configurar um token de segurança. Caso contrário, siga estas etapas para configurar um conjunto de permissões para o usuário de integração e o objeto do Salesforce.

Para configurar um conjunto de permissões para o usuário de integração:

1. No menu Configuração, clique em Usuários > Conjuntos de permissões.
2. No painel Conjuntos de permissões, clique no botão Novo.
3. Na caixa de diálogo Conjuntos de permissões, insira os seguintes detalhes:
   • Rótulo: insira um nome para o conjunto de permissões.
   • Licença: selecione Salesforce na lista suspensa Licença.
   • Clique em Save.
4. Na lista de opções de configuração Sistema, role para baixo e selecione Permissões do sistema
5. Na página Permissões do Sistema, clique no botão Editar.
6. Role a lista de permissões disponíveis para baixo e marque a caixa de seleção API ativada.

   A permissão Somente usuário da API também é obrigatória, mas não pode ser ativada até que o token de segurança exigido seja redefinido. Essa permissão é adicionada em uma etapa posterior.

7. (Opcional) Role e selecione Modificar todos os dados e Ver todos os dados, se aplicável. Essas permissões não são obrigatórias, mas podem ser úteis se você quiser que o usuário de integração acesse automaticamente novos objetos. Recomendamos ativar essas permissões somente para testes em um sandbox.
8. Role até o topo da lista de permissões e clique em Salvar.
9. Confirme suas configurações e clique em Salvar.

Para configurar o conjunto de permissões para o objeto do Salesforce:

1. Clique em Visão geral do conjunto de permissões para retornar à página de configuração principal Conjunto de permissões.
2. Selecione Configurações do objeto na seção Apps do painel Permissões definidas.
3. Role para baixo e selecione os objetos do Salesforce que exigem um conjunto de permissões. Este exemplo usa o objeto Opportunity.
   OBSERVAÇÃO: o CDC é compatível apenas com um subconjunto de objetos padrão do Salesforce. Para saber mais, consulte: Alterar suporte a objetos de evento.
4. Clique no botão Editar na página de detalhes do objeto.
5. Marque as caixas de seleção dos tipos de registro. Se você souber quais tipos de registro são necessários, selecione-os. Se não souber quais tipos de registro são necessários, selecione todos eles.
6. Marque as caixas de seleção das Permissões do objeto para ativá-las. As opções Ler e Ver tudo são recomendadas.
7. Conceda Acesso de leitura ou Acesso para edição em cada campo de objeto marcando a caixa de seleção correspondente.
   Observação: o acesso de gravação não é necessário para uso com CDC.
8. Role para a parte superior da página e clique em Salvar.

Configurar um token de segurança

Se você tiver criado um token de segurança para o usuário da integração antes e tiver redefinido a senha, um e-mail com um novo token de segurança será enviado automaticamente. Use o novo token e pule para a seção Criar um app conectado.

Caso contrário, siga as etapas abaixo para redefinir o token de segurança do usuário de integração:

1. Faça login no Salesforce como usuário de integração com o nome de usuário e a senha definidos em uma etapa anterior.
2. No menu principal, clique na foto do perfil e em Configurações.
3. No menu Configurações, selecione Redefinir meu token de segurança para abrir o painel Redefinir token de segurança.
4. Clique no botão Redefinir token de segurança.
5. Procure na conta de e-mail associada ao usuário de integração um e-mail contendo o novo token de segurança. Anote o novo token de segurança, porque você precisará dele para uma etapa posterior.
6. (Opcional) Ative a permissão Somente usuário da API nas Permissões do sistema do seu conjunto de permissões, conforme descrito em Configurar uma permissão acima.

Criar um app conectado

A permissão de administração do sistema é necessária para configurar um app conectado. Se você estiver conectado como um usuário de integração, saia e faça login novamente como sysadmin.

Siga estas etapas para configurar um aplicativo conectado:

1. Clique no ícone de engrenagem e selecione Configuração.
2. No menu Configuração, procure e selecione Gerenciador de aplicativo, como mostrado na imagem abaixo:
3. Clique em New Connected App.
4. No painel de configuração, forneça os detalhes a seguir:
   • Nome do app conectado: digite um nome para o app conectado.
   • Nome da API: digite o nome da API.
   • E-mail de contato: informe um e-mail para seu app conectado, de preferência um alias de e-mail de grupo.
   • API (ativar configurações do OAuth): selecione Ativar configurações do OAuth. Em seguida, defina o seguinte:
     1. (Opcional) URL de callback: só será necessário se você quiser que um serviço externo realize a validação. Se você optar por fornecer um callback, inclua o prefixo http(s)://.
     2. Escopos do OAuth selecionados: selecione:
        • Acessar e gerenciar seus dados (API)
        • Faça solicitações em seu nome a qualquer momento (refresh_token, offline_access)
5. Clique em Save.
   Observação: o app conectado recém-criado não funcionará nos primeiros 2 a 10 minutos após a criação.
6. Clique em Continuar. Você precisa autorizar novamente com um código de verificação enviado para seu endereço de e-mail.
7. Depois de verificar o código, um secret do cliente e um token do cliente serão exibidos na próxima página. Anote esses valores, porque eles serão usados na configuração do módulo do Auth para Apigee.
8. Clique no botão Gerenciar.
9. Na página Detalhes do app conectado, clique no botão Editar políticas.
10. Na seção Políticas do OAuth, altere o valor no menu suspenso Usuários permitidos para Usuários aprovados por administradores são pré-autorizados.
11. Clique em Save.
12. Role até a seção Perfis e Conjuntos de permissões da página para selecionar o perfil ou o conjunto de permissões que você quer aplicar ao app conectado.
    Você pode selecionar um perfil, um conjunto de permissões ou uma mistura de ambos, o que permitirá que os usuários com o perfil ou o conjunto de permissões correto acessem o aplicativo conectado.
13. Selecione o perfil ou o conjunto de permissões desejado.
14. Clique em Save.

Etapas de pré-requisito para usar eventos do CDC

Antes de configurar o gatilho de integração da Apigee para usar eventos do CDC, adicione um objeto configurado ao CDC no Salesforce:

1. Faça login no Salesforce como um sysadmin.
2. Clique no ícone de engrenagem e em Configuração.
3. Usando a navegação à esquerda, pesquise e selecione Change Data Capture.
4. Na página de configuração Change Data Capture, localize o objeto do Salesforce que você quer usar na coluna Entidades disponíveis e arraste-o para a coluna Entidades selecionadas.
   Observação: é possível selecionar até cinco objetos por licença do Salesforce para CDC. Entre em contato com seu representante do Salesforce para mais informações e opções de licenciamento.
5. Clique em Save.

Pré-requisitos para usar eventos de plataforma

Antes de configurar o gatilho da Apigee para usar eventos da plataforma, conclua as etapas a seguir no Salesforce:

• Criar um evento de plataforma
• Atualizar permissões para o evento da plataforma

Criar um evento de plataforma

Para criar um evento de plataforma, siga estas etapas:

1. Faça login na instância do Salesforce com as credenciais de sysadmin.
2. Clique no ícone de engrenagem e selecione Configuração.
3. No painel de navegação, procure Plataforma e clique em Eventos de plataforma.

4. Na página Eventos da plataforma, clique em Novo evento da plataforma e defina as seguintes propriedades:

• Rótulo
• Rótulo plural
• Nome do objeto(este campo é preenchido automaticamente)
• Comportamento de publicação: selecione qualquer um dos seguintes valores:
  • Publicar após confirmação: reverte o streaming de eventos se uma condição não for atendida.
  • Publicar imediatamente: aciona o evento instantaneamente, sem aguardar validação.
  Para mais informações sobre o comportamento de publicação, consulte Eventos e transações da plataforma.
• Deployment Status (opcional): selecione Deployed se o evento estiver pronto para implantação.

Clique em Save.

Criar campos personalizados. Para criar os campos personalizados, clique em Novo na seção Campos personalizados e relacionamentos e selecione o tipo de campo personalizado. É possível criar quantos campos personalizados forem necessários.

Depois de criar os campos personalizados, na página Eventos da plataforma, observe o valor do campo Nome da API. O nome do objeto termina com _e, o que significa que se trata de um objeto de evento da plataforma. Para um objeto CDC, o nome do objeto termina com _c.

Atualizar permissões para o evento da plataforma

O conjunto de permissões deve ser atualizado para permitir que o usuário de integração acesse o evento de plataforma recém-criado.

Para atualizar as permissões, execute as seguintes etapas:

1. No menu Configuração, clique em Usuários > Conjuntos de permissões.
2. Na página Conjuntos de permissões, clique na permissão criada anteriormente.
3. Clique em Configurações de objetos > Plural Label of the Platform Event.
4. Na seção Permissões do objeto, ative as permissões Ler e Criar.
5. Clique em Save.

Adicionar um gatilho do Salesforce

Para adicionar um gatilho do Salesforce a uma integração nova ou atual, siga as etapas abaixo:

1. Na IU da Apigee, selecione sua organização da Apigee.
2. Clique em Desenvolver > Integrações.
3. Selecione uma integração existente ou clique em Criar integração.

   Caso você esteja criando uma nova integração, siga estas etapas:

   1. Digite um nome e uma descrição na caixa de diálogo Criar integração.
   2. Selecione uma Região para a integração na lista de regiões compatíveis.
   3. Clique em Criar.

   Isso abre a integração na página do designer de integração.

4. Na barra de navegação do designer de integração, clique em +Adicionar uma tarefa/gatilho> Tarefas para ver a lista de tarefas disponíveis.
5. Selecione uma integração ou clique em CRIAR INTEGRAÇÃO.
6. No editor de integração, clique em + Adicionar uma tarefa/gatilho > Gatilhos para ver as opções disponíveis.
7. Clique e arraste o elemento Gatilho do Salesforce para o designer.

Configurar o gatilho do Salesforce

Para configurar o gatilho do Salesforce, execute as etapas a seguir:

1. Clique em gatilho do Salesforce no editor de integração para exibirr o painel de configuração do gatilho.
2. Selecione uma instância do Salesforce na lista suspensa Configuração de instância do Salesforce.

   Se você não tiver uma instância do Salesforce, crie uma nova. Para mais informações, consulte Criar uma nova instância do Salesforce.

3. Selecione um canal do Salesforce na lista suspensa Configuração do canal do Salesforce.

   Se você não tiver um canal do Salesforce, crie um novo. Para mais informações, consulte Criar um novo canal do Salesforce.

4. Se você escolheu o tipo de evento como CDC, selecione qualquer uma das seguintes operações:
   • Create
   • Update
   • Delete
   • Undelete

   O gatilho é executado somente se a operação específica ou de lacuna ocorrer.

   O gatilho do Salesforce pode ser configurado para apenas uma operação. Se você quiser executar o gatilho para várias operações, crie um gatilho do Salesforce para cada operação.

Criar uma nova instância do Salesforce

Para processar uma nova instância do Salesforce, execute as seguintes etapas:

1. Nas propriedades editáveis do gatilho, clique em Selecionar uma configuração de instância do Salesforce > + Adicionar nova configuração de instância do Salesforce.
2. Na caixa de diálogo Adicionar configuração de instância do Salesforce, defina as seguintes propriedades:
• Nome da conexão da instância do Salesforce: insira um nome para a instância.

  Após a configuração, você usará esse nome para se referir à instância do Salesforce.

• Domínio do Salesforce: insira uma autoridade de serviço para a instância. Encontre o domínio na sua conta do Salesforce. Por exemplo, instance.my.salesforce.com. A imagem a seguir mostra o domínio do Salesforce:

  

• Perfil de autenticação: selecione um perfil de autenticação.

  Se você não tiver um perfil de autenticação, crie um novo do tipo de autenticação Credenciais de senha do proprietário do recurso OAuth 2.0. A imagem a seguir mostra os campos necessários para criar um perfil de autenticação:

  

  Para informações sobre os campos, consulte Credenciais de senha do proprietário do recurso OAuth 2.0. Para a instância do Salesforce, insira os seguintes valores:
  • ID do cliente: insira a chave do consumidor que você anotou ao configurar um app conectado.
  • Secret: insira o secret do cliente que você anotou ao configurar um app conectado.
  • Senha: digite a senha do usuário com o formato USER_PASSWORDSECURITY_TOKEN. Substitua:
    • USER_PASSWORD: a senha do usuário do Salesforce.
    • SECURITY_TOKEN: o token de segurança que você definiu para sua integração.
    Por exemplo, se USER_PASSWORD for test-password e SECURITY_TOKEN for 737K27NCa3O6, sua senha será test-password737K27NCa3O6.

ID da organização do Salesforce: insira o ID da organização da instância do Salesforce. Solicite o ID ao administrador do Salesforce.

Clique em Add.

Criar um novo canal do Salesforce

Para conquistar um novo canal do Salesforce, siga estas etapas:

1. Nas propriedades editáveis do gatilho, clique em Selecionar uma configuração de canal do Salesforce > Adicionar nova configuração de canal do Salesforce.
2. Na caixa de diálogo Adicionar configuração de canal do Salesforce, insira o nome do objeto da propriedade Nome do objeto do Salesforce.

   Se não tiver certeza do nome do objeto, entre em contato com o administrador do Salesforce.

3. Clique em Add.

Variáveis de saída

A resposta do gatilho do Salesforce está disponível para você nas variáveis de saída.

As variáveis de saída para um evento CDC estão descritas na tabela a seguir:

Variável	Tipo de dado	Descrição
SalesforceTriggerCdcPayload	JSON	Detalhes do evento de alteração.
SalesforceTriggerEvent	JSON	Contém replayId do evento.
SalesforceTriggerSchema	String	Esquema de gatilho.
SalesforceTriggerCdcSnapshot	JSON	Snapshot do objeto após o evento de alteração. Este campo está disponível apenas para operações Update e Create.
SalesforceTriggerCdcRecordId	String	Contém o recordId do registro atualizado ou adicionado. O recordId é um identificador do objeto Salesforce alterado.

As variáveis de saída para um evento Platform estão descritas na tabela a seguir:

Variável	Tipo de dado	Descrição
SalesforceTriggerPEPayload	JSON	Detalhes do evento de alteração.
SalesforceTriggerEvent	JSON	Contém replayId do evento.
SalesforceTriggerSchema	String	Esquema de gatilho.

O parâmetro de saída para este acionador é a variável JSON CdcTriggerPayload. A variável JSON contém objetos de registro atualizados.

Práticas recomendadas

O uso do gatilho do Salesforce é recomendado nos casos em que você quer usar as notificações do Salesforce para acionar integrações sem escrever código personalizado para publicar eventos do Salesforce. Qualquer pequena alteração de campo no caso do Salesforce acionará um evento CDC do Salesforce e, portanto, acionará uma integração, o que pode resultar em ruídos significativos. Use Alterar filtros de evento para filtrar apenas os eventos CDC necessários que acionam a integração. O uso de Alterar filtros de eventos pode ajudar a reduzir o ruído de integração e garantir a conformidade com as limitações de licenças.

Da mesma forma, recomendamos cancelar a publicação de qualquer integração usando esse gatilho quando a integração não for mais necessária. Até que a publicação seja cancelada ou excluída, a integração continuará a detectar os eventos de plataforma e CDC do Salesforce.

Considerações

Antes de usar o gatilho do Salesforce para executar a integração, considere o seguinte:

• O Salesforce normalmente envia, no máximo, 100 mil CDC e eventos da Plataforma por dia. Converse com o administrador do Salesforce para entender as restrições de licença antes de escolher eventos de CDC para seu gatilho de integração.
  Observação: várias integrações com o mesmo canal do Salesforce não dobrarão o consumo de cota do Salesforce.
• Se você estiver planejando uploads em massa para o Salesforce, considere pausar o CDC para reduzir o ruído de integração e garantir a conformidade com as limitações da sua licença.
• O tamanho máximo da mensagem de evento que o Salesforce pode publicar é de 1 MB. Para mais informações, consulte Alterar alocações de captura de dados.
• As integrações da Apigee não são compatíveis com eventos CDC do Salesforce nas regiões de minicluster a seguir:
  • asia-northeast1
  • asia-south1
  • australia-southeast1
  • europe-west2
  • europe-west3
  • europe-west6
  • northamerica-northeast1
  • southamerica-east1
  • us-east4
  • us-west2