Consultar registros do Salesforce usando SOQL no Jitterbit Studio

Introdução

SOQL (Salesforce Object Query Language) é a linguagem de consulta usada por todas as APIs do Salesforce para recuperar registros. O Studio oferece duas abordagens para consultar registros do Salesforce:

• Atividade Salesforce Query: Um assistente de configuração que cria e valida a instrução SOQL, gera um schema de resposta e atua como a origem em uma operação. Use isso para leituras em massa onde os registros do Salesforce orientam uma transformação.
• Funções de script (SfLookup, SfLookupAll): Consultas inline executadas em um script ou mapeamento de transformação. Use estas para consultas de valor único ou pequeno conjunto que suportam lógica de processamento, como resolver um ID de registro pai durante uma transformação.

Para documentação de referência completa, consulte Atividade Salesforce Query e Funções do Salesforce.

Este guia pressupõe que uma conexão Salesforce já esteja configurada no projeto.

Padrão de design

A atividade Query segue o padrão de transformação:

Parte 1: Configurar a atividade Salesforce Query

Etapa 1: Nomear a atividade e selecionar objetos

1. Na tela de design, arraste um tipo de atividade Query de uma conexão Salesforce existente para iniciar a operação.

2. Clique duas vezes na atividade para abrir sua configuração.

3. Nome: Digite um nome descritivo, como Query Contacts.

4. Selecionar Objeto(s): Clique no objeto principal a consultar, por exemplo Contact ou Account. Apenas um objeto principal pode ser selecionado.

5. Selecionar Objeto(s) Relacionado(s): Opcionalmente, marque a caixa de seleção ao lado de cada objeto relacionado a incluir na consulta. Isso produz uma consulta de relacionamento, que permite recuperar campos de objetos filhos ou pais em uma única solicitação. A seleção de objetos relacionados é limitada a filhos imediatos e ancestrais até cinco níveis.

6. Clique em Próximo.

Etapa 2: Selecionar campos e criar condições

1. No painel Selecionar Campos e Criar Condições, marque as caixas de seleção dos campos a incluir. A caixa de texto Instrução SOQL à direita é preenchida automaticamente conforme você faz as seleções.

2. Para adicionar cláusulas não suportadas pelo seletor de campos (como ORDER BY, LIMIT ou subconsultas), edite a caixa de texto da instrução SOQL diretamente. Para referência de sintaxe SOQL, consulte a documentação do Salesforce sobre Sintaxe SOQL SELECT.

3. Para filtrar resultados, adicione uma cláusula WHERE usando os dropdowns Objeto: Campo, Operador e Valor, depois clique no link de adição para anexar a condição à cláusula. Repita para adicionar várias condições, inserindo AND ou OR entre elas.

   Dica

   Para consultar apenas registros modificados desde um ponto específico no tempo (o padrão de filtro mais comum em integrações de sincronização), adicione uma condição em LastModifiedDate usando o operador >= e uma variável de projeto ou variável global que contenha o timestamp. Por exemplo:

   SELECT Id, Name, Email FROM Contact WHERE LastModifiedDate >= 2024-01-01T00:00:00Z
   

   Substitua a data literal por uma referência de variável como [last_sync_timestamp] para que o valor possa ser atualizado entre execuções sem modificar a configuração da atividade.

1. Clique em Test Query para validar a instrução. A consulta deve passar na validação antes que o botão Next fique disponível.

2. Clique em Next.

Etapa 3: Revisar o esquema de dados

1. Revise o esquema de resposta gerado a partir da consulta. Este esquema é usado na transformação na Parte 2.

2. Clique em Finished.

Parte 2: Mapear registros em uma transformação

1. Na tela de design, adicione uma etapa de Transformation após a atividade Query e, em seguida, adicione uma atividade de destino após a transformação.

2. Abra a transformação. O esquema de resposta da atividade Query aparece como a origem. Quando a transformação espelha o esquema da atividade Salesforce, a origem inclui um nó raiz records. Este nó é definido automaticamente como um nó de loop para que cada registro no conjunto de resultados seja processado individualmente.

3. Mapeie os campos sob o nó records para os campos de destino correspondentes.

Para uma análise completa do mapeamento de transformação, consulte Visão geral do mapeamento de transformação.

Parte 3: Como alternativa, consultar a partir de um script

Use funções de script quando precisar pesquisar um valor ou um pequeno conjunto de registros inline (por exemplo, para resolver uma ID de registro pai durante uma transformação ou para direcionar lógica condicional em um script). As funções de script fazem login no Salesforce automaticamente usando a referência do endpoint; nenhuma chamada de login separada é necessária.

SfLookup

SfLookup retorna o primeiro campo do primeiro registro que corresponde à consulta. Use-a para resolver um único valor, como uma ID de conta ou contato:

accountId = SfLookup("<TAG>endpoint:salesforce/Salesforce</TAG>",
    "SELECT Id FROM Account WHERE Name='" + $account_name + "'");
If(IsNull(accountId), RaiseError(GetLastError()));

SfLookupAll

SfLookupAll retorna um array bidimensional de todos os registros que correspondem à consulta. Use-a quando precisar iterar sobre um conjunto de resultados em um script:

contacts = SfLookupAll("<TAG>endpoint:salesforce/Salesforce</TAG>",
    "SELECT Id, Name, Email FROM Contact WHERE AccountId='" + $account_id + "'");
If(IsNull(contacts), RaiseError(GetLastError()));
firstContactName = contacts[0]["Name"];

Os campos podem ser acessados por nome (contacts[0]["Name"]) ou por índice baseado em zero (contacts[0][1]).

SfCacheLookup

SfCacheLookup tem a mesma assinatura que SfLookup, mas armazena em cache o resultado durante a cadeia de operações. Use-a quando a mesma pesquisa é executada várias vezes com parâmetros idênticos (por exemplo, ao pesquisar um valor de referência estático uma vez por iteração do loop de transformação):

orgId = SfCacheLookup("<TAG>endpoint:salesforce/Salesforce</TAG>",
    "SELECT Id FROM Organization LIMIT 1");

Chamadas subsequentes com a mesma referência de endpoint e string SOQL retornam o valor em cache sem fazer outra chamada de API.

Verificar a integração

Implante e execute a operação. Verifique os logs de operação para confirmar que a atividade Query foi executada com sucesso e verifique se a contagem de registros no destino corresponde ao conjunto de resultados esperado do Salesforce. Se nenhum registro for retornado, verifique as condições da cláusula WHERE e confirme que todas as variáveis usadas na cláusula foram atribuídas aos seus valores esperados antes da execução da operação.