Configuring YSoft SafeQ Client v3

About

All configuration-related files are located in the configuration folder located in YSoft SafeQ Spooler's root folder. The default location is C:\SafeQ6\Spooler\configuration.
There are three configuration types:
1. YSoft SafeQ Spooler Configuration
  - local.json
  - cached.json
  - static.json
2. Logging Configuration
  - logging.json

YSoft SafeQ Spooler Configuration

General

When a YSoft SafeQ Spooler starts, it tries to download the configuration from YSoft SafeQ, which is then saved into cached.json.
- When the Site Server is not available, YSoft SafeQ Spooler retries configuration retrieval indefinitely.
It loads configuration as follows:
1. Download configuration from YSoft SafeQ Management Service and save it to cached.json.
2. Load or create static.json
3. Load cached.json.
4. Load local.json.
5. Override values from cached.json with values from local.json ( it does not rewrite the file, only in memory).
local.json is used for overriding configuration downloaded from YSoft SafeQ which is stored in cached.json.
It uses the same configuration keys as available in the Management Server.
static.json if the configuration file does not exist, it is generated by YSoft SafeQ Spooler, it currently contains the YSoft SafeQ Spooler GUID for identification. This file should not be modified or deleted, doing so might lead to the loss of jobs.
When the configuration is changed on management, the spooler does not require a restart. Exceptions are:
- Guid - would lead to loss of jobs (this should never be changed).
- IPP printer settings.
- Site server configuration.
- Job Store path.

Configuration files are created under the Administrator account. Administrator privileges are required to edit configuration files. To ensure end users cannot modify these files you need to set adequate access permissions.

Required configuration

Required is only Site Server configuration which should be filled during installation.

{ 
  "SiteServerOptions": { 
    "SiteServers": [
      "Scheme":  "http",
      "Host": "10.0.12.118",
      "JobServicePort": 5000 
    ]
  } 
}

Cached configuration

The cached configuration is categorized into
- JobDeliveryOptions,
- JobReceivingOptions,
- UncategorizedOptions - This category contains all of the configuration properties from YSoft SafeQ Management Service, which we currently do not use.

Available configuration values

Group	Key	Type	Default value	Description
SpoolerOptions	Guid	string		Spooler identifier.
	UserInterfacePort	int	3050	Port where are hosted static files for the electron web application
	BufferSize	int	65536	Size of the buffer
	CacheCredentials	bool	true	Flag if user credentials will be cached in the client's machine so she will be asked less frequently to sign in when submitting a print job
	EnableQueueManagementInClient	bool	false	Enables Queue Management from YSoft SafeQ Client v3 context menu.
	DriverConfigurationFolderPath	string	..\..\DriverConfigurations	Path to folder containing configuration files. On Windows usually .dat file
	DriverName	string		Name of the print driver used when the direct queue is deployed. (Available only on Windows)
	DriverConfigurationFileName	string		Name of the configuration .dat file used when the direct queue is deployed. (Available only on Windows)
	OfflinePrintEnabled	bool	false	Users using YSoft SafeQ client v3 or YSoft SafeQ FlexiSpooler will be able to send a print job directly to the recently used device when communication with the server is unavailable. This configuration is set from YSoft SafeQ Management Service through Job Service.
	OfflinePrintAvailableServersideDevicesRefreshInterval	int	30	Controls the interval between refreshing records of device usage in minutes.
SiteServerOptions	EnableManualSiteServerSelection	bool	false	If set to true, automated print location (Site Server) is disabled and user chooses the location manually.
	SiteServerSources	array		List of Site Server sources, delimited by comma. Possible sources are: "local" and "jobservice". "Local" - the client will include Site Servers from its local configuration file into its Site Server selection pool "JobService" - the client will include Site Servers from the configuration provided by jobservice into its Site Server selection pool
	DisableCertificateValidation	bool	false	Sets whether spooler should ignore server certificate errors
	KeepAliveInterval	TimeSpan	00:00:15	Represents the interval to send keep-alive pings. Should be at most half of the JobService's ClientTimeoutInterval to avoid connectivity issues.
	SelectedSiteServerAlias	string		Represents the value of the currently selected print location, if the manual selection is enabled by EnableManualSiteServerSelection. It is useful for setting the default value for the user. Corresponds to either Alias or Host property of the Site Server. If not set, first in the list is selected.
