Restore & Migration Guide

Owned by Nani Gurgenidze (Deactivated)
Last updated: Nov 12, 2024 by Gia Jgarkava
25 min read

Table of Contents

To restore the desired backup of a certain Schema, click on the “Restore” button across the needed schema in the Synched schemas grid (see Backup Configuration | Synced schemas):

Restore button in the Synced schemas

The button may be temporarily disabled if there is an error on establishing a connection to the database or if the schema is already deleted from Assets.

Clicking “Restore” button will navigate you to the page with the list of all the available backups and restore history.

Available Backups

Under Available backups, you will see all the backups for the selected schema:

image-20241024-145110.png
Available backups in the Restore / Migration page for the schema

For each backup you can see the following information and Actions:

Pagination will appear below the backups if there are more than 20 entries.

Quantity of objects in backup is visible for te backups made with or after version v2.0.12 (November 17th, 2022).

You can also filter the backup with the Backup type (Scheduled or Manual) or the Date, by clicking Date control, which will display a calendar to choose a date or a date range:

If yet there are no backups of the schema, the list will be empty with the options either to manually backup the schema by clicking Backup now button or schedule backup by clicking Schedule button:

Edit Backup

You can edit the Description of the backup by “Edit“ under the three dots along the backup.

You will see the description and basic information of the backup in the popup:

After entering the information in the text box, under the “Description”, you can save the backup.

Delete Backup

With the Delete under the three dots along the backup, you can delete a certain backup by typing the schema name and confirming delete in the following confirmation popup:

Restore

To restore the schema, select it by clicking the Select button. You will see the information about the selected backup on the left side of the page and the Restore options - on the right (Destination). As the first step, you need to select the destination - DC/Server or Cloud:

From here you can go back to the list of the backups by clicking the “Back to list of backups“ button or navigate back to the list of the schemas by clicking the “Back to schemas“ button.

Restoring on Cloud

After selecting Cloud under Destination, you can restore the schema on the current instance in a new or an existing schema or migrate it to another instance:

New schema - current instance

To restore the schema on a current instance in a new schema, choose a new schema name and key, where the schema should be restored in (the schema will be automatically created). Click continue to move to the restore options:

From here you can select to restore object history or restore specific object types. After the restore starts, the status will be shown in the right pane Destination) and Restore history. Selecting the options, you will be directed to the last, Review step of the restore wizard, where you can review the selected details and click Restore button to start the restore:

After the restore started, the Status of the restoration can be:

  • Restore pending

  • Restore in progress

  • Restore completed

    • If the restore was completed successfully, you will see “Operation success“ message by clicking the Result message:

  • Restore Error

    • If the restore was not successful, you will see the error message by clicking the Result message:

  • Restore completed:

Once started, you can terminate the restore by clicking the STOP button and confirming termination in the confirmation popup:

Once restore is started, you can see the stages of the restore under the Status column. The following steps can be observed:

  • Restoring Icons

  • Restoring Schema

  • Restoring global config

  • Restoring global status types

  • Restoring schema status types

  • Restoring reference types

  • Restoring global reference types

  • Restoring object types

  • Restoring attributes

  • Restoring object entries

  • Restoring object references

After restoring the schema on the current instance, the schemas will be automatically synced on the current instance.

If the restore process is interrupted due the API, connectivity or system error, you will see the error under the status: The process was interrupted due to API or connectivity issues.

Restore with Object Type global custom icons

If this checkbox is checked, custom object icons will be updated with the parent Object Type custom icon. Due to the lack of a corresponding endpoint in the Atlassian REST API, individually uploaded object avatars cannot be restored. The checkbox will not be visible if the restore is done on the same instance as the original one and the icons will be restored by default, because the global icons list is the same for the original and the restored schema.

Restore object history

You can restore also the history of objects by checking the “Restore object history“ checkbox at the “Options” step of the Restore wizars:

If checked, after the schema is restored, object history will be restored in a newly created attribute: OBJECT_HISTORY.

Restore specific Object Types

You can also restore the Schema not completely, but only certain Object Types, including Objects. To do so, check “Restore specific Object Types” checkbox at the “Options“ step of the restore wizard and the list of all the Object Types from the backup will show up:

You can Expand and collapse the parent Object Type(s) by clicking the arrow and select child Object Type(s) from the list by clicking the corresponding Checkbox:

To expand or collapse all the parent object types, click the “two arrows“ button at the top rightmost corner.

You can see the number of the selected Object Types and the objects, with the list of the Object Types to be restored, on the next (Review) step, after clicking the Continue button:

New schema - another instance

You can migrate a backup from the current to another instance. To do so, select the “On another instance” option at the Target step of the restore wizard,, choose a Target instance and enter a unique Schema name and key:

Under the Targe instance dropdown, you will see the instances that were added to the List of target instances under the current connection. You can identify and select the added target instance by name and the URL:

Also, from the same window, you can choose to add a new target instance, by filling the same information as while adding a new target instance under the current connection. Select New target instance in te dropdown to see the necessary fields to fill in:

After Migration is started, you will have a chance to save the newly added instance to the List of target instances.

In the next step you will be able to select the options for restore:

On the last (Review) step you can review the details of the restore, before starting the migration process by clicking Migrate button:

Existing schema

You can restore objects in the original/existing schema by selecting “Existing schema“ option at the “Target” step of the Restore wizard. By checking this option, you will see the list of the existing schemas on the current instance. the “Schema” dropdown will show the list of the existing schemas on the instance, from where you can choose a schema you want the objects to be restored in:

This way, only objects that do not exist in the schema will be restored and the existing objects will not be updated. To update the existing objects, use the “ Restore specific object attributes” option.

In the next step, you can choose the options of the restore:

In the last (Review) step of the wizard you can review the details of the restore, selected options and start restore by clicking the Restore button:

Restoring on Data Center / Server

After selecting “Data Center / Server” under Destination, you can restore the schema on any instance previously added to the Data Center / Server instances.

To DC/Server you can migrate the schema to a new or an existing schema:

Target Instance

To restore the schema on a target DC/Server instance, choose a target instance from the list and enter a new schema name and key, where the schema should be restored (the schema will be automatically created).

Click the Continue button to move to the restore options:

From here you can select to restore object history or restore specific object types. After the restore starts, the status will be shown in the right pane Destination) and Restore history. Selecting the options, you will be directed to the last, Review step of the restore wizard, where you can review the selected details and click Restore button to start the restore:

When the restore is started, all the restore statuses and the details are the same as for restoring the Assets on “Cloud: current instance”.

Once started, you can terminate the restore by clicking the STOP button and confirming termination in the confirmation popup:

Once restore is started, you can see the stages of the restore under the Status column. The following steps can be observed:

  • Restoring Icons

  • Restoring Schema

  • Restoring global config

  • Restoring global status types

  • Restoring schema status types

  • Restoring reference types

  • Restoring global reference types

  • Restoring object types

  • Restoring attributes

  • Restoring object entries

  • Restoring object references

If the restore process is interrupted due the API, connectivity or system error, you will see the error under the status: The process was interrupted due to API or connectivity issues.

Existing schema

You can restore objects in the original/existing schema on the target DC/Server by selecting “Existing schema“ option at the “Target” step of the Restore wizard. By checking this option, you will see the list of the existing schemas on the current instance. the “Schema” dropdown will show the list of the existing schemas on the instance, from where you can choose a schema you want the objects to be restored in:

This way, only objects that do not exist in the schema will be restored and the existing objects will not be updated. To update the existing objects, use the “ Restore specific object attributes” option.

In the next step, you can choose the options of the restore:

In the last (Review) step of the wizard, you can review the details of the restore, selected options and start restore by clicking the Restore button:

All the following actions are identical for restoring on Cloud or on DC/Server.

Restoring cross-schema references

After the objects are restored/migrated, you can restore also references between schemas.

To restore the reference, click the “References“ button in a “Restores” grid or the “Restore references button“ in the Cross-schema references box:

After clicking either button, you will see the following popup:

From here you can choose the schemas (one or more) from which you need to restore the references in the current schema.

You can also choose to whether restore outbound references from the current schema to the selected ones by toggling the “Restore also outbound references” control:

Click the “Restore References” button to start restoring.

You can see the progress and the results of the references restore in the “Cross-schema references“ box:

You can see the following information:

  • Restore of outbound references:

    • YES or NO, indicating whether Outbound references restore was selected

  • Restore started:

    • date and time when the Cross-schema references restore started.

  • Restore ended:

    • date and time when the Cross-schema references restore ended.

  • Restore status with the following options:

    • PENDING

    • IN PROGRESS

    • SUCCESS

    • ERROR

  • Reference update result

    • In case of errors, clicking on the “Result message” will show the details of the error

  • Referenced schemas

    • List of the schemas selected for the references restore

Restoring comments

You can restore the comments of the objects if the backups contain the comments.

To do so, after the restore of the schema is completed, click “Start restore“ button in the “Comments“ box under the “Restores” details of the restored schema:

After clicking the button, you will see the confirmation popup:

You will see the status of the progress (pending, in progress, success, error) in the same box:

Restore of original Object Type ID

You can also restore the original Object Type ID. To do so, after the restore of the schema is completed, click “Start restore“ button in the “Restore Object Type ID“ box under the “Restores” details of the restored schema:

After clicking the button, you will see the confirmation popup:

You will see the status of the progress (pending, in progress, success, error) in the same box:

After the restore is completed, you can see the original object type ID in the Description of the object type:

Restores grid

After the restore is of the schema is started, the restore will appear in the Restores grid for the certain backed-up schema:

The grid shows the following information:

  • Schema

    • Name and link (if the restore/migration was successful) of the schema that was restored. You can click the schema name to directly go to the schema

    • Destination

      • Which option was used as a destination during the restore/migration:

        • Current instance

        • Existing schema

        • Another instance

    • Started

      • The date and time of the restore/migration was started

    • Ended

      The date and time of the restore/migration was Ended

    • Status

      • Status of the restore/migration. Can be:

        • Restore completed

        • Restore error

    • Result

      • Result of the restore. In case of error, you can click an error icon to identify the reason for the error:

      • If the “Restore objects in issues” is attempted for the restored schema, the result will show the fields validation results. Please refer to Restore Objects in Jira Issue Fields for more details

    • “References” button

    • “Attachments“ button [feature coming soon!]

      • By clicking the button you can restore/migrate attachments

      • To have this feature enabled, you need to install the Asset Attachments Backup & Migration app extension!

    • “Restore objects in issues” button

      • For more details refer to Restore Objects in Jira Issue Fields to restore the objects in the issues of the current instance or to restore objects in the migrated issues from DC to Cloud or from Cloud to another Cloud.

To view additional information regarding the restore, click the “down arrow” in the beginning of the schema row:

The information about the restore is organized in the following boxes:

  • Schemas

    • Source: the name and link of the original schema.

    • Target: the name and link of the restored schema.

  • Restore options

    • Restored with

      • Marketplace app: when the schema was restored via Insight Assets Backup & Migration app.

      • Assets Backup Vault: when the schema was restored via Assets Backup Vault.

    • Objects history restored: YES/NO - whether history restore option was selected

    • Specific object types restored: YES/NO - whether the “Restore only specific object types“ option was selected during the restore

    • Custom objects Icons restored: YES/NO - whether the “Restore icons“ option was selected

    • Duplicate objects selected: YES/NO - whether the “Duplicate objects“ option was selected during the restore in the existing schema

  • Restore information

    • Restore started: date/time when the restore was started

    • Restore ended: date/time when the restore was ended

    • Restore status

      • Pending

      • In progress

      • Completed

      • Terminated

    • Objects restore result

      • Result message: will show the end result

        • If the restore was completed successful the message will contain “Operation Success“ message

        • If the restore was unsuccessful, the message will contain the details of the error

    • Full log

    • Real-time log

Real-time log monitoring

When the restore of objects is started, you can monitor the process in real-time by clicking the “Real-time log monitoring“ button in the Restore information box:

In the displayed window you will the the log of the successful and erroneous object restores when they appear in the process:

Full restore log

After completing the restore, you can download the full restore log in .xlsx format, which will show a detailed log of the restored objects or the error messages per certain object. The downloaded file contains:

  • ObjectKey

    • Key of the Asset object

  • Result

    • Restore status of the object

      • true: The object was restored

      • false: The object was not restored

  • Message

    • { message: 'OK' } - if the message was restored

    • The certain error message of the object was not restored:

      • Example of the error messages:

        • OBJECTKEY-001 {"errorMessages":[],"errors":{"attribute-id":"The attribute '[attribute name]' has to be unique"}}

          • “Unique“ is checked in the General tab of the attribute configuration

        • OBJECTKEY-002 {"errorMessages":[],"errors":{"attribute-18718":"Invalid values ([attribute value])"}}

          • The attribute contains invalid value, e.g. text in the Integer attribute type

        • OBJECTKEY-003 {"errorMessages":[],"errors":{"attribute-18334":"[attribute name] - Text attribute value must be less than 255 characters long"}}

          • The “text“ type attribute contains more than 255 characters

Example of the log file:

Restore History

All the restores, whether successful or unsuccessful will be shown in the History table on the main page of the app:

Total shows the total number of the restore/migrations, including successful and failed ones. You can also select the number of restores you want to see on one page (from 10 to 200).

Restores Grid shows the following information regarding all the restores after the app installation:

  • Source Schema

    • Name of the source schema restored or tried to be restored

    • Destination Schema

      • Name of the destination schema restored or tried to be restored

      • For successful restore/migrations, the schema name is clickable and you will be navigated to the restored schema in Atlassian Assets.

  • Started

    • Date and time when the schema restore was started

  • Ended

    • Date and time when the restore was finished

      • will be empty for unsuccessful restores

  • Status

    • status of the restore

      • In progress: the restore process is in progress.

      • Restore completed: restore was finished successfully.

      • Restore error: restore was not finished.

  • Result

    • Result message: details of the result. Clicking the result message will show the details of the result.

  • View Details

    • Click the View Details button to navigate to the details in the Schema Restore Grid. If the schema was deleted from the app, the “View details“ button will be disabled.

In addition, by clicking the downward arrow button on the left of the schema name, you can see more details regarding the certain restore:

The following additional details are available:

  • Cross-schema references

    • Restore started (date and time when Cross-schema references restore started; N/A if not yet started)

    • Restore ended (date and time when Cross-schema references restore ended; N/A if not yet started)

    • Restore status (Status of Cross-schema references restore; Empty if not yet started)

  • Objects in issues

    • Restore started (date and time when objects in issues restore started; N/A if not yet started)

    • Restore ended (date and time when objects in issues restore ended; N/A if not yet started)

    • Restore status (Status of objects in issues restore; Empty if not yet started)

  • Attachments

    • Restore started (date and time when attachments restore started; N/A if not yet started)

    • Restore ended (date and time when attachments restore ended; N/A if not yet started)

    • Restore status (Status of attachments restore; Empty if not yet started)

If the restored schema is already deleted, you won’t be able to click View Details and the button will be disabled, showing the reason:

Additional Remarks and Limitations