5. Application Integration

Promptar application integration is, by nature, a very open-ended and broad subject: it depends on which and how many applications are being integrated, what type of information needs to be collected and displayed to the users, under which conditions, etc. As such, this section will focus more on presenting the key concepts and behaviors rather than taking the approach we’ve been following of a step-by-step installation procedure document.

5.1. Feature Groups

Application integration may be considered under the following feature groups:

  • Business Information Delivery The ability to collect application managed information associated to other parties on the phone; also defining under which conditions which information should be collected and displayed to the users.
  • Task Automation The possibility of implementing user-controllable actions supporting open-ended application integration.
  • Contact Lookup Helping users quickly find application managed contacts from within Promptar Desktop Client and initiating calls towards them.
  • Application Call Control The capability of having the application initiate/control phone calls from within its own user interface.

Depending on your needs, the target applications and the application connectors being used, each of these feature groups will be pursued and achievable to varying degrees of coverage (for example, one may not be able to change a particular application into supporting call initiation or control from within its native user interface).

5.2. Business Information Delivery

The key Promptar Server concepts associated to business information delivery are Templates and Rules.

  • Templates | Define what should be displayed to the user.

    • There is no server-imposed limit to the number of templates that can be configured.
    • Each template has an identifier and contains one or more fields.
    • Each field is composed of a label and a value expression.
    • Value expressions are Python expressions, evaluated as strings, that generally include data items.
    • Data items represent information obtained from the application connectors, telephony connector and provided by the Promptar Server itself.
  • Rules | Define under which conditions particular templates are selected.

    • There is no server-imposed limit to the number of rules that can be configured.
    • Each rule has an identifier, contains one or more conditions and activates one or more templates.
    • Conditions are Python expressions, evaluated as boolean values, that generally include data items.

Python Expressions

 

  • Expressions throughout the server configuration are Python 2 expressions.
  • Other than the built-in Python functions, the following modules are available for use, from within their namespace: datetime, time, urllib, HTMLParser and re.
  • Expressions should strive to evaluate quickly - slow expressions may negatively affect the overall performance.
  • Native Python introspection abilities aren’t limited in any way and may allow for complex use-cases with undesirable results, within the simple sandboxing around them.

Data Items are the essence of Promptar flexibility and support business information delivery in a very natural way. As mentioned above, in the context of both Templates and Rules, data items play a key role and, depending on a given integration scenario and the connectors in use, more or less data items will be available.

As a general rule, application connectors provide as many different data items as there are different application fields supported by that connector. Refer to each connector documentation to determine which data items it provides.

Additionally, Promptar Server itself provides several built-in data items, often useful in implementing simple but very common sets of rules. Refer to the Data Item Reference appendix for information on them.

Last but not least, some telephony connectors may also provide data items themselves. These are often related to particular details of the telephony system that Rules or Templates can also use.

 

When used in the Python expressions for either Rules or Templates, data items are represented as identifiers between curly braces, formatted like in {<domain>.<item>} where the <domain> part identifies which component is providing it and the <item> part is dependent on that provider. The data item domains are summarized in the following table:

domain provided by note example

server

Server

Internal server information.

{server.date.weekDay}

user

Server

Information about the user.

{user.data.email}

peerUser

Server

Information about the other Promptar user on the call.

{peerUser.name}

group

Server

Information about the user’s group.

{group.id}

peerGroup

Server

Information about the group for the other Promptar user on the call.

{peerGroup.name}

session

Server

Information about the user’s session.

{session.langID}

call

Server

Information about the call.

{call.peerAddress}

call.data

Telephony Connector

Extra information about the call.

{call.data.ivr_input}

app.<plg-id>

Connector <plg-id>, as in plugins.conf.

Application obtained information. Connector/application dependent.

{app.crm.account.name}

{app.erp.shipment.date}

Let’s take a look at a simple configuration, as shipped in the Server’s integration.conf file:

[templates]

users.name                  = User on the phone with a Promptar User
users.field.h1.value        = {peerUser.name}
users.field.h2.value        = {peerGroup.name}

