Deploying the Screen Recording Service - Advanced Configuration

The following sections provide advanced Screen Recording Service installation and configuration steps.
For basic instructions about how to install and configure the Screen Recording Service, see: Deploying the Screen Recording Service.

Enable Screen Recording

Important

Before you can start to capture and play back the screen recordings, you must make sure that you have configured the Web Services components, and encryption specifically for screen recording.

To set up recording conditions, add the recordingWhen parameter to the [screen-recording-client] section of the Web Services Cluster object.

When this parameter is set in the Web Services Cluster object, the recording condition applies to all agents in the environment. You can create the recordingWhen parameter in a [screen-recording-client] section of each agent object to override the settings at the environment level.

The parameter value is an expression of conditions to enable screen recording for each agent. The format is:

• For Non-voice agents: recordingWhen = condition1,condition2,... where condition1,condition2, etc. are a set of conditions that must all be true in order for the screen recording to be taking place.

• For Voice agents: Screen recording starts when the voice recording starts except in cases where recordingWhen is explicitly set to off.

Integrating with Workspace Web Edition

If your agents use Workspace Web Edition as their desktop, screen recording must be set up as follows to support single sign on:

Using Genesys Administrator Extension, add the following parameters to the interaction-workspace section of the Web Services Cluster object.

Important

If you are working with HTTP, the Screen Recording Service default port number is 8080. If you are working with HTTPS, the default port number is 443. In addition, verify that the Workspace Web Edition configuration is set to 8080 or 443.

Parameter Name	Mandatory	Description	Default Value
privilege.screen-recording.can-use	Y	Specifies whether agents can use screen recording. If set to true, the integration module is loaded and sends credentials to the client.	false
screen-recording.client.address	N	Specified the IP address that the Screen Recording Client listens for credentials on. Valid values: 127.0.0.1, [::1]	127.0.0.1
screen-recording.client.port	N	Specifies the port that the Screen Recording Client listens for credentials on.	8080
screen-recording.client.ping-interval	N	Specifies the interval, in milliseconds, between ping requests to the Screen Recording Client.	5
screen-recording.client.max-attempts	N	Specifies the maximum number of attempts to establish communication with the Screen Recording Client.	5
screen-recording.client.server-url	N	Defines the GWS server address that the Screen Recording Client will use for communication.

Integrating with Workspace Desktop Edition

If your agents use Workspace Desktop Edition as their desktop, screen recording must be set up according to the instructions in the Workspace Desktop Edition Deployment Guide.

Enable Screen Recording for a Contact Center

To enable the screen recording feature for a given Contact Center:

Using the ops account:

POST http://<Web Services-host-prefix>/api/v2/ops/contact-centers/<ccid>/features
{ "uris": ["/api/api-voice-screenrecording","/api/api-multimedia-screenrecording"] }

Advanced Installation Procedures

Configuring During the Installation

If you have made customizations to the config.json file in your environment, you can configure the installer to automatically replace the baseline version with your customized version, using the following command while installing the Screen Recording Service.

setup.exe /VERYSILENT /CONFIG="C:\path\to\config.json"

To verify the version installed, browse to https://127.0.0.1/version or http://127.0.0.1:8080/version.

Creating Self-Signed Certificates

If you did not use the /TASKS="HTTPS" parameter to install the Screen Recording Service, and if you are not using your own certificates, you can create self-signed certificates as follows:

1. Open a command window as an Administrator.
2. Navigate to the <install_dir>\Certificates\Self-Signed directory.
3. Run the create_certificates.bat file. This creates a set of unique self-signed certificates.
4. Run the install_certificates.bat file. This installs the new self-signed certificates to Windows trusted certificates store.

Installing Your Own Certificates

If desired, you can use your own certificates as follows:

