Skip to main content
Skip table of contents

Deployment of YSoft SafeQ Job Service

Job Service is a component responsible for handling the communication between Spooler controller and Spooler/YSoft SafeQ Client v3. It is also responsible for communication with other Job Service components and a persistent layer (YSoftSQ-JSDL). It handles info about jobs, users and configuration. Job Service is deployed server side and is a necessary part of the architecture when using YSoft SafeQ Client v3. For advanced configuration please visit the links below.

Installed services

YSoft SafeQ Job Service can be installed using the PowerShell script included in the package – install.ps1. The script will install 2 Windows services: 

  • YSoft SafeQ Job Service (YSoftSQ-JOB-SERVICE)
  • YSoft SafeQ Job Service Distributed Layer (YSoftSQ-JSDL)

Prerequisites

  1. IP addresses or hostnames of all Site Servers where YSoft SafeQ Job Services will be installed in the cluster.
  2. The IP address of YSoft SafeQ Spooler controller running on the same machine as is the installation destination of Job Service.
  3. SSL/TLS certificate which is trusted in the infrastructure
    • Used for HTTPS
    • Without the certificate, YSoft SafeQ Job Service will use a self-signed certificate
    • Will be provided via HttpsCertificatePath and HttpsCertificatePassword configuration values in the install script, see section How to
  4. Asymmetric key pair packaged as a certificate for signing access tokens
    • YSoft SafeQ Job Service needs an asymmetric key pair to sign and validate access tokens (JWTs). This key material must be packaged as a certificate.
    • (warning) Must be the same for all YSoft SafeQ Job Services in the cluster
    • See Generating certificate for signing access tokens/secured SSL connection to generate such certificate
    • Will be provided via SigningCertificatePath and SigningCertificatePassword configuration values in the install script, see section How to
  5. The Microsoft Visual C++ Redistributable 2019 is installed on the YSoft SafeQ Job Service server.

