Installation and administration

Requirements

Workstation

DesktopClient is a thick desktop application for Windows built on the .NET and WPF technologies. Therefore, it does not pose any special workstation requirements.

Network settings for ProServer

DesktopClient requires the possibility to connect to ProServer. You can set the location of the ProServer and the port (the default for TCP is 18321) with the PbxParameters configuration parameter.

Network settings for softphone

If you are going to use the embedded softphone, you must enable SIP communication with the server. See Network communication.

Installation

The DesktopClient application itself does not require installation. Copy the application build folder to the target computer, then just run iCC.DesktopClient.exe.

You must install the Microsoft Edge WebView add-on for the chat elements of the application to function properly. It allows the application to natively open a web interface that provides ReactClient functionality.

  • Navigate through the link to the add-on website

  • Choose the appropriate installer according to the operating system architecture

  • Restart your computer after the installation

Note

It is advisable to keep this add-on up to date due to security threats. On the other hand, it is always advisable to test the functionality with a given Desktop client build on one specific computer before deploying a new version on all computers. After a successful test, then deploy to the remaining ones.

System settings for application integration

Attention

When integrating the application, it is necessary to modify the DeletePerso'' script on the installation so that it does not delete the data related to the DesktopClient. The ``Perso table contains saved application bar definitions and reaction definitions (each agent has its own definitions). The database RefName for these definitions is ProCaller#RibbonDefinition and ProCaller#EventHandlingDefinition.

Steps required to integrate the application:

ProServer settings

DesktopClient does not communicate with FrontStage directly, but via ProServer. The station must therefore have network access to ProServer and have DesktopClient set appropriately.

The username and password are not required since the application uses Windows authentication and the current user is sent to ProServer. For workstations connected to a domain, these are usernames in the form domain\name (e.g. acmecorp\johndoe).

In the ProServer administration in the Agents section, create an account necessary for the connection as follows:

  1. In the Agents section, name the account in the Name field with the name of the agent or the like.

  2. In the Credentials section, add or edit the entry as follows:

    • Enter the username in the System Name field as it is sent by Windows authentication from stations (e.g. acmecorp\johndoe) (see above).

    • In the Application field, select iCC.DesktopClient

  3. In the Permissions section, add the necessary roles. Usually UseChannels a ExtensionCTI.

  4. In the Data Items section, add or modify the entry as follows:

    • Enter UserData in the Key field

    • In the Application field, select iCC.DesktopClient

    • In the Data field, enter a string in the style of <?xml version="1.0" encoding="utf-8"?><UserData><IdentityCC>agent login< /IdentityCC></UserData>, e.g.

      <?xml version="1.0" encoding="utf-8"?><UserData><IdentityCC>fs-sql_demo\jelinek</IdentityCC></UserData>

      See System Name.

Tip

In the Stations section, you can track several recent DesktopClient connections.

Definitions for the database

In the Perso database table, it is necessary to upload the bar definition and the reaction definition for the users who are to use the application. The definitions are saved in the json format.

Database entries and their RefName:

  • Ribbon definition - ProCaller#RibbonDefinition

  • Response definition - ProCaller#EventHandlingDefinition

Local configuration file

The configuration parameters for the connection are set for each computer separately. The file name is appsettings.json; it is located in the application folder. A local settings in the config file has lower priority than workplace settings in the database, if both places contain the same parameter, the database one will be used.

WebRTC

For locally usable parameters see WebRtcConfiguration section. At least ServerUrl parameter is mandatory.

SIP

The following information needs to be filled in:

Login

Agent has to be able to login using the application. You can set this via Agent visual editor.

Workplace

Workplaces which are supposed to work with the DC app have to log-in to the ProServer as a softphone. In ReactAdmin, Agents ‣ Workplace section, Softphone configuration (JSON) field, set the json softphone object. The order of the parameters in the object does not matter.

WebRTC

To be able to log-in from DC to AS7 it is necessary that PhoneType parameter is in a format PhoneName_DC (connection won’t work without the “_DC” stated)

An object example:

{"PhoneType": "AS7anCTI_DC", "Password": "password", "UserName":"user@user.com", "ServerUrl": "https://server.atl.com/cti/ancti/ancti.js", "DeviceName": "sip:555@stat.777", "HoldOnDirectCti": false}

