Trulioo GlobalGateway v1.0

This package provides capabilities that extend the Avoka Transact platform for users wishing to perform real-time identity verification of individuals using the Trulioo GlobalGateway service. Please note this service only provides the data Identity check and doesn't support for the document verification.


Clients must ensure they are appropriately licenses in order to use this package. Organisations who wish to use this package are required to establish a commercial relationship with the 3rd party directly.


This package has the following compatibility requirements:

Transact Manager5.1.4 or above
Transact Maestro5.0.14 or above
Truolioo GlobalGateway API Versionv1

Installation Instructions

To install this package please walk through the following proceedure:

  1. Unzip the package to a directory on your computer
  2. Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
  3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
  4. Configure any required Service Connections. These requirements can be found at the bottom of this document or in the Help Doc for each of the imported services.

    Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.

  5. Import each archive found in the libraries folder to Maestro.

    Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.

Usage Instructions

Use the following procedure to configure Trulioo GlobalGateway in your form:

  • Add the Trulioo GlobalGateway Verify component onto your page.
  • Select the Trulioo GlobalGateway Verify component and on the Properties tab select the Input Data section. In Global Gateway Input Fields, map all required fields into the input data maps.
  • In the Rules section, add any processing rules to handle On GlobalGateway Verified and On GlobalGateway Verify Failed events.

Multiple Verification Sessions

If you need to perform id verifications on multiple individuals in a single transaction you will need to add an instance of the Trulioo GlobalGateway Verify component for each individual and specify a Role Identifier (found under Options on the Properties panel) for each instance. For example, if your form supports 2 applicants you would specify a Role Identifier of Applicant1 and Applicant2 respectively. This will ensure that the sessions do not interfere with each other.

Triggering the Checks

Typically you would trigger the GlobalGateway ID checks before the applicant is presented with the identity verification section of the form. This way, if the applicant is verified successfully on the checks alone, then the identity verification section can be excluded from the applicant experience.

You can add the following call to a rule in your form to trigger the checks automatically at an appropriate time:

Form.fireRule("click" ,"verifyButton" , data);
where verifyButton is the ID of the Verify button located in the Trulioo GlobalGateway Verify component.

HTTP Audit Logging

For audit purposes the package provides a HTTP Audit feature that records information about each HTTP request call made in the execution of a service. If this feature is enabled at the service level, HTTP request and response information will be logged to a submission property on the transaction for which the request was made. The name of this submission property can be customized to suit your needs.

