Blogs

How to Use Round Trip for Editing

By Janessa Olson posted 08-17-2017 10:57

  

The Round Trip feature is designed to conduct mass editing of multiple items in Jama Connect. It is important to keep in mind that this feature is exclusive to Excel documents only.  

This is done so by exporting the desired items to an Excel document, making the desired changes offline, and importing the edited document back into Jama Connect, where you will see the updated changes to the items.


Step 1: Selecting and Exporting Items for Round Trip
In this example, we will be using test cases. While in List View, select the files you wish to export for Round Trip. You can select multiple items by holding the Ctrl button while clicking on the items you need.



Go to the "Export" in the top right corner, and select "Office Templates".



This will open a pop-up window. Select "Excel Export for Roundtrip" and click "Run". Note: Round Trip is only available to be exported to Excel. Rich Text fields can oftentimes create difficulties within Excel and should not be used for Round Trip.



Your export should open shortly, looking similar to the picture below:




Step 2: Editing Your Excel Document
You are now ready to make changes to your document. In the above picture, we see three test cases with names that need to be changed, which we have edited in the picture below:




Adding Items
It is also possible to add new items to the Round Trip export that will be added into Jama Connect once the document is imported. 



If you add an item to your Round Trip document, it will appear at the bottom of the Set or Folder you decide to import to. It is important to keep in mind that you can only add one type of item, which will be the same as the chosen set or folder. The ID and Global ID will be assigned to the item once it is imported, so be sure to leave those columns blank. Assigned and Priority all columns that can be filled but are not required. 


Step 3: Importing Your Modified Document
When you are satisfied with the changes to your document, it is time to import it back into Jama Connect (be sure to save the file before importing). Go to the folder or set you exported your items from, and select "Import".




Select your file and hit "Next".





Step 4: Adjusting Settings
Jama Connect will now ask you to choose the Excel options for your import. It is important to note two things this section:

1. The Excel Header Row starts at 2 on the Roundtrip export; be sure to change it as it will automatically be selected as Row 1.
2. Making sure the "Update Items" box is checked. You also have the option to decide how your items will update if there is a conflict between your Excel document and Jama Connect. If you want your Excel document to "win" should a conflict occur, be sure to change this option.



The Field Mapping area has many item fields for customizing details of the item you are importing. You will map this the same way you map a typical Excel document. You should have something like the image shown below:





Step 5: Set the Hierarchy
Since this is a Round Trip document, it is likely that you will not need to set the hierarchy, and we will not for this example. However, should you need to use hierarchy in your other Excel imports, you can do so by indenting or coloring cells. Please note that for Round Trip reports, hierarchy changes will only be applied to new items in the Round Trip report. 

More information on hierarchies is available in our User Guide, available here.




 
Step 6: Review and Submit Your Import



Remember to refresh your window in Jama Connect to see your updates.





If you are still experiencing issues with Round Trip, please contact Jama Software Support and we will be happy to help you further!



#requirementsmanagement #OfficeTemplates
27 comments
1216 views

Comments

David Allison
05-08-2023 14:34

So, is it not possible to just export the test cases in a folder where there are also text items? From the list view, I selected only the test case items, but when I do the round robin export, I get all items in the folder. It seems like it is ignoring which items I selected.

Nick Helsper
03-12-2019 14:55

The second to last screenshot on this page has a button that says "Save this as new document mapping." 

What does this button do?  I successfully saved the mapping, but I am not sure where the mapping is being saved or what is being saved.  

Any help would be appreciated.

Thanks

Iain Sommerville
02-28-2017 05:01

Another quirk of round-trip export/imports that we stumbled on is that it can overwrite another project if you mix up the round trip spreadsheets so care must be taken when using this feature.

This can occur when you:
- Export a round-trip spreadsheet from project A
- Make the changes in the spreadsheet thinking it was exported from project B (easy to do when you do a lot of round-tripping)
- Go to project B and import the round-trip spreadsheet into a set in project B

