Updating to MeLuDI 1.6.0

MeLuDI 1.6.0 contains added functionality to simplify using it with multiple BASE projects. Updating to MeLuDI 1.6.0 therefore requires some extra steps, in addition to the standard update procedure.

Follow this procedure:

1. Preparations before update to MeLuDI v1.6.0

a. Update BASE to at least version 3.15.0, if needed

1. MeLuDI v1.6.0 requires at least version 3.15.0 of BASE. If needed, update BASE before installing MeLuDI v1.6.0. If the current BASE version is 3.5.0 (minimum version for use with MeLuDI version 1.3.3), perform a two-step upgrade, first 3.5.0 -> 3.6.0, then 3.6.0 -> 3.7.0, followed by 3.7.0 -> 3.15.0.
2. MeLuDI v1.6.0 should be used with Tomcat 9.

b. Create BASE projects to be used with MeLuDI

1. Select BASE menu View -> Projects. Add all projects, that are intended to be used initially with MeLuDI. It is recommended to use complete and descriptive names, since the projects are to be selected from their names in BASE "Recently used projects" menu and the project names will be included in headers of generated protocols and reports (names may include spaces). Abbreviations that are commonly used, are of course eligible.
2. Make sure that Protocol and other BASE items needed for the MeLuDI pipeline, are available for the BASE projects to be used with MeLuDI. If several projects should use the same item, there is no need to store multiple copies of the latter, but one item can be shared to all the projects.
3. Make a note of the project names, since they are needed for the MeLuDI configuration file.

c. Information and recommendations regarding new MeLuDI configuration file meludi-config.xml

MeLuDI 1.6.0 relies on a data in configuration file meludi-config.xml to obtain project-specific settings.

1. Backward compatibility with original MeLuDI project.
   If MeLuDI 1.6.0 is to be installed on a BASE server used to store data for the original MeLuDI project (named "MeLuDi" in BASE), settings for the latter must be added in the configuration file, to enable MeLuDI to be used as previously with this project (see next section for what settings to use). Even if no new samples will be registered in the original MeLuDI project, the configuration of prefixes is needed to ensure that "Case summary", "Sample source report", "Sample processing statistics", and other inspection wizards can be used to inspect the data.
2. Recommendations for choice of project-specific prefixes for item names.
   For each item type, it is strongly recommended that unique prefixes are chosen for all projects to be used with MeLuDI.
3. Use with non-configured projects.
   MeLuDI 1.6.0 allows a non-configured BASE project to be used as active project, but all item name prefixes will then be empty strings, and item names will consist of a pure serial number with optional suffix (e.g. for storage boxes). If more than one non-configured project is used, the same name might be used for items in different projects, which may cause confusion. This is therefore not recommended.

d. Create MeLuDI configuration file meludi-config.xml

1. Create a MeLuDI configuration file meludi-config.xml with information on each project to be used with MeLuDI. The configuration file has the following structure, where new elements in MeLuDI 1.6.0 are marked with "NEW" (not part of the XML contents):

<?xml version="1.0" encoding="UTF-8"?>
<meludi>
	<projects>
		<project>
			<name>...</name>
NEW			<referral-prefix>...</referral-prefix>
NEW			<referral-num-digits>...</referral-num-digits>
			<sample-item-prefix>...</sample-item-prefix>
			<sample-item-num-digits>...</sample-item-num-digits>
NEW			<blood-item-prefix>...</blood-item-prefix>
NEW			<blood-item-num-digits>...</blood-item-num-digits>
NEW			<ffpe-block-item-prefix>...</ffpe-block-item-prefix>
NEW			<ffpe-block-item-num-digits>...</ffpe-item-num-digits>
			<storage-box-prefix>...</storage-box-prefix>
			<storage-box-num-digits>...</storage-box-num-digits>
			<start-list-item-prefix>...</start-list-item-prefix>
			<start-list-item-num-digits>...</start-list-item-num-digits>
			<start-plate-item-prefix>...</start-plate-item-prefix>
			<start-plate-item-num-digits>...</start-plate-item-num-digits>
			<patient-item-prefix>...</patient-item-prefix>
			<patient-item-num-digits>...</patient-item-num-digits>
			<libprep-kit-item-prefix>...</libprep-kit-item-prefix>
			<libprep-kit-item-num-digits>...</libprep-kit-item-num-digits>
NEW			<uses-site-prefix>...</uses-site-prefix>
NEW			<site-prefix-hash-list>...</site-prefix-hash-list>
NEW			<uses-referral-creation>...</uses-referral-creation>
NEW			<uses-site-specific-referral-templates>...</uses-site-specific-referral-templates>
			<project-focus-default>...</project-focus-default>
			<specimen-type-default>...</specimen-type-default>
			<specimen-input-type-default>...</specimen-input-type-default>
			<extracts-from-first-specimen-only-default>...</extracts-from-first-specimen-only-default>
			<deparaffinization-rna-volume-microliters-default>...</deparaffinization-rna-volume-microliters-default>
			<deparaffinization-dna-volume-microliters-default>...</deparaffinization-dna-volume-microliters-default>
		</project>
		...
	</projects>
