Install Bridg

Introduction

This document covers the installation of the Bridg service. The Bridg service and app allow users to see contextual information about calls coming from the UCCUCC stands for Unified Contact Center and consists of a queue that can be handled by Agents Each Contact Center has its own settings, interactive voice response questions and Agent with specific skills. Agents can be member of, or sign up to, one or more Contact Centers. (Unified Contact Center) and transfer calls.

This installation guide covers all installation aspects: prerequisites, installation, configuration verification and troubleshooting.

Let’s start with the installation prerequisites.

 

Installation prerequisites

The Bridg service can be deployed on the UCC server, or any other server with Internet Information Services (IIS). The Bridg service has the following requirements:

 

Installation

Start by extracting the Bridg service zipfile to a directory.

BridgServiceTool

Some configuration values must be created using the BridgServiceTool found in the BridgServiceTool folder. The tool can be used for:

  • Creating SharePoint connection strings
  • Creating the Microsoft SQL Server connection string
  • Creating the Microsoft Dynamics 365 connection string
  • Encrypting a Twilio auth token.

 

Install the Bridg service

  1. Modify Properties.ps1 using a text editor. Save and close when done.
  2. Start PowerShell as an Administrator and go to the extraction directory
  3. Run the script called InstallBridgService.ps1
    1. Configure SharePoint when asked (Bridg settings are in the Bridg scope)
    2. Continue installation when SharePoint is configured

Warning Changing these settings after the installation and verification will require a restart of the Bridg service. This will disconnect all clients!

 

Configure the Bridg service settings

Open a web browser and navigate to the PluginSettings SharePoint page that the installation script has provided. Example URL: http://www.mycompany.com/ucc/ucc_main/Lists/PluginSettings/AllItems.aspx

Warning Changing these settings after the installation and verification will require a restart of the Bridg service. This will disconnect all clients!

 

The following are minimum settings for Bridg service to operate, see Appendix A for all settings:

Setting

Value

UccConnections:ConnectionStrings

Value: UCC name, ‘=’ the UCC connection string. Use the BridgServiceTool to create the SharePoint connection string

Example: ucc_main=Url=https://www.mycompany.com/sites/ucc/ucc_main;Username=username;Password=password;Domain=WORKGROUP

HubAdapters;Dashboards

Value: UCC name ‘=’ the URL of the Dashboard service reachable by the BridgService.

Example: ucc_main=https://myserver.mycompany.com/DashboardService

HubAdapters;Attendants

Value: UCC name ‘=’ the URL of the Attendant service reachable by the BridgService.

Example: ucc_main=https://myserver.mycompany.com/AttendantService

Twilio;AccountSid

See “Auth Token and how to change them” for more information. The Account SID should start with “AC”.

Twilio;AuthToken

See “Auth Token and how to change them” for more information.

Note: use the BridgServiceTool for this value.

Twilio;PhoneNumberToSendSmsFrom

The bought Twilio phone number which is capable of sending SMS.

General;PropertyServiceUrl

Fully qualified URL to the CallPropertyManager.svc. Must be reachable by the Bridg service.

Timeline;ServiceUrl

Fully qualified URL to the Universal Timeline service. Must be reachable by the Bridg service.

General;UccPhoneFormat

sipThe Session Initiation Protocol (SIP) is a protocol to make multimedia communication (audio, video and other data communication) possible and it is also used for Voice over IP (VoIP). SIP has similarities with other Internet protocols such as HTTP and SMTP.:{0}@mydomain.com;user=phone

mydomain must be changed. Also change the top level domain if it isn’t com.

General;MainUccName

The primary UCC name. An entry for this value must be present in UccConnections:ConnectionStrings. Example: ucc_main

General;DatabaseConnectionString

Connection string for the Microsoft SQL Server. Use the BridgServiceTool for this value. It is recommended that the Bridg service account has db_owner permissions.

CrmCRM stands for Customer Relationship Management and is a method/technology for managing contacts of customers. CRM helps to offer each customer an individual value proposition based on its wishes. In addition, CRM makes it visible which customers represent higher value for the organization and therefore might be served in a different way.;ConnectionString

The Dynamics 365 connection string. Use the BridgServiceTool for this value.

Crm;BaseContactQuery