1. Provide a certificate for the IPv4 host, 127.0.0.1, in the <install_dir>\Certificates\server.pem file.
2. Install the .pfx form of this certificate to the local certificates store as a "Trusted Root Certification Authority" file.
3. Provide a certificate for the IPv6 host, [::1], in the <install_dir>\Certificates\serverIp6.pem file.
4. Install the .pfx form of this certificate to the local certificates store as a "Trusted Root Certification Authority" file.
5. The PEM certificate files should include both the private RSA key and the certificate itself. [+] Show an example.

   ----BEGIN RSA PRIVATE KEY----
   .
   .
   .
   ----END RSA PRIVATE KEY----
   ----BEGIN CERTIFICATE----
   .
   .
   .
   ----END CERTIFICATE----

Important

When the .pem certificates must be protected by a password, the password is configured in the config.json file using the certificatePassword parameter. The default certificatePassword is genesysscreenrecording. For more details, refer to the Client Side parameters table in step #2 of the Advanced Configuration for the Screen Recording Service section.

Advanced Configuration for the Screen Recording Service

The Screen Recording Clients running on all desktops should be configured when they are managed locally on the system (using config.json), and occasionally when configurations are managed centrally. This configuration should use the GAX Web Services Cluster application object.

1. If your server uses a self-signed certificate, set the certificate parameter to the path on the file system where the pem file is stored.
2. Edit the local config.json file on the Screen Recording Client machine, and add the client parameters.
   [+] Show the table describing the parameters.

   Name	Mandatory	Description	Default value
   server	N	The server base url. The default port is 80; to use a diffrent port, use the url:port format. This must be configured at installation.	Empty
   allowedHosts	N	Represents a list of allowed host names to be configured as the SRS GWS server address using POST API. The value can be a single address, a list of specific addresses or a wild card. Notes: When SRS receives the server configuration parameter from Workspace Web Edition (WWE) after the agent logs in, it will check if the URI matched the allowedHost configuration parameter. If there is a match, it will establish a connection to the Genesys Web Services with the information provided. If the parameter does not match, the SRS will not establish a connection with the GWS. If the server address is configured in the local config.json file, the SRS will connect to the Genesys Web Services, regardless of the allowedHost value. If the server parameter is not configured in the config.json file and it is passed in real time as part of the login POST API, you must update the allowedHosts so that it matches the GWS's server address in the actual deployment.	https://*.genesyscloud.com
   allowedOrigins	N	Specifies the approved CORS Origin headers that Screen Recording Client approves. If it is not provided, the * character is set as the default, which means any request will be approved, with or without origin header. If it is provided, the header can be a single origin, or a list of approved origins, that is used to approve the CORS requests. The defined server parameter is always added to the list of approved origins automatically.	*
   authenticationCertificate	N	The relative or full path to the authentication server's PEM certificate. If a value is available, the authentication server uses it for the HTTPS connection to the agent's desktop. Note: This parameter is not needed in the default Screen Recording Client installation. The Screen Recording Client uses the default self-signed certificate (%install_dir\Certificates\server.pem) automatically.	'%install_dir\\Certificates\server.pem'
   authenticationCertificateIp6	N	The relative or full path to the authentication server's PEM certificate for IPv6. If a value is available, the authentication server uses it for the HTTPS connection to the agent's desktop. Notes: This parameter is not needed in the default Screen Recording Client installation. The Screen Recording Client uses the default self-signed certificate (%install_dir\Certificates\server.pem) automatically. Each host requires a unique certificate.	%install_dir\\Certificates\serverIp6.pem
   authenticationPort	N	The port used for internal communication with Web Services.	If using HTTP, the port is 8080. If using HTTPS, the port is 443.
   authenticationPortIp6	N	The port used for internal communication with Web Services.	If using HTTP, the port is 8080. If using HTTPS, the port is 443.
   certificate	N	Indicates how the screen recording client validates the Web Services server TLS certificate. If set to false, the screen recording client will not validate the certificate. If set to true, the client will validate the certificate using the Windows certificate store when the server is using a certificate from the public CA. If set to a file path (for example, C:\\Automation\\server.pem), the screen recording client will validate the certificate using a self-signed certificated when the server is using a private self-signed certificate.	true
   certificatePassword	N	The password for the PEM certificate's private RSA key.	Empty
   certificatePasswordIp6	N	The password for the IPv6 PEM certificate's private RSA key.	Empty
   credentialsTimeout	N	The timeout duration, in minutes, between the keep alive (GET/Ping) requests from the agent's desktop and the Screen Recording Client. When the timeout expires, the agent's credentials are deleted from the Screen Recording Client's cache.	35 Note: This value must be longer than the Web Services session timeout duration for the agent's desktop. By default the Web Services session timeout is 30 minutes, and the credentialsTimeout is 35 minutes. The latter must be increased if the Web Services session timeout is increased.
   ip6	N	Indicates whether to support IPv6 in addition to IPv4 for communication with Web Services.	true
   statusTimeout	N	The timeout duration, in seconds, between the keep alive GET/Ping requests from the agent's desktop and the screen recording client.	60

