Properties Based Configuration for the BMS - IntegratedBreedingPlatform/Documentation GitHub Wiki
Note: These instructions were originally posted on the IBP Confluence site. Going forward, we will maintain this document here.
Introduction
Properties-based configuration is useful when configuration is set once during implementation and then never adjusted. In this way, the penalty of database queries is avoided in selecting the same data over and over. Some parts of this configuration related to rules will move to database table based configuration in future releases.
The files are provided as part of the code deliverable and will reside in each module of the BMS resident in the Tomcat webapps directory
These configuration settings are presented by module in a tabular format, with the following structure:
| Configuration Item | Details | Default Setting |
|---|---|---|
| Element subject to configuration | Background information | Settings that are applied in a default installation of the BMS |
Please Note:
- the abbreviation SNC stands for Should Not Change.
Middleware Config
Purpose
Database connection properties. Only change if the database is resident on a different server from the application, the database port is different, or there are different user credentials you would like to use.
File
This configuration file is located at: [INSTALL_DIR]\infrastructure\tomcat\webapps\Middleware\classes\database.properties (default INSTALL_DIR = C:\BMS4)
Details
| Configuration Item | Details | Default Setting |
|---|---|---|
| db.host=localhost | Localhost | |
| db.port | 43306 | |
| db.username | Root | |
| db.password | ||
| db.workbench.name | (SNC) workbench |
Workbench Config
Purpose
This is the heart of the BMS configuration as controlled through file-based properties. In this file we configure:
- BreedingView - detailed instructions for licensing; information on how to run Breeding View in server and local installation scenarios
- BMS Version
- Tomcat redirect
- Add a text message to the login screen - detailed instructions
- Email for Forgotten Password - [detailed instructions] (https://github.com/IntegratedBreedingPlatform/Documentation/wiki/Networking-for-BMS-4-server-installation)
- Email for Ask Support - [detailed instructions] (https://github.com/IntegratedBreedingPlatform/Documentation/wiki/Networking-for-BMS-4-server-installation)
File
This configuration file is located at: [INSTALL_DIR]\infrastructure\tomcat\webapps\IBPWorkbench\WEB-INF\classes\workbench.properties (default INSTALL_DIR = C:\BMS4)
Details
| Configuration Item | Details | Default Setting |
|---|---|---|
| bmsapi.url | (SNC) (path) http://localhost/bmsapi/ | |
| web.api.url | (SNC) (path) http://localhost/bmsapi/rest/breeding_view/ssa/save_result_summary | |
| workbench.is.single.user.only | Indicates whether the BMS installation is configured to allow multiple users. If not only admin user is enabled | True |
| workbench.is.add.program.enabled | Indicates whether the Add Programs option is available in the instance. | True |
| atomikos.transaction.timeout | Indicates maximum time, in seconds, the system will wait for a transaction to finish | 1200 |
| pagedresult.max.page.size | Maximum number of items in a page for search results | Default is 10000 |
| active.users.max.number | The maximum number of active users allowed | Default is 200 |
| bv.design.validation.on.login.enabled | Enable validation of BV Design license upon log in | false |
Tomcat Settings
| Configuration Item | Details | Default Setting |
|---|---|---|
| tomcat.manager.url | (SNC) http://localhost/manager/text | |
| tomcat.manager.username | (SNC) tomcat | |
| tomcat.manager.password | (SNC) tomcat |
Settings to customize the Login Screen
| Configuration Item | Details | Default Setting |
|---|---|---|
| institute.logo.path | The place where your institution logo is found | |
| footer.message | Sets a text message to appear on the login screen |
SMTP Settings for Forgot password functionality – (CAREFUL – consult IBP)
| Configuration Item | Details | Default Setting |
|---|---|---|
| mail.server.host | ||
| mail.server.port | 587 | |
| mail.server.protocol | SMTP | |
| mail.server.username | ||
| mail.server.sender.email | ||
| mail.server.password | ||
| reset.expiry.hours | 24 |
Settings for Two-Factor Auhentication
| Configuration Item | Details | Default Setting |
|---|---|---|
| security.2fa.enabled | Enable two-factor authentication feature in the BMS instance | true |
| security.2fa.enforce.otp.on.unknown.device | Enforce two-factor authentication when user logs in to an unknown device. If security.2fa.enabled is set to false, this property is automatically ignored and disabled. | false |
| security.2fa.otp.expiry.interval | The number of minutes the OTP (one time password verification code) will expire | Default is 5 minutes |
| security.2fa.otp.length | The length of OTP code | Default is 6 digits |
| security.2fa.otp.maximum.verification.attempts | The number of OTP verification attempts | Default is 5 attempts |
| security.2fa.otp.maximum.verification.attempts.expiry.interval | The number of minutes the user has to wait after maximum verification attempt is reached | Default is 5 minutes |
| security.login.password.minimum.length | The minimum required password length | Default is 6 characters |
| security.login.password.minimum.uppercase | The minimum number of uppercase characters required in a password | Default is 0 |
| security.login.password.minimum.numeric | The minimum number of numeric characters required in a password | Default is 0 |
| security.login.password.minimum.special.character | The minimum number of special characters required in a password. | Default is 0 |
Fieldbook Config
Purpose
In this file we configure:
- Pedigree Generation
- Seed Source/Origin String generation - detailed instructions
- StockID generation - detailed instructions
File
This configuration file is located at: [INSTALL_DIR]\infrastructure\tomcat\webapps\Fieldbook\classes\fieldbook.properties (default INSTALL_DIR = C:\BMS4)
Details
| Configuration Item | Details | Default Setting |
|---|---|---|
| upload.directory | directory where temporary uploads are held | |
| url.program.locations | Should not change | ibpworkbench/content/ProgramLocations?programId= |
| url.program.breeding.methods | Should not change | ibpworkbench/content/ProgramMethods?programId= |
| delete.old.format.temp | set this to the location of the Excel file to use | |
| dataset.import.maximum.row.limit | The maximum number of rows that the dataset importer can process | 10000 |
| atomikos.transaction.timeout | Indicates maximum time, in seconds, the system will wait for a transaction to finish | 1200 |
| maximum.number.of.sub.observation.sets | Maximum number of sub observation sets per study | 4 |
| maximum.number.of.sub.observation.parent.unit | Maximum number of sub observation sets per parent unit | 25 |
| max.file.upload.size | Maximum Upload File size | |
| germplasm.edition.max.recursion | Max recursive queries when editing germplasm pedigree | 10 |
| germplasm.grouping.max.recursion | Max recursive queries when grouping germplasm | 10 |
Crossing Config
Purpose
In this file we configure:
- Crossing
- Cross name prefix generation - detailed instructions
File
The crossing configuration file is configured in ibpcommons.jar but can be overwritten at: [INSTALL_DIR]\infrastructure\tomcat\webapps\Fieldbook\classes\crossing.properties (default INSTALL_DIR = C:\BMS4)
Notes on Germplasm Origin String formatting
-
Formats for the germplasm origin (also interchangeably called seed source or plot code) strings for newly created germplasm e.g. when advancing.
-
Currently following place holders are supported in the origin format string.
-
[NAME] replaced by the name of the nursery/trial. -
[LOCATION] replaced by the value of LOCATION_ABBR (cvterm id = 8189) variable if it is present in nursery/trial settings and has a non empty value. Defaulted to empty string otherwise.
-
[SEASON] replaced by the value of SEASON_VAR (cvterm id = 8371) variable if it is present in nursery/trial settings and has a non empty value. Defaulted to current year and month in YYYYMM format otherwise.
-
[PLOTNO] replaced by the value of PLOT_NO (cvterm id = 8200) assigned to the germplasm
-
[SELECTION_NUMBER] replaced by a dash ("-") + the selection number (ear/plant number) IF advancing method results in selection of multiple plants/ears per plot. Nothing is applied if all plots are selected.
All other characters in the format string are kept as is.
PLEASE NOTE: If the \ character (backslash) is expected to be used as separator in between the place holder components, two of those characters must be used for a single one to appear in final output.
- e.g. [LOCATION]\[PLOTNO] when a single backslash character is expected to be generated between location and plot number.
- This is because a single \ character is a special programming construct to mean escaping for Strings in Java programming language.
Details
| Configuration Item | Details | Default Setting |
|---|---|---|
| pedigree.profile | Pedigree profile | |
| wheat.generation.level | generation levels are numeric and unlimited | 1 |
| maize.generation.level | generation levels are numeric and unlimited | 1 |
| default.generation.level | generation levels are numeric and unlimited | 1 |
| maize.nametype.order | Name types in priority order to stop at while traversing ancestry tree | 1 |
| maize.backcross.notation.female | UNUSED | * |
| maize.backcross.notation.male | UNUSED | * |
| naming.rules | (SNC) RootNameGenerator,Separator,Prefix,Count,Suffix | |
| stockid.rules | (SNC) IDENTIFIER,NOTATION,SEPARATOR | |
| hybrid.breeding.methods | # Comma separated list of breeding method ids (mid in methods table) that are considered Hybrid methods. | |
| germplasm.origin.nurseries.default | # Nurseries for all crops except wheat and maize (see below) will use the following default formats | |
| germplasm.origin.studies.wheat | # Format strings for Maize studies. | |
| germplasm.origin.studies.maize | # Format strings for Wheat nurseries. | |
| germplasm.origin.studies.default | # Trials for all crops except wheat and maize | |
| breeders.cross.id.study | # Format strings for breeders cross id |
For more information on how germplasm names are generated for Crosses and Advanced lines, please see this page.
BMSAPI Config
Purpose
In this file we configure:
- Experiment Design Generation
- Swagger UI
- REST Services configuration and logic
File
This configuration file is located at: [INSTALL_DIR]\infrastructure\tomcat\webapps\BMSAPI\classes\application.properties (default INSTALL_DIR = C:\BMS4)
Spring and API Details
| Configuration Item | Details | Default Setting |
|---|---|---|
| server.port | Spring embedded Tomcat server port | 19080 |
| server.contextPath | Root context of API webapplication | /bmsapi |
| baseUrl | Public absolute base url for BMS instance (considering proxies). Needed for BrAPI OAuth/OIDC flow. E.g: https://www.bms-uat-test.net/ | |
| spring.thymeleaf.cache | Flag for enabling Thymeleaf cache | true |
| spring.jackson.mapper.default-view-inclusion | Flag for including default view | true |
| authentication.xauth.secret | Secret token for use encrypting authentication token | Default value extracted to BMSConfig so that is not exposed publicly, but the default value remains the same |
| authentication.xauth.tokenValidityInSeconds | Validity period of authentication token | 21600 |
| maximum.number.of.sub.observation.sets | Maximum number of sub observation sets per study | Default is 4 |
| maximum.number.of.sub.observation.parent.unit | Maximum number of sub observation sets per parent unit | Default is 25 |
| bms.version | Version of the BMS | (depends on version installed) |
| pagedresult.max.page.size | Maximum number of items in a page for search results | Default is 10000 |
| swagger.enable | Flag whether to enable Swagger UI | true |
| germplasm.list.add.entries.limit | Max number of entries that can be added to a list when this one has parents related columns added | Default is 500 |
| max.file.upload.size | Max file size | 10 MB |
| germplasm.edition.max.recursion | Max recursive queries when editing germplasm pedigree | 10 |
| export.lot.max.total.results | maximum number of entries for a lot export operation | 20000 |
| export.germplasm.max.total.results | maximum number of entries for a germplasm export operation | 3000 |
| germplasm.merge.max.number | Maximum number of germplasm that can be merged at a time | 100 |
| cop.max.entries | Maximum number of germplasm entries for COP (Coefficient Of Parentage) operation | 20 |
Experimental Design Generation
| Configuration Item | Details | Default Setting |
|---|---|---|
| upload.directory | directory where temporary uploads are held | |
| bv.design.path | Path of BVDesign binary | ./tools/breeding_view/bin/BVDesign.exe |
| bv.design.runner.timeout | Timeout in minutes of design generation call | 10 |
| design.runner | Class for running experimental design service | org.ibp.api.java.impl.middleware.design.runner.BVDesignRunner |
| design.runner.license.service | Service class for checking design service license | |
| org.ibp.api.java.impl.middleware.design.runner.BVDesignLicenseService |
File storage config: aws or sftp, from environment variables
| Configuration Item | Details | Default Setting |
|---|---|---|
| aws.accessKeyId | ||
| aws.secretAccessKey | ||
| aws.bucketName | ||
| aws.region | ||
| sftp.host | ||
| sftp.username | ||
| sftp.password | ||
| sftp.privateKeyPath |