DRAFT: Migrating a Custom Plug-in using the JavaMail library to use the Jakarta Mail library

In Appian 22.3, the mail library available for use in custom plug-ins has been updated from JavaMail (javax.mail) to Jakarta Mail (jakarta.mail). Custom plug-ins that reference the JavaMail library will need to be updated to use the Jakarta Mail library to continue to work in Appian 22.3.

The update to use the Jakarta Mail library requires import statements in each java class that reference the javax.mail package and the javax.activation package to be updated to reference the jakarta.mail package and the jakarta.activation package respectively.

Example steps to update a plug-in project in Eclipse:

1. Open your existing plug-in project in Eclipse.
   
2. Ensure the project builds successfully.
   1. Right click your project and click Export….
   2. Select the JAR file option as the Export destination.
   3. On the Resources to export dialog, clear the .classpath and .project selections as these files are used exclusively by Eclipse.
   4. Select a destination directory for the export.
   5. Click Finish.
3. Replace the JavaMail dependency JAR with the Jakarta Mail JAR in META-INF/lib
   1. Ensure you include the Jakarta Mail JAR within your plug-in. You should always include the library that contains the classes used in your plug-in so that the plug-in uses the same version of the library regardless of which version of Appian it runs in. See: https://docs.appian.com/suite/help/latest/Custom_Plug-in_Packages.html
      
4. Update the build path to remove the JavaMail library JAR and add the Jakarta Mail library JAR.
   1. Update your Java Build Path to include any new JAR files; otherwise, the project won't build.
   2. Right click the project and select Properties.
   3. In the Package Explorer (left navigation) click Java Build Path.
   4. On the Libraries tab, click Add JARs….
   5. Select the Jakarta Mail JAR file in your project.
   6. Select the existing JavaMail library and click Remove.
      
5. Update any Java classes that reference the javax.mail or javax.activation packages to use the jakarta.mail and jakarta.activation packages.
   1. The Jakarta Mail library implements the same classes as the JavaMail library because Jakarta is the updated version of this same library. As such, we need to update the classes in the project to use the jakarta.mail package instead of the javax.mail package and the jakarta.activation package instead of the javax.activation package.
   2. Example class using javax.mail:

      1. package com.appiancorp.plugins.example.mail;
         
         
         
         import java.util.Date;
         
         import java.util.Properties;
         
         
         
         import javax.mail.Authenticator;
         
         import javax.mail.Message;
         
         import javax.mail.PasswordAuthentication;
         
         import javax.mail.Session;
         
         import javax.mail.Transport;
         
         import javax.mail.internet.InternetAddress;
         
         import javax.mail.internet.MimeMessage;
         
         
         
         import org.apache.log4j.Logger;

   3. Example class updated to use jakarta.mail:

      1. package com.appiancorp.plugins.example.mail;
         
         
         
         import java.util.Date;
         
         import java.util.Properties;
         
         
         
         import jakarta.mail.Authenticator;
         
         import jakarta.mail.Message;
         
         import jakarta.mail.PasswordAuthentication;
         
         import jakarta.mail.Session;
         
         import jakarta.mail.Transport;
         
         import jakarta.mail.internet.InternetAddress;
         
         import jakarta.mail.internet.MimeMessage;
         
         
         
         import org.apache.log4j.Logger;
         
         

   4. The updated classes and methods from the Jakarta Mail library will typically implement the same parameters and logic as the JavaMail equivalents. However, there may be some differences that will require updates to your plug-in beyond the update of the package naming alone.
6. Increment the plug-in version in appian-plugin.xml.
   1. In order to differentiate this latest version of your plug-in from the existing release that implements the JavaMail library, you should increment the version of this plug-in within the appian-plugin.xml file.
      1. Example current version:
         1. <version>1.0.1</version>
      2. Example new version:
         1. <version>1.1.0</version>
   2. As this is a change beyond a simple revision, you may wish to increment the minor or major version of the plug-in.
7. Ensure the updated plug-in builds successfully.
   1. Right click your project and click Export….
   2. Select the JAR file option as the Export destination.
   3. On the Resources to export dialog, clear the .classpath and .project selections as these files are used exclusively by Eclipse.
   4. Select the _admin/plugins folder of your installation directory for your export destination. - This directory is created during application server startup.
   5. Click Finish.