In the Forge manifest, delete each jiraIssueFields module from the connectModules section and rewrite each one as a new jira:customField entry in the modules section.

In each replacement jira:customField entry:

Use the same key value as the original jiraIssueFields module module.
Set the migratedFromConnect field to true

Refer to the following references for additional syntax conversion details of different fields.

String and Number fields

Connect module

1
2
connectModules:
  jira:jiraIssueFields:
    - key: connect-read-only-string
      name:
        value: connect-read-only-string-field
      description:
        value: connect-read-only-string-field
      type: string

Forge replacement

1
2
modules:
  jira:customField:
    - key: connect-read-only-string
      name: connect-read-only-string-field
      description: connect-read-only-string-field
      type: string
      migratedFromConnect: true

Read-only fields

For read-only Connect issue fields, the replacement Forge module must:

Match the type in Forge manifest to the value in property.type in connect.
If the Connect read-only issue field refers to a collection of Strings, the equivalent Forge custom field module should have collection: list. See collection types for more details.
Ensure connectFieldProperty refers to the entityProperty details used by the connect issue field.

Connect module

1
2
connectModules:
  jira:jiraIssueFields:
    - key: connect-read-only-date
      name:
        value: connect-read-only-date-field
      description:
        value: connect-read-only-date-field
      type: read_only
      property:
        path: date
        key: statistics
        type: date

Forge replacement

1
2
app:
  id: ari:cloud:ecosystem::app/<<app_id>>
  connect:
    key: connect-fields-migration-test-app
    remote: connect
    authentication: jwt

modules:
  jira:customField:
    - key: connect-read-only-date
      name: connect-read-only-date-field
      description: connect-read-only-date-field
      type: date
      migratedFromConnect: true
      readOnly: true
      connectFieldProperty:
        key: statistics
        path: date

Migration tracking

When a new Forge app version replaces Connect jiraIssueFields entries with Forge customField, installing the app triggers a Jira background task. This task:

Validates data integrity.
Switches the custom field implementation from Connect to Forge, requiring no admin action. For example, if customfield_10054 referred to the Connect issueField schema, then customfield_10054 will refer to Forge's customField schema after switching.
Makes the old Connect data available to the Forge custom field.

Migration may take a few minutes. Internal tests show migrating a Connect read-only number field used in 110K issues took about 40 seconds.

Task progress API

Your Forge app can use the following API endoint to track the migration status of a specific customField:

1
2
GET /rest/atlassian-connect/1/migration/{connectKey}/{jiraIssueFieldsKey}/task

The value of connectKey is the Connect app key, and jiraIssueFieldsKey is the key of the Jira Issue Field module. For example, to track the sample Read-only field entry, use:

1
2
GET /rest/atlassian-connect/1/migration/connect-fields-migration-test-app/connect-read-only-date/task

For more information, see the Task progress API documentation.

Limitations

Once a module is migrated to Forge, it cannot be migrated back to Connect.

Testing

You are now ready to verify the migration on the Jira instance that your team uses for testing.

Install the Connect app.
Adopt Forge for your Connect app following this guide.
Replace Connect jira:jiraIssueFields module with Forge jira:customField module. Install the updated app on the Jira instance.
Verify that the custom field name reflects the one used by Forge (if different).
Verify that existing custom field data is accessible and works as expected.
1. Custom fields referencing the migrated issue field modules display correctly in issues.
2. The custom field values are preserved and accessible after migration.