Handling documentKey Field in DX ReqIF Imports

Overview

This article explains the issue where documentKey appears as an editable import field in Data Exchange (DX) and causes Jama to reject items during ReqIF import.

1. Issue Summary

✔ documentKey is a system-generated, non-editable field in Jama Connect.
✔ DX incorrectly presents documentKey as an editable destination field in import mapping.
✔ If documentKey is mapped in DX, Jama rejects all items mapped to this field.
✔ This issue is observed in DX 3.8.4 but may affect other versions.

2. Symptoms of the Issue

🚨 What users experience:
✔ documentKey appears as a selectable field in the DX import mapping interface.
✔ If mapped, Jama rejects all affected items during import.
✔ Import logs may show errors related to documentKey mapping.

🚨 Screenshot Example:
✔ Users have reported seeing documentKey listed as an editable field in the mapping generator.

3. Workarounds & Fixes

✅ Do not map documentKey when creating import mappings in DX.
✅ Manually review import mapping files to ensure documentKey is not mapped.
✅ If issues persist, recreate the mapping file without documentKey.
✅ DX Development Work Item: A fix is being considered to remove non-editable fields from mapping dropdowns in a future update.

4. Best Practices for ReqIF Imports

✔ Verify that only editable fields are mapped in DX import configurations.
✔ Cross-check mapping files before executing the import.
✔ If unsure, consult Jama field definitions to confirm editable vs. system-managed fields.
✔ Monitor future DX updates for a permanent fix.

5. Conclusion

✔ documentKey should never be mapped in DX imports.
✔ Mapping documentKey causes item rejections in Jama during ReqIF import.
✔ DX teams are considering a fix to prevent non-editable fields from appearing in mapping dropdowns.