For possible parameters and their meaning see WebRtcConfiguration section.

SIP

An object example:

{"PhoneType": "SWPSIP", "SipServer": "192.168.1.221", "Password": "xyz", "UserName":"420"}

The object will also include other attributes with the SIP server location, verification, etc. (see Configuration).

LiteralLookup set

For the correct rendering of all texts in the application, it is a good idea to always upload an up-to-date set of LiteralLookup texts to the database. This will limit the situation where only the system LiteralText is displayed in the application, without the corresponding text, for the given language.

Network communication

WebRTC

Communication via internet, see Network communication

SIP

Enable network communication between the station and the PBX specified in Softphone configuration (JSON). It is normally handled by the FrontStage network specialist, see Network communication.

Basis for user statistics

If you want to fill statistics for individual users, you need to set the following:

  1. BroadcastDataQueries - in the administration, set the parameter to true (if you set it on an already “live” installation, you must then restart the synchronous service - the parameter is loaded at start-up)

  2. Create a database query (Administration, section Data queries) that returns the required columns for statistics

    • The Validity interval item must be set for the query

    • The query is always called after the specified interval; it is evaluated as a whole and the data is distributed to individual agents in their applications

    • It must contain the AgentId control column to allow data binding

  3. You must assign the created database query to a specific agent

    • In the administration in the Agents section, fill in the DQ in the bar parameter

Note

After creating a new database query, check that the indexes are set correctly. This will prevent complications due to increased computing power on the server side.

Default sound device (WebRTC only)

See Default communication device.

Configuration file

The appsettings.json configuration file contains many settings, but most of them do not usually need to be edited. The only exception is the connection to ProServer. The file is in the JSON format.

Important

The configuration file is extensive. Do not edit sections outside this description - they are not meant to be configured by users. Make sure to follow the syntax of the JSON file, such as nesting elements, enclosing attributes in quotes, etc.

configuration.SoftphoneConfigurationSection section

Section dedicated to Built-in softphone and its settings.

Parameter

Description

PhoneType

Softphone device. The only option for now is SWPSIP, which activates the built-in softphone.

UserName

SIP server login.

Password

SIP server login password.

SipServer

SIP server DNS/IP address.

SipPhone_Agent

User-Agent header inserted into SIP messages.

Recomended value for:

  • MXONE is Aastra 6867i/5.1.0.2040

  • A5000 is Mediant VE-H SBC/v.7.20A.256.024

RegistrationExpiration

Registration renewal interval [sec]. Maximum value 3600. Will be inserted into SIP REGISTER message.

KeepAliveSipPacketInterval

Interval odesílání SIP keepalive paketů v sekundách. Parametr pomůže při řešení potíží se zavíráním spojení při neaktivitě.

  • 0 pro zákaz

  • >1 interval v sekundách

  • minimálně 30 sekund

KeepAliveRtpPacketInterval

RTP keepalive packet sending interval [sec]. It can help troubleshooting the RTP stream closing problem occuring during inactivity.

  • 0 for disabling

  • >1 interval in seconds

  • 15 seconds is minimum

PeriodicReconnect

Whether to register again, after the interval has passed. Ignored, if already registered. Use this parameter only when experiencing network issues and softphone is beign disconnected periodically.

  • values true or false

PeriodicReconnectInterval

Interval, after the device should be registered again [sec], if the PeriodicReconnect is enabled.

ToneEmulation.BusyHere486

If the customer is trying to reach an occupied phone, he will hear a “busy tone”. Values true or false

ConnectionChecker

Whether to reconnect, after the interval has passed. Softphone will check the connection during a network error (internet or LAN connection). This param can cause trouble when using the A5000 PBX.

  • values true or false

ConnectionCheckerInterval

Interval [sec], after which reconnect,if the ConnectionChecker param. is enabled.

EnableReliableProvisional

Whether to use PRACK.

  • values true or false

WindowScale

Softphone window scale option. For example 0.8 pro low resolution screens, 1.3 for high resolution screens (in case UI is too small). Recommended value is 1.

Tip

If you set the value to 0, softphone will be completely hidden. Notification window, during the incomming call will remain vissible.

AudioCodecs

Supported voice communication codexes.

Note

