Best Practices for Creating and Configuring a New Item Type

Author: Amanda Jennewein

Updated: September 2024

Audience: System Engineers, Engineering Leadership, etc

Products Applicable: Jama Connect®

Use Case

Best Practices for Creating and Configuring a New Item Type

Field Labels vs. Field Names

When setting up a new field in Jama Connect®, you will specify a Field Label and a Unique Field Name.

The specific field name may seem insignificant initially, as it does not appear in Jama Software's user interface. However, this name is crucial for many underlying functions of Jama Software, including search. Jama Connect® will try to suggest a suitable field name based on the label you gave me. Still, ensuring the name is easily identifiable, memorable, and descriptive of the field's purpose is essential. We recommend that you use camel case notation for your field names. Good examples of well-named fields include "numAffectedUsers" and "isArchived."

If you have several item types for which you'd like to track the same information, we strongly recommend using the same unique field name for each kind. This can make searching and reporting more accessible and powerful.

When performing a description search, "hello" will return any in-scope item whose "description" field contains that word. However, if one of your item types has a Rich Text field named "summary," that field will not be searched or returned.

Predefined vs. Customer Fields

The difference between predefined and custom fields in Jama Connect® might not always be evident to users. Apart from a few field types for which we don't offer a predefined option (e.g., Item of Type fields), choosing one option over the other generally won't affect the end user. However, if you intend to create reports using the BIRT or Velocity reporting engines, opting for Predefined Fields when possible will simplify the underlying schema of the document type and make handling those fields easier when writing reports. Similar to the note on field names, if you have multiple item types tracking the same or similar information, it can be beneficial to ensure that those item types use the same predefined field to capture that information.

Text Boxes vs. Text Fields

Text fields are for short, unformatted text-like titles, with a 255-character limit and no support for Rich Text or formatting like line breaks. On the other hand, text boxes have a larger storage capacity and can be plain-text or Rich Text-formatted. A text field may be appropriate if you view and edit your text frequently using the list view. However, in most cases, 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 you need to change something later?

No problem; for more information, see:

• Delete or Update an Item Type’s Field Without Losing Data.

References

• Delete or Update an Item Type’s Field Without Losing Data.
• Success Programs
• Success Catalog
• Datasheets
• Request a Solution Offering or Training from the Success Catalog

Please feel free to leave feedback in the comments below.