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

 i. 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.
 ii. MeLuDI v1.6.0 should be used with Tomcat 9.

=== b. Create BASE projects to be used with MeLuDI ===

 i. 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.
 ii. 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.
 iii. 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.

 i. Backward compatibility with original MeLuDI project.[[BR]]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.
 ii. Recommendations for choice of project-specific prefixes for item names.[[BR]]For each item type, it is strongly recommended that unique prefixes are chosen for all projects to be used with MeLuDI.
 iii. Use with non-configured projects.[[BR]]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` ===

 i. 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` ||
|| `referral-prefix` || Prefix for referral item names in project || `` ||
|| `referral-num-digits` || # Digits in referral item names in project || `` ||
|| `sample-item-prefix` || Prefix for sample item names in project || `ML` ||
|| `sample-item-num-digits` || # Digits in sample item names in project || `5` ||
|| `blood-item-prefix` || Prefix for blood item names in project || `ML` ||
|| `blood-item-num-digits` || # Digits in sample item names in project || `5` ||
|| `ffpe-block-item-prefix` || Prefix for FFPE block item names in project || `ML` ||
|| `ffpe-block-item-num-digits` || # Digits in FFPE block 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` ||
|| `uses-site-prefix` || Flag indicating if site prefixes are used || `false` ||
|| `site-prefix-hash-list` || Comma-separated list of comma-separated pairs of site prefix and site name || `` ||
|| `uses-referral-creation` || Flag indicating if referral creation is used || `false` ||
|| `uses-site-specific-referral-templates` || Flag indicating if site specific referral PDF templates are used || `false` ||
|| `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:[[BR]]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.[[BR]]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 ||
[[BR]]
|| '''Specimen type''' ||
|| '''Menu option value''' || '''Menu option text''' ||
|| `` || unknown ||
|| `Primary` || Primary tumour ||
|| `MetastasisDistant` || Metastasis ||
[[BR]]
|| '''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 ||

An example of a site prefix hash list is:

|| `site-prefix-hash-list` || 01,Goteborg,33,Halmstad,22,Helsingborg,99,Jonkoping,55,Karlskrona,44,Kristianstad,02,Linkoping,11,Lund,77,Malmo,08,Stockholm,04,Trelleborg,05,Umea,88,Uppsala,66,Vaxjo ||

=== e. Install MeLuDI configuration file `meludi-config.xml` ===

 i. 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 ===

 i. 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.
 ii. 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

 i. 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

 i. 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.