La actividad Servicio web integra un servicio web en un flujo de trabajo y permite que este intercambie datos con otros sistemas.
Por ejemplo, puede utilizar un servicio web dentro de un flujo de trabajo para crear, actualizar o eliminar información en aplicaciones de terceros. El servicio web también puede recuperar datos de aplicaciones empresariales como CRM o contabilidad y ponerlos a disposición de un flujo de trabajo de DocuWare. Los flujos de trabajo de DocuWare admiten la integración de servicios web tanto REST como SOAP.
Nota: añada primero un servicio web
Añada primero el servicio web a su organización DocuWare. Antes de poder integrar un servicio web en un flujo de trabajo, debe crear una conexión a este servicio web en Configuraciones de DocuWare > Servicios web.
Esta es la visión general de la configuración:
Para añadir un servicio web al flujo de trabajo, vaya a Configuraciones de DocuWare > Colaboración > Workflow Designer.
Haga clic en el botón Nuevo flujo de trabajo o en Editar para abrir un flujo de trabajo nuevo o existente en el lienzo.
En la barra lateral izquierda, haga clic en Servicio web.
Elija su método: REST o SOAP. La configuración de los servicios web REST o SOAP se describe en detalle más abajo.
También tiene la opción de crear salidas condicionales para una acción Servicio web.
Una vez finalizada la configuración, debe conectar la actividad Servicio web a otras actividades del flujo de trabajo.
.png)
El cuadro de diálogo de la actividad Servicio web en el Workflow Designer basado en web
Servicio web REST
El intercambio de datos a través de un servicio web RESTful se configura en un asistente con tres pestañas: General, Asignación de datos y Códigos de estado.
General: seleccione un servicio web
Dirección
Antes de poder utilizar un servicio web REST en un flujo de trabajo, debe estar registrado en Configuraciones de DocuWare > Servicios web. Solo aparecen en esta sección los servicios registrados.
Todos los servicios web REST instalados en su organización DocuWare y a los que tiene permisos figuran en la sección General > Dirección.
Servicio web definido: seleccione el servicio web REST que desea invocar.
URL del servicio web: la URL del servicio web REST seleccionado. Este campo se rellena automáticamente en función de la selección en Servicio web definido y es de solo lectura.
Para cambiar la URL, actualice el registro del servicio web en Configuraciones de DocuWare > Servicios web.Formato: indique el formato para el intercambio de datos (JSON o XML). La asignación de datos será diferente según el formato seleccionado.
Endpoint
Un endpoint es una URL específica del servidor web a la que se envía la solicitud. El endpoint recibe los datos y define la acción que se va a ejecutar.
El endpoint predeterminado es la raíz o la URL base (/). Es el punto de entrada inicial al servicio web.
Si el servicio web ofrece un archivo de especificación OpenAPI (*.json, .txt, .yml o *.yaml), puede importarlo mediante el botón de importación. Una vez importado, todos los endpoints disponibles aparecen en la lista desplegable.
Información: API predeterminada de DocuWare Platform
Al utilizar endpoints procedentes de una especificación OpenAPI o de la API DocuWare Platform API predeterminada o de DocuWare E-Invoicing, todas las rutas y parámetros necesarios se preconfiguran automáticamente en función del endpoint elegido, lo que simplifica la configuración de la solicitud HTTP del servicio web.
Configuración de parámetros: defina la solicitud HTTP
Haga clic en la URL que se muestra detrás del endpoint seleccionado para abrir el asistente Configuración de parámetros. Aquí se indica la información y las propiedades necesarias para ejecutar la solicitud HTTP, por ejemplo rutas, parámetros de consulta o el encabezado y el cuerpo de la solicitud. Esta información es necesaria para proporcionar al servicio web todos los datos que requiere.
.png)
Solicitud
En esta sección se configura la solicitud que se envía al endpoint. Las opciones de configuración disponibles dependen del servicio web y el endpoint que haya seleccionado. En la parte superior se muestra una vista previa de la solicitud (URL).
Método: el método HTTP indica lo que desea hacer con el endpoint. DocuWare admite GET, POST, PUT y DELETE.
Si utiliza un archivo de especificación OpenAPI o la API DocuWare Platform API predeterminada o DocuWare E-Invoicing, el método HTTP se preconfigura automáticamente en función del endpoint elegido.
Rutas: utilice las rutas para dirigirse de forma específica a recursos concretos del endpoint.
Si utiliza un archivo de especificación OpenAPI o la API DocuWare Platform API predeterminada o DocuWare E-Invoicing, la ruta se preconfigura automáticamente en función del endpoint elegido.
Puede pasar valores fijos o valores de índice de documento, así como variables globales o de sistema.Parámetros de consulta: introduzca aquí pares clave/valor para indicar al servicio web exactamente qué consultar. Los parámetros de consulta suelen ser opcionales y se utilizan con endpoints que emplean el método GET para filtrar o acotar un resultado.
Si utiliza un archivo de especificación OpenAPI o la API DocuWare Platform API predeterminada o DocuWare E-Invoicing, los parámetros de consulta se preconfiguran automáticamente en función del endpoint elegido.
Puede pasar valores fijos o valores de índice de documento, así como variables globales o de sistema.Documento adjunto: indique si el documento que se encuentra actualmente en el flujo de trabajo debe adjuntarse a la solicitud. El documento puede adjuntarse en su formato original o como PDF. Si el documento DocuWare contiene varios archivos (engrapados), todos los archivos se exportan y se adjuntan por separado. La solicitud HTTP contiene entonces varios objetos de archivo.
Esto le permite, por ejemplo, enviar un documento como una factura a un servicio externo.Codificación: indique la codificación de los valores pasados en las rutas y las consultas. Según los valores que pase en su solicitud, es posible que necesite codificar o no los caracteres de la URL. Existen tres opciones de codificación:
Codificar caracteres especiales (recomendado): se codifican todos los caracteres especiales. Por ejemplo, «AT&T» se convierte en «AT%26T» y «Rapid Transport» se convierte en «Rapid%20Transport».
Codificar caracteres especiales (excepto caracteres reservados de URL): (*&^%$#@!:
Se codifican todos los caracteres especiales excepto los caracteres reservados de URL. Por ejemplo, «AT&T» se mantiene, pero «Rapid Transport» se convierte en «Rapid%20Transport».
No codificar caracteres especiales: ni los caracteres especiales ni los espacios se codifican.
La codificación se aplica a todos los valores indicados en las rutas y los parámetros de consulta.
Encabezados HTTP
Los encabezados se sitúan al principio de la solicitud, justo después de la línea de estado. Los encabezados HTTP son pares clave-valor que proporcionan metadatos sobre la solicitud: por ejemplo, sobre el remitente, el formato de los datos enviados, la autenticación o la forma que debe tener la respuesta del servicio web, dentro de las posibilidades que ofrezca el propio servicio web.
Cuerpo HTTP
El cuerpo HTTP es la parte de la solicitud en la que envía datos (por ejemplo, con POST o PUT).
Indique la información y las propiedades necesarias para ejecutar la operación seleccionada, por ejemplo, el GUID del sello que se va a aplicar. O, si está creando un nuevo usuario, el cuerpo HTTP contiene los datos del usuario en formato JSON. La validación del cuerpo HTTP se realiza al enviar la solicitud o automáticamente al guardar la configuración. Si parte del contenido no es válido, el error correspondiente se resalta y se muestra un mensaje apropiado. La configuración también puede guardarse si hay problemas de validación.
Estructure el contenido del cuerpo HTTP utilizando valores fijos, datos de índice o variables globales y de sistema. Tenga en cuenta que, incluso si hay problemas de validación, dispone de la opción de guardar la configuración.
Prueba
Pruebe la solicitud con el botón Enviar solicitud y examine la «Respuesta» para verificar si la operación se ha realizado correctamente. Tenga en cuenta que debe proporcionar un valor de prueba para cada variable a fin de ejecutar la prueba. También puede indicar aquí un documento de prueba, que se incluirá en la solicitud de prueba al servicio web.
Asignación de datos: utilizar los datos de la solicitud en el flujo de trabajo
La información devuelta por la respuesta del servicio web puede utilizarse dentro del flujo de trabajo. En Asignación de datos se indica dónde deben almacenarse estos datos dentro del flujo de trabajo. La estructura de la respuesta la define el servicio web, no el flujo de trabajo de DocuWare. En el Workflow Designer solo decide si se utilizan partes de la respuesta y cuáles.
Asigne los valores de la respuesta a variables globales o a datos de índice. Elija los valores necesarios directamente en la estructura JSON o XML de la respuesta.
Ejemplo: el servicio web recupera los datos de una empresa desde el CRM o información adicional sobre un pedido desde el sistema ERP.
Si desea procesar todas las entradas devueltas, sustituya manualmente el índice por un asterisco (*) en el indexador de la matriz. Así podrá procesar de forma exhaustiva todas las entradas de la matriz.
Códigos de estado
Los servicios web REST devuelven, una vez ejecutados, lo que se conoce como código de estado HTTP. Este código indica si la solicitud se ha realizado correctamente o si se ha producido un error.
Algunos códigos de estado habituales son, por ejemplo:
200 = OK (todo se realizó correctamente)
201 = Created (se ha creado algo)
400 = Bad Request (error en los datos enviados)
404 = Not found (recurso no encontrado)
500 = Error del servidor
Si activa la función Asignar código devuelto a una variable del flujo de trabajo, el código de estado devuelto se guardará en una variable global del flujo de trabajo.
El código almacenado en la variable puede evaluarse posteriormente en el flujo de trabajo, por ejemplo, para el control de errores o el registro.
Control de errores
Cambie a la pestaña Errores para configurar cómo debe continuar el flujo de trabajo si la llamada al servicio web falla. Si, por ejemplo, el servicio web externo no está disponible, puede configurar el flujo de trabajo para que dirija el documento a otra acción automatizada, como enviar una notificación por correo electrónico que solicite introducir manualmente la información que falta.
Elija una de las siguientes opciones:
Sin control de errores: esta opción está activada por defecto.
Reiniciar flujo de trabajo: el documento se enruta automáticamente desde el principio a través de los pasos del flujo de trabajo.
Finalizar flujo de trabajo: el documento se enruta automáticamente al final del flujo de trabajo. Todos los cambios realizados hasta este punto se conservan.
Ir al paso: esta opción añade una salida Error a la actividad Asignar datos. Conéctela con otra actividad para enrutar el documento del flujo de trabajo manualmente.
Servicio web SOAP
SOAP (Simple Object Access Protocol) es un protocolo de mensajería estandarizado que utiliza XML para el intercambio de datos. A diferencia de REST, donde se configuran manualmente los métodos HTTP, los encabezados, las rutas y el cuerpo de la solicitud, los servicios web SOAP se describen mediante un archivo WSDL (Web Services Description Language). El WSDL define las operaciones disponibles, sus parámetros y el formato de los datos, por lo que el Workflow Designer recupera esta información automáticamente y la presenta como opciones seleccionables.
Tras seleccionar Servicio web SOAP en la pestaña Método, haga clic en Definir servicio web para abrir el panel de configuración:
Dirección: seleccione el servicio web
Antes de poder utilizar un servicio web SOAP en un flujo de trabajo, debe estar registrado en Configuraciones de DocuWare > Servicios web. Solo aparecen en esta sección los servicios registrados.
Todos los servicios web SOAP instalados en su organización DocuWare y a los que tiene permisos figuran en la sección General > Dirección.
Servicio web definido: seleccione el servicio web SOAP que desea invocar. Cada servicio registrado apunta a un endpoint WSDL específico que describe las operaciones y las estructuras de datos que ofrece el servicio.
URL del servicio web: la URL del endpoint WSDL del servicio seleccionado. Este campo se rellena automáticamente en función de la selección en Servicio web definido y es de solo lectura.
Para cambiar la URL, actualice el registro del servicio web en Configuraciones de DocuWare > Servicios web.
Método: elegir la operación
La lista desplegable Método muestra todas las operaciones expuestas por el servicio web SOAP seleccionado. Estas operaciones se recuperan automáticamente a partir de la definición WSDL del servicio.
Seleccione la operación que el flujo de trabajo debe ejecutar. En este ejemplo se selecciona el método «DeleteUnsignedDocument», una operación proporcionada por el servicio de firma que elimina un documento sin firmar. Una vez seleccionado un método, la sección Parámetros que se muestra debajo se actualiza automáticamente para mostrar los parámetros de entrada que requiere esa operación.
Parámetros: definir la solicitud HTTP
La sección Parámetros muestra los datos de entrada que requiere el método seleccionado. Estos parámetros están definidos en el WSDL y aparecen automáticamente: no es necesario añadirlos ni eliminarlos manualmente. Cada parámetro tiene un nombre, un tipo de datos y campos para configurar:
Tipo de origen: determina de dónde procede el valor. Están disponibles los siguientes orígenes:
Índice de documento: un valor de campo de índice del documento que se encuentra actualmente en el flujo de trabajo.
Valor fijo: un valor estático que se introduce directamente.
Variable global: una variable del flujo de trabajo que puede establecerse y modificarse durante la ejecución del flujo de trabajo.
Variable de sistema: un valor predefinido proporcionado por DocuWare, como el GUID del archivador o el ID del documento.
Valor: el campo, la variable o el valor fijo específico que se va a transferir. Los valores disponibles en la lista desplegable dependen del tipo de origen seleccionado.
En el ejemplo de la captura de pantalla anterior, el método «DeleteUnsignedDocument» requiere tres parámetros:
DocId: asignado al ID del documento procedente del índice de documento)
FileCabinetId: asignado a la variable de sistema GUID del archivador,
Token: asignado a una variable global.
Asignación de datos: utilizar los datos de la respuesta en el flujo de trabajo
Tras la ejecución, el servicio web SOAP devuelve una respuesta con los datos del resultado. La sección Asignación de datos le permite poner estos datos a disposición del flujo de trabajo asignando los campos de la respuesta a variables globales.
La estructura de la respuesta la determina el propio servicio web SOAP y se muestra automáticamente como un árbol contraíble. Cada campo muestra su nombre y su tipo de datos. Usted no configura la estructura: solo decide qué campos capturar.
Para asignar un valor, seleccione una variable global para el campo de respuesta que desee utilizar. Los campos que se dejen sin asignar se ignoran. La asignación se produce automáticamente en tiempo de ejecución: cada vez que el flujo de trabajo ejecuta esta actividad, los valores de la respuesta se escriben en las variables globales asignadas. Estas variables pueden utilizarse luego en pasos posteriores del flujo de trabajo, por ejemplo, en condiciones, notificaciones u otras actividades.
A diferencia de los servicios web REST, donde los datos de respuesta pueden asignarse tanto a variables globales como a campos de índice de documento, la asignación de datos SOAP admite únicamente variables globales.
En el ejemplo de la captura de pantalla, el método «DeleteUnsignedDocument» devuelve un «DeleteUnsignedDocumentResult» que contiene un campo «Message» de tipo cadena. Este campo podría asignarse a una variable global para capturar un mensaje de confirmación o de error del servicio de firma.
Control de errores
Cambie a la pestaña Errores para configurar cómo debe continuar el flujo de trabajo si la llamada al servicio web falla. Si, por ejemplo, el servicio web externo no está disponible, puede configurar el flujo de trabajo para que dirija el documento a otra acción automatizada, como enviar una notificación por correo electrónico que solicite introducir manualmente la información que falta.
Elija una de las siguientes opciones:
Sin control de errores: esta opción está activada por defecto.
Reiniciar flujo de trabajo: el documento se enruta automáticamente desde el principio a través de los pasos del flujo de trabajo.
Finalizar flujo de trabajo: el documento se enruta automáticamente al final del flujo de trabajo. Todos los cambios realizados hasta este punto se conservan.
Ir al paso: esta opción añade una salida Error a la actividad Asignar datos. Conéctela con otra actividad para enrutar el documento del flujo de trabajo manualmente.