Restore Objects in Jira Issue Fields

Owned by Gia Jgarkava
Last updated: Nov 04, 2024
12 min read

Table of Contents

Restoring or Migrating Objects in issue fields - Server/DC-to-Cloud, Cloud-to-Cloud (including current instance)

After the schemas are restored, you can restore the corresponding objects in Jira issue fields. The process of the migration is identical for all the three cases:

  • Restore of the schema on the current instance

  • Migration of the schema from Data Center / Server to Cloud

  • Migration of the schema from Cloud to another Cloud

Prerequisites

Before starting the process, the following prerequisites should be fulfilled:

  • Make sure that the projects and issues are already migrated Cloud.

  • The user (email) indicated in the current connection must be added to the project(s) and have valid permission to view and edit.

  • After backup is completed, objects in issue fields are backed up in the background. The backup status of the objects in issue fields can be checked under “Objects in issues status“ column of the “Available backups“ grid. Only after the status is COMPLETED, it is possible to start restoring objects in Issue fields. While the status is IN PROGRESS, “Restore objects in issues” will be disabled (see Restore Process). By clicking the (i) info button, you will see the number of issues in which the objects from this schema are selected. If no issues were found (i.e. “Objects in issues status“ is “NO DATA FOUND“), The “Restore objects in issues” will be disabled.

  • image-20240118-163042.png
    Objects in issues status in backup

Due to the known issue of Jira Service Manaement Cloud, after importing or migrating Assets custom fields values to another site Jira will show an error for all Assets custom fields on Issue view (JSDCLOUD-12773). Therefore, after restoring Asset object fields, the app will not be able to fill the fields with the Asset objects. To deal with this issue, try the following workaround before migrating the object fields: Bulk update Assets Object custom fields via External System Import | Atlassian Documentation.

Restore Process

After you have successfully migrated the schema either from Server/DC to Cloud, or from Cloud to another Cloud, you will see the button “Restore objects in issues“ along the corresponding schema Restores grid:

image-20240216-092729.png
“Objects in issues” button

The process is identical for the Server/DC-to-Cloud and Cloud-to-Cloud migrations.

The “Restore objects in issues“ will be disabled, until “Objects in issues status” is IN PROGRESS (see Prerequisites) or if another process of objects restore in fields is ongoing.

After clicking the button, you will see the popup with the prerequisites reminder, Start Process button, and link to the current instructions:

1. Fields - validate fields to restore

After clicking Start process button, you will see the list of the Jira fields of the original Server/DC or Cloud instance, where the Asset objects from the original backup are presented:

From here you can select the fields, that you want to restore and click the Continue button. The selected fields will be checked and the validation results will be shown in the next screen.

2. Fields check - field validation results

For the selected fields you will see the validation results on the next screen:

There can be various results of the validation:

  • The Asset field does not exist in the target Cloud instance and will be created with the next step if you select the field from the list.

    • The field(s) will be created with the contexts that exist in the field configuration on the source instance (i.e. in the backup) and have the schema, restore of which was initiated the current “objects in issues“ update process. Additionally, if the specific project is indicated in the context, the context will be configured with the “global” setting.

  • The Asset field already exists in Cloud, therefore there is no need to create it. No action is needed in this case

  • There is more than one Asset field with the same name name in the target Cloud instance. In such case, you will not be able to proceed with the restore, until only one Asset field with the proper name remains in the Cloud instance.

  • To deal with such an issue, you can:

    • Rename one of the corresponding Asset fields in Jira (leaving a proper name to the field, which you will use for the restore) or

    • Go to the original instance (where the backup was taken from), change the corresponding Asset field name to the unique one, backup and restore the schema again, and Start the process of Issues restore from the beginning.

If there are blocking issues with the fields, the Continue button will be disabled. After sorting the issues out and restarting the check, if there are no issues that might prevent the restore, click the enabled Continue button to proceed to the screens configuration step.

3. Screens configuration

At this stage, you can configure the screens and the tabs for the Assets custom fields and subsequently associate fields to the screens and tabs. You can also skip this step if you have already configured the screens, you will see the corresponding message:

