Table of Contents

After installation, Insight Assets Backup & Migration is available in the "Apps" administration menu:

Initial Setup

After clicking Insight Assets Backup & Migration, if it is the first time when the app is accessed, you will be walked through the initial Setup process:

1. Credentials - Token | Email | Workspace ID

For the first step, before creating and configuring individual backup schedules, the following three fields should be filled:

• Workspace ID

  • Fill in the ID of the Assets (Insight) workspace you want to configure backup for. The Workspace ID can be found on the following link: https://[yourcloud].atlassian.net/rest/servicedeskapi/insight/workspace. The Jira Service Management REST API uses the workspace ID to identify your individual instance of Assets (Insight), it is an alphanumeric string at the end of the text shown on the opened link with the following sample appearance: 3b3b70g5-66f8-3c01-a2d7-e5bbf2584dc3:

  • {"size":1,"start":0,"limit":50,"isLastPage":true,"_links":{"self":"https://[yourcloud].atlassian.net/rest/servicedeskapi/assets/workspace","base":"https://[yourcloud].atlassian.net","context":""},"values":[{"workspaceId":"3b3b70g5-66f8-3c01-a2d7-e5bbf2584dc3"}]}

• API Token

  • Atlassian API token secures account access to the API. You can create a token, through the following URL: Atlassian account - API Tokens. You can read more about Atlassian API Token on the documentation page: Manage API tokens for your Atlassian account | Atlassian Support.

  • After creating an API Token, just copy and paste it into the corresponding “API Token“ field on the configuration page.

• Email

  • Fill in the email related to the Atlassian account (valid JSM agent) that will be used to access the data in the Assets. To create and update the schemas, object types and objects, the user should have valid permissions, at least a Manager role in the schema (in case of resting in an existing schema), or the user should be added to Jira Admin group.

After filling the three fields in, click the “Save and Continue“ button. If there is an error in the filled fields, you will see the corresponding error message and link for editing the incorrect information:

If the filled information is correct, you will see the corresponding success message:

2. Backup storage

For the second step, you have the option to decide where to store the backups. By default, the backups are stored in Cloud (EU, Germany).

As an option, you can choose your own local database to store the Assets backups:

The three possible options for local DB are:

• MongoDB

• DocumentDB

• CosmosDB

• DynamoDB

To activate local DB storage, switch on the ”Backup on local database” toggle and fill in the following data (examples and instructions are given for MongoDB):

• Connection String: read more information about MongoDB connection string here: Connection String URI Format — MongoDB Manual.

• Database Name: follow the following link to find the name of the databases in MongoDB: https://www.mongodb.com/docs/atlas/atlas-ui/databases/#view-databases.

After deciding on the database, click the Save and Continue button to proceed to the third step.

3. Sync Schemas

When the backup database is chosen, you will see the Current Connection information and can Sync the existing schemas by clicking the Sync schemas button:

After a successful Sync, all the retrieved schemas from Assets (Insight) will be displayed:

Go to Synced Schemas for further details.

Connection

After initial setup, you can do the following actions on the current connection, by clicking the three dots after Sync schemas button:

• Add new target instance

• List of target instances

• Edit configuration

• Delete

Add new target instance

Here you can add a Cloud target instance, where you can later migrate the backed-up schemas (see Migration to another instance for more details). To add the target instance, fill in the following fields:

1. Connection name

   • To easily identify the instance while migrating the schemas

2. Target Email

   1. Fill in the email related to the Atlassian account that will be used to access the data in Assets (Insight) for a target instance (the user should have a valid agent license!)

3. Target WorkspadeID

   1. Fill in the ID of the Assets (Insight) workspace you want to restore the backup to. The Workspace ID can be found on the following link: https://[yourcloud].atlassian.net/rest/servicedeskapi/assets/workspace. The Jira Service Management REST API uses the workspace ID to identify your individual instance of Assets (Insight), it is an alphanumeric string with the following sample appearance: 3b3b70g5-66f8-3c01-a2d7-e5bbf2584dc3.

      

4. Target Instance URL

   1. URL of target instance: https://[yourcloud].atlassian.net

   2. Make sure to include “https://“ in the URL, otherwise you will not be able to save the instance - the corresponding error message will be shown along the field:

      

   3. You also won't be able to save the URL if you indicate https:// but in reality the URL does not support https://

   4. Keep in mind, that you cannot use bypass like localhost or localtest.me

5. Target Token

   1. Token for the target instance: you can create a token for a different, through the following URL: Atlassian account - API Tokens. You can read more about Atlassian token on the documentation page: Manage API tokens for your Atlassian account | Atlassian Support.

   2. After creating a token, just copy and paste it into the corresponding “Target Token“ field.

After filling in the necessary information, click the Save target instance button to add the instance to the list.

After the instance is added, you can see and modify it from the List of target instances.

List of target instances

From here you can see and manage the added target instances:

The list shows:

• Instance name

• Location

  • Cloud

  • Data Center

• Created at

  • Date when the target instance was added

• Actions

  • Edit

    • To modify the instance details. After clicking Edit, you will see the same fields as for adding the new instance

  • Delete

    • To delete the target instance from the list

