Introducción 

Un pipeline representa un proceso estructurado en una secuencia de rutas y pasos, donde cada paso transforma, procesa o transfiere datos de forma sistemática. Este flujo inicia desde un input inicial y concluye con un output final, garantizando un procesamiento integral de los datos end-to-end.

En la plataforma Vor-Tex, los pipelines se diseñan y configuran dentro del Workspace, para orquestar distintos orígenes de datos, donde cada paso se conecta a una vista de datos para realizar operaciones de lectura o escritura.

Para implementar un pipeline en Vor-Tex, es fundamental comprender y aplicar los siguientes conceptos técnicos:

1. Conexión a Orígenes de Datos: Configuración de conexiones a fuentes de datos, para operaciones de lectura o escritura.
   
   
2. Creación de Vistas de Datos: Abstracción y transformación de los datos de la respuesta de los orígenes de datos en vistas de datos que serán utilizadas por el pipeline.
   
   
3. Configuración de parámetros: Definición de parámetros, tipos y valores.
   

En este documento se abordarán todos los aspectos relacionados a la creación y configuración de un pipeline en Vor-Tex, dando cuenta de sus funcionalidades, versatilidad y posibilidades de uso. 

Crear o editar pipelines

Si se ingresa a la opción Nuevo pipeline, podrá comenzarse a modelar el pipeline agregando distintas configuraciones. A continuación se presenta la pantalla con sus principales botones.

De esta pantalla se debe tener en cuenta lo siguiente: 

• Lienzo: es el espacio gris punteado donde se irán visualizando los distintos pasos del pipeline.
• Inicio: es el punto de partida del pipeline, un hito de inicio y es único (no puede haber un pipeline con dos inicios diferentes). 
• Agregar paso: botón que se utiliza para agregar los pasos del pipeline. 
• Depurar: permite ejecutar el pipeline para entrar en modo debug o depuración y conocer los resultados de su ejecución.
• Guardar borrador: permite guardar en borrador los cambios realizados, para poder entrar luego en modo depuración.
  

Inicio

Un pipeline solo puede tener un inicio, del cual luego se pueden desprender diferentes rutas que pueden contener uno o más pasos.

Cuando existe una bifurcación que se da desde el inicio del pipeline, una de las rutas será la ruta principal y las otras serán rutas que se utilizarán ante condiciones definidas en el pipeline.

Además del inicio, estas bifurcaciones pueden ocurrir en cualquiera de los pasos del pipeline y el flujo de los datos dependerá de la configuración de variables condicionales en el inicio o en los pasos precedentes a la bifurcación. 

Configuraciones en el Inicio del Pipeline. 

Estas configuraciones tendrán impacto en el pipeline a nivel global, esto es en la inicialización del pipeline, sus rutas y pasos.

Para poder llevar adelante estas configuraciones, en ícono de “Inicio” se debe hacer clic en la opción Expandir la cual se reconoce por un cuadrado marcado únicamente en sus esquinas: 

• Agregar variable: son las variables globales del pipeline, que pueden hacer referencia a los valores de los parámetros o a valores fijos.
• Nuevo parámetro: son los parámetros del pipeline que se utilizarán en su ejecución. Los parámetros del pipeline serán los parámetros del método de la API, que podrán exponerse al cliente final o relacionarse con variables de contexto.
• Seleccionar la ruta de inicio del pipeline: es la ruta principal del pipeline, que puede seleccionarse de forma predeterminada o bajo una condición establecida mediante templates jinja. 

Agregar variables.

Las variables globales del pipeline estarán disponibles para ser utilizadas en cualquier paso del pipeline. Pueden hacer referencia a los valores de los parámetros o a valores fijos, pudiendo aplicar transformaciones y condiciones mediante scripting jinja.

Esta configuración requiere ingresar: 

• Nombre de la variable: el nombre que asumirá la variable, sin espacios.
• Describir la variable: Descripción de la variable a modo de documentación interna.
• Seleccionar valores a asignar: es posible seleccionar los parámetros del pipeline, código jinja y texto personalizado, y aplicar de forma visual diferentes tipos de filtros de transformación.

Nuevo parámetro.

Es posible agregar parámetros del pipeline que se utilizarán en su inicialización.