Bridg requires at least this query to operate. Read Appendix B for more information about this query and the other CRM queries. Read Appendix C for the configuration of the PluginAttributes list which are used by these settings.

Important: modify the URL for Contact in the PluginAttributes list.

Warning Empty or remove any other settings starting with “Crm;”, especially “Crm;CallNotesQuery”.

 

Continue the Bridg service installation

Go back to the PowerShell prompt which is running InstallBridgService.ps1 and confirm that the settings are configured. The script will then install the Windows feature Application Initialization which will enable websites to automatically start when IIS starts.

The script will now ask for the password of the account provided in Properties.ps1. Other actions performed by the script will fail if the password is incorrect. Simply restart the installation if any errors occur.

The IIS application pool will be created next. The script will then modify the Web.config file and copy the Bridg service to the correct directory and add it as an application to the application pool. It will also enable preloading which, together with the Application Initialization feature, allows the Bridg Service to start when IIS starts.

The QR code used for configuring the app is created next. The script will store a link to this file in SharePoint for easy access. It can be found in the PluginSettings page. The key is App;ConfigurationUrl.

The script is now done. Time to verify the installation!

 

Verify installation

An iPhone or Android device is necessary to verify that the installation was completed successfully.

The following are links to the app stores:

Get it on Google Play
Get it on the App Store

Note A more detailed user guide for the Bridg app can be found here.

Read the instructions in the app. Scan the QR code using the app when it’s requested. A link to the QR code can be found on the PluginSettings page. The key is AppConfigurationUrl.

Please wait until the app shows that it is connected to the server.

Note: There is likely a problem with the Bridg service if the app hasn’t connected within approximately 30 seconds. Open a web browser and go to the BridgService URL. The configuration is incorrect if an error page is shown. Please follow the instructions on Configure the Bridg service settings and run the installation again. Please make sure that the service can be reached from the Internet by configuring the firewall. Follow instructions on "Firewall Settings for your network" for Windows Firewall.

Note: Please make sure that there aren’t any apps which intercept SMS are installed on the phone.

An SMS will be sent from the Bridg service to the phone during the registration.

Note: The SMS should arrive within one minute. Please verify in the Twilio portal that the SMS has been sent. Please follow the instructions on Configure the Bridg service settings if the SMS hasn’t been sent and run the installation again.

Please request a test notification when the app presents the opportunity. A notification will then be sent from the Bridg service to the phone. This should be within 10 seconds.

 

Configure the UCC for Bridg

The Bridg service pushes a notification about the incoming call to a Bridg app user using the phone number of the device. The phone number must be in the E.164 format. This can be configured in three ways:

  1. Configure a Forward skill with a phone number, read the Skills for more information about (forward) skills and how to create them.
  2. Add the phone number as an PSTN agent, Learn More
  3. Set up the Skype for BusinessSkype for Business (formerly Microsoft Office Communicator and Microsoft Lync) is an instant-messaging client used by Anywhere365. In order to use SFB, a Microsoft Skype for Business Server is required. Skype for Business is enterprise software; compared to Skype, it has different features that target businesses. client to forward calls to your mobile phone.

The notification will be sent to the device after the user has picked up the phone when using option 2 or 3. The Bridg app can also be used to call on behalf of the UCC when using either of these two options and a configured non-chat skill other than a Forward skill.

The app also allows transferring to non-chat skills other than Forward skills. Please read the Skills in the CoreThe Core is the center of Anywhere365. It manages all the Dialogues. manual to set up various skills. The next step is to create Modality endpoints for those skills. Read more about Modality endpoint and how to create them here.

Note:Adding / removing skills including Forward skills does not require a restart! Changes will be polled by the Bridg service in an interval configured on the PluginSettings page.

 

Verify the configuration

The best way to verify the configuration is to perform a test call. Register a device and set up a Forward skill. Set up the forward skill as an option in the IVRInteractive Voice Response (IVR) is a telephone application to take orders via telephone keypad or voice through a computer. By choosing menu options the caller receives information, without the intervention of a human operator, or will be forwarded to the appropriate Agent.. Read more about IVR here. Now call the UCC with your Skype for business client and select the option for the device in the IVR.

Note: Make sure that your address is known in the backend as an e-mail address. The Bridg service will strip the beginning of your Skype for business address (sip:) and perform the search. Read “Understanding Accounts and Contacts” for more information about contacts in Microsoft Dynamics. Also make sure that the account used by the Bridg service can access Microsoft Dynamics.

