Descripción general

Las integraciones definen cómo los bots pueden conectarse a los sistemas externos. Esto se puede utilizar para el cumplimiento o para recuperar datos de otros sistemas en Attributes (Atributos). Los administradores pueden crear y gestionar las aplicaciones, las instancias de la aplicación (las credenciales para conectarse a los sistemas de destino) y las operaciones. Los servicios web se utilizan en las habilidades para realizar el cumplimiento en los sistemas de destino solicitados. Generalmente, un administrador crea las aplicaciones y las instancias en el nivel del inquilino.

Crear aplicación

Las instancias de aplicación son los sistemas de destino en los que se ejecutan las habilidades y los atributos para el cumplimiento. Al crear la instancia de la aplicación, se definen los mecanismos de conectividad y autenticación para el sistema de destino. Se puede definir el nombre de la aplicación y el tipo de integración (por ejemplo, REST, ISM, SDM, correo electrónico, etc.). El tipo de aplicación seleccionado en la definición de la operación debe indicar el tipo de integración que hará que se presente la plantilla para la configuración de la operación solicitada. Para crear una aplicación:

1. En el menú Tenant (Inquilino), haga clic en Integrations (Integraciones).
   La página Connected Apps (Aplicaciones conectadas) aparece como se muestra a continuación. 
   Una aplicación conectada es una integración que está configurada con Luma en el nivel del inquilino. Una vez que se ha creado la aplicación conectada, el paso siguiente es crear la instancia de la aplicación y las operaciones de servicios web correspondientes.
   
   
2. Haga clic en  Crear aplicación  para crear una nueva aplicación.
   Aparecerá la página Create App (Crear aplicación) como se muestra a continuación.
   
3. Introduzca el  Nombre de la aplicación.
4. Seleccione el tipo de integración.
5. Haga clic en Create (Crear) para completar la creación de la aplicación.
   La aplicación creada está disponible en la lista Connected Apps  (Aplicaciones conectadas). El paso siguiente es crear una instancia.  

Crear instancia

Una vez creada la aplicación, se debe crear la Instancia de la aplicación. En resumen, la instancia de la aplicación define los mecanismos de autenticación y conectividad para el sistema de destino. La instancia de la aplicación ayuda a definir los detalles del entorno de destino para la ejecución de las operaciones del servicio web. El desarrollador utiliza los detalles de la instancia de la aplicación en el cumplimiento de la habilidad o el cumplimiento del atributo para realizar la operación en el entorno de destino solicitado. En el caso del tipo de integración REST de la aplicación conectada, se puede proporcionar la configuración de la solicitud (ruta de acceso, consulta y encabezados) en el nivel de la instancia de la aplicación, que son comunes para todas las operaciones del servicio web.  

Para crear una instancia:

1. En la página de Connected Apps (Aplicaciones conectadas), haga clic en Create Instance (Crear instancia) como se muestra a continuación.
   

Aparecerá la página de  Crear instancia  como se muestra a continuación.

1. Introduzca el  Nombre  y la  Descripción de la instancia. El paso siguiente es definir las credenciales y los detalles de conexión para esta instancia.

2. Introduzca la URL base a la que Luma se debe conectar.

3. Luma usa el tipo de autorización para iniciar sesión y realizar las operaciones especificadas como parte de la operación del servicio web.

   Luma es compatible con los siguientes tipos de autorizaciones:

   1. No auth (Sin autenticación): utilice esta opción si no necesita ninguna autenticación para iniciar sesión en los sistemas de terceros.
   2. Basic Auth (Autenticación básica): utilice esta opción para autenticar las aplicaciones externas para interactuar con el inquilino de Luma. La autenticación básica consta de los siguientes campos:
      
      1. Username (Nombre de usuario): especifique el nombre de usuario. Luma lo utiliza como un nombre de usuario de autenticación para iniciar sesión en los sistemas de terceros.
      2. Contraseña: especifique la  contraseña. Luma utiliza esta contraseña durante la autenticación con el sistema de terceros.
      3. Authorization Header Name (Nombre del encabezado de autorización): de forma predeterminada, el nombre del encabezado de autorización es especificado como autorización por Luma.
   3. Bearer Token (Token de portador): este es el token único de autenticación que se necesita para que las aplicaciones externas se comuniquen con la API de Luma. 
      
      El token de portador consta de los siguientes campos:
      
      1. Authorization Header Name (Nombre del encabezado de autorización): de forma predeterminada, el nombre del encabezado de autorización es especificado como autorización por Luma.
      2. Token: introduzca el token de autenticación exclusivo para que las aplicaciones externas se comuniquen con la API de Luma.