internal.name               = Internal Calls - Peer is not a Promptar User
internal.field.h1.value     = "Extension " + {call.peerAddress}
internal.field.h2.value     = "Internal Call"


[rules]

users.name              = Internal Calls: between Promptar users
users.condition         = {peerUser.id|""} != ""
users.template          = users

internal.name           = Internal Calls: Promptar user to/from non-user
internal.condition      = len({call.peerAddress|""}) <= {server.data.ext_len}
internal.template       = internal

Templates are declared in the [templates] section:

  • Each Template is declared across a set of lines, grouped visually for convenience.
  • The first group of lines declare a Template identified as users, containing two fields; the second group of lines declares another Template, identified as internal, also containing two fields.
  • In both templates the first two fields have h1 and h2 as identifiers. Fields have associated value expressions.
  • In the user Template, h1 contains the name of the Promptar peer user [11] and h2 contains the peer user’s group name. In the internal template, h1 contains the string "Extension" followed by the peer address [12].
  • These Templates address the simple case of displaying information about internal calls in two different scenarios: two Promptar users on the phone with each other and one Promptar user on the phone with someone else.

Rules are defined in the [conditions] section:

  • As before, each Rule is defined across a set of lines, grouped visually for convenience.
  • The first three lines define a Rule identified as users, containing a single condition and referencing the Template identified as users; the second group of lines follows as similar structure with a different condition.
  • The users Rule condition value, {peerUser.id}, acts as a simple expression to determine whether the other party on the phone is a Promptar user or not; in detail, that data item represents the peer user id as defined in the users.conf file and will be None if no such user exists — when evaluated in a boolean context, any defined user id is evaluated as True and a non-defined one is evaluated as False.
  • The internal Rule condition value, len({call.peerAddress}) <= {server.data.ext_len}, will be true if the Caller ID for the other party on the phone has {server.data.ext_len} [13] digits or less — a simplified approach at stating that a given call is internal.

The full syntax for both Templates and Rules is defined in the sample configuration file comments.

For each call involving an extension associated to a user that is online, Promptar Server will, on behalf of that user:

  • Evaluate the rules, first to last.
  • Stop on the first rule for which all the conditions evaluate to true.
  • Collect the necessary data to fill in the template or templates pointed to by the activated rule, if any.
  • Send the data to the user.
  • In the cases of a call between two online Promptar users, this process is run twice: once from the perspective of each user such that for user A the peer user is user B and for user B the peer user is user A.

This establishes the general understanding of how Promptar Business Information Delivery works and how flexible it can be given that an unlimited amount of Templates and Rules can be defined and that they are based on data items provided by a variety of sources.

 

Application Integration Example

Let’s now describe a more complex example involving a sample application that manages Client Accounts and associated Support Issues and Orders. Promptar server integrates with it by means of a connector [14] that provides the following data items:

data item contents

{app.sample.account_name}

Account name

{app.sample.account_type}

Account type — Assumed to be a text string

{app.sample.account_website}

URL for the website of the account — May be empty

{app.sample.account_issue_id}

ID for open issues associated to an Account

{app.sample.account_issue_summary}

Summary for open issues associated to an Account

{app.sample.account_issue_detail}

Full detail text for open issues associated to an Account

{app.sample.account_issue_status}

Status for open issues associated to an Account

{app.sample.account_order_id}

ID of an open order associated to an Account

{app.sample.account_order_amount}

Amount of an open order associated to an Account

{app.sample.account_order_date}

Creation date for an open order associated to an Account

 

Template declarations:

[templates]

general.name                   = Account information - Simple
general.field.h1.value         = {app.sample.account_name}
general.field.h2.value         = {app.sample.account_type}

account_info.name              = Account information - Full
account_info.field.h1.value    = {app.sample.account_name}
account_info.field.h2.value    = "Account Information"
account_info.field.e1.value    = {app.sample.account_type}
account_info.field.e1.label    = Type
account_info.field.e2.value    = {app.sample.account_website}
account_info.field.e2.label    = Web