A notification should be visible on the device within 30 seconds after selecting the option in the IVR.

 

Troubleshooting

The Bridg service logs many of its actions. The logs can be found at: c:\inetpub\wwwroot\BridgService\logs

Always test the connection to the server when restarting the service using a phone, see Verify installation. This might take a while when multiple UCC’s are configured and SharePoint Online is used.

Warning Restarting the service will disconnect all devices!

Log level is DEBUG by default, set in the Web.config file in the BridgService directory. Change to VERBOSE for additional log events.

Warning Changing the Web.config file will restart the BridgService.

 

Appendix A – All settings

Note: Bridg can handle multiple UCC’s. It requires adding an entry in the first 3 settings.

Setting

Value

UccConnections:ConnectionStrings

Value: UCC name, ‘=’ the UCC connection string. Use the BridgServiceTool to create the SharePoint connection string

Example: ucc_main=Url=https://www.mycompany.com/sites/ucc/ucc_main;Username=username;Password=password;Domain=WORKGROUP

Add a UCC connection string for another UCC on a new line within this field.

HubAdapters;Dashboards

Value: UCC name ‘=’ the URL of the Dashboard service reachable by the BridgService.

Example: ucc_main=https://myserver.mycompany.com/DashboardService

Add another dashboard service for a different UCC on a new line within this field when applicable.

HubAdapters;Attendants

Value: UCC name ‘=’ the URL of the Attendant service reachable by the BridgService.

Example: ucc_main=https://myserver.mycompany.com/AttendantService

Add another attendant service for a different UCC on a new line within this field when applicable.

Twilio;AccountSid

See “Auth Token and how to change them”. The Account SID should start with “AC”.

Twilio;AuthToken

See “Auth Token and how to change them”. Use the BridgServiceTool for this value.

Twilio;PhoneNumberToSendSmsFrom

The bought Twilio phone number which is capable of sending SMS.

Timeline;ServiceUrl

Fully qualified URL to the Universal Timeline service. Must be reachable by the Bridg service.

Timeline;DialogueLimit

Maximum number of call dialogues to be shown in the timeline. The last dialogue is shown first. Default 50.

Timeline;PreviousContactsLimit

Maximum number of previous contacts to be shown in the app. Default 20.

General;PropertyServiceUrl

Fully qualified URL to CallPropertyManager.svc. Must be reachable by the Bridg service.

General;UccPollIntervalInSeconds

120

General;IntermediateUccDelayInSeconds

1

General;UccPhoneFormat

sip:{0}@mydomain.com;user=phone

mydomain must be changed. Also change the top level domain if it isn’t com.

General;MainUccName

The primary UCC name. Example: ucc_main

General;DatabaseConnectionString

Connection string for the Microsoft SQL Server. Use the BridgServiceTool for this value. It is recommended that the Bridg service account has db_owner permissions.

MemoryCaches;Session

slidingExpirationInMinutes=480

Note: Only change if memory usage is too high.

MemoryCaches;Registration

cacheMemoryLimitMegabytes=100

Note: Only change if memory usage is too high.

Crm;ConnectionString

The Dynamics 365 connection string. Use the BridgServiceTool for this value.

Crm;PhoneNumberFormat

The format used when searching the CRM when a call comes in. There are four values:

  1. E164: e.g. +0012345678. See “The International Public Telecommunication Number Plan”.
  2. International: e.g. +1 206-555-1234. Based on the E.123 International format. See official recommendation.
  3. Rfc3966: e.g. tel:+1-206-555-1234. See “The tel URI for Telephone Numbers”.
  4. Wildcard: do a wildcard search. Default.

Note: Change this setting if phone numbers are stored in any of the other formats to improve performance.

Crm;ShowStatus

Show what kind of contact is calling. Can be a Contact, Lead or Unknown. Default True.

Crm;DefaultPhoneNumberRegion

Iso 3166 alpha-2 code. Default ZZ.

 

There are six more settings, which are explained in detail in Appendix B

  • Crm;BaseContactQuery
  • Crm;BaseLeadQuery
  • Crm;BaseCaseQuery
  • Crm;ContactCaseFilter
  • Crm;CallNotesQuery
  • Crm;SetCallNoteQuery

