OnCall IVR Engine v3.3.4, part of OnCall IVR Suite v3.3.x
IVR Engine Configuration Guide
Web Services Setup
Log on to the IVR Engine Server Host with a user account possessing local administrator privileges.
Launch the IIS Manager and open the menu tree at the left side of the screen to reveal the Application Pools.
Right-click the Application Pools item and select Add Application Pool...
- Name: Enter IVRWS as the name of the pool.
- .NET CLR version: Select .NET CLR Version v4.0.30319
- Managed pipeline mode: Select Integrated
- Start application pool immediately: check
Click OK, then right-click the newly created pool and select Advanced Settings...
Locate the Start Mode parameter within the General settings group and select AlwaysRunning.
Locate the Specific Times parameter within the Recycling settings group and specify the time of day with the lowest expected call load.
Locate the Identity parameter within the Process Model settings group and enter the user account configured to run the Windows Service components.
Click OK to close the Advanced Settings dialog – do not start the pool yet – and open the Sites and Default Web Site menu tree items.
Right-click the Default Web Site item and select Add Application...
- Alias: Enter the name of the application pool created earlier – IVRWS
- Application pool: Select the pool created earlier.
- Physical path: Browse to the installation folder of the IVRWS component. The default value should be C:\Program Files\Geomant\IVR\IVRWS
- Click OK to close the Add Application dialog.
Granting Write Permissions on the IVRWS Log Folder
Navigate to the IVRWS folder in a file explorer and open its Properties.
Go to the Security tab and check the user names.
Use Edit to manage the credentials and the related permissions.
Add the user account configured for the IVRWS application pool.
Assign Write permissions to the account on this folder.
Manage User Accounts in IIS Manager
This action can be done from IIS Manager, as well. Right-click on the IVRWS application pool to reach Edit Permissions, where user accounts can be managed the same way described above.
Updating the Web Services Configuration
Navigate to the IVRWS folder on the IVR installation path in a file explorer.
Open the web.config file in a text editor.
Update the configuration parameters to reflect your installation environment – use the parameter descriptions for guidance listed in the table below.
Open the IIS Manager and start (or restart) the IVRWS application pool to load the updated configuration.
The following IVRWS web.config
parameters must be set up:
Parameter | Location within config file | Value |
---|---|---|
nodeserviceurl | within appSettings |
The URL of the Node Service to use in a TCP format, e.g. "tcp://127.0.0.1:12977/NodeService" |
localannsfolder | within appSettings |
The full path of the local announcements stored on the host computer's filesystem. The default value is C:\Announcements |
localannenabled | within appSettings |
A switch controlling whether the local announcements feature is enabled or not. The default value is True. |
connection_string | within hibernate-configuration |
Database connection string containing the SQL server address and authentication methods. In case Windows Authentication is set, the string will have a Server=;Database=;Trusted_Connection=; format. The Trusted Connection should be set to True. In case SQL authentication is set, the string will have a Server=;Database=;User=;Password=; format instead. Database is the ucmaivr, User and Password is the Service Running user. |
file | within log4net / appender |
The full path of the IVRWS log file. This file specified must reside in the folder you granted the write permissions to in the previous steps. |
debug | log4net |
To enable or disable debug logging. The default value is False. |
level | within log4net / NHibernate and NHibernate.SQL |
The detail level of the logged information for these components and events. |
Component Server Setup (optional)
Log on to the IVR Engine server host with a user account possessing local administrator privileges.
Launch the IIS Manager and open the menu tree at the left side of the screen to reveal the Application Pools.
Right-click the Application Pools item and select Add Application Pool...
- Name: Enter IVRCompSrv as the name of the pool.
- .NET CLR version: Select .NET CLR Version v4.0.30319
- Managed pipeline mode: Select Integrated
- Start application pool immediately: check
Click OK, then right-click the newly created pool and select Advanced Settings...
Locate the Start Mode parameter within the General settings group and select AlwaysRunning.
Locate the Specific Times parameter within the Recycling settings group and specify the time of day with the lowest expected call load.
Locate the Identity parameter within the Process Model settings group and enter the user account configured to run the Windows Service components.
Click OK to close the Advanced Settings dialog – do not start the pool yet – and open the Sites and Default Web Site menu tree items.
Right-click the Default Web Site item and select Add Application...
- Alias: Enter the name of the application pool created earlier – CompSrv
- Application pool: Select the pool created earlier.
- Physical path: Browse to the installation folder of the Component Server component. The default value should be C:\Program Files\Geomant\IVR\IVRCompSrv
Click OK to close the Add Application dialog.
Granting Write Permissions on the Component Server Log Folder
Navigate to the IVRCompSrv folder in a file explorer and open its Properties.
Go to the Security tab and check the user names.
Use Edit to manage the credentials and the related permissions.
Add the user account configured for the IVRWS application pool.
Assign Write permissions to the account on this folder.
Updating the Component Server Configuration
Navigate to the IVRCompSrv folder on the IVR installation path in a file explorer.
Open the web.config file in a text editor.
Update the configuration parameters to reflect your installation environment – use the parameter descriptions for guidance listed in the table below.
Open the IIS Manager and start (or restart) the IVRCompSrv application pool to load the updated configuration.
The following Component Server web.config
parameters must be set up:
Parameter | Location within config file | Value |
---|---|---|
file | within log4net / appender |
The full path of the CompSrv log file. This file specified must reside in the folder you granted the write permissions to in the previous steps. |
component | within compsrv |
Any configuration parameter the 3rd party components might require. These are documented in the Developer's Guide. |
EndpointStateCheck | within compsrv / component |
This parameter – sitting next to all the other component related setting referred to above – will control whether the IVR Engine will monitor the state of its endpoints or not. For the endpoint status check to work, you the Endpoint Service configuration also needs to be updated with the "EnableOptions" parameter. You'll find further details in this article. |
If there is a 3rd party integration, the parameters of the 3rd party software has to be specified in this part of the component server's configuration file.
IIS Application Pool Recycling
Both the IVRWS and IVRCompSrv components are using a dedicated IIS application pool. The instructions on this page make sure these are configured to run permanently – as opposed to on-demand startup – thus staying ready for customer requests every time. When running permanently, IIS app pools are automatically 'recycled' on a daily basis. For this, you need to find a time during the day where the load is lowest.
License Server Setup
Deploy your license file into the LSMgr\lic folder of the IVR installation path.
Navigate to the LSMgr folder of the IVR installation path in a file explorer.
Open the LSMgr.exe.config file in a text editor.
Check and update the following configuration parameters as per your requirements:
- appSettings / port – the network communication port of the License Server. The default value is 18000.
- appSettings / ivrwsurl – the URL of the Web Service. The default value is
http://127.0.0.1/IVRWS/IVRWS.asmx
pointing to the local server computer. - logging details within the log4net / appender section. The default value is
<maxSizeRollBackups value="20">
,<maximumFileSize value="50MB">
In case the database login is set to use Windows Authentication, locate the Geomant IVR License Server Windows Service and assign the designated Windows user account for the Log On As identity.
Make sure this user account has Full Control permission on the lic and log folders under LSMgr.
Start or restart the Geomant IVR License Server Windows service.
Node Service Setup
Navigate to the NodeService folder of the IVR installation path in a file explorer.
Open the NodeService.exe.config file in a text editor.
Check and update the configuration parameters as per your requirements – use the parameter descriptions for guidance listed in the table below.
In case the database login is set to use Windows Authentication, locate the Geomant IVR Node Service Windows Service and assign the designated Windows user account for the Log On As identity.
Make sure this user account has Full Control permission on the log folder within NodeService.
Start or restart the Geomant IVR Node Service Windows service.
NodeService Configuration Parameters
Parameter | Location within config file | Value |
---|---|---|
port | within appSettings |
The network communication port of the Node Service. The default value is 12977 |
LicenseServer | within appSettings |
The IP address in "tcp:" form, the network port and service name of the License Server. The default value is tcp://127.0.0.1:18000/LSService which points to the local host computer. |
NoLicenseSipUri | within appSettings |
A SIP address where a call is forwarded in case all available licenses were consumed, and other configuration issues like incorrect tree administration. This parameter has no default value, you must set this explicitly. |
ivrwsurl | within appSettings |
The IP address in "http:" form, network port and service name of the Web Services. The default value is http://127.0.0.1/IVRWS/IVRWS.asmx which points to the local host computer. |
LogCallHistory | within appSettings |
Saves call information into the database. The default value is True. |
ValidateTree | within appSettings |
Forces a verification of the tree nodes, their connections, etc.. The default value is True. |
DumpTree | within appSettings |
Saves the entire menu tree XML into the log file for each call. The default value is True. |
maxSizeRollBackups | log4net / appender |
The number of log file copies to keep. The default value is <maxSizeRollBackups value="20"> |
maximumFileSize | log4net / appender |
The maximum size of the log files . The default value is |
EnableConversationID | within appSettings |
Enables to extract ce-convid SIP tag from call destination SIP address and use that value as conversation id in IVR. It can be useful when calls transferred from Contact Expert to the IVR. This parameter also enables to add ce-convid SIP tag with conversation id value to the transfer destination SIP address when using Trasnfer node. It can be useful when calls transferred from IVR to Contact Expert. Contact Expert is going to use ce-convid SIP tag value as conversation id. |
Endpoint Service Setup
Navigate to the EndPoint folder of the IVR installation path in a file explorer.
Open the UCMAIVR.exe.config file in a text editor.
Check and update the configuration parameters as per your requirements – use the parameter descriptions for guidance listed in the table below.
The Endpoint Service maintains the connection to the Microsoft Telephony infrastructure. Therefore, it has a lot more configuration parameters than the rest of the components. Please read through the following sections carefully.
In case the database login is set to use Windows Authentication, locate the Geomant IVR Endpoint Service Windows Service and assign the designated Windows user account for the Log On As identity.
Make sure this user account has Full Control permission on the log folder under EndPoint.
Start or restart the Geomant IVR Endpoint Service Windows service.
Sample Configuration Library
This version of Geomant IVR Engine comes with a sample Endpoint Service configuration file for each supported telephony infrastructure. Please find the sample config for your environment in the following folder:
C:\Program Files\Geomant\IVR\EndPoint\sampleconfig
Generic Endpoint Service Configuration Parameters
Parameter | Location within config file | Value |
---|---|---|
remotingport | within appSettings |
The network communication port of the Endpoint Service used by the Node Service. The default value is 12976. |
nodeserviceurl | within appSettings |
The IP address in "tcp:" form, the network port and service name of the Node Service. The default value is tcp://127.0.0.1:12977/NodeService which points to the local host computer. |
localserviceurl | within appSettings |
The IP address in "tcp:" form, the network port and service name of this particular Endpoint Service which is passed over to the Node Service for callbacks. The default value is tcp://127.0.0.1:12976/ResponseUnitSrv which points to the local host computer. |
mgmtport | within appSettings |
The network communication port of this Endpoint Service to provide services such as statistical information. The default value is 6010. |
workdir | within appSettings |
The filesystem path on the server computer where the announcements are cached temporarily. The default value is C:\Program Files\Geomant\IVR\cache. |
ivrwsurl | within appSettings |
The IP address in "http:" form, network port and service name of the Web Services. The default value is http://127.0.0.1/IVRWS/IVRWS.asmx which points to the local host computer. |
EnableOptions | within appSettings |
Activates an extra verification option before transferring a call to an endpoint at the expense of the extra time it introduces at every transfer. This is not an automatic feature, when enabled it must be called explicitly from the IVR tree before the transfer. |
Microsoft Telephony Specific Configuration Parameters
Parameter | Location within config file | Value |
---|---|---|
unattendedtransfer | within appSettings |
Alters the way Geomant IVR is passing over the call transfer duties to the Microsoft telephony infrastructure. When enabled, IVR is passing over the transfer control responsibility to the Microsoft telephony architecture. It is disabled by default. |
TrustedLyncDomains | within appSettings |
A space separated list of trusted communication domains – the local server FQDN is added automatically. |
TrustedOtherDomains | within appSettings |
A space separated list of other – non communication type – domains IVR will trust, it is empty by default. |
vmdetection.enabled | within appSettings |
Enables voicemail (answering-machine) detection for outbound calls. The default value is false. |
vmdetection.silence | within appSettings |
A technical parameter for proper vm-detection measured in milliseconds. The default value is 2000. |
vmdetection.speech | within appSettings |
A technical parameter for proper vm-detection measured in milliseconds. The default value is 4000. |
platformtype | within appSettings |
The Microsoft voice platform type governing the telephony integration method. The possible choices are: auto, client, server or standalone. Please see the below sections for further details of each choice. The Standalone platform setting is not relevant for Microsoft telephony, that is used to configure other types of SIP voice backend systems. |
Platform Type – Auto
If you wish to configure the platform to auto you will need to set the following parameters. This means that the Geomant IVR is deployed as an auto-provisioned Microsoft trusted application.
Parameter | Location within config file | Value |
---|---|---|
useragent | within appSettings |
SIP user agent description. The default value is LyncIVR . |
applicationid | within appSettings |
The ApplicationId parameter of the trusted application configured in the Microsoft Telephony system. This parameter has no default value, you must set this explicitly. |
Further description is detailed in the Further Configuration Steps for Auto-provisioned Installation section of this guide.
Platform Type – Client
The Client platform type avoids the whole trusted application concept. The IVR system is logging into the Microsoft Telephony platform as if it was a standard SfB (Lync) user.
The Client platform type can only be used for testing purposes. Geomant does not endorse nor does it support using this type for production environments!
These parameters have no default value, you must set them explicitly.
Parameter | Location within config file | Value |
---|---|---|
useragent | within appSettings |
SIP user agent description. The default value is LyncIVR . |
impersonatetransfer | within appSettings |
When enabled, and the MaxWait parameter is also configured in the transfer node(s) of the relevant IVR tree, then Geomant IVR will impersonate the caller when transferring the call from the IVR. It will appear as if the original caller transferred the call. The default value is False. This feature will not work if the MaxWait is not configured in the transfer node(s) of the IVR tree. |
endpoint.0.username | within appSettings |
The username of the SfB (Lync) user account used to log in to the Microsoft telephony infrastructure. |
endpoint.0.sipuri | within appSettings |
The SIPURI of the SfB (Lync) user account. |
endpoint.0.domain | within appSettings |
The Windows domain of the SfB (Lync) user account. |
endpoint.0.password | within appSettings |
The password of the SfB (Lync) user account, when entered in an "ENC:password" format, the system will read the clear text password, encrypt it and rewrite the parameter value to "DEC:password" where the "password" part will be encrypted. |
endpoint.0.reportpresence | within appSettings |
When enabled, the system will publish its availability on the IVR endpoint, so SfB (Lync) users will see its presence, e.g. "Available – IVR In Service". |
Platform Type – Server
The Server platform type is used when Geomant IVR is deployed as a manually provisioned Microsoft trusted application. In this case the Microsoft telephony infrastructure identifies the IVR trusted application via the gruu parameters (further details over at the IETF website for RFC5627).
Most of these parameters have no default value, you must set them explicitly.
Parameter | Location within config file | Value |
---|---|---|
gruu | within appSettings |
The gruu of the trusted application established in the Microsoft telephony infrastructure. |
cert | within appSettings |
The friendly name of the certificate used to connect to the Microsoft telephony infrastructure. |
useragent | within appSettings |
SIP useragent description. The default value is LyncIVR . |
port | within appSettings | The network communication port of the trusted application. The default value is 6000. |
localhost | within appSettings |
The FQDN of the server computer designated as the trusted application server in the Microsoft telephony infrastructure. |
impersonatetransfer | within appSettings |
When enabled, and the MaxWait parameter is also configured in the transfer node(s) of the relevant IVR tree, then IVR Engine will impersonate the caller when transferring the call off from the IVR, it will show up as if the original caller transferred the call. The default value is False . This feature will not work if MaxWait is not configured in the transfer node(s) of the IVR tree. |
endpoints | within appSettings |
The number of endpoints created by this instance of the IVR Engine – for each endpoint, the following parameters must be defined. |
endpoint.n.sipuri | within appSettings |
The SIPURI of this particular IVR trusted application endpoint. |
endpoint.n.proxyhost | within appSettings |
The FQDN of the SfB (Lync) front-end server computer (or pool). |
endpoint.n.proxyport | within appSettings |
The network communication port of the SfB (Lync) front-end server computer (or pool). |
endpoint.n.disablednsloadbalancing | within appSettings |
Disables the DNS load-balancing feature for the IVR endpoint. |
endpoint.n.reportpresence | within appSettings |
When enabled, the system will publish its availability on the IVR endpoint so SfB (Lync) users will see its presence, e.g. "Available – IVR In Service". The default value is true. |
endpoint.n.useregistration | within appSettings |
when enabled, Geomant IVR Engine will register itself at the Microsoft telephony architecture as a presence enabled application. |
Generic SIP Telephony Specific Parameters
Platform type – Standalone
The Standalone platform type is used to integrate with 3rd party telephony infrastructures – e.g. Asterix, or directly connected SIP clients – using pure SIP protocols only.
Parameter | Location within config file | Value |
---|---|---|
localhost | within appSettings |
The local host name used to build a SIPURI, e.g. sip:default@hostname . This can also be set to the local IP address if no ActiveDirectory or DNS is configured. Do not set this to "localhost" – in such cases set this to 127.0.0.1, but try to use a dedicated IP if possible. |
port | within appSettings |
The SIP network communication port of the Endpoint Service. The default value is 5060. |
standaloneserverport | within appSettings |
The SIP network communication port of the connected telephony infrastructure (e.g. a SIP PBX). The default value is 5060. |
standaloneserveraddress | within appSettings |
The IP address of the telephony infrastructure server (e.g. a SIP PBX) where the SIP INVITE messages are sent in case of outbound calls and transfers. |
mediaencryption | within appSettings |
This parameter controls whether and how the Endpoint Service cooperates in setting up an encrypted media channel (voice streams) with the telephony infrastructure of choice. The potential values are: Required – the Endpoint Service will not build up a media connection unless it can be encrypted. This might not work for all the telephony systems. Supported – the Endpoint Service attempts to set up an encrypted media channel, but falls back to non-encrypted if it fails. NotSupported – the Endpoint Service will only set up decrypted media channels. |
uuiformat | within appSettings |
This parameter controls the format of the UUI (https://tools.ietf.org/html/draft-ietf-cuss-sip-uui-17) to be passed over to the telephony infrastructure of choice, the possible values with this version of the Geomant IVR Engine are: UCMA, AvayaShared, AvayaProvider. |
Further Configuration Steps for Auto-provisioned Installation
Deploying the OnCall IVR Engine as an auto-provisioned Microsoft Telephony application is the preferred method as this provides the most flexibility and efficiency in terms of operational maintenance. The trusted application endpoints do not need to be individually configured in the IVR because the software is part of the Microsoft Telephony topology and all the endpoint data is automatically replicated on to the IVR server.
Running IVR Services Under a Named Account
Both the IIS web application pools as well as all Windows Service components must be configured to run in the name of a domain account. This is required in this case because there are certain Microsoft permissions that must be granted explicitly to OnCall IVR to be able to work in auto-provisioned mode.
Tip
It is best to place the service running account in the corporate domain.
Assigning Permissions to the Service Running Account
Please follow these steps in order to assign the necessary permissions:
Assign the service running account to the RTCComponentUniversalServices group.
- In case the service running account is not a domain account (but is created on the IVR Engine server locally instead), then you need to assign the account to the local RTC Component Local Group (which is a member of the RTCComponentUniversalServices domain group).
Assign the service running account to the local Administrators group on the IVR Engine server host computer.
Enabling Windows Authentication for the IVR Engine
Although it is not mandatory to do so, Geomant advises to use an Active Directory user account to run the Windows Services, the web applications, and also to have the IVR Engine log in to the database with this account. In order to do this, please alter the IVR Engine configuration accordingly:
Log on to the IVR Engine host computer with a local or domain administrator account.
Change the Identity field of both the IVRWS and IVRCompSrv web application pools to the designated Active Directory user account in the Internet Information Services Manager. See exact steps in the Web Services Setup and Component Services Setup chapters above.
Stop and then restart both application pools in IIS Manager.
Assign the Active Directory user account to the local Administrators group on the IVR Engine host computer.
Register the same Active Directory user account in the Microsoft SQL Server providing the IVR Engine database.
- Launch SQL Server Management Studio and log on to the IVR Engine database server with system administration level user account.
- Open the Security node in the Object Explorer panel and right click Logins.
- Select New Login... and add the Active Directory user account to the Login Name (use the Search button to make sure you do not make typing mistakes).
- Set the Default database: drop-down to the IVR Engine database (default name is ucmaivr).
- Click User Mapping in the Select a page panel and set the checkbox in the Map column for the IVR Engine database (ucmaivr).
- Click OK to close the New login window.
Locate the web.config file under the IVRWS folder of the IVR Engine install path and change the connection_parameter as per the description in the Updating the Web Services config file chapter above.
Launch the Services administration tool and perform the following changes for the Geomant IVR Endpoint Service, Geomant IVR License Server and Geomant IVR Node Service components:
- Double-click on the designated item.
- Click the Log On tab and click the This account: radio button.
- Enter the Active Directory user account manually or use the Browse button to find it in the domain – then enter the password and click OK.
- Stop and start each service after the change.
Enabling Windows Authentication for the IVR Engine Administration Web Page
In addition to the above steps, you can also force Windows Authentication for accessing the Administration website of the IVR Engine:
Log on to the IVR Engine host computer with a local or domain administrator account.
Launch IIS Manager and navigate to the IVRWS virtual application node under the Default Web Site node in the Connections panel.
Click the IVRWS node and double-click the Authentication configuration icon in the IIS section at the right.
Disable the Anonymous Authentication option.
Enable the Windows Authentication option.
Right-click the IVRWS node in the Connections panel and select Edit Permissions... item.
Click the Security tab and add the Active Directory user account (or an encompassing AD security group) with Read & Execute permissions for every user that you want to grant access to.
Depending on the security settings of the web browser you are using to access the IVR Engine Administration website, you might not receive a login dialog when you logged in to your Windows OS with an Active Directory user account that is configured to access the site with the above procedure.
Administering the Endpoint in IVR Administration
After installation and configuration is finalized, you need to administer the newly created endpoint(s) in IVR Administration.
Follow the steps described in the Administration of IVR Flows Using IVR Administration article.