Correcting a Typo in a Custom Field’s Unique Field Name Without Impacting Existing Data

Published Date: May 13, 2026
Audience: Everyone
Products and Versions Covered: 

• Jama Connect® version(s)
  • Cloud/CVC
  • Self-hosted - All versions

Summary

A typo in a custom field’s Unique Field Name (for example, workflow_staus$214 instead of workflow_status$214) can create downstream problems for reporting and automation, such as velocity report exports and scripts that expect consistent field identifiers across item types. In Jama Connect®, the Unique Field Name may also be referenced in configuration data (for example, rollup configuration and saved filters), which makes direct renaming risky.

This article explains safer, supportable approaches to resolve the problem without directly modifying the database and without losing existing data, including approaches that work when items are workflow-locked (for example, locked at an “Approved” status).

Symptoms

• Custom reporting (including velocity report exports) is difficult because one item type uses a misspelled unique field identifier.
• REST API and/or scripting across multiple item types is harder to generalize because the same conceptual field has different unique field names.
• Admins request to “just rename” the Unique Field Name to correct the typo.

Cause

A custom field’s Unique Field Name can be referenced outside of the “field definition” record (for example, within serialized configuration values). Renaming it directly can break dependent configurations (saved filters, rollups, dashboards, etc.) if those references are not updated at the same time. In addition, changing these identifiers directly at the database level is typically not a supported operation due to risk of unintended side effects. 

Example: typo correction request in a Parallel Development Tech Preview environment for staus → status with a requirement to avoid impacting existing data.

Resolution

Recommended Approach: Create a New Field and Migrate Data (No Direct DB Rename)

1. Create a new field on the applicable item type with the correct Unique Field Name (for example, status) and the same field type as the old field.
2. Identify all affected items:
   • Use filters to collect items where the old field has data (or where the old field exists on the item type).
3. Migrate values from the old field to the new field using one of the following methods:
   • Excel Roundtrip (best when items are editable), or
   • API-based migration (best when items may be workflow-locked; see below).
4. After validating the migration results:
   • Keep the old field (recommended when you want to avoid any potential ripple effects and simply omit it from views/exports), or
   • Delete the old field (only after confirming it’s not needed anywhere and data has been fully migrated).

This approach avoids the risks associated with renaming an identifier that may be referenced in configuration strings (saved filters/rollups/dashboards/etc.).

Option A: Excel Roundtrip Migration (When Items Can Be Edited)

Use an Excel Roundtrip to populate the new (correctly named) field from the old (typo’d) field:

1. Add the new field to the item type.
2. Run a filter/smart filter to gather the target items.
3. Perform an Excel Roundtrip export for the filtered set.
4. In Excel, ensure values from the old field are mapped into the new field on import.
5. Import back, using conflict handling appropriate for your scenario (for example, “Excel wins” if you want the imported value to overwrite blanks).

Notes from the case: roundtrip migration was tested as effective even across multiple projects/containers, but large volumes may require batching.

Option B: API-Based Migration for Workflow-Locked Items (Unlock → Update → Re-lock)

If items are system-locked by workflow (for example, locked at “Approved”), Excel Roundtrip may not be feasible. In that scenario, migrate data via an API/scripted process that temporarily transitions items to an unlocked state, updates the field, then transitions them back.

High-level outline:

1. Create the new field with the correct Unique Field Name.
2. For each impacted item:
   • Read the value from the old field.
   • If the item is in a locked status, transition it to an unlocked status.
   • Update the new field with the old value.
   • Transition the item back to its original locked status (for example, “Approved”).
   • Add an appropriate transition comment (example: “Transitioned for clerical API edit”) to preserve traceability.

Workflow configuration guidance:

• Ensure the transition path from Approved → temporary unlocked status → Approved is only available to a controlled integration user/account (for example, via workflow transition permissions).

If you do not have internal development resources, consider engaging Jama’s services organization (for example, Extended Engineering Services) for scripted migration assistance, per your account team’s process.

Additional Resources

• Workflow Transitions Action Text
• Lock items in a workflow (Organization or project admin)
• Success Programs
• Success Catalog
• Datasheets
• Request a Solution Offering or Training from the Success Catalog

Feedback:
We welcome your input! Please sign in to leave any comments, suggestions, or ideas for improvement below.