Introduction

 
This feature will enable customers to have functionality to approve or reject an approval task via email. One can directly respond to the pending approval task without logging into Identity Manager.

Once this feature is turned on from configuration and notify by email is selected in workflow definition with required email notification template, approver should receive an email with approve and reject link once someone has requested a PRD. We support localization for email approval notification templates and approve or deny phrases.

Approver can act upon these mail in two ways.

1. Click on either approve or reject link it should compose a new email with required subject and body. In body approver can enter the comments. Please do not modify the subject. Once done approver can send that email.

• Reply with reserved keyword like approve or reject (or whatever we have already configured in user app). Approver should provide these keyword by adding in subject and body should be used to provide the comment (To use email approval feature in this way you should configure your from address same as the incoming mail box user or reviewer has to manually put the incoming mail email address at the time sending response).

Once approver will send this mail approver will receive feedback mail it could be either success Or failure.

Setting up Email Based Approval Feature

 

Pre-requisites:

• Installed IDM 4.6 version to make use of email based approval feature.

• Outgoing email server is setup.
  
  
  
  • Outgoing mail server is pre-configured using configupdate or imanager. Please ensure outgoing mail is working.
  
  

• Use Designer 4.6 for updating or creating new workflows.

• You have an account setup on an email server which supports POP3 or IMAP protocol. This account will be used while setting up the incoming email configuration.

• (Optional) If the email server outside the firewall, ensure that a proxy is setup which can help Identity Manager to reach to the email server.

Note: The feature works for simple approvals requests (requests which don’t have complex forms associated).

Configuration Highlights

• Configuration in Designer for email templates
  
  
  
  • You need to import new email based approval package and install that package. You also need to deploy new notification templates available in this package to be deployed on your identity vault.
  
  
• Using the email template on your PRDs

• Configuration in configupdate utility
  
  
  
  • You need to configure outgoing mail properties from configupdate.
  
  
• You may require to configure private key store related properties if you are enabling email digital signing for outgoing mail.

• Configuration in IDM Dashboard
  
  
  
  • You need to configure incoming mailbox related properties, cleanup service properties, approve and deny phrases etc. from Administration > Email based approval.
  
  

Configuration in Designer for email templates

• Importing the email based approval package

• Uncheck show base packages only and select Email Based approval package and click ok

• Right click on IDM engine and select properties > Packages

• Click ( ) Icon for new package and select Email based approval package.
  
  
  

• Install the package and click ok.

• Expand Default Notification templates and select all email based approval templates.
  
  
  
  

• Deploy the templates in to ID vault.

Configuration in configupdate utility

• You need to configure outgoing mail properties from configupdate utility in Email Server Configuration section inside User Application tab this email account will be used to send the email notification from IDM.
  
  
  
  

Configuration in IDM Dashboard

Login to IDM dashboard as Admin account.

• Navigate: Administration > Email based approval.

• Provide the email server details and click save.

• Note: This changes don’t require any tomcat restart.
  
  
  
  

Using Email Based Approval feature

• Create a required PRD workflow with Notify participants by Email options enabled.
  
  
  
  

• Right click on the approver icon and select show Email-Notification.
  
  

• Select Email based Approval provisioning Notification template in Email Template dropdown box.
  
  
  
  

• Select the email template wherever the approval is required (based on workflow).

• Deploy the workflow once created.

• Login to idmdash as normal user navigate to Access->Request.

• Create new request and search for permission (deployed PRD), after selecting permission provide comment and click on request.
  
  
  

• This will trigger a notification email to the reviewer he has to click on approve or deny link present in email content it will compose a new email, you can also reply to the mail to given email address inside email content by adding reserved keyword(Approve or Deny) in subject.
  
  
  

• Provide the comments in newly composed mail and click on send.
  
  
  
  

• Reviewer should receive the response, it could be either success or failure.
  
  
  
  • Sample feedback mail Success
    
    
    
    
  
  
• Sample feedback mail Failure
  
  
  
  

Enabling Socks Proxy (optional)

 
To connect to incoming mail box via proxy server instead of direct connection, you have to enable the socks proxy