If you choose to skip the step, you will be directed to the fields configuration step. Otherwise, clicking the “Yes, load screens and tabs“ button will load the list of the screens and the tabs for the selected fields:

For all the fields, selected in the previous steps, you can see all the screens and the tabs, that were the fields in the source instance (i.e. in the backup) are associated. If the field is not associated with any screen and the tab in the source instance, the field will be still loaded with the corresponding messages underneath: “No screen is found for this field in backup“ and “No tab is found in backup“. You will still be able configure such fields (see below).

Before loading the fields, the app checks the screen configurations and shows the results on the interface. The interface shows:

  • The checkbox for the fields which are not yet associated for further configuration.

    • You can select all the fields that can be configured by clicking the top checkbox in the header.

    • The checkbox is disabled, if the field is already associated with the screen and the tab in the target instance.

  • Field

    • Field name, that was selected in the previous step.

      • For one field, you will see as many rows as is the number of screens/tabs to which the field is associated with.

    • Screen (Source)

      • Screen name in the backup

    • Tab (Source)

      • Tab name in the backup

  • Screen (Target)

    • If the field is already associated with the screen and the tab on the target instance, this select will be disabled and you will see the name of the screen here.

    • If the fields is not associated with the screen and the tab on the target instance, by clicking the checkbox, you can select the screen from the available screens (with descriptions) on the target instance:

      • The red border shows that the screen is not yet selected for the checked field.

  • Tab (Target)

    • If the field is already associated with the screen and the tab on the target instance, this select will be disabled and you will see the name of the tab here.

    • If the field is not associated with the screen and the tab on the target instance, by clicking the checkbox, after screen is already selected, you can select the tab from the available tabs of the selected screen on the target instance:

      • The red border shows that the tab is not yet selected for the checked field and the selected screen.

    • If the fields is not associated with the screen and the tab on the target instance, but the matching (with name) screen/tab was found on the target instance, you will see the matching screen/tab already filled in. For such cases, you need to check the field, and the field will be associated with the screen/tab on the next step.

  • Match

    • Show the status of the matching of the screens/tabs configuration in the backup and on the target instances:

      • No matching screen found (No match)

        • Indicates that the screen/tab with the same name was not found on the target instance.

      • The field is already associated with screens/tabs (Field Associated)

        • Indicates that the field is already associated with screens/tabs on the target instance

      • Perfect match

        • Indicates that the matching screen/tab was found on the target instance.

You can also search the fields, screens and tabs by name (in backup) by typing in the search box:

If you “check all” while the search term is entered, only the fields/screens/tabs rows that are found will be selected:

You can see and export the complete list of the fields with the associated screens and tabs (in the backup), plus the Request Types by clicking the “View Screens, Tabs and Request Types" button

Finally, you can filter the fields by the matching status:

If you edited the screens/tabs through the interface or modified the associations via Jira configuration, you can click the “Reset and check matches“ button:

This will:

  1. Reset all the modifications made through the interface to the initial state

  2. Check the configurations on the target instance and update the Matching status accordingly.

Before resetting the screens/tabs according to the backup, you will see the confirmation popup:

Finally, when you select (by the checkbox) the necessary fields and select appropriate screens and tabs for at least one field, the “Associate Fields“ button will be enabled. Clicking the “Associate Fields“ will associate the fields to the screens/tabs ONLY for the fields that are selected and you will see the results on the next step - Screens review. If all the fields are already associated with the screens/tabs on the target instance, you will see the “Continue “, clicking of which will transfer you directly to the field configuration, skipping the screens review step.

4. Screens review

Here you will see and review the results of the screen associations. If the selected fields were successfully associated, you will see the appropriate status along the field/screen/tab row - Successfully associated:

If, due to technical reasons or if the fields have already been associated with the same screen/tab manually, and this was not checked in the previous step with the “Reset and check matches“, you will see the appropriate status - Association failed:

In this case, you can go back (by clicking the “Back“ button) and correct the issue by rechecking the statuses or by trying again to associate fields.

