Cloud Functions and Process Definitions

Introduction

This document will cover the necessary steps to create and test a Cloud Function. The example given will be based on using data from a standard process definition such as those provided by process definition templates.

There are a number of steps that should be performed in order to create and use a cloud function. These steps are outlined below.

1. Define your Cloud Function
2. Test & Deploy your Cloud Function
3. Add a Cloud Function to your Process Definition
4. Test your Process Definition

Define your Cloud Function

When defining a cloud function there there 3 pieces of information to provide:

1. Name, this name will be used later when referencing the Cloud Function within a Process Definition.
2. Description, provide some information about the purpose of the cloud function. This will help you or your colleagues to remember the purpose of the cloud function in the future.
3. Function, this is the actual Cloud Function to be executed - i.e. this is where you implement the logic of your cloud function.

Python Environment

The Python environment that a Cloud Function is written in will depend on the activity selected for the Cloud Function.

• Execute Cloud Function v1 - will run Cloud Functions in the Python 3.9 Environment.
• Execute Cloud Function v2 - will run Cloud Functions in the Python 3.9 Environment and Python 3.12 Environment , with the additional libraries to support cryptography operations.
  • Access to the Python 3.12 Environment is provided per tenant. Contact Daon Support to request access.

Anatomy of a Cloud Function

When writing a Cloud Function, like any programming language, there are three points to consider:

1. Inputs i.e. what data is available to the Cloud Function
2. Logic, what logic can be performed within a Cloud Function
3. Output, i.e. what results / data can the Cloud Function return after invocation.

Inputs

A Cloud Function executes in the context of a Process Definition, as such the following data is available to the cloud functions. The Cloud Function can access this data via a dict variable params .(see https://docs.python.org/3.9/library/stdtypes.html#mapping-types-dict)

Inputs - Cloud Secrets

In the example below, we show how to invoke an API which requires authentication using an API Key. The API Key is stored as a Cloud Secret (see Cloud Secrets Guide) which is access by the Cloud Function in order to set the API store in the Cloud Secret as the X-API-Key header.

In the example Cloud Function:

1. The cloud secret is accessed as follows: my_api_key = params["secrets"]["myApiKey"]
2. The HTTP header X-API-Key is set with the value of the Cloud Secret: headers = {"X-API-Key": my_api_key} and the API is invoked.

# Retrive the API Key via Cloud Secrets

​

import urllib

import json

​

# The Params dict is 'injected' into the cloud fuction 

# by TrustX, here we access the 'secrets' value of the dictionary

# and then 

my_api_key = params["secrets"]["myApiKey"]

​

# use  webhook.site for test

url = "https://webhook.site/f60d0723-3a56-42c7-85e1-890176536662"

​

headers = {"X-API-Key": my_api_key, "Content-Type": "application/json"}

​

data = {

    "hello": "world"

}

data = json.dumps(data)

data = data.encode()

​

# Create a custom request with the headers

request = urllib.request.Request(url, headers=headers, data=data)

​

success = False

​

try:

    # Perform the request and get the response

    response = urllib.request.urlopen(request)

​

    if response.getcode() == 200:

        # handle success response e.g.

        success = True

        response = response.read().decode("utf-8")

    else:

        # handle non 200 response e.g.

        success = False

        response = response.read().decode("utf-8")

except urllib.error.HTTPError as e:

    # handle http error

    success = False

except urllib.error.URLError as e:

    # handle URL error

    success = False

Inputs - Session Data

In the example below, we show how to access Session Data via process variables and perform a logic operation on the data. The issued data, such as issued date, of a document is retrieved from the Session Data and some logic is performed to check how old the document is. For general information on Session Data, see the following documents:

• Session Data - An overview on Session Data.
• Session Data Tables - All available Session Data tables and the values available.

In the example Cloud Function:

1. The issued data is accessed as follows: issuedDateISO = params["vars"]["_idDocs"]["doc1"]["currentDocumentCapture"]["processorResults"]["documentProcessorDocInfo"]["issuedDate"]

   1. params["vars"]["_idDocs"]provides access to the _idDocs Session Data process variable. The ["vars"] key is required to access process variables and followed by the name of the process variable to be accessed ["_idDocs"]See _idDocs Session Data Tables for more information.
   2. ["doc1"] refers to the Document Capture that uses the "doc1" name. For more information, see the Document Session Data Tables
   3. "[currentDocumentCapture"]["processorResults"]["documentProcessorDocInfo"]["issuedDate"]is used to obtain the issuedDate from the DocumentCapture Session Data Tables.
      1. ["currentDocumentCapture"] refers to the current captured taken from the ["doc1"]document capture.
      2. ["processorResults"] is a name-value pair representing the map of document capture results. In this example, we refer to ["documentProcessorDocInfo"]where "documentProcessorDocInfo" represents the name and DocumentInfo is the value. This allows access to session data associated with DocumentInfo.
      3. ["issuedDate"]is derived from DocumentInfo and refers to the date the document was issued.