Keys listed in XML as a nested elements. For example. AudioCodecs.AUDIOCODEC_PCMU is

<AudioCodecs>
   <AUDIOCODEC_PCMU>true</AUDIOCODEC_PCMU>
   ...
</AudioCodecs>

Available keys (true or false):

  • AUDIOCODEC_PCMU – PCMU/G711-law 8KHZ 64kbit/s.

  • AUDIOCODEC_PCMA – PCMA/G711 A-law 8KHZ 64kbit/s.

  • AUDIOCODEC_G729 – G729 8KHZ 8kbit/s.

  • AUDIOCODEC_ILBC – iLBC 8KHZ 30ms-13kbit/s 20 ms-15kbit/s.

  • AUDIOCODEC_GSM – GSM 8KHZ 13kbit/s.

  • AUDIOCODEC_AMR – Adaptive Multi-Rate (AMR) 8KHZ (4.75,5.15,5.90,6.70,7.40,7.95,10.20,12.20)kbit/s.

  • AUDIOCODEC_G722 – G722 16KHZ 64kbit/s.

  • AUDIOCODEC_SPEEX – SPEEX 8KHZ (2-24)kbit/s.

  • AUDIOCODEC_AMRWB – Adaptive Multi-Rate Wideband (AMR-WB)16KHZ (6.60,8.85,12.65,14.25,15.85,18.25,19.85,23.05,23.85)kbit/s.

  • AUDIOCODEC_SPEEXWB – SPEEX 16KHZ (4-42)kbit/s.

  • AUDIOCODEC_G7221 – G722.1 16KHZ (16,24,32)kbit/s.

  • AUDIOCODEC_OPUS – OPUS 48KHZ 32kbit/s.

Ports

Setting supported voice communication codecs.

Note

Keys are in XML as a nested element. For example, Ports.MinimumRtpAudioPort is

<Ports>
   <MinimumRtpAudioPort>...</MinimumRtpAudioPort>
   ...
</Ports>

Available keys:

  • MinimumRtpAudioPort, MaximumRtpAudioPort – Range of ports for RTP protocol communication. Default is 7002-7810, range 10402-10800 reserved for future use.

UseMxoneStrategy

Mandatory parameter when using MX ONE PBX. When experiencing sound trouble on some MX devices, allow this parameter. Otherwise leave off, so no extra SIP packets are being created.

UseA5000Workarounds

Used for troubleshooting when A5000 PBX is used. If you experience “autoanswer/Call.Hold / Call.Unhold” or sound problems, enable this.

Use571MxoneExternalCallRefresh

Obsolete, replaced by UseMxoneStrategy

When experiencing sound problems on some MX ONE versions, enabling can solve the problem. Otherwise leave off, so no extra SIP communication is being created.

ManualAastraMacAddress

If defined, this MAC address will be used for softphone. Otherwise, local network adapter address (NIC) is used.

SeedAastraMacFromExtension

_(‘’)

A5000AastraId

“X-Aastra-Id” header within SIP communiction. If any is set, it will be used instead of the generated one.

UseFakeRegistrationToCheckPassword

Obsolete. Only for testing purposes, otherwise not recomended to use.

RegistrationSecretEnabled

If allowed, A5000 PBX will send the OK status even when the credentials are not valid. As a part of this settings, configuration items are not sent.

This functionality controls the hidden string in configuration item (key defined in RegistrationSecret).

If not allowed, softphone can generate “false-positive” registration result, even if the action failed.

RegistrationSecret

Key for RegistrationSecretEnabled. Must be sent from PBX, if the registration was succesfull. The app checks “NOTIFY” messages with application/xml content.

RegistrationSecretWaitTimeMilliseconds

When sending the credentials, application waits for here defined interval, if it receives RegistrationSecret at least in one A5000 request.

Valid range is 500 - 10000 (recomended value is 6000).

AEC

Enable/Disable “Acoustic Echo Cancellation” function.

VAD

Enable/Disable “Voice Activity Detection” function.

CNG

Enable/Disable “Comfort Noise Generator” function.

AGC

Enable/Disable “Automatic Gain Control” function.

ANS

Enable/Disable “Audio Noise Suppression” function.

VideoNackStatus

Enable/Disable “NACK” function, which hjelps with video quality. Currently not usable.

