Step 1- Configure and start LedgerBridge

Download files

Before you begin, 

Starting LedgerBridge

You can start LedgerBridge using any of the following options:

Start LedgerBridge with default settings

Starting LedgerBridge without any configuration allows you to log on to the LedgerBridge administration console and view the configurations available for starting LedgerBridge and the LedgerBridge connector. Run the following command in the terminal:

java -jar gospel-ledgerbridge-<version>.jar 

Log on to the LedgerBridge administration console (http://localhost:8080/login) using the password provided in the terminal. On this page, you can enter the required configuration and generate a properties file using the Download Config option. Save the file (application.properties) to the directory which contains the gospel-ledgerbridge-<version>.jar file, and restart LedgerBridge to apply the new configuration. 

When you start LedgerBridge without configuration, LedgerBridge starts with minimal functionalities. This option is useful only for viewing the dashboard and generating the properties file. To be able to import records, start LedgerBridge either by passing parameters as command-line arguments or by defining the properties file.

The LedgerBridge Administrative Panel > Config Builder page displays the configuration currently applied when starting the LedgerBridge. 

On this page, you can provide the required configuration and generate a configuration file using the Download Config option. Save the file to the LedgerBridge directory as application.properties and restart LedgerBridge to apply the new configuration. 

Pass parameters in the terminal as command-line arguments

To pass the parameters in the terminal as command-line arguments, go to the directory where the gospel-ledgerbridge-<version>.jar file is located, and run the following command:


java -jar gospel-ledgerbridge-<version>.jar --gospelUrl=<https://URL> --pathToCertificate=<path/../certificate> --pathToPrivateKey=<path/../privatecertificate>
  • The code example lists some configuration values required for starting LedgerBridge. You can provide additional configuration parameters if required.
  • You can download the certificate and private key for the current session from the Tools > Certificate Tools page. 

Log on to the LedgerBridge administration console (http://localhost:8080/login) using the password provided in the terminal. 

Defining properties 

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.

If you have defined the configuration in the application.properties file, open the terminal, go to the directory where the gospel-ledgerbridge-<version>.jar file is located, and run the following command:

java -jar gospel-ledgerbridge-<version>.jar 

Log on to the LedgerBridge administration console (http://localhost:8080/login). Use the password defined in the properties file, or use the password generated for this session displayed in the terminal.

Configuring LedgerBridge Settings 

The table lists and describes the configuration values you can set in the applications.properties or pass as parameters in the terminal when starting the LedgerBridge:

  • If you make changes to the configuration, you must restart LedgerBridge to apply the changes.
  • The parameters set from the command line have precedence over the properties file in the project directory.
Properties 
Description
Value
queueSize

Size of the record queue is allowed to grow to before it is consumed and sent to LedgerBridge. 

If the number is too large, the amount of queue space taken up can become excessive as the data is not committed, and cannot be removed from the queue until the data is committed.

Default: 1000

Minimum value: 100

Maximum value = 10000

batchSize

The records are sent to the LedgerBridge in batches. Set the number of records to be sent in each batch.

For example, if you set the value to a big number, more data is sent to the LedgerBridge, and if the value is set to a small number, frequent requests are made to the LedgerBridge for data.

Default: 10

Minimum value: 1 

Maximum value: 100

batchTimeoutSecondsTime in seconds after which a record batch gets consumed, even if it has not reached the set batch size.

Minimum value: 1

Maximum value: 100

preserveSharedSecretBetweenRuns

When set to true, the LedgerBridge Connector attempts to load secret from the file system, based on the parameters passed. Otherwise, it generates a random secret.

  • True (Default)
  • False
sharedSecretFileNameRequired. The file containing the secret passphrase that is shared between Ledgerbridge and Ledgerbridge connectorDefault: .ledgerbridge
pathToDirectoryContainingSharedSecret

Required. The directory containing the secret passphrase that is shared between Ledgerbridge and Ledgerbridge connector


sharedSecretLength

The shared secret length in bytes

Default: 64

Minimum value: 32

Maximum value: 1024

tokenValidityPeriodSeconds

The period (in seconds) after which a LedgerBridge connection-token becomes invalid

Default: 15

Minimum value: 1

Maximum value: 3600

logErrorsToFileSystem

Message logging is disabled by default. When enabled, it logs on files (debug.log and error.log) in a /logs folder created under the current path and archives it through a rolling policy.

The maximum default size of the log files is 10 MB. When the maximum size is reached, a back up of the file is created and renamed to <filename.timestamp>.log.


  • True 
  • False (Default)
logDirectoryThe path to the directory where the log files are saved.Default: ./logs
pathToCertificateThe full path to the directory containing the certificate file and private key. You can download the certificate and private key for the current session from the Tools > Certificate Tools page./path/to/certificate
pathToPrivateKey/path/to/key
gospelUrlRequired. The address of the Gospel UI. http://localhost:8080
apiVersion

The version of the Gospel API. 

Default: v1.1
idField

Required. The field in the data source that defines the ID for the records. 

You can use %AUTOID% to automatically generate the ID when importing the records.

Default: id
actionRequired. Value for the "Action" field. 

Expected values are, 

  • write (Default)
  • delete
  • read
uiPasswordThe password used for logging on to the UI. If you leave this field empty, the password that is automatically generated when you start LedgerBridge is displayed in the terminal. 
errorRecordDefinitionId

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.


errorRecordDefinitionVersionThe version of the record definition to which the logs are written.
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: DISABLED
recordDefinitionCacheMinutesDuration in minutes for which the Record Definition is stored in the cache.Default: 60
backendConnectionTimeoutSeconds

Duration in seconds for which LedgerBridge should wait to get the RecordDefinition from the backend before timing out.

Default: 15
metricPrintPeriodMinutes

Duration in minutes between each set of metrics that are reported in the console

Set the value to zero (0) to disable the feature.

Default: 5
metricLogLevel

Records the rate of logged events by their logging level

Ensure that the following properties are set in the application.properties to enable logging:

logging.level.com.gospel=DEBUG

logging.level.tech.gospel=DEBUG

Default: DEBUG

Options: 

  • DEBUG
  • ERROR
  • INFO
  • TRACE
  • WARN 

Example Configuration

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

queueSize=100
batchSize=10
batchTimeoutSeconds=1
preserveSharedSecretBetweenRuns=true
sharedSecretFileName=.ledgerbridge
pathToDirectoryContainingSharedSecret=.
sharedSecretLength=64
tokenValidityPeriodSeconds=15
logErrorsToFileSystem=true
logDirectory=./logs
pathToCertificate=spcert.pem
pathToPrivateKey=spkey.pem
gospelUrl=https://sample-gospel-url.com
apiVersion=v1.1
idField=id
action=write
uiPassword=p
errorRecordDefinitionId=RecordErrors
errorRecordDefinitionVersion=1
chainLogLevel=DISABLED
recordDefinitionCacheMinutes=60
backendConnectionTimeOutSeconds=15
metricPrintPeriodMinutes=5
metricLogLevel=DEBUG