2. The HTTP header X-API-Key is set with the value of the Cloud Secret: headers = {"X-API-Key": my_api_key} and the API is invoked.

# Retrive the issue date via Session Data Process Variable

​

# import some data libraries

from datetime import date

from dateutil import relativedelta

​

issuedDateISO = params["vars"]["_idDocs"]["doc1"]["currentDocumentCapture"]["processorResults"]["documentProcessorDocInfo"]["issuedDate"]

​

#parse the issued date

if issuedDateISO is not None:

  issuedDate = date.fromisoformat(issuedDateISO)

​

today = date.today()

delta = relativedelta.relativedelta(today, issuedDate)

​

tooOld = delta.years >= 10

Note: Entering Process Variables in the Process Designer

Cloud Secrets and Process Variables are not automatically applied to the Cloud Function. The Cloud Secrets and Process Variables must be explicitly declared as part of the Inputs using the Cloud Function Activities Input Parameters.

When entering Process Variables into the Input Parameters of the Cloud Function activity, it is not required to pass the vars key. Only the name of the Process Variable value is required, such as _idDocs.

For example:

Outputs - Process Variables

When writing a cloud function, it is possible to add process variables which can be used to control logic used within the process definition e.g. to us on a gateway to decide if an activity should be executed.

Building on the familiar example above, the example is updated below to set a process variable with an the output tooOld .

