On this page:
|
...
|
Basics of customizing the configuration mapping
To customize the mapping of a project, configuration element, or user, you need to have a JSON file with a transformation record for it. The transformations Transformations are customizations you can apply to an element in the configuration being migrated.
...
mapping a configuration element to a chosen destination element,
renaming any configuration element such as project, workflow, custom field, user, and more,
changing a project key , and
changing a user email.
Tip |
---|
Contexts can also be transformed from a JSON file. To learn all the context transformation rules, guidelines, and use cases, visit the page we created specifically for this purpose. |
In the JSON file, you always need to provide the source ID of the configuration element you want to transform. Later, we’ll show you end-to-end what you need to do in order how to apply a JSON transformation step by step.
You can also visit the following use case page on Appfire's website to find more useful information and view a demo of customizing the configuration mapping.
https://appfire.com/products/use-cases/modify-configuration-mapping-cloud-migrationNow, let’s take a closer look at each transformation type and its JSON record.
Transformations you can apply with custom mapping
When the migration analysis process detects a match between a server and a cloud configuration element, it creates a mapping between them.
Projects & configuration elements: Map the configuration element to a chosen destination element
With the Customize mapping option, you can change the destination element the server element is mapped to. All you need to do is provide a different ID in the following way, and the migration analysis will create a new mapping:
...
Code Block | ||
---|---|---|
| ||
"transformation": { "id": "100123" } |
Projects & configuration elements: Rename
With this transformation, you can:
...
Code Block | ||
---|---|---|
| ||
"transformation": { "name": "New configuration element name", } |
After the renaming, any existing mapping will be disregarded afterward.
Panel | ||
---|---|---|
| ||
Use configuration elements' ID to ensure accurate mapping Mapping by name works correctly when a configuration element's uniqueness is determined by its name. But when elements, like filters, have the same name, renaming them won't guarantee a correct match with a destination element of the same name. In these cases, where the name isn’t a unique attribute of the configuration element, use the unique IDs to map source and destination elements. |
Projects: Change project key
You can add a transformation record to a project to change its key. Remember that you can change the project key using the inline edit transformation in the UI.
Code Block | ||
---|---|---|
| ||
"transformation": { "key": "PROJDOC" } |
Users: Change user email
For users, you can add a transformation record to change the user their email address . This or match them to another destination user by providing an ID. These transformations will allow you to create, merge, and remap users. Remember that The source and destination users are matched either by their names or by their IDs.
Learn more about transforming users.
Code Block | ||
---|---|---|
| ||
"transformation" : { "name" : "Karlie Davis", "email" : "karlie@demo.com", } |
Users: Map to a destination user by ID
You can also add a transformation record to map a source user to a chosen destination user by providing the destination user’s ID.
Learn more about transforming users.
Code Block | ||
---|---|---|
| ||
"transformation": { "id": "5da444878f33800c416f30ed", } |
Ways of customizing the configuration mapping
To make transformations to projects, configuration elements, and users, you can:
Download a JSON mapping file, add transformations to it, and upload it with the Customize mapping button.
Construct a JSON file containing the transformations you want to apply and upload it with the Customize mapping button.
Reuse a mapping file from a previous migration and upload it with the Customize mapping button.
Download mapping and customize it
With the Download mapping button, you’ll get a JSON file listing the configuration elements in the migration scope. This mapping file contains a description of how all these configuration elements will migrate to Jira Cloud. The following JSON snippet illustrates how configuration elements are listed in the file:
Code Block | ||
---|---|---|
| ||
{ "issueTypeSchemes": [ { "source": { "id": "10208", "name": "DOM: Scrum Issue Type Scheme", "default": false }, "destination": { "newObject": true } } ] } ] |
As you can see, each configuration element has a source
and destination
record. The source
record contains all the details of the server element. The , and the destination
record holds information about how this element will be migrated. The configuration element can either be created as a new one or be mapped to an existing destination element.
If you want to customize the default mapping of a configuration element, you need to add a transformation
record for it like this:
Code Block | ||
---|---|---|
| ||
{ "issueTypeSchemes": [ { "source": { "id": "10208", "name": "DOM: Scrum Issue Type Scheme", "default": false }, "destination": { "newObject": true }, "transformation": { "id": "10206" } } } ]] } |
Then, in the transformation
record, you can map the element to a destination element or create it as a new element.
...
Construct your own mapping file
You can create your own mapping file without downloading such from the UI. Just follow the guidelines in this section. After creating it, you upload it with the Customize mapping option in the UI, the same way you would do with a downloaded mapping file. The following snippets show how to construct the JSON records of a transformation to a single configuration element:
Code Block | ||
---|---|---|
| ||
{ "issueTypeSchemes": [ { "source": { "id": "10208", }, "transformation": { "id": "100119" } }, } ]] } |
or
Code Block | ||
---|---|---|
| ||
{ "issueTypeSchemes": [ { "source": { "id": "10208", }, "transformation": { "name": "Destination issue type scheme", } } } ]] } |
The source
record must contain the ID of the server configuration element. Similarly to the example above, you can add more details to the source
record. However, for a successful transformation, the only required component for the source
record is the source element’s ID. Then, you need to have a transformation
with the new ID or name, as shown in the example above. For projectsThis way, you can also change their key this way, and for users their project keys and user email addresses and keys.
Users
Users are mapped by In the source record
, we always refer to source users by their IDs. For Server/Data Center users, the ID is their name. So, in the source record
when building your mapping file with a user transformation, you need to provide the source user’s ID, and its value must be the user’s name:
Code Block | ||
---|---|---|
| ||
{ "users": [ { "source": { "id": "Karlie Davis" }, "transformation": { "email": "karlie@test.com" }, } ] "transformation" } |
This transformation will change the user’s email address. You can also build a transformation that will map a source user to a destination user by ID. You just need to provide the destination user’s ID in the transformation
record :
Code Block | ||
---|---|---|
| ||
{ "users": [ { "source": { "emailid" : "karlie@test.com",Karlie Davis" }, "transformation": { "id": "5da444878f33800c416f30ed" } } } ] } |
You can learn more about what you can do with users in the User Transformations document.
...
Reuse a mapping file from a previous migration
The third option to customize the mapping through JSON is to reuse a mapping file created for a previous migration. It will work only if it’s applicable to the currently migrated configuration.
...
Panel | ||
---|---|---|
| ||
Key points:
|
Validations
...
and conflict detection
During the mapping file upload, we perform JSON validation checks for:
...
We’ve also built a fail-safe mechanism into the analysis process to avoid data loss or migration failures. It’s able to detect and report conflicts that can be introduced with customized mapping, such as:
Multiple source configuration elements are mapped to the same destination element after transformations.
A configuration element is mapped to a non-existent destination element.
...