Actualizar Datos de Clarizen con una Cadena de Operaciones¶

Introducción¶

Este patrón de integración utiliza una cadena de operaciones dentro de Harmony Design Studio para insertar datos en su instancia de Clarizen conectada. Antes de comenzar, ya debería estar familiarizado con el funcionamiento de Jitterbit, configure un extremo de Clarizen, y ser capaz de usar la consultar nativa, crear, y actualizar operaciones dentro de Design Studio Clarizen Connector.

Resumen¶

El propósito de una operación upsert es actualizar registros que ya existen e insertar registros que no existen. Aunque la API REST de Clarizen no admite explícitamente las operaciones upsert, Jitterbit permite configuraciones sencillas y flexibles de los flujos de trabajo de inserción/actualización.

En este patrón, se utiliza un campo de clave única para determinar la existencia de un registro mediante la búsqueda de un registro en Clarizen cuyo campo de clave única tenga el mismo valor. El campo de clave única debe tener un valor diferente para cada registro y ser el mismo en ambos sistemas. Se puede usar cualquier campo que ya mantenga estas propiedades y, si no existe ninguno en el objeto, se puede crear un campo personalizado en Clarizen para almacenar los ID de registro del sistema de origen.

El siguiente diagrama muestra el flujo de trabajo generalizado de un upsert Clarizen usando este patrón de diseño.

adjunto

Específicamente, la modificación de registros en Clarizen requiere el mantenimiento de pares (clave, valor) de la clave/valores únicos y su coincidencia con los ID de registro de Clarizen. Luego, los registros se pueden separar en "crear" o "actualizar" en función de si su clave única tiene una ID de Clarizen correspondiente en el almacén de claves.

Existen numerosas formas de implementar el almacén de claves y la separación de registros, con diferentes niveles de eficiencia. A continuación se muestra la implementación que seguiremos en este patrón, que sacrifica la eficiencia por la simplicidad en ciertos lugares. Los números corresponden a los pasos incluidos en la siguiente sección.

adjunto

Implementación¶

Las siguientes secciones describen los pasos principales para implementar este patrón de diseño. Como ejemplo, insertaremos datos de objeto de usuario existentes en Clarizen en nuestros datos de objeto de cliente en Clarizen. Esta es la configuración final:

adjunto

Paso 1: Obtenga los Datos de Origen para Ser Alterados¶

adjunto

Primero, traiga los datos que desea usar para la operación upsert usando la funcionalidad estándar de Jitterbit. Puede usar una variedad de fuentes de datos.

Para este ejemplo, consultar a todos los empleados existentes del objeto Usuario dentro de nuestra instancia de Clarizen conectada, y luego usaremos estos datos como fuente para nuestro upsert. Para el ejemplo, configuramos nuestros datos de origen de la siguiente manera:

Cree una nueva operación de consultar de Clarizen para el objeto Usuario y seleccione todos los campos. La consultar se denomina "Consulta de empleados".
Cree una operación a partir de esta consultar (haga clic en el botón Crear operación). La operación se denomina "1. Obtener datos de origen para modificar".
Pase los datos a través de la transformación sin ningún cambio (haga clic con el botón derecho en Respuesta > Paso a través). También puede configurar una transformación normal para obtener datos en el formato que le gustaría usar.
Establezca el destino como almacenamiento temporal, denominado "Empleados" (haga doble clic en Objetivo > Crear nuevo destino; escriba: "Almacenamiento temporal"; nombre de archivo: "empleados").
Copie el destino "Empleados" en una fuente, también denominada "Empleados" (dentro del árbol de la izquierda, haga clic con el botón derecho en el destino específico > Copiar a nueva fuente). Esto se utilizará como fuente para nuestros datos upsert en la próxima operación.
Ejecute una nueva operación de transformación en caso de éxito (haga clic con el botón derecho en el fondo de la operación > En caso de éxito > Operación > Crear nueva operación > Transformación). Esta operación se usará en el Paso 2, a continuación.

Paso 2: Agregue Claves Únicas a un Diccionario¶

adjunto

En este patrón se utiliza un diccionario para mantener los pares (clave única, ID de Clarizen). En esta operación, insertaremos un secuencia de comandos antes de la fuente para inicializar un diccionario global y crearemos una transformación para mapear el campo clave único.