account_orders.name            = Account Orders
account_orders.field.h1.value  = {app.sample.account_name}
account_orders.field.h2.value  = "Orders"
account_orders.field.e1.value  = {app.sample.account_order_id}
account_orders.field.e1.label  = Order ID
account_orders.field.e2.value  = {app.sample.account_order_amount} + " €"
account_orders.field.e2.label  = Amount
account_orders.field.e3.value  = {app.sample.account_order_date}
account_orders.field.e3.label  = Date
account_orders.sort-desc       = {app.sample.account_order_date}

account_issues.name            = Account Issues
account_issues.field.h1.value  = {app.sample.account_name}
account_issues.field.h2.value  = "Issues"
account_issues.field.e1.value  = {app.sample.account_issue_id}
account_issues.field.e1.label  = Issue ID
account_issues.field.e2.value  = {app.sample.account_issue_status}
account_issues.field.e2.label  = Status
account_issues.field.e3.value  = {app.sample.account_issue_summary}
account_issues.field.e3.label  = Summary

issue_detail.name              = Account Issues in Detail
issue_detail.field.h1.value    = {app.sample.account_name}
issue_detail.field.h2.value    = "Issue " + {app.sample.account_issue_id}
issue_detail.field.e1.value    = {app.sample.account_issue_summary}
issue_detail.field.e1.label    = Summary
issue_detail.field.e2.value    = {app.sample.account_issue_detail}
issue_detail.field.e2.label    = Detail
issue_detail.field.e3.value    = {app.sample.account_issue_status}
issue_detail.field.e3.label    = Status

default.name                   = Default Template - Account
default.field.h1.value         = "No Account for phone number"
default.field.h2.value         = {call.peerAddress}

Rule declarations:

[rules]

sales_team.name                = User from Sales or Management
sales_team.condition           = {group.id} in ("sales", "management")
sales_team.condition           = {app.sample.account_name}
sales_team.template            = account_info
sales_team.template            = account_orders
sales_team.template            = account_issues

support_team.name              = User from Support
support_team.condition         = {group.id} == "support"
support_team.condition         = {app.sample.account_name}
support_team.condition         = {app.sample.account_issue_id}
support_team.template          = issue_detail

general.name                   = Everybody else
general.condition              = {app.sample.account_name}
general.template               = general

default.name                   = Fallback
default.condition              = True
default.template               = default

Highlights:

  • Promptar users in the Sales and Management team get an overview of the Account including information about Orders and Issues — obtained by three templates: account_info, account_orders and account_issues.
  • Promptar users in the Support team get fully detailed information about the issues associated to the Account as defined by template issue_detail. However, if there are no associated issues, they fallback to the next case.
  • All other users get general Account information from the general template.
  • Team membership is being evaluated based on the Promptar user’s group as defined in users.conf; it could be derived from an application in more complex scenarios.
  • Templates:

    • The first two fields of every Template have no label defined: this results from the fact that the Promptar Desktop client does not display labels for them.
    • The second field of the templates for the Sales and Management users are the constant strings "Account Information", "Orders" and "Issues" respectively; see the next section, describing the relationship between templates, fields, data and the Promptar Desktop Client user interface to understand the motive.
  • Rules:

    • Given that they are evaluated from top to bottom, as a general principle, they should be defined from the most to the least specific; the last one, named default, has its condition forced to be True and is, invariably, the least specific case.
    • The sales_team rule only activates if {app.sample.account_name} is true — in other words, if it exists — and if the Promptar user belongs to one of the defined groups.
    • The issue_detail rule goes further and its associated conditions ensure that Account Issues in detail are only delivered to users of the Support team if the Account is known and if there are any associated issues.
  • These Templates and Rules can and probably should be configured in addition to the internal ones.

 

Templates, Fields, Data and the Promptar Desktop Client user interface

