Therefore™ Help

La tarea 'Función de llamada' permite personalizar Therefore™ Online. Puede utilizarse como cualquier otra tarea de flujo de trabajo automático. Cuando la tarea se ejecuta, se enviará una solicitud HTTP(S) POST al URL especificado. Este ‘URL de solicitud’ es el único campo obligatorio de la configuración.

El diagrama siguiente ilustra el comportamiento de los distintos componentes.

Cuando se ejecuta la tarea “Función de llamada” en el motor de flujos de trabajo de Therefore™, se envía una solicitud HTTPS POST a la función. Si la llamada es correcta, la función llamada se ejecutará y muy probablemente llamará al servidor de Therefore™ utilizando la API web para recuperar documentos, datos de índice y otra información adicional necesaria para su propósito.

La función llamada puede ser una función de Azure, un servicio web o cualquier ejecutable que pueda reaccionar a solicitudes HTTPS POST. Sin embargo, es necesario que la función llamada devuelva un objeto JSON que contenga la cadena “TheError” y un valor booleano “TheRoutingDone” o un entero “TheRetryAfterMin”. Si la función fue desarrollada por Therefore™, se puede hospedar en la suscripción a Azure de Therefore™ Online.

Por motivos de seguridad, las funciones desarrolladas por clientes deben ejecutarse en su suscripción a Azure o en su infraestructura. Como se muestra en el diagrama, todas las conexiones entre Therefore™ y la función llamada son solo solicitudes HTTPS POST y llamadas a la API (web). El servicio del servidor no ejecuta directamente código del cliente y tampoco se ejecuta código del cliente en el entorno de Therefore™ Online. Todas las comprobaciones de permisos se aplican de la forma habitual cuando se realizan llamadas a la API web. El token de acceso suministrado con la solicitud HTTPS se limita a la instancia de flujo de trabajo actual. Dada esta arquitectura, es seguro utilizar personalización de flujos de trabajo en Therefore™ Online.

La función llamada puede ser una función de Azure, un servicio web o cualquier aplicación que esté disponible públicamente y que pueda desencadenarse mediante una solicitud HTTPS POST. Lo único obligatorio son los siguientes "parámetros de devolución" que la función debe enviar como respuesta JSON:

•TheError: Valor de cadena obligatorio. Si la cadena no está vacía, se mostrará en el historial del flujo de trabajo. La instancia se marcará con error, a menos que se haya solicitado un reintento en un momento posterior.

•TheRetryAfterMin: Valor de entero opcional. Puede emplearse para solicitar un reintento desde Therefore™.

Si se establece con un valor mayor que cero, la tarea ‘Función de llamada’ se comportará como una tarea ‘Espera’ y enviará una nueva solicitud cuando transcurra un número especificado de minutos (aproximadamente). Si se establece “TheError”, se tratará como una advertencia y la instancia de flujo de trabajo no se marcará con error.

•TheRoutingDone: Valor booleano obligatorio, a menos que se especifique «TheRetryAfterMin».

Puede establecerse como ‘true’ para indicar que ya ha realizado el enrutamiento de la instancia de flujo de trabajo utilizando la función de la API web «FinishCurrentWorkflowTask». Si se establece como ‘false’, Therefore™ enrutará la instancia de flujo de trabajo a la siguiente tarea. Si se especifica «TheRetryAfterMin», aún no se realizará el enrutamiento, por lo que en ese caso es opcional. Con cada llamada de función, Therefore™ envía los siguientes parámetros a la función como JSON con la solicitud HTTPS:

•TheWebAPIUrl: Mantiene el ajuste del servidor "URL de API web", que se puede configurar en la pestaña ‘XML Web Service’ o en la configuración avanzada. Este ajuste ya estará configurado correctamente cuando se utiliza Therefore™ Online, pero puede estar vacío si no se configura.

•TheTenant: Nombre del inquilino actual. Estará vacío si el sistema no utiliza multiinquilino.

•TheAccessToken: JWT-token que puede utilizarse para conectar con Therefore™ mediante la API.

El token se configura para dar al usuario “$TheWFSystem” acceso al documento o expediente asociado con la instancia de flujo de trabajo actual como acceso al token y la instancia de flujo de trabajo actuales. Con los permisos concedidos es posible realizar cambios en el documento asociado, el expediente o los documentos asociados al expediente. Los permisos concedidos también deben permitir el enrutamiento de la instancias de flujo de trabajo a otra tarea. No se permite crear nuevos documentos o expedientes, ni ejecutar consultas. Tampoco se permite eliminar el expediente o el documento principal asociado con la instancias de flujo de trabajo o la propia instancias de flujo de trabajo.

•TheInstanceNo: Número de instancia de la instancia de flujo de trabajo actual.

•TheTokenNo: Número de token de la instancia de flujo de trabajo actual.

•TheCaseNo: Número de expediente del expediente asociado con la instancia de flujo de trabajo. Este parámetro solo está disponible para flujos de trabajo de expediente.

•TheDocNo: Número de documento del documento principal asociado con la instancia de flujo de trabajo. Este parámetro solo está disponible para flujos de trabajo de documento.

•TheSettings: Objeto JSON (pasado como cadena) de todas las ‘Configuraciones de función personalizadas’ establecidas.

Puede estar vacío o utilizarse para pasar parámetros adicionales a la función llamada. El nombre y el valor de cada ajuste puede elegirse libremente, pero los nombres deben ser únicos de acuerdo con la especificación JSON. Todos los valores se tratan como valores de cadena y deben convertirse en otro tipo dentro de la función si es necesario.

Si está configurada una clave de función para funciones de Azure, la solicitud HTTPS incluirá esa clave como “x-functions-key” en el encabezado de solicitud.

La información adicional necesaria deberá recuperarse utilizando la API web de Therefore™. Bien utilizando el JWT-token suministrado o especificando un nombre de usuario y contraseña si se requieren más derechos. Cuando se utilizan funciones de Azure, se pueden facilitar credenciales en la configuración de la aplicación como “WebAPIUser” y “WebAPIPassword”. Si falta esa configuración, la función utilizará el JWT-token de forma predeterminada.

Cuando escriba una función, no olvide enviar una respuesta en menos de 4 minutos. En caso contrario, terminará el tiempo de espera de la llamada a la función. Asimismo, puede utilizar el parámetro “TheError” para devolver excepciones capturadas, a fin de facilitar el seguimiento del problema.

Casi no hay restricciones en lo que se refiere a personalización.

Cuando utiliza funciones de Azure hay algunas restricciones que proceden de Azure directamente. Por ejemplo, al cargar dependencias, debido al entorno PaaS (Plataforma como servicio) o el tiempo de ejecución (230 segundos, tiempo de espera HTTPS) y otras implicaciones que se derivan de la ejecución de código en Azure.

La restricción de tiempo de espera se puede evitar escribiendo una función asincrónica que envía una solicitud de reintento a Therefore™. De este modo, la ejecución puede continuar en una tarea de fondo aparte y el resultado/respuesta se puede devolver a Therefore™ cuando se desencadena la siguiente solicitud de reintento.

Debido a las restricciones de dependencia de Azure no se puede utilizar la API Therefore™ API y es necesario recurrir a la API web. Esta limitación podría evitarse ejecutando la función desencadenada HTTPS en un equipo con una instalación de Therefore™. Lo único que se necesita para que esto funcione es que se pueda acceder al equipo desde el exterior.