Funciones Integration

Introducción

Las Integration Functions te permiten programar y usar una función de Catalyst como backend de otros servicios de Zoho, y establecer una integración con ellos. Puedes programar la lógica de negocio de cualquier funcionalidad backend del servicio que sea soportada, a través de Catalyst, en las plataformas Java, Node.js o Python.

Cuando esa funcionalidad particular se accede en el servicio externo, automáticamente invocará la ejecución de la Integration Function programada en Catalyst a través de una llamada HTTP.

Crear Integration Functions para servicios externos te permite almacenar y gestionar la función en Catalyst, permitiéndote así acceder a varias funcionalidades y herramientas de Catalyst para ella, como ver los logs o reportes de las ejecuciones de funciones a través de Catalyst Logs o Application Performance Monitoring.

Catalyst proporciona paquetes SDK individuales exclusivos para los servicios con los que puedes integrarte. El SDK contiene plantillas de código de clases, objetos y métodos que puedes incorporar en tu aplicación fácilmente, y construir backends potentes para el servicio.

También puedes generar payloads de ejemplo para probar Integration Functions en el CLI. Consulta la página de ayuda de Event Generate para obtener más información.

Integración con Cliq

Catalyst actualmente soporta integración con Zoho Cliq a través de Integration Functions. Cliq facilita la comunicación en equipo y te permite colaborar, organizar conversaciones, programar tareas y más. También proporciona una plataforma para que los desarrolladores construyan herramientas internas que automaticen actividades de trabajo y traigan datos de otras aplicaciones dentro de las ventanas de chat. Puedes distribuir estas herramientas que creas, y los usuarios finales en Cliq pueden instalarlas para acceder a la funcionalidad.

Las Integration Functions de Catalyst te permiten programar el backend de extensiones de Cliq que pueden agrupar las siguientes herramientas internas de Cliq:

• Bots: Interfaz conversacional que maneja tareas o responde a consultas
• Commands: Comandos slash que realizan acciones integradas o personalizadas
• Message Actions: Acciones que se realizan como respuesta a mensajes individuales
• Widgets: Te permite personalizar tu pantalla de inicio de Cliq
• Functions: Funciones personalizadas que pueden ejecutar tareas basadas en ocurrencias de eventos

Puedes aprender más sobre estas herramientas internas y extensiones en la documentación de desarrollador de Cliq.

Beneficios

• Te permite programar extensiones agrupadas en las plataformas Java, Node.js o Python, en lugar de en Deluge que es el entorno de programación predeterminado soportado por Cliq
• Accede a los logs de ejecución de funciones y reportes detallados de rendimiento de funciones backend de Cliq a través de Logs o APM, que te permiten identificar áreas problemáticas y rectificarlas inmediatamente
• Soporte SDK funcionalmente rico y exclusivo para la integración con Cliq con archivos de clases pre-programados y plantillas de código, facilitando la comprensión de las acciones que se pueden realizar
• Capacidad de crear clases handler personalizadas para cualquier componente de Cliq y escribir tu lógica según tus necesidades

Crear Integration Functions en Catalyst

Similar a otros tipos de funciones, puedes crear una Integration Function desde la consola o inicializarla desde el CLI. Si la inicializas desde el CLI, puedes programarla usando un IDE externo y desplegarla en la consola de Catalyst.

Al crear una Integration Function ya sea desde la consola o desde el CLI, simplemente puedes seleccionar el servicio para el cual quieres crear la función. A diferencia de otros tipos de funciones, no tendrás la opción de crear una Integration Function sin un SDK, ya que la estructura del SDK puede ayudarte a entender mejor los componentes de Cliq.

Veamos la estructura de una Integration Function en detalle.

Estructura de Integration Function con Cliq

Un paquete de Integration Function contiene componentes diferentes en comparación con los otros tipos de funciones. El directorio de una función en Catalyst generalmente contiene el archivo principal de la función, junto con los componentes SDK de Java, Node.js o Python y los archivos de configuración.

