Table of Contents
...
After clicking Assets backup vault, you will see a popup where you can add or remove trusted users.
...
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):
...
Info |
---|
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:
...
For each backup you can see the following information and Actions:
N
Order number of the backup
Backup date
Date and time when the backup was completed
Objects
Number of the object in the schema backup
Type
Manual
Scheduled
History status
Defined the status of the object history restoration (see Restore Object History for more details)
Objects in issues status
Status of background backup of the objects in issue fields (see Restore Objects in Jira Issue Fields for more details)
Actions
Select
Delete
Info |
---|
Pagination will appear below the backups if there are more than 20 entries. |
Info |
---|
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:
...
Info |
---|
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
With the Delete under the three dots along the backup, you can delete a certain backup by confirming delete in the following confirmation popup:
...
Note |
---|
After deleting, the backup data will be permanently removed. |
Info |
---|
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:
Note |
---|
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. |
Info |
---|
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. |
Restore with object icons
If this checkbox is checked, object icons will be restored (not Object Type icons).
Note |
---|
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 several hours, 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.
Info |
---|
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. |
...
Note |
---|
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:
...
Info |
---|
If at least one child Object Type is Selected all the corresponding parent Object Types (including parent Objects) will also be restored. |
Info |
---|
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
Info |
---|
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. |
Migration on 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:
...
Info |
---|
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.
Note |
---|
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. |
Info |
---|
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. |
Migration of cross-schema references
After the objects are migrated, you can restore also references between schemas.
Info |
---|
All the schemas with inbound and outbound references should be initially migrated to the same Cloud instance. |
To restore the reference, click “Restore References“ button in a “Restores” grid:
...
After clicking the 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.
Info |
---|
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. |
...
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:
...
Info |
---|
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 “Restores“ and “Restore History“ grids:
...
You can see the following information after clicking the downward arrow on the schema, which was created after the restore:
Cross-schema references restore status with the following options
PENDING
IN PROGRESS
SUCCESS
ERROR
Outbound references
YES or NO, indicating whether Outbound references restore was selected
Referenced schemas
List of the schemas selected for the references restore
Reference update message
In case of errors, clicking on the “Result message” will show the details of the error
Restores grid
After the restore is completed or failed, the restore will appear in the Restores Clicking “+ Add trusted users“ button will show a windows where you can enter email address of the user to be invited to Assets backup vault.
Info |
---|
Only emails with Google or Microsoft authentication can access Assets backup vault! |
...
After entering an email and clicking Invite, an invitation email will be sent to the user and the user will be added to the trusted users list:
...
You can remove the trusted user from the list by clicking the “Remove“ button and by confirming user deletion:
...
Authorization in Assets Backup Vault
For authorization into the Assets Backup Vault, first you need to enter the instance URL, where the user is trusted.
Info |
---|
Make sure to include https:// into the Cloud instance URL! |
...
After entering the URL, you can choose Google or Microsoft Authorization method and enter your username and password:
...
Info |
---|
You may also need to authorize with SMS, Token or any other secondary authorization method, if 2FA is enforced for the user account. |
After successful authorization, you will be navigated to the main page of the Assets Backup Vault.
...
The interface is similar to the Cloud plugin interface and you can restore and migrate the schemas that were backed up initially.
Schema Restore/Migration
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):
...
Info |
---|
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:
...
For each backup you can see the following information and Actions:
N
Order number of the backup
Backup date
Date and time when the backup was completed
Objects
Number of the object in the schema backup
Type
Manual
Scheduled
History status
Defined the status of the object history restoration (see Restore Object History for more details)
Objects in issues status
Status of background backup of the objects in issue fields (see Restore Objects in Jira Issue Fields for more details)
Actions
Select
Delete
Info |
---|
Pagination will appear below the backups if there are more than 20 entries. |
Info |
---|
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:
...
Info |
---|
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:
...
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:
Note |
---|
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. |
Info |
---|
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. |
Restore with object icons
If this checkbox is checked, object icons will be restored (not Object Type icons).
Note |
---|
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 several hours, 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.
Info |
---|
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. |
...
Note |
---|
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:
...
Info |
---|
If at least one child Object Type is Selected all the corresponding parent Object Types (including parent Objects) will also be restored. |
Info |
---|
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
Info |
---|
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. |
Migration on 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:
...
Info |
---|
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.
Note |
---|
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. |
Info |
---|
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. |
Restore objects in Jira issue fields
The process is identical to the process in the Cloud app. Foor the detailed instructions, please visit Restore Objects in Jira Issue Fields.
Migration of cross-schema references [coming soon!]
Restores grid
After the restore is completed or failed, the restore will appear in the Restores grid for the certain backed-up schema:
...
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
“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.
...
Restored from: the name and link of the original schema
Restored to: the name and link of the restored schema
History restored: YES/NO - whether history restore option was selected
Icons restored: YES/NO - whether the “Restore icons“ option was selected
Specific object types restored: YES/NO - whether the “Restore only specific object types“ option was selected during the restore
Result message: the result of the restore. In case of an error, you can click an error icon to identify the reason for the error (see the screen above)
Download full log (.xlsx) - you can download full restore/migration log by clicking the button. More details: https://twinit.atlassian.net/wiki/spaces/IB/pages/596476255/Restore+Migration+Guide#Full-restore-log .
Updated fields - List of the updated Jira custom fields
For this and the next two positions, please see Restore Objects in Jira Issue Fields for more details.
Field update status
Fields update date
Full restore log
You can download full restore log in .josn format, which will show 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 restoredThe 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:
Code Block | ||
---|---|---|
| ||
[
{
"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"}}' }"
}
] |
...
Updated fields - List of the updated Jira custom fields
For this and the next two positions, please see Restore Objects in Jira Issue Fields for more details.
Field update status
Fields update date
Full restore log [coming soon!]
Restore History
All the restores, whether successful or unsuccessful will be shown in the History table on the main page of the app:
...
Schema
Name of the 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.
Destination
Current instance
Another instance
Started
Date and time when the 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: 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.
...