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.


  • 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 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 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


Required. The relative or absolute path.

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



Required. The URL of the Gospel UI. 


Required. The version of the Gospel API. 

Default value: v1.1


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


  • True 
  • False (default)


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.


The port number for the Gospel user interface.

Default value: 8080


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

The maximum number of attempts for failed actions. 

Default Value: 10

Minimum: 1

Maximum: 100


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


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


The host IP address of the outgoing mail server


Set to true if the server requires authentication


  • True
  • False (default)


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


The port number used by the outgoing mail server

Default value: 587


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

  • True
  • False (default)


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

  • True
  • False (default)


Set to True if TLS is required  

  • True
  • False (default)

Call Plugin Settings


The maximum time for a connection to be established. 

Default Value: 10

Minimum: 1

Maximum: 3600


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 


SDK requests timeout

Default Value: 15


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

Default Value: 5


Metrics log level

Default Value: DEBUG


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

Default Value: 500


Maximum number of attempts for the BackOff mechanism

Default Value: 10


Maximum number of attempts for BackOff mechanism for watcher action

Default Value: 10


Maximum number of attempt for BackOff mechanism for watcher definitions

Default Value: 100


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 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 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 file containing the available configurations that can be provided when starting the WatcherSubscriber:

apiVersion=v1.1 errorRecordDefinitionName=RecordErrors uiPort=8080 maxAttempts=10 chainLogLevel=WARN uiPassword=password mailPassword=password mailAuth=false 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