Read Appendix C for the configuration of the PluginAttributes list which are used by these settings.

The defaults provide a solid basis for the initial setup, however the URL’s for Contact and Lead in the PluginAttributes list should be modified.

Important: create a field called “new_correlationid” in the phone call entity when using the call notes feature. It must a string/text field with a length of at least (maximum) 38. This feature also requires write permissions!

 

Appendix B – CRM queries

Dynamics 365 data is obtained through the use of FetchXML queries, please read "Build queries with FetchXML" for more information. Queries are created using base and filter queries and further completed using the attributes in the PluginAttributes list, see Appendix B.

  1. Crm;BaseContactQuery:

    By default the following base query:

    <fetch distinct='true' top='100'>

    <entity name='contact'>

    <link-entity name='account' from='accountid' to='parentcustomerid' link-type='outer' alias='account'>

    <link-entity name='contact' from='contactid' to='primarycontactid' link-type='outer' alias='account.owner'>

    </link-entity>

    </link-entity>

    </entity>

    </fetch>

    Note Top is mandatory and linked entities must have an alias.

     

  2. Crm;BaseLeadQuery:

    By default the following base query:

    <fetch distinct='true' top='100'>

    <entity name='lead'>

    <link-entity name='owner' from='ownerid' to='ownerid' link-type='outer' alias='account'>

    </link-entity>

    <filter type='and'>

    <condition attribute='statecode' operator='ne' value='1' />

    </filter>

    </entity>

    </fetch>

    Note Top is mandatory and linked entities must have an alias.

    Contacts have precedence over leads. A total of ‘top’ is returned. If there are less contacts, then leads are included until ‘top’ has been reached.

    Only contacts can have cases and the following settings must be present:

     

  3. Crm;BaseCaseQuery:

    By default the following base query:

    <fetch distinct='true' top='50'>

    <entity name='incident'>

    <order attribute='modifiedon' descending='true' />

    </entity>

    </fetch>

     

  4. Crm;ContactCaseFilter:

    By default the following base filter:

    <filter type="or">

    <condition attribute="contactid" operator="eq" value="[contactid]" />

    <condition attribute="accountid" operator="eq" value="[account.accountid]" />

    </filter>

    Note Condition attribute and value must be valid SystemName’s.

     

  5. Crm;CallNotesQuery:

    <fetch>

    <entity name='phonecall'>

    <attribute name='description' alias='note' />

    <filter type='and'>

    <condition attribute='new_correlationid' operator='eq' value='[callid]' />

    </filter>

    <link-entity name='activityparty' from='activityid' to='activityid' link-type='inner'>

    <link-entity name='contact' from='contactid' to='partyid' link-type='inner'>

    <attribute name='contactid' alias='agentid' />

    <attribute name='fullname' alias='name1' />

    <attribute name='mobilephone' alias='agentphonenumber' />

    <filter type='and'>

    <condition attribute='mobilephone' operator='not-null' />

    </filter>

    </link-entity>

    </link-entity>

    </entity>

    </fetch>

 

This assumes Bridg agents are in the contact entity table. The callid placeholder is mandatory. This will require the creation of a new attribute (new_correlationid) in Dynamics 365 of string/text type with a length of at least (maximum) 38 characters.

Further requirements:

  • An attribute with alias note;
  • An attribute with alias agentphonenumber.

