External Source Face Matching

Introduction

TrustX enables users to match live face images against an uploaded face image by utilizing External Source Face Matching. The user will be able to generate an upload URL from a start process instance invocation that can be used by an external application to upload a face image. Alternatively, this can be completed by generating the face upload URL from the 'External Source Face Upload v1' activity and preforming the upload in a custom page or cloud function.

This document will describe both use cases to implement this flow:

1. External Upload Via Process Definition
2. External Upload Via Starting Process Instance

External Upload Via Process Definition

This section will discuss configuring a Process Definition where the external face image is uploaded from a cloud function before performing a face match against the live image captured during the Process Instance.

Step One - Create a Cloud Function

Before creating the Process Definition, a custom page will be configured that handles the upload process of the external image.

1. A new custom page can be created by navigating to Cloud Functions in the Backoffice.
2. For more information, see the Cloud Functions Guide.
3. This example will demonstrate a simple implementation of a cloud function.

Example Cloud Function:

import json

import requests

from io import BytesIO

​

from cfresults import Outcome, OverallResult, OverallResultEncoder, Result, JSONEncoder

​

class ResultEncoder(JSONEncoder):

        def default(self, o):

            return o.__dict__

​

cfResults = {}

​

#downloading a static image, could be fetched dynmaically...

image_url = "https://somehost.com/myimage.jpeg"

​

#take headers from varaibles setup in Cloud Function

# activity 

presigned_url = params["vars"]["uploadURL"]

headers = params["vars"]["uploadURL_headers"]

​

#download the image

response = requests.get(image_url)

if response.status_code == 200:

    image_data = BytesIO(response.content)  # Convert to binary stream

    #upload the image to the presigned URL using the URL & Headers.

    upload_response = requests.put(presigned_url, data=image_data.getvalue(), headers=headers)

    if upload_response.status_code == 200:

      print("Upload successful!")

    else:

      # may want to put in different error handling depending on use case

      print(f"Upload failed! Status: {upload_response.status_code}, Response: {upload_response.text}")

else:

    # may want to put in different error handling depending on use case

    print(f"Failed to download image, status code: {response.status_code}")

​

overallOutcome = Outcome.APPROVE

overallResult = OverallResult(overallOutcome, cfResults)

​

# set the results back for the cloud function

cfResults = json.loads(OverallResultEncoder().encode(overallResult))

​

​

# we must use the variable name.

results['cfResults'] = json.loads(ResultEncoder().encode(Result(

        params,

        Outcome.APPROVE,

        cfResults,

    )))

• In the example above, the presigned_url variable is populated with the 'Output Variable' input parameter value of the 'External Source Face Upload v1' activity, which will be configured within Step Two of this document.
• The image is uploaded to the presigned URL using the URL and headers of the activity: requests.put(presigned_url_,_``data=image_data.getvalue(), headers=headers)

Step Two - Configure External Source Upload Activity

1. In a new Process Definition, add an 'External Source Face Upload v1' activity at the beginning of the Process Definition. The 'Output Variable' input parameter will be used as the upload URL of the external face image within the custom page.

2. Click the 'External Source Face Upload v1' activity to open the right-most contextual menu and expand the Input Parameters to see the available 'Output Variable'.

For more information on the available input parameters, see Face Activity Parameters guide.

Step Three - Configure Cloud Function Activity

1. After the 'External Source Face Upload v1' activity, add a 'Cloud Function V2' activity and connect them using a sequence flow arrow.

2. Select the 'Execute Cloud Function v2' activity to open the right-most contextual menu and configure the activity to use the custom page created in Step One.
3. Set the following input parameters:
   1. Function Name - Represents the name of the cloud function created in Step One.
   2. Function Version - The version of the cloud function.
   3. Process Variables - Add two process variables to the list: uploadURL_headers and uploadURL

Step Four - Capture Face Image

1. This step will handle capturing a live face image that will be used to compare to the uploaded face.
2. Add a 'Capture Face Image' activity to the Process Designer and connect the activity to the 'Execute Cloud Function v2' activity using a sequence flow arrow.

Step Five - Perform Match

1. To match a live image against an external source, the 'External Source Face Match v1' activity can be added to the Process Definition after the 'Capture Face Image' activity.

2. It is important that this activity is included after both the external source image and live image are available.
3. The activity provides three error boundary events for the following scenarios:
   1. Exceed face match count - This error is thrown when the number of failed match attempts exceeds the value set within the 'Max Attempts' input parameter.
   2. Failed face to face match - The error is thrown when the face matching has failed.
   3. Failed face template generation - This error is thrown if the face template generation has failed.

Step Six - Add a Simple Decider

1. Add a 'Simple Decider' activity and connect to the 'External Source Face Match v1' activity using a sequence flow arrow. This will generate a final decision for the Process Instance based on the result of the external source face match.