However, you can continue to the next step (Fields configuration). On the next steps, the screen/tab associations will not be further checked and validated until restore is started. If there are fields that are not associated with screens (i.e. they were not selected during the screens configuration step), you will see the error message in the restore result, real-time error log and full log.

If you close the wizard at this step, you will see the results in the Restore Details of the relevant schema restore details:

You will see the list of the created fields and updated screens/tabs by clicking the corresponding “View all“ buttons:

You can export both of the lists in the .xlsx format.

5. Fields configuration

On the Configure screen, you will be given the necessary information regarding the issue fields where the objects should be restored and you can configure the fields either directly from the app or open the configuration of the fields in Jira. Initially, you will see the list of the fields selected/created in the first steps (you can open the field configuration details for each field by clicking the “down“ arrow in the beginning of the field row):

The list shows:

  1. Field search (by field name)

  2. Field status filter

  3. Field name

  4. Field ID (on the target instance)

  5. Status

    1. Schema matched: the correct schema is already configured on the target instance. The schema name is given in the “Configuration helper” above.

    2. Incorrect schema: the correct schema is already configured on the target instance. The schema name is given in the “Configuration helper” above.

    3. Validation errors: field configuration contains validation errors (see below).

The list shows the fields that were selected during the very first (Fields) step. If there are inconsistencies in the fields, you will not be able to proceed until those consistencies are solved. Clicking the “down“ arrow along the field will open the field configuration:

The screen shows the field configurations for:

  1. Current target instance (left side)

    1. Object schema name

    2. Filter scope (AQL)

    3. Filter issue scope (AQL)

    4. Search filtering attribute

    5. Display these attributes in the issue view

    6. Display default objects

    7. Field can store multiple objects

  2. In the backup, i.e. source instance (right side): the field configuration attributes are auto-filled from the ones in the backup, except for the object schema

    1. Object schema name

      1. Is filled with the schema from the restore of which the “objects in issues“ update is started

    2. Filter scope (AQL)

      1. The AQLs are given for information only and the field configurations will not be modified after “Configure Fields“.

    3. Filter issue scope (AQL)

      1. The AQLs are given for information only and the field configurations will not be modified after “Configure Fields“.

    4. Search filtering attribute

      1. Besides the filled attribute from the backup, you can also add other attributes. After clicking “Configure Fields“, the attributes will be added to the ones already selected in the field configurations of the target instance. The existing attributes will not be deleted. If the attributes are empty in the target field configuration and no attributes are selected, you won’t be able to configure the fields. The parameter with the issue will be highlighted and the “Configure fields“ button will be disabled in this case.

    5. Display these attributes in the issue view

      1. Besides the filled attribute from the backup, you can also add other attributes. After clicking “Configure Fields“, the attributes will be added to the ones already selected in the field configurations of the target instance. The existing attributes will not be deleted. If the attributes are empty in the target field configuration and no attributes are selected, you won’t be able to configure the fields. The parameter with the issue will be highlighted and the “Configure fields“ button will be disabled in this case.

    6. Display default objects

      1. You can turn the toggle on or off to set the parameter.

    7. Field can store multiple objects

      1. You can turn the toggle on or off to set the parameter. It is strongly recommended to select the same setting as it is in the source instance (left side).

By merely selecting the attributes and the settings, the field configuration will not be updated, you need to click the “Configure Fields“, button to update the configuration. After doing this, the screen will be updated and the left side will show the setting after the configuration.

Above the field, you will see the number of contexts for the field, and clicking the Context dropdown will show the list of all the contexts from the field, including the configuration condition:

If even one context in the fields contains the error (either incorrect schema is selected or any validation error), you won't be able to continue to the issue update. The dropdown shows the detailed issues with the context and the field row will show the total number of errors in the field configuration:

When you click the context, the screen will be updated with the information for the specific context. The components with the errors will be highlighted:

If you prefer to configure the fields manually, you can click the “Open Configuration“ button to be navigated to the custom field configuration in Jira. After you configure the fields, you can go back to the app and click the “Refresh Target configuration“ button to validate the configuration:

After all the fields and contexts are configured and there are no validation errors, you can click “Continue“ to go to the issue scoping and issue restore step.

6. Scoping issues for update

