Process Flow

Second Factor Authentication

Open SMS Message

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 the 3rd party vendor directly.

Compatibility

This package has the following compatibility requirements:

Installation Instructions

This package should be installed as a single archive via the Avoka Exchange. Once installed you should walk through the following procedure to ensure you complete any required configuration:

1. Review the documentation below for each of the imported services and make any required adjustments to service parameters.
2. Review the documentation below for any Service Connections and add your credentials as required.

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

Usage Instructions

To use this package please walk through the following procedure:

Second Factor Authentication

Setting up the Maestro template

1. Login to Maestro, create or open your existing form template, in the "Save Challenge" dialog, locate the "Security Question" section, create a challenge field called PIN.
2. Create a send/resend pin button
3. Create a click rule on this button to call the Amazon SNS - Save Challenge Send Token fluent function. Below is the example code that you can modify to suit your business case.

var getURLParameter = function(name) {
  return decodeURIComponent((new RegExp('[?|&]' + name + '=' + '([^&;]+?)(&|#|;|$)').exec(location.search) || [null, ''])[1].replace(/\+/g, '%20')) || null;
}
Form.showProgress("~T~waitingMsg~T~Please wait...");
Transact.formFunction("Amazon SNS - Save Challenge Send Token", "1.0.0", "Amazon SNS Send Token", {"referenceNumber": getURLParameter("referenceNumber")}).then(function(response) {
    Form.showProgress("");
    // Set result data
    if (!!response.data) {
      var executionStatus = response.data.executionStatus;
      var errorMessage = response.data.errorMessage;
      // put these result into your data fields in the template
    }
}).catch(function(err){
    alert("~T~errorMsg~T~Error sending Token.");
    Form.showProgress("");
});

NOTE: When you call form function, you need to specify an explicit version number. In this case, 1.0.0

4. Add the above Javascript to the Dialog Load event on the "Save Challenge" dialog if you want to send the token automatically when opening the dialog.
5. Publish the template to your Maestro library.

Setting up the Maestro form

1. Login to Maestro, create a form and make sure it uses the template you created and published above.
2. Create a data extract in the form which contains the phone number you want to receive the token number.

Make sure the data extract name matches the service parameter: snsPhoneExtractName defined in the Amazon SNS - Save Challenge Send Token fluent function.

Since phone number is mandatory for Amazon SNS service, you need to make sure the user provides it before saving the form.

3. build the form with "Use Transact Functions" option.

TM server configuration

1. Configure the Amazon SNS Service connection with Amazon SNS end point and credentials
2. Configure the Amazon SNS - Save Challenge Send Token fluent function, make sure all the service parameters are configured correctly.

Pay attention to set the proper service parameter: snsSigningRegion and endpoint in Amazon SNS Service connection based on your region. Please check AWS Regions and Endpoints for more information.

3. Find the form you built earlier, go to the Form Version -> Functions. Add a form function trigger which calls the Amazon SNS - Save Challenge Send Token - v1.0.0 fluent function.

Open SMS Message

User Case 1: Triggered directly from Maestro form

1. Login to Maestro, create or open your form, create a normal button to send the message.
2. Create a click rule on this button to call the Amazon SNS - Send Message fluent function. Below is the example code that you can modify to suit your business case.

// assuming you have three fields with id "applicant_mobileNumber", "message" and "sender"
var mobileNumber = data.applicant_mobileNumber;
var message = data.message;
var senderId = data.sender;
Form.showProgress("~T~waitingMsg~T~Sending SMS ...");
Transact.formFunction("Amazon SNS - Send Message", "1.0.0", "Amazon SNS Send Message", {"phoneNumber": mobileNumber , "senderId": senderId , "message": message }).then(function(response) {
    Form.showProgress("");
    // Set result data
    if (!!response.data) {
      var executionStatus = response.data.executionStatus;
      var errorMessage = response.data.errorMessage;
    }
}).catch(function(err){
    alert("~T~errorMsg~T~Error sending SMS.");
    Form.showProgress("");
});