DoNotDistrurb

Enable/Disable “Do not disturb” mode.

SipServerPort

SIP port for communication with the server.

  • for softphone with address 10.99.218.81 - port UDP 5060

  • for softphone with address 10.99.218.84 - port UDP 10000 - 20000

AuthName

User name for authorization (usually the same as the user name). Some PBXses do not need this value to be set.

DisplayName

User nickname, can be any value. Optional.

SipLogLevel

Log level.

  • -1 logging not active

  • 1 to 4 determines the level, where 4 means we log everything.

If the parameter LogDirectory is not set, logging is off regardless of this option.

LogDirectory

Log file folder. If not set, logging is turned off (if you enter this value <LogDirectory xsi:nil="true" /> it has the same meaning as “off”)

Path to the folder should be valid and DC app should have the rights to access it. The path string can be filled with system variables, for example: <LogDirectory>%localappdata%\atlantis\DC_Logs</LogDirectory>.

ProductVersion

Backup value, if the build number is not readable. If not needed, whole tag can be deleted.

StunServerPort

STUN server port. Can be turned off by omitting the value or writing in the xsi:nil="true" string.

TransportType

Transfer type for SIP communication.

Valid values:

  • UDP (for softphones with the addess 10.99.218.81 a 10.99.218.84)

  • TCP

  • TLS

At the same time, it is needed that port 18321 is enabled, for the server communiction purposes.

PlaybackDeviceVolume

Default volume level for playback device. The higher priority has the user settings tied with the Windows profile. Valid range is 0 - 255. Can be turned off by entering the xsi:nil="true" value.

RecordingDeviceVolume

Default volume level for recording device. The higher priority has the user settings tied with the Windows profile. Valid range is 0 - 255. Can be turned off by entering the xsi:nil="true" value.

UseVirtualizedAudioDevices

For testing purpose on the devices, where physical playback device is not possible (softphone expects any playback device, if not found, it will return a warning message).

If on, the function will force the usage of a virtual playback device.

After finishing the test, turn this functionality off!

WebRtcConfiguration section

Softphone “WebRTC” configuration.

Parameter

Description

PhoneType

When AS7 used, the values is always “AS7anCTIupd_DC”

UserName

AS7 user ID with ctiDeviceId right assigned

Password

User password, see above

ServerUrl

Direct URL address to the ancti.js library which runs the WebRTC backend. AS7 is a multitenant app, so the value for this parameter can be the same for more FS instances.

DeviceName

Terminal and workplace identification. Syntax - sip:extension_number@term.id_of_terminal, e.g. sip:165@term.262

HoldOnDirectCti

Indication, whether the call HOLD should be performed locally instead of by CSTA operation (temporary solution till release 5.9)

RecordingDeviceId

Windows registered device ID for recording the sound. Optional parameter. If empty, the application will set it automatically after the user selects one.

PlaybackDeviceId

Windows registered device ID for playing the sound. Optional parameter. If empty, the application will set it automatically after the user selects one.

PlaybackDeviceVolume

Volume level of PlaybackDeviceId, ranges from 0 to 255 or NULL.

RecordingDeviceVolume

Volume level of RecordingDeviceId, ranges from 0 to 255 or NULL.

configuration.applicationSettings'' section

Parameter

Description

PbxParameters

ProServer connection string. values divided by commas, blank spaces among the values, the order is: <host>,<port>,<timeout>.

  • mandatory

  • type: string

  • example: frontsrv,18321,20000

Where:

  • host can be IP or DNS

  • for ProServer 3.15+ the port value should be a negative number (default ProServer port is 18321)

  • timeout in miliseconds

InstanceName

The name of the instance to connect to the ProServer. This is usually the hostname of the remote server.

If the DesktopClient and ProServer are on the same machine, you can use the value #MACHINENAME# to replace the hostname of the machine you are running the DesktopClient from (not the remote one).

DebugIndicators

Logging level and it’s settings. Possible values: App, Detail. Separate the inserted values by commas.

StartMinimized

Settings, which determines the application rendering mode after start. Possible values: True, False

  • True - app started as minimized with minimum possible UI

  • False - standard behaviour, ribbon displayed

ScalingOptions

