Jira Migration. Tips on People Interaction

Andrey Kozynets
Atlassian Expert at Rozdoum

Our team at Rozdoum has performed Jira merges several times, and it was always a pain. Merging two or more active Jira instances into one, with a big amount of projects, users, and configuration schemes is a task that takes a great deal of effort. There are some tools out there to help you, but we are not going to talk about the technical side of the migration (merge) now.

In this post, I am going to take a different approach and focus on communication with your client. Jira/Confluence migration is a pretty specific process. The way you interact with the client can be one of the factors that define success or failure. I am going to share some of the rules we now use in our company. These rules are a result of some lessons that we have learned the hard way.

This post is nowhere a complete guide to building your communication with your clients. It provides a set of items you could add to your list to cut the risks bound to client communication: the risks which have a direct influence on the budget, the timeline, and the success of the project on the whole.

Tip One: Prepare the Client

At the very start, explain to the client that there is a difficult journey ahead and that at times it requires their contribution. There are tasks that you cannot do without the client, so they should be ready to allocate time and resources. Deliver the message that you, as an Atlassian expert, will do most of the job. Furthermore, you will guide the client through the tasks that they have to perform themselves. Insist that the overall success of the project depends on their contribution and cooperation. Don’t let them live within an illusion that you would perform all the work yourself. Jira to Jira migrations do not work this way usually.

What Could Go Wrong?

You should do it as soon as possible. There could be confusion and disappointment on the client’s side: “I hired YOU to do the job. Why do I have to do anything?”. However, if you manage to explain that from the very start reasonably, then things will go smoothly.

Tip Two: Support and Guide Your Client

Jira migrations cannot be done without client interaction. It is not just a technical task. You have to talk to the client a lot throughout all stages of the migration. Mutual trust — on a human interaction level — is a must. But when it comes to business, try not to trust the client 🙂

Once the scope is defined, there is a lot of work for you and your team, but also there are always some pieces of work which have to be done by the client. As an external contractor, there are many decisions you cannot make for them. For example, you cannot decide which subset of users have to be migrated from Jira A to Jira B or how to merge users which exist in both instances. This is a job that has to be performed by the client. Your next steps depend on it, and the job is blocked until the client does their part.

The client may tell you: “sure, we will do it”. However, it is in your best interests to not trust them too much. So…

Help Your Client to Perform Their Tasks

Often the client does not perform their task well, for different reasons. They probably don’t understand how important the task is or how to tackle it. Or they do it their own way instead of doing it the way you asked them to. So…

1. Make sure you explain the task and its importance really well. Example: If the users are not handled correctly, people won’t have appropriate access levels to the Jira after the migration.
2. Make agreements about the deadline for the task. Your next steps and the entire schedule depend on this task.
3. Make agreements about what happens if the deadline is missed or the task has completely failed. The client has to understand that if they miss the deadline or ignore the task, the project timeline and success is affected.
4. Make frequent checks to make sure that right thing is being done. Otherwise, you could end up getting something that you hadn’t asked for, even if it had been done within the deadline.

Take Away the Chance to Make Mistakes

Example: Imagine you are performing a test migration and are tuning the migration process. It is vital at this stage that the configuration of the source Jira is not changed! You kindly ask the client not to alter the configuration of any projects that are being migrated, and they say “Ok”. In reality, the chances are quite high that they will make changes to the configuration of the source Jira. There are numerous reasons why it is likely that it will happen: the message hadn’t been delivered to all the administrators of Jira, there was a misunderstanding, or they just had to do it “because”. To decrease this risk, your better option is to rely on software instead of people. Restrict the number of Jira administrators and project administrators, check the audit log daily to make sure nothing is being changed.

Another example is the final production migration — you have to make the source Jira read-only for the time of the migration even if the client asks you not to and promises not to add or edit issues. We were asked such things a couple of times, but we held our ground. The consequences can be catastrophic, and this is not the risk you want to take. So, apply read-only permission schemes and thus prevent people from making expensive mistakes.

What Could Go Wrong?

So, what could happen if you didn’t provide enough support to help a client carry out their tasks? Nothing bad, in some cases. In other cases though, your schedule could be compromised because the client didn’t do what they had to. The migration results and/or deadlines can be put in danger. At the end of the day, you are responsible for this delay even if you think it is ‘their fault’. (We will get to the part of ‘Who to Blame’ at the bottom of this post).

One great lesson we had with this kind of risk was the User Acceptance Testing.

Most of the clients tend to ignore the UAT phase. This is the time when they can test the migration results on the dedicated test instance and report any problems, ask questions, etc. Your team has to test the migration themselves of course. Despite all your effort, you cannot do all the testing for the client — they have to try using the migrated data and see if they get what they wanted. Usually, the client doesn’t do the acceptance testing well (or doesn’t do it at all) because

• they don’t understand how important it is,
• they don’t know how to do it, or
• they think you did it for them.

After the migration of the production instances is done, it may appear that things are not working as the client expected, but it is too late to fix! The chance is lost by ignoring the UAT phase.

This case illustrates very well how important it is to explain everything to the client, to help and guide them, and to make them do their job.

Tip Three: Establish and Strictly Follow the Procedure

Being nice, polite and respectful is a basic rule of people interaction, and we do recommend following that rule. At the same time, do not allow yourself to rely on your nice trusty relationships too much. It can lead you down the wrong path. Sometimes you have to make the client commit to their promises in a written way, sometimes you have to decline their requests. Often you have to be that irritating person who asks a lot of questions and wants to control everything. For the client, you probably won’t seem ‘nice’ at these moments. Keep in mind — you are doing an important task, a lot of effort and people involved, and then there is a budget, of course. Your top priority is to do the job well, being nice is less important.

