ReLink - Admin Instructions

The purpose of this Plugin is to help you import Excel data with traceability and external links intact. Configuration for the plugin is per project. You can import data from excel with traces and/or with external links e.g. Jira, Github, Gitlub. To import items with traces and external links you need you prepare one Excel including both. The instructions on how to prepare the Excel file can be found here: {Insert Importing data from Excel}

Overall you have two

1. The first option is to import data keeping traces.

2. The second option is about importing external links

The description is available in the Manual: https://docs23.matrixreq.com/usv23/how-can-i-import-data-from-excel-with-links-betwee

This guide provides step-by-step instructions on importing data from Excel with trace links in Matrix.

Prerequisites:

1. Enable Excel Importer:

   • Ensure the Excel importer is enabled in the Matrix setup. Note that Matrix may require a small add-on for link creation post-import.

2. Category and Traceability Rules:

   • Define categories, associated fields, and traceability rules before initiating the import.

3. Configure Item Fields:

   • The minimum required fields for configuring the plugin in an item are:

• “Legacy ID” → Text Line Control:
  This field represents the ID of the current item and can be any unique text.

• “Legacy down” → Text Line Control:
  This field represents the downlinked ID of an item.

• “References” → Downlinks:
  Configure downlinks as references.

Note:

• IDs are crucial for correct linking. Ensure they are accurately listed correctly Excel and are in line with the traces configuration.

Importing Data

1. Data Preparation in Excel:

   • Organize data by placing each Matrix category in a separate Excel sheet or file. Refer to the detailed guide on Importing Data from Excel for specifics.

2. Import All Data:

   • Use the Matrix Excel importer to bring in all the prepared data. You can do so

3. Link Recreation:

   • After importing, recreate the necessary links to establish connections between items.

Import Process

1. Import Items:

   • Use the Matrix Excel importer to import all items across categories.

After completing the import process, your data representation will resemble the following. In this illustration, we have two categories, REQ and SPEC. REQ items have the capability to establish downlinks to SPEC items.

A SPEC category may be represented as follows:

{insert SPEC screenshot}

Whilst the REQ category may be structured like this:

{insert REQ screenshot}

[So the REQ-41 (aka my_req_00) knows that it needs to be linked to some SPECs with legacy ids my_spec_id_01 and my_spec_id_03 ]

Now that the data is imported we will need to proceed with the Admin configuration of the Plugin you just installed.

Link Recreation

Configuration:

To define the Plugin, navigate to the Admin settings and add the project you’d like to use the Plugin in. To configure the ReLink Plugin add or edit the "reLinkConfig" in the project setting. This setting contains rules for link recreation.

The parameters of these rules explain as follows:

{
    menuEntry:string // e.g. "relink" what to show in menu if "" nothing will be shown == rule is disabled
    category: string // e.g. "REQ": parent category from where links are created
    linksField: string // e.g. "legacy down": name of field which contains comma separated links into Matrix or external tool
    downCategory?:string // e.g. "SPEC": to where to create links (if empty no downlinks will be created)
    downLegacyField?:string // e.g. "legacy id": name of legacy field for identification against links
	upCategory?:string // e.g. "SPEC": to where to create links (if empty no uplinks will be created)
    upLegacyField?:string // e.g. "legacyId": name of legacy field for identification against links
}

2. Example Configuration:

   JS

   {
       menuEntry: "relink",
       category: "REQ",
       linksField: "legacy down",
       downCategory: "SPEC",
       downLegacyField: "legacy id",
       upCategory: "SPEC",
       upLegacyField: "legacyId"
   }

Link Creation:

After establishing the rules, refresh the client and choose a specific folder where you wish to generate the links.

The tool operates similarly if you store UP links in Matrix fields instead of DOWN, using symmetric settings. In the menu, you will find the tool for link creation:

{screenshot missing}

Note: Once the links have been created they are removed from the legacy downlink field, so you can immediately see if some links could not be created.

HINT:

If you omit the downLegacyField, the tool uses the ID of down items.