Knowledge Base

 View Only

Best Practices for Creating and Configuring a New Item Type

By Alexander Kahn posted 03-13-2015 15:39


Field Labels vs. Field Names

When configuring a new field, Jama Software will ask you to specify both a Field Label and a Unique Field Name


The unique field name doesn't seem to matter much at first glance, as it does not appear in Jama Software's UI, but this name is used to power many of Jama Software's underlying functions, such as search. Jama Software will attempt to guess an appropriate field name based on the field label you've provided, but make sure it is easy to identify and remember and that it explains the purpose of the field. We recommend using camel case notation for your field names. Examples of a well-named field include numAffectedUsers or isArchived.

If you have several item types in which you'd like to track the same information, we strongly recommend using the same unique field name for these fields in each item type. Doing so can make searching and reporting both easier and more powerful. For example, performing a search for description:hello will return any in-scope item whose "description" field contains the word hello; however, if one of your item types' Rich Text field is named summary, that field will not be searched and returned.

Predefined vs. Custom Fields
It isn't always obvious to users what the difference is between predefined and custom fields in Jama Software. Other than a few field types that we don't provide a predefined option for (e.g. Item of Type fields), choosing one option over the other won't generally make a difference to the end user. However, if you plan on doing any reporting with either the BIRT or Velocity reporting engines, choosing Predefined Fields when possible will simplify the document type's underlying schema and make those fields a bit easier to handle when writing those reports. Similar to the note on field names above, if you have multiple item types tracking the same or similar information, it can be helpful to make sure those item types are using the same predefined field to capture that information.


Text Boxes vs. Text Fields
Text fields are designed for short, unformatted text such as titles. They have a 255-character limit and cannot display Rich Text or contain formatting such as line breaks. Text boxes have a much larger storage capacity and can be either plain-text- or Rich Text-formatted. If you anticipate making heavy use of the list view to view and edit your text, it may be appropriate to use a text field. In most cases, however, you will find that text boxes are a more versatile and better choice for storing your data.

In the predefined field options, Text fields are listed as string[1-10] and Text boxes are listed as text[1-7].


What If I Need to Change Something Later?
Don't sweat it; it happens to the best of us. See our article: Delete or Update an Item Type’s Field Without Losing Data for more information.



06-20-2016 03:35

Hi Alexander,

thanks for your article. I'm developing some BIRT Reports and I would like to use some of the predefined fields on a Test Run (one of date1-5 and one of flag1-5) but those predefined fields are not available for a test run item type. Strange enough, because Test Runs are stored in a Document Table, where the fields exist.

Do you know if there is any way to make those fields available for a Test Run?

Thanks in advance for your feedback,


03-22-2016 20:15

A couple of questions:
- We have 3,000 requirements in a single project so would like to understand whether there is any performance issues with using custom fields vs predefined fields. Predefined fields look like they use otherwise unused fields in the main item db record so I would assume they are faster.
- You mention that predefined fields are better for custom report access - are there any advantages/disadvantages for REST API access?  For SOAP access it is certainly easier to figure out what is in a custom field vs string1....

05-15-2015 17:42

Andrew, what do you envision using this Parking Lot item type for? Is it some sort of draft state for an item?

05-15-2015 14:18

Thanks Alexander for posting this. 

How would you suggest about creating an item type called Parking Lot. Does Contour have anything like this already?