Al igual que con los otros tipos de funciones, la estructura boilerplate de una Integration Function también contiene todos los componentes SDK y archivos de configuración necesarios. Sin embargo, además de los archivos JAR o módulos de Node agregados al directorio, el paquete de una Integration Function también incluye el SDK de Catalyst Cliq. El SDK te proporciona las interfaces y objetos necesarios para crear clases handler y desarrollar lógica de negocio específica del servicio. La plantilla de código contiene clases handler individuales para cada componente de la extensión de Cliq. Es decir, archivos de clases handler individuales para bots, commands, widgets, functions y message actions.

Primero veamos una estructura de función de ejemplo en Java, Node.js y Python, antes de discutir las clases handler.

Java

La estructura de archivos Java contiene el archivo Java principal, junto con las clases handler, los archivos JAR del SDK de Java de Catalyst y los archivos de configuración.

El SDK de Cliq para Java se incluye automáticamente cuando inicializas la función desde el CLI o la creas en la consola. También puedes obtener el SDK de Cliq para Java desde aquí.

Node.js

La estructura de archivos Node.js también contiene una función principal junto con las clases handler, los archivos de módulos de Node del SDK de Node.js de Catalyst y los archivos de configuración.

Similar al SDK de Cliq para Java, el SDK de Cliq para Node.js también se incluye automáticamente cuando inicializas la función desde el CLI o la creas en la consola.

Para instalarlo manualmente, debes ejecutar este comando desde el directorio de la función Node.js usando tu terminal:

npm install zcatalyst-integ-cliq

Python

Cuando creas una Integration Function en Python, además de los módulos de Python agregados al directorio de funciones, también se incluirá un paquete de Integration Function llamado SDK de Cliq para Python. El SDK te proporciona las interfaces y objetos necesarios para crear clases handler y desarrollar lógica de negocio específica del servicio. La plantilla de código contiene clases handler individuales para cada componente de la extensión de Cliq. Es decir, archivos de clases handler individuales para bots, commands, widgets, functions y message actions.

pip install zcatalyst-cliq

El paquete SDK de Catalyst Cliq contiene los sub-paquetes mencionados a continuación que son específicos de las herramientas internas en la aplicación Cliq. Puedes consultar esta sección para saber más sobre estas herramientas.

Clases Handler de Cliq

Los handlers de Cliq contienen las definiciones de la lógica de negocio de una acción específica en un componente de Cliq. Cada componente contiene múltiples handlers que definen acciones para manejar acciones o eventos específicos.

Por ejemplo, algunos de los handlers de un bot de Cliq son:

• Welcome handler: Define un mensaje personalizado cuando un usuario se suscribe a un bot
• Message handler: Se activa cuando un bot recibe un mensaje
• Mention handler: Renderiza una respuesta cuando un bot es mencionado en un chat

De manera similar, cada uno de los componentes de Cliq soportados por Catalyst- Commands, Message Actions, Widgets, Functions, tienen handlers individuales.

Consulta las páginas de ayuda de Cliq para detalles sobre todos los handlers soportados por cada componente.

Catalyst proporciona plantillas para los objetos y métodos necesarios que serían útiles para construir una extensión en cada clase handler. Te ayudan a entender el manejo de varias acciones como el análisis de llamadas de Cliq, el enrutamiento a la implementación apropiada o la construcción de la respuesta requerida.

Por ejemplo, BotClass.java, bot-handler.js o main.py contiene una plantilla de código de ejemplo para cada handler individual de una clase handler de bot.

Puedes consultar estas definiciones y usar estos métodos para personalizar tu propia lógica para la extensión. Puedes modificar las clases handler según tus requisitos e incluir solo las necesarias. El usuario puede usar este SDK para analizar la llamada de Cliq, enrutar la llamada a la implementación correspondiente y formar respuestas de salida.

Mapeo de archivos de clases Handler

Mapeo en catalyst-config.json para funciones Java y Node.js

Todos los archivos de clases handler se mapean en el archivo de configuración catalyst-config.json de una función. El archivo de configuración típicamente solo incluye detalles básicos de ejecución y despliegue de una función de Catalyst. Sin embargo, para una Integration Function, este archivo también mapea las clases handler que se utilizan en ella.

Este mapeo ayuda a Catalyst a ejecutar el conjunto correcto de acciones cuando se invoca la función.

También puedes crear un nuevo archivo de clase handler para un componente de Cliq y definir tu propia lógica en él. Sin embargo, debes mapear manualmente el archivo de clase handler en el archivo catalyst-config.json. Asegúrate de seguir el mismo formato al escribir la clave para el mapeo.

