Onfido LogoOnfido Logo

Developers

Best practices for building Studio workflows

Introduction

Studio workflows are the backbone of dynamic end-user verification journeys. Workflows can be created and implemented in minutes through the Dashboard using the Workflow Builder – our no-code, drag and drop orchestration interface.

And while the Workflow Builder allows you to build, maintain and update workflows seamlessly without the need for developer involvement, there are some pitfalls that should be avoided when designing workflows. This guide highlights some key considerations to help you construct the best possible workflows to suit your business needs.

Managing workflow branches and joins

The path of a Studio workflow can branch out for one of two reasons:

  • a condition defined in a logic task
  • parallelism - splitting the path into multiple branches to allow multiple workflow tasks to execute simultaneously

In most cases, a branch will never rejoin the path of a Studio workflow. For example, when the condition of a logic task is used to decide the outcome of a workflow run based on the results of a report. The final nodes will mark the end of the workflow run and won't ever rejoin.

There will be certain scenarios, however, when after a path branches out, it may again come together in a join. For example, the condition of a logic task might be used to determine which report variant is applied for different end-users. Or when you want to execute multiple workflow tasks simultaneously (parallelism) in order to reduce the turnaround time (TaT) of a workflow run.

In both cases, we will see a join of the diverging branches as the workflow path continues.

Joins and their behaviour

The behaviour of a join along a workflow path differs depending on what triggered the branching in the first place. To understand how joins work in a Studio workflow, let's look at a few examples.

When a workflow path splits because of a condition in a logic task, only one branch will execute based the outcome of the condition. Once the logic has decided on which branch to take, it will rejoin the path and the workflow will continue.

On the other hand, when a workflow path splits in order to run multiple workflow tasks simultaneously, all branches are intended to execute. In this case, the workflow is designed to wait until all branches have executed and rejoined the path before proceeding.

As a result of these two possible join behaviours, there are certain scenarios where parallel branches can result in a workflow deadlock, as a join point may be waiting for a branch that will never complete. Please refer to the next section to learn how to avoid this.

Workflow deadlocks and how they can be avoided

There are some workflow topologies where Studio cannot infer the behaviour of a join at build time, resulting in a deadlock blocking the workflow path from proceeding to completion.

In the first example shown below, the condition of a logic task leads to two branches: the left branch runs a Document Capture task, while the right branch runs both the Document Capture task and a Face Capture: photo task in parallel, before rejoining the workflow path.

If the left path executes, only the Document capture task is expected to run, so the workflow will proceed when the path rejoins. If, however, the right path is taken, both the Document capture task and the Face capture: photo task run in parallel, so the join is expected to wait for both tasks to execute.

Since the join behaviour would depend on the runtime of the workflow, the workflow builder takes the conservative approach of setting the join to wait for both branches. This causes a deadlock if the left path of the condition is taken, as the join waits indefinitely for the Face capture: photo task to execute, which never happens.

To prevent deadlocks when building workflows, it's best to:

Avoid branches from a condition connecting with each other before they are fully joined

Workflow deadlock scenario one

Avoid connecting branches of different conditions that haven't been joined

Workflow deadlock scenario two

Avoid connecting branches of parallel paths prior to having been merged

Workflow deadlock scenario three

Use parallel tasks to reduce turnaround time

To reduce the turnaround time (TaT) of workflow executions, we recommend the usage of parallel tasks for verifications, whenever possible.

Parallel verification tasks are distributed across our systems, meaning that the execution time of the parallel block will be bounded by the time of the longest task, instead of the sum of the individual time of execution of each task.

Although the Workflow Builder allows you to arrange tasks that require applicant interaction (such as Document Capture or Face Capture tasks) in parallel, this has no practical effect since they will be presented to the applicant one at a time. Hence, there is no benefit in parallelising these tasks.

However, you can parallelise the execution of an applicant task with a verification task if you have already previously captured all the information for the verification to run.

Avoid adding manual review tasks between applicant tasks

Manual review tasks require an operator to go through the Studio Dashboard and make a decision. Since this may take some time, if it is performed between tasks that require applicant interaction (such as Document Capture or Face Capture tasks), the applicant will remain waiting in the verification flow until the manual review is finished. As such, it is recommended to avoid adding manual review tasks between applicant tasks to prevent applicant dropoff.

Subscribe to webhooks to obtain report results

It is recommended that you subscribe to our webhooks in order to be notified of the results of workflow runs. Rather than polling our system to obtain results, which could result in API throttling, we provide a range of webhook events to alert you of changes in the status of your resources.

Avoid using the advanced condition editor

Studio provides the advanced condition editor to allow heavy optimisers that have very specific needs to fine tune their conditions by having access to the raw expressions. However, using the advanced editor is error prone as it doesn't provide any static validation about the expression correctness.

Always try to model your conditions using the regular editor and if you have a more specific need, seek assistance from your Customer Support Manager.

If you must use the advanced editor, it is recommended that you start with the basic editor and setup the basic structure of your expression. After that, switch to the advanced editor to understand how expressions are built, and edit from there.

Please note that once you start editing a condition on the advanced editor, you can no longer go back to the regular editor on that condition node.

Maintain a one-to-one mapping of applicant to applicant ID

An applicant ID is the unique identifier associated with an end user being verified by our systems.

It is recommended that you maintain a one-to-one mapping of applicant to applicant ID to ensure that all verifications for a single end user are consistently linked to the same unique identifier. If you need the same individual to go through multiple workflow journeys, you should therefore reuse the ID returned in the initial applicant creation response object in the applicant_id field.

Maintaining a one-to-one mapping of applicant to applicant ID also allows end users to resume a workflow at the point where they might have dropped off, as long as the task / workflow run has not timed out.

Autofill tasks and data extraction

Autofill provides a fully automated data extraction and classification solution for identity documents.

Autofill is designed as a triaging tool, a first layer for filtering certain data, classifying identity documents and funnelling customers along the most appropriate verification flow.

It is recommended that Autofill only be used for identity document classification and light data and document verification. Autofill should not be used for critical decision making or instances where a high level of accuracy is required.

From a Studio workflow perspective, an Autofill task is dependent on the data it extracts from a document. As such, an Autofill task must always be included along a path that follows a Document Capture task.

Fuzzy matching for Document Report tasks

Fuzzy matching allows for greater flexibility during data comparison, catering for potential discrepancies (for example, when an applicant uses their middle or spouse's name, or there has been an extraction error).

Exact comparison, by contrast, requires a precise match for all fields and could increase false rejection rates, particularly for Known Faces Reports.

It is therefore recommended that you enable fuzzy comparison when configuring Document Report tasks.