1. Concepts

Promptar XLATE, also known as Promptar Telephony Translation Plugin, is a proxy connector that processes phone numbers: adding/removing prefixes, normalizing and cleaning up are among common usages of the connector.

Sitting between Promptar Server and the phone system connector, XLATE processes phone system events directed at Promptar Server and call control commands in the reverse direction.

1.1. Promptar and Phone Numbers

Understanding the way Promptar handles phone numbers and the possible role for XLATE is fundamental in order to setup Promptar in a way that ensures the best possible experience. To do that, two distinct scenarios are described: handling of call notifications, on one hand, and handling of desktop triggered call initiation requests, on the other.

 

Call Notification

Call notifications are triggered from the phone system connector towards Promptar Server whenever an incoming or outgoing call is detected on a given user’s phone device.

The following diagram represents a typical Promptar component architecture, including XLATE, where the tagged arrows represent the flow of notifications and requests containing phone numbers.

 

setup-guide-01-concepts/images/xlate-notification-overview.png

 

  • Phone system connector notifications in (A) include two phone numbers obtained from the phone system:

    • The configured user’s extension address, often as a sequence of a few digits.
    • The remote party’s address, again, often, as a sequence of digits. When associated to external parties, this tends to vary widely in format: not only depending on the phone system and its configuration, but also on the remote party’s geographic area and country, for example.
  • XLATE may process the numbers in (A), forwarding the notification to the server with updated numbers in (B).
  • With the phone numbers in (B), the server:

    • Identifies the user based on its configured extension and immediately notifies it of the call with the same numbers as in (B), via DCC and towards the Promptar Desktop Client.
    • Optionally performs an additional step of lightweight processing to the other party’s phone number in (B), resulting in (C), which is passed on to application connectors when collecting application data for rule and template processing.

Call Initiation

Desktop based call initiation results in a flow of requests when a user directly or indirectly uses the desktop client to initiate a call towards a specified destination. When successful, the associated outgoing call desktop notification is an independent process, just like the one described before.

Call initiations can be triggered by one of multiple actions:

  • Submitting a phone number on the client’s control window lookup/dial text entry box.
  • Running a lookup on the client’s control window and double-clicking a given result.
  • Double clicking an entry in the client’s control window call history pane.
  • Clicking the dial button on a previously terminated call window.
  • Via click-to-call, which triggers a URL based dial action from any application, such as clicking a tel: or callto: link in a web browser [1].

In any of the cases above, a call initiation request will be directed from the desktop client towards Promptar Server. The following diagram represents the same component architecture as before, where the tagged arrows represent the flow of requests containing phone numbers.

 

setup-guide-01-concepts/images/xlate-call-init-overview.png

 

  • As highlighted, the destination phone number is passed-through in (A) with no processing at all across the chain of components: from the desktop client, through DCC and into the Server.
  • The Server directs the request towards the phone system connector, now including the user’s configured extension in (A), but with no changes to the requested destination number.
  • XLATE may then process either number in (A), resulting in (B) which is used to forward the request to the phone system connector.

1.2. The case for XLATE

The key motives to use and configure XLATE are related to application record matching, user experience and performace.

 

Application Record Matching

Even though matching phone numbers to application records depends on the configuration and behaviour of the application connectors and the underlying application capabilities, it is a good practice to have the application connector use phone numbers in a format that matches application data as closely as possible.

  • Stripping prefixes not present in application data.

    • External party phone numbers with digits prepended by the phone system. Often automatically added by the phone system to easily support dialling back from the existing phone devices, these prefixes are meaningless as phone numbers to both users and applications; removing them when phone numbers flow from the phone system connector to the server is a good way to facilitate application record matching.
    • International prefixes. If phone numbers are stored as local/national numbers in the application and the phone system provides phone numbers with leading country code prefixes, stripping them, at least if matching the local country code, is probably the only way to ensure application record matching.
  • Normalizing phone numbers to more closely match application data. Often times, phone numbers are stored in full international format[2] in the application, but the phone system delivers differently formatted numbers depending on the external party’s location; it may deliver 7 digits to local calls, 10 digits for national calls and two leading zeroes followed by a country code followed by a national number for international calls. In these cases, XLATE can convert all phone numbers to the full international format in all notifications from the phone system connector to the server; this, again, ensures the desired application side record matching.
  • Mapping phone numbers. In some geographies, business phone numbers have a "base number" which can be followed by an arbitrary number of digits, normally corresponding to internal extensions; many times, however, the application stored records only include the above mentioned "base number". To facilitate application record matching XLATE can either map any set of phone numbers to a predefined one or, in a more general way, strip trailing digits according to a very flexible rules system.

 

