Step 2- Configure the WatcherSubscriber

This section describes how to configure the WatcherSubscriber to receive information from the Watcher regarding changes in records, and then execute specified actions for the matched conditions.

Prerequisites

  • You can download the JAR files from the Dashboard > Downloads section
  • When setting up the Watcher, ensure that you set the corresponding actions for the plugins. For more information on setting up a Watcher, see Watchers.

Connect WatcherSubscriber to the server

You can store configurable properties in an application.properties file and place it in the same directory as the JAR file.

Each parameter is stored as a pair of strings, one storing the name of the parameter, and the other storing the value. For example, dataLocation=datafiles where, dataLocation is the parameter and datafiles is the value. 

The parameters set from the command line have precedence over the properties file in the project directory.

To start the WatcherSubscriber:

  • If the configuration is defined in an application.properties file, in a terminal session, navigate to the location of the directory containing the .jar files and run the following command:
java -Dloader.path="watcher-plugin-email-smtp-<version>.jar,watcher-plugin-call-http-<version>.jar" -cp watchersubscriber-<version>.jar org.springframework.boot.loader.PropertiesLauncher
// To start watcher subscriber with a custom plugin
java -Dloader.path="watcher-plugin-email-smtp-<version>.jar,watcher-plugin-call-http-<version>.jar,watcher-plugin-<custom-plugin>-http-<version>.jar" -cp watchersubscriber-<version>.jar org.springframework.boot.loader.PropertiesLauncher
  • To pass the parameters in the command line arguments, navigate to the location of the directory containing the .jar files and run the following command:
java -Dloader.path="watcher-plugin-email-smtp-<version>.jar,watcher-plugin-call-http-<version>.jar" -cp watchersubscriber-<version>.jar org.springframework.boot.loader.PropertiesLauncher --certificatePath="<certificate>" --privateKeyPath="<private_key>" --gospelUrl="https://<gospel_url>" --apiVersion="v1.1"

where -Dloader.path is the path to the list of plugin (jar) files and -classpath is the entry to the main class using a properties file that is included in the JAR file.

WatcherSubscriber Settings

The table lists, and describes the configuration values you can set when starting the WatcherSubscriber:

Properties (Command Line)Description

certificatePath

Required. The relative or absolute path.

You can download the certificate and private key for the current session from the Tools > Certificate Tools page.

privateKeyPath

gospelUrl

Required. The URL of the Gospel UI. 

apiVersion

Required. The version of the Gospel API. 

Default value: v1.1

logErrorsToFileSystem

Message logging is disabled by default. When enabled, the logs are saved to the file system as a text file.

Options: 

  • True 
  • False (default)

errorRecordDefinitionName

The record definition to which the logs are written. Ensure that the record definition has required permissions, and contains fields message and loglevel that are of type string.

uiPort

The port number for the Gospel user interface.

Default value: 8080

uiPassword

The password used for logging on to the UI. the password for this session will be randomly generated and displayed in the terminal.
maxAttempts

The maximum number of attempts for failed actions. 

Default Value: 10

Minimum: 1

Maximum: 100

chainLogLevel

You can set the following severity level of the messages to control the type of messages displayed on the console.

  • DISABLED: Disables logging. 
  • ERROR: Logs errors and critical errors
  • WARN: Logs warnings, errors, and critical errors 
  • INFO: Logs informational messages 
  • DEBUG: Logs debug messages and also logs informational messages, warnings, errors, and critical errors
  • TRACE: Logs trace messages that can be used for problem-solving

Default value: WARN

Mail Plugin Settings

mailUsername

The sender's name as it appears in sent emails
mailPasswordThe password for the email

mailHost

The host IP address of the outgoing mail server

mailAuth

Set to true if the server requires authentication

Options:

  • True
  • False (default)

mailFrom

The email address used to send notifications, that is the 'sender address'

mailPort

The port number used by the outgoing mail server

Default value: 587

mailEnableSSL

Set if the outgoing mail server supports SSL (Secure Sockets Layer) 

  • True
  • False (default)

mailEnableTLS

Set if the outgoing mail server supports TLS (Transport Layer Security)

  • True
  • False (default)

mailRequireTLS

Set to True if TLS is required  

  • True
  • False (default)

Call Plugin Settings

httpTimeout

The maximum time for a connection to be established. 

Default Value: 10

Minimum: 1

Maximum: 3600

userAgent

In HTTP, the User-Agent string is often used for content negotiation, where the origin server selects suitable content or operating parameters for the response. For example, the User-Agent string might be used by a web server to choose variants based on the known capabilities of a particular version of client software.

Default Value: GospelWatcher 

sdkTimeout

SDK requests timeout

Default Value: 15

metricPrintPeriodMinutes

Time in minutes between each set of metrics that will be reported. Set value to 0 to disable.

Default Value: 5

metricLogLevel

Metrics log level

Default Value: DEBUG

blockFetchDelayMS

Time to wait before fetching blocks after receiving a message from the WebSocket (in milliseconds)

Default Value: 500

backOffMaxAttempts

Maximum number of attempts for the BackOff mechanism

Default Value: 10

watcherActionBackOffQueueCapacity

Maximum number of attempts for BackOff mechanism for watcher action

Default Value: 10

watcherDefinitionsBackOffQueueCapacity

Maximum number of attempt for BackOff mechanism for watcher definitions

Default Value: 100

blocksRetrievalBackOffQueueCapacity

Maximum number of attempt for BackOff mechanism for block retrieval

Default Value: 100

  • The WatcherSubscriber Administrative Panel > Config Builder page displays the configuration currently applied when starting the WatcherSubscriber. On this page, you can modify the required configuration and generate a configuration file using the Download Config option. Save the file to the WatcherSubscriber directory as application.properties and restart the WatcherSubscriber to apply the new configuration. 
  • By default, the following timeout properties are set to infinite in the JavaMail Session object. This causes the mail to wait indefinitely for the SMTP server to respond. You can add the following properties to the application.properties and provide a value for the timeout period in milliseconds:

    • mail.smtp.connectiontimeout

    • mail.smtp.timeout

    • mail.smtp.writetimeout

Example Configuration

Below is an example of the application.properties file containing the available configurations that can be provided when starting the WatcherSubscriber:

certificatePath=/home/keys/publickey.pem
privateKeyPath=/home/keys/privatekey.pem
gospelUrl=https://sample-gospel-url.com
apiVersion=v1.1 errorRecordDefinitionName=RecordErrors uiPort=8080 maxAttempts=10 chainLogLevel=WARN uiPassword=password mailUsername=user@company.com mailPassword=password mailHost=smtp.company.com mailAuth=false mailFrom=user@company.com mailPort=587 mailEnableSSL=true mailEnableTLS=true mailRequireTLS=true httpTimeout=10 userAgent=GospelWatcher logErrorsToFileSystem=false sdkTimeout=15 metricPrintPeriodMinutes=5 metricLogLevel=DEBUG blockFetchDelayMS=500 backOffMaxAttempts=10 watcherActionBackOffQueueCapacity=100 watcherDefinitionsBackOffQueueCapacity=100 blocksRetrievalBackOffQueueCapacity=100