The import will actually occur into project A, however the dashboard entries make it look like the import happened in project B so it may not be obvious what has happened.  According to support this isn't a bug(?) - it is something to be aware of (especially when making copies of projects to give people for training!)

Kristina King
11-01-2016 14:14

Ohhh... Good catch on that!

Iain Sommerville
10-31-2016 15:20

I did some more experimenting with this and discovered the following:
- If you export all requirements across multiple sets using round trip export, Jama will import changes to all requirements across all the sets for the item type associated with the set selected at import and for folders and text items across all sets (at least all sets of that item type)
So it actually works fine for my need to import changes across 47 sets of requirements at once (the UI is just a bit quirky).  I just thought I would post this for other people's benefit (particularly people just expecting changes to a single set!).

Kristina King
10-31-2016 12:48

I would say round-trip support of folders in this case is wonky; it should respect hierarchy and you ideally should be able to make changes to folders via round-trip, but there are some bugs that prevent it from always working as expected. Text items are a special sort since they can live anywhere (e.g. outside of containers). I wish there were a way to force this to work given what you point out.

Iain Sommerville
10-29-2016 12:34

That is what the online documentation states; however it does (and has since I have been using Jama) also import changes to text items and folders within the set if these were exported at the same time.  Of course only fields in the list view can be changed.

Kristina King
10-28-2016 20:35

Iain, 
The problem lies in the fact that Round Trip will import only one item type at a time...and because containers (folders, sets), are considered item types, they can't be roud-tripped. I don't have another suggestion.

Iain Sommerville
10-28-2016 18:56

We would like to use roundtrips to update fields within our dataset of requirements.  These 4,000 or so requirements are organized into 45 sets under a single component.  From experimentation I couldn't find a way of updating more than a single set at a time even though the round-trip export allows export of all requirements at once.

The documentation doesn't make it clear what targets are allowed for imports (though the cheatsheet implies that it has to be a set or lower).  Any ideas to simplify the import across all sets (other then using the API)?

Kristina King
10-09-2015 15:28

Victoria, it looks like you also submitted a support ticket for this issue. Because Paul has already started the troubleshooting process, I think it's best to let him continue. Don't hesitate to post to the community in the future, though! We have support engineers available in both places.

Victoria Lin
10-09-2015 14:10

Hi, I have a similar question on importing excel files to update and overwrite data in the same fields. I updated some of the data in my Excel file which was originally created via a round trip export. I had selected "Update, on import Excel wins" option, but when I import, I have another duplicate set of requirements that are imported, rather than updating the requirements that I already have. How do I update my current fields with the updated info?

Anand Seetharaam
06-11-2015 19:59

@Stephen: Unfortunately our requirements run beyond 255. I assume the Name is supposed to handle "Title" which is not available for us.. All good :-)

Janessa Olson
06-11-2015 19:52

Hi Anand! I'm so glad to hear that Round Trip is now going smoothly for you (no doubt thanks to Stephen's tips)! Please let us know if you run into any other hurdles! 

swoo Woo
06-11-2015 19:48

Anand, I am glad that you are able to import. A name field is configured so that it is limited to 255 characters if I am not mistaken. Have a good rest of day.

Anand Seetharaam
06-11-2015 19:40

Stephen,

That worked. In our project we don't use "Name" - since it truncates above certain limit, instead we were using Description and Requirement Text. For this specific purpose I double mapped "Name" as well as "Requirement Text" and the items got added.

Thanks

swoo Woo
06-11-2015 13:25

Hi Anand, I am sure that Janessa and official Jama support engineers can help you. The only hint I have is that you might have to make sure the mandatory field "name" is filled in. If it's blank, then Jama Excel import will skip that line entirely. You could also try to debug your import process by importing just a few new items. Good luck. 

Anand Seetharaam
06-11-2015 13:12

Stephen, 

(1) There was no confirmation for new items being created. there were other confirmations though for updates, conflicts, etc
(2) Refreshed. Tried Logging out  and Logging Back in
(3) I suspected this, so searched all my requirements with the keywords from new items. Nothing shows up, also scrolled down manually looking for them.