Los parámetros estarán disponibles al ejecutar el método relacionado al pipeline y podrán relacionarse con variables de contexto. También los parámetros estarán disponibles para ser utilizados en la selección de rutas y en los pasos del pipeline, y enviar así sus valores a los parámetros de las vistas de datos de cada paso, con o sin transformaciones de sus valores. 

Tener en cuenta:

• Nombre: debe ser único y será el nombre del parámetro expuesto en el método.
• Obligatorio: permite definir si el parámetro será obligatorio.
• Descripción: permite agregar una descripción del parámetro que será expuesta en la documentación del método en el Portal para desarrolladores.
• Tipo: es el tipo de validación que tendrá el parámetro (texto, número, fecha, lista de valores, booleano, JSON)
• Valor por defecto: permite definir un valor por defecto para el parámetro.
• Validaciones: las validaciones dependen del tipo seleccionado.
• Template: permite agregar plantillas jinja para validaciones más complejas y dinámicas.

Rutas

En caso de existir más de una ruta, es posible seleccionar la ruta de inicio por defecto o establecer una condición en base a un template jinja. 

Esto permite seleccionar la ruta de ejecución según los parámetros de entrada del pipeline. En la selección de las rutas están disponibles los parámetros y variables definidas en el inicio. 

El resultado del template jinja debe ser el nombre de la ruta. 

Pasos

Los pasos del pipeline ejecutan vistas de datos y procesan sus respuestas. Al agregar un paso debe seleccionarse una vista de datos desde el listado. 

Los pasos tienen tres etapas: 

• Ejecutar: consiste en la ejecución de la vista de datos.
• Finalizar: es el proceso de finalización del paso.
• Reducir: es el momento de reducción, donde se define cómo se continuará al siguiente paso.

Agregar un paso y seleccionar una vista

Luego de agregar paso y unirlo al inicio, o al paso que lo antecede, se debe hacer clic en “Configurar” dentro del paso:

Tras ingresar a las configuraciones del Paso, lo primero que se debe hacer es seleccionar la vista a la cual estará conectado. 

Seleccionada la vista, podrá verse su nombre al interior del Paso en la graficación del pipeline. Para seguir configurando el Paso, se debe hacer clic en el ícono de expandir: 

Configurar paso

Tras hacer clic en el botón de expandir se pueden realizar configuraciones sobre la vista de datos relacionada al paso, y definir sus etapas:

• Ejecutar: consiste en la ejecución de la vista de datos.
• Finalizar: es el proceso de finalización del paso.
• Reducir: es el momento de reducción, donde se define cómo se continuará al siguiente paso.

Ejecutar

La ejecución consiste en definir el modo de ejecución, los valores de los parámetros y la descripción del paso.

• Modo de ejecución: por defecto se encuentra seleccionado JSON, donde la lectura de la respuesta del origen será bajo la abstracción del resultado realizado en la vista de datos, pudiendo obtener los datos en un sentido tabular. La opción RAW permite procesar la respuesta del origen de datos sin transformaciones, utilizado cuando los orígenes responden con objetos json.
• Parámetros de ejecución: en caso que la vista de datos tenga parámetros se mostrarán para poder definir qué valores asumirán. Los valores pueden ser fijos o hacer referencia a las variables disponibles, que pueden visualizarse a la derecha. 
• Descripción del paso: es posible agregar una descripción del paso para documentarlo.  

Finalizar

La etapa de finalizar consiste en el procesamiento del resultado de la ejecución de la vista de datos, esto es, cómo se utilizará la respuesta entregada por la vista de datos.

De modo general, el procesamiento incluye:

• Gestión del resultado como grupo único o subgrupos (ramas)
• Reducción a una sola rama de las ramas abiertas en un paso futuro (join in the future).
• Excluir filas del procesamiento, por ejemplo excluir las cabeceras de la vista de datos.
• Abrir ciclos, esto es, generar nuevos grupos para abrir ciclos de ejecución (ciclos dentro de ramas)
• Paginación sobre el origen de datos, cuando el origen de datos requiere paginado.
• Agregar variables de cada rama

Gestión del resultado en caso exitoso

Es posible definir el tratamiento del resultado exitoso de la vista de datos. 

El resultado entregado puede tratarse de diferentes formas, que permiten abrir o no ramas de ejecución bajo diferentes criterios. Las ramas o branches permiten abrir hilos de ejecución para procesar el resultado de la vista de datos, y eventualmente, continuar hacia el paso siguiente con esos hilos o ramas abiertas (ver Reducir más adelante).

