Applies to QESTNet

Contents

Configuration Files

The QESTNet configuration settings are stored in configuration files that reside in the QESTNet installation directory or subdirectories thereof. Common settings will be set using the user interface provided in the QEST Web App as detailed in the articles related to QEST Platform Post Install Configuration via QEST Web App so for many QEST Platform instances, it will not be necessary to modify the configuration files manually. If manual modifications are required, however, the configuration files are XML format and can be edited by any standard text or XML editor.

Custom.app.config

Custom.app.config is the primary configuration file for the QESTNet service and resides within the Config subdirectory located within the QESTNet installation directory. The Custom.app.config file will hold the sections that will need to be customised for the specific QESTNet instance.

The file is broken up into the following configuration sections.

configSections

This section defines the structure of later sections of the custom.app.config file. Do not change this section unless advised to do so by Spectra QEST.

appSettings

This section contains name-and-value pairs for commonly modified settings.

qestnet

This section contains configuration subsections that related specifically to the QESTNet service. Portions of this section will be general and others specific to a given instance of QESTNet. It is usually necessary to modify the configuration sections described in this section to be applicable to the given network and QESTNet instance.

Configuration of these sections should be handled via the QEST Web App: QEST Platform Post Install Configuration via QEST Web App

modules

If there are any custom workflows to use, their assemblies for workflows and contracts must also be defined here:

• Custom.Workflows: an example of a custom workflows module.

notifications

This section configures notifications that are issued by the QESTNet service, e.g. for field technicians whose work schedule has been revised.

Some of these settings are now handled in the QEST Web App. See the Notifications page.

The settings still controlled in this configuration are:

• registrationExpiry - the timespan after which users will no longer receive push notifications if they have not opened the QESTField app (in format dd:HH:mm:ss). This is used as a safeguard against abandoned installations of the app. Defaults to seven days.

• rollbackToAppCenter - the service provider used for push notifications was originally Visual Studio App Center, but with that service retiring at the end of 2020 this has been migrated to Azure Notifications Hub. This option can be set to true in the unlikely event that there are issues in the migration to Azure Notification Hubs, to temporarily revert to Visual Studio App Center.

The QESTNet Configuration Key must be installed on the QESTNet server in order for push notifications to be setup. See Installing the QESTNet Configuration Key for more information.

dataIntegrators

This section is where the available data integrators for the deployment are defined. This section is not required it only needs to exist when data integration is being used. The Spectra QEST services team will advise if any data integrators additional to the notification email summarising license use is required.

Each data integrator can have the following properties:

• name: Required. The identifier for the data integrator. Each integrator must have a unique name.

• assemblyName Required. The assembly that the custom code class is located in.

• pluginType: Required. The custom code class which contains the logic for the data integrator.

• integratorConfigFile: Optional. Only used by integrators which understand it. A config file with integrator-specific configuration.

• inputName: Optional. Typically required by integrators that don't use an external configuration. The data source from which the integrator will extract data. This value will typically correspond to the name of a connection string in the connectionStrings section. If it does, then that connectionString is used to open the input data source.

• outputName: Optional. Typically required by integrators that don't use an external configuration. The data source to which the integrator will write data. This value will typically correspond to the name of a connection string in the connectionStrings section. If it does, then that connectionString is used to open the output data source.

• fileSystemWatchDirectory: Optional. An alternative to timers, executes the integrator when a file is created, modified or renamed in this directory. Can be a local or network path. Requires a fileSystemWatchFilter to be specified. An integrator using this will attempt to open the files it finds for reading, and will ignore any of the timer based options. All integrators using a file system watch are assumed to be threadsafe for handling multiple files that are created, etc. at the same time.

• fileSystemWatchFilter: Optional. Required with fileSystemWatchDirectory. Restricts which files will be noticed by the file system watcher. Is a pattern using an asterisk (*) for a wildcard that can be any sequence of up to any length.

• transferInterval: After executing having executed the first time, the period a started data integrator will wait before executing again.

• timeDelay: The period which a started data integrator will wait before first executing.

• dateDelayUntil: A list of common delays until which a started data integrator will wait before executing for the first time. Possible values: "NextSunday", "NextMonday", "NextTuesday", "NextWednesday", "NextThursday", "NextFriday", "NextSaturday", "NextMonthFirst", "ThisMonthLast"

• timeDelayUntil: The time until which a started data integrator will wait before executing for the first time, once the dateDelayUntil has been satisfied.

• state: Whether or not the timer clock is currently running for this data integrator. Valid values are "Stopped" and "Started". QESTNet will initialise the timer clock for the integrator based on this value such that a running timer clock will restart even if the QESTNet restarts. NOTE: the "Started" state does not mean the data integrator itself is currently executing, simply that the timer clock is. Only data integrators with a value for one or more of transferInterval, timeDelay, dateDelayUntil or timeDelayUntil can be started.