Dependiendo de cómo haya configurado su fuente, ya debería tener una nueva operación en blanco creada desde el Paso 1. De lo contrario, cree una nueva operación de transformación (Nueva operación > Transformación). La operación se llama "2. Agregar claves únicas al diccionario".
Especifique la fuente de sus datos. La fuente debe contener todos los registros que se van a modificar. En el ejemplo, usamos la fuente "Empleados" creada en el Paso 1 (haga doble clic en Fuente y seleccione la fuente "Empleados" existente).
No se necesita ningún objetivo, así que elimine el objetivo de la operación (haga clic con el botón derecho en Objetivo > Eliminar del gráfico).
Inserte un secuencia de comandos antes de la fuente (haga clic con el botón derecho en Fuente > Insertar antes de esto > Secuencia de Comandos) y cree un nuevo secuencia de comandos (llamado "Inicializar el diccionario") como sigue:
```
<trans>
$UpsertIdDict = Dict();
</trans>
```
Cree una nueva transformación cuyas estructuras de origen y destino sean las mismas que sus datos (haga doble clic en Transformación > Crear nueva Transformación). La transformación del ejemplo se llama "Asignar campo clave único".
1. Para la fuente, seleccione la misma estructura que sus datos de origen. En el ejemplo, nuestra fuente es el resultado de una consultar de Clarizen, por lo que usamos "Respuesta de función de Clarizen ". Para el objetivo, elegiremos "Texto".
2. Para la fuente, siga las indicaciones del asistente, en el ejemplo seleccionando "Consulta" y la operación de consultar específica utilizada como fuente.
3. Para el destino, crearemos manualmente una nueva estructura que tenga un campo (Definiciones de formato de archivo disponibles > Crear nuevo > Crear manualmente; en Defina propiedades de segmento, haga clic en Nuevo y escriba un nombre de campo, por ejemplo, "ID"). En el ejemplo, el nombre del formato de archivo es "Claves únicas".
4. En la transformación, itere sobre el campo de clave única asignándolo del lado de origen al lado de destino (en el ejemplo, arrastre y suelte el campo Usuario > Entidad > "id" a la izquierda del campo "ID" a la derecha).
Modifique la transformación para que se agregue una nueva entrada en el diccionario con el campo de clave única como ID y '0' como valor. Para hacer esto, haga doble clic en su campo de ID en el lado de destino e ingrese lo siguiente:
```
<trans>
AddToDict($UpsertIdDict, Quote(<Your_Unique_Key>), 0)
</trans>
```
En el ejemplo, \<Your_Unique_Key> se reemplaza con OUTPUT$User$Entity.id$ al seleccionar el campo de clave única del lado de la fuente.
```
<trans>
AddToDict($UpsertIdDict, Quote(OUTPUT$User$Entity.id$), 0)
</trans>
```
Inserte un nuevo secuencia de comandos después de la transformación que acaba de crear (haga clic con el botón derecho en la transformación > Insertar después de esto > Secuencia de Comandos) y cree un nuevo secuencia de comandos llamado "Actualizar almacén de claves". Por ahora dejaremos el secuencia de comandos en blanco. Esto se completará más adelante durante el siguiente paso para crear un filtro de modo que solo se consulten los registros de Clarizen con claves únicas que coincidan con una en el diccionario.

Paso 3: Consulta Clarizen para Registros con Claves Únicas Coincidentes¶

adjunto

Para llenar el diccionario con los ID de Clarizen asociados, en este patrón deberá crear una nueva operación de consultar de Clarizen para el objeto que desea insertar. Es necesario consultar el ID y la clave única, y se debe agregar una variable de proyecto al final para incluir una cláusula WHERE.

Cree una nueva operación de consultar de Clarizen para su objeto (en el ejemplo, usamos el objeto Cliente) con una cadena de consultar en el siguiente formato.
```
SELECT <Your_Unique_Key> FROM <Your_Object> Where <Your_Unique_Key> In [ClarizenWhereClause]
```
En el ejemplo, usaremos un campo personalizado llamado "C_JB_External_Id" en nuestro objeto Cliente como nuestra clave única, de la siguiente manera:
```
SELECT C_JB_External_Id FROM Customer Where C_JB_External_Id In [ClarizenWhereClause]
```
Nota

