docs/installation-and-operations/jira-migration/custom-fields/README.md
The Jira Migrator automatically detects custom fields that are actually used in your imported issues, and creates matching OpenProject custom fields for them. Fields that exist in Jira but contain no values in any imported issue are ignored.
All newly created custom fields are placed in a Jira import group in the work package form configuration and are not assigned to any existing project by default.
The following Jira custom field types are imported:
| Jira field type | OpenProject field type |
|---|---|
| Single select | List |
| Radio buttons | List |
| Multi-select | List |
| Checkboxes | Boolean or List |
| Text field | Text (short) |
| Text area | Text (long) |
| Date picker | Date |
| Number | Float |
| URL | Link (URL) |
| User picker | User |
| Multi-user picker | User |
| Cascading select | Hierarchy or List |
| Labels | List |
Read more about OpenProject custom field formats and the Hierarchy format in particular in the system administration guide.
Jira custom field types not listed above are skipped. This includes (but is not limited to):
If a field is skipped, its values are not imported and no OpenProject custom field is created for it.
Jira checkbox fields (multicheckboxes) behave differently depending on how many options the field has in the imported data:
<FieldName> - <OptionValue>. It is true if the issue had that option checked.If a checkbox field has different option sets across projects (via Field Contexts), both rules above apply independently per context group. A single Jira checkbox field can result in multiple OpenProject custom fields.
Jira cascading select fields have two import modes depending on your OpenProject edition:
Animals > Cat is stored as the Cat item under the Animals parent.Animals > Cat produces both Animals and Animals / Cat as separate list options.
The selected value on each issue becomes the deepest matching path.Jira Labels fields and any String list custom fields do not expose all their allowed values within Field contexts through the Jira API. Instead, the migrator scans all imported issues and collects every distinct string value actually used. These collected values become the option list for a multi-value List custom field in OpenProject.
Values that do not appear in any issue are not added to the option list.
Jira text area fields store content in Jira wiki markup format. The migrator automatically converts this markup to OpenProject's Markdown format. The conversion covers common elements (headings, bold, italic, links, code blocks, tables), but plugin-specific markup may not convert perfectly.
User picker and multi-user picker fields are resolved by matching the Jira user key to a user who is a member of the migrated project. If the Jira user was not imported because they are not a member of any selected project, the user reference is dropped for that field value.
In Jira Data Center, a single custom field can have different allowed values in different projects or for different issue types, via Field Contexts. The migrator handles this as follows:
<FieldName> (<ProjectKey>) to disambiguate.During issue import, each issue is matched to the context whose projects and issue types fit. If no context matches (for example, the field was removed from a screen after values were set), the first available context is used as a fallback so no data is silently lost.
If an OpenProject custom field with the same name and format already exists (from a previous import run or created manually), the migrator reuses it instead of creating a duplicate. The existing custom field is linked to the import and its values are preserved.
For Hierarchy and List fields, deduplication is not attempted because option lists may differ - a new custom field is always created for these types.
If a name collision exists but the formats differ, the migrator appends a numeric suffix to the new field name (e.g., My Field (2)).