1. Continuar con una sola rama de ejecución en todas las filas: permite tratar a la vista de datos como un único grupo, sin generar subgrupos de datos. Esto es útil cuando el resultado tiene una única fila, o cuando se desea tratar todo el resultado de la vista de datos de forma conjunta. 
   
   
2. Abrir una rama de ejecución para cada fila: permite abrir una rama o hilo por cada fila de la vista de datos. Es decir, habrá tantos grupos o ramas como filas en la vista de datos. Esto es útil cuando se obtiene un listado, y por cada fila de ese listado se deben generar variables con sus valores y ejecutar pasos siguientes por cada una de las filas.
   
   
3. Abrir ramas de ejecución según criterios de agrupación: permite generar grupos de filas bajo un criterio de agrupación. Esto es, en base a valores únicos (repetidos) de una columna de la vista de datos generar ramas o grupos. Por ejemplo, si la vista entrega un listado de usuarios, donde en la primera columna se indica la cuenta a la que pertenece cada usuario, esta opción permite generar grupos de filas (usuarios) por cuenta.

A modo de resumen, al procesar el resultado de la vista de datos pueden generarse ramas de ejecución que permitirán generar variables para cada una de ellas y poder definir si se continúa al siguiente paso con esas ramas abiertas.

Delay en la apertura de las ramas

Cuando se definen las opciones de apertura de ramas (2 y 3 en el listado anterior) es posible definir un tiempo de espera (delay) en la apertura de cada rama. El valor se define en segundos, pudiendo utilizar punto como separador decimal para indicar milisegundos. Por ejemplo 0.5 son 500 milisegundos.

Reintentar ejecución

Esta opción permite reintentar, es decir, volver a ejecutar el paso, ante ciertas condiciones establecidas. Por ejemplo, si el paso responde de forma exitosa, pero su contenido indica que debe reintentarse la solicitud puede utilizarse esta opción.

Un caso de uso frecuente es cuando en pasos anteriores se ejecutaron solicitudes a orígenes de datos asincrónicos y en este paso se consulta el estado de la tarea ejecutada previamente. En un caso así, el origen de datos puede responder con un mensaje exitoso pero su contenido indica que la tarea no fue finalizada. De esta forma, es posible reintentar para obtener el estado de la tarea cuando haya finalizado.

Al habilitar la opción es posible:

• Definir una plantilla jinja: la resolución de la plantilla debe devolver true si se quiere reintentar y false si no se desea aplicar reintentos.
• Definir la cantidad máxima de reintentos.
• Definir tiempos de espera entre reintentos expresados en milisegundos.
• Inicializar variables en cada reintento.
• Definir si al finalizar los reintentos debe continuar o detenerse la ejecución de la rama.

Reducir a una sola rama en un paso posterior

En caso que se hayan abierto ramas de ejecución, es posible definir un agrupamiento o reducción a una sola rama en un paso posterior (join in the future). Esto es útil si se desean ejecutar varios pasos con apertura de ramas, pero es necesario generar una reducción a una rama más adelante.

Excluir cabeceras o filas

En el procesamiento del resultado de la vista de datos es posible:

• Excluir las cabeceras: para no considerarla parte de los datos y evitar, por ejemplo, la apertura de una rama con los valores de las cabeceras
• Excluir grupos de filas en base a scripting jinja. 

Lo más común en este caso es seleccionar la primera opción.

Ciclos de ejecución

Los ciclos de ejecución permiten generar nuevos grupos (ciclos) dentro de grupos (ramas).

Los ciclos pueden abrirse en base a:

• Todas las columnas: se generarán grupos por cada columna de la vista de datos.
• Solo algunas columnas: se generarán grupos en base a una o más columnas de la vista de datos.
• Todas las filas dentro del grupo: se utilizarán las filas dentro del grupo para generar nuevos grupos.

Es posible además ejecutar un script jinja para determinar cuántos ciclos abrir.

Por ejemplo, imaginemos un caso donde tenemos un listado de usuarios donde se indica a qué cuenta pertenece cada usuario. Sobre ese listado, en un paso posterior debemos realizar una ejecución por cada usuario y en otro paso una ejecución por cada cuenta, la cual puede incluir uno o más usuarios.

Si seleccionamos la opción Abrir ramas de ejecución según criterios de agrupación y utilizamos como criterio la columna que contiene el identificador de cuenta, luego podremos abrir ciclos de ejecución en base a cada fila dentro del grupo. En este caso, el grupo está formado por los usuarios (cada fila) de cada cuenta (conjunto de filas).

Paginación del origen de datos

Si el origen de datos tiene paginado puede utilizarse esta opción para recorrer todas las páginas.

Por ejemplo, si el origen de datos a ejecutar tiene 100 items, pero solo entrega 20 items por página, es necesario consultar el origen de datos 5 veces para obtener todos los items. 

Mediante esta opción se pueden recorrer todas las páginas para obtener todos los resultados.

Puede definirse:

• Obtener la cantidad de páginas desde una cabecera: muchos orígenes de datos de tipo rest/json devuelven la cantidad total de páginas en una cabecera. Esta opción permite obtener ese valor.
• Ejecutar script: permite mediante un script jinja definir la cantidad de páginas. El resultado del script debe ser un número entero que represente la cantidad de páginas que se deben recorrer.

Agregar variables

Las variables a inicializar en cada rama son una de las secciones más relevantes al momento de definir las configuraciones del paso.

Esto permite obtener valores de la vista de datos para generar variables que estén disponibles en pasos posteriores.

Es posible generar de forma automática las variables con un solo clic en el botón Generar variables. Esto agregará variables por cada una de las columnas de la vista de datos.

Es posible también agregar variables de forma manual, mediante scripting jinja u obteniendo otros valores. 

La generación de variables permite utilizar todas las capacidades de jinja templates.

Reducir

En la etapa de reducción del paso se define cómo se debe continuar hacia el paso siguiente o si deben hacerse un cambio de ruta.

Gestión de errores

La gestión de errores permite definir qué acciones tomar ante un error en la vista de datos o en el origen de datos.

Es posible:

• Continuar la ejecución del pipeline sin importar si hubo o no error.
• Gestionar los errores

Si se define gestionar los errores, es posible seleccionar:

• Códigos de error
• Acción a tomar: reintentar, detener o continuar.

En caso de reintentos, es posible definir:

• Cantidad de reintentos
• Tiempo de espera entre reintentos
• Ejecutar un script jinja para evaluar cada reintento

Configuración sobre las ramas

En caso que se hayan definido apertura de ramas en la finalización del paso, es posible mediante esta opción definir cómo continuar al siguiente paso.

Las opciones disponibles permiten:

• Cerrar todas las ramas y continuar sólo con una rama abierta: esta opción cierra todas las ramas paralelas y unifica el flujo en una única rama activa, siendo útil, por ejemplo, cuando se requiere consolidar resultados y proseguir de forma centralizada
• Continuar con todas las ramas abiertas: mantiene las ramas en ejecución sin que converjan; suele utilizarse para flujos paralelos que siguen procesamientos independientes
• Cerrar ramas por grupo y continuar con una rama abierta por grupo: agrupa varias ramas en conjuntos y cierra el resto dentro de cada grupo, dejando solo una rama activa por grupo

Inicializar nuevas variables

En la etapa de reducción del paso es posible definir nuevas variables de salida. 

Configuración de rutas

En la reducción del paso es posible definir si continuar con la misma ruta hacia el siguiente paso, o cambiar de ruta.

El cambio de ruta puede establecerse mediante scripting jinja, donde el resultado del script debe ser el nombre de ruta que debe tomarse ante las condiciones definidas.

Depurar pipeline (debug)

En la creación o edición de un pipeline, es posible entrar en modo debug o depuración para probar su ejecución.

Primero, deberá hacer clic en Guardar Borrador para activar el botón Depurar.

Una vez guardado en borrador el pipeline, se habilita el botón Depurar. Haga clic sobre ese botón para depurar el pipeline y espere a que se entreguen los resultados.

Se mostrará una pantalla como la siguiente, donde podrá:

• Salir de la depuración.
• Navegar entre los pasos.
• Seleccionar las ramas de ejecución si hay más de una.
• Conocer la respuesta del paso y las variables generadas

Puede utilizar el recuadro del panel inferior para mostrar el contenido en pantalla completa.