User experience

  • Being flexlible with user entered phone numbers used for call initiation. As described in the previous section, user entered phone numbers for the purposes of desktop based call initiation are passed through from the client towards the phone system connector without changes, regardless of their format. Most phone systems, however, require strict phone number formats in such cases, failing to initiate calls towards numbers that include symbols other that digits and, maybe, a leading + sign (thus excluding support for phone formatting helper symbols commonly used such as spaces, dashes, dots and brackets). XLATE should be used to cleanup extraneous symbols from such numbers and maybe normalize them to a format supported by the phone system.
  • Adding required prefixes for successful outbound dialling. Some phone systems require a leading digit to allow for outbound calling. Instead of requiring the user to manually enter it[3] XLATE should be used to ensure such outbound call initiation requests include the necessary prefixes to succeed.
  • Improving phone number format when displaying it to users. Even though users should rarely be presented with actual phone numbers in a finely tuned Promptar solution, they can always use the desktop client’s abilities to see, or copy to the clipboard, the phone number for the other party on any given call they participate in. This being the case, it is generally a good idea to use XLATE to also account for this, including removing phone system prepended digits or normalizing phone numbers as metioned above.

 

Performance

  • Normalizing numbers to perfectly match application stored phone numbers. Fast response is always a critical success factor in any Promptar solution. How fast an application responds with data associated with a given phone number depends on many different factors. Among those, some are Promptar dependent: for example, how flexible or strict the application connector is when trying to match application records with a given phone number tends to affect response time, which will be faster, the stricter the request is. As a general guideline, to achieve the best possible performance two things are necessary[4]: on one hand, all application stored phone numbers should be normalized to a common format; on the other, XLATE should be used to normalize all phone numbers to the same format as used by the application. With such conditions met, application connectors can be configured for maximum strictness and allow for improved performance.

1.3. XLATE Operation

XLATE processes phone numbers with regular expression[5] based substitutions, in two independent pipelines:

  • One handling call notifications originated from the phone system connector towards the server.
  • The other handling call control requests in the opposite direction, from the server towards the phone system connector.

Each such pipeline is fully configurable and consists of three processing stages, executed in order - clean, normalize and map, where the output of a given processing stage is passed on to the next stage:

  • Processing stages contain zero, one or more substitution rules.
  • Substitution rules consist of a regular expression and a replacement expression.
  • Stage execution is as follows:

    • Try to match the input phone number with each rule’s regular expression, in the configured order.
    • If a match is found, apply the replacement expression and feed that result to the next stage.
    • If no match is found, feed the unchanged input phone number to the next execution stage.

As a final note, other than the three-stage pipepiline and specific stage names, XLATE’s operation is universal: any rule in any stage can perform any substitution; the existing clean, normalize, map structure encourages such practise but does not enforce it in any way.



[1] As long as that URL type is configured to be handled by the desktop client.

[2] With a leading + sign, followed by the country code, followed by the national level phone number.

[3] Which isn’t itself possible if the call is initiated via URL handling, by clicking on a tel: or callto: link on a web browser, for example.

[4] Necessary, but probably not suffucient, keep that in mind. Promptar performance depends on many external factors and usually comes down to a trade-off between several aspects.