4. Path Parameter (Parámetro de ruta): forma parte de un segmento de ruta que aparece después de su nombre. Los parámetros de ruta ofrecen una oportunidad única para reemplazar los valores de forma dinámica y pasarlos a la dirección URL. Por ejemplo, http://myserver.com/some-path/{parameter1}/path-continued/{parameter2}.
   1. Introduzca el Campo externo y el Valor.
5. Query Parameter (Parámetros de consulta): los parámetros de consulta a veces se conocen como parámetros opcionales. Los parámetros de consulta se separan de los parámetros jerárquicos con un signo de interrogación. Los parámetros de consulta se muestran en la dirección URL tras el signo de interrogación (?) después del nombre del recurso. Por ejemplo, https://myserver.com/resource-name?param1=value1&param2=value2. 
   1. Introduzca el Campo externo y el Valor.
6. Encabezados: los encabezados se clasifican principalmente como encabezados de solicitudes. Se deberán establecer los encabezados de la solicitud cuando se envíe la solicitud.
   1. Introduzca el Campo externo y el Valor.
      Los siguientes encabezados de muestra son los que más se encuentran.
      • Authorization (Autorización): incluye credenciales que contienen la información de autenticación del cliente para el recurso que se solicita. 

      • Accept-charset (Aceptar conjunto de caracteres): se trata de un encabezado que se establece con la solicitud y que indica al servidor qué conjuntos de caracteres son aceptables para el cliente. 

      • Content-Type (Tipo de contenido): indica el tipo de medio (texto/HTML o texto/JSON, XML/personalizado) de la respuesta que el servidor envía al cliente, por lo que el cliente podrá procesar correctamente el cuerpo de la respuesta.

7. Click Create to create the app instance.

   La primera instancia que se agrega se considera la instancia predeterminada.

Crear operaciones

Las operaciones ayudan a generar integraciones con sistemas externos. Como administrador, puede crear y editar las operaciones en la aplicación seleccionada para las habilidades en el nivel de dominio, lo cual se debe ejecutar en el entorno de destino como parte del cumplimiento de la habilidad. 

Una vez que se han creado la instancia de la aplicación y la aplicación, se deben crear las operaciones necesarias. Una operación define la tarea que se debe llevar a cabo en el cumplimiento. Para crear una operación:

1. En la página de Aplicaciones conectadas , haga clic en  Crear operación  como se muestra a continuación.

1. 
   
   
   La página de  Crear operación aparecerá como se muestra a continuación.
   
2. En la pestaña Detalles de operación , introduzca el  nombre de la operación.
3. El sistema muestra automáticamente el dominio de la habilidad predeterminado del inquilino. 
4. El identificador de recursos uniforme (URI) se utiliza para referirse al recurso de información. Introduzca el URI.
5. Seleccione el métodode la operación. Utiliza un marco de encadenamiento de solicitud de API para que los bots inserten o soliciten datos desde los sitios web, los sistemas y las aplicaciones web mediante el uso de los servicios web.
   Los métodos de operación siguientes están disponibles:
   • Get  (Obtener): para recuperar datos
   • Post  (Publicar): para crear datos
   • Colocar:  para editar los datos
   • Delete  (Eliminar): para eliminar los datos
