Importing Relationships Using the Jama Connect Import Relationships Plugin

Who: Organization Administrator

What: Batch import relationships via the Import Relationship Plugin

When: After importing two or more item types with known relationships, usually at the beginning of a Jama implementation

Where: In Jama Connect

Why: The Relationship Plugin allows Organization Admins to batch create relationships between existing items in the application by importing a CSV of known relationships

How: Read on!

When transitioning to a requirements management tool like Jama Connect, teams who have existing requirements and traceability need a way to import those requirements while maintaining existing relationships. In this article, we will walk through an example of a customer who has established requirements and relationships between them.

In the example below, we see an Excel spreadsheet that shows the relationships between two types of requirements (item types): User Needs (orange, left, upstream) and Product Requirements (blue, right, downstream).

Figure 1 Example Excel Trace Matrix

We will follow the process outlined below to accomplish these needs:

• Import User Needs *see prerequisite below
• Import Product Requirements *see prerequisite below
• Identify Parameters for the Plugin
• Create a New Import Relationship Plugin
• Create CSV Spreadsheet Documenting Upstream and Downstream Relationships
• Batch Import Relationships Using the Custom Import Functionality

* Prerequisite for Importing User Needs and Product Requirements
Before importing our User Needs and Product Requirements, we need to consider how we plan to “tell” Jama what upstream items (User Needs) trace to what downstream items (Product Requirements). The easiest way to do this is to import the existing ID of the items we need to import; it’s clear in the example above that UN-1 traces to PR-1 and PR-2.

Because Jama will automatically assign a unique Project ID to each item we import, we will add a text field labeled Legacy ID* to the User Need and Product Requirement item types to capture the existing IDs.

*Note – another label may be used to identify this field; Legacy ID is just an example.

Figure 2 Add Legacy ID Text Field to User Need Item Type

Figure 3 Add Legacy ID Text Field to Product Requirement Item Type 

When we import our User Needs and Product Requirements, we will map the ID fields of the User Needs and Product Requirements shown in the trace matrix above to these new Legacy ID fields on the User Need and Product Requirement item types Jama.

 Now we are ready to import our User Needs and Product Requirements.

Step 1: Import User Needs

Import User Needs by following the instructions here: Import from Microsoft Excel

Figure 4 Map Jama Item Field "Legacy ID" to ID

 Here is our result after completing the import of our User Needs:

Figure 5 Imported User Needs
 

Step 2: Import Product Requirements

Import Product Requirements by following the instructions here: Import from Microsoft Excel

Figure 6 Map Jama Item Field "Legacy ID" to ID

Here is our result after completing the import of our Product Requirements:

 Figure 7 Imported Product Requirements

 
Step 3: Gather Parameters for the Plugin

Before we create our plugin, we need to gather some information for our parent (upstream) and child (downstream) item types so we can define the plugin parameters. The plugin uses the API ID of the parentType and childType to identify these parameters. It might be helpful to open a text editor or jot down the parameters as they are located; they will be used in Step 4.

Let’s identify the parentType and childType for our example, along with their API IDs. We will find this information under Admin > Item Types.

• parentType: Defines which item type to use for the parent (upstream) relationship.

Our upstream item is the User Need, so the User Need is our parentType. The API ID of the User Need, shown below, is 113 (parentType=113).

Figure 8 Identify the parentType API ID

• childType: Defines which item type to use for the child (downstream) relationship.

Our downstream item is the Product Requirement, so the Product Requirement is the childType. The API ID of the Product Requirement, shown below, is 136 (childType=136).

Figure 9 Identify the childType API ID

Now we need to identify the fields that will be used to find the parent and downstream items. The plugin uses the Unique Field Names of the parentField and childField to identify these parameters.

• parentField: Defines which field to use to find the parent (upstream) item.

Our parent (upstream) item is the User Need; the parentField – the field we are using to find the child (downstream) item – is Legacy and the Unique Field Name is legacy_id. The parentField, shown below, is legacy_id (parentField=legacy_id).

Figure 10 Finding the parentField of the User Need

• childField: Defines which field to use to find the child (downstream) item.

Our child (downstream) item is the Product Requirement; the childField – the field we are using to find the child (downstream) item – is Legacy ID and the Unique Field Name is legacy_id. The childField, shown below, is legacy_id (childField=legacy_id)

Figure 11 Finding the childField of the Product Requirement

Step 4: Create a New Relationship Import Plugin

Once we have identified the parameters, we can now create our plugin. These instructions are also outlined in the User Guide here: Configure Import Relationships Plugin

1. Select Admin > Organization, then select Plugins > Add entry.
2. In the Add plugin entry window, enter the following information and select Save:

Figure 12 Add Plugin Entry Window

• • Name: Import Relationships (or whatever name you want visible to users)
  • Enabled: Check this box to make the plugin available to users.
  • Class (case sensitive):  Enter the name of the object defined in the source code.
    • For a single project enter: com.jamasoftware.contour.plugin.jama.ImportRelationships
    • For cross-project imports enter: com.jamasoftware.contour.plugin.jama.ImportRelationshipsCrossProject and include parentProjectid and childProjectid

• • Type: Import
  • Parameters:  Set Relationship Parameters
    • Example:

      parentType=24; childType=25; parentField=documentKey; childField=documentKey; * parentProjectid=4; * childProjectid=5; * only add parentProjectid and childProjectid for cross-project imports

• • Plugin notes: Add any notes you have here. This will not be visible to end-users.

Figure 13 Create the Import Relationship Plugin from the Parameters Identified in Step 3

Step 5: Create CSV

Relationships are imported to Jama Connect from a CSV file. The file consists of two columns. This process is also outlined in the User Guide here: Import Relationships

1. Column A: Parent or upstream item references (User Need: Legacy ID field)
2. Column B: Child or downstream item references (Product Requirement: Legacy ID field)

Figure 14 Create CSV

Tip: It's possible to import multiple relationships to a single item or many relationships to many items by creating duplicate cell combinations for those items. In the example above, UN-1 has two downstream relationships – PR-1 and PR-2.

Step 6: Batch Import Relationships Using the Custom Import Functionality

Now it’s time to complete our relationship import. This process is also outlined in the User Guide here: Import Relationships

In Jama Connect, select Project > Import > Custom Import. This opens a pop-up window with settings to configure.

Select a destination: Select the location in your project for the Import Relationships Plugin. While destination is a required setting, it doesn't affect the import.

Select custom importer: Select the Import Relationships Plugin created by an organization admin.

Field delimiter: Select Comma.

Optional encoding: Select UTF8.

Select a file to import: Upload the CSV file containing the required relationships.

Figure 15 Custom Import

Attach your CSV file and select Import. You see a notification at the top of your screen after the import is complete that says, "Success: X items imported."

Note: You might see the Success pop-up message even if relationships weren't successfully imported. Try the following if this happens:

1. Double-check that you're importing a file with the extension .csv.
2. Give Jama Connect time to process the relationships. If you're importing more than 100 relationships, the update isn't instantaneous. We recommend importing relationships are imported in small batches no larger than 250 at a time.
3. Check that your parameters are written correctly and reference the right API ID or Field.

Now we are finished! Let’s look at our newly imported relationships as shown in the Trace View – you’ll see that our User Needs are now correctly traced to our Product Requirements.

Figure 16 Trace View of Imported Relationships