Single-Project Snapshots
- Rosen Marinkov
- Stanley Neychev
On this page:
Deploying Single-Project Snapshots
Single-project snapshots are project snapshots that contain the configuration of only one project. Read our Multi-Project Snapshots document if you want to deploy a snapshot with more than one project.
The deployment of single-project snapshots starts with providing a deployment snapshot on CMJ’s Deploy page. After that, the deployment goes through the following phases:
Select phase - In this phase, you must choose a deployment mode: Merge Project or New Project.
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.
This document will walk you through the initial Select phase of the deployment. Choosing between Merge Project and New Project mode is important because each mode represents a different deployment strategy. Read below to understand what will happen with your project configuration and issue data (if your project snapshot contains such) in each deployment mode.
Merge Project Mode
In Merge Project Mode, you can deploy:
project configuration snapshots - they contain only the project’s configuration, or
project with issues snapshots - a project configuration together with issue data.
Merging the project configuration works the same way in both cases, but merging issue data has its specifics. Read more below.
Merge Project Configuration Snapshot
When you deploy a snapshot in Merge Project mode, CMJ applies the project configuration in the snapshot to the target project you choose. When merging project configurations, CMJ applies the following rules to the target Jira project:
All configuration objects from the snapshot that don't exist on the target project will be added.
If a snapshot and a target configuration object have the same name/id, CMJ compares both objects. If they are different, the app will replace the target object with the object from the snapshot.
CMJ doesn't delete or change configuration objects in the target project if they don’t exist in the snapshot. An exclusion: the 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 project | Result |
|---|---|---|---|
Workflow scheme “Dev Code” root | Yes | No | A new workflow scheme “Dev Code” will be added to the target project. |
Workflow scheme “Dev Code”root | Yes | Yes | The workflow scheme “Dev Code” in the snapshot will replace workflow scheme “Dev Code” in the target project 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 project 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 project. |
JSM request typechild | Request types “A”, “B” | Request type “A” | The target project will contain request types “A” and “B” after |
JSM request typechild | Request types “A”, “B” | Request types “B”, “C” | The target project 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 your target project? The Selective Merge feature in CMJ allows you to create and assign a new scheme instead. Learn more from our Selective Merge documents.
Merge mode is very useful in the Test-Staging-Production use case. Imagine you make configuration changes to a project in your Test environment. You can create a project snapshot and then verify the changes work as expected by deploying to the Staging environment. Finally, deploying the snapshot to the Production environment in Merge mode will ensure that the project behaves in the exact same way because the changed configurations will replace the old ones in Production.
To deploy a project snapshot in Merge Project mode:
By default, the single-project deployment starts in Merge Project mode.
From the Select Target Project dropdown, choose a project on which the configuration will be applied.
(Optional) Choose Advanced Options.
Click Next to proceed to the Analyze page.
Merge Project with Issues Snapshot
When deploying a project snapshot with issues in Merge Project mode, the project configuration will be applied to the target project the same way as when merging project configuration snapshots without issue data.
Issue data in the snapshot includes the issues in the project 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 issue data in Merge Project mode.
A. The snapshot merges into a target project with no issues. In this case, all issue data is imported into the target project.
B. The snapshot merges into a target project that already contains 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.
If you want to ensure that all issue data is imported, we recommend the New Project mode (see below).
For more information on migrating projects with issue data, please refer to our use case document:
Move Projects (with Issue Data)
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.
New Project Mode
When you deploy a project snapshot in New Project mode, CMJ creates a project on the target system identical to the source project in the snapshot. This mode works the same for project configuration snapshots and project with issues snapshots.
To deploy a project snapshot in New Project mode:
Choose the New Project option on the top right.
Enter a name for the new project on the target system (Configuration Manager, by default, offers the project name from the snapshot).
Click Next to proceed to the Analyze page.