How to

  1. Run install script install.ps1

    Example of script usage

    This is an example of how the script can be called.

    BASH 
    .\install.ps1 `
	-NrgAddresses SITE_SERVER_1,SITE_SERVER_2,SITE_SERVER_3 ` 
	-SigningCertificatePath "PATH_TO_SIGNING_CERTIFICATE" `
	-SigningCertificatePassword SIGNING_CERTIFICATE_PASSWORD `
	-HttpsCertificatePath "PATH_TO_SSL_TLS_CERTIFICATE" `
	-HttpsCertificatePassword SSL_TLS_CERTIFICATE_PASSWORD

Install script arguments

ArgumentDescriptionRequiredDefault value

Example

-InstallPathA path where YSoft SafeQ Job Service will be installed.no<install_dir>/JobService<install_dir>\JobService
-SpocAddress 

SpocAddress

Changing SPOC address to anything but localhost is not supported and will probably result in some features not working correctly.

Address of YSoft SafeQ Spooler Controller to which will YSoft SafeQ Job Service connect.

nolocalhost
localhost

-NrgAddresses

A comma-separated list of addresses of all YSoft SafeQ Job Services in the near roaming group. If the YSoft SafeQ Job Service is installed with a standalone Site Server then you have to enter the address (typically IP address, hostname or FQDN) of the server where the YSoft SafeQ Job Service is installed. This argument cannot be empty.

NrgAddresses

The list must not be surrounded with quotation marks (10.0.10.50,10.0.10.51,10.0.10.52 is correct,  "10.0.10.50,10.0.10.51,10.0.10.52" is incorrect).

yesNONE10.0.10.50,10.0.10.51,10.0.10.52
-NrgAliasesComma-separated list of aliases of the YSoft SafeQ Job Services in the near roaming group. They have to be in the same order as Job Services.noNONEred,green,blue

-SigningCertificatePath

Path to the certificate (with public and private key) which will be used for signing access tokens. Use different from HTTPS certificate. The path must contain also the filename of the certificate. The path can be either absolute or relative.yesNONE

YSoft SafeQ Signing Certificate.pfx

C:\certificates\YSoft SafeQ Signing Certificate.pfx

-SigningCertificatePasswordThe password that was used during signing certificate generation.yesNONE123456
-HttpsCertificatePathA certificate that will be used to enable HTTPS. This will enable communication encryption between YSoft SafeQ Client and YSoft SafeQ Job Service (and between multiple YSoft SafeQ Job Services). This certificate will be validated by clients. If the validation in the client fails, the client will not communicate with the server. If the path is not provided, the installer will create a self-signed certificate using which you might need to disable the certificate validation on YSoft SafeQ Clients and other YSoft SafeQ Job Services. It is highly recommended to use a certificate that is trusted by your infrastructure.noThe installer will create a self-signed certificate.YSoft SafeQ Job Service.pfx
-HttpsCertificatePasswordThe password that was used during certificate generation.no

-InfinispanPortPort of Infinispan's REST interface.no

-DisableCertificateValidation

Switch which disables YSoft SafeQ Job Service's validation of HTTPS certificates. The extent of the validation is certificate and platform dependent (e.g. macOS requirements). Using this switch will severely decrease security. noCertificate validation is enabled by default.This argument is a switch, you should not pass any values to it.
-SiteServerHosts
Comma-separated list of IP addresses or hostnames of the server where YSoft SafeQ Job Service is installed. This will be used to update the information in the spooler. The spooler will connect to the first one and if it is not available it will randomly select from the rest.

no

NONE10.0.10.53,10.0.10.54
-SiteServerAliasesComma-separated list of aliases of the Site Server hosts. They have to be in the same order as Site Server hosts.noNONEeva,merlin
-JobServicePortsComma-separated list of ports where YSoft SafeQ Job Service listens. They have to be in the same order as Site Server hosts.noNONE5000
-ServerSpoolerPortsComma-separated list of ports where YSoft SafeQ Spoolers in Server mode listen. They have to be in the same order as Site Server hosts.noNONE5002,5002
-SecureJMXSwitch which enables secure JMX for YSoft SafeQ Job Service Distributed Layer if supplied. For more information about securing JMX see Configuring password authentication for JMX connections.noCertificate validation is enabled by default.This argument is a switch, you should not pass any values to it.

-SigningCertificateThumbprint

This argument is for the update procedure (see section Updating with preserved configuration and print jobs). Use it only if you have a certificate in the certificate store to use. It sets local.json – IdentityServerOptions – SigningCertificateOptions – Thumbprint.no
E82D4BAB8938E72914B9D9CBC14F10400C814767

-HttpsCertificateThumbprint

This argument is for the update procedure (see section Updating with preserved configuration and print jobs). Use it only if you have a certificate in the certificate store to use. It sets local.json – HttpServerOptions – CertificateOptions – Thumbprint.no
54BB97D3275AF226520F5509B82573B81963385F

-SelfUrlResolutionKind

Argument that configures how Job Service resolves its own URL for the purposes of adding itself to the Address Book. Possible values are "Connection", "Host" and "Static". Used when a Job Service is clustered. For details refer to Configuring YSoft SafeQ Job Service.noUses "Connection" when not setStatic

-SelfUrlResolutionUrl

When SelfUrlResolutionKind is set to "Static", this configures the URL parameter.noNONEhttps://job-service.example.com:5000

Example of script usage

This is an example of how the script can be called when installing a single server (e.g. with IP 10.0.10.50)

BASH 
.\install.ps1 -NrgAddresses 10.0.10.50 -SigningCertificatePath "YSoft SafeQ Signing Certificate.pfx" -SigningCertificatePassword 123456

This is an example of how the script can be called when installing server s01 as a cluster member:

BASH 
.\install.ps1 -NrgAddresses s01.example.com,s02.example.com,s03.example.com -SigningCertificatePath "YSoft SafeQ Signing Certificate.pfx" -SigningCertificatePassword 123456 -SelfUrlResolutionKind Static -SelfUrlResolutionUrl https://s01.example.com

This is an example of how the script can be called when specifying an additional list of Site Server hosts:

BASH 
.\install.ps1 -NrgAddresses 10.0.10.50 -NrgAliases red,blue -SigningCertificatePath "YSoft SafeQ Signing Certificate.pfx" -SigningCertificatePassword 123456 -SiteServerHosts 10.0.10.51,10.0.10.52 -SiteServerAliases eva,merlin -ServerSpoolerPorts 5000,5001 -JobServicePorts 5003,5004

This is an example of how the script can be called when specifying a static SelfUrlResolution (this Job Service is reachable on https://job-service.example.com):

BASH 
.\install.ps1 -NrgAddresses 10.0.10.50 -SigningCertificatePath "YSoft SafeQ Signing Certificate.pfx" -SigningCertificatePassword 123456 -SelfUrlResolutionKind Static -SelfUrlResolutionUrl https://job-service.example.com:5000

Uninstallation

To uninstall YSoft SafeQ Job Service from the server run the uninstall.ps1 script that is part of the folder where the YSoft SafeQ Job Service is installed or launch these commands in the Windows Command Prompt ( Win+R > type in "cmd" > press  Enter )

BASH 
sc stop "YSoftSQ-JOB-SERVICE"
sc delete "YSoftSQ-JOB-SERVICE"
sc stop "YSoftSQ-JSDL"
sc delete "YSoftSQ-JSDL"
iisreset /stop
RMDIR "C:\SafeQ6\JobService" /Q /S
iisreset /start

Updating with preserved configuration and data

This section describes how to preserve configuration and data (mostly print jobs) during update of YSoft SafeQ Job Service.

Limitations:

  • Update removes cached user sessions. Users will have to log in to YSoft SafeQ Client v3 GUI again. This is one time operation which can be mitigated by using single sign-On.

Skipping the cache backup and restore will result in:

  • Print jobs spooled before update cannot be released. User may see them on terminal but release attempt will result in error. Solution is to delete such jobs e.g. via Management Interface and user needs to send them for print again.
  • Print jobs marked for deletion may remain present in the print job storage (on servers or user workstations). Solution is to delete old jobs manually.

Remarks on backup_ispn.ps1 and restore_ispn.ps1 scripts:

  • they are attached within the installation zip package
  • use backup_ispn.ps1 from the installation package of Build you are updating FROM
  • use restore_ispn.ps1 from the installation package of Build you are updating TO
  • if updating from/to Build 75 or older, contact Y Soft support to provide suitable backup_ispn.ps1 (reference SBT-4297)

Performance consideration:

  • guids.txt with 100 000 lines will take about 15 minutes to complete the backup and the similar time to do the restore.
  • It is possible to save the time and skip the Job Service cache backup/restore, but only if the risks described above are acceptable (print jobs lost, print jobs left on the disk).
    • If you decide to skip the cache backup/recovery:
    • SQL 
      -- run this SQL query on SQDB6 database before updating Site Servers
-- if you run the query after the update of Site Servers, it is necessary to delete SPOC caches
-- query marks all the print jobs as deleted (including favorite jobs), preventing errors upon attempt user to release them
update tenant_1.smartq_jobs set cur_status = 32768 where cur_status in (1,2,4,8,16,32,64,128,256,512,1024,131072,131073,131074) and spooler_type='JOB_SERVICE'


Both backup_ispn.ps1 and restore_ispn.ps1 scripts are prepared for the default configuration of the distribution layer. In case you have some custom configuration, you will have to modify backup_ispn.ps1 and restore_ispn.ps1 scripts accordingly as well.

  1. Stop YSoft SafeQ Job Service (YSoftSQ-JOB-SERVICE) on all Site Servers.

  2. Run this SQL query on SQDB6:

    SQL 
    select job_guid from tenant_1.smartq_jobs where spooler_type='JOB_SERVICE'

    Save the output of this query as guids.txt.

  3. On all Site Servers:
    1. Copy guids.txt to C:\temp\.

    2. Run backup_ispn.ps1 to make the cache backup. This script creates ispn_backup.json.

      Ignore the 404 errors, some jobs might have been already deleted.

  4. Update YSoft SafeQ Job Services on all Site Servers.

    1. Back up the following configuration folders and files (if they exist):
      1. <jobservice>\configuration
      2. <jobservice>\distServer\distServer.conf
      3. <jobservice>\distServer\jmxremote.access
      4. <jobservice>\distServer\jmxremote.password
    2. Uninstall YSoft SafeQ Job Service.
    3. Install the new version of YSoft SafeQ Job Service with the SigningCertificateThumbprint and HttpsCertificateThumbprint arguments.
      • Provide the thumbprint values from the backed-up configuration\local.json configuration file.
    4. Stop YSoft SafeQ Job Service (YSoftSQ-JOB-SERVICE).

    5. Merge the backed-up configuration folders and files from step a. with the new folders and files created during the installation of a new version.

      Individual versions of YSoft SafeQ Job Service can have different configuration options, thus the backed-up configuration has to be merged with the new configuration options accordingly.

      1. One of the common configuration options to be replaced with the backed-up configuration is “Guid” from JobServiceOptions in local.json.

        Example of configuration\local.json

        CODE 
        "JobServiceOptions": {
	"DisableCertificateValidation": false,
    "Guid": "2e8992f4-e57f-4380-b4c6-8adfc854de9e"
}

      2. Other options such as SpocAddress and NrgAddresses in configuration\local.json and distServer\distServer.conf depends on whether it was set correctly during the installation of the new version.

      3. If updating from Build 79 or older, make this change in restored config file

        distServer\distServer.conf

        TEXT 
        remove:
### Type of communication protocol. Keep TCP.
ysoft.cluster.protocol=TCP

add:
### Enables JGroups diagnostic probing
ysoft.jgroups.diag.enabled=false
### The minimum number of threads to use.
ysoft.jgroups.thread_pool.min_threads=0
### The maximum number of threads to use.
ysoft.jgroups.thread_pool.max_threads=200
  5. Compare ispn_backup.json files from all Site Servers and pick the one with the biggest data set – just in case the cache was not updated on every server – and then run restore_ispn.ps1 script only on this one particular server.
  6. Start YSoft SafeQ Job Service (YSoftSQ-JOB-SERVICE) on all Site Servers.


Troubleshooting

Problem

During cache backup using backup_ispn.ps1 or restore_ispn.ps1 there is error:

CODE 
Invoke-WebRequest : Invalid request path

Resolution

Check that you are using backup_ispn.ps1 or restore_ispn.ps1 script corresponding to the actual version you are backing up from or restoring to.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close