[ClarizenWhereClause] es una variable de proyecto que definiremos más adelante en el secuencia de comandos"Actualizar almacén de claves".
Cree una operación a partir de esta consultar (haga clic en el botón Crear operación). La operación se llama "3. Consultar Clarizen para registros con claves únicas coincidentes".
No se necesita ningún objetivo, así que elimine el objetivo de la operación (haga clic con el botón derecho en Objetivo > Eliminar del gráfico).
Cree una nueva transformación (haga doble clic en Transformación > Crear nueva Transformación). La transformación del ejemplo se denomina "Coincidencia de claves únicas".
1. En el ejemplo, la fuente ya debería estar definida como la respuesta de la consultar del objeto. Para el objetivo, elegiremos "Texto".
2. Para la estructura de destino, seleccione el mismo formato de archivo creado durante el paso 2 (en el ejemplo, denominado "Claves únicas").
3. En la transformación, asigne los campos de ID del lado de origen al lado de destino (en el ejemplo, arrastre y suelte tanto el campo Usuario > Entidad > "id" como el campo personalizado "C_JB_External_Id" a la izquierda al campo "ID" a la derecha).
Modifique la transformación para escribir los ID de Clarizen en los valores del diccionario para las claves únicas correspondientes. Esto establecerá su clave única igual a su ID de objeto. Para hacer esto, haga doble clic en su campo de ID en el lado de destino e ingrese lo siguiente:
```
<trans>
$UpsertIdDict[Quote(OUTPUT$<Your_Object>$Entity.<Your_Unique_Key>$)] = OUTPUT$<Your_Object>$Entity.id$;
</trans>
```
Recuerde que puede hacer doble clic en los campos debajo de SALIDA en el lado derecho para obtener los campos apropiados para su clave y objeto únicos. El ejemplo dice lo siguiente:
```
<trans>
$UpsertIdDict[Quote(OUTPUT$Customer$Entity.C_JB_External_Id$)] = OUTPUT$Customer$Entity.id$;
</trans>
```
A continuación, cree un nuevo secuencia de comandos que construya una cláusula IN a partir de las claves del diccionario. Esto se puede crear fuera de la operación (en el árbol de la izquierda, haga clic con el botón derecho en Secuencias de Comandos > Nuevo Secuencia de Comandos). La secuencia de comandos del ejemplo se denomina "Construir InClause a partir de claves de dictado". Pegue lo siguiente en el secuencia de comandos:
```
<trans>
ArgumentList(Dictionary, start, end);
keys = GetKeys(Dictionary);

//keyIter = 0;
inClause = '';
if(end > length(keys),
//use length keys as condition
while( start <length(keys)-1,
    inClause = inClause + keys[start] + ', ';
    start++;);,
while( start < end ,
    inClause = inClause + keys[start] + ', ';
    start++;);
);

inClause + keys[start]
</trans>
```
Ahora que se creó la secuencia de comandos de la cláusula IN, podemos usarla dentro de la secuencia de comandos "Actualizar almacén de claves" que se creó al final de la segunda operación en el Paso 2. Esta secuencia de comandos recorre el diccionario de claves y busca en Clarizen un registro coincidente.. Una vez terminado, ejecutará las operaciones de actualización e inserción que configuraremos en los siguientes pasos. Haga doble clic en este secuencia de comandos e ingrese lo siguiente, sustituyendo los nombres de sus secuencias de comandos y operaciones reales donde sea necesario.
```
<trans>
//Update cache
keys = GetKeys($UpsertIdDict);
//WriteToOperationLog(keys);
interval = 999;
batch = 0;

While(batch*interval < Length(keys),
$ClarizenWhereClause = '(' + RunScript("<TAG>Scripts/Construct InClause From Dict Keys</TAG>",$UpsertIdDict, batch*interval, (batch + 1)*interval - 1) + ')';
WriteToOperationLog($ClarizenWhereClause);
If(!RunOperation("<TAG>Operations/3. Query Clarizen for Records with Matching Unique Keys</TAG>",true),
RaiseError(GetLastError())
);
batch ++;
);

RunOperation("<TAG>Operations/4. Separate Records to Update; Update Records</TAG>",false);
RunOperation("<TAG>Operations/5. Separate Records to Create; Insert Records</TAG>",false)
</trans>
```
Nota