Janessa,

Created a ticket below. This has the email (screenshots) of the scenario I am observing

Request #22678

Thank you guys.

Janessa Olson
06-10-2015 20:03

Hi Anand! Stephen brought up some really good troubleshooting questions and pointers (thanks, Stephen!), however if you're still running into issues with the round trip report, I am more than happy to assist you through opening a Support ticket!

Janessa Olson
06-10-2015 20:01

Thank you for reading it, Stephen! I love your cheat sheet, especially #1, #16, and #22 (or, the ones that have personally tripped me up the most)! 

I also think performing a baseline is a really great idea; thank you for the tip!

Bob Dilly
06-10-2015 12:42

Within the past week I had a desire to do something like this.  The task was to build a duplicate folder structure for test cases - without adding test cases.  I didn't actually try it, but if I recall the import process determines which row is construed as a folder and which isn't - and the "leaves" seem to be treated as items, not folders.  (If you follow that...)

Bob

swoo Woo
06-10-2015 12:34

Hi Janessa,

Thanks for your detailed and graphical tutorial on this very import but sometimes complex function. Keep up the good job. By the way, here is my cheatsheet :-)

Purpose: A Jama author (with read/write permission) can use Excel-RoundTrip (RT) report to make complex/batch updates to a selection of items instead of editing items one-by-one, in list/reading view, or using batch update (setting a collection of items’ properties to one value only).

 Overview:

1.      Practice

2.      Perform a baseline in case something bad happens that require restoring of old data. (Requires a Project Administrator Access)

3.      Select items by selecting folders or using a filter

4.      Change view to the list view

5.      May need to configure the list view to show the fields that you want to export and edit

6.      Upper-right-hand-corner select Export/Office Template/

7.      Select RoundTrip Template

8.      Export by selecting Run

9.      Run the VBA

10. (For those self-hosted Jama instances that have RoundTrip template embedded with Excel VBA macros in .xlsm file, please save the file as .xlsx as Jama currently does not recognize .xlsm files.)

11.  Import at the target folder or a  higher folder/set

12.  Follow the import wizard

13.  Select the Excel workbook

14.  Select worksheet

15.  Select header row

16.  MUST, MUST, MUST check the box for roundtrip. (otherwise you are importing items as new)

17.  Map the fields

18.  Fields that are mandatory need a default value. Go ahead and select anything. If no input fields are mapped, nothing will be updated. If input fields are mapped, then the values in Excel worksheet will be imported correctly.

19.  Verify the first item

20.  Run

21.  Optionally save the mapping file for re-use next time

22.  Verify manually

swoo Woo
06-10-2015 12:28

Hi Anand,

Sorry for your troubles. Can you explain a little more about your issue? 1) At the end of the Excel import, did you check whether the confirmation says whether the items were created? 2) Please refresh your explorer and item pane. 3) Be aware that the new items are added at the end of the highest set/folder where you have selected as target import. Good luck in resolving your issue.  Thanks for your patience and understanding.

swoo Woo
06-10-2015 12:26

Kristina, thanks for re-iterating this phenomenon of Excel RoundTrip not being able to update a field that's "Item of type." Jama might consider making an enhancement for this.

Anand Seetharaam
06-10-2015 11:47

Hello Janessa,

I am unable to add new items (requirements) during my round trips

Kristina King
05-26-2015 16:05

Mike, I'm sorry we missed this question. The answer is no—there is no way to map values via import or Round Trip to the "item of type" field. Functionality is quite limited for this item type.

Mike Donlon
05-19-2015 13:35

Hi Janessa,

If I have a pick list field which is using "item of type", is there a way to update/create the values using the Round Trip template?  I can't seem to find a way to export the value or a way to set the value on import.

Thanks,
Mike

Bob Dilly
02-15-2015 21:03

We use this often, particularly to make global changes - something which shows up quite a bit in the fora.

One thing we experimented with the other day was added a step to a set of test cases.  We found you need to preserve the values in the hidden low columns, i.e. duplicate rows rather than insert new rows, but it worked well for us.