How to use Round Trip

By Janessa posted 08-17-2017 13:57

  
The Round-Trip feature is designed to conduct mass editing of multiple items in Jama. 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, 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: Roundtrip 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 in turn be added into Jama 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 are all columns that can be filled out, 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. (Be sure to save the file before importing.) Right click the folder or set you exported your items from, and select "Import".

 




 

Select your file and hit "Next".




 

Step 4: Adjusting Import Settings

Jama will now ask you to choose the Excel Options for your import. It is important to note two things on this section:

1. The Excel Header Row starts at 2 on the Round-Trip 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. 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, however our example will use only four fields, marked with red arrows in the picture 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 to see your updates.






If you are still experiencing issues with Round-Trip, please contact Jama Support and we will be happy to help you further!
25 comments
513 views

Permalink

Tags

  • Jama features and functionality
  • Office Templates
  • requirements management

Comments

02-28-2017 08: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!)

11-01-2016 17:14

Ohhh... Good catch on that!

10-31-2016 18: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!).

10-31-2016 15: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.

10-29-2016 15: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.

10-28-2016 23: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.

10-28-2016 21: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)?

10-09-2015 18: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.

10-09-2015 17: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?

06-11-2015 22: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 :-)

06-11-2015 22: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! 

06-11-2015 22: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.

06-11-2015 22: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

06-11-2015 16: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. 

06-11-2015 16: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.

06-10-2015 23: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!

06-10-2015 23: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!

06-10-2015 15: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

06-10-2015 15: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

06-10-2015 15: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.

06-10-2015 15: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.

06-10-2015 14:47

Hello Janessa,

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

05-26-2015 19: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.

05-19-2015 16: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

02-16-2015 00: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.