• waitForIntegratorNames: a comma separated list of names of integrators that this integrator should wait to finish before it begins running. This doesn't trigger the integrator to begin running, it still requires either a timer, or a file system watch to be configured. This must not be configured in a way that causes an integrator to wait for itself, even indirectly - e.g. two integrators that are both configured to wait for each other - this will cause a deadlock where neither integrator will ever run.

Licensing Email Data Integrator

While most integrators are optional, the only automatically setup integrator is the Licensing Emailer. The Licensing Emailer data integrator and associated fileSmtpIntegrator configuration section (discussed below) will not be present in the configuration file unless the settings for the integrator differ from the default. This integrator is required in order for QEST Platform administrators to receive notification emails about important license events as described in Checking License Use for QESTField Products. Note that if no recipients are included in the settings, then the integrator will not send out any emails.

Use of the licensing email data integrator has the following prerequisites:

1. Logging for licensing events is configured as described in the log4net section

2. Email delivery details are configured as described in the Settings for Email section of the System.net section below

3. The fileSmtpIntegrator configuration is defined as described below

4. This line appears in the configSections element of the configuration file:

The standard configuration for this integrator is shown below, it will set the integrator to run daily at 10pm according to the server time on which the QESTNet service is running:

engine

This section defines the sessions supported by QESTNet . Sessions hold state information for a given user for a given duration. By default there are two:

• IntegrationSession: holds the available data integrators ready to be triggered by timers or by user action.

• LabSession: holds the open documents of a user using the Lab functionality - such as through QESTField.

All of the configuration items listed below use a TimeSpan string. For information, see: https://msdn.microsoft.com/en-us/library/se73z7b9(v=vs.110).aspx

engine section:

• expirationPeriod defines how frequently QESTNet checks for expired sessions, and defaults to 1 minute.

• sessionLifetime defines a default value for how long a session is held in memory, and defaults to 1 hour. Usually this is not set, but instead set per-session in the session section → lifetime attribute.

• clientLifetime defines how long a client registration (i.e. a particular browser session) is held in memory, and defaults to 1 hour. A client will not expire if their session is still active, so there is usually no benefit to changing this setting. 

• userLifetime defines how long a user registration is held in QESTNet memory, and defaults to 1 hour. A user will not expire if their session is still active, so there is usually no benefit to changing this setting.

session section:

• lifetime is a time span value which defines the duration after which a session will be terminated by QESTNet if there has been no activity from the client.

  • The default value for LabSession, which is used for QESTField sessions, is one hour.

    • This value can be set lower to terminate sessions sooner and clear memory faster, but can be inconvenient to users who would lose any unsaved work and be forced to log in again.

    • This value can be set higher (e.g. to 1 day) so that users can stay logged in all day, with the potential cost of higher memory usage on the QESTNet service.

  • The default value for IntegrationSession, which is used for running data integrators, is 9999 days. This is to ensure the session will not terminate and stop running timed integrators.

services

This section defines the services supported by QESTNet. Services define the external contracts of communication with QESTNet. In the default configuration there are two:

• IntegrationService for data integration with remote systems.

• LabService for providing QESTLab functionality to clients such as QESTField.

• ApiService for providing QESTNet functionality through the Web Api.

fileSMTPIntegrator

This configuration is used to provide extra details for the running of the Licensing Emailer data integrator (see data integrators for more information) and is required in order for QEST Platform administrators to receive notification emails about important license events as described in Checking License Use for QESTField Products.

Configuration of this sections should be handled via the QEST Web App: QEST Platform Post Install Configuration via QEST Web App

The fileSmtpIntegrator has the following, mandatory, properties:

• name should be set as "Licensing Emailer"

• fromAddress should be set as the from address that the generated emails will use. Note that if the emails are ever replied to, this email address will receive the replies

• subject will be the subject on any notification emails. If left blank, the generated emails will not contain a subject

• body will be the text preceding the licensing summary

• sourceDirectory should be the directory where the licensing log files are being generated per the log4net configuration

• filePattern must match the filename pattern of the licensing log files as set in the log4net configuration

• archiveDirectory the directory to which the processed log files are moved after processing. This directory will need to be manually created with write permissions granted to the service user running the QESTNet service or an error will appear in the QESTNet log file stating that the directory does not exist every time the integrator runs.

In addition to the above properties, the integrator will expect collection of recipient email addresses to whom the summary email should be sent. It is recommended these are set to be the email addresses of the QEST Platform administrators.

log4net