</meludi>

Add a <project></project> XML block for each project. Configuration values for each project:

XML tag name	Description	Value for original MeLuDI project
name	Name of the project item in BASE	MeLuDi
sample-item-prefix	Prefix for sample item names in project	ML
sample-item-num-digits	# Digits in sample item names in project	5
storage-box-prefix	Prefix for storage box names in project	ML_
storage-box-num-digits	# Digits in storage box names in project	4
start-list-item-prefix	Prefix for start list item names in project	SL
start-list-item-num-digits	# Digits in start list item names in project	5
start-plate-item-prefix	Prefix for start plate item names in project	LP
start-plate-item-num-digits	# Digits in start plate item names in project	5
patient-item-prefix	Prefix for patient item names in project	MLP
patient-item-num-digits	# Digits in patient item names in project	6
libprep-kit-item-prefix	Prefix for library preparation kit item names in project	LP_kit_
libprep-kit-item-num-digits	# Digits in library preparation kit item names in project	3
project-focus-default	Cancer type studied in the project	<empty string> (unknown)
specimen-type-default	Primary tumor or metastasis	<empty string> (unknown)
specimen-input-type-default	The form in which a specimen is delivered	<empty string> (unknown)
extracts-from-first-specimen-only-default	Flag indicating whether extract items should be created for first specimen only	false
deparaffinization-rna-volume-microliters-default	RNA elution volume (µl)	25
deparaffinization-dna-volume-microliters-default	DNA elution volume (µl)	25

Notes:
1. The "name" tag value is used by MeLuDI to identify the project item in BASE, so it is essential that it corresponds exactly to the project item name in BASE.
2. It is allowed to configure MeLuDI for projects, before the latter are created in BASE. A project configuration will only be used, when a BASE project is selected as active.

The menu option values for project focus, specimen type, and specimen input type to use for default choices are:

Project focus
Menu option value	Menu option text
	unknown
melanoma	Melanoma
lungcancer	Lung cancer
coloncancer	Colon cancer
GIST	GIST (Gastrointestinal stromal tumour)
breastcancer	Breast cancer

Specimen type
Menu option value	Menu option text
	unknown
Primary	Primary tumour
MetastasisDistant	Metastasis

Specimen input type
Menu option value	Menu option text
	unknown
fresh_frozen	Fresh frozen
ffpe_section	FFPE section
ffpe_punch	FFPE punch
ffpe_slide	FFPE slide
cell_line	Cell line

e. Install MeLuDI configuration file meludi-config.xml

1. Place configuration file meludi-config.xml on the BASE server in same directory as base.config.

f. Update MeLuDI case label info file Case_Label_Info.csv, if existing

1. Check on the BASE server if a MeLuDI case label info file Case_Label_Info.csv exists in BASE user files directory. If it does, MeLuDI versions prior to 1.6.0 stored information in a single line about the highest case number, for which a label file had been created. The line consisted of the string "Highest case number;" followed by the case number. MeLuDI 1.6.0 will store information in one line per project, for which a label file has been created, where each line consists of the project name, followed by a tab character and the case number. In order to make sure that information for the original MeLuDI project is retained, replace the string "Highest case number;" with "MeLuDi" followed by a tab character (Note that for historical reasons, the original MeLuDI project was named "MeLuDi" with a lowercase i at the end). As an example, if the original contents of file Case_Label_Info.csv was "Highest case number;1272", it should be changed to "MeLuDi 1272", with a tab character separating the project name and the highest label case number.
2. If no case label info file Case_Label_Info.csv exists, no action is needed, since MeLuDI 1.6.0 will create it automatically.

2. Update to MeLuDI v1.6.0

1. After installation of MeLuDI v1.6.0, run the installation wizard, for each of the configured projects as active project. This assumes that a BASE project exists for all the projects configured in meludi-config.xml. However, it is allowed to configure projects in advance, and then create BASE projects when needed. In that case, run the installation wizard after a configured project has been created in BASE.

3. Check/modify roles of users

1. MeLuDI v1.6.0 allows a PAD/CL number (Patho-Anatomical Diagnosis/cytology number) to be registered with a case, even if no other patient data is known (e.g. personal number). However, the PAD/CL input field will be disabled if the logged-in user does not have PatientCurator or Administrator roles. If registration of a PAD/CL number is essential, make sure that all users, that should perform the registration, have PatientCurator or Administrator roles.