Asignar fechas de origen a campos de fecha de Salesforce y registrar errores de respuesta en Jitterbit Studio

Introducción

Al escribir datos en Salesforce desde Studio, dos patrones de scripting se necesitan constantemente en asignaciones de transformación:

• Formato de campo de fecha: Los campos Date y DateTime de Salesforce requieren valores en formatos de cadena específicos. Cuando los datos de origen contienen una cadena de datetime (por ejemplo, una marca de tiempo de base de datos en formato YYYY-MM-DD HH:MM:SS), el valor debe convertirse al formato que Salesforce espera antes de que se ejecute la operación de escritura.
• Registro de errores de respuesta: Las operaciones de escritura de Salesforce (como Upsert, Insert y Update) devuelven un resultado por registro. Cuando el procesamiento falla para uno o más registros, el campo success en la respuesta se establece en false y se completa una matriz errors con uno o más mensajes. Sin una comprobación explícita en la transformación de respuesta, estos errores por registro pueden pasar desapercibidos incluso cuando la operación general de Studio reporta éxito.

Esta guía proporciona ambos scripts, explica cada componente y describe dónde colocarlos.

Patrón de diseño

Ambos scripts se colocan en transformaciones dentro de la misma cadena de operación de escritura de Salesforce. El script de conversión de fecha pertenece a la transformación de solicitud, que formatea los datos de origen antes de enviarlos a Salesforce. El script de registro de errores pertenece a la transformación de respuesta, que asigna la respuesta de la operación de escritura de Salesforce:

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

Parte 1: Asignar una fecha de origen a un campo de fecha de Salesforce

Los campos Date de Salesforce esperan valores en formato YYYY-MM-DD. Los campos DateTime de Salesforce esperan valores en formato ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). Las funciones GetUTCFormattedDate y GetUTCFormattedDateTime producen estos formatos a partir de una cadena de datetime de origen. Esta parte asume que el campo de origen contiene una cadena de datetime en formato YYYY-MM-DD HH:MM:SS y que la hora de origen es UTC.

Paso 1: Abrir el editor de scripts del campo de fecha de destino

1. En Studio, abre la transformación donde el esquema de destino proviene de una actividad de escritura de Salesforce (como Upsert, Insert o Update).

2. En el esquema de destino, localiza el campo de fecha o datetime a asignar.

3. Haz clic en el campo para abrir su editor de scripts.

Paso 2: Escribir el script de conversión de fecha

Para un campo Date de Salesforce, usa GetUTCFormattedDate, que devuelve solo la porción de fecha en formato YYYY-MM-DD:

// Source field must be in YYYY-MM-DD HH:MM:SS format, expressed in UTC.
// GetUTCFormattedDate returns YYYY-MM-DD, which is the required format for
// Salesforce Date fields.
// If the source date uses a different format, apply a conversion function
// before passing it to GetUTCFormattedDate. See the date and time functions
// reference for available options.
// The third argument (false) uses non-European (month-first) date format.
GetUTCFormattedDate(<source_field>, "UTC", false);

Para un campo DateTime de Salesforce, usa GetUTCFormattedDateTime en su lugar, que devuelve la cadena de datetime ISO 8601 completa:

GetUTCFormattedDateTime(<source_field>, "UTC", false);

Reemplaza <source_field> con la ruta al campo de fecha de origen tal como aparece en el esquema de origen de la transformación.

Parte 2: Registrar errores de una respuesta de operación de Salesforce

Las operaciones de escritura de Salesforce devuelven una respuesta que incluye un array result. Cada elemento corresponde a un registro de entrada y contiene:

• success: Un booleano que indica si ese registro fue procesado.
• errors: Un array de uno o más objetos de error, cada uno con un campo message. Se completa cuando success es false.
• Un campo clave (como un ID externo o el ID de registro de Salesforce).

Dado que result es un array, la transformación de respuesta hace un bucle sobre él una vez por cada registro de entrada. El script en esta parte verifica success en cada iteración y, cuando es false, escribe una entrada de registro que identifica el registro fallido por su valor de campo clave.

Paso 3: Agregar una transformación de respuesta a la operación

Si la actividad de escritura de Salesforce no tiene ya una transformación descendente que mapea la respuesta:

1. En el lienzo de diseño, agrega un paso de Transformación después de la actividad de escritura de Salesforce.

2. Abre la transformación. El esquema de respuesta de la actividad de Salesforce aparece como la fuente, incluyendo el nodo result (que hace un bucle una vez por cada registro de entrada), los campos success y errors dentro de result, y el campo clave del lado de la solicitud del esquema.

3. Para el esquema de destino, agrega un único campo String (por ejemplo, response), o utiliza un esquema de destino existente si la respuesta se está mapeando a un sistema descendente.

Paso 4: Escribir el script de registro de errores

En la transformación, haz clic en el campo de destino para abrir su editor de script. Escribe un script que verifique success para el registro de resultado actual y, cuando sea false, registre el valor del campo clave y los mensajes de error:

// Check whether Salesforce processed this record successfully.
// If not, log the key field value and Salesforce error messages to the operation log.
// Update the field references below to match the paths in your response schema.
// If the key field changes in your Salesforce operation, update the FindByPos reference.
If(<result.success> == false,
    WriteToOperationLog("The following record failed to process. Record: " +
    FindByPos(SourceInstanceCount(), <request.records#.keyField>) +
    " The issue was: " +
    SumString(<result.errors#.message>, ". ", false)));

Reemplaza las referencias de marcador de posición con las rutas de campo reales del esquema de origen de tu transformación:

Cada función en el script cumple un papel específico:

• La transformación hace un bucle sobre el array result, por lo que If evalúa success una vez por cada registro de entrada.
• WriteToOperationLog escribe los detalles del error en el registro de operación, donde son visibles después de que se ejecuta la operación.
• SourceInstanceCount devuelve el índice basado en 1 de la iteración del bucle actual. Dado que el array result y el array de registros de solicitud están en el mismo orden, este índice mapea el resultado actual nuevamente al registro de entrada correspondiente.
• FindByPos recupera el valor del campo clave en ese índice. La referencia de campo clave utiliza notación # para devolver el array completo de instancias para que FindByPos pueda seleccionar el elemento correcto.
• SumString concatena todos los valores message en el array errors para el registro de resultado actual en una única cadena, separada por ". ". Si Salesforce devuelve varios errores para el mismo registro, todos se incluyen en la entrada de registro.

Verificar la integración

1. Implementa y ejecuta la operación con una carga de prueba que incluya al menos un registro válido.

2. Abre los registros de operación y confirma que los valores del campo de fecha en la solicitud de Salesforce coincidan con el formato esperado para el tipo de campo destino: YYYY-MM-DD para campos Date, YYYY-MM-DDTHH:MM:SSZ para campos DateTime.

3. Para probar el script de registro de errores, incluye un registro deliberadamente inválido en la carga de prueba (por ejemplo, un registro que incumpla una regla de validación de Salesforce o que haga referencia a un registro relacionado inexistente). Después de ejecutar la operación, consulta el registro de operación para buscar una entrada que identifique el registro por su valor de campo clave e incluya el mensaje de error de Salesforce.

4. En Salesforce, confirma que los registros válidos se hayan creado o actualizado según lo esperado.