La última parte de este secuencia de comandos conecta las operaciones que se crearán a continuación en los pasos 4 y 5. Es posible que deba volver a este secuencia de comandos al final para actualizar los nombres de las operación si es necesario.

Paso 4: Separe los Registros para Actualizar, Luego Actualice los Registros en Clarizen¶

adjunto

Este paso filtra los registros para una operación de actualización de Clarizen y luego realiza la actualización de registros en la instancia de Clarizen.

Cree una nueva operación de actualización de Clarizen para el objeto que desea actualizar (en el ejemplo, el objeto Cliente).
Especifique la fuente que contiene todos los registros que se van a modificar. En el ejemplo, usamos la fuente "Empleados" creada en el Paso 1 (haga doble clic en Fuente y seleccione la fuente "Empleados" existente).
No se necesita ningún objetivo, así que elimine el objetivo de la operación (haga clic con el botón derecho en Objetivo > Eliminar del gráfico).
Cree una nueva transformación de solicitud (haga doble clic en Solicitud > Crear nueva Transformación). La transformación del ejemplo se denomina "Separar registros para actualizar".
1. Para la fuente, seleccione la misma estructura que sus datos de origen. En el ejemplo, nuestra fuente es el resultado de una consultar de Clarizen, por lo que usamos "Respuesta de función de Clarizen ". El objetivo debe definirse como una solicitud para la operación de actualización.
2. Para la fuente de ejemplo, siga las indicaciones del asistente, en el ejemplo seleccione "Consulta" y la operación de consultar específica utilizada como fuente. Si tiene un tipo diferente de fuente, seleccione las opciones apropiadas.
3. En la transformación, cree una condición en la carpeta del objeto de destino (en el ejemplo, haga clic con el botón derecho en la carpeta Cliente > Agregar condición). La condición debe devolver verdadero cuando el registro se encuentra en el diccionario y falso cuando no lo es:
```
<trans>
if($UpsertIdDict[Quote(OUTPUT$<Your_Object>$Entity.id$)]!='0',
WriteToOperationLog('Found in Dict');
true,
WriteToOperationLog('Not Found In Dict');
false)
</trans>
```
  En el ejemplo, la condición se establece de la siguiente manera:
```
<trans>
if($UpsertIdDict[Quote(OUTPUT$User$Entity.id$)]!='0',
WriteToOperationLog('Found in Dict');
true,
WriteToOperationLog('Not Found In Dict');
false)
</trans>
```
4. Luego, mapee el campo ID recuperándolo del diccionario usando la clave única. Es decir, haga doble clic en la ID en el lado del objetivo e ingrese lo siguiente:
```
<trans>
$UpsertIdDict[Quote(OUTPUT$<Your_Object>$Entity.id$)]
</trans>
```
  En el ejemplo, esto se establece de la siguiente manera:
```
<trans>
$UpsertIdDict[Quote(OUTPUT$User$Entity.id$)]
</trans>
```
5. Continúe con la asignación de los campos de identificación restantes, así como cualquier otro campo que deba asignarse al actualizar. En el ejemplo, también asignamos el campo Usuario > Entidad > "id" al Cliente > "C_JB_External_Id" (campo personalizado) a la derecha. En el ejemplo, el campo Usuario > Entidad > "Nombre para mostrar" también se asigna al campo Cliente > "Nombre" a la derecha.
Para la transformación de respuesta restante en la operación, puede pasar los datos a través de la transformación sin ningún cambio (haga clic con el botón derecho en Respuesta > Transferencia).
Cuando se complete la operación de actualización, verifique dos veces la secuencia de comandos "Actualizar almacén de claves" que se describe al final del Paso 3 para asegurarse de que esta operación esté incluida para ejecutarse dentro de la secuencia de comandos.

Paso 5: Separe los Registros para Crear, Luego Inserte los Registros en Clarizen¶

