Configuring Email notifications

Email notifications feature allows you to send notifications to users who are expected to perform a certain action on a step of a workflow.

Before you begin

  • Ensure that the application is set up to send emails to users.
    For more information, see smtp section - env_settings.ini file parameters file.
  • Ensure that you have imported the email_integration_model.zip data model file in the Admin UI. The email_integration_model.zip data model file is located here: $TOP/mdmui/env-export/emailintegration. For more information, see Importing data model.
  • The email notifications artifacts like report, input specs are included with the data model for the feature. If you change the code, you need to also change the name of these artifacts.

Configuring email notifications

Proceed as follows if you want to configure email notifications.
  1. Stop the services.
  2. Go to the Email integration configuration section in the $TOP/bin/conf/env-settings.ini file, set the value as enable=yes, and save the file.
  3. Run the $TOP/bin/configureEnv.sh file.
  4. Start the services.
  5. Go to $TOP/bin/conf/classpath/jars_custom.txt file. Verify that the email_integration.jar file location is $TOP/mdmui/libs/emailIntegration.

Configuring email notifications by using customized sample code

Proceed as follows if you want to configure email notifications by using customized sample code.

  1. Log in to Admin UI.
  2. Generate the email-integration.jar file.
    1. Get the source code from the $TOP/mdmui/samples/com.ibm.mdm.email.integration.zip file. The source code contains the following two classes.
      com.ibm.mdm.approval.notification.GenerateAndSendApprovalEmail.java
      This class contains the code for generating the email content that is described in the Step 3. It also retrieves the email of the performer set for the step from which this extension is called and sends the email. You can update this code to change the content required in the email. The sample code has the logic to create the attribute difference table. The code also picks up the exit values that are provided in the step and provides them as the actionable options in the email.
      com.ibm.mdm.approval.notification.ExecuteUserResponse.java
      This class contains the code that is attached to the report described in the Step 4. This code reads the response emails with specific subject format based on the user actions that are taken in the notification email and parses the subject lines to take actions on respective items in the workflow. If the method that generates response email subjects in the com.ibm.mdm.approval.notification.GenerateAndSendApprovalEmail.java class is updated, you need to also update the logic to read the emails in this class.
    2. Compile the sample code with your changes and generate a JAR file with email_integration.jar as the file name.
    3. Stop the services.
    4. Go to the Email integration configuration section in the $TOP/bin/conf/env-settings.ini file, set the value as enable=yes, and save the file.
      Note: This step ensures that the email_integration.jar file gets fetched from the $TOP/mdmui/libs/emailIntegration folder and the JAR path gets automatically updated in the $TOP/bin/conf/classpath/jars_custom.txt and $TOP/bin/conf/env-settings.ini files.
    5. Replace the JAR on the server present in the $TOP/mdmui/libs/emailIntegration folder with the JAR that you have generated in the Step 2b.
    6. Run the $TOP/bin/configureEnv.sh file to update the class path, and start the services.
      Note: No overwrite is required while running the configureEnv.sh file.
    7. Start the services.
  3. Configure the workflow from which you want to send email notifications.
    1. Go to the Data Model Manager > Workflows > Workflow Console.
    2. Click New to create your own workflow. Else, select an existing workflow and click Edit.
    3. In the Workflow Steps section, click the step from which you want the email notifications to be sent.
    4. Click Add script, above the Edit Workflow Step section. The script parameters get added to the workflow.
    5. In the Script field, click Edit.
    6. Add the following to the scriptlet editor and click Save. 
      //script_execution_mode=java_api="japi://com.ibm.mdm.approval.notification.GenerateAndSendApprovalEmail.class"
  4. Configure Check Email and Execute report. This report checks the inbox of the From address and reads the fetched emails since the last report run. The application has a report job (Report Type: Email Check, Report Name: Check Email and Execute) scheduled to run repeatedly. This report job has an input spec where you must configure the email host, username, password, mail protocol, and folder details for reading the emails. The report filters the emails having the specified subject format and parses the subject line to get the collaboration area, step, entry, and exit values. The exit value that is retrieved from the response email is set on the entry and the entry then moves forward in the workflow.
    1. Go to the Product Manager > Reports > Report Console.
    2. In the Report Console, click Check Email and Execute report.
    3. In the Parameters Value Set section, add the details for the email account that is going to receive responses from the users, and click Save.
  5. Configure your email application.
    1. In your email application, set a folder in the email account that sends the emails to users where the responses are going to be received. Check Email and Execute report checks this folder for responses.
  6. Configure the Url Helper Lookup table.
    1. Go to the Product Manager > Lookup Table > Lookup Table Console.
    2. Open the Url Helper Lookup table.
    3. Specify the Value field for the HelperUrl key as the <Protocol>://<IP address>:<Port> of the server where the application is running. Example http://127.0.0.1:9090

Results

When a workflow reaches a certain step, performers receive auto-generated emails. This email notification is sent to the details that you specify for each performer in the Security > User Console > User Profile. This email notification has certain actions that such users can directly click and allow further processing of the workflow without the need to log in to the application.
Note: When an item enters a step, the application triggers an email notification to users who are performers for that step only if email integration script is added for that step. No email generation happens for Initial step.