The way template collected data is displayed in the Promptar Desktop Client user interface is as follows:

  • Template fields are mapped vertically, in the same order as declared, to the Promptar Desktop Client call window user interface.

    • The first two template fields display automatically and include no labels.
    • The remaining fields, if any, will be available by expanding the call window.
    • By default, the Promptar desktop client will skip displaying fields for which no data was found.
  • When collecting data for fill in a particular Template, multiple records may be found.

    • Multiple distinct data values in the first two fields are displayed by Promptar Desktop Client as drop-down boxes; these behave somehow hierarchically: the second one displays values depending on the first one.
    • Multiple data values in the remaining fields are displayed as individual records which can be navigated.
  • Template aggregation is done on a positional basis and can be thought of as providing a "template" with as many fields as the template with the most fields and with multiple lines of data as obtained from each individual template.

 

Picking up on the integration setup from the previous section, let’s describe a few cases.

 

Case #1 | The general template is selected

The template filled in with data for a single matched Account can be imagined as a table like:

 

h1 h2

Blue Sails Inc

Customer

 

 

Which ends up being displayed by the Promptar Desktop Client as:

 

setup-guide-05-app-integration/app-screen-1-1.png

If, however, when getting information from the Application two accounts are found, we may get:

 

h1 h2

Blue Sails Inc

Customer

Soft Wind Corp

Partner

 

 

Which is displayed in almost the same way. Notice, though, that the first line is a drop-down selector:

 

setup-guide-05-app-integration/app-screen-1-2.png

When changing it to Soft Wind Corp, the second line will automatically display Partner instead.

Case #2 | The issues_detail template is selected

If a single Account is found with two Issues the data can be thought of as:

h1 h2 e1 e2 e3

Blue Sails Inc

Issue 23

Need support fixing sail.

<several lines of text>

In Progress

Soft Wind Corp

Issue 19

Sonar upgrade.

<several lines of text>

Wait for Customer

When displayed to a user it comes up as:

 

  setup-guide-05-app-integration/app-screen-2-1.png

 

Which can be expanded by clicking the eject-like button on the rightmost side of the bottom panel displayed when hovering the window with the mouse:

 

  setup-guide-05-app-integration/app-screen-2-2.png

 

The second issue can be selected from the drop-down box in the second line, having the extra fields below change accordingly:

 

  setup-guide-05-app-integration/app-screen-2-3.png

 

Case #3 | Template aggregation with multiple data per template

When rule sales_team is activated, three templates will collect data. Let’s look at a possible scenario for each individual template and then describe how the combined result ends up in the user interface.

Here is the data representation for account_info, account_orders and account_issues. Notice how account_issues finds the same issues as in the previous example, but structures them in a different way:

h1 h2 e1 e2  

Blue Sails Inc

Account Information

Customer

http://www.example.com/

 

h1 h2 e1 e2 e3

Blue Sails Inc

Orders

E7-221

6289.00 €

2016-07-24

Blue Sails Inc

Orders

E7-29A

1992.40 €

2016-10-02

Blue Sails Inc

Orders

E3-211

520.00 €

2016-10-02

h1 h2 e1 e2 e3

Blue Sails Inc

Issues

23

In Progress

Need support fixing sail.

Blue Sails Inc

Issues

19

Wait for Customer

Sonar upgrade.

When these three templates are aggregated, they result in:

h1 h2 e1 e2 e3

Blue Sails Inc

Account Information

Customer

http://www.example.com/

 

Blue Sails Inc

Orders

E7-221

6289.00 €

2016-07-24

Blue Sails Inc

Orders

E7-29A

1992.40 €

2016-10-02

Blue Sails Inc

Orders

E3-211

520.00 €

2016-10-02

Blue Sails Inc

Issues

23

In Progress

Need support fixing sail.

Blue Sails Inc

Issues

19

Wait for Customer

Sonar upgrade.

This data is first displayed as:

 

  setup-guide-05-app-integration/app-screen-3-1.png

 

Which expands to:

 

  setup-guide-05-app-integration/app-screen-3-2.png

 

On changing the drop-down to Orders, the extra information fields will change to display the first Order information.

Additionally, on the bottom right side, an indicator informs the user that record 1 out of 3 is being displayed and to its right the previous/next buttons allow the navigation between existing orders.

 

  setup-guide-05-app-integration/app-screen-3-3.png

 

