Mica 5.0 Upgrade Notes

Summary

To account for the new harmonization standards put forward by Maelstrom Research, upgrading to Mica 5.0 requires a few preparations to ensure proper installation and data integrity.

Before following the steps described below it is strongly recommended that the administrators have a restorable backup of Mica and its database. If a staging server is available, administrators should do the upgrade on this server before replicating it on the production server.

The main changes in Mica 5.0 are:

• Renaming of Harmonization Study to Harmonization Initiative.
• Addition of new fields to better describe a Harmonization Initiative.
• Removal of Population and harmonizationDesign fields from Harmonization Initiative.
• Renaming of Harmonized Dataset to Harmonization Protocol.
• Addition of new fields to better describe a Harmonization Protocol.

To reduce data integrity and website routing errors the name changes are merely at the UI level, the database entities are not changed.

Upgrading an existing installation of Mica

Backups:

Administrators are free to choose their backup techniques; below are the items that should be considered:

• Mica database
• Mica Home folders under /var/lib/mica2

Mica's Upgrade Script

The new Mica installation automatically adds the new fields required by the Maelstrom Standards to the new Harmonization Initiative and Harmonization Protocol configurations, namely, the Schemas and Definitions found under Administration / Harmonization Initiative Configuration and Administration / Harmonization Protocol Configuration.

Any data associated with the old mandatory populations field will be migrated to the new custom populations field. Similarly, all custom fields associated with a Population will be migrated to the new custom field populationModel. Both of these fields can be found under Administration / Harmonization Initiative Configuration.

Harmonization Initiative

As mentioned above populations and harmonizationDesign fields are no longer part of the new standards and are now considered obsolete. Mica administrators can remove these fields from their Mica installation by using the Harmonization Initiative Cleanup Script.

Update the Harmonization Initiative public (website) page

The administrator must be familiar with Public Pages Configuration before proceeding.

In case populations and harmonizationDesign are to be kept, the following instructions describe how to add them to the Mica public pages:

• Stop the Mica server.
• Under /etc/mica2/ create the templates folder.
• Go to templates folder.
• Create/edit study.ftl (to create refer to study.ftl from Github)
• Paste the snippet below <@studyModel study=study type=type/>:

<#if type == "Harmonization">
  <#if (study.model.populations)?? && study.model.populations?size != 0>
    <!-- Populations -->
    <div class="row">
      <div class="col-lg-12">
        <div id="populations" class="card card-info card-outline">
          <div class="card-header">
            <h3 class="card-title">
              <#if study.model.populations?size == 1>
                ${localize(study.model.populations[0].name)}
              <#else>
                <@message "populations"/>
              </#if>
            </h3>
          </div>
          <div class="card-body">
            <#if study.model.populations?size == 1>
            <#else>
              <ul class="nav nav-pills mb-3">
                <#list study.model.populations as pop>
                  <li class="nav-item"><a class="nav-link <#if pop?index == 0>active</#if>" href="#population-${pop.id}" data-toggle="tab">
                    ${localize(pop.name)}</a>
                  </li>
                </#list>
              </ul>
            </#if>
            <div class="tab-content">
              <#list study.model.populations as pop>
                <div class="tab-pane <#if pop?index == 0>active</#if>" id="population-${pop.id}">
                  <div class="mb-3 marked">
                    <template>${localize(pop.description)}</template>
                  </div>
                </div>
              </#list>
            </div>
          </div>
        </div>
      </div>
    </div>
  </#if>
</#if>

• Under the templates folder create libs subfolder.
• Go to the libs subfolder.
• Create/edit study.ftl (to create refer to study.ftl)
• Paste the following snippet right above <#if study.model.additionalInformation??>:

<#if study.model.harmonizationDesign??>
  <div class="row">
    <div class="col-12">
      <div class="card card-info card-outline">
        <div class="card-header">
          <h3 class="card-title">
            <@message "study_taxonomy.vocabulary.harmonizationDesign.title"/>
          </h3>
          <div class="card-tools">
            <button type="button" class="btn btn-tool" data-card-widget="collapse" data-toggle="tooltip" title="<@message "collapse"/>">
              <i class="fas fa-minus"></i></button>
          </div>
        </div>
        <!-- /.card-header -->
        <div class="card-body">
          ${localize(study.model.harmonizationDesign)}
        </div>
      </div>
    </div>
  </div>
</#if>

• Make sure the new folders and the files have the proper permission:

$ sudo chown -R mica:adm /etc/mica2

• Restart Mica server.