Consultar registros de Salesforce usando SOQL en Jitterbit Studio

Introducción

SOQL (Salesforce Object Query Language) es el lenguaje de consulta que utilizan todas las APIs de Salesforce para recuperar registros. Studio ofrece dos enfoques para consultar registros de Salesforce:

• Actividad Salesforce Query: Un asistente de configuración que construye y valida la declaración SOQL, genera un esquema de respuesta y actúa como fuente en una operación. Úsalo para lecturas masivas donde los registros de Salesforce impulsan una transformación.
• Funciones de scripts (SfLookup, SfLookupAll): Búsquedas en línea ejecutadas dentro de un script o mapeo de transformación. Úsalas para búsquedas de un solo valor o de pequeños conjuntos que admitan lógica de procesamiento, como resolver un ID de registro padre durante una transformación.

Para la documentación de referencia completa, consulta Actividad Salesforce Query y Funciones Salesforce.

Esta guía asume que ya hay una conexión Salesforce configurada en el proyecto.

Patrón de diseño

La actividad Query sigue el patrón de transformación:

Parte 1: Configurar la actividad Salesforce Query

Paso 1: Nombra la actividad y selecciona objetos

1. En el lienzo de diseño, arrastra un tipo de actividad Query desde una conexión Salesforce existente para iniciar la operación.

2. Haz doble clic en la actividad para abrir su configuración.

3. Nombre: Ingresa un nombre descriptivo, como Query Contacts.

4. Seleccionar objeto(s): Haz clic en el objeto principal a consultar, por ejemplo Contact o Account. Solo se puede seleccionar un objeto principal.

5. Seleccionar objeto(s) relacionado(s): Opcionalmente, selecciona la casilla junto a cada objeto relacionado a incluir en la consulta. Esto produce una consulta relacional, que te permite recuperar campos de objetos secundarios o principales en una única solicitud. La selección de objetos relacionados se limita a hijos inmediatos y antecesores hasta cinco niveles.

6. Haz clic en Siguiente.

Paso 2: Selecciona campos y crea condiciones

1. En el panel Seleccionar campos y crear condiciones, selecciona las casillas de los campos a incluir. El cuadro de texto Declaración SOQL a la derecha se rellena automáticamente conforme realizas selecciones.

2. Para agregar cláusulas no admitidas por el selector de campos (como ORDER BY, LIMIT o subconsultas), edita directamente el cuadro de texto de la declaración SOQL. Para la referencia de sintaxis SOQL, consulta la documentación de Salesforce sobre sintaxis SELECT de SOQL.

3. Para filtrar resultados, agrega una cláusula WHERE usando los menús desplegables Objeto: Campo, Operador y Valor, y luego haz clic en el enlace para agregar la condición a la cláusula. Repite para agregar múltiples condiciones, insertando AND u OR entre ellas.

   Consejo

   Para consultar solo registros modificados desde un punto específico en el tiempo (el patrón de filtro más común en integraciones de sincronización), agrega una condición en LastModifiedDate usando el operador >= y una variable de proyecto o variable global que contenga la marca de tiempo. Por ejemplo:

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

   Reemplaza la fecha literal con una referencia de variable como [last_sync_timestamp] para que el valor pueda actualizarse entre ejecuciones sin modificar la configuración de la actividad.

1. Haz clic en Test Query para validar la declaración. La consulta debe pasar la validación antes de que el botón Next esté disponible.

2. Haz clic en Next.

Paso 3: Revisa el esquema de datos

1. Revisa el esquema de respuesta generado a partir de la consulta. Este esquema se usa en la transformación en la Parte 2.

2. Haz clic en Finished.

Parte 2: Asignar registros en una transformación

1. En el lienzo de diseño, añade un paso Transformation después de la actividad Query y luego añade una actividad de destino después de la transformación.

2. Abre la transformación. El esquema de respuesta de la actividad Query aparece como origen. Cuando la transformación refleja el esquema de la actividad Salesforce, el origen incluye un nodo raíz records. Este nodo se establece automáticamente como un loop node para que cada registro del conjunto de resultados se procese individualmente.

3. Asigna los campos bajo el nodo records a los campos de destino correspondientes.

Para un tutorial completo del mapeo de transformación, consulta Transformation mapping overview.

Parte 3: Alternativamente, consulta desde un script

Utiliza funciones de scripting cuando necesites buscar un valor o un pequeño conjunto de registros en línea (por ejemplo, para resolver un ID de registro principal durante una transformación o para controlar la lógica condicional en un script). Las funciones de scripting inician sesión en Salesforce automáticamente usando la referencia del endpoint; no se requiere una llamada de inicio de sesión separada.

SfLookup

SfLookup devuelve el primer campo del primer registro que coincide con la consulta. Úsalo para resolver un único valor, como un ID de cuenta o contacto:

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

SfLookupAll

SfLookupAll devuelve un arreglo bidimensional de todos los registros que coinciden con la consulta. Úsalo cuando necesites iterar sobre un conjunto de resultados en un 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"];

Se puede acceder a los campos por nombre (contacts[0]["Name"]) o por índice de base cero (contacts[0][1]).

SfCacheLookup

SfCacheLookup tiene la misma firma que SfLookup pero almacena en caché el resultado durante la duración de la cadena de operación. Úsalo cuando la misma búsqueda se ejecuta varias veces con parámetros idénticos (por ejemplo, cuando buscas un valor de referencia estática una vez por iteración del bucle de transformación):

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

Las llamadas posteriores con la misma referencia de endpoint y cadena SOQL devuelven el valor almacenado en caché sin hacer otra llamada a la API.

Verifica la integración

Implementa y ejecuta la operación. Consulta los operation logs para confirmar que la actividad Query se ejecutó correctamente y verifica que el recuento de registros en el destino coincida con el conjunto de resultados esperado de Salesforce. Si no se devuelve ningún registro, verifica las condiciones de la cláusula WHERE y confirma que todas las variables usadas en la cláusula han sido asignadas a sus valores esperados antes de que se ejecute la operación.