Best Practices for Creating and Configuring a New Item Type

Amanda Jennewein
Amanda Jennewein

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 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 try to guess an appropriate field name based on the field label you've provided, but please make sure it is easy to identify and remember and that it explains the purpose of the field. We recommend that you use 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 more accessible and more powerful. For example, when performing a description search, 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
The difference between predefined and custom fields in Jama Software isn't always apparent to users. Other than a few field types for which we don't provide a predefined option (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. For more information, see our article: Delete or Update an Item Type’s Field Without Losing Data.

Please feel free to leave feedback in the comments below.

Related to

Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request



Please sign in to leave a comment.