The popular logging system log4net is used for logging from QESTNet. General QESTNet logging and logging for licensing are configured separately. The default configuration:

• Writes general logging to rolling files, one file per day, in the location [ProgramData]\Spectra QEST\QESTNET vX.X\Logs. The files are prefixed with qestnet-log.

• Writes licensing logging to rolling files, one file per day, in the location [ProgramData]\Spectra QEST\QESTNET vX.X\Logs. Licensing files are prefixed with licensing-log.

The log4net settings are not required in the configuration file unless the log4net configuration differs from the default. Configuration of this sections should be handled via the QEST Web App: QEST Platform Post Install Configuration via QEST Web App

For advanced configuration of log4net, the manual is available here: https://logging.apache.org/log4net/release/manual/configuration.html#files

connectionStrings

This section defines the connection strings which QESTNet can use to connect to databases. The three areas which use these are the Lab Session (to provide LIMS functionality via QESTNet), publishing to Construction Hive, and any Data Integrators that directly transfer data between databases.

Configuration of this sections should be handled via the QEST Web App: QEST Platform Post Install Configuration via QEST Web App

Lab Session

The Lab Session uses the connection string with the name QESTLab_Data to connect to the QESTLab database. The default connection string looks like:

Upon installation the values SQL_INSTANCE and DATABASE_NAME must be replaced with the details of the relevant QESTLab database. Further changes can be made to the connection string as required, such as to change security modes.

Construction Hive Publishing

To be able to publish documents to Construction Hive, a connection string with the name HivePublish_Data is required that connects to the Construction Hive publishing database.

Data Integrators

QESTNET data integrators can connect directly to databases to exchange information. The connection strings to do so are specified here and each is given a name. This name may be referenced in the dataIntegrators configuration in the qestnet section described earlier.

Settings for Email

Publishing through QESTField products via email and the licensing summary emails, described in Checking License Use for QESTField Products both require mail settings to be configured in QESTNET.exe.config. For more information, please refer to Microsoft Docs.

Configuration of this sections should be handled via the QEST Web App: QEST Platform Post Install Configuration via QEST Web App

From Address

Emails sent from QESTNet will attempt to obtain a 'from' address from the following sources, in descending priority:

• A configured address specific to the type of email sent, where applicable. See appSettings section above

• Email address of the user publishing the mail

• The 'from' address configured in these mailSettings

Please note that if a "from" address is not configured in these settings, users without a recorded email address will not be able to publish documents via email.

Template Locations

Note: this does not currently need to be set as the default templates are initially sufficient for all customers.

QESTNet publishing includes support for customising the template files used to build email content. QESTNet can be configured to look for template files in specified paths. If this configuration section is not present, QESTNet will use the default templates.

Additional Configuration

Included in the Config directory within the QESTNet installation directory are the Bindings.config and Behaviours.config files. More most installations, these do not require any additional configuration. For instances that use Hive Archive Publishing or require additional integration settings, these configuration files will required addtional configuration.

bindings.config

This file defines the binding configurations used to expose the QESTNet services. The default binding configurations included in the config file are as shown:

• UnsecuredBindingTcp: a TCP binding with no security enabled, used to expose the LIMS functionality to clients on the same local network (e.g. QESTField).

• FileStreamBindingTcp: a streaming TCP binding with no security enabled, used to transfer files to and from the QESTNet to clients on the same local network (e.g. QESTField).

• UnsecuredBindingNamedPipe: a named pipe binding with no security enabled, used to expose Data Integrator management functionality to clients on the same machine (e.g. QESTNet Console)

Binding properties can be adjusted or additional bindings can be added as the situation requires it. For example an HTTP binding can be added to expose QESTNet functionality on the web.

For more information on how to customise service bindings, see: https://msdn.microsoft.com/en-us/library/ms731399(v=vs.110).aspx

behaviors.config

This file defines the service behaviours. By default there is a single common behaviour used by all QESTNet services defined as shown:

For more information on how to customise service behaviour, see: https://msdn.microsoft.com/en-us/library/aa967282(v=vs.110).aspx

client.config

This file is not included with the QESTNet installation by default as most instances will not require it. Configuration is included here to access additional client services such as Hive Publish Archiving as can be seen below:

Additional Config Files

A few QESTNet instances will require additional configuration files for integration with external services. Spectra QEST will advise you when additional configuration is required.

QESTNet Api

HTTP URL ACL

The QESTNet service account needs to be able to listen on the QESTNet API address - by default, http://*:53535/

From an admin command prompt:

netsh http add urlacl url=http://*:53535/ user="qestnet.service@domain.example"

https://msdn.microsoft.com/en-us/library/windows/desktop/cc307223(v=vs.85).aspx