Configuring Voice Delivery

You can use the MDC Configuration Utility to configure an HTTP gateway for voice delivery. This application allows you to import, export, or manually configure an HTTP gateway. For more information about importing or exporting gateway definitions, see Importing/exporting gateway definitions (Message Delivery Component).

To configure an HTTP gateway connection for voice delivery

1. Start the MDC Configuration Utility.
2. Switch to the Voice delivery tab.
3. If the delivery method is not yet enabled, select the Enable voice delivery checkbox.
4. Click Add. Type a display name and click OK.
5. Select the profile you just created from the Voice gateways section.

6. Configure the voice gateway settings:

   1. Switch to the Gateway settings tab.

   2. Type the URL of the gateway. If the URL uses an https:// prefix, then it is TLS/SSL-enabled. In that case, click Browse and navigate to the certificate file to use.

      Certification authority (CA) files should be located on the same host as OneSpan Authentication Server. If your CA file is located on a network share, you need to copy the file locally before you browse to it and select it.

   3. Type the port on which the gateway should be listening.

   4. Configure load-balancing, failover, and/or failback by specifying the following:

      • The order of the gateway definition in the gateway list.
      • The server type (i.e. Primary or Backup).

      For more information, see MDC gateway load-balancing, failover, and failback.

   5. Type the user name and password of the gateway account in the Voice gateway account section.
7. If required, switch to the Query and result tab to configure querying and result matching rules settings (see Query data and Result page).
8. In the Voice settings section, provide the appropriate number prefix in the Phone number prefix field. MDC will automatically prepend this to each user phone number.
9. Click Apply.

For more information about testing your gateway settings, see Testing gateway configurations.

For more information about configuring proxy settings, see Configuring HTTP proxy servers (for Message Delivery Component).

Query data

The query data is used in an HTTP or HTTPS query to the voice gateway. It typically contains the following parameters:

• username. The user name to log in to the gateway.
• password. The password to log in to the gateway.
• device. The mobile phone number to send the message to.
• network. The type of mobile network to use (if required by the gateway).
• message. The message content.

Each query parameter requires a value or a pre-configured Message Delivery Component variable. The following variables are available:

• [acc_user]. From the User name field in the Voice Delivery > Gateway Setting > Voice gateway account section (MDC Configuration Utility).
• [acc_pwd]. From the Password field in the Voice Delivery > Gateway Setting > Voice gateway account section (MDC Configuration Utility).
• [otp_dest]. The user's mobile phone number in the respective user record. Sent by OneSpan Authentication Server.
• [otp_msg]. Message template string set in the Configuration Utility. Sent by OneSpan Authentication Server.

To set up the query string

1. Start the MDC Configuration Utility.
2. Switch to the Voice delivery tab.
3. Select the gateway definition to which you want to add a query string from the gateway list.

4. Select a form method. This depends on the requirements of the gateway, but typically is POST.

   • POST. The message data is stored in the request body of the HTTP request as URL-encoded form data.
   • GET. The message data is appended to the URL as a regular HTTP query string.
5. If required, modify the query data as name–value pairs in the Form data field or the Query string field, respectively, depending on the selected form method.

Result page

Voice gateways usually return a request result when a text message is submitted. That result is normally an HTML-formatted page containing specific error codes and/or additional messages for success/failure.

Result messages are generally categorized as three types:

• Information. The message delivery was successful, i.e. the message has been accepted by the server.

• Warning. The submission/delivery failed, but it is most likely a specific error only affecting this particular user. The user’s logon request will fail on the first step. Possible causes are:

  • The phone number is invalid.
  • A temporary gateway failure occurred.

• Error. Some error occurred during the delivery attempt. This means that the delivery failed for a particular user, but the error might be affecting all users. In this case, the user’s logon request will fail immediately. Possible errors are:

  • The account data is incorrect, i.e. account user or password is wrong.
  • The account credit expired (for a pre-paid gateway account).
  • A communication error with the gateway occurred (network error).
  • Another permanent gateway error occurred.

Result matching rules

