Configuring the Email mapping plug-in

About this task

The Email-mapping plug-in is included with IBM Content Navigator. To use it, you must update the list of usernames and email addresses, and configure the plug-in.

The Email-mapping plug-in provides a service that returns an email address that is associated with an IBM Content Navigator user. The email address that the service is returning is the address that the email is being sent from.

If you enable a desktop and repository for Box Share, a mapping of user IDs and email addresses is required. This action displays the user’s email address and uses it to send the link to the document. The email address might be provided in one of the following ways:

  • For a IBM Content Cortex repository that is configured with email addresses, IBM Content Navigator uses the email address from IBM Content Cortex.
  • For a IBM Content Cortex repository that is not configured with email addresses, or for an IBM Content Manager repository, you can create a custom list of user IDs and email addresses, and configure the Email-mapping plug-in.
  • If you do not use the email addresses from IBM Content Cortex or from the Email-mapping plug-in, you can set the configuration option in the desktop. This action allows users to enter an email address when a document is shared.
    Important: The email address that is entered by a user is not verified and poses a security risk.
To create a custom list of user accounts and email addresses, you need to update the JSON file for the Email-mapping plug-in, rebuild the JAR file, and then configure the Email-mapping plug-in.

Before you begin Determine the user IDs and email addresses that you want to set up for the Box Share action. Create a custom list of user IDs and email addresses.

Note: Starting in version 3.0.9, if you want to send emails, you must update the Email-mapping plug-in to include a plug-in request filter when you use the HTML-based email service. The plug-in request filter provides the From email address to the email request since the request no longer includes the user’s email. The filter details are provided in the com.ibm.ecm.extension.emailMapping.EmailRequestFilter class.

Procedure

Follow these steps to configure the Email-mapping plug-in:

  1. Edit the emailMapping.json file that is located in the JAR file for the Email-mapping plug-in. The default JAR file path for the installation directory on Windows is C:\Program Files\IBM\ECMClient\plugins\emailMappingPlugin.jar.
  2. Find the sample list of user IDs and email addresses, and replace it with your custom list of user IDs and email addresses. Save the file.
    Optional. If you want to customize the Email-mapping service, you can modify the code in the emailMappingPlugin.java file.
  3. Rebuild the JAR file, emailMappingPlugin.jar, and save it in the original JAR file path. Follow these steps to rebuild the JAR file.
    1. Back up the original emailMappingPlugin.jar.
      For example, copy emailMappingPlugin.jar to emailMappingPlugin_original.jar.
    2. Run this command to extract the JAR file contents. 
      jar -xvf emailMappingPlugin.jar

      You see that the com and META-INF folders are extracted to the current directory.

    3. Modify the emailMapping.json file in the com directory to include your custom email addresses.
    4. Remove all signature files with the extension .rsa and .sf in the META-INF directory. Do not delete the MANIFEST.MF file.
    5. To rebuild the JAR file, run 
      jar -cvfM emailMappingPlugin.jar com META-INF

      This action overwrites the existing JAR file by using the extracted com directory, which contains the modified emailMapping.json file and the META-INF directory.

      With the M option, the jar command does not create a manifest file. You can also create a JAR file by using the 
      jar -cvfM emailMappingPlugin2.jar com META-INF
      command and then, rename this JAR file to emailMappingPlugin.jar.
  4. Open the administration tool in the IBM Content Navigator web application, and click Plug-ins > New Plug-in.
  5. Enter the JAR file path for the Email-mapping plug-in. The default JAR file path for the Email-mapping plug-in class on Windows is C:\Program Files\IBM\ECMClient\plugins\emailMappingPlugin.jar.
  6. Click Load.
  7. Save your changes.

What to do next

Ensure that Box Share is enabled for your desktop and any repositories. For the desktop configuration settings, select a Box repository for shared files, and select whether to allow users to update the email address when they share a document.

The results of the configuration settings at run time are explained in the following table:

Table 1. Configuration settings at run time
Do not allow update User ID included or not included Results for the Box Share action
Yes. Allow users to update the email address when they share a document. Yes. The user ID is included in the file emailMapping.json. The email address is displayed, and the user can change it to a different email address.
Yes. Allow users to update the email address when they share a document. No. The user ID is not included in the file emailMapping.json. The email address is blank, and the user can enter an email address.
No. Do not allow users to update the email address when they share a document. Yes. The user ID is included in the file emailMapping.json. The email address is displayed, but the user cannot change it to a different email address.
No. Do not allow users to update the email address when they share a document. No. The user ID is not included in the file emailMapping.json. An error is returned. The administrator needs to update the file emailMapping.json, rebuild the JAR file, and reload the plug-in.