Jira Service Management Special Cases
On this page:
Jira Service Management special cases
Since version 6.0.0 Configuration Manager fully supports moving Jira Service Management (JSM) projects.
All Service Management-specific configuration is considered part of the project and is packaged within the project in the snapshot.
There are some specific use cases of how Configuration Manager deploys changes to customer organizations and email channels. You can see them below.
Customer organizations
Organizations are handled differently because they are not part of a project and can be referenced by multiple projects.
The behavior for moving Service Management projects is as follows. If a project refers to organizations and users, they will be exported. When importing the snapshot:
If importing on the Target instance as a new project, CMJ will search the Target instance for matching organizations. If they exist, they will be added to the new project; otherwise, they will be created first. Customers are handled likewise: if a customer does not exist on the Target instance, they will be created. Note that this does not affect the user tier and licensing in any way.
When merging into an existing project, CMJ will override the target organizations and customers for this project(s) with the ones from the snapshot. Again, if an organization does not exist on the Target instance, it will be created. If an organization is added to the source project, but not to the target project, CMJ will just remove the reference from the target project. CMJ does not delete organizations from the system.
Note that Configuration Manager exports Organizations only when creating a snapshot of type Project with issues, as Organizations are not quite useful in a project that contains no issues.
Email channels
Email channels in Jira Service Management (JSM) turn the emails from your customers into issues in your service project and directly add them to your queues.
Configuration Manager versions 6.12.0+ support deploying and merging JSM projects with multiple email channels configured for each project.
In all use cases, CMJ:
identifies the email channel by the email address to which customers send their requests;
imports only changes to the email channel's request type, and
doesn't import changes to other properties of the email channel (email address, username, password, port, etc.)
Deploying a new project
How deploying a new Jira Service Management (JSM) project with email channels works:
CMJ deploys all request types from the project on the source Jira instance to the target Jira instance.
CMJ compares the email addresses on source with the email addresses on target. An email address may be used for an email channel of another JSM project on the target Jira instance. In that case, CMJ will deploy the project without the email channel with the overlapping email address.
If CMJ can't deploy one or more of the source email channels, you will receive warnings in the diff during the Analyze phase of the deployment and in the Audit log afterward.
Merging two JSM projects
Let's look at the main use cases when merging two JSM projects with email channels:
Target project without an email channel:
If the matching target project has no email channel and another project on the target instance doesn't use the email address, Configuration Manager will not deploy the email channel from the snapshot. You will see a warning in the Analyze phase and in the Audit log afterward.
If another JSM project uses the source email address on the target Jira, Configuration Manager will not deploy the source email channel. You will receive a warning during the Analyze phase of the deployment and in the Audit log afterward.
Both projects have an email channel:
If both the target project and the source project have an email channel, Configuration Manager will not apply any changes to the source email channel except for changes to the request type.
If the snapshot contains changes to the request type, Configuration Manager will modify the request type on the target project. When the request type is modified, you will see warnings in the Analyze phase and Audit log afterward.
Source project without an email channel:
If the source project has no email channel and the target project has one or more, Configuration Manager will not delete the email channels.
If a request type on the target project is missing on the source project, then CMJ will apply the change in the request type i.e. will remove the request type on target. Removing the request type renders the email channel invalid, and Configuration Manager will remove the target email channel as well.
The following table shows how merging two JSM projects with email channels works in practice. You can use it as a quick reference.
Source project Request types | Target project Request types | Target project after deployment | Merged changes |
|---|---|---|---|
requestType-1, requestType-2 source-1: first@example.org , requestType-1 source-2: second@example.org , requestType-2 | No email channels | requestType-1, requestType-2 No email channels |
|
requestType-1 source-1: first@example.org , requestType-1
| requestType-3, target-1: first@example.org, requestType-3
| requestType-1 target-1: first@example.org, requestType-1
|
|
requestType-1, requestType-2 source-1: first@example.org , requestType-1 | requestType-2
target-1: second@example.org , requestType-2 | requestType-1, requestType-2 target-1: second@example.org , requestType-2 |
|
requestType-3, requestType-4 No email channels | requestType-3, requestType-4 target-1: third@example.org , requestType-3 target-2: fourth@example.org , requestType-4 | requestType-3, requestType-4 target-1: third@example.org , requestType-3 target-2: fourth@example.org , requestType-4 |
|
requestType-4 No email channels | requestType-3, requestType-4 target-1: third@example.org , requestType-3 target-2: fourth@example.org , requestType-4 | requestType-4 target-2: fourth@example.org , requestType-4 |
|
Deploying and merging projects between older and newer JSM versions
Jira Service Management 4.22 introduced the possibility to configure multiple email channels for the same service project. Older versions support only one email channel per project.
If one of your Jira instances is older than version 4.22, then keep in mind the following specific cases when deploying and merging projects with multiple email channels.
The source Jira instance is version 4.22 or newer, and the target Jira instance is an older version. In this case, the main rules for deploying and merging JSM projects with email channels will be applied. However, only one of your source project’s email channels will be deployed on the target Jira as the target Jira doesn’t support projects with multiple email channels.
The source Jira instance is older than version 4.22, and the target Jira instance is a newer version. In this case, only the main rules for deploying and merging JSM projects with email channels will be applied.
Insight fields
When deploying Service Management projects with Insight fields configured on request types on Jira Service Management 4.14.x or older versions, these fields are shown with the title Unknown field on the Service Management portal (if visible to users). This issue doesn't affect Jira Service Management 4.15.x or newer versions.
You can apply the following workaround to fix this problem in Jira Service Management 4.14 / Jira Software 8.14 or earlier versions:
Remove the broken field(s) from the Request Type.
Add the field(s) through the Jira UI.
Enable the custom field(s).
Afterward, the Insight custom fields should be visible as expected.