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

Use an Administrator account for installation. Unzip the Bridg service zipfile.

ConnectionStringCreator

Some connection configuration values must be created using the ConnectionStringCreator tool found in the ConnectionStringCreator folder.

  • It is a command line tool. Open PowerShell and start the ConnectionStringCreator.exe with arguments to use it.
  • Start with argument /? to check the usage.
  • This document will provide notes when to use the tool to set the value of a setting.

Tip select the created connection string using the mouse and press Enter to copy the connection string to the Clipboard.

 

TwilioAuthTokenEncrypter

Tool to encrypt the Twilio auth token to store it securely in SharePoint found in the TwilioAuthTokenEncrypter folder.

  • It is a command line tool. Open PowerShell and start the ConnectionStringCreator.exe with arguments to use it.
  • Start with argument /? to check the usage.
  • This document will provide notes when to use the tool to set the value of a setting.

Tip select the encrypted auth token using the mouse and press Enter to copy the value to the Clipboard.

 

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 install directory
  3. Run the script called InstallBridgService.ps1
    1. Configure SharePoint when asked
    2. Continue installation when SharePoint is configured

 

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!

  1. Add or edit UCC connections

    Every unique UCC must have an accompanying entry in the UccConnections;ConnectionStrings item.

    Edit the existing UccConnections;ConnectionStrings item with the Bridg scope.

    Value: UCC name, ‘=’ the UCC connection string. Use the ConnectionStringCreator tool 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.

     

  2. Add or edit attendant and dashboard hub adapters/services

    The Bridg service can handle multiple Dashboard and Attendant services. At least one of each is required.

    Edit the existing items with the scope Bridg

    Setting: HubAdapters;Attendants

    Value: UCC name ‘=’ the fully qualified URL of the Attendant service, e.g. https://myserver.mycompany.com/AttendantService

    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.

    Setting: HubAdapters;Dashboards

    Value: UCC name ‘=’ the fully qualified URL of the Dashboard service, e.g. https://myserver.mycompany.com/DashboardService

    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.

     

  3. Edit Twilio settings

    Edit the existing items on the PluginSettings page with the scope Bridg.

    Setting

    Value

    Twilio;AccountSid

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

    Twilio;AuthToken

    The Twilio auth token. See “Auth Token and how to change them” for more information.

    Note Use the TwilioAuthTokenEncrypter tool for this value.

    Twilio;PhoneNumberToSendSmsFrom

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

     

  4. Edit Timeline settings

    Edit the existing items on the PluginSettings page with the scope Bridg.

    Setting

    Value

    Timeline;ServiceUrl

    Fully qualified URL to the Universal Timeline 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.

     

  5. Edit General settings

    Edit the existing items on the PluginSettings page with the scope Bridg.

    Setting

    Value

    General;PropertyServiceUrl

    Fully qualified URL to the CallPropertyManager.svc

    General;UccPollIntervalInSeconds

    120

    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. Example: my_ucc

    General;DatabaseConnectionString

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

     

  6. Edit MemoryCaches settings

    Edit the existing items on the PluginSettings page with the scope Bridg.

    Setting

    Value

    MemoryCaches;Session

    slidingExpirationInMinutes=480 Only change if memory usage is too high.

    MemoryCaches;Registration

    cacheMemoryLimitMegabytes=100 Only change if memory usage is too high.

     

  7. Edit CRM settings

    Edit the existing items on the PluginSettings page with the scope Bridg.

    Setting

    Value

    Crm;ConnectionString

    The Dynamics365 connection string. Use the ConnectionStringCreator tool to generate.

    Crm;PhoneNumberFormat

    The format to use when searching the CRM for a contact when a call comes in. There are four values:

    1. E164: e.g. +0012345678. Please read “The International Public Telecommunication Number Plan” for more information.

    2. International: e.g. +1 206-555-1234. Based on the E.123 International format. Please read the official recommendation for more information.

    3. Rfc3966: e.g. tel:+1-206-555-1234. Please read “The tel URI for Telephone Numbers” for more information.

    4. Wildcard: do a wildcard search. Default option.

    Important: 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, which can be a Contact, Lead or Unknown. Default is False.

    Crm;DefaultPhoneNumberRegion

    Iso 3166 alpha-2 code. Default ZZ.

 

The BridgConfigurationInitializer also creates 4 more settings, which are explained in detail in Appendix A:

  • Crm;BaseContactQuery
  • Crm;BaseLeadQuery
  • Crm;BaseCaseQuery
  • Crm;ContactCaseQuery

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

The defaults provide a solid basis for the initial setup.

 

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.

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

The following are links to the app stores:

Get it on Google Play
Get it on the App Store

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.

During the registration an SMS will be sent from the Bridg service to the phone.

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. Read "Formatting International Phone Numbers" for more information about the 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. Read Agents for more information about agents and how to add them.
  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. / LyncMicrosoft Lync (formerly Microsoft Office Communicator) is an instant messaging program designed for business use and is the successor of Windows Messenger. In order to use Lync, a Microsoft Lync Server is required. client to forward calls to your mobile phone. Read "Set Call Forwarding options in Skype for Business" for setting up call forwarding in Skype for Business.

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!

 

Appendix A – 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.

 

Appendix B – 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.