Knowledge Base

What is the Relationship Import Plugin?
If you need to create many relationships between existing items in Jama, the Relationship Import Plugin can help you achieve this goal. Using a CSV file, the Relationship Import Plugin can save you time by relating many existing items in Jama at once, rather than manually relating one at a time.


Setting Up the Plugin
Before you can use the Plugin, it will need to be configured by an administrator in your Jama instance. To do this, navigate to Admin > Plugins. Select Add Entry. 

• Name: The name of the plugin that will display to you and your users.
  
  
• Enabled: Having this checked will make this plugin available to your users.
  
  
• Class: The Class is referring to the name of the object defined in Jama's source code. For this plugin in particular, you can have your plugin be for creating relationships within a single project, or cross-project:

• • Single Project: com.jamasoftware.contour.plugin.jama.ImportRelationships
  • Cross-Project: com.jamasoftware.contour.plugin.jama.ImportRelationshipsCrossProject
    
    
• Type: For the Relationship Import Plugin, you will choose Import

• Parameters: Parameters help tell Jama what items you want to use for the Relationship Plugin. There are four parameters to determine:

• • The parent (or upstream item) type
  • The child (or downstream item) type
  • The parent item field
  • The child item field
    • You will need to define what Item Type the Parent and Child items are (shown below as parentType or childType), as well as what Field you are using within those item types (shown as parentField or childField). Please note that parameters are case sensitive. Be sure you are capitalizing (or not capitalizing) the correct words.

• parentType and childType
  • The parameter for parentType and childType will look like:

parentType=X;
childType=X;

• • • A semicolon is required at the end of each parameter. The "X" you see in the parameter will be the API ID of the Item Type you wish to use. You can find the API ID under Admin > Item Types. 

• • • • For example, if you wanted to create parameters for relating Requirements (upstream) to Use Cases (downstream), it would look like:

parentType=24;
childType=25;
 

• parentField and childField
  • The next parameters to create are determining which field of the parent and child item you wish you use. You can see which fields are available to use under Admin > Item Types > [Highlight the item type you want to use in the parameter] > Config. 

• • • If you wanted to use the ID (also known as the Unique ID) for your parentField or childField, your parameter would look like the following:

parentField=documentKey;
 childField=documentKey;

• • • • Remember that parameters are case sensitive, and a semicolon is needed at the end of each parameter.

• Plugin Notes: A short description of the plugin that is not required for configuration.
  • Your completed plugin configuration will look something similar to the following:

• • • Your parameters can be written in any order. As long as they are case sensitive with the correct Type and Field and have a semicolon at the end, your plugin will be able to relate the items successfully. Once everything looks correct, save your plugin.

Importing Relationships Using the Plugin
To import relationships into Jama, you will need to create a CSV file. The spreadsheet will have two columns:

• Column A: parent, or upstream, items
• Column B: child, or downstream, items

In Jama, select Project > Import > Custom Import.



This will open a pop-up window with some settings you need to configure. Select a Destination: Select a location within your project for the Relationship Import plugin. While destination is a required setting, it does not matter what location you choose for this import

• Select Custom Importer: Select the import plugin you created
• Field Delimiter: For this plugin, you will select Comma
• Optional Encoding: For this plugin, you will select UTF8

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

Frequently Asked Questions

How Many Relationships Can I Import At Once?
It is recommended to import relationships in batches up to 250 items to prevent performance degradation.

Do I Need to Install Anything on My Jama Instance?
No, the plugin is automatically installed by default.

Does It Support One-to-Many Relationships as Well as Many-to-Many Relationships? 
Yes. To import many relationships to one item, create duplicate cell combinations in the CSV file:



Does It Work Cross-Project?
Yes, you will need to use the Cross-Project class when setting up the plugin.

I'm Receiving the Message: "Success: X Items Imported," However No Relationships Were Created. Why Could This Be Happening?
There are a few things you can check when you run into this scenario: 

• Double-check that you are importing a CSV file, and not an XLS file.
• Give Jama time to process the relationships. If you are importing more than a hundred relationships, this will not be instantaneous.
• Check that your parameters are written correctly, and are referencing the right API ID or Field.

If you are using a self-hosted version of Jama, you can look at your contour.log file to confirm which items are causing problems. Here is an example of the logs when the parentField and childField parameters were written incorrectly, as

parentField=ID; 
 childField=ID;

You can see that the parameter is using ID, which is a Label instead of a Field (the parameter should be parentField=documentKey;). The logs will tell you which items were skipped in the plugin, and why (these have been bolded).

2015-10-07 15:40:33,514 INFO  http-bio-8082-exec-8  [com.jamasoftware.contour.service.impl.DataImportServiceImpl] - Starting Custom Import
 2015-10-07 15:40:33,517 WARN  http-bio-8082-exec-8  [com.jamasoftware.contour.plugin.jama.ImportRelationships] - 

Relationship skipped: the Requirement does not exist in system for: CP-REQ-10

 2015-10-07 15:40:33,519 WARN  http-bio-8082-exec-8  [com.jamasoftware.contour.plugin.jama.ImportRelationships] - 

Relationship skipped: the Requirement does not exist in system for: CP-REQ-8

 2015-10-07 15:40:33,520 WARN  http-bio-8082-exec-8  [com.jamasoftware.contour.plugin.jama.ImportRelationships] - 

Relationship skipped: the Requirement does not exist in system for: CP-REQ-9

 2015-10-07 15:40:33,520 INFO  http-bio-8082-exec-8  [com.jamasoftware.contour.service.impl.DataImportServiceImpl] - Finished Custom Import

If you are still unable to successfully import relationships, please submit a ticket with Support and attach screenshots of your plugin settings, Item Types, and the CSV file.


#traceability #administration