SiteServerOptions.SiteServers	Host	string		IP Address or hostname of the Site Server.
	Alias	string		Alias as Site Server host.
	JobServicePort	int	5000	Port of Job Service.
	ServerSpoolerPort	int	5002	Ports where YSoft SafeQ Spoolers in Server mode listen
	Scheme	string		A scheme used for communication with the Site Server. Either HTTP or HTTPS.
JobDeliveryOptions	IppPrinterConnectionTimeout	TimeSpan	00:00:15	Network connection timeout in which IPP server must respond or the print fails.
	RawPrinterConnectionTimeout	TimeSpan	00:00:30	Network connection timeout in which TCP counterpart must respond or the print fails. Defined in seconds.
	RawPrinterConnectionLingerTimeout	int	0	When not zero, TCP connection is not closed until all queued messages for the socket have been successfully sent or the linger timeout has been reached. Defined in seconds.
	LprPrinterConnectionTimeout	TimeSpan	00:00:30	Network connection timeout in which LPR server must respond or the print fails.
	LprPrinterConnectionLingerTimeout	int	0	When not zero, TCP connection is not closed until all queued messages for the socket have been successfully sent or the linger timeout has been reached. Defined in seconds.
	LprBufferSize	int	65536	Buffer size used for sending data (usually to MFD) via LPR.
	InternalLdapReplaceAtChar	bool		If set to true, the character "@" (at) is replaced with the given value. Note that special characters must be escaped with a backslash - ie. use "\#" to replace "@" with "#" (hash). This option could be used with Toshiba and Oki embedded terminals.
	RemovePjlDminfoForHp	string		Enabling this property causes the removal of the Dminfo PJL header from HP print jobs as the header could cause problems during printing.
	PrintedJobPath	string		The path where a modified job will be stored upon delivery.
	SaveTickets	bool	false	If set then Spooler will store the Print request at PrintedJobPath.
	IppPrintMonitoringEnabled	bool	true	Enables IPP monitoring of a submitted job. The spooler will ask for a job status periodically and logs the result. When submitting multiple jobs a job will be submitted only when the Spooler receives a Ready state from the printer. When the feature is disabled, the time to print multiple documents might improve due to less communication between the Spooler and the printer. This feature works only when a device has the backend configured to IPP. The feature does not interfere with other IPP settings outside of Spooler, such as Online accounting over IPP.
	IppPrintMonitoringInterval	TimeSpan	00:00:05	Interval at which Spooler asks printer for the job status.
	IppPrintShortMonitoringInterval	TimeSpan	00:00:00:500	The short interval at which Spooler asks printer for the next job status. The interval is used for Pending and Pending held states.
	IppPrintMonitoringTimeout	TimeSpan	01:00:00	The monitoring will stop after this time period. This can help with jobs that become stuck for some reason. When the timeout is reached and the print job is not finished, the cancel job IPP message will be sent. This feature works only when a device has the backend configured to IPP.
	IppCancelStoppedJobInterval	TimeSpan	00:05:00	When job processing is stopped for this time period, a cancel job IPP message will be sent. This corresponds to the IPP state 'processing-stopped'. This feature works only when a device has the backend configured to IPP.