6. El sistema muestra automáticamente la operación compatible para invocar la API REST.
7. Se debe especificar Timeout (in milliseconds) (Tiempo de espera [en milisegundos]), la cantidad de tiempo de espera para una respuesta de servicio web  al invocar una solicitud saliente.  El valor predeterminado es de 10.000 milisegundos, 10 segundos, y el valor máximo permitido es de 3 minutos, 180.000 milisegundos.
8. Haga clic en Next (Siguiente) para especificar los detalles de la configuración de la solicitud .
   La página Request Configuration (Configuración de la solicitud) aparece como se muestra a continuación.
   
9. Parámetro de ruta: forma parte de un segmento de ruta que aparece después de su nombre. Los parámetros de ruta ofrecen una oportunidad única para reemplazar los valores de forma dinámica y pasarlos a la dirección URL. Por ejemplo, http://myserver.com/some-path/{parameter1}/path-continued/{parameter2}. Se puede sobrescribir la configuración definida en el nivel de instancia o continuar utilizando el mismo elemento, y es posible que se necesite agregar los valores y variables específicos de la operación. 
   1. Introduzca el Campo externo y el Valor.
10. Parámetros de consulta: los parámetros de consulta a veces se conocen como parámetros opcionales. Los parámetros de consulta se separan de los parámetros jerárquicos con un signo de interrogación. Los parámetros de consulta se muestran en la dirección URL tras el signo de interrogación (?) después del nombre del recurso. Por ejemplo, https://myserver.com/resource-name?param1=value1&param2=value2. Se puede sobrescribir la configuración definida en el nivel de instancia o continuar utilizando el mismo elemento, y es posible que se necesite agregar los valores y variables específicos de la operación. 
    1. Introduzca el Campo externo y el Valor.
11. Encabezados: los encabezados se clasifican principalmente como encabezados de solicitudes. Se deberán establecer los encabezados de la solicitud cuando se envíe la solicitud. Se puede sobrescribir la configuración definida en el nivel de instancia o continuar utilizando el mismo elemento, y es posible que se necesite agregar los valores y variables específicos de la operación. 
    1. Introduzca el Campo externo y el Valor.
       Los siguientes encabezados de muestra son los que más se encuentran.
       • Authorization (Autorización): incluye credenciales que contienen la información de autenticación del cliente para el recurso que se solicita. 

       • Accept-charset (Aceptar conjunto de caracteres): se trata de un encabezado que se establece con la solicitud y que indica al servidor qué conjuntos de caracteres son aceptables para el cliente. 

       • Content Type: indica el tipo de medio (texto/HTML, texto/JSON, XML/personalizado o multipart/form-data) de la respuesta que el servidor envía al cliente, por lo que el cliente podrá procesar correctamente el cuerpo de la respuesta.

         Use multipart/form-data como Content Type (Tipo de contenido) para enviar un archivo adjunto al servidor del inquilino.

12. Carga saliente: es necesario transmitir la carga saliente para completar la solicitud. Form Data es la codificación predeterminada que usa un formulario web para transferir datos. El área del cuadro de texto acepta pares simples de clave-valor y JSON complejos o anidados. 
    

    

    To send an attachment as Outbound payload, use Attachment Mapping. Enter a External Field and select an attribute with datatype File as Value.
    
    
    
    

13. Haga clic en Continuar para crear la configuración de la respuesta.

Configuración de la respuesta

Esta sección se utiliza para procesar los datos o la respuesta recibida del servicio web externo.

Mapeo de entrada

Se pueden crear los atributos locales y personalizados del usuario para almacenar los datos que se utilizan en una operación. El atributo local almacena los datos temporales en el flujo de trabajo de acción que se van a pasar entre varias operaciones. Se utiliza como un marcador de posición en las plantillas y las reglas de mensajes del usuario dentro del flujo de trabajo de acción. El atributo de usuario personalizado almacena los datos extraídos de la entrada de usuario, de la operación de integración de terceros , de respuestas, etc.