Let’s dive into this topic in more detail.

Manage Expectations

Make sure that you set the client’s expectations for each piece of the job that you are doing.

Explain everything as you would explain it to a kid. Keep in mind that often you talk different languages with the client. They use their own terminology for Jira features and probably don’t have the same level of technical knowledge and understanding as you do (they don’t have to, they hired you!). So make sure that the client fully understands what they agree to.

Let’s take private filters as an example. If you are not going to migrate the private filters from one Jira to another — make sure you explain it to the client. Don’t just tell them “the private filters won’t be migrated”. Have a meeting to show them what a private filter is. Explain that there could be dashboard gadgets and Agile Boards which use these filters, and these gadgets/boards won’t work after the migration. Show them examples using their own filters and boards. Ask them to share this info with the heads of their departments or anyone who can be affected by this decision. It could be that the people you are talking to are ok with not having private filters migrated, but the work process of one or two departments will be heavily affected. So have them confirm the decisions with every party involved.

It is your job to provide enough information and make sure you are on the same page with the client about the upcoming piece of work.

What Could Go Wrong?

If you fail to set the correct expectations, the risk is high that in the end, the client gets much less than what they had expected or imagined. It causes frustration and loss of trust. The responsibility for this is, in most cases, on your shoulders!

Document Expectations

Write down all the agreements that you have with the client (see above) and make them sign these agreements in some way. Add it to the contract or just ask them to set an approval on the Jira issue or a Confluence page where these things are tracked. It is important to have your agreements documented and officially signed by both parties.

Sometimes the managers change, people forget or misunderstand things. The migrations are often stretched in time, and chances are high that information can get lost along the way. So, when an angry manager yells at you that their private filters are lost after the migration and that you have to fix it for free, right now; You can explain to the client that this is expected and politely point them to the signed agreements which clearly show that this is out of scope. It allows you to put a stop to any unnecessary escalation and bring the discussion back to a normal state.

What Could Go Wrong?

If you don’t document the expectations, you may end up arguing with the client when they accept the work. It is hard to find out who is right if it is not written and not accepted officially by both parties.

Changes are Evil: Stick to the Plan

Stick to the plan and the scope, treat any change request with suspicion.

At the start of the project, take your time to define the scope, estimates and the schedule. When the scope and schedule are defined, you shouldn’t accept any further changes. Migration is a tricky process with a lot of unknowns, especially at the early stages. There always should be at least 3 stages of migration. Sometimes there should be more, but we will talk about that more in the next post.

1. Test migration. You migrate things, discover new unknowns and problems and find solutions for them. You create your checklist.
2. Stage migration. This is the main ‘rehearsal.’ Once you think you have solved all of the problems, you perform a Stage migration which should go smoothly. Only minor changes to the process are acceptable. You also tune your checklist.
3. Production migration.

In an ideal world, absolutely nothing should be changed after the Test migration. In reality, clients often come up with new ideas and requirements along the way. The best thing for you to do is to decline these requests politely. However small the requested change looks, it can have a great impact, and not always foreseeable.

The later the request comes in, the greater danger it brings.

Our clients once asked us to “just quickly” change the keys of some projects right before the Production migration. This happened after the Test and Stage migrations were done and approved. The problem is that Jira keeps track of the project keys history. If you have a JQL filter which uses the project key ABC, and then you change the key to XYZ — the filter is still working because the source Jira knows that ABC is actually XYZ now. However, when you export the project and import it to another Jira instance, the history of the project keys does not persist. Consequently, the filter “project = ABC” is, in fact, invalid on the target Jira (along with all the gadgets and Agile Boards). We detected this danger in time, but we were really close to missing it. This would result in additional hours of technically complicated fixes which could put the whole migration in danger because it was performed during the weekend, and we had to either finish it before Monday or rollback all the changes.

What Could Go Wrong?

The risk is very high. Any change can endanger the whole migration. So please do not accept any last-minute changes. In fact, try to not accept any changes after the Test migration. Be strong. Learn to say ‘No’.

Tip Four: Do it Yourself if You Can

Don’t delegate to the clients the tasks that your team can do. It may be tempting to do so and save your team’s time, especially if the client suggests they want to perform some of the tasks themselves. Be very careful — instead of saving time you could lose even more by explaining how exactly you want the task done and guiding the client through the process.

Tip Five: Talk to Decision Makers

Try to get access to the person(s) making decisions and keep in touch with them.

Sometimes the managers assigned to the job could be an impediment. It doesn’t mean they don’t do their job well, but they are a link between you and the person making decisions. It happens that the content or the tone of the message is lost in this communication chain. This can result in bad decisions being made. You are deprived of a chance to talk to the person making decisions and to explain to them critical aspects of the migration.

Your chances of doing the job effectively are much higher if you have access to decision makers.

Conclusion – Who to Blame?

So, whose responsibility is it if things went wrong and you had major problems with the migration? Simple — it is all your fault! It may seem that I depict the clients as whiny kids who don’t know what they want and don’t want to do their part. Hence they could similarly be blamed for something that went wrong.

That’s not how things are. First of all, I exaggerate a bit to add drama. 🙂 Second — never forget that it is YOUR job to guide the client through the migration process, and, if anything goes wrong, it is likely due to the fact that you failed to communicate well with them. I hope the lessons we have learned can help you do your job better, and do it with the least amount of pain possible. Good luck!