Recommended:

  • One or more attributes with aliasX (where X is a number between 1 and 9);
  • An attribute with alias agentid.

 

  1. Crm;SetCallNoteQuery

    By default:

    <note>

    <placeholders>

    <query name='agent'>

    <fetch distinct='true' top='1'>

    <entity name='contact'>

    <attribute name='contactid' />

    <filter type='and'>

    <condition attribute='mobilephone' operator='eq' value='[agentphonenumber]' />

    </filter>

    </entity>

    </fetch>

    </query>

    </placeholders>

    <entity name='phonecall'>

    <attribute name='subject' type='string'>Call Registration [contacttitle] [callacceptedon(dd-MM-yyyy hh:mm:ss)]</attribute>

    <attribute name='description' type='string'>[note]</attribute>

    <attribute name='from' calloutbound='to' type='partylist' required='true'>[contactid]</attribute>

    <attribute name='to' calloutbound='from' type='partylist' required='true'>[query.agent.contact.contactid]</attribute>

    <attribute name='new_correlationid' type='string'>[callid]</attribute>

    <attribute name='phonenumber' type='string'>[callphonenumber]</attribute>

    <attribute name='directioncode' type='boolean'>[calldirection]</attribute>

    <attribute name='actualstart' type='datetime'>[callacceptedon]</attribute>

    <attribute name='actualend' type='datetime'>[calldisconnectedon]</attribute>

    </entity>

    <fetch distinct='true' top='1'>

    <entity name='phonecall'>

    <attribute name='activityid' />

    <attribute name='description' />

    <filter type='and'>

    <condition attribute='new_correlationid' operator='eq' value='[callid]' />

    </filter>

    <link-entity name='activityparty' from='activityid' to='activityid' link-type='inner'>

    <link-entity name='contact' from='contactid' to='partyid' link-type='inner'>

    <filter type='and'>

    <condition attribute='mobilephone' operator='eq' value='[agentphonenumber]' />

    </filter>

    </link-entity>

    </link-entity>

 

This XML defines how to create/fetch the call note entity and is directly related to the CallNotesQuery. Bridg provides the following placeholders:

callid, callphonenumber, callacceptedon, calldisconnectedon, calldirection, contactid, contacttype, contacttitle, agentphonenumber, bridgphonenumberid and note.

These can be further expanded by adding placeholder queries. Supported attribute types: string, boolean, datetime and partylist.

Note Requires write permissions!

 

Appendix C – PluginAttributes

This list contains the items which are shown to the user in the Bridg app. All items are grouped by the Category.

The PluginAttributes list contains the following columns:

Column

Meaning

DisplayName

The name of the property shown in Bridg.

SystemName

This must be the Dynamics 365 attribute. If it is part of a linked entity then the alias must precede the attribute.

ShowOnExtensionWindow

Indicate that the property is visible in Bridg. The main reason to set this to ‘No’ and still configure it as an item is when the property should not be shown, but is used in a Hyperlink.

Order

The order in which the property is to be shown. It is per Category, meaning the counting must restart for each Category.

FieldType

Zero or more field types, these are covered per Category later on.

Hyperlink

Make the property clickable with the Hyperlink specified. It is possible to include the value of a property in the Hyperlink. This is done by putting the value of a SystemName property in square brackets in the Hyperlink. For example if there is a property with the SystemName ‘Example’, then the URL becomes: http://www.example.com/?queryString=[Example]

OpenAutomatically

Ignored by the Bridg service.

Category

The Category for this item.

ShowOnToast

Indicate that the value should be shown in the call notification’s title.

Note it is possible to combine the values of several properties, for instance when a name is split up in multiple properties, e.g. a FirstName and LastName column. In this case both properties should have the same DisplayName and they should appear after each other in Order, e.g. 1 and 2.

Note Only Contact is mandatory to have items.

The items in the contact and lead category are the properties shown of a single contact or lead. It supports the following field types:

Field type

Description

Id

This field type in combination with a value in the Hyperlink column, will be shown as CRM link.

Name

The name of the contact which will be shown as the contact’s title.

PhoneNumber

The column contains phone numbers.

SipAddress

The column contains SIP-addresses.

Email

The column contains e-mail addresses.

Bridg can also show that a company is calling when there are multiple contact candidates that call from the same phone number. This requires configuring items for the Account category.

Note Do not include the account alias in the SystemName column.

Note Set order to 0 if it is an account attribute which is not linked to the account entity, e.g. companyname in the lead entity.

The field types of importance here are Name, PhoneNumber, SipAddress and Email. All items with the field type Name are combined to form the title. The property with any of the others is used as a subtitle.

Note Only contacts can have cases.

Note The DisplayNames in the case category are fixed. The following items are supported:

DisplayName

Description

Title

The title of the case. Multiple items can have this DisplayName.

Note: must have the Name field type.

Description

The description. Only a single item is allowed.

Date

Note: must have the Date field type to be used.

Status

The case status. Add field type FormattedValue to obtain the display name of this property.

It is also possible to add a ID field type to an ID item or any of the other items. The ID field type in combination with a URL in the Hyperlink column will be shown as a CRM link for each case.