At this stage, you can limit the issues you want to update. This can be handy if you are updating a large number of issues and don’t have a wide timeframe. For example, you can update the only active issues or the issues for the last year. To do so, turn on the JQL toggle and enter the desired JQL to query the issues:

 

After typing the desired JQL, click the Validate query button to see the result:

After query validation, you will be able to see the number of the issues and open the list of the issues, if needed:

Click the “Start Restore” button to restore the objects in the Jira issue fields.

7. Restore

After configuring all the fields, click the “Start Restore“ button. When the restore starts, you will see the following screen:

When the restore is finished you will see the corresponding message:

You can close the popup and see the restore result in the Restores, under Objects in the issues box:

 

Here you can see:

To export the list, click the “Export“ button. The downloaded file (in .xlsx format) will contain the data organized in the same columns as on the interface.

When the process is started, if needed, you can stop the process by clicking the “STOP” button and confirming by “Yes, Stop“ button on the subsequent confirmation popup.

The corresponding actions will also be added to the audit log:

Restoring or Migrating Objects in issue fields Cloud-to-Server/DC and Server/DC-to-Server/DC

  • Migration of the schema from Cloud to another Data Center / Server

  • Migration of the schema from Data Center / Server to another Data Center / Server (the schemas should be initially backed-up via cloud app)

Prerequisites

Before starting the process, the following prerequisites should be fulfilled:

  • Make sure that the projects and issues are already migrated to Data Center / Server.

    • Use Atlassian-recommended methods, which preserve Jira issue keys of the original issues in the target DC/Server

    • Make sure the corresponding Assets custom fields exist on the Data Center and are configured.

      • Restored schema should be filled in the field configurations.

      • Make sure the field is on the appropriate edit screen.

      • The user indicated in the added to the “Data Center / Server“ connection must be added to the project(s) and have valid permission to view and edit.

Restore Process

After you have successfully migrated the schema either from Cloud to DC/Server, you will see the button “Restore objects in issues“ along the corresponding schema Restores grid:

After clicking the button, you will see the popup with the prerequisites reminder, Start Process button, and link to the current instructions:

1. Choose the fields to migrate

After clicking Start process button, you will see the list of the Jira fields of the original Server/DC or Cloud instance, where the Asset objects from the original backup are presented:

From here you can select the fields, that you want to restore and click the Start Restore button. the restore will be started and the selected fields will be updated.

2. Scoping issues for update

At this stage, you can also limit the issues you want to update. This can be handy if you are updating a large number of issues and don’t have a wide timeframe. For example, you can update the only active issues or the issues for the last year. To do so, turn on the JQL toggle and enter the desired JQL to query the issues:

Click the Start restore button for resting the objects in the Jira issue fields. The progress and the results is identical to the details of the migration to the Cloud, see above for the details.

Repeat restore

When the objects in issues is already restored at least once from the backup, you can repeat the restore again with the last configuration, without configuring the fields from scratch. To do so, click “Objects in issues“ button again, in the “Objects in issues“ box:

On the popup, you will see “Repeat Restore“ button (this button is not visible when the objects in issues restore is not yet run from the backup):

Clicking the “Repeat restore“ button will display the configuration of the last fields restore, including used JQL and the updated fields:

Clicking the “Restore” button will start the fields update and you can check the progress in the Restores, under the “Objects in issues“ box.

Real-time error log

When the restore of objects in issue fields is started, you can monitor errors in real-time by clicking the “Real-time error log“ button:

In the displayed window you will the the errors when they appear in the process:

Since the process of the fields' update may take time, this way you can identify the errors in the process (for example, if the fields are not on the corresponding screens), stop the restore, correct the issue, and run the process again, without need of waiting the restore to be completed.

Full Error log of the updated issues

You can see the errors (if any) after updating the issues, by downloading the error log file (JSON) from the restore details:

The log will show ONLY the errors while updating certain fields. The downloaded file contains the following information in JSON format:

  • IssueKey: Corresponding issue kye

  • Result: will be always false for errors

  • Message: The details of the error

{ "IssueKey": "ISSUE-001", "Result": false, "Message": "The process was stopped" }