Lastly, changing the drop-down to Issues, behaves in a similar fashion as in the previous case with the lower fields now showing 1 out of 2 existing issues.

 

  setup-guide-05-app-integration/app-screen-3-4.png

 

5.3. Task Automation

Task automation is tightly related to Templates and its associated fields. The key concepts are:

  • Excluding the first two fields, any template field can be actionable.
  • An actionable field is displayed with a lighter background and behaves much like a link in a web browser, including changing the mouse cursor to a pointing hand in place of the regular arrow. To trigger the action, the user clicks the field.
  • Two types of actions can be configured:

    • Open URL | The Desktop Client requests the operating system to open the URL associated to the action which may include data items as well.
    • Local Execute | The Desktop Client requests the operating system to run a particular program which, again, may be supplied arguments based on data items.
  • Actions can be triggered manually, by the user, or automatically. There are three modes for auto-triggered actions, in the context of each template:

    • Single | The action will be auto-triggered if and only if a single data record is received by the client.
    • First | The action will be auto-triggered within the context of the first data record, regardless of the number of data records received by the client.
    • All | The action will be auto-triggered once for each of the data records delivered to the client.
  • Independently of the triggering mode, actions can always be re-triggered by the user.

Picking up on the previous section example, let’s build on top of it by adding a few actions, highlighted below:

[templates]

...

account_issues.name            = Account Issues
account_issues.field.h1.value  = {app.sample.account_name}
account_issues.field.h2.value  = "Issues"
account_issues.field.e1.value  = {app.sample.account_issue_id}
account_issues.field.e1.label  = Issue ID
account_issues.field.e1.action-type  = openURL
account_issues.field.e1.action-value = "http://url/?id=" + {app.sample.account_issue_id}
account_issues.field.e2.value  = {app.sample.account_issue_status}
account_issues.field.e2.label  = Status
account_issues.field.e3.value  = {app.sample.account_issue_summary}
account_issues.field.e3.label  = Summary

issue_detail.name              = Account Issues in Detail
issue_detail.field.h1.value    = {app.sample.account_name}
issue_detail.field.h2.value    = "Issue " + {app.sample.account_issue_id}
issue_detail.field.e1.value    = {app.sample.account_issue_summary}
issue_detail.field.e1.label    = Summary
issue_detail.field.e2.value    = {app.sample.account_issue_detail}
issue_detail.field.e2.label    = Detail
issue_detail.field.e3.value    = {app.sample.account_issue_status}
issue_detail.field.e3.label    = Status
issue_detail.field.e4.value    = "Send email"
issue_detail.field.e4.label    =
issue_detail.field.e4.action-type  = openURL
issue_detail.field.e4.action-value = "mailto:" + {...email} + "?subject=Issue " + {...id}
default.name                   = Default Template - Account
default.field.h1.value         = "No Account for phone number"
default.field.h2.value         = {call.peerAddress}
default.field.e1.value         = "Create new Account"
default.field.e1.label         =
default.field.e1.action-type   = openURL
default.field.e1.action-value  = "http://url/newAccount?phone=" + {call.peerAddress}
default.field.e1.action-trig   = autoSingle

 

Notes:

  • The account_issues template field e1 became actionable: clicking it will invoke the default browser with the URL as defined the action-value expression; in the sample application, we’re assuming that a URL formatted like http://url/?id=<issue-id> would display the full issue details in the application’s user interface, which is not uncommon for web based applications.
  • An action-only [15] field e4 was added to the issue_detail template which prepares an email message for sending; it builds a URL of the format mailto:<email-address>?subject=<subject> that the majority of email clients handle by bringing up a pre-filled message composition window; note how the <email-address> and <subject> are built out of available [16] data items.
  • Another action-only field e1 was added to the default template. This one would help the user creating a new Account in the application associated to the underlying Caller ID. In this case, the action was configured to be auto-triggered by means of the action-trig filed setting.
  • A similar auto-triggering approach could be applied to the account_issues e1 field above, which would bring up the application’s user interface for a given issue and where a choice of autoSingle or autoAll could be useful.

 