NOTE: When you call form function, you need to specify an explicit version number. In this case, 1.0.0

3. build the form with "Use Transact Functions" option.
4. Login to TM, find the form you built earlier, go to the Form Version -> Functions. Add a form function trigger which calls the Amazon SNS - Send Message fluent function.

User Case 2: Triggered from Narrator

You could include this function as part of preAction or PostAction in your Form Narrative. Once condition meets, the Narrator will call this function to send SMS. This function accepts mobile number and message information either from server configuration (in Form Narrative) or from Maestro form (using form data extract). The following example demonstrates the case where mobile number is from a form mobile field and message is defined on TM server. The form contains three Narrator pages "GetStarted", "Address", "Final" and after user finishes the Address page, a SMS will send to user.

1. Make sure you installed Narrator support both in Maestro and TM.

You can find the Narrator documentation here

2. Create your template and form, configure them correctly based on Narrator documentation. This also includes Narrator configuration on TM (Three triggers, Form Narrative property, etc.).
3. In your Maestro form, create a data extract in the form which contains the phone number to receive the SMS.

Make sure the data extract name matches the service parameter: snsPhoneExtractName defined in the Amazon SNS - Send Message fluent function.

Since phone number is mandatory for Amazon SNS service, you need to make sure the user provides it before this function being triggered.

4. Create a data extract "FirstName" in the form which contains the first name.
5. build the form with "Use Transact Functions" option.
6. Login to TM, find the form you built earlier, go to the Form Version -> Properties. Find the Form Narrative property, add the following code to postActions in Address page.

{ "name": "Amazon SNS - Send Message",
                    "version": "1.0.0",
                    "completed": true,
                    "skipped": false,
                    "alwaysProcess": false,
                    "params": {"senderId": "NOTICE" , "message": "Congratulations! ${txn.formDataMap.get('FirstName')}. You just completed address information. Please sign now."},
                    "condition": "true" }

This function will always use phoneNumber and message if they are defined in the input params. If not provided, it will try to use the data extract in the form. In this example, we defined the message as input parameters in Form Narrative so the function will use this as message. We didn't provide phoneNumber in params on purpose because we want to use the mobile number that applicant input in the form instead, that's why we configured data extract for mobile number field at earlier step. As you can see, the function is designed flexible enough to allow you define those information either in the form or on the server to suit your requirment.

Even if you decide to provide message as input parameters in Form Narrative, you still have full access to form data to be used to construct your message. Narrator recommends to use data extract if you want to get form data instead of directly parsing xpath in form xml. In this example, we use data extract to get user's first name to be included as part of the message.

User Case 3: Be called through Form trigger on TM

You can also call this function directly on form triggers. Since TM doesn't allow any input parameters in this case, you need to provide mobile number and message info in your form as data extract.

1. Login to Maestro, create or open your form
2. Create a data extract in the form which contains the phone number to receive the SMS.

Make sure the data extract name matches the service parameter: snsPhoneExtractName defined in the Amazon SNS - Send Message fluent function.

Since phone number is mandatory for Amazon SNS service, you need to make sure the user provides it before this function being triggered.

3. Create a data extract in the form which contains the SMS message you want to send.

Make sure the data extract name matches the service parameter: snsMessageExtractName defined in the Amazon SNS - Send Message fluent function.

Since message is mandatory for Amazon SNS service, you need to make sure the user provides it before this function being triggered.

4. build the form with "Use Transact Functions" option.
5. Login to TM, find the form you built earlier, go to the Form Version -> Functions. Add a trigger which calls the Amazon SNS - Send Message fluent function to suit your requirement. For example, if trigger is "User Save", a SMS will be sent after user saves the form.

When calling this function on certain trigger, it doesn't provide any input parameters. Hence you need to make sure you configured the data extract for mobile number and message correctly in the form.

Release Notes

Version 1.0 July 27, 2018

• Baseline release.