Cloud Functions return a dict (see https://docs.python.org/3.9/library/stdtypes.html#mapping-types-dict) named results . By adding a key-value pair to this dict a Process Variable is created that can be used in the Process Definition.

See line 17 below for an example

# Retrive the issue date via Session Data Process Variable

​

# import some data libraries

from datetime import date

from dateutil import relativedelta

​

issuedDateISO = params["vars"]["_idDocs"]["doc1"]["currentDocumentCapture"]["processorResults"]["documentProcessorDocInfo"]["issuedDate"]

​

#parse the issued date

if issuedDateISO is not None:

  issuedDate = date.fromisoformat(issuedDateISO)

​

today = date.today()

delta = relativedelta.relativedelta(today, issuedDate)

​

tooOld = delta.years >= 10

​

results["docTooOld"] = tooOld

Process Variables created by the cloud function can be accessed as follows: ${cloudFunctions.ruleExecutionResults.rule.ruleResults.myVariableName}

e.g. ${cloudFunctions.ruleExecutionResults.rule.ruleResults.docTooOld}

In the example above, the result is a simple type i.e. boolean. Other types may be set such as Strings, Arrays and Dicts.

Outputs - Rule Results

Cloud functions also support the concept of setting outcomes that can impact the overall status of the Process Instance, and are visible when viewing the Process Instance.

Cloud Functions return a 'dict' mapping type (see https://docs.python.org/3.9/library/stdtypes.html#mapping-types-dict) named results . By adding a special key-value pair named cfResult to this dict, a Process Variable is created that can be used in the Process Definition. The results are visible when viewing the Process Instance.

We will build on the example above to demonstrate how to set the overall results:

# Retrive the issue date via Session Data Process Variable

​

# import some data libraries

import json

from datetime import date

from dateutil import relativedelta

from cfresults import Outcome, Result, OverallResult, OverallResultEncoder

​

issuedDateISO = params["vars"]["_idDocs"]["doc1"]["currentDocumentCapture"]["processorResults"]["documentProcessorDocInfo"]["issuedDate"]

​

#parse the issued date

if issuedDateISO is not None:

  issuedDate = date.fromisoformat(issuedDateISO)

​

today = date.today()

delta = relativedelta.relativedelta(today, issuedDate)

​

tooOld = delta.years >= 10

​

# set result

results["docTooOld"] = tooOld

​

# create overallResult

if tooOld:

  docAgeCheckResult = Result(

        "Doc Age Check",

        Outcome.DECLINE,

        "The provided document is too old.",

    )

  overallResult = OverallResult(

     Outcome.DECLINE, {docAgeCheckResult.name:docAgeCheckResult})

else:

    docAgeCheckResult = Result(

        "Doc Age Check",

        Outcome.APPROVE,

        "The document does not meets the min age check.",

    ) 

    overallResult = OverallResult(

       Outcome.APPROVE, {docAgeCheckResult.name:docAgeCheckResult})

​

​

# set the results back for the cloud function & we must use the variable name.

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

results["cfResults"] = cfResults

Line 7: Imports the classes required to set an overall result - Outcome, Result, OverallResult, OverallResultEncoder, see Cloud Function - Helper Classes guide for more information.

Line 23: The decision is made to create a result result of Approve or Decline based on the variable

Line 25: A 'Check Result' is created and stored in the docAgeCheckResult variable where:

• A Name is provided: "Doc Age Check"
• An outcome for the result is provided. In this case: Outcome.DECLINE
• A description for for the Check Result is provided. In this case: "The provided document is too old."

Line 30: An 'Overall Result' is created and stored in the overallResult variable where:

• An overall outcome is provide, in this case Outcome.DECLINE
• A dict of the Check Results is provided that are used to support overall outcome. In this case, there is only one Result Check performed - docAgeCheckResult. When building the dict of Check Result, we provide key-values, we use the name of the Check Result to form the key: docAgeCheckResult.name

Line 32: Deals with the 'else' case for the tooOld variable and sets the Result Check and Overall Result's outcome to Outcome.APPROVE

Line 43: Encodes the overall result as JSON - this is required so that it can be set as part of the result

Line 44: Sets the special result of cfResult to our overall result.

Test & Deploy your Cloud Function

Once you have defined your Cloud Function the next step is to test your Cloud Function. TrustX Cloud Functions can be tested by following these steps:

1. Define your Cloud Function, see Define your Cloud Function
2. Save your Cloud Function, there is not need to deploy yet
3. Supply your test data
4. Execute Test

Once you have executed your test you can review the results and logs.

Choosing Test Environment

Tenants that have access to the Python 3.12 Environment will be able to select which environment the Cloud Function will be executed in.

Select the Python dropdown box to choose between Python 3.9 and Python 3.12.

Test Data Format

Test data is supplied as a JSON document. This JSON document can supply a map of all the data required to test a Cloud Function. The data in the map is keyed as detailed below;

Test Data Examples

Secrets

Cloud Secrets are secret values that can be used to store and send protected data such as API keys. For more information, see Cloud Secrets Guide.

In the example below we provide a secret myApiKey with it corresponding value.

This example can be used to test the above Cloud Function defined in Inputs - Session Data.

{

  "secrets": {

    "myApiKey":"Mkt377hEbE63T5llqFyxThKfCA40sHuX"

  }

}

Vars

This example demonstrates how to provide test data for testing, which requires access to Process Variables. In this instance we are provided data that would be generated after Document Processing - DocumentInfo.

This example can be used to test the above Cloud Function defined in

{

  "vars": {

      "_idDocs": {

          "doc1": {

              "currentDocumentCapture":{

                  "processorResults": {

                      "documentProcessorDocInfo": {

                          "issuedDate":"2010-01-01"

                      }

                  }

              }

          }

      }

  }

}

Adding a Cloud Function to a Process Definition

Now that you have tested your Cloud Function it is time to use the Cloud Function as part of a Process Definition.

1. Save and Deploy your Cloud Function - the Cloud Function is not available to use until it is deployed

2. Navigate to your Process Definition and open the Process Designer

   1. Alternatively create a new Process Definition

3. Click and drag a new Execution Cloud Function or Execute Cloud Function v2 from the left-side actions menu and place it into the ID&V flow.

4. Update the Input Parameters of Execution Cloud Function activity. Click the Execute Cloud Function action to reveal the right-side options menu.

5. Save the Process Definition

Input Parameters

The table below outlines each of the input parameters available when creating a Cloud Function.