Regarding Local Execute type actions, which provide fully open-ended integration possibilities:

  • Much like the Open URL types of actions, the action-value should include a Python string expression, which can be built out of data items; it defines the command to be executed on the client system in these cases.
  • The path to the executable must not be included in the string, Promptar Desktop Client will locate it in predetermined locations:

    • Windows 32 bit | Under the Promptar Desktop Client Actions directory in %ProgramFiles%.
    • Windows 64 bit | Under the Promptar Desktop Client Actions directory in %ProgramFiles%, %ProgramFiles(x86)% or %ProgramW6432%.
    • Mac OS | Under the Promptar Desktop Client Actions directory in /Library/Application Support.
  • The command to be executed will depend on its extension and platform:

    • Windows | .bat | Processed by %WINDIR%/System32/cmd.exe.
    • Windows | .vbs and .wsf | Processed by %WINDIR%/System32/wscript.exe.
    • Windows | .exe and .com | Executed directly.
    • Mac | .sh | Processed by /bin/bash.
    • Mac | no extension | Executed directly.

For completeness, here is an example of how such an action can be configured. In this case it controls the SAP GUI in the user’s desktop to display a given customer information:

customer.field.e1.value         = {app.sap.kunnr.id}
customer.field.e1.label         = Customer ID
customer.field.e1.action-type   = localExec
customer.field.e1.action-value  = "sapgui-xd03.wsf /kunnr:"+{app.sap.kunnr.id}

5.4. Contact Lookup

Promptar Server handles contact lookup by matching a lookup string against the Server’s user list and/or one or more application connectors.

Matching of the lookup string against candidate results depends on the source:

  • For internal user list lookups, the lookup string is matched against the user name and the associated group name, as defined in users.conf.
  • For lookups directed at application connectors, the candidate matching rules are within each connector’s configuration scope.

The result of a lookup request will be a set of [<name>, <address>] pairs which is returned to the client for display and, possibly, subsequent call initiation. Regarding the configuration, the following definitions must be declared:

  • Which sources a particular contact lookup request should use. These can be defined on a per-group basis and fallback to a default case.
  • How to format the display of the <name> part of the result. For lookups against the internal user database, this configuration is performed on the Server itself. For lookups sourced from application connectors, this configuration is, again, within each connector’s configuration scope.

Contact lookup is configured in the [default] section of the integration.conf file. Let’s review a few cases.

Case #1 | Lookup in the internal user database with default <name> formatting

[default]

lookup = server
  • Any client submitted lookup request will be performed against the internal user list.
  • The results will have <name> formatted as "<user-name> - <group-name>".

Case #2 | Lookup in the internal user database with custom <name> formatting

[default]

lookup = server:{group.name}+" | "+{user.name}
  • As above, but the <name> will be formatted as "<group-name> | <user-name>".
  • Any group or user data item can be used in the expression following the ":".

Case #3 | Finance team users also lookup in the ERP

[default]

lookup         = server:{group.name}+" | "+{user.name}
lookup.finance = erp, server:{group.name}+" | "+{user.name}
  • Lookup requests coming from users belonging to the group identified by finance will be performed against the application connector identified by erp, as defined in plugins.conf; additional results will be collected from Promptar Server’s internal user list.
  • Requests coming from users in other groups will only be performed against the internal user list.
  • There is no limit to the number of per group lookup configurations.

5.5. Application Call Control

Application call control comprises the ability of initiating and/or controlling calls from within the application user interface. Technically this can be achieved in one of two ways:

  • Application Connector Based In this scenario, the application connector receives call initiation/control commands from the application and forwards them to the Promptar Server on the user’s behalf. This requires that both the application user interface be adapted to such interactions and, of course, that the associated connector supports such types of requests.
  • Desktop Client Based Promptar desktop client registers itself with the underlying operating system as a protocol handler for the callto, tel and promptar.callto URL schemes. It then handles invocations for URLs formatted like <scheme>:<phone-number> by initiating calls towards the given destination. No other call control mechanism is currently available via the Desktop Client.