JobReceivingOptions	UseIpp	bool	true	If enabled, Spooler will use IPP for receiving print jobs
	UseIpps	bool	false	If enabled, Spooler will use IPPS for receiving print jobs
	IppPort	int	631 (5631)	The port used in the Spooler for receiving print jobs through IPP. If a port with a number lower than 1024 is used, the port applied in OS X will have a number higher by 5000.
	CertificatePath	string	certificate.pfx	Defines the path to certificate needed to use for IPPS
	CertificatePassword	string	password	Defines the password needed for the certificate
	SQLPRPrt	int	515 (5515)	Port used in the Spooler for receiving print jobs through LPR. If a port with a number lower than 1024 is used, the port applied in OS X will have a number higher by 5000.
	IsServer	bool	false	If enabled, Spooler will run in server mode
	ParseUserFromTitle	string		Defines a list of usernames so that if a print job comes from one of them. The username will be extracted from the job title and used as the job owner instead. Job titles contain a username at the position specified in the property parseUserFromTitleIndex. The format of the property: a list of usernames separated by a comma. Example: Administrator, SAP
	ParseUserFromTitleDelimiter	string	[.:_/\\]	A regular expression that defines the delimiter of the components of print job titles for parsing a username. The default value contains the following characters: .:_/\ The delimiter is any of these: dot, colon, underscore, slash, or backslash.
	ParseUserFromTitleIndex	int	1	Defines where the username is located (a numerical index of the first character of the username) in print job titles. Set 0 for titles like USER.something, and 1 for something.USER.title, ...
	ParseUserFromTitlePreserverTitle	bool	false	If enabled, the original job title is preserved. Otherwise, username is removed from the print job title.
	RemoveDelimiterAfterParsedUsername	bool	false	If enabled, the following delimiter after username will be removed. Otherwise job title may contain delimiter which was before username. The property works if the property ParseUserFromTitlePreserverTitle is enabled.
	LprEncoding	string	Default	Defines the encoding used by the LPR protocol for the LPD print server. Protocol headers also include usernames and job titles that may contain some non-ASCII characters which might be displayed incorrectly. Therefore, specify the encoding that corresponds to the local national alphabet. For example, Windows-1251 for Cyrillic, Windows-1250 for Czech, etc. If not set, UTF-8 encoding is used. There can be problem if user has login name with character from different charset then Windows Region settings. There are two ways how to fix it: 1) It can be fixed by setting Windows local settings and LprEncoding set both to charset of problematic character. OR 2) It can be fixed by UTF-8 setting in Windows (Beta feature) and keeping LprEncoding in default state or UTF-8. This should fix the problem in case that the character is in UTF-8 charset.
	WaitForDataTimeout	TimeSpan	00:00:30	Defines how long will the spooler wait for the next data chunk before time out-ing.
	RemoveInvalidCharactersFromJobTitle	bool	true	If enabled, invalid characters (according to XML 1.0 specification) are removed from the title of each print job when the YSoft SafeQ server receives it. Common print jobs do not contain such characters in their titles and will not be modified.
	HeaderAnalysisBufferSize	long	256000	Size of the buffer used for header analysis.
	DefaultJobLanguage	JobLanguage (string)	Other	Other is useful for most cases, but if the customer produced PCL5 without PJL (unwrapped), setting this to PCL will allow full processing of these jobs
JobStoreOptions	Path	string	JobStore	Path to job store.
	MinimumDiskSpaceRequired	long	500	The minimum amount of disk space required to accept print jobs in Megabytes (MB).
	DiskSpaceMonitoringEnabled	bool	true	Enables and disables disk space monitoring.
