Restore & Migration Guide

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 a error on establishing connection to the database or if the schema is already deleted from Assets (Insight).

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-20240215-133005.png
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:

The Date filter for Available backups

While accessing the “Restore“ page, the date filter will be empty and the latest 50 backups will be visible. To show more backups, please use the date filter.

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:

Delete backup

Delete Backup

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

After deleting, the backup data will be permanently removed.

While deleting the backup from own database (e.g. MongoDB), the deletion may take up to 6 hours.

Restore

To restore the schema, select it by clicking 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):

By selecting the corresponding option under Destination, you can restore the schema on the current instance in a new or an existing schema or migrate it to another instance.

Current instance

To restore the schema on a current instance, choose a new schema name and key, where the schema should be restored in (the schema will be automatically created) and click Restore and Confirm buttons, which you will see in the confirmation popup. After the restore starts, the status will be shown in the right pane Destination) and Restore history:

 

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:

Schema will be automatically created during restore, therefore choose an unique schema name and key. If the schema exists either with the same name, or the key, restore will not be successful and the corresponding result message will be visible in the Restores Grid.

Due to the rate limits of corresponding Atlassian REST API, performance of restore process is limited to ~1,000 objects per minute. For example, if a schema contains 90,000 objects, restore will take approximately 1.5 hours. Also, please keep in mind that if you start more than one parallel restore/migrations, it may also take long due to the Request per minute limitation of the corresponding Atlassian REST API.

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

Termination may take some time, therefore if the process is stopped by the end of the progress, restore still might have been completed!

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

The status is updated every 10 seconds, therefore if number of entries in certain stage is low, displaying the stage progress might be skipped.

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.

Restoring icons may take considerably longer! If a schema contains many objects, after backup is completed, icons will be backed up in background, which may take long, depending on the number of objects. Therefore, if you are trying to restore backup with icons immediately, icons may not be included in the restored schema.

Restore object history

You can restore also the history of objects by checking the “Restore object history“ checkbox:

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

Due to the limitations of Atlassian corresponding REST API, after backup is finished, object history is being backed up in background. To prevent the cases when the history restore is tried before the history is backed up, you will not be able to select this option immediately after the objects backup is finished and the option will be disabled, until the backup is completed in the background. Estimated waiting time before restoring object history option becomes available, depends on the number of the objects and with rough average is 5 minutes plus ~1 minute for every 1,000 objects. You can see the object history backup status in the Available backups.

Times in the restored history attribute will be always shown in CET (UTC+2)

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 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:

If at least one child Object Type is Selected all the corresponding parent Object Types (including parent Objects) will also be restored.

If you try to restore Object Type that has an attribute referenced to another Object Type (which you are not restoring), in such case the restored Object Type will lack the corresponding attribute.

Existing schema

You can restore objects in the original/existing schema. By checking this option, you will see the following fields:

  • Schema

    • A 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:

  • Duplicate Objects

    • This option deals with the cases when objects that need to be restored already exist in the existing schema (Object IDs are used for matching)

      • If checked: Duplicate objects will be created

      • If unchecked: Duplicate objects will NOT be created

  • Restore with object icons

    • Same as for Current instance - see above

  • Restore specific Object Types

    • Same as for Current instance - see above

If you restore a backup twice in the existing schema, even if you choose not to duplicate the objects, they will still be duplicated as the restored objects will have new IDs.

While adding new objects in the restored schema, if you create new objects by cloning the existing ones, due to cloning of ORIGINAL_ID and ORIGINAL_KEY in new objects, these objects will not be restored if this schema is backed up and restored again, unless duplicate option is selected.

Migration to another instance

You can migrate a backup from the current to another instance. To do so, select the “Restore on another instance” option, choose a Target instance and enter a unique Schema name and key:

Insight Assets Backup and Migration app must be installed on the target instance with an active trial or paid subscription.

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.

While migrating a schema to another instance, you can also use the “Restore with object icons“ and “Restore only specific Object Types“ options.

Schema in another instance will be automatically created during migration, therefore choose an unique schema name and key. If the schema exists either with the same name, or the key, restore will not be successful and the corresponding result message will be visible in the Restores Grid.

