Step-by-step Classic Mail Handler to Next Generation Mail Handler migration aid
Last updated
Last updated
Important: As of version 9.2.0 Classic handlers have been deprecated and do not work anymore.
This is a step-by-step guide for migrating Classic Mail Handlers to Next Generation Mail Handler. If you’re already familiar with our app, you may only need the quick guide, however, if you’re unsure about any of the steps, check the detailed procedure below.
Add a new mail account in Email This Issue administration. Read more here.
Test the connection and save it. Read more here.
Create a Next Generation Mail Handler and save it. Read more here.
Configure a next-gen handler. Read more here.
Delete the Mail server connection in Jira system administration – Incoming emails.
Open the email client of the mail account and remove everything from the processing folder that you don’t want to be processed.
Enable your Next Generation Mail Handler.
Delete the Classic handler in Email This Issue administration and its counterpart in Jira administration - Incoming emails.
We feel it is important to emphasize that you should either experiment with your new handler in a test environment entirely OR at least work on it using a test project and test email address to be on the safe side.
Migrating the classic handler setup to match that of the next-gen handler’s is no easy task. Please make sure that you understand the differences between the two handlers. Read more here. Also make sure you know how you’ll create the Next Generation Mail Handler before working in a production instance. Read more here.
When you’ve created the test project and you have the test email address which will be your mail handler address, your first step should be adding a new mail account in Email This Issue and enabling it. Read more here.
It is important that you enable the mail account as it won’t be visible in the handler if it's disabled.
Test the connection to see if the credentials are accepted and save it when the connection is successful. Read more here. If you run into problems here, troubleshoot them before working with the handler.
When this is done, navigate to the mail handlers and create a Next Generation Mail Handler. Read more here. Select the mail account you just created and add your default reporter. This function is the same as it was in the classic handler, you may even use the same technical account but make sure that its permissions are correct for your test project. For testing, we recommend that you also enable the debug option here so you can see the results of your processing later on.
Save the handler and keep it disabled until the last step.
Important: If you make it enabled now, there is a chance that the old and the new handler would steal emails from each other, making processing messy and unreliable.
When this is done, start to configure your handler according to your requirements. Read more here.
When you’re done with configuring the mail handler, navigate to Jira system administration – Incoming emails and delete the Mail server connection you’ve had connected to your classic mail handler.
Note: You can delete the old handlers later, if the mail account in deleted here, no new mails will be processed by the old handler.
When this is done, open the email client of the mail account you’ve connected to our app.
If this is a test account and it is empty, you don’t have to do anything. If you’re working on a production account that already has emails in the inbox (read or unread), remove everything you don’t want to be processed. This is needed because at the first processing round we download every email from the folder. Later on, we only download those that have not been processed yet.
Any emails that are received while you’re carrying out this step needs to be left in the inbox untouched.
All you need to do now is enable the Next Generation Mail Handler you’ve created and all emails that are left in the inbox will be processed by the new handler. This is very important to emphasize, all emails will be processed regardless of being read or unread, already processed or unprocessed.
See if it works as intended, and clean up your configuration by deleting the Classic Mail Handler in Email This Issue administration and its counterpart in Jira administration.