You can define result matching rules to process gateway results and to create alternate messages for auditing whenever a result is received. A gateway result page can be recognized by key words and phrases, and an alternate message created for logging to the audit console whenever the result is received. Variables can be extracted from the result and used in the log message to provide extra information.

You can set the order of the result matching rules to match more specific messages first and finally catch any other message, which the gateway might send. If no rule matches a result returned, an error will be added to the audit log, reporting that the result page returned from the gateway could not be matched.

Result matching patterns

A result matching rule defines a result matching pattern that triggers the rule. The format of the matching patterns depend on the content type configured in the request details settings of the voice gateway definition.

Matching patterns use the following syntax:

fixed_1 [variable_1] fixed_2 [] fixed_3variable_2 ...

Where the pattern is constructed in the following way:

• fixed_<x> is a character string that must be matched exactly as is in the result returned by the gateway. Note that multiple fixed_<x> segments can appear in a single template, as long as they do not overlap. Matching is case-sensitive.
• [ ] omits a variable part of the result between two fixed_<x> segments, when matching a template. This can be useful to ignore arbitrary data or time/date data in the returned web page.
• variable_<x> describes a segment of the result between two fixed_<x> segments or at the end of the result page, which will be stored in a variable to use as a named backreference in the audit text. Usually this will be data that can provide more detailed information why a particular message submission has failed. The variable name within square brackets can be used as part of the audit message template to create a meaningful audit message. The variable names are case-sensitive.

Plain text result matching patterns

Consider a gateway that returns the following results for successful and failed transmissions, respectively:

• Success: “<b>Submission successful at 10:00, 11/11/02, status: 00 - message delivery in progress.</b>”
• Failure: "<b>Submission unsuccessful at 10:05, 11/11/02, status: 47 - number too short</b>"

The following possible result matching rules can be configured to handle these results:

1. Rule name: Success

   Matching pattern: successful at [DateTime], status: [Status] - [Message]</b>

   Variables retrieved: DateTime, Status, Message

2. Rule name: Warning

   Matching pattern: unsuccessful at [DateTime], status: 47 - [Message]</b>

   Variables retrieved: DateTime, Message

3. Rule name: Error

   Matching pattern: unsuccessful at [DateTime], status: [Status] - [Message]</b>

   Variables retrieved: DateTime, Status, Message

Audit text templates

If a result matching rule triggers, a corresponding audit message is constructed and written to the audit log. The result processing stops, subsequent result matching rules are not evaluated. The audit message is constructed based on the audit text template defined in the result matching rule, it can contain variables retrieved from the result matching pattern and the following pre-defined variables:

• [otp_dest]. The destination address (a mobile phone number) the OTP was sent to.
• [otp_msg]. The message that was submitted. This variable will also contain the OTP, so should not be used for the construction of audit messages.
• [acc_user]. Account name for the gateway. Not recommended for use in audit messages.
• [acc_pwd]. Account password for the gateway. Not recommended for use in audit messages.
• [Username]. The user ID of the user requesting the OTP.

Use variables in audit text templates

• Insufficient credit on account [acc_user] when sending to [Username]
• Message not sent to user [Username]/[otp_dest]. Gateway reported: [Message]

To add a result matching rule

1. Start the MDC Configuration Utility.
2. Switch to the Voice delivery tab.
3. Select the gateway definition you want to configure from the gateway list.
4. Switch to the Query and result tab.
5. Click Add to open the Result matching rule dialog.
6. Type a descriptive name for the rule in the Description box.
7. Type the full text or a partial match of the text displayed by the gateway in the Matching pattern box, optionally with variables (see Result matching patterns).
8. Select an audit message level for the rule. Each message level will be displayed with a different color scheme in the Audit Viewer application, based on the respective color highlighting settings configured.
9. Type the message text you want the users to see into the Audit text box, optionally using variables (see Audit text templates).

10. Click OK.

    The new result matching rule is added to the rule list. Use the Move up and Move down buttons, to configure the order of the result matching rules. The result matching rules are processed from top to bottom, the first one that is triggered writes the audit message.