The value list, which will be available as the scaling options for DesktopClient’s ribbon. This can be increased/decreased in proportion to the operating system display settings.

Default list: 0.6|0.75|0.8|1|1.25|1.5

Inserted numbers will be presented percentually to the user, which means 0.6 = 60%

DCWindowMode

Application bar anchor.

  • docked - the bar is docked to the top or bottom of the screen (depending on the user’s settings)

  • floating - a floating Windows window that can be moved anywhere

RunOnboardingRoutine

Controls “onboarding” in the application.

If true the application will attempt to retrieve the configuration from the licensing site, which will then provide the necessary login information.

If false is deactivated.

OnboardingSuccess

Parameter filled automatically after successful completion of “onboarding”. Values true or false.

ReactClientOnboardingUrl

Address of the server where the request for login credentials is sent. E.g. https://fronstage.cz/api/onboarding/accept/dc/onboardingKey

ReactClientFileResourceUrl

Link where the logo displayed on the splashscreen is downloaded. E.g. https://frontstage.cz/api/content/logo/fname

ReactClientTextResourceUrl

Link from where the text displayed on the splashscreen is downloaded. E.g. https://frontstage.cz/api/content/text/fname

system.diagnostics section

DesktopClient can log its activity, which is useful for troubleshooting.

Note

The built-in softphone has own logging.

In the default configuration file, the logging of DesktopClient activity is commented out. To enable

  1. Uncomment or create a configuration/system.diagnostics section as per the example below.

  2. Set the file path in the initializeData attribute.

    • The file path should exist and DesktopClient should have the right to create a file there.

    • If the file already exists, additional log messages will be added at the end.

    • A relative path will be evaluated as relative to the location of iCC.DesktopClient.exe.

    • The absolute path can use environment variables, such as %localappdata%\atlantis\DC_Logs\iCC.DesktopClient.log.

 <system.diagnostics>
  <trace autoflush="true">
    <listeners>
      <add name="textListener"
          type="Atlantis.General.Common.TextWriterTraceListener,General.Common"
          initializeData="iCC.DesktopClient.log" />
    </listeners>
  </trace>
</system.diagnostics>

Important

Enabled logging generates files not bigger than tens of megabytes a day, which consumes some of the computer storage over time. If the computer has a limited storage capacity, it’s necessary to ensure they are periodically deleted. Enabled logging has minimal performance impact on the computer.

configuration.userSettings section

User interface configuration.

  • It is read only on the first start-up. The point is to prepare a configuration in the XML file in the installation that is as convenient as possible for everyone. And then distribute this installation.

  • The configuration is copied to the user’s profile the first time it is run. On subsequent runs, the configuration is no longer read from the XML!

  • To delete a copy, erase everything in the folder %localappdata%\Atlantis\iCC.DesktopClient.exe_Url_<hash><verze>. Např. C:UsersjelinekAppDataLocalAtlantisiCC.DesktopClient.exe_Url_gnkzcm2ntgqebnpp2xoywawuif0kqyto3.19.8042.10914>

Note

The Softphone_* parameters control the user interface of the built-in softphone, not the softphone itself.

Parameter

Section

Description

Softphone_PlaybackDeviceIndex

user

Playback device index

Softphone_RecordingDeviceIndex

user

Recording device index

UpgradeRequired_User

user

Sign which determines, whether it’s required to perform the configuration upgrade.

Softphone_PlaybackDeviceVolume

user

Playback device volume

Softphone_RecordingDeviceVolume

user

Recording device volume

Wnd_Softphone_Topmost

user

Sign, whether DesktopClient should be always above Windows apps in the operating system.

Wnd_Softphone_ShowInTaskbar

user

Sign, whether the DesktopCLient app should have the tray icon visible. If False, the icon will be there anyway, but only in the hidden icons area.

RingtoneDeviceId

user

Ringtone device ID. Can be also set within the DC app - Ribbon designer ‣ Global settings

ApplicationScale

user

Scale value for the initial run. If the user then changes the scale, the new value will be saved to Perso database table and this parameter is no longer considered. The default is 1, which means 100% (only one inserted value possible). Related to ScalingOptions.

LastUsedCultureCode

user

Last used localization. If not set the application will set it automatically based on your language. The parameter can be used to force specific localization, for example - en-US, cs-CZ, and so on.