Even though the application connector based call control approach may lead to a more seamless integration, even supporting call indications within the native application user interface, its implementation is very complex and, again, requires the support of the associated connector. As of this writing, this is only supported when integrating with SAP ECC solutions.

The desktop client based approach, being simpler, makes it very easy to achieve the critical capability of initiating a call from within an application — the remaining call control actions can, of course, be handled via the desktop client call window interface: all that is needed is to update the application user interface to invoke the supported URLs form the operating system.

In web based applications, it generally boils down to changing the HTML associated to displaying a phone number by wrapping the actual phone number in a tag like:

<a href="callto:+351213939800">+351 21 3939 800</a>

In practice, many applications already use this type of approach associated to phone numbers.

For non web based applications, the approach is somehow similar: to request a call initiation, all they should do is request the operating system to open a correctly formatted URL.

Regarding operating system URL handling, here are a few important notes:

  • The callto and tel URL schemes are standardized and supported by a multitude of desktop applications. If more than one such application is present on the system, one may need to use operating system level tools to decide which application will handle which URL schemes:

    • Windows | Go to "Start > Default Programs > Set your default programs"; from there select Promptar Desktop Client on the left and click "Choose defaults for this program" to reach a form where the URL schemes can be selected. The procedure, of course, can be executed for other applications [17].
    • Mac | No user native interface is available for this. Without having any affiliation with it, RCDefaultApp is available at http://www.rubicode.com/Software/RCDefaultApp/ and provides a preference pane where such selections can be easily done.
  • To test operating system level URL handling, bring up a command line shell and run:

    • Windows | explorer "<scheme>:<phone-number>"
    • Mac | open "<scheme>:<phone-number>"

5.6. Implementing

Wrapping up this chapter, we get back to a more step-by-step approach that is more like the remaining of this document. Promptar application integration should generally be implemented with the following steps:

  • Install and configure the application connector, while referring to its associated documentation.
  • Add the connector declaration to the server’s plugins.conf configuration file.
  • Within the integration.conf file, in the [defaults] section, add a get-data rule.

    • get-data rules are key in the integration process and define how Promptar server should deliver a phone number to the application connector when asking for associated data.
    • Look at the commented out examples in the sample configuration file for guidance. The key aspect is knowing the app-field-id to use in the search-field declaration: for that consult the application connector documentation; search-value should be an expression defining precisely which phone number to use: generally {call.peerAddress} is adequate, but arbitrarily complex expressions can be used to filter or process the phone number obtained from the phone system connector at this stage, including avoiding reaching out to the application connector not to impose unnecessary load on the application.
  • Still within the integration.conf file, add a simple rule and template to test out the integration. We recommend starting off with the integration.conf.sample that the application connector may provide.

    • Restart the server and perform initial tests as shown previously.
    • Build your full set of rules and templates one step at a time. This makes it easy to detect eventual mistakes during this process. At this stage, there is no need to restart the server at every step; use the server.reload command instead [18].
  • Once the base templates and rules are operational, add actions as needed:

    • Again we recommend changes are performed and tested one step at a time.
    • Distributing commands, scripts or binaries may need to be done or planned.
  • Lastly configure lookup.



[11] The peer user is the Promptar user who is on the phone with a given Promptar user: if users A and B are on the phone with each other, B is A’s peer, and vice versa; if the peer isn’t a Promptar user, the peer user is undefined.

[12] The peer address, by similarity, is the address of whoever a given Promptar user is on the phone with; in the majority of cases, it will be a phone number corresponding to what generally is called the Caller ID.

[13] Recall, server data items are declared in the [data] section of the integration.conf file.

[14] Promptar URC for databases or REST for web-based integration, for example.

[15] By action-only we mean two things: the field display is hard configured to the string "Send email" and the field label is forced to empty. This results in a button-like interface and familiar user experience.

[16] Actually, we’re assuming the availability of a data item that provides the issue requester’s email address by including a {…email} in the action-value expression.

[17] Often you will find that the URL handling for callto or tel URLs is directed at Skype or some other soft phone.

[18] See the Command Line Reference appendix, Server Commands section.