Configuration
This topic contains detailed configuration steps required to capture calls with Alvaria DRS-3P.
Note
Only configuration settings relevant to this integration are listed. Leave all other settings set to their default values.
This topic covers the Alvaria and CTI Triggered Recording components and is intended to be used alongside a supported Communication Recording Agent recording integration, such as SIPREC. As a result, additional configuration steps may be required — refer to the Integration Guidelines for the relevant telephony platform here.
Step | Reference | Description |
|---|---|---|
1 | Configure the Integration Adapter on the Collector. | |
2 | Create the Alvaria CTI Server configuration file (CTIServer_Noble.config) on the Collector. | |
3 | See the relevant Integration Guidelines topic for the integration that Alvaria sits on top of. | Complete the telephony integration dependent configuration steps for audio capture, such as RTP Configuration. |
4 | See the relevant information and configuration for adding or removing devices for call capture. |
Additionally, see Log Files for information on configuring log files.
Configure the Integration Adapter
The Integration Adapter configuration is specified in IntegrationAdapter.ini and Identity.ini. These files are automatically generated with default values when the Collector is started for the first time.
Note
Only configuration settings relevant to this integration are listed here. For all other settings, leave these set to their default values.
IntegrationAdapter.ini
[General] DownstreamAPIVersion=1 RecordByDefault=1 [JetStream] ServerURL=nats://u-capture.example.com:4222 [VoiceActivityDetection] WindowSizeMS=10 UseShortTermEnergy=1 MinEnergy=0.000060 UseZeroCrossingRate=0 MinZeroCrossingRate=0.000001 MaxZeroCrossingRate=0.187400 UseActivityTriggering=0 MinActivityMS=20 ActivityEndHangTimeMS=5000 [Licence] RecordPoolChannels=500 PP0=YMAHSYCPKCWFJJVJ [INSTALLED PPS] PP0=/usr/lib/libPP_Matcher.so [Phones] DefaultRecordOnDemandState=Recorded SegLengthSecs=9999999 [Recording] DelayRecordingStartUntilMediaIsReceived=1 Triggers=CTI, Signalling MediaFlushTimeoutMS=100 [Call] UpdateLastDataTimeOnCaptureStartStop=1
[General]
[General]DownstreamAPIVersion
Controls the format of messages sent downstream to consuming applications, either:
Set to
0(default) to use the original message format ofmetadatafor metadata, andmedia.<call_id>for media.Set to
1to use the formatcall.metadata.tenant.<tenant_id>.call.<call_id>for metadata andcall.media.tenant.<tenant_id>.call.<call_id>for media.
[General]UseConfigManager
Set to 0 to disable use of the Configuration Manager for getting device configuration from Communication Recording Agent. Devices.ini will be used to populate the device configuration instead. This is a developer setting. If not specified, the default value is 1.
[General]RecordByDefault
Set to 1 to enable or 0 to disable recording by default, for newly discovered devices. If not specified, the default value is 1 (enabled).
[JetStream]
[JetStream]ServerURL
The URL of the NATS server. In the most simple of cases, this will be the NATS server used by the Audio Connector.
[JetStream]Username
If the NATS server is configured for user-based authentication, specify the username here. If not specified, no value is used.
[JetStream]Password
If the NATS server is configured for user-based authentication, specify the password here. If a password is used, the NATS server should also be configured to use TLS to prevent the password from being sent over the network in the clear. If not specified, no value is used.
[JetStream]Token
If the NATS server is configured for token based authentication, specify the token here. If a token is used, the NATS server should also be configured to use TLS to prevent the token from being sent over the network in the clear. If not specified, no value is used.
[JetStream]TrustedCACertificatesFileName
If the NATS server is configured to use TLS, specify the trusted CA certificate chain here. This will be the CA certificate chain that was used to sign the server certificate. If not specified, no value is used.
[JetStream]ClientCertificateChainFilename
If the NATS server is configured to use TLS with mutual-authentication, specify the client certificate chain here. This will be the client certificate plus the CA certificate chain used to sign the client certificate. If not specified, no value is used.
[JetStream]ClientCertificateKeyFilename
If the NATS server is configured to use TLS with mutual-authentication, specify the client private key here. If not specified, no value is used.
[JetStream]SkipServerVerification
If the NATS server is configured to use TLS, disables verification of the server certificate. Not recommended. If not specified, the default value is 0.
[VoiceActivityDetection]
This section of the .ini file is used to define the VAD settings. If the default configuration values don’t work for the customer, it’s recommended that you disable VAD, then record and export some example calls to WAV. These files can then be passed through a test tool that will allow the trial of different configuration values to ensure the correct parts of the call are identified as voice. The best fit configuration can then be applied. Please contact the Uniphore Development Support Team for details.
Note
To disable Voice Activity Detection, simply disable the use of both Short-Term Energy and Zero Crossing Rate (set UseShortTermEnergy and UseZeroCrossingRate to 0).
[VoiceActivityDetection]WindowSizeMS
The size of the window, in milliseconds, on which to perform VAD. The default is 10 milliseconds – we don’t recommend any other value at present.
[VoiceActivityDetection]UseShortTermEnergy
Enables (1) or disables (0) use of the Short-Term Energy algorithm. By default, this is enabled (1).
[VoiceActivityDetection]MinEnergy
The minimum energy required for the window to be considered as voice activity. Expressed as a decimal value between zero and one. Zero being absolute silence and one being maximum loudness. The default is 0.000060. This may seem like a low value, but generally background noise will be lower than this.
[VoiceActivityDetection]UseZeroCrossingRate
Enables (1) or disables (0) use of the Zero Crossing Rate (ZCR) algorithm. Use of ZCR is only recommended if it’s required that tones on the channel do not trigger voice recording. If this is the case, ZCR should be used in conjunction with STE. By default, ZCR is disabled (0).
[VoiceActivityDetection]MinZeroCrossingRate
The minimum Zero Crossing Rate for the window to be considered as voice activity. The default is 0.000001. Human speech has a low ZCR, increasing this value may prevent voice from being detected. A lower limit is required because a ZCR of zero indicates that the sine wave is not crossing zero i.e. the waveform is flatline (silence).
[VoiceActivityDetection]MaxZeroCrossingRate
The maximum Zero Crossing Rate for the window to be considered as voice activity. The default is 0.187400.
[VoiceActivityDetection]UseActivityTriggering
Enables/disables use of activity triggering. By default this is disabled (0). If enabled (1), a voice recording will not be created until voice activity is detected on the channel. Likewise, the voice recording will be ended on cessation of voice activity on the channel. If disabled (0), voice recordings will be created and ended based on signalling as normal.
[VoiceActivityDetection]MinActivityMS
The minimum duration of voice activity, in milliseconds, that is required to invoke voice recording. The default is 20 milliseconds. This value must be a multiple of the window size (WindowSizeMS) and must be between 10 and 300 milliseconds.
[VoiceActivityDetection]ActivityEndHangTimeMS
The duration, in milliseconds, to continue the voice recording after voice activity has ceased. The default is 5000 milliseconds (5 seconds). This value must be a multiple of the window size (WindowSizeMS). This prevents pauses in speech from causing excessive stopping and restarting of the recording.
[Licence]
[Licence]RecordPoolChannels
Defines how many concurrent channels can be captured by the Collector. Calls over this value will be discarded. If not specified, the default value is 1000.
[Licence]PP<0…N>
One or more PP license codes PP(s) for the Integration Adapter to load and what mode they should operate in.
[Installed PPS]
[Installed PPS]PP<0…N>
PP license code for the Collector. This will have been provided as part of the customer’s deployment information from Uniphore.
[Phones]
[Phones]SegLengthSecs
The maximum recording segment length in seconds. After this duration, recordings will be split. If not specified, the default value is 3600 (1 hour).
For call segmentation to work in Communication Recording Agent, this should be set to an extremely high value e.g. 9999999. This will prevent call segmentation from being carried out by the Collector.
[Phones]DefaultRecordOnDemandState
If the accompanying integration uses the devices.ini file (for example, when using SIPREC), determine if devices should be recorded by default. The default record-on-demand (ROD) state is applied to each device and saved in the devices.ini file. The ROD API can change the device's state. Possible values include Unspecified, Recorded, and NotRecorded.
Setting the value to NotRecorded results in devices not being recorded by default. Setting the value to Unspecified, entering no value, omitting the setting from the file, or setting the value to Recorded means that devices are recorded by default.
[Capture]
[Capture]VLANTaggedTraffic
Enables (1) or disables (0) capture of VLAN tagged packets. If not specified, the default is 1 (enabled).
[Recording]
[Recording]Triggers
Set the comma-separated list for the priority of recording triggers, valid options are CTI, Activity, and Signalling. The Alvaria integration uses CTI triggered recording, set to CTI, Signalling.
Under normal operation, the first trigger listed is used - If the source of that trigger fails then the next working trigger source in the list is used to determine when to trigger recording.
[Recording]MediaFlushTimeoutMS
The maximum interval, in milliseconds, at which to flush media data to NATS Streaming. If not specified, the default value is 10000 (10 seconds). Real-time streaming solutions should set this value to 100 milliseconds.
[Recording]DelayedCallEndTimeoutMS
Determine how long (in milliseconds) to continue capturing each call after the call end signal has been received, this is to allow any remaining audio to be captured. If not specified, the default value is 1000 (1 second)
[Recording]DelayRecordingStartUntilMediaIsReceived
Determine if the activation of recording should be delayed (1) until audio is received by the Collector or not (0). Useful in cases where CTI events can trigger recording before audio arrives at the Collector, which is more likely when using multiple Collectors. Set to 1.
[Recording]Policy
Determine which calls should be recorded, either internal extension to extension calls (Internal), external calls (External), or both internal and external calls (All). If not specified, the default value is to record just external calls (External).
[CallSuppression]
[CallSuppression]MaxSuppressCount
The maximum number of times a given recording can be suppressed. If not specified, the default is 3 times (3).
[CallSuppression]MaxSuppressTime
The maximum length of time a given period of suppression will last. If not specified, the default is 15 seconds (15).
[CallSuppression]StopCapture
When call capture is suppressed, send (true) or do not send (false) a request that the audio feed from the 3rd party system be stopped. If not specified, the default is to send the request (true).
[CallSuppression]StopOnCallEnd
Determine if the suppression for a device is ended when the suppressed call on that device ends. If not specified, the default is false.
[CTIServer]
[CTIServer]MaxConnections
The maximum number of concurrent CTI Server connections to accept. If not specified, the default value is 20.
[Call]
[Call]UpdateLastDataTimeOnCaptureStartStop
Reset the SIP shared context timestamp on each call start/stop event, preventing the context from reaching the dead-call timeout and therefore retaining the SIP/Media link from captured CTI sub-calls (set to 1, default). Setting to 0 enforces the legacy behavior where the timer does not reset frequently.
Identity.ini
TenantID=dcedc429-11a9-4408-84a7-c781363c62e1 TenantName=test CollectorID=0f89817f-e324-48ca-bcb6-3d61f292755b CollectorName=collector1
TenantId
Set to the unique identifier of the tenant associated with this Collector. If no tenants are defined, the default test tenant will be used dcedc429-11a9-4408-84a7-c781363c62e1
TenantName
The name of the tenant to which the Collector belongs (optional).
CollectorId
The unique identifier for this Collector. A UUID will be automatically generated and written to Identity.ini on first start.
CollectorName
The name of the Collector (optional).
Configure the CTI Server
Create the Alvaria CTI Server configuration file (CTIServer_Noble.config) to define the CTI Server connections. A sample file is provided in the SampleConfigFiles sub-folder, and examples are provided in this Integration Guidelines topic. An example is shown below:
<recorder>
<recorders>
<add logicalRecorderId="1">
<add recorderIpAddress="10.205.1.0" />
</add>
<add logicalRecorderId="2">
<add recorderIpAddress="10.202.9.228" />
</add>
</recorders>
</recorder>
<ctiServerSettings>
<nobleSettings keepAlivePeriodInSeconds="60" keepAliveToleranceInSeconds="5" transferToleranceInMilliseconds="6000">
<nobleServer logicalId="1" ip="noble-host" />
<nobleServer logicalId="2" ip="noble-recorder" port="8922" />
<nobleServer logicalId="9" ip="10.205.1.58" />
</nobleSettings>
</ctiServerSettings>Recorders
Define the Collector (or Collectors in instances where resiliency or multi-tenancy is to be setup) the CTI server should connect to, using the following settings:
logicalRecorderID
A friendly name for the Collector for the CTI Server to connect and send data to.
recorderIpAddress
The address for the Collector that the CTI Server should connect and send data to. Use 127.0.0.1 to connect to the local Collector.
ctiServerSettings
Define the Alvaria DRS-3P server (or servers in instances where multi-tenancy is to be set up) to connect to and receive events from, using the following settings:
nobleSettings > keepAlivePeriodInSeconds and keepAliveToleranceInSeconds
Alvaria generates keep alive messages every 60 seconds, use keepAlivePeriodInSeconds and keepAliveToleranceInSeconds to define how often to expect to receive these keep alive message, if no keep alive message is received within the sum of the keepAlivePeriodInSeconds and keepAliveToleranceInSeconds values then alarms are raised.
Configuring these settings is optional – keepAlivePeriodInSeconds defaults to 60 and keepAliveTolerance defaults to 5.
nobleSettings > transferToleranceInMilliseconds
The timespan in which an event can be received and still be associated with the call within a transfer scenario, defaults to 6000.
nobleServer > logicalId
A friendly name for the Alvaria DRS-3P server that the CTI server should receive events from.
nobleServer > Ip
Set to the address or IP of the Alvaria DRS-3P server.
nobleServer > port
The port of target NobleServer to bind socket to, defaults to 8922.
nobleServer > timeoutInMilliseconds
The socket timeout value, effectively the polling interval used to send messages to Alvaria, defaults to 500.
Recording Control
Recording Control Policies
Use Recording Control policies to control which call recordings are discarded and retained. Recording Control policies do not impact live calls so they can continue to be monitored. Blocklisting a call does not disable the call for recording and instead simply discards the call after the call has ended.
For more info on Recording Control Policies and further direction on adding, editing, and deleting Recording Control Policies, see Manage Recording Control Policies.
Blocklist: Blocklist policies can be used to provide fine control of what recordings are discarded. All calls outside the scope of the Blocklist are retained.
Allowlist: Allowlist policies are the reverse of a Blocklist. An Allowlist can be used to specify calls to be retained that would otherwise be discarded. All calls outside the scope of the Allowlist are discarded).
Add Devices
Typically, once the Collector has been fully configured and the initial setup is complete, recordable items (devices, agents, etc.) are recorded. Adding any new recordable items is managed with the configuration of the telephony integration accompanying Alvaria.
For example, if SIPREC accompanies this Alvaria integration, then the Custom.ini file needs to be configured, which defines the participants we're interested in and, therefore, which devices are discovered and added to the Devices.ini file. The Alvaria integration then uses this Devices.ini file to determine which calls to capture (recording control policies are applied to calls after this process).
Log Files
The following log files are provided on the Collector server:
Logs and Configuration Reference | Log File | Log Configuration File |
|---|---|---|
Inetgration Adapter - see Logging.ini Configuration | IntegrationAdapter.00.txt | IntegrationAdapter.Logging.ini |
NATS - see Logging.ini Configuration | forwarding-engine.00.txt | forwarding-engine.Logging.ini |
CTI - see CTI Alvaria Logs Configuration | CTIServer_Noble.txt and Noble_DRS-3P.txt | CTIServer_Noble.config |
Note
Additional logging may be available depending on the initial integration that Noble sits on top of. See the relevant Integration Guidelines topic for further details.
Logging.ini Configuration
Log files for the Integration Adapter, the RPT Collector, and NATS are configured in their respective logging.ini files. To configure the logs, set the following in the .ini file(s):
[RBRLogging] LogLevel=INFO [FileAppender] MaxFileCount=10 MaxFileSizeMB=50 Compress=1
[RBRLogging]LogLevel
Sets the log level for this logging zone. If not specified, defaults to Warning. If an invalid value is specified, the default is used. Valid values are below in order of least to most detail:
ErrorPrintWarningMessageInfoTrace
[FileAppender]Compress
Enables/disables log file compression for this logging zone. If not specified, defaults to 0. If enabled, the most recent log file will be compressed on rotation. If enabled on an established system, any pre-existing non-compressed log files will still be rotated but will not be compressed.
[FileAppender]Enabled
Enables/disables logging to file for this logging zone. If not specified, defaults to 1.
[FileAppender]LogDirectory
The directory to write log files to. If not specified, defaults to /var/redbox/logs on Linux.
[FileAppender]MaxFileCount
The maximum number of log files to retain. If not specified, defaults to 6.
[FileAppender]MaxFileSizeMB
The maximum log file size (in MB) before the file is rotated. If not specified, defaults to 15.
CTI Alvaria Logs Configuration
The logs and messages are both configured in the CTIServer_Noble.config file, and can be enabled/changed while the server is running.
To define the main CTI Server logging level, under <root> where <appender -ref ref = “RollingFileAppender", set the <level> to one of the following (examples are in order of least to most detail):
OFFERRORWARNDEBUGALL
These CTI Server logs will then be stored in CTIServer_Noble.txt.
To enable the logging of Alvaria messages, under <root> where <appender -ref ref = “NobleCommsFileAppender", set the <level> to “ALL” – all messages received from Alvaria will be stored in the Noble_DRS-3P.txt file.