This is a step-by-step guide for migrating classic mail handlers to next-gen handlers. 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, feel free to lean on the explanation and the screenshots below.
Quick Guide Steps:
Test the connection and save it
Create a next-gen handler and save it
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-gen handler
Delete the Classic handler in Email This Issue administration and its counterpart in Jira administration - Incoming emails
Explanation and screenshots
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 and you know how you’ll create the next-gen handler before working in a production instance.
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.
...
| Info |
|---|
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. 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-gen handler. 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.
...
| Note |
|---|
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.
...
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.
| Info |
|---|
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-gen 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 config by deleting the classic handler in Email This Issue administration and its counterpart in Jira administration
| Redirect | ||||
|---|---|---|---|---|
|