A continuación se muestran los detalles necesarios para el Mapeo de entrada:

• Scope (Alcance): representa el alcance del atributo que se utilizará para contener los valores entrantes.
  • Utilice Global para asignar el valor a un atributo global que se utilizará en la habilidad. Aunque los atributos estén disponibles para que se puedan utilizar otras habilidades, el valor se mantiene hasta la ejecución de las habilidades.
  • Utilice Local (Local) para crear y establecer el valor de un atributo local. Estos atributos son válidos y están disponibles únicamente durante la ejecución de la habilidad.
  • Utilice User Custom (Personalizado del usuario) para asignar el valor a un atributo personalizado del usuario. Estos atributos mantienen los valores asignados a menos que se sobrescriban.
• Attribute (Atributo): es el nombre del atributo.
• Data Type (Tipo de dato): representa el tipo de dato del valor. 
• Expression Type (Tipo de expresión) y Expression (Expresión): representan el tipo (valor o JSON) y la ruta de la ubicación del  valor  que se asigna al atributo.
  • Utilice Expression Type (Tipo de expresión) → Value  (Valor) cuando un valor que se asigna al atributo, es decir, Expression (Expresión), apunta a un valor directo, por ejemplo, @{response.body}, @{response.code}.
  • Use Tipo de expresión y  JSONPath cuando un valor de la respuesta de JSON recibida se asignará al atributo, por ejemplo,  Expresión apunta a una ruta de acceso a JSON (por ejemplo, $.data.TicketIdentifier, $.data.items[*].Priority).
  • Use Expression Type (Tipo de expresión) → Indirect JSONPath (JSONPath indirecto) cuando un valor del atributo de tipo JSON se asignará al atributo, por ejemplo, Expression (Expresión) apunta a un atributo que mantiene una ruta de acceso a JSON (por ejemplo, @{local.items}→$).[*].TicketIdentifier

Manejo de errores

Esta sección se utiliza para definir el comportamiento y la respuesta de bot para el usuario cuando se produce un error durante la ejecución de la operación. Se pueden crear varias reglas que controlen errores desde las operaciones del servicio web.

Seleccione una de las siguientes opciones para definir una regla para enviar el mensaje de error. El mensaje de error se enviará solo si se validan las condiciones especificadas:

• Coincidencia con alguna de las siguientes condiciones: una de las condiciones especificadas debe coincidir para analizar el mensaje de error.
• Coincidencia con todas las siguientes condiciones: es necesario validar todas las condiciones especificadas para analizar el mensaje de error.
• Definición de criterios personalizados: se pueden definir criterios personalizados en función de las condiciones proporcionadas para analizar el mensaje de error si se valida.
  Por ejemplo, 1 y 2 o 3. Las condiciones primera y segunda deben coincidir, o solo la tercera condición debe coincidir. Se pueden introducir solo números, y, o, (,)

Especifique @response.StatusCode en el campo Key (Clave) seguido por un operador.  A continuación, se muestra la lista de operadores compatibles:

• Es igual a
• No es igual a
• es mayor que
• es mayor o igual que
• es menor que
• es menor o igual que
• Comienza con
• No comienza con
• Termina con
• No termina con
• Contiene
• No contiene
• está vació
• no está vacío
• coincide con el patrón

Sin manejo de datos

Esta sección se utiliza para definir el comportamiento y la respuesta del bot para el usuario cuando la ejecución de la operación no produce datos. Se pueden crear varias reglas sin ningún escenario de datos desde las operaciones del servicio web. Siga los valores de la devolución de la API de los sistemas externos desde los cuales recibe los datos, y escriba o evalúe los valores correspondientes en la sección Rules/conditions (Reglas/condiciones).

Manejo de operaciones correctas

Esta sección sea utiliza para definir el comportamiento y la respuesta del bot al usuario cuando la ejecución de la operación se ha realizado correctamente. Cree múltiples reglas que gestionen satisfactoriamente las operaciones del servicio web.