2. In the example above, all previous error boundary events have been connected to the 'Simple Decider' activity.

External Upload Via Starting Process Instance

This use case involves utilizing the TrustX API to generate a pre-signed URL upon creating the Process Instance. This pre-signed URL can then be used by an external application for handling face upload.

This use case can be achieved with minimal configuration of a Process Definition, only requiring an 'External Source Face Match v1' and 'Simple Decider' activity. Note that this example does not incorporate quality checks and is recommended for reporting purposes.

Step One - Configure Process Definition

For this Process Definition, an 'External Source Face Match v1' and 'Simple Decider' activity are all that is required to complete the configuration. Optional face quality checks can be performed if required.

1. Create a new Process Definition and include a 'Start' activity.
2. From the 'Start' activity, add an 'External Source Face Match v1' activity and connect them using a sequence flow arrow.

3. Add the 'Simple Decider' activity and connect the activity to the 'External Source Face Match v1' activity using a sequence flow arrow.
4. Finally, end the process by adding an 'End' event activity.

Step Two - Create a Process Token

When creating a Process Token, a processInstanceInit parameter can be specified, which includes the external source to be uploaded. Currently, only faceUploads are supported.

In the example below, two face images are added as parameters to the token. The xface1 can be used as an external face image, while the face1 can be used for capturing a live image.

Example:

POST https://{{tenantid}}.oak.trustx-dev.com/api/process-manager/processTokens

Content-Type: application/json

X-API-Key: {{apiKey}}

​

{

    "name": "mytoken-{{$guid}}",

    "description": "my token desc",

    "status": "ACTIVE",

    "type": "UNLIMITED",

    "processDefnName": "{{processDefinitionName}}",

    "processDefnVersion": "{{processDefinitionVersion}}",

    "uiUrl": "https://www.google.com",

    "parameters": {

        "lastName": "corcoran",

        "email": "acorcoran@daon.com",

        "phoneNumber": "+353876182287",

        "referenceID": "asdasd"

    },

    "processInstanceInit": {

        "externalSources": {

            "faceUploads": {

                "xface1": {

                    "imageFormat": "JPEG"

                },

                "face1": {

                    "imageFormat": "JPEG"

                }

            }

        }

    }

}

Step Three - Create Process Instance

Creating the Process Instance utilizing the token created in Step Two will generate an uploadUrl as part of the response. This can be used in an external application to handle uploading the external source image.

Example Request:

POST https://{{tenantid}}.oak.trustx-dev.com/api/process-manager/processInstances/create?pt={{ptoken}}

Content-Type: application/json

X-API-Key: {{apiKey}}

Example Response:

{

    "redirectUrl": "https://www.google.com?ps=https%3A%2F%2Fskydev1.oak.trustx-dev.com%2Fapi%2Fprocess-server%2FstartProcess%3Fpi%3DA74JJ3WOYESJ7TNMCXRLA2TI4U",

    "processInstanceId": "A74JJ3WOYESJ7TNMCXRLA2TI4U",

    "externalSources": {

        "faceUploads": {

            "xface1": {

                "imageFormat": "JPEG",

                "captureKey": "1c5797c4-764f-4279-939c-cea4c999b34b",

                "uploadUrl": "...",

                "uploadHeaders": {

                    "x-amz-tagging": "RemoveAfter=30d&RemoveAfterDate=20250308",

                    "x-amz-server-side-encryption-aws-kms-key-id": "2efc4785-51fe-4d45-9a3d-5abf2f1276ea",

                    "Content-Type": "image/jpeg",

                    "x-amz-server-side-encryption": "aws:kms"

                }

            }

          "face1": {

                "imageFormat": "JPEG",

                "captureKey": "1c5797c4-764f-4279-939c-ceo4c999b35d",

                "uploadUrl": "...",

                "uploadHeaders": {

                    "x-amz-tagging": "RemoveAfter=30d&RemoveAfterDate=20250308",

                    "x-amz-server-side-encryption-aws-kms-key-id": "2efc4785-51fe-4d45-9a3d-5abf2f1276io",

                    "Content-Type": "image/jpeg",

                    "x-amz-server-side-encryption": "aws:kms"

                }

            }

        }

    }

}

Viewing Results

Results of a face match can be viewed from the individual Process Instance page in the Backoffice. When two face images have been provided as part of a Process Instance, each image will have its own set of checks displayed under the 'Verification' section.

In the example above, 'xface1' represents the ID of the external face that was uploaded during the Process Instance. This face image was matched against the live face image, 'face2'.

In the 'External Face Match...', the live image will be shown on the left, while the external image will appear on the right.

In the 'Checks' section, quality checks for each face image can be found under 'faceMatches'.