3. In the most basic configuration, you will not need to add the following parameters, they are all optional. However, if you intend to use any of the server parameters, install using Genesys Administrator Extension, and following the next steps:
   1. At the Environment level, locate the Web Services Cluster application object that was created during the Web Services installation.
   2. Edit the application object, and create a new section named screen-recording-client. The following figure provides an example of the screen-recording-client section.
      [+] Show the table describing the parameters that can be added to this section.

      
      

      Name	Mandatory	Description	Default value
      CaPath	N	The path for the authority PEM certificate file used for verification of encryption certificates. If not present, verification will not take place.	false
      cleanupPolicy	N	Specifies the method for managing failed screen recording files on the Client machine. The available values are: delete—Deletes the recording from the local drive regardless if upload was successful or not. keep—Deletes successfully uploaded recordings. Recordings whose upload failed will be stored in a sub folder called "Problem Videos", after which they will not be uploaded or deleted by the Screen Recording Client. keepForever—All recordings are kept permanently on the local drive. Successfully uploaded recordings will be store in a sub folder called "Uploaded", unsuccessfully uploaded videos will be stored in the "Problem Videos" folder. Recordings in those folders will not be uploaded or deleted by the Screen Recording Client. Note that this setting is recommended for debug purposes only because it can cause disk space to run out quickly.	keep
      clockColor	N	The color of the time stamp clock. Use HTML color codes.	0xffffff (white)
      clockFormat	N	The display format for the time stamp clock. See the table later in this section for the valid values.	%H:%M:%S-%Y-%m-%d %Z (HH:MM:SS-YYYY-MM-DD TZ)
      clockOpacity	N	How non-transparent the time stamp clock displays. Valid values: 0-255	150
      clockPosition	N	The position for time stamp clock. Valid values: 0=center, 1=left, 2=right, 4=top, 8=bottom. You can also use combinations of these values—for example, 6 = top-right.	8 (bottom-center)
      clockSize	N	The font size for the timestamps written to the screen. Note: This option is available if the timeStamp option is set to true.	40
      delayShutdown	N	The time, in seconds, to delay shutting down the SRS and the system if the uploadPolicy parameter is set to immediate. This allows all the screen recording files to upload before the shutdown starts. The maximum value is 125 seconds (limited by Windows).	15
      diskCheckInterval	N	The interval, in seconds, between disk space checks.	30
      diskFreeSpaceLimit	N	The minimum disk space, in MB, on the client machine. When the disk space drops below this value, the screen recording will stop any active recording sessions.	2000
      diskFreeSpaceThreshold	N	The amount of free space available above the defined limit, before recordings can be restored, after dropping below the disk space limit.	500
      encodingFps	N	The minimum frame rate used for encoding. This parameter should always be set to a value that is equal to or higher than the value set for the fps parameter. For example, if fps is set to 1: If encodingFps is set to 2, the minimal time to recording will be approximately six seconds. If encodingFps is set to 4, the minimal time to recording will be approximately five seconds. If encodingFps is set to 5, the minimal time to recording will be approximately four seconds. Note: Increasing the encodingFps value will result in a larger file size.	1
      encodingLevel	N	The H.264 encoding level restriction. Valid values: 10,11,12,13,20,21,22,30,31,32,40,41,42,50,51. For more information, see H.264/MPEG-4 AVC Levels.	41
      encodingProfile	N	The H264 encoding profile. Valid values: baseline, main, high.	high
      folder	N	The folder name where the media is uploaded in the WebDAV server.	/
      fps	N	Frames per second.	1
      grayScale	N	Indicates whether to record the screen in color or gray scale. Set to true to record in gray scale. Set to false to record in color.	false
      isACWEnabled	N	Indicates whether to record the agent when in the After Call Work state. Note: You must also configure the wrap-up-time parameter on the Agent's Login object.	true Note: If isACWEnabled is set to any value other than false, then the value is true.
      keepAspectRatio	N	Indicates whether to keep the original aspect ratio or stretch the video to fill the screen if the screen resolution is large than the maximum resolution, and the screen is down scaled.	true
      logsToKeep	N	The number of log files to keep.	10
      logLevel	N	The logging level. Set to one of the following: debug, info, warning, error, critical. Only messages with a level set equal to or above the defined level will be logged.	info
      maxDurationMinutes	N	The maximum duration, in minutes, before slicing a screen recording file.	According to the selected qualityPreset: low-180 standard-120 high-75
      maxHeight	N	The maximum height resolution in pixels. The client will always use the lower resolution defined by either the maxHeight/maxWidth parameters or the resolutionScale parameter.	1080
      maxLogSize	N	The maximum size, in MB, of the log file before a new log file is created. The old log file is named with the .1 extension. Set the value to 0 if you do not want to limit the log file size.	5
      maxWidth	N	The maximum width resolution in pixels. The client will always use the lower resolution defined by either the maxHeigh/maxWidth parameters or the resolutionScale parameter.	1920
      multipleMonitorsEnabled	N	Indicates whether to record on all available monitors. If set to false, the client will record on the primary display monitor only.	true
      postProcessingSavePath	N	The post processing temp location. When used as a UNC path, verify that the computer running SRS (SYSTEM account) has read\write permissions.	%LOCALAPPDATA%/Genesys/SRS (C:/Users/<user_name>/AppData/Local/Genesys/SRS)
      qualityPreset	N	Defines the desired bitrate, depending on the agent's screen resolution. Valid Values: low—Emphasis is on storage capacity, and text is readable 90% of the time. For example, 120 Kbps for 1920 x 1080 resolution with color. standard—Text should be readable 100% of the time with normal use. For example, 150 Kbps for 1920 x 1080 resolution with color. high—Emphasis is on quality, and text should be readable 100% even on a high movement environment. For example, 190 Kbps for 1920 x 1080 resolution with color. See the table later in this section for the full list of preset examples.	standard
      recordingWhen	N	An expression from configuration states when screen recording should be taking place for a particular recording client. The format is: recordingWhen= condition1,condition2,... where condition1,condition2..., are a set of conditions that must all be true in order for the screen recording to take place. In other words: Screen Recording Active = condition1 && condition2 && ... Note: If the state of any of the conditions is unknown (occurs only before first determining agent state, so limited to initial state), then the state of screen recording is unknown. See the table later in this section for the full list of conditions.	This parameter is optional for the Screen Recording Client and defaults to an empty value.
      resolutionScale	N	Used to scale the screen size. Setting resolutionScale to 0.5 will resize the screen resolution in half. Setting it to 1 will do nothing. The client will always use the lower resolution defined by either the maxHeigh/maxWidth parameters or the resolutionScale parameter.	1
      saveCredentialsToVault	N	Indicates whether to upload screen recordings after a system restart without requiring the agent authentication credentials. If set to true, the agent's credentials are saved into the local Windows vault.	true
      sharedSavePath	N	The Shared folder. The location in which recordings are saved to be uploaded. When used as a UNC path, verify that the computer running SRS (SYSTEM account) has read\write permissions.	<Installation_dir>
      sleepNoConnection	N	The maximum time, in minutes, that the client will sleep if there is no connection with the server before attempting to reconnect.	1
      sleepNoNewVersion	N	The time, in minutes, that the client updater thread will sleep if there is no new version available.	1440(24H)
      slowMachine	N	Indicates whether the screen recording client is installed on a slow machine, so that the extra time is available to save the video files before closing the client.	false
      softwareChecksum	N	The SHA512 checksum of the latest software setup file.	Empty
      softwareUrl	N	The URI used to fetch the latest screen recording client software installation package.	None
      softwareVersion	N	The latest screen recording client software version number.	Empty
      timeout	N	The timeout duration, in seconds, for HTTP requests. This value must be bigger than the cometD Server request timeout.	60
      timeStamp	N	Indicates whether a time stamp will be water marked on the video.	false
      updateWhen	N	Determines when to run software update when available. Available options are: Restart - The safest option in order to not to loose any recording. With this option the upgrade will be installed during the next system restart. Logout - Will run the software update once all of the agents have logged out of Windows. With the Logout option there is a risk of losing a screen recording session if the agent logs-in before the update is completed. In this case, SRS will be restarted after upgrade is complete. Immediate - Will shut down SRS and install the new version regardless of the current state (that is, even if a recording is taking place). In this case, SRS will be restarted after upgrade is complete.	restart
      uploadPolicy	N	Specifies the screen recording upload policy. If set to window, the screen recording files are uploaded to storage during the times specified by the windowStartTime and windowEndTime parameters. If set to immediate, the files are uploaded immediately; however, after the agent's last call, the Screen Recording Client needs some time to upload the recording to the server before the Agent's desktop shuts down. The amount of time needed depends on the duration of the last call and network speed. Genesys recommends to estimate one minute for every minute of screen recording on a network with 150Kbits per second and and upload speed approximate to 20 KB per second. For example, if the last screen recording lasted 10 minutes, and the network speed is 300Kbits/s (~40KB/s), five minutes is required. Note: If the Agent's PC is shutdown before the upload is completed, the recording will be uploaded on next PC start up.	immediate
      userSavePath	N	The user recordings temp location. The location must be a local folder. If a non-default location is used, verify that the user has read\write permissions.	%LOCALAPPDATA%/Genesys/SRS (C:/Users/<user_name>/AppData/Local/Genesys/SRS)
      videoBitrate	N	Encoding bitrate. Use this parameter to override the default bitrate that is calculated based on the resolution and the selected qualityPreset value.	150 Kbps for 1920 x 1080 resolution (standard preset, color recording)
      windowEndTime	N	Specifies the upload end time, in the local time. The format is hh:mm:—for example, 23:00. This parameter is mandatory for the Window upload policy.	Empty
      windowStartTime	N	Specifies the upload start time, in the local time. The format is hh:mm:—for example, 23:00. This parameter is mandatory for the Window upload policy.	Empty

      Video File Size/Compression Optimization Estimate

      The following table provides file size estimates according to the selected Quality Preset, FPS and color scheme, given a specific resolution.

      Preset	Color	Resolution	Frame Rate	Encoding Level	Average File Size MB/Minute
      Low	Color	1920x1080	1	High 4.1	0.754
      Standard	Color	1920x1080	1	High 4.1	1.1017
      High	Color	1920x1080	1	High 4.1	1.241
      Low	GrayScale	1920x1080	1	High 4.1	0.565
      Standard	GrayScale	1920x1080	1	High 4.1	0.642
      High	Grayscale	1920x1080	1	High 4.1	0.663

      Recording Conditions

      The following table describes the recording conditions for the Recordwhen parameter:

      Condition	Description
      off	A special case. Cannot appear with other conditions. When specified as such, screen recording never occurs for the agent.
      loggedin	When the agent is logged in
      DNDoff	When agent sets DND (do not disturb) to off
      ready(any)	True when any media type is set to ready, or list(ready media).count != 0
      ready(abc)	True when the abc media type is set to ready
      ready(abc,...xyz)	A list of media types that are set to ready. Note that ready(abc,...xyz) = ready(abc) || ... ready(xyz).
      random_voice(%)	Records the agent's screens based on a percentage of the total voice call volume for that agent.

      Important

      Each individual setting's key/value can be overwritten at the agent level by setting the Person object with the Annex of the same section name (screen-recording-client).

      Clock Format Directives

      The follow table lists and describes the values that are available for the clockFormat parameter.

      Directive	Meaning
      %a	Locale’s abbreviated weekday name.
      %A	Locale’s full weekday name.
      %b	Locale’s abbreviated month name.
      %B	Locale’s full month name.
      %c	Locale’s appropriate date and time representation.
      %d	Day of the month as a decimal number [01,31].
      %H	Hour (24-hour clock) as a decimal number [00,23].
      %I	Hour (12-hour clock) as a decimal number [01,12].
      %j	Day of the year as a decimal number [001,366].
      %m	Month as a decimal number [01,12].
      %M	Minute as a decimal number [00,59].
      %p	Locale’s equivalent of either AM or PM.
      %S	Second as a decimal number [00,61].
      %U	Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
      %w	Weekday as a decimal number [0(Sunday),6].
      %W	Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.
      %x	Locale’s appropriate date representation.
      %X	Locale’s appropriate time representation.
      %y	Year without century as a decimal number [00,99].
      %Y	Year with century as a decimal number.
      %Z	Time zone name (no characters if no time zone exists).
      %%	A literal '%' character.

   Advanced Software Installation Tips & Tricks

   • To debug problems with the installation, check C:\src_setup.log.
   • If a proxy is used for agents to access Workspace Web Edition, make sure 127.0.0.1:443 and 127.0.0.1:8080 (or the appropriate ports, if non-default values are used) are in proxy white list. This lets the agents access Workspace Web Edition directly without the proxy.
   • The recommended installation procedure will install the Screen Recording Client's self-signed PFX certificates to the root certificates store.. For more information, see Creating Self-Signed Certificates.
   • In the default configuration, the recordingWhen parameter is set to false. If you do not enable screen recording as described in the next section, screen recordings will not be captured.
   • During startup, the Screen Recording Client writes the current version to the log file. However, since the log file is periodically cleaned, the version is not always be at the top. Use the following command line to check the version along with other properties of the Screen Recording Client—wmic datafile where name='C:\\<Installation Directory>\\SRC.exe'
   • If you have deployed with a GoDaddy certificate, without including the G2-to-G1 cross certificate (that is, the intermediate certificate), you must perform one of the following manual workarounds:
     • Include the G2-to-G1 cross certificate in the server side certificate (concatenated with the server certificate).
     • Import the G2-to-G1 cross certificate into the SYSTEM (Local Machine) Root CA certificate store.

     The G2-to-G1 certificate can be downloaded from https://certs.godaddy.com/repository/gd_bundle-g2-g1.crt.

   • When a Proxy is used, it may interfere with SRS. SRS runs as an HTTP server and it relies on an incoming socket connection to identify the agent’s windows session correctly. If the HTTP requests are forwarded by a proxy, SRS may not be able to identify the user session correctly in a multi-user environment. In a single user case, SRS will fall back to the currently active windows session. To avoid this it is recommended that localhost (127.0.0.1) connections be excluded. When the proxy is an internal system service (like an Antivirus\Firewall), it is recommended that the SRS related processes (SrsProcess.exe and GenesysServiceHandler.exe) should be added to the security software exception\white list.