Schedule Email Notification using Oracle BPEL - Part 1

Email notifications are widely used in Oracle Applications for FYI or Action notifications. They can be achieved in many ways using Workflow, PL/SQL, host file etc. As we are all getting geared up for Fusion Middleware, I wanted to explore the option of using BPEL process. In my article, I will create a bpel process which it scheduled to send email notifications say every 30 min. For simplicity I will do this in two steps which are covered in two articles. 1. Create a bpel process which sends email notification. 2. Schedule the above bpel process to run every 30 min. This article covers the sending emails using BPEL process. Before I go into the steps of implementing email notification, I will brief you about the environment I'm using for this article. Environment for this article SOA Suite 10.1.3.1 Basic Installation. So it uses Oracle Lite database. JDeveloper 10.1.3.3.0 For setting up the environment, refer to the SOA Suite Installation article. The problems I've faced during installation are: Internet Explorer 7.0 - I was getting "The procedure entry point GetProcessImageFileNamew could not be located in the dynamic link library PSAPI.dll" error message at 99% of installation progress bar. So I had to uninstall IE 7.0 to get it working. Funny thing is after you install SOA Suite, you can install IE 7.0 and it works perfectly. Firewall - My McAfee firewall blocked opmn service. So the Recommended installation was failing during installation. Disable your firewall or make exclusion list during installation. The above two problems were resolved after 4 hrs OWC session with Oracle Support. You can continue with the later part of the article, if your environment is set up. BPEL Process using Email Activity Notification services in BPEL are exposed as web services. The notification service sends email using SMTP and receives email from IMAP-based or POP-based email accounts. You can use Email activity in the component palette to add email notification of BPEL process. You can directly enter the required and optional email addresses and message content (subject and body) or you can use the following built-in functions: Identity lookup dialog: Browse the user directory that is configured for use by Oracle BPEL Process Manager—Oracle Internet Directory (OID), JAZN/XML, LDAP, and so on. XPath Expression Builder: For recipient email addresses (To, Cc, Bcc, Reply To), you can use the XPath Expression Builder to get email addresses dynamically from the input. For my example, I will directly enter the recipient email address, subject and body in email activity fields. Before using email activity, you must set up configuration details for email accounts in the ns_emails.xml file, found at <SOAHOME>\bpel\system\services\config Configuring Email Accounts in ns_emails.xml: ns_emails.xml is found in <SOAHOME>\bpel\system\services\config folder. 1. Make a backup copy of the ns_emails.xml file. 2. Open ns_emails.xml in Text Editor and Change the NotificationMode from "NONE". NotificationMode can be set to the following: EMAIL - If you have only email setup, but not other channels like voice, SMS, fax, etc. ALL     - if you have email and other channels like voice, SMS, fax, etc. set up. I will be using only email, so I have set NotificationMode to "EMAIL". 3. Configure Default EmailAccount. When Email activity is selected in BPEL process, From Account field is defaulted  with "Default". If "Default" email account is not configured in ns_emails.xml, email notification is not sent to the recipient. Also this account is used when no account is specified to receive an email notification. This account is also used to send task-related notifications. A default email account must always be specified in the configuration file i.e ns_emails.xml Change FromAddress, OutgoingServerSettings, IncomingServerSettings elements to your desired email address and your smtp host name as below. 4. This step is Optional. Define the parameters for the additional email account with an additional <EmailAccount> </EmailAccount> structure. For Example: If I defined 'Apps2Fusion' email account, I can use 'Apps2Fusion' in From Account field in Email activity.    <EmailAccount>       <Name>Apps2Fusion</Name>       <GeneralSettings>         ...       </GeneralSettings>       <OutgoingServerSettings>          ...       </OutgoingServerSettings>       <IncomingServerSettings>          ...       </IncomingServerSettings>    </EmailAccount> 5. Save ns_emails.xml Configuring wf_config.xml: wf_config.xml is found in <SOAHOME>\bpel\system\services\config folder. It is a workflow configuration file. Add the below property to wf_config.xml <property name="oracle.bpel.services.notification.publisher_interval" value="1" /> This property specifies the interval for sending notifications. If this property is absent, the notifications are sent every 15 mins (default) or after starting the SOA Suite. Once the cofiguration files i.e ns_emails.xml and wf_config.xml are edited, Start your SOA Suite and JDeveloper. If you have already started SOA Suite before editing these configuration files, restart the SOA Suite. Creating Email Activity in BPEL Process Open SOA Launch Console and Click on Application Server Control link. Login with username/password and go to Runtime Ports link at the bottom. Write down the RMI port number. We will use this port for creating Application Server connection in JDeveloper. Open JDeveloper. Create Application Server Connection and test it. RMI Port 12401 is fetched from above screenshot. Create Integration Server connection using the above application server connection. Test it. Now I will create Asynchronous BPEL project. My BPEL process looks like in below screenshot. I will drag the Email Activity from Component Palette (left most frame), on to BPEL process in between the receive and response activities. Configure the fields in Email activity. From Account is defaulted with 'Default' email account name. Default email account settings are taken from ns_emails.xml You can also use XPath Builder to set the fields dynamically from input variables. Click OK. I've renamed the activity to "SendEmail". Email is a complex activity like a subprocess in workflow. You can click on "+" of email activity to expand it. It contains Assign activity which assigns the values for the different parameters of email, and Invoke activity to initiate Notification Service. If NotificationMode parameter in ns_emails.xml is not changed from "NONE", the notification is sustained here. Save All. Deploy the process on to Integration Server. Now Login to BPEL Control and Click on the process name in the dashboard. Click on Post XML Message to manually kick off the process. Check the email. I've received email successfully. But the message text came as an attachment. So I went back to my email activity and unchecked Multipart message attachments. I've deployed and ran the process again. Bravo !!! I got the email notification as I wanted. You can view the flow and the xml data at each activity. Click on Instances in BPEL Console, then Flow tab. To revise the whole process to send email notifications, I'm briefing the steps below: Set your SOA Suite enviroment for development. Configure ns_emails.xml and wf_config.xml CreateAsynchronous BPEL Process Create Email acitivity and enter values for To, Subject and Body fields Save and Deploy the Process Manually initiate the process Check the email In this article, I've manually initiated the process to send notification. I will automate this step to schedule the bpel process in the next article.

