Multi-Project Snapshots
- Rosen Marinkov
- Stanley Neychev
On this page:
Deploying Multi-Project Snapshots
Multi-project snapshots are project snapshots that contain the configuration of two or more selected projects. A multi-project snapshot can include the issues of the selected projects if it is created as a project with issues snapshot type. Read our Single-Project Snapshots document if you want to deploy a snapshot with only one project.
The deployment of multi-project snapshots starts with providing a deployment snapshot on CMJ’s Deploy page. The deployment goes through the following phases:
Select phase - In this phase, you can use the Advanced Options to select elements you want to skip merging during deployment.
Analyze phase - In this phase, CMJ performs deep change and impact analysis of the changes that the deployed snapshot will introduce on the target Jira instance.
Migrate phase - This is the issue migration phase. It’s only required when issues on the target Jira are incompatible with the snapshot configuration. To learn more, see the list of cases that require Issue Migration.
Deploy phase - This is the final phase of the deployment process. In this phase, you must confirm that you want to apply the configuration and issues from the selected snapshot to your Jira instance.
The deployment of multiple-project snapshots works by “merging” the projects' configuration and issue data from the snapshot into the target Jira instance. This document explains how “merging” works when deploying project configuration snapshots and projects with issues snapshots.
Deploying Project Configuration snapshots
When you deploy a snapshot containing multiple projects and their configuration, CMJ applies the project configurations in the snapshot to the target Jira instance. When merging project configurations, CMJ applies the following rules to the target Jira:
All configuration objects from the snapshot that don't exist on the target Jira instance will be added.
If a snapshot and a target configuration object have the same name/id, CMJ compares both objects. If they are different, CMJ will replace the target object with the object from the snapshot.
CMJ doesn't delete or change configuration objects on the target Jira instance if they don’t exist in the snapshot. An exclusion: a configuration object will be deleted if it is a non-root (child) object.
Merging root vs. non-root configuration objects
CMJ applies different rules when merging root and non-root configuration objects. A configuration object represents a piece of Jira configuration. There are two types of configuration objects: root and non-root (also known as child). For example, workflows are root objects, and custom field contexts are non-root objects. You can find a full list of root and non-root configuration objects in the What is a Configuration Object document.
Example
Let's assume you have the following:
A workflow scheme called "Dev Code" is an example of a root configuration object.
The Jira Service Management request types "A," "B," and "C" as examples of non-root (child) objects.
Suppose you're performing a deployment, and these objects will be merged into the target project. Check the table below to see if and how CMJ will change the target workflow scheme and request types in each use case.
Configuration object | In the snapshot | In the target Jira | Result |
|---|---|---|---|
Workflow scheme “Dev Code”root | Yes | No | A new workflow scheme “Dev Code” will be added to the target Jira instance. |
Workflow scheme “Dev Code”root | Yes | Yes | The workflow scheme “Dev Code” in the snapshot will replace workflow scheme “Dev Code” in the target Jira instance only if there are differences between the two workflow schemes. Otherwise, the target project will not be changed. |
Workflow scheme “Dev Code”root | No | Yes | The workflow scheme “Dev Code” in the target Jira instance will stay as it is and will not be deleted. |
JSM request typechild | Request types “A”, “B” | No request types | Request types “A” and “B” are added to the target instance. |
JSM request typechild | Request types “A”, “B” | Request type “A” | The target instance will contain request types “A” and “B” after |
JSM request typechild | Request types “A”, “B” | Request types “B”, “C” | The target instance will contain request types “A” and “B”. |
What if you don’t want to replace a configuration object, let’s say, the workflow scheme “Dev Code” in the target Jira instance? The Selective Merge feature in CMJ allows you to create and assign a new scheme instead. Learn more in our Selective Merge documents.
Merging Jira Service Management project snapshots
Knowing which objects are considered root and non-root and how merging issues works is very helpful for understanding the results of the deployment of a Jira Service Management (JSM) project snapshot. A JSM snapshot includes:
the standard Jira project configuration (mostly root objects),
Jira Service Management-specific configuration (mostly non-root objects), and
(optionally) issue data.
Each of these three JSM project snapshot elements follows the merge rules relevant for its type.
Deploying Projects with Issues snapshots
When deploying a project snapshot with issues, the projects and their configuration objects will be “merged,” as explained in the Deploying Project Configuration snapshots section.
Issue data in the snapshot includes the issues in the selected projects and all their comments, links, history, worklog, custom field values, agile data, etc. For including issue attachments in the snapshot, read more about Moving Attachments here.
How CMJ imports issue data?
There are two cases of importing issues and related data when deploying a multi-project snapshot.
A. Some or all of the matching projects on the target Jira instance do not contain issues. In this case, all issues and their data are imported into the empty projects on the target Jira instance.
B. Some or all of the matching projects on the target Jira instance already contain issues. In this case, if the same issue exists both in the target project and in the snapshot, this issue will not be imported. Issues not existing in the target project will be imported with all their data.
For more information on migrating projects with issue data, please refer to our use case document:
Move Projects (with Issue Data)