AuthenticationOptions	AuthenticationType	string		Specifies the authentication type to use on the client. Possible values: DOMAIN_USERNAME, USERNAME_AND_PASSWORD, STORED_USERNAME, DOMAIN_USERNAME_FROM_CLIENT DOMAIN_USERNAME - The Job Service will try to use Windows Integrated Authentication (SSO) to authenticate the user. If SSO is successful the user will not get the login window. If SSO fails user will be prompted for the credentials. USERNAME_AND_PASSWORD - The user will have to enter the credentials to authenticate. STORED_USERNAME - The Job Service will try to use the stored username from the client to authenticate the user. If authentication is successful the user will not get the login window. If the STORED_USERNAME authentication fails and the AuthenticationType value of JobService is DOMAIN_USERNAME, the Job Service will try to use Windows Integrated Authentication (SSO) to authenticate the user. If SSO fails user will be prompted for the credentials. If the STORED_USERNAME authentication fails and the AuthenticationType value of JobService is not DOMAIN_USERNAME, user will be prompted for the credentials directly. DOMAIN_USERNAME_FROM_CLIENT - Client v3 retrieves the username by calling whoami.exe /UPN and uses this as it would be a STORED_USERNAME. It is convenient when Job Service is in a different domain than Client v3 and there is no trust between those domains. The username is always in UPN format user@domain. This option is only for Windows Client v3. If you use also Client V3 on Mac, the AuthenticationType should be locally overridden. Both STORED_USERNAME and DOMAIN_USERNAME_FROM_CLIENT require additional settings on Job Service. SafeQConfigurationOptions.AuthenticatedUserMustMatchJobTicketOwner set to False, SafeQConfigurationOptions.AllowStoredUsernameFromClient set to True. For more information and security considerations, please see AuthenticationOptions on Configuring YSoft SafeQ Job Service page.
	Username	string		The username used for STORED_USERNAME authentication method.
DhcpDiscoveryOptions	Enabled	bool	false	Enables DHCP discovery of Site Server addresses.
	Timeout	TimeSpan	00:00:15	How long DHCP discovery will wait for a DHCP response after sending a DHCP request.
	FilterRules	Array	empty array	Configures filtering of results obtained via DHCP discovery. See DHCP discovery of site servers for more details.
SpoolerApiOptions	JobDataTemporaryTokenExpirationTimeout	TimeSpan	00:00:30	Memory Cache expiration timeout for any temporary token that is related to job data download
SpoolerUpdateOptions	RequireValidSignature	bool	true	Client will validate the signature of the package against the certificate from the server
	RequireTrustedCertificate	bool	true	Client will execute the update package only if the underlying operating system trusts the certificate
	RequireMatchingCertificateFields	bool	true	Client will execute the update package only if the certificate's subject contains required fields (see RequiredCommonNames and RequiredCountries)
	RequiredCommonNames	string	Y Soft Corporation, a.s.	Client will check whether the certificate contains all of these common names
	RequiredCountries	string	CZ	Client will check whether the certificate contains all of these countries
PrintJobCommand	Timeout	TimeSpan	00:30:00	Specifies the upper limit of how long can printing jobs take.
UpdateSpoolerCommand	Timeout	TimeSpan	00:00:10	Specifies the upper limit of how long can updating spooler take.
UpdateConfigurationCommand	Timeout	TimeSpan	00:00:30	Specifies the upper limit of how long can updating configuration take.
NotifyUserCommand	Timeout	TimeSpan	00:00:30	Specifies the upper limit of how long can sending a notification to a user take.
DeleteJobCommand	Timeout	TimeSpan	00:00:10	Specifies the upper limit of how long can deleting print jobs take.
GeneratePreviewCommand	Timeout	TimeSpan	00:03:00	Specifies the upper limit of how long can print job preview generation take.

Printer Configuration

This contains IPP printer configuration.

Logging Configuration

This contains the configuration of YSoft SafeQ Spooler's logging.
It is based on Serilog's configuration (see https://github.com/serilog/serilog/wiki/Configuration-Basics).
Some of the default options
- path - (default 'logs/spooler.log') location of the log
- rollingInterval - (default 'Day') specifies the minimum time when the log will be rotated (this adds the date format to the log file name). Available options are Infinite, Year, Month, Day, Hour, Minute
- fileSizeLimitBytes (default 20000000) - maximal size of log file
- rollOnFileSizeLimit (default true) - specifies if log will be rotated after maximum size is reached, if false, NOTHING is logged when the maximal limit is reached.
- retainedFileCountLimit (default 30) - maximal number of log files. If exceeded, the oldest file gets deleted
The configuration archives the logs in a GZip format after file roll.