The audit information will be stored in the submission property as a JSON array with a structure as follows:

        "serviceName": "TruliooIdv",
        "executionTimestamp": "2017-08-16 17:43:58 AEST",
        "durationMillis": 147,
        "request": {
            // Request Details
        "reseponse": {
            // Response Details
        "serviceName": "TruliooIdv",
        // Etc...

See the documentation for the Trulioo GlobalGateway - Identity Verification service for information on how to enable this feature.

Tamper Proofing

To help combat fraudulent applications this package includes Trulioo GlobalGateway - Tamper Check Groovy service that checks for data tampering to ensure that the data provided at submission time exactly matches the data used to complete the identity verification. To enable this capability you must add a call to the Trulioo GlobalGateway - Tamper Check groovy service, passing in key identity information attributes at the time of submission. If all provided data exactly matches the original identity this service will return a successful result (true), otherwise a failure will result (false).


  1. Double check the identity data request parameters you want this service to check in Trulioo GlobalGateway - Identity Verification Service parameter: truliooTamperCheckRequestParams. For example, firstName,middleName,lastName,dateOfBirth,buildingNumber,buildingName,unitNumber,streetName,streetType,city,suburb,county,stateProvinceCode,addressCountryCode,postcode,poBox,addressLine1. The name must match the request parameter name that Trulioo GlobalGateway - Identity Verification service accepts.
  2. Write a Submission Completed Processor to call the Trulioo GlobalGateway - Tamper Check Groovy service to check the submission data. Below is an example on how to call the service.
    import com.avoka.core.groovy.GroovyLogger as logger
    import javax.servlet.http.*
    class FluentSubmissionCompletedProcessor {
        // change this value to match role defined in your form
        final static String ROLE_KEY = ''
        // change to your client code
        final static String CLIENT_CODE = 'exchange'
         * Perform submission completed processor service
        void invoke(SvcDef svcDef, Txn txn, HttpServletRequest request, User user) {
            String verifyStatusTxnPropertyName = ROLE_KEY ? "TruliooIdv.${ROLE_KEY}.verifyStatus" : "TruliooIdv.verifyStatus"
            String verifyStatus = txn?.propertyMap?.get(verifyStatusTxnPropertyName)
            List identityData = []
            // get identity data and add to identityData list.
            if (verifyStatus) {
                // call Tamper Check to verify identity data not modified in any way
                // we don't give identityData on purpse cos we want to use xpath defined in form data extract
                Map params = [
                            "task": "check",
                            "roleKey": ROLE_KEY,
                            "identityData": identityData,
                            "txn": txn
                    // calling tamper check groovy service
                    boolean success = new GroovyServiceInvoker()
                            .setServiceName('Trulioo GlobalGateway - Tamper Check')
       "Tamper Check result=$success"
                if (success==false) {
                    throw new Exception("Tamper Check failed. Identity data has been tampered!")
            } else {
       "Identity data is not verified by third party service yet. Skip tamper check."
  3. In "Form Version" - "Services" section in published form, select the "Submission Completed Processor" above.
  4. At runtime, Tamper check will be performed after form submitted. And result will be recorded as a submission property "TruliooIdv.roleName.identityDataTamperCheck" with possible values [passed | failed] to indicate the check result.

Note: you need to manually add this call to your post submit processing functions in order to utilise this feature.

Release Notes

Version 1.0 Sep , 2017

  • Baseline release.

Maestro Assets

Trulioo GlobalGateway Verify Library: exchange.trulioo.globalgateway Category: Trulioo

Facilitates integration of Trulioo GlobalGateway into form designs

Service Calls

Rule Templates

You may add your own logic to handle the following rule types triggered by this component:

  • On GlobalGateway Verified : Gets executed when the identity verification is successful and complete
  • On GlobalGateway Verify Failed : Gets executed upon identity verification terminal failure where the individual could not complete the verification requirements
  • On GlobalGateway Data Error : Gets executed upon data error
  • On GlobalGateway System Error : Gets executed upon system error


Property Category Description Type Default
GlobalGateway Input Fields Input Data

Defines input mappings for the person data collected elsewhere in the form.

isoLatin1Name is expected to be full name in ISO Latin-1 character set. It's used for data sources that require the person’s name in ISO Latin-1 format.

Field Refs:

  • firstName : First Name Field
  • lastName : Last Name Field
  • middleName : Middle Name Field
  • secondSurname : Second Surname Field
  • isoLatin1Name : ISO Latin1 Name Field
  • dateOfBirth : Date Of Birth Date Field (YYYY-MM-DD)
  • minimumAge : Minimum Age Field
  • gender : Gender Field
  • telephone : Telephone Field
  • mobilePhone : Mobile Phone Field
  • telephone2 : Alternative Telephone/Mobile Field
  • email : Email Field
  • buildingNumber : Building Number Field
  • buildingName : Building Name Field
  • unitNumber : Unit Number Field
  • streetName : Street Name Field
  • streetType : Street Type Field
  • city : City Field
  • suburb : Suburb Field
  • county : County Field
  • stateProvinceCode : State/Province Code Field
  • addressCountryCode : Address Country Code Field
  • postcode : Postcode Field
  • poBox : PO BOX Field
  • addressLine1 : Address Line 1 Field (Combined Address)
  • countryCode : Country Code Field (Two-letter Alpha Code)
  • nationalIdType : National ID Type (NationalID, Health, SocialService)
  • nationalIdNumber : National ID Number
Role Identifier Options

If you have multiple instance of this block, you need to give each one a unique role name here so that server can support multiple verification instance.



Trulioo GlobalGateway - Get Country Codes v1
Provides Trulioo GlobalGateway Identity Verification get country codes service. There is no request parameters needed for this service. This service retrieves all the countries that are available to perform a verification.

Service Connection


Module Compatibility
Manager 5.1.4

Service Parameters

Name Description Required Default
truliooConfigurationName Indicate the configuration used for the GlobalGateway. Yes Identity Verification


Name Description
countryCodes List of Two letter Country Codes that currently supported for GlobalGateway ID verification.
executionStatus The status of the service execution [ SUCCESS | SYSTEM_ERROR ]. Successful execution will be denoted by a SUCCESS value. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
Trulioo GlobalGateway - Identity Verification v1
Provides Trulioo GlobalGateway Identity Verification service. This service only provides the data Identity check and doesn't support for the document verification.

Prevent Multiple Verification Attempt

When service parameter "preventMultiAttempt" set to true, it will prevent following verification request if any previous verification is FAILED in the same txn. If this is the case, it will not call Trulioo GlobalGateway IDV web service, instead, will return FAILED response immediately. On TM server it will also write submission property "TruliooIdv.(roleName.)multipleVerifyAfterFail"="true" in current txn.

There is also another service parameter maxAttemptNumber when set to a positive number, it will control the maximum number an applicant can perform the Trulioo GlobalGateway Idv service in the same transaction and returns DATA_ERROR when max attempt exceeded with errorCode: EXCEEDED_NUMBER_OF_ATTEMPTS. Its default value is -1 which means no restriction. If this parameter is set to positive number, it will also include The number of attempts left for calling this service in result JSON.

Service Connection


Module Compatibility
Manager 5.1.4

Service Parameters

Name Description Required Default
truliooCleansedAddress Set to true if you want to receive address cleanse information, This will only change the response if you have address cleansing enabled for the country you are querying for. No true
truliooConfigurationName Indicate the configuration used for the verification. Yes Identity Verification
truliooVerboseMode Verbose Mode Output Flag. No true
truliooDataErrorMap A set of error codes that belong to data error and related error messages. No 1001:Missing Required Field,1004:State not supported (AU driver licence),1005:Missing Consent - consent not sent for the source,3005:Missing Address Info
truliooTamperCheckRequestParams Request parameter names separated by comma that should not be changed once verified. No firstName,middleName,lastName,dateOfBirth,buildingNumber,buildingName,unitNumber,streetName,streetType,city,suburb,county,stateProvinceCode,addressCountryCode,postcode,poBox,addressLine1
enableHttpAudit With HTTP auditing enabled, details about each HTTP request (including request and response data) are stored in a submission property as a JSON array against the relevant transaction. No false
httpAuditPropertyName Specify the name of the HTTP audit submission property to receive the audit information. No httpAudit
preventMultiAttempt Prevent multiple verification attempt. If true, will send failed response directly if failed before in same txn. No false
recordResponse Controls whether or not to record the entire response payload from Trulioo as a submission property, useful if there is a requirement for the downstream system to receive this information. No false
maxAttemptNumber Max number that allowed to initiate Au10tix ID verification in a single session for each applicant. -1 means no limit. Yes -1


Name Description Required
countryCode The country code for which the verification needs to be performed. Two-letter alpha code for the country for which the verification needs to be performed. Call configuration/v1/countrycodes/{configurationname} to get the countries that are valid for you. Yes
applicantRole The Applicant role for distinguish different applicants request in the same session. No
Personal Details Inputs:
  • firstName
  • middleName
  • lastName
  • secondSurname
  • isoLatin1Name
  • dateOfBirth
  • minimumAge
  • gender
  • telephone
  • telephone2
  • mobilePhone
  • email
  • buildingNumber
  • buildingName
  • unitNumber
  • streetName
  • streetType
  • city
  • suburb
  • county
  • stateProvinceCode
  • addressCountryCode
  • postcode
  • poBox
  • addressLine1
Personal details of the individual being identified.

Date of birth is expected to be received in Avoka standard format (yyyy-MM-dd) E.g. 2016-07-21.

Gender is expected to be received from Avoka gender field format (M/F)

isoLatin1Name is expected to be full name in ISO Latin-1 character set. It's used for data sources that require the person’s name in ISO Latin-1 format.

Trulioo GlobalGateway - Tamper Check v1
This service checks the supplied identity data against the previously stored data to ensure it has not been tampered with since the ID verification was completed. It provides two main functions. One is to generate a hashcode based on identity Data and stores it into current submission. This is typically called after a successful ID verification.
The other one is to check if the current identity Data has been tampered in any way. This is done by rehashing the current identity Data and compares it with the hashcode previous stored. This is typically called in a submission complete processor to check if identity Data in submission are the same as the identity Data that has been ID verified.

This service supports identity data check for multiple roles in a single session. For example, you could have identity check for a husband and a wife and have this service check both of them submission data not being tampered.


Module Compatibility
Manager 5.0.4


Name Description Required
task Task to perform with possible values [ store | check ]

store: It generates a hash code based on identity Data provided and stores it into current submission as txn property.

check: It regenerate hash code with current identity Data and compare it with the hash code stored previously in submission.

roleKey Optionally provide a role key to support multiple identity sessions in a single transaction. A typical example would be Applicant1 and Applicant2. No
txn current Txn object Yes
identityData Identity Data (List) to be hashed and stored. (For store task) or to be checked. (For check task) Yes


Name Description
boolean (For store task) return true if hash data has been stored successfully. false otherwise.

Service Connections

The following service connections are used by this package.

Trulioo GlobalGateway
Property Name Description Required
Type HTTP Endpoint Yes
Endpoint Trulioo GlobalGateway web service end point. You only need host name. The service will add context path like '/verifications/v1/verify'
  • Test:
  • Prod:
Make sure you change to correct URL and credential on production before using this service.
Username Username for Trulioo GlobalGateway web service Yes
Password Password for Trulioo GlobalGateway web service Yes