Los archivos handler predeterminados creados como parte del SDK de Catalyst Cliq ya están mapeados cuando creas la función desde la consola o el CLI.

Mapeo en main.py para funciones Python

Cuando creas una Integration Function, el SDK de Cliq para Python se instalará automáticamente dentro del directorio de funciones de tu proyecto actual. Para Python, todos los archivos de clases handler se mapean en el archivo main.py de una función. Este mapeo ayuda a Catalyst a ejecutar el conjunto correcto de acciones cuando se invoca la función.

También puedes crear un nuevo archivo de clase handler para un componente de Cliq y definir tu propia lógica en él. Sin embargo, debes mapear manualmente el archivo de clase handler en el archivo main.py. Asegúrate de seguir el mismo formato al escribir la clave para el mapeo.

Los archivos handler predeterminados creados como parte del SDK de Cliq para Python ya están mapeados cuando creas la función desde el CLI.

import zcatalyst-cliq
# aquí se debe indicar el mapeo de los archivos del manejador de cliq
config = {
    "ZohoCliq": {
        "handlers": {
            "bot_handler": "handlers/bot_handler.py",
            "function_handler": "handlers/function_handler.py",
            "installation_validator": "handlers/installation_validator.py",
            "command_handler": "handlers/command_handler.py",
            "widget_handler": "handlers/widget_handler.py",
            "messageaction_handler": "handlers/message_action_handler.py",
            "installation_handler": "handlers/installation_handler.py"
        }
    },
}
def handler(request, response):
    handler_resp = zcatalyst_cliq.execute(request, config)
    response.set_content_type('application/json')
    response.send(handler_resp)

El objeto request de tipo IntegrationRequest se envía como argumento al método execute() y se analiza con información como el nombre de la herramienta interna de Cliq y la operación que se está realizando con ella. La propiedad config contiene los mapeos de los archivos de clases handler con los respectivos handlers y se pasa como otro argumento al método. Según los parámetros, el método execute() procede con su operación de procesar la solicitud con las respectivas clases handler y devuelve la respuesta.

Después de crear una Integration Function en Catalyst, puedes crear una extensión en Cliq para invocar la función. Para crear extensiones en Cliq, puedes consultar esta sección.

Configurar extensiones en Cliq

Después de desarrollar el backend para una extensión de Cliq, debes agregar la función mientras configuras la extensión en Cliq. Este será un mapeo único de Extensión de Cliq - Integration Function de Catalyst.

Cada vez que los componentes de esa extensión se invoquen a través de Cliq, a su vez activará la función de Catalyst mapeada a ella. La acción apropiada definida para esa solicitud se activará a través de las clases handler.

Por ejemplo, si el usuario final en Cliq envía un mensaje a un bot cuyo backend está definido en Catalyst, la solicitud se pasará a Catalyst después de ser autenticada. Los detalles del componente, usuario y chat se adjuntan en el cuerpo de la solicitud HTTP.

Catalyst luego invocará el message handler definido en el archivo BotClass.java, bot-handler.js o main.py, y ejecutará la acción apropiada. Catalyst enviará la respuesta de vuelta a Cliq y se renderizará en el frontend del componente de Cliq.

Crear una extensión en Cliq

Puedes crear una extensión en Cliq y configurar componentes como bots, widgets o commands para agruparlos en ella desde la consola de desarrollador en Cliq.

Para configurar una Integration Function de Catalyst en una extensión de Cliq, debes seleccionar el Execution Type como “Catalyst Function” cuando crees la extensión en Cliq.

Luego debes elegir el proyecto de Catalyst de la lista desplegable. Todos los proyectos de tu cuenta de Catalyst se listarán aquí. También puedes hacer clic en Create Project que te redirigirá a Catalyst para crear un nuevo proyecto.

Luego debes seleccionar la Integration Function de la lista desplegable que se asociará con esta extensión. Después de configurar otros detalles y componentes de tu extensión, haz clic en Create Extension.

Esto creará la integración con Catalyst y habilitará que la Integration Function se ejecute cada vez que se acceda a los componentes.

Para aprender sobre el desarrollo de extensiones para Catalyst en Cliq en detalle, consulta la documentación de ayuda de extensiones tipo Catalyst.