Using Email to initiate a BPEL Process

The notification service in Oracle BPEL Process Manager allows you to send a notification by email (as well as voice message, fax, pager, or SMS) from a BPEL process. However another requirement is to be able to use the receipt of an email to initiate a BPEL process. This is the subject of this blog, many thanks to Muruga Chinnananchi on whose original example this is based. Essentially we want to create a simple process EMailActivation which recieves an email sent to a particular email address. To achive this there are two basic steps: Configure the BPEL Server to be able to connect to the mail account. Define the BPEL Process to be initiated on receipt of an email. Note: Download working example. Configure Email Account To configure the email account which the BPEL Server should connect to, we need to place a MailAccount xml configuration file (in our example BpelMailAccount.xml) into the following directory:     <soa_home>\bpel\domains\default\metadata\MailService Note: You will need to create the metadata and MailService directories. The file itself can have any name (though must end with .xml) as you can define multiple accounts. However make a note of the name as you will need it to link your BPEL Process to the actual mail account. Here’s our sample file: The outgoing SMTP service doesn’t need to be configured (as we use the notification service to send outgoing emails). However the incoming account is defined by the following tags:     <incomingServer>         <protocol>[protocol pop3 or imap]</protocol>         <host>[imap or pop3 server]</host>         <email>[imap or pop3 account]</email>         <password>[imap or pop3 password]</password>         <folderName>[imap only, inbox folder ]</folderName>     </incomingServer> Note: When defining the account name, be careful to use the actual account name not the email address as they are not always the same. Creating BPEL Process The first step is to use JDeveloper to create an Asynchronous process initiated by a request message with a payload containing an element of type mailMessage (defined in Mail.xsd installed as part of BPEL PM). To do this use the BPEL Project Creation wizard to create a BPEL Process in the normal way. After entering the process name and specifying the process template to be asynchronous, select "Next". This will take you to the next step in the wizard where you specify the Input and Output Schema Elements, click on the flash light for the input schema and select Mail.xsd (located in <SOA_HOME>\bpel\system\xmllib) as shown in the figure 1 below. Figure 1 - Specify Input and Output Element This will then open the type chooser window to select the element to use from the imported schema. Select the mailMessage element as shown in figure 2 below. Figure 2 - Type Chooser Once the process has been created you can remove the callBackClient activity as we won’t need this. Import Common Schema If you now try and compile your process, you will find it fails with an error message. Thus is because the Mail.xsd itself imports a schema (common.xsd), so you need to import this schema as well. To import the Mail Schema into your BPEL Process, ensure the diagram view for your BPEL process is open and selected in JDeveloper. Then within the BPEL Structure window, right click on the Project Schemas node and select "Import Schemas" (as shown in figure 3 below). Figure 3 - Import Schema Note: Once imported, manually update the WSDL file to ensure the import statements for both the Mail.xsd and common.xsd are contained within the same <schema> element or it will still fail to compile. See previous blog - Using Nested Schemas with BPEL for details. Define Mail Activation Agent The process itself is now ready for deployment. However we need to complete one final activity, which is to tie the BPEL Process to a mail activation agent for the Email account that we defined earlier. The Activation Agent will poll the defined mail box for emails and then for each email it receives invoke an instance of the process to handle it. To do this you need to add the following definition to the bpel.xml file, after the <partnerLinkBindings> element:   <activationAgents>     <activationAgent className=”com.collaxa.cube.activation.mail.MailActivationAgent”                             heartBeatInterval=”60”>       <property name=”accountName">BpelMailAccount</property>     </activationAgent>   </activationAgents> Where heartBeatInterval is how often we want to poll the email account for new emails, and the accountName corresponds to the name of the account configuration file we defined earlier. Finally deploy the process and send an email to the appropriate account. Gotcha!! - If you modify the BPEL process in JDeveloper, the bpel.xml file may lose its changes (i.e. the activationAgent definition), and as a result the process will never get initiated - so always check the bpel.xml file is correctly defined just before deploying the process. Email Server To make testing easier, I installed my own local mail server. For this I used James (which is an Open Source Java Mail Server from Apache). Installation of James is very straight forward you just download it and unzip it to a convenient location. To start it, use the script run.bat or run.sh, depending on your operating system in the james-2.3.0/bin directory. To configure James just bring up a telnet session (on port 4555) to bring up the Remote Administration Tool from which you can create the required accounts. For example, to create the accounts bpel and jsmith (where the password is welcome1) enter the following: JAMES Remote Administration Tool 2.3.0 Please enter your login and password Login id: root Password: root Welcome root. HELP for a list of commands adduser bpel welcome1 User bpel added adduser jsmith welcome1 User jsmith added listusers Existing accounts 2 user: bpel user: jsmith quit