Therefore™ Help

The 'Call Function' task allows customization in Therefore™ Online. It can be used like any other automatic workflow task. When the task is executed, a HTTP(S) POST request will be sent to the specified URL. This ‘Request URL’ is the only mandatory field in the configuration.

The following diagram illustrates how the different components work together.

When the “Call Function” task is executed in the Therefore™ Workflow Engine, a HTTPS POST request is sent to the function. If the call was successful, the called function will be executed and most likely call the Therefore™ Server using the Web API to retrieve documents, index data or other additional information required for its purpose.

The called function can be an Azure function, a Web Service, or any executable that can react to HTTPS POST requests. However, it is required that the called function returns a JSON object that contains “TheError” string and either “TheRoutingDone” bool or “TheRetryAfterMin” integer. If a function was developed by Therefore™, it can be hosted in the Therefore™ Online Azure subscription.

For security reasons, functions developed by customers need to run on their Azure subscription, or on their infrastructure. As shown in the diagram, all the connections between Therefore™ and the called function are just HTTPS POST requests and (Web) API calls. No customer code is directly executed by the server service, nor is any customer code run inside the Therefore™ Online environment. All permission checks apply as usual when making Web API calls. The access token provided with the HTTPS request is limited to the current workflow instance only. Because of this architecture, the workflow customization is secure to be used in Therefore™ Online.

The called function can be an Azure function, a Web service, or any application that is publicly available and can be triggered by an HTTPS request. The only thing mandatory are the following “return parameters” the function needs to send as a JSON response:

•TheError: Mandatory string value. If the string is not empty, it will be displayed in the Workflow history. The instance will be marked as faulty, unless a retry at a later time was requested.

•TheRetryAfterMin: Optional integer value. Can be used to request a retry from Therefore™.

If set to a value greater zero, the ‘Call Function’ task will behave like a ‘Wait’ task and send a new request after the specified amount of minutes has passed (approximately). If “TheError” is set, it will be treated as a warning and will not cause the workflow instance to be marked as faulty.

•TheRoutingDone: Mandatory bool value, unless “TheRetryAfterMin” is specified.

Can be set to ‘true’, to indicate that routing the workflow instance was already done by the function using the “FinishCurrentWorkflowTask” Web API function. If set to ‘false’, Therefore™ will route the workflow instance to the next task. If “TheRetryAfterMin” is specified, the routing will not be done yet, so in that case it’s optional. With every function call, Therefore™ sends the following parameters to the function as JSON with the HTTPS request:

•TheWebAPIUrl: Holds the “Web API URL” server setting, which can be configured in the ‘XML Web Service’ tab or in the advanced settings. This setting will be already configured correctly when using Therefore™ Online, but can be empty if not configured.

•TheTenant: Name of the current tenant. Will be empty if the system does not use multi-tenancy.

•TheAccessToken: A JWT-token that can be used to connect to Therefore™ using the Web API.

The token is configured to give the “$TheWFSystem” user access to the document or case associated with the current workflow instance, as well as access to the current workflow instance and token. With the granted permissions, it is possible to make changes to the associated document, case, or documents associated to the case. The granted permissions also allow routing the workflow instance to a different task. It is not allowed to create new documents or cases, or to run queries. It is also not allowed to delete the main case or document associated to the workflow instance, or the workflow instance itself.

•TheInstanceNo: Instance number of the current workflow instance.

•TheTokenNo: Token number of the current workflow instance.

•TheCaseNo: Case number of the case associated to the workflow instance. This parameter is only available for case-workflows.

•TheDocNo: Document number of the main document associated to the workflow instance. This parameter is only available for document-workflows.

•TheSettings: JSON object (passed as string) of all configured ‘Custom function settings’.

This can be empty or used to pass additional parameters to the called function. Name and value of each setting can be chosen freely, but names need to be unique according to the JSON specification. All values are treated as string values and need to be converted to another type inside the function if required.

If a function key for Azure functions is configured, the HTTPS request will include that key as “x-functions-key” in the request-header.

Any additional information required needs to be retrieved using the Therefore™ Web API. Either by using the provided JWT-token, or by specifying a user name and password if more rights are required. When using Azure functions, credentials can be provided in the application settings as “WebAPIUser” and “WebAPIPassword”. If those settings are missing, the function will use the JWT-token by default.

When writing a function, please keep in mind to send a response in less than 4 minutes, otherwise the function call will time out. Also consider using “TheError” parameter to return any caught exception, to make it easier to track down the issue.

There are almost no restrictions when it comes to customization.

When using Azure functions, there are some restrictions from Azure itself. For example when loading dependencies, due to the PaaS (Platform as a Service) environment or the execution time (230 seconds HTTPS timeout) and other implications that arise from running your code in Azure.

The timeout restriction could be avoided by writing an asynchronous function that sends a retry request to Therefore™. This way, the execution could continue in a separate background task and the outcome/response can be returned to Therefore™ when the next retry request is triggered.

Due to dependency restrictions in Azure, the Therefore™ API cannot be used and the Web API needs to be used instead. This limitation could be avoided by running the HTTPS triggered function on a machine with a Therefore™ installation instead. The only thing required for this to work, is that the machine can be reached from the outside.