You can also add a new instance, by clicking the +Add new button.

Edit configuration

From here you can modify the details of the current instance:

You can modify all the fields that were configured during the Initial setup, including the local database, by turning on the Backup on local database toggle.

Delete

You can delete the current connection by clicking Delete. You will see the confirmation popup:

If you click the Delete button, the synched schemas will disappear and to continue using the app, you will need to go through the Initial setup.

Synced schemas

Here you can see the synched schemas from the current instance and Data Center / Server instances. The grid shows the following information:

• Schema Name

• Instance

  • URL of the instance where the schema is located

• Location

  • Cloud

  • Another Cloud: Backup schemas from another instance

  • Data Center: Add Data Center / Server

• Status

  • Active

  • Inactive

    • The schema will be “inactive” if it was a part of another instance, but the instance was later removed from the list.

    • Backup will be disabled for the schemas with the “Inactive” status

  • Deleted

    • When the schema is deleted from the assets. It is not possible to backup the deleted schema, in this case Backup now button will be disabled:

      • 

    • Sync Error

      • Backup will be disabled for the schemas with the “Sync error” status

• Last backup date

  • Date of the last backup

  • In this column, additional information might be shown, e.g. regarding the last backup backup error

    • 

• Backups

  • Disabled

    • When the backup schedule is not set

  • Pending

    • When the backup has not yet started and is in the queue

  • In Progress

    • Backup in Progress

  • Auto

    • Backup is scheduled

    • The next backup date will also be displayed:

      • 

• Actions

  • Backup now

  • Restore

  • Schedule Backup

    • You can schedule backup using a corn expression

  • Delete

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

      • 

You can also use additional filters for filtering the schemas in the grid:

• Hide deleted schema toggle

  • By turning off the toggle you can hide the deleted schemas

• Instances (single-select)

  • You can choose the instances for which you would like to see the schemas

  • Instance type

    • Cloud

    • Another Cloud

    • DC/Server

  • Status

    • Active

    • Inactive

    • Deleted

    • Sync Error

  • Search

    • You can search the scheme by name. After typing the first letter in the Seach field, the schema grid will be automatically filtered according to the search term.

  • Clear Filter

    • Will appear if at least one filter is selected and will clear all the selected filters:

The filters will remain selected if you navigate through the app or refresh the browser window.

Schema Backup

You can back up the desired schema either manually or by scheduling regular backups.

Manual Backup

To back up the desired schema, click Backup now button under the Actions of the schema grid. After clicking the button you will see the confirmation popup:

You can add descriptions to certain backups for further simplifying the backups management. You can later view and edit the description if needed. After adding the description (not mandatory), click the Yes button to start the backup. You can check the backup process status along the corresponding schema in the Synced schemas grid:

After the backup is started, it will go into the “IN QUEUE“ status and “IN PROGRESS“, when the backup process is started.

When the backup is started you can stop the process anytime, by clicking Stop button:

After you click the button, you will see the confirmation popup either to stop the process or abort the termination of the backup:

After the backup is finished, you can check the status below the Last backup date column. If the process was successful, you will see the date and time of the last backup. Otherwise, you will see the error message, explaining the problem with the backup.

After the backup is completed, the new item will appear on the Restore page, under Available backups (see Restore and Migration Guide for more details):

Schedule Backup

A backup schedule should be configured for an individual schema. To configure the backup schedule, click on the Schedule backup button, under three dots along the desired schema. The schedule configuration window will pop up:

To switch backup on, activate the “Enable“ toggle. The green color of the toggle corresponds to “On“ and the grey color corresponds to “Off”.

You can choose between two options - Recommended and Custom. In case of choosing the recommended time, the most optimal time is defined in the moment and the backup will start every day on that time.

You can also choose your desired schedule for the backup. You can define the schedule at a specific time by choosing from every:

• Year

• Month

• Week

• Day

Additionally, you can use Cron expression to further define the schedule.

Cron Expression

To enhance the backup schedule, cron expression is used. A cron expression gives you control over the frequency, compared to the default schedules. It is a simple and straightforward expression to define the backup schedule. You can find more information about how to construct the expression on the following links:

• Construct cron expressions for a filter subscription | Jira Cloud

• Crontab.guru - The cron schedule expression editor

After deciding on the schedule and filling in the expression, click “Save“ button.

If the Cron expression is not valid (e.g. number of hours is more than 24 or the number of minutes is more than 60), after clicking the Save button, you will see the error message - “Cron expression is not valid”:

Allowed frequency of backup

The minimum allowed frequency of backup is once per day. If the cron expression implies more frequent backups, it will not be possible to save such a backup configuration and you will see the corresponding message:

Backup of objects in Jira issues

During schema backup, the information about objects selected in Jira issue fields will be also backed up. The corresponding backup status will be shown under “Objects in issues status“ in the schema restore page (Available Backups).

Clicking the “Info“ icon will display the number of the issues, information of which was recorded in the backup. The number shows a number of the unique issues where the objects from this issue are selected and do not depend on the number of fields and the number of objects.