Licensing

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 Equifax IDMatrix directly.

Compatibility

This package has the following compatibility requirements:

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.

IdMatrix Verification Rules

Clients wishing to use the IDMatrix service will be required to work with the IDMatrix team to complete a Rules Checklist which will include defining appropriate values for configuration name, client cost centre, IDMatrix service name(s), interactive sources and any other additional modules.

The API integration is set to use the default values but this can be changed in the service parameters of the Equifax IDMatrix - Identity Verification dynamic data service.

Legal Considerations

Clients using electronic identity verification are required to understand the legal considerations of doing so and ensure their legal obligations are being met, such as ensuring the capture of an individuals agreement to the T&Cs prior to running the check.

When using the DVS you are required to explicitly provide consent for each document data source. This package by default provides expressed consent for searching against all data sources. Check idMatrixConsentEnums service parameters in Equifax IDMatrix - Identity Verification. Business Users are required to obtain consent from individuals to verify the identifying information they provide. Including a consent provision on application forms is recommended.

This package does not deal with these legal obligations which must be considered in the overall flow of the data capture experience.

Supported Verification Sources

The following identity sources are supported:

• Australian Driver's License
  Supporting all 8 States of Australia, individuals are required to select their State and enter their Driver's License Number.
• Medicare Card
• Passport
• Immigration Card
• Citizenship Certificate
• Birth Certificate
• Change Of Name Certificate
• Marriage Certificate

Usage Instructions

Use the following proceedure to configure IDMatrix in your form:

• Add the Equifax IDMatrix Verify component onto your page or Equifax IDMatrix Dialog into the Dialogs folder of your form. If using the Equifax IDMatrix Verify component you may find it better to add it to a section configured with Top To Bottom Layout (in the Additional Layout properties) to provide more horizontal space.
• Select the Equifax IDMatrix Verify component (if using the dialog you will find this inside the Dialog Content block) and on the Properties tab select the Options, Interactive Sources you wish to support.
• Open the Input Fields section on the Properties tab and map all required fields into the input data maps.
• In the Rules section, add any processing rules to handle On Verified and On Unverify events.

Help Display Option

This package provides an option to display help content during the interactive verification process. This help content includes document sample images indicating location of required information and related instructions. By default, this help content will be presented but may be disabled by deselecting the relevant configuration option.

Manual Verification Option

This package provides support for manual verfication should the user fail or opt out of the electronic verification. This feature can be enabled or disabled according to the usage requirements using the Allow Opt Out property on the Equifax IDMatrix Verify component.

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 Equifax IDMatrix 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 IDMatrix 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" ,"idMatrixVerifyButton" , data);

Dialog Usage Patterns

Avoka's recommended usage pattern is to trigger the verification process when the applicant clicks the Continue button and on a page where we have captured all personal details required to do so. For example, if you wanted to trigger this process when the applicant clicks the Continue button at the bottom of page 2 of the form you could add this script to the click rule:

if(Form.getCurrentPageNumber() !== 2 || data.verifyStatus === "VERIFIED"){
  // If the applicant is verified or we are not on page 2 then continue as normal
  Form.$Pages.move(true)
} else {
  // If we are on page 2 and we are not yet verified then reset and trigger IDMatrix
  data.idmatrixSelectedSource = "";
  data.verifySources = "";
  Form.fireRule("click" ,"idMatrixVerifyButton" , data);
}

Additionally, if we receive a successful validation result then we should automatically progress to the next page. We can achieve this by adding to the On Verified rule of the Equifax IDMatrix Verify component as follows:

Form.showDialog(""); // Default script
Form.$Pages.move(true); // Move on to the next page

Address Format Requirement

IDMatrix requires a physical address provided either in a single line unformatted address or in Long format with an explicit breakdown of address components as follows:

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": "EquifaxIDMatrix",
        "executionTimestamp": "2017-08-16 17:43:58 AEST",
        "durationMillis": 147,
        "request": {
            // Request Details
        }
        "reseponse": {
            // Response Details
        }
    },
    {
        "serviceName": "EquifaxIDMatrix",
        // Etc...
    }
]

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

Tamper Proofing

To help combat fraudulent applications this package includes Equifax IDMatrix - 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 Equifax IDMatrix - 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).

Configuration

1. Double check the identity data request parameters you want this service to check in Equifax IDMatrix - Identity Verification Service parameter: idMatrixTamperCheckRequestParams. For example, firstName,middleNames,lastName,dateOfBirth,streetNumber,streetName,streetType,suburb,state,postcode,country. The name must match the request parameter name that Equifax IDMatrix - Identity Verification service accepts.
2. Write a Submission Completed Processor to call the Equifax IDMatrix - 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 com.avoka.tm.svc.*
   import com.avoka.tm.vo.*
   import com.avoka.tm.util.Path
   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 ? "EquifaxIDMatrix.${ROLE_KEY}.verifyStatus" : "EquifaxIDMatrix.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('Equifax IDMatrix - Tamper Check')
                           .setClientCode(CLIENT_CODE)
                           .setVersionNumber(1)
                           .invoke(params)
   
               logger.info "Tamper Check result=$success"
               if (success==false) {
                   throw new Exception("Tamper Check failed. Identity data has been tampered!")
               }
           } else {
               logger.info "Identity data is not verified by IDMatrix 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 "EquifaxIDMatrix.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.6Apr 27, 2022

• Enhanced to add new "Card Number" field for DVS Driver's Licence checks

• Fixed validation bugs in medicare, birth certificate, and change of name services.
• Fixed major validation bug (First name and Last name) in change of name certificate and validation messages order.
• Fixed server error if applicant changes verification source service and sends partial params
• Fixed multiple validation bugs in birth certificate and marriage certificate sources
• Enhanced UX by auto-scrolling and setting focus upon selecting a service
• Enhanced UX by creating consistency with Desktop view by enabling "Help images" in Mobile view

Version 1.4 Oct 16, 2017

• Fixed birth certificate type cannot be disabled in Maestro component.

Version 1.3 Sep 26, 2017

• Fixed middle name on card in medicare card verification blank value issue.

Version 1.2 Sep 7, 2017

• Added support for tamper check.

Version 1.1 August 25, 2017

• Added support for audit logging of all HTTP requests.

Version 1.0 August 8, 2017

• Baseline release.