• Login to idmdash as Admin account.

• Navigate: Administration > Email based approval.

• Enable socks proxy and provide proxy host, port etc detail the details
  
  
  
  

Setting up Digital Signature Support (optional)

• You need to provide private key store and private key certificate properties from config update.

• If private key certificate alias contains special characters you may require to rename the alias as IDM cannot read few special chars.

• You need to choose email content option form idmdash appropriately.

• Importing private key certificate:

• <JRE_BIN_PATH>/keytool -v -importkeystore -srckeystore <privatekey_certificate_path>-srcstoretype PKCS12 -destkeystore <keystore_path> -deststoretype JKS

• Renaming the imported certificate:

• <JRE_BIN_PATH>/keytool -changealias -keystore <privatekey_store_path> -alias “<old_alias_name>” -destalias <new_alias_name>

• Login to idmdash as Admin account. Navigate: Administration > Email based approval. Email content option select Include action links with digital signature and save the configuration.

Template customization

 
You can customize the email approval provisioning notification template, success and failure notification templates as per your requirement. We have introduced few new tokens along with existing tokens which will be used for template customization. I am describing the newly introduced tokens below

• EMAIL_APPROVAL_TOKEN_ID: Randomly generated secure token, it contains alphanumeric characters (it is mandatory to include this token in subject of provisioning templates as well as in reply email subject).

• PROXY_AS: If user is working as proxy for some approver this field will have approver name otherwise it will be “na”.

• REPLY_EMAIL: Reply to mail id to which approve will be sending the email to approve or deny the task.

• REPLY_SUBJECT: Contains the subject for failure or success notification mail, It contains token along with approve or deny action.

• APPROVE_PHRASE: localized phrase to approve the task (it should be added in subject or reply email along with token if approving).

• DENY_PHRASE: localized phrase to deny the task (it should be added in subject or reply email along with token if denying).

• TASK_ACTION: Action taken by the approver while acting on the approval task it could be either approve or deny.

• ERROR_MESSAGE: Error messages in case of any failure or error while task approval by email.

Trouble Shooting Tips

• Email based approval token is empty in the provisioning request mail.
  
  
  
  • Email based approval is disabled by mistake. Check configuration in IDM dashboard.
  
  

• User App is not acting on any emails.
  
  
  
  • Check whether the incoming mail box is connected and reachable from the server where it is deployed (refer catalina.out logs).
  
  

• Approve/Deny link in the email is not working.
  
  
  
  • Check mail client is configured or default application is selected to send email.
  
  

• Email based approval is configured, but mails are not having the Approve/Deny links
  
  
  
  • Templates may not be properly configured on the workflows.
  
  

• How to check when it starts up correctly
  
  
  
  • If you are enabling feature from idmdash UI, It will give success message if the feature starts properly without any error.
  
  
• You can also refer the log for detailed information regarding each component of email based approval like jms, incoming mail box connection, and cleanup service.

• Sample logs if feature stats up successfullyINFO com.novell.soa.notification.impl.EmailReceiverEngine- [RBPM] Successfully started persistent JMS notification system for email based approval
  
  EmailReceiver Notification Thread] INFO com.novell.soa.notification.impl.EmailReceiverThread- [RBPM] Starting asynchronous notification system
  
  INFO com.novell.soa.notification.impl.EmailReceiverEngine- [RBPM] Mailbox service for incoming mail started successfully without any warning
  
  INFO com.novell.soa.notification.impl.EmailReceiverEngine- [RBPM] Email based approval token cleanup service started successfully.

• When it might require you to restart
  
  
  
  • On clusters setup, if some changes has done in incoming mailbox properties or you turned OFF/ON feature you may require to restart nodes other than the active node.
  
  
• If you are continuously getting errors regarding not able to connect to mailbox for some reason and problem persist for hours (verify connectivity between with mailbox host as well).

• For cluster setup
  
  
  
  • You need provide running active mq server IP in sever.xml of other nodes as default se to localhost.
  
  

• Email based approval token is empty in the provisioning request mail.
  
  
  
  • Email based approval is disabled by mistake and using the new email templates in PRD.