adjunto

Este paso filtra los registros para una operación de creación de Clarizen y luego realiza la inserción de registros en la instancia de Clarizen.

Cree una nueva operación de creación de Clarizen para el objeto en el que desea insertar datos (en el ejemplo, el objeto Cliente).
Especifique la fuente que contiene todos los registros que se van a modificar. En el ejemplo, usamos la fuente "Empleados" creada en el Paso 1 (haga doble clic en Fuente y seleccione la fuente "Empleados" existente).
No se necesita ningún objetivo, así que elimine el objetivo de la operación (haga clic con el botón derecho en Objetivo > Eliminar del gráfico).
Cree una nueva transformación de solicitud (haga doble clic en Solicitud > Crear nueva Transformación). La transformación del ejemplo se denomina "Separar registros para crear".
1. Para la fuente, seleccione la misma estructura que sus datos de origen. En el ejemplo, nuestra fuente es el resultado de una consultar de Clarizen, por lo que usamos "Respuesta de función de Clarizen ". El objetivo debe definirse como una solicitud para la operación de creación.
2. Para la fuente de ejemplo, siga las indicaciones del asistente, en el ejemplo seleccione "Consulta" y la operación de consultar específica utilizada como fuente. Si tiene un tipo diferente de fuente, seleccione las opciones apropiadas.
3. En la transformación, cree una condición en la carpeta del objeto de destino (en el ejemplo, haga clic con el botón derecho en la carpeta Cliente > Agregar condición). La condición debe devolver falso cuando el registro se encuentra en el diccionario y verdadero cuando no lo es:
```
<trans>
if($UpsertIdDict[Quote(OUTPUT$<Your_Object>$Entity.id$)]=='0',
WriteToOperationLog('Not Found in Dict. Creating CZ customer');
true,
WriteToOperationLog('Found In Dict. Customer already exists in CZ');
false)
</trans>
```
  En el ejemplo, la condición se establece de la siguiente manera:
```
<trans>
if($UpsertIdDict[Quote(OUTPUT$User$Entity.id$)]=='0',
WriteToOperationLog('Not Found in Dict. Creating CZ customer');
true,
WriteToOperationLog('Found In Dict. Customer already exists in CZ');
false)
</trans>
```
4. Continúe con el mapeo de los campos de identificación restantes, así como cualquier otro campo que deba mapearse al actualizar. En el ejemplo, también asignamos el campo Usuario > Entidad > "id" al Cliente > "C_JB_External_Id" (campo personalizado) a la derecha. En el ejemplo, el campo Usuario > Entidad > "Nombre para mostrar" también se asigna al campo Cliente > "Nombre" a la derecha.
Para la transformación de respuesta restante en la operación, puede pasar los datos a través de la transformación sin ningún cambio (haga clic con el botón derecho en Respuesta > Transferencia).
Cuando se complete la operación de creación, verifique dos veces la secuencia de comandos "Actualizar almacén de claves" que se describe al final del Paso 3 para asegurarse de que esta operación esté incluida para ejecutarse dentro de la secuencia de comandos.

Mejoramiento¶

El patrón de diseño presentado anteriormente utiliza un diccionario para mantener claves únicas con sus ID de Clarizen asociadas con el fin de simplificar.

Esto es suficiente para muchos casos de uso, pero debido a que el diccionario no se conserva, se debe consultar Clarizen cada vez para crear el almacén de claves. Esto agregará al menos 1 uso adicional de API por registro alterado.

Dado que una consultar masiva se puede utilizar para consultar 100 000 registros por llamada, el gasto suele ser insignificante para grandes cargas de datos. Sin embargo, para aplicaciones en tiempo real de alta frecuencia, esto puede convertirse rápidamente en una adición costosa.

Una alternativa es usar el caché en la nube de Jitterbit para almacenar estas identificaciones. Hay algunas complejidades añadidas al uso de la memoria caché en la nube; dado que permite solo 250 lecturas/escrituras por segundo, el implementador debe manejar el caso de que falle la lectura o la escritura.

Otras alternativas son utilizar capas de persistencia externas para mantener el almacén de claves o utilizar almacenamiento local si se utiliza un Agente Privado.