Conectores - Tomo 4 Conector Servicios Web REST - Intranet ...
←
→
Transcripción del contenido de la página
Si su navegador no muestra la página correctamente, lea el contenido de la página a continuación
Integración
Conectores – Tomo 4
Conector Servicios Web REST
(7 octubre 2019)
Esta publicación pertenece al Servicio de Documentación de AuraPortal (SDAP) y todos los
derechos están reservados. La reproducción total o parcial de este documento, así como la
entrega a terceras partes sin el permiso escrito del SDAP quedan prohibidas.
www.auraportal.com | info@auraportal.com | Skype: AuraPortal | Tel: +34 962 954 497 | In-
ternacional: +18 572 390 070ÍNDICE
INTRODUCCIÓN ........................................................................................................................................................... 3
1. QUÉ SON LOS SERVICIOS WEB REST .................................................................................................................. 3
2. CONECTOR DE SERVICIOS WEB REST ................................................................................................................ 4
2.1. INTERFAZ ......................................................................................................................................................... 4
2.2. CREAR Y CONFIGURAR UN CONECTOR ...................................................................................................... 6
2.2.1. Autenticación ............................................................................................................................................ 6
2.2.1.1 OAuth 2.0 .......................................................................................................................................... 6
2.2.1.2 Básica (o de Windows) ..................................................................................................................... 7
2.2.2. Formato de fechas .................................................................................................................................... 7
2.2.3. Formato de codificación ............................................................................................................................ 8
2.2.4. Headers Request y Headers Response ................................................................................................... 8
2.2.5. Request ..................................................................................................................................................... 9
2.2.6. Response .................................................................................................................................................. 9
2.3. MAPEO ............................................................................................................................................................ 10
2.3.1. Mapeo de la URL .................................................................................................................................... 10
2.3.2. Mapeo de las cabeceras ......................................................................................................................... 11
2.3.3. Mapeo de Request y Response .............................................................................................................. 11
2.4. USO DE UN CONECTOR ................................................................................................................................ 17
3. SERVICIOS WEB REST EN MENSAJES DE AURAPORTAL (IM, EM) ................................................................ 17
3.1. CONFIGURACIÓN .......................................................................................................................................... 17
3.2. INVOCACIÓN .................................................................................................................................................. 18
3.2.1. Autenticación .......................................................................................................................................... 18
3.2.2. Datos de inicio ........................................................................................................................................ 18
3.2.2.1. Consideraciones generales ........................................................................................................... 18
3.2.2.2. Campo Texto una Línea (o Multilínea) .......................................................................................... 20
3.2.2.3. Campo Número Entero .................................................................................................................. 20
3.2.2.4. Campo Número Decimal ............................................................................................................... 20
3.2.2.5. Campos Fecha y Fecha-Hora ........................................................................................................ 20
3.2.2.6. Campo Prefijo ................................................................................................................................ 21
3.2.2.7. Campo Selección Múltiple ............................................................................................................. 21
3.2.2.8. Campo Biblioteca ........................................................................................................................... 21
3.2.2.9. Campo Grupo de Campos ............................................................................................................. 22
3.2.3. Referencia del EM .................................................................................................................................. 23
3.2.4. Respuesta ............................................................................................................................................... 23
ANEXO 1. EJEMPLO MAPEO .................................................................................................................................... 25
JSON ORIGINAL .................................................................................................................................................... 25
JSON CON MAPEO ............................................................................................................................................... 26
INTEGRACIÓN. CONECTORES. TOMO 4 Página 2 de 26INTRODUCCIÓN
AuraPortal dispone de una gran variedad de mecanismos que le permiten integrar, o conectar con, datos
externos para facilitar en lo posible una gestión centralizada en la empresa. Entre estos mecanismos, se
encuentran los Conectores, objeto de esta documentación.
Hay varios conectores desarrollados por AuraPortal que se recogen en la serie Integración-03-
Conectores:
• Conector Email. Permite iniciar Procesos a partir de la recepción de un email. Se explica en el
Tomo 1 de la serie.
• Conector Excel. Extrae filas de una hoja Excel y las convierte en líneas de un grupo de campos. Se
explica en el Tomo 1 de la serie.
• Conector SharePoint Online. Integra documentos en SharePoint y convierte grupos de campos
en Listas de SharePoint. Se explica en el Tomo 1 de la serie.
• Conector SAP. Permite conectar con SAP de forma sencilla sin necesidad de programar una línea
de código, permitiendo integrar los datos del ERP en AuraPortal para utilizarlos o modificarlos in-
cluyéndolos en los Procesos de la entidad. Se explica en el Tomo 3 de la serie.
• Servicios Web REST. El término REST deriva de “REpresentational State Transfer” y es cualquier
interfaz entre sistemas que utilice directamente HTTP para obtener datos o indicar la ejecución de
operaciones sobre los datos, en cualquier formato (XML, JSON, etc.) sin las abstracciones adicio-
nales de los protocolos basados en patrones de intercambio de mensaje (SOAP). Se explican en
este documento.
• Adaptadores. Incluidos en AuraPortal Adapters Server, conjunto de Conectores cada uno de
ellos relacionado con una base de datos externa y que desarrolla una acción específica. Este me-
canismo permite la obtención de datos para la Lectura y / o Modificación de datos en Bases de
Datos Externas. Se explican en el Tomo 2 de la serie.
1. QUÉ SON LOS SERVICIOS WEB REST
El termino REST deriva de “REpresentational State Transfer” y es cualquier interfaz entre sistemas que utili-
ce directamente HTTP para obtener datos o indicar la ejecución de operaciones sobre los datos, en cual-
quier formato (XML, JSON, etc.) sin las abstracciones adicionales de los protocolos basados en patrones de
intercambio de mensaje (SOAP).
Los Servicios Web (SW) REST se caracterizan por tener estas propiedades:
- Se publican recursos. Un recurso se puede considerar como una entidad que representa un con-
cepto de negocio que puede ser accedido públicamente.
- Cada recurso posee un identificador único y global.
- Cada recurso posee un estado interno que no será accesible de forma externa, lo que sí es acce-
sible es una representación de dicho estado en forma de JSON.
- Todos los recursos comparten una interfaz única y constante formada por acciones. Estas son:
• GET para obtener recursos.
• POST para crear nuevos recursos.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 3 de 26• PUT y PATCH para modificar recursos.
• DELETE para eliminar recursos.
2. CONECTOR DE SERVICIOS WEB REST
El conector de SW REST de AuraPortal es una herramienta que le permitirá conectar a cualquier API REST
sin necesidad de ningún tipo de programación.
El conector de SW REST de AuraPortal consta de una sencilla interfaz donde se podrán crear diferentes
conectores con múltiples operaciones. Cada conector dispondrá de una configuración para la autorización
requerida por la API REST a la que se quiere acceder; esta configuración será común para cada operación
del conector.
En cada conector se podrán crear de forma sencilla las operaciones necesarias (GET, POST, ...) sin necesidad
de codificación.
2.1. Interfaz
El conector de SW REST de AuraPortal dispone de una interfaz clara y sencilla desde la que podrán crear
las diferentes operaciones y relacionar los JSON de envío y respuesta contra los respectivos campos de
AuraPortal.
La interfaz cuenta con cuatro partes claramente diferenciadas:
• Cabecera (1). Contiene la configuración genérica del conector.
• Operaciones (2). Contiene la lista de operaciones contenidas en un mismo conector, desde aquí
podremos añadir nuevas operaciones o seleccionar las operaciones a editar. Por ejemplo:
INTEGRACIÓN. CONECTORES. TOMO 4 Página 4 de 26Puede haber cualquier número de operaciones de cualquiera de los tipos posibles. En la imagen superior
hay 3 operaciones distintas, pero también pueden repetirse varias o todas del mismo tipo, etc.
• Detalles de la operación (3). Contiene los detalles de la operación seleccionada para su edición.
• Diccionarios (4). Contiene un buscador de campos para facilitar el mapeo de los campos.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 5 de 262.2. Crear y configurar un conector
Para crear un nuevo conector abriremos el editor desde:
Estructura > Conectores > Configurar > Web Services REST > Crear
El primer paso será indicar el nombre del conector, único campo requerido.
A modo de configuración, podremos indicar el sistema de autenticación, el formato de fechas y el formato
de codificación en el que se espera recibir los datos.
Continuaremos añadiendo una nueva operación con el botón Crear Operación, la cual personalizaremos en
el apartado Detalles de la operación con el nombre de la operación, la URL de invocación del SW y el tipo
de acción a realizar.
Detalles de la operación dispone de cuatro pestañas para terminar la configuración del conector:
• Headers Request
• Request
• Headers Response
• Response
Tanto el conector, como las propias operaciones, disponen de una opción para su publicación, Publicar. Si
esta opción no está marcada, el conector o la operación no aparecen disponibles en el diseño del proceso.
2.2.1. Autenticación
Los SW REST aceptan varios tipos de autenticación. El conector REST de AuraPortal está preparado para
trabajar con los dos tipos más populares y extendidos: OAuth 2.0 y Basic Auth.
2.2.1.1 OAuth 2.0
Para hacer uso de este sistema de autenticación solo necesitamos seleccionarlo y rellenar los campos que
se aprecian en la imagen con la información que proporcione la API REST con la que estemos interactuan-
do.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 6 de 262.2.1.2 Básica (o de Windows)
Este sistema de autenticación es el más sencillo y vendrá definido por la típica pareja de Usuario-Password
2.2.2. Formato de fechas
El conector dispone de una amplia variedad de formatos de fecha. Estos formatos se aplicarán a todas las
operaciones de un mismo conector.
El envío de fecha y hora o solo fecha dependerá del tipo de campo contra el que esté mapeado.
Si no se indica ningún formato de fecha y hora, se usará el de la configuración general de AuraPortal.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 7 de 262.2.3. Formato de codificación
El conector acepta tres formatos de codificación de caracteres: UTF-8, Unicode o Default. Si no se seleccio-
na ninguno, el conector tomará por defecto el formato UTF-8.
2.2.4. Headers Request y Headers Response
Contenedor de las distintas cabeceras que necesite el SW.
El formato de las cabeceras constantes será:
CLAVE :VALOR
El formato de las cabeceras dinámicas será:
CLAVE :[Nombre interno campo AuraPortal] (Ver Anexo 1: Sobre los mapeos)
Se pueden añadir tantas cabeceras como sea necesario, siendo obligatorio que cada una de ellas esté en
una nueva línea, como muestra la siguiente imagen de ejemplo.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 8 de 262.2.5. Request
En este contenedor incluiremos el JSON que enviará el SW con su correspondiente relación con los campos
de AuraPortal, tal como muestra la imagen. (Ver Anexo 1: Sobre los mapeos).
2.2.6. Response
En este contenedor incluiremos el JSON que recibirá el SW con su correspondiente relación con los cam-
pos de AuraPortal, tal como muestra la imagen.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 9 de 26Una vez terminada la configuración de la operación, haremos uso del menú de Detalles de la Operación
para guardarlo.
Podemos mapear múltiples JSON para diferentes respuestas de un mismo servicio web, para ello indicare-
mos el StatusCode de cada respuesta e incluiremos su JSON correspondiente, por ejemplo, así:
Podemos añadir tantas operaciones como necesitemos a nuestro conector repitiendo este proceso.
2.3. Mapeo
El objetivo del conector de SW REST es el de integrar con AuraPortal cualquier plataforma externa que
disponga de una API REST. Para cumplir esto, es necesario relacionar los campos de AuraPortal con la in-
formación proporcionada por los SW REST, lo que se conoce como Mapeo.
2.3.1. Mapeo de la URL
Las URL pueden contener parámetros, y es posible que necesitemos que esos parámetros provengan de un
campo del panel del proceso. Para ello, podremos indicar el nombre interno del campo en la URL y el co-
nector se encargará de sustituirlo por el valor que corresponda en ejecución.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 10 de 26Formato: [Nombre Interno]
2.3.2. Mapeo de las cabeceras
Las cabeceras pueden contener valores susceptibles de ser parametrizados (tipo de datos, tamaño, lengua-
je…), así que el conector también permite mapear cabeceras contra campos de panel de un proceso de
AuraPortal.
Formato: Nombre cabecera:[Nombre Interno]
2.3.3. Mapeo de Request y Response
Los SW REST se caracterizan por utilizar JSON como formato de datos, proporcionado una estructura clara
de los datos tratados. El conector de SW REST de AuraPortal permite un mapeo sencillo de estas estructu-
ras.
En la pestaña correspondiente a cada mapeo podremos comprobar si la estructura JSON es correcta. Un
aspa azul nos indica que la estructura es correcta.
Los JSON están formados por varios tipos de estructuras más pequeñas, estas son:
Propiedad
La unidad básica, formada por una pareja de clave – valor.
Ejemplos:
“clave”:”valor”
“id”:”123”
“nombre”:”Juan”
Para mapear esta estructura debemos sustituir el valor de la derecha por el nombre interno del campo de
AuraPortal del cual queremos obtener o asignar los datos.
Ejemplos:
“clave”:”3_valor”
“id”:”3_idUsuario”
“nombre”:”3_NombreCliente”
Array
Los arrays son una estructura de tipo contenedor que permite repetir una misma estructura más simple.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 11 de 26Este tipo de estructura se mapeará siempre contra términos de tipo grupo de campos de AuraPortal. Ya
que la estructura interna se repite, solo será necesario mapear una unidad básica.
La forma de mapear es la siguiente:
En el nombre del array incluiremos el nombre interno del grupo de campos separados por “###”. Esto
indicará de qué grupo de campos leerá o escribirá los datos. Dentro del array mapearemos los campos de
una estructura simple con campos que formen parte del grupo de campos contenedor.
Array dentro de Array
Estos arrays más complejos están formados por estructuras básicas que contienen otro array.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 12 de 26Su mapeo es idéntico al del array sencillo, pero en este caso tendremos que mapear el array contenido en
el primer array como un grupo de campos afiliado.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 13 de 26Array anónimo
Este es un tipo de array que no contiene propiedades en su interior, solamente los valores.
En este caso mapeamos directamente los campos sobre los valores.
Si el número de campos que contendrá el array anónimo es variable, el mapeo se hará contra un término
de tipo multilínea.
Esto dará como resultado una lista con todos los valores que contenga el array.
Documentos
El conector permite el envío y recepción de documentos. Los documentos se pueden enviar de dos formas
a través del conector: en formato JSON con el fichero codificado en Base64, o en formato binario.
Para configurar el envío, entraremos en la opción Condiciones de documentos.
Después de elegir el Término de tipo biblioteca del diccionario, desde aquí podemos configurar Condicio-
nes según Etiquetas para el filtrado de los documentos.
También seleccionaremos el Tipo de formato de envío: Base64 o Binario.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 14 de 26En función del tipo de formato seleccionado, el conector se comportará de diferente manera.
Con el formato binario podremos seleccionar los documentos que deseamos Ingresar; se pueden ingre-
sar Todos, la Solo la última versión o Solo último documento incluido en la biblioteca.
Con el formato en Base64, si existe más de un documento en la biblioteca, se enviará el último integra-
do.
El mapeo de las bibliotecas es distinto para los dos tipos de envío.
- Binario. En este caso no hay JSON en el Request ni en el Response, así que en su lugar indicare-
mos el nombre interno de la biblioteca con la que vamos a tratar.
- Base64. Para el mapeo de los documentos en formato de Base64 tendremos que usar una serie
de palabras clave.
El campo que contendrá el nombre del documento (Obligatorio) lo mapearemos contra la palabra
clave “_Name”.
El campo con el propio documento (Obligatorio) lo mapearemos contra la palabra clave
“_Content”.
El campo con la descripción del documento lo mapearemos contra la palabra clave “_Description”
Existen 40 palabras clave más reservadas para etiquetas. Las etiquetas sencillas se mapearán con
la palabra clave “_Txt1” cambiando el número por el que corresponda (del 1 al 32). Las etiquetas
de campos multilínea se mapearán con la palabra clave “_Txt_Multi1” cambiando el número por
el que corresponda (del 1 al 8).
La biblioteca con la que tratará el conector se indicará en la key del campo:
Con este mapeo conseguiremos enviar o recibir documentos. En caso del envío (POST), se enviará el últi-
mo documento de la biblioteca del proceso donde se ejecuta.
ResponseArray y RequestArray
Estas palabras reservadas se utilizarán en caso de que el servicio web invocado envíe o reciba un JSON que
sea un array en su totalidad. Esto suele ocurrir cuando invocamos un servicio de tipo GET sin especificar
algún parámetro y el servicio nos responde con todos los casos posibles.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 15 de 26Ya que una respuesta de este tipo está formada por un array que no dispone de un nombre para poder
mapearlo, usaremos estas palabras clave, ResponseArray y RequestArray, como nombre del array para así
mapearlo contra el grupo de campos de AuraPortal.
SingularFields
Esta palabra reservada se usa para el mapeo de un array contra campos singulares de AuraPortal. En los
casos en que el array contenga más de un valor, solo se guardará el último.
Mapeamos el array contra campos singulares:
INTEGRACIÓN. CONECTORES. TOMO 4 Página 16 de 262.4. Uso de un conector
Para integrar los conectores creados en una clase de procesos, debemos tener en cuenta el tipo de auten-
ticación de los SW. En el caso de la autenticación básica podemos asignar nuestro conector tanto a una
tarea de sistema como a un botón de acción del usuario. En el caso de la autenticación OAuth será nece-
saria la intervención del usuario para ingresar sus datos de conexión a la API REST con la que esté interac-
tuando el conector, en este caso, el conector debe ir integrado en un botón de acción.
3. SERVICIOS WEB REST EN MENSAJES DE AURAPORTAL
(IM, EM)
La integración de AuraPortal con los SW REST es total, así que también se permite lanzar un IM o EM des-
de un SW REST.
3.1. Configuración
Para crear un SW REST de inicio de IM (o EM) se tiene que crear un formulario en dicho IM (o EM). Con el
formulario creado ya podemos seleccionar la opción de Servicios Web.
Entrando en la configuración comprobamos que disponemos de dos opciones de SW de inicio de IM (o
EM), seleccionamos el tipo REST, a continuación, indicamos un nombre para nuestro SW y guardamos.
Con esto ya tendremos la URL de un SW REST listo para ser invocado de forma externa.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 17 de 263.2. Invocación
Para invocar un servicio web REST de inicio de IM (o EM) se creará una llamada de tipo POST con los re-
quisitos que se detallan a continuación:
3.2.1. Autenticación
La llamada al SW REST de inicio de IM (o EM) deberá contener un Header con la autenticación básica de
acceso a nuestra instalación de AuraPortal.
3.2.2. Datos de inicio
Si nuestro IM (o EM) requiere de datos externos para su inicialización, podemos enviar esos datos en el
Body de la llamada en forma de JSON.
Este JSON contiene el mapeo de los campos que deseamos iniciar y sus valores; para ello se deben usar las
estructuras correspondientes para cada tipo de dato de AuraPortal y que se especifican seguidamente:
3.2.2.1. Consideraciones generales
Esta será la estructura general del JSON de envío de datos:
INTEGRACIÓN. CONECTORES. TOMO 4 Página 18 de 26• El array “PanelFields” contiene todos los campos que queremos inicializar en el nuevo IM (o EM).
• Cada campo viene definido por:
o “InternalName”: Contiene el nombre interno del campo, respetando las mayúsculas y mi-
núsculas del nombre en AuraPortal.
o “Type”: El tipo de campo.
o El valor se debe insertar el adecuado para cada tipo.
• Tipos de datos aceptados:
o Text
o Integer
INTEGRACIÓN. CONECTORES. TOMO 4 Página 19 de 26o Decimal
o Boolean
o SimpleSelection
o MultipleSelection
o Prefix
o Sufix
o Library
o DateTime
o Date
o FieldsGroup
En los próximos puntos veremos un ejemplo de estructura de cada tipo.
3.2.2.2. Campo Texto una Línea (o Multilínea)
3.2.2.3. Campo Número Entero
3.2.2.4. Campo Número Decimal
3.2.2.5. Campos Fecha y Fecha-Hora
El valor de los campos “DateValue” y “DateTimeValue” siempre debe venir en el formato indicado.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 20 de 263.2.2.6. Campo Prefijo
3.2.2.7. Campo Selección Múltiple
El campo “MultipleSelectionValue” está formado por un array con los diferentes ID de los elementos a
seleccionar.
3.2.2.8. Campo Biblioteca
El campo “Documents” es un array con los diferentes documentos a integrar en el campo biblioteca. Esta
estructura de documento está formada por el nombre y el propio fichero en formato base64, estos campos
son obligatorios para su correcta integración.
Opcionalmente, podremos añadir una descripción y todas las etiquetas de las que disponen los documen-
tos de AuraPortal. Estas etiquetas respetan el tipo de etiqueta (Manual o Automática) definido en la Biblio-
teca de AuraPortal.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 21 de 263.2.2.9. Campo Grupo de Campos
El campo “FieldsGroupValue” es un array formado por diferentes repeticiones de la estructura “Row”. Esta
estructura es un nuevo array formado por los diferentes campos del grupo de campos, pudiendo contener
cualquier otro tipo de campo visto hasta ahora; desde campos de texto, hasta bibliotecas u otros grupos
de campos.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 22 de 263.2.3. Referencia del EM
Para iniciar un EM es necesario indicar la referencia del proceso al que pertenece. Esta referencia la añadi-
mos como una nueva propiedad en el JSON.
……..
3.2.4. Respuesta
El servicio responde con un StatusCode 200 OK y un JSON con el ID del nuevo proceso, la referencia del
nuevo proceso y un mensaje informativo sobre el resultado de la acción.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 23 de 26………
Nota.
Puede consultar estos detalles en el fichero ejemplo: InitIMJsonExample.json, que
se incluye en este mismo elemento.
INTEGRACIÓN. CONECTORES. TOMO 4 Página 24 de 26ANEXO 1. EJEMPLO MAPEO
JSON ORIGINAL
INTEGRACIÓN. CONECTORES. TOMO 4 Página 25 de 26JSON CON MAPEO INTEGRACIÓN. CONECTORES. TOMO 4 Página 26 de 26
También puede leer