If the schema which is being restored contains references to the users, which does not exist in another instance, the object attribute will be still restored but attribute value will be empty. Such empty attributes are by default hidden from an object view, unless manually edited. Additionally, due to the GDPR restrictions, the matching with the users is not passive via email, and only Name/Surname is used. Therfore, in some cases (e.g. when there are several users with the identical name and surname), the user attribute value may not be restored.

Restoring cross-schema references

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

To restore the references between schemas, ALL the referenced schemas should be preliminarily backed up!

All the schemas with inbound and outbound references should be initially migrated to the same Cloud instance. In the referenced schemas are not migrated, the corresponding attributes in the migrated schema will not be created. However, you can run cross-schema references migration after all the missing schemas are also migrated - this way the missing attributes will be created with the proper referenced objects.

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

After clicking either buttons, 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.

Only schemas with “Allow others to select objects from this schema“ option selected will show up here. Make sure to “sync schemas“ to see the updated schemas from the last synchronization.

In case of migrating the cross-schema references from Cloud to Cloud, the schemas list will show not the schemas from the instance, but the list of the schemas that are restored on the same target instance. You can check the Restore ID in the Restores grid:

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:

Keep in mind that in case of large number of references, restoring may take hours and the references between the selected schemas (from the select list) will not be restored.

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.

The comments restore/migration was added on February 16th, 2024. Therefore, only backups taken since that date will contain object 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:

If the original Description of the Object Type contained the information, it will be overwritten by the original object type ID!

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 https://twinit.atlassian.net/wiki/spaces/IB/pages/685899777 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

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

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:

Only the events of last 500 objects restore are displayed in the log!

Full restore log

After completing the restore, you can download the full restore log in .josn 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:

[ { "ObjectKey": "OBJECTKEY-001", "Result": true, "Message": "{ message: 'OK' }" }, { "ObjectKey": "OBJECTKEY-002", "Result": true, "Message": "{ message: 'OBJECTKEY-002 {"errorMessages":[],"errors":{"attribute-id":"The attribute '[attribute name]' has to be unique"}}' }" } ]

Full log is available for the restores and migrations performed after October 12th, 2023. For the restoes done before, the downloaded log will be empty.

Restore History

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

Restores Grid shows the following information:

  • 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

When there are more than 20 schemas, pagination will appear below the Schema Grid.

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)

  • Attachmens [feature coming soon!]

    • 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 two or more restores are started approximately simultaneously, the restores executed later will wait in queue until the first ones are completed.

If schema contains many objects, restore may take time!

Additional Remarks

If you are migrating from Server to Cloud, the “Text“ attributes may contain more than 255 characters. In such case, after the migration, the objects containing more than 255 characters in this attribute, will not be restored. If this happens, you need to change the affected attribute type “Text“ to “Text Area“ on the Cloud and Restore only affected specific object types in the existing schema: https://twinit.atlassian.net/wiki/spaces/IB/pages/596476255/Restore+Migration+Guide#Existing-schema.

If the objects types that were backed up,

  • had either custom icons,

  • or they were imported with Asset Discovery,

  • or were restored to different instance,

some icons may be lost after restore, as they are not saved in the schema itself. If this happens, the icons will be changed with the default object icon (see the screen below). As a workaround, you can upload the original icons to the global icons on the target instance, keeping the name identical to the original ones, and after the restore, correct icons will be updated for Object Types and corresponding objects.

It may happen that the Schema was backed up in Cloud and after some time you decide to switch to your MongoDB. In such case, if you try to Restore the older backup, you will see the error message. This is true also if you backed up a schema in your MongoDB and later you try to Restore that certain backup after switching to Cloud backup (Switced off the “Backup on local database“ toggle).

During restoring the schema on current instance, If the objects in the schema contain the references to another schema not existing on the instance, the attributes will be restored, however with the emty values.

Due to the corresponding REST API limitations, when the objects are restored, they always have new Object ID and Object key. This results in various issues in the restore process e.g. the objects are duplicated when restored more than once, or the references are lost between the schemas. To deal with this issue, all the restored objects have 2 new additional attributes:

  • ORIGINAL_ID

  • ORIGINAL_KEY

Both attributes represent the Original ID and the Key, which the object had in the VERY FIRST backup of the schema. e.g. If the schema was backed up, restored and the newly restored schema was restored again, the original ID and the Key will not be changed in the last restore.