Conceptos clave

Antes de aprender sobre la implementación de circuitos de Catalyst, es importante comprender algunos conceptos fundamentales en detalle.

Componentes de un circuito

El diseño del flujo de trabajo de un circuito de Catalyst contiene varios componentes que te ayudan a orquestar la lógica y el flujo de datos en él.

Estados del circuito

Un estado es una condición particular en la que se encuentra el circuito en un momento dado. Define una tarea o proceso específico que se ejecuta en esa etapa del circuito.

Los estados del circuito se pueden agrupar ampliamente en dos categorías:

• Controles de flujo: Los estados de control de flujo orquestan el flujo de la lógica y los datos en el circuito. Los siguientes estados de control de flujo están disponibles en los circuitos de Catalyst:
  

  • Pass
  • Branch
  • Parallel
  • Wait
  • Batch
  • Success
  • Failure

• Funcionales: Los estados funcionales definen las operaciones reales que necesitan ser ejecutadas en el circuito. Los siguientes estados de control funcional están disponibles en los circuitos de Catalyst:
  

  • Function
  • Circuit

Discutiremos cada uno de estos estados en detalle en la siguiente sección.

Un circuito transita de un estado al siguiente durante su ejecución de manera paso a paso. El flujo de lógica y datos ocurre entre cada estado en el circuito. Las siguientes propiedades existen en la configuración de cada estado:

• Estado anterior: El estado que se transitó antes del estado actual
• Estado siguiente: El estado que se transitará después del estado actual

El inicio de un circuito está marcado por una clave llamada Start, y el final del circuito está marcado por una clave llamada End, en el diagrama de flujo esquemático del circuito.

En el código JSON del circuito, si un estado no menciona la clave next, es el último estado, y si un estado no se menciona como next en ningún otro estado, es el primer estado del circuito. Puedes consultar esta sección para un fragmento de código JSON de ejemplo.

Entrada, salida y resultado

Un circuito de Catalyst, en general, acepta una entrada cuando se inicia y proporciona una salida después de ejecutarse. Estos se llaman la entrada del circuito y la salida del circuito.

• Entrada del circuito: Cuando inicias la ejecución de un circuito, necesitarás proporcionar una entrada al circuito como pares clave-valor en formato JSON. Dado que las funciones Basic I/O, que son los elementos funcionales de un circuito, procesan la entrada en formato JSON, la entrada del circuito admite lo mismo. Esta entrada proporcionada durante la iniciación se pasa al primer estado del circuito.

• Salida del circuito: El JSON de entrada luego se procesa y se transita a través de los estados del circuito, según el diseño y la arquitectura de su flujo de trabajo. Después de que se ha transitado el último estado, Catalyst genera la salida final del circuito obtenida después de que su ejecución se completa.

Puedes ver los registros e historial de ejecución detallados de cada ejecución desde la consola.

Puedes manipular el JSON de entrada y proporcionar una entrada personalizada a cada estado para su procesamiento, o seleccionar una porción de la salida del procesamiento de cada estado para pasarla al siguiente estado según tus necesidades. También puedes incluir dinámicamente los resultados de un estado procesado al JSON de entrada y pasarlo.

Esto se realiza mediante las siguientes propiedades de un estado del circuito:

• Ruta de entrada:
  

La ruta de entrada te permite seleccionar una porción de la entrada del estado y pasarla a la tarea del estado para su procesamiento. Por ejemplo, sea el JSON de entrada de un estado:

{
name: Amelia Burrows
gender: F
age: 33
} 

Si solo quieres enviar las variables name y gender como la entrada a un estado, digamos una función, puedes configurar la ruta de entrada de la función como $.name,gender. Esto se refiere a los objetos JSON name y gender como la ruta de entrada.

Catalyst importa la biblioteca externa JsonPath para definir la ruta de entrada, la ruta de salida y la ruta de resultado de un estado en un circuito. Por lo tanto, puedes usar todas las expresiones soportadas por JsonPath en tus definiciones de rutas. Consulta esta documentación de GitHub sobre la sintaxis de JsonPath.

• Ruta de salida:

La ruta de salida te permite seleccionar una porción de la salida del estado y pasarla al siguiente estado para su procesamiento. Por ejemplo, sea el JSON de salida de un estado:

[
26,
"John Kemper",
  {
    "streetAddress": "Sunshine Avenue",
    "city": "Austin",
    "postalCode": "630-0231"
   }
]

Puedes seleccionar solo los valores de los objetos age y name (26, John Kemper) de la salida para pasar al siguiente estado, configurando la ruta de salida del estado como $.age,name.

• Ruta de resultado:

La ruta de resultado te permite combinar partes de la entrada del estado y el resultado de la ejecución del estado, como la salida del estado. En otras palabras, puedes agregar el resultado del estado al JSON de entrada proporcionado al estado y modificar el JSON. Luego puedes pasar este JSON modificado como la salida del estado al siguiente estado para su procesamiento.

Por ejemplo, sea una función en un circuito que procesa un JSON de entrada que contiene dos objetos llamados presentDays y totalWorkingDays. La salida del procesamiento de la función genera un nuevo valor que se asigna a una variable llamada attendancePercentage en su salida.

Si quieres incluir el valor obtenido para attendancePercentage al JSON original, puedes proporcionar la ruta de resultado como $.attendancePercentage. El JSON se modificará entonces como:

[
  	180,
  	200,
  	90
	]

Donde el valor para presentDays es 180, totalWorkingDays es 200 y attendancePercentage es 90.

Ahora puedes pasar esta salida al siguiente estado para su procesamiento.

Estados del circuito

Como se discutió anteriormente, los estados del circuito se pueden agrupar como estados de control de flujo o estados funcionales. Aprendamos sobre cada estado en detalle y las configuraciones disponibles para ellos.

Esta es la vista Builder View de un circuito. Esta sección muestra imágenes de las configuraciones disponibles para cada estado como referencia. Para conocer los pasos involucrados en la creación de un circuito y la adición de estados en él, consulta la sección de Implementación.

Function

El estado de función es un elemento funcional que representa una función Basic I/O. Los estados de función son los elementos centrales de un circuito, donde se procesa una gran parte de la lógica. Todos los demás estados de control de flujo te ayudan a manipular y personalizar el procesamiento de las funciones en un circuito.

Puedes ingresar nombres para todos los estados en un circuito, seleccionar su tipo y seleccionar sus estados siguientes mientras configuras el circuito en la consola. Puedes eliminar un estado particular haciendo clic en Delete State debajo de la ventana de configuración.

Cuando seleccionas un estado de función, puedes vincularlo con una función Basic I/O configurada en tu proyecto de Catalyst seleccionándola de la lista desplegable.

Manejo de errores:

El estado de función admite el manejo de errores para gestionar errores que ocurren frecuentemente durante la ejecución de la función. Puedes configurar las acciones a tomar durante errores de On TimeOut, On Authorization Failure o On Execution Failure.

Haz clic en la casilla de verificación de un error para habilitarlo. Los tres manejadores de errores admiten dos acciones predeterminadas: Retry y Fallback. Haz clic en Retry o Fallback para habilitarlos.

La opción de reintento asegura que la ejecución de la función se reintente si ocurre ese error particular. Puedes configurar las siguientes propiedades en el reintento:

• Delay: Define la duración del tiempo de espera antes de intentar el primer reintento
• Attempt: Define el número de intentos de reintento a realizar
• Step Delay: Define la duración del tiempo de espera entre cada intento

La opción de fallback se usa para establecer la acción a realizar cuando todos los reintentos fallan. Esto te permite elegir otro estado en el circuito al cual retroceder cuando los reintentos fallan.

Selecciona un estado de la lista desplegable al cual retroceder. Ingresa la ruta del rastreo de error en Result en la sintaxis de JsonPath al ingresar este valor. Si los intentos de reintento fallan, el circuito se establece al estado configurado aquí, y se genera el rastreo de error. Haz clic en Save para guardar el manejador.

Los manejadores de errores de los tres errores predeterminados (On TimeOut, On Authorization Failure, On Execution Failure) tienen las mismas acciones y configuración.

Además de estos manejadores de errores predeterminados, puedes definir errores personalizados y manejar las acciones que ocurren al recibir ese error. Puedes codificar la función para procesar el manejador de errores personalizado para un error específico que se encuentre.

Haz clic en Add Custom Error en Error Handling en la configuración del estado.

Ingresa un nombre para el error personalizado en el encabezado de la ventana emergente. Puedes seleccionar Error Code o Error Message como el tipo de excepción. Proporciona un valor de excepción en ambos casos. Este será el mensaje de error o código que se muestra cuando ocurre el error.

Puedes habilitar y configurar tanto Retry como Fallback para un error personalizado, como los manejadores de errores predeterminados. Haz clic en Save después de configurarlo.

Puedes eliminar un error personalizado haciendo clic en el ícono de eliminar.

Catalyst considera todos los códigos de estado HTTP de la serie 200 (200-299) como una ejecución exitosa para una función Basic I/O. Si la función devuelve un código de estado en su respuesta distinto de la serie 200, por ejemplo 502, Circuits verificará la configuración de manejo de errores de la función en busca de una coincidencia con un manejador de errores personalizado. Si se encuentra una coincidencia, se ejecutará la lógica configurada para él. Si el código de error no se ha manejado, la ejecución del circuito se considerará como un fallo.

Si configuras un mensaje de error, puedes manejarlo como necesites en la lógica de la función.

Entrada/Salida:

Puedes configurar las rutas de entrada, salida y resultado de un estado de función, como se discutió en esta sección. También puedes pasar y configurar parámetros individuales para ser pasados a una función desde esta sección.

Puedes seleccionar un conjunto específico de parámetros del JSON de entrada del circuito para ser pasados a la función usando la ruta de entrada.

Por ejemplo, sea el JSON de entrada pasado a un circuito:

"personalDetails":{
      "name":"Patricia Boyle",
      "age" : 26,
	   "address":"13, Orchid Lane, NY"
	},
"company":"Zylker Corporation",
"empDetails":{
"department":"Sales",
"designation":"Sales Manager"
}

Si necesitas pasar toda la entrada a una función configurada en el circuito como su payload, puedes pasarla al circuito de la manera predeterminada, al iniciar el circuito. Los pares clave-valor en esta entrada se pasarán como los parámetros de la función automáticamente.

Si solo necesitas que se pase un cierto conjunto de parámetros a la función, puedes configurar la clave del conjunto de parámetros en la ruta de entrada. Por ejemplo, para pasar solo los parámetros company y empDetails, puedes proporcionar la ruta de entrada a la función como: $.company,empDetails usando la sintaxis de JsonPath.

También puedes elegir parámetros individuales para ser pasados a la función usando la opción Parameters. Esta opción también te permite pasar valores adicionales a la función que no están presentes en el JSON de entrada del circuito. Haz clic en Add Parameters para agregar un parámetro y un valor.

Por ejemplo, puedes elegir pasar solo el nombre y la designación a la función como parámetros configurando name y designation como las claves de los parámetros e ingresando sus rutas en la sintaxis de JsonPath como valores de los parámetros. Puedes eliminar un parámetro haciendo clic en Remove.

La respuesta de una función Basic I/O de Catalyst entrega la salida de la función usando la clave output. Cuando configuras una función en un circuito, no necesitas proporcionar la clave output explícitamente en la ruta de salida o la ruta de resultado de la función.

Catalyst lo maneja de manera predeterminada y entrega el valor de salida automáticamente. Si el circuito está configurado para pasar la salida de la función al siguiente estado, Catalyst pasa automáticamente la salida como el payload sin configuraciones adicionales.

Por ejemplo, esta salida JSON de una función,

[
180,
90
]

se pasa como la entrada JSON al siguiente estado en el circuito como el payload durante la ejecución del circuito.

El registro de ejecución del circuito proporciona enlaces a la función que se ejecutó y a Catalyst Logs que contiene el registro de esa función específica, para un estado de función.

Circuit

El estado de circuito es una representación de un circuito anidado. Puedes procesar otro circuito dentro del circuito principal. Cuando se activa un estado de circuito, el circuito hijo se ejecuta como está configurado en Catalyst Circuits.

También puedes tener circuitos anidados dentro de un circuito hijo. Esto te permite configurar circuitos simples e independientes para diferentes propósitos y anidarlos entre sí, en lugar de configurar un circuito complejo para un patrón de flujo de trabajo complicado.

Puedes seleccionar el circuito hijo usando su nombre de referencia del cuadro desplegable Circuit Name en un estado de circuito. También podrás seleccionar el propio circuito padre para un estado de circuito. Esto ejecuta el mismo circuito en un bucle, cuya lógica puedes configurar.

El estado de circuito también admite manejadores de errores predeterminados y manejadores de errores personalizados, como el estado de función. Sin embargo, a diferencia del estado de función, el estado de circuito solo tiene una acción para su manejador de errores predeterminado o personalizado: Retry. Consulta la sección de Function para información sobre reintentos y manejadores de errores personalizados.

Puedes escribir tu propia lógica para las acciones a realizar si todas las operaciones de reintento fallan. Por ejemplo, puedes codificar que el circuito se vuelva a ejecutar, o terminarlo y enviar una notificación sobre el problema.

Puedes manipular los datos JSON que se pasan a través del estado de circuito configurando su ruta de entrada, ruta de salida o la ruta de resultado, como se describió en la sección anterior y en el estado de Function.

El registro de ejecución del circuito también proporciona un enlace al registro del circuito anidado para fácil referencia.

Pass

El estado pass es un estado de control de flujo que permite que los datos de un circuito pasen de un estado a otro. De manera predeterminada, simplemente pasa los datos JSON de entrada de su estado anterior a su estado siguiente.

Puedes manipular los datos JSON que se pasan a través de un estado pass configurando su ruta de entrada, ruta de salida o la ruta de resultado, como se describió en la sección anterior. Por ejemplo, puedes seleccionar solo una porción de los datos JSON para pasarla a su siguiente estado configurando su ruta de entrada.

El estado pass también tiene una nueva propiedad llamada result además de las rutas de entrada, salida y resultado. Esta no está disponible para ningún otro estado.

La propiedad result te permite agregar un nuevo objeto al JSON y pasar el JSON modificado al siguiente estado.

Por ejemplo, en un JSON de entrada que contiene los objetos name, age y gender, puedes agregar un nuevo parámetro llamado location como $.location en la ruta de resultado del estado pass. Puedes ingresar el valor para location en el cuadro de result. El JSON modificado entonces contendrá los objetos name, age, gender y location.

Branch

El estado branch te permite establecer condiciones en el flujo de trabajo del circuito y ejecutar tareas basadas en esas condiciones. Puedes crear ramificaciones en el flujo del circuito si los datos de entrada cumplen un conjunto específico de criterios, y ejecutar diferentes estados en cada rama.

Por ejemplo, supón que la salida del estado anterior a una ramificación en un circuito genera los valores para un objeto JSON status como complete o incomplete. Si el status es complete, necesitas que el circuito transite a un estado de éxito. Si el status es incomplete, necesitas que el circuito transite a un estado de fallo.

Para lograr este resultado, puedes agregar una condición como $.status == ‘complete’ y configurar el ‘Go To’ a un estado de éxito. De manera similar, puedes agregar otra condición como $.status==‘incomplete’ y establecerla a un estado de fallo.

Puedes agregar una condición haciendo clic en Add Condition, luego puedes ingresar la condición y seleccionar el siguiente estado de esa rama. Configura ese estado como el tipo que necesites. Puedes eliminar una condición haciendo clic en Remove.

Los siguientes operadores son soportados por Catalyst para las sentencias condicionales en el estado branch:

Las sentencias condicionales también admiten las siguientes funciones integradas:

También puedes usar la sintaxis de JsonPath para acceder a la ruta de un objeto en la condición.

El estado branch tiene una ruta predeterminada que puedes vincular con el siguiente estado del estado branch completo. Si ninguna de las condiciones configuradas se cumple, se sigue la rama predeterminada y se ejecuta ese estado.

Puedes configurar las rutas de entrada y salida de un estado branch como se describió anteriormente.

Parallel

El estado parallel te permite procesar múltiples estados en paralelo, en lugar de manera secuencial.

Cuando asignas dos estados para ser procesados en paralelo, ambos procesos se inician al mismo tiempo, y su entrada, salida y resultados se procesan y generan de forma concurrente. Los estados también se finalizan al mismo tiempo. Puedes verificar el procesamiento en paralelo desde los registros de ejecución después de que el circuito se ha ejecutado.

Por ejemplo, si necesitas que dos funciones se ejecuten en paralelo, puedes agregar dos estados para ellas respectivamente y configurarlos como rutas en el estado parallel.

Puedes agregar rutas en un estado parallel para cada estado que necesite ser ejecutado en el procesamiento en paralelo haciendo clic en Add Path. Puedes ingresar los nombres de las rutas y configurar los tipos de estado.

Puedes configurar las rutas de entrada, salida y resultado de un estado parallel como se discutió anteriormente.

Wait

El estado wait te permite pausar la ejecución del circuito por una duración particular de tiempo, antes de reanudarla nuevamente y transitar al siguiente estado.

Por ejemplo, si necesitas que la ejecución de una función se active con un retraso de tres segundos después del procesamiento del estado anterior, puedes usar esto. Puedes establecer la duración del retraso en segundos en su configuración.

Puedes configurar las rutas de entrada y salida de un estado wait como se discutió anteriormente.

Batch

El estado batch te permite ejecutar una función o un circuito en lotes como múltiples trabajos de manera iterativa. El procesamiento por lotes te permite procesar un gran volumen de entrada o tareas en conjuntos, para que el servidor no se sobrecargue con cargas pesadas.

Si la entrada contiene un arreglo de objetos JSON, puedes procesar cada objeto JSON simultáneamente usando el estado batch. Este estado batch permite que la función o circuito asociado se active en paralelo múltiples veces, basado en el número de trabajos configurados.

Por ejemplo, si una función Basic I/O está configurada para enviar un correo electrónico a un gran número de clientes, puedes procesarla en el estado batch y establecer el número de trabajos en 10, para que la función se ejecute 10 veces simultáneamente en una sola iteración. Cuando los 10 trabajos se han ejecutado, otros 10 trabajos se inician en la siguiente iteración. Dado que se ejecutan múltiples instancias de una función o un circuito, esto asegura que no enfrenten un error de tiempo de espera.

Puedes vincular el estado batch a una función o circuito específico, eligiendo el tipo de vínculo y el nombre de referencia del circuito o el nombre de la función de las listas desplegables. Puedes configurar las siguientes propiedades de un estado batch:

• Collection path: La ruta que contiene la lista JSON, escrita en la sintaxis de JsonPath
• Collection variable: La variable que se asigna para contener la salida JSON

Por ejemplo, una entrada JSON contiene una lista de dos objetos JSON como un arreglo de la siguiente manera:

{
"userList":[{"name":"Paul"},{"name":"Max"}]
}

Pasamos esta entrada a un lote que está asociado con una función. Definimos la ruta de colección como $.userlist, indicando que el objeto que contiene el arreglo de lista está disponible en esa ruta. Ingresamos la variable de colección como user, asignándola como la variable para contener la salida.

Si ingresamos el número de trabajos como 2, la función asociada, que devuelve el objeto name, se llama dos veces en paralelo y la entrada se le pasa. La salida de la primera iteración se genera como:

{
"userList": [{"name": "Paul" },{"name": "Max"}],
"user":{"name": "Paul"}
}

La salida de la segunda iteración contiene el valor de Max asignado al parámetro name:

{
"userList": [{"name": "Paul" },{"name": "Max"}],
"user":{"name": "Max"}
}

Ambas iteraciones ocurren simultáneamente. Si asignas $.userlist en la ruta de resultado del lote, puedes pasar la salida que contiene la lista JSON al siguiente estado.

Catalyst puede ejecutar un máximo de 10 trabajos en un estado batch. Puedes definir esto en la configuración del lote.

El estado batch admite manejadores de errores predeterminados y personalizados similares al estado de circuito. Tiene una acción para su manejador de errores predeterminado o personalizado: Retry. Consulta la sección de Function para información sobre reintentos y manejadores de errores personalizados.

Puedes escribir tu propia lógica para las acciones a realizar si todas las operaciones de reintento fallan. Por ejemplo, puedes codificar que el circuito se vuelva a ejecutar, o terminarlo y enviar una notificación sobre el problema.

Puedes configurar las rutas de entrada, salida y resultado de un estado batch.

También puedes pasar parámetros a la función que se procesa en el estado batch de forma dinámica, similar al estado de función. Consulta la sección de Function para más detalles.

El registro de ejecución del circuito proporciona enlaces a la función o circuito que se ejecutó, y a Catalyst Logs que contiene el registro de esa función, para un estado batch.

Success

El estado success es un estado final que se usa para determinar el éxito de la operación o tarea anterior ejecutada en el circuito. Se usa para representar una ejecución exitosa como referencia para el usuario.

Por ejemplo, podrías usar el estado de éxito junto con un estado de fallo en una ramificación para marcar los resultados de dos procesos en ella basados en diferentes condiciones, o usarlo después de una ejecución de función para indicar el éxito de la ejecución.

El estado de éxito no tiene ninguna configuración o propiedad, ya que es el estado final de esa ruta particular en el circuito. No podrás establecer ningún estado siguiente después de él.

Tampoco podrás configurar una ruta de entrada o ruta de salida para un estado de éxito.

Failure

El estado failure es también un estado final que se usa para determinar el fallo de la operación o tarea anterior ejecutada en el circuito. Se usa para representar una ejecución fallida como referencia para el usuario.

Puedes usar el estado de fallo de manera similar al estado de éxito, y en otros escenarios para marcar el fallo de un proceso o la ejecución de una tarea.

No podrás establecer un estado siguiente para un estado de fallo, ya que es el estado final de esa ruta particular en el circuito. Puedes proporcionar un mensaje de error y una razón opcional en el estado como referencia, si se transita este estado.

No podrás configurar una ruta de entrada o ruta de salida para un estado de fallo.

Código JSON

Como se mencionó anteriormente, también puedes codificar directamente un circuito en formato JSON desde la consola.

La sección Code View te permite trabajar en el código directamente. El código se genera automáticamente a medida que arrastras y sueltas estados en el diagrama de flujo. Consulta la sección de Implementación para más información.

Un nombre de estado es un objeto JSON y sus propiedades son los pares clave-valor de ese objeto. Propiedades como type y next se usan comúnmente para todos los estados. Si un estado no menciona la clave next, es el último estado en el circuito. Si un estado no se menciona como next en ningún otro estado, es el primer estado del circuito.

Debes seguir la sintaxis JSON estándar al codificar un circuito.

A continuación se muestra un fragmento de código de ejemplo de un circuito:

URL del circuito

Cuando creas un circuito en tu proyecto de Catalyst, se generará automáticamente una URL de invocación única para él. Puedes activar el circuito desde esta URL de punto final. Puedes implementar esta URL en el código de tu aplicación o usarla según lo necesites.

Puedes obtener la URL de un circuito desde la consola.

La URL de un circuito tiene el siguiente formato:

https://project_domain_name.environment_type.zohocatalyst.com/baas/v1/project/_project_ID_/circuit/circuit_ID/execute

Esta URL debe invocarse con el método HTTP POST.

El project_domain_name es el nombre de dominio de tu proyecto. El environment_type es development, si estás trabajando en el entorno de desarrollo. De lo contrario, el environment_type no está presente en la URL.