Wednesday, July 7, 2010

Setting up email notifications for AIA 2.0

Here, I quickly describe how to set up the system to allow for email notifications upon AIA errors. This is not an exhaustive overview of AIA Error Handling.
1. Configure outgoing emailEdit $ORACLE_HOME/bpel/system/services/config/ns_emails.xml and configure the following:
<EmailAccount>
  <Name>AIA Error Handler</Name>
  <GeneralSettings>
    <FromName>AIA Error Handler</FromName>
    <FromAddress>do-not-reply@thisisahmed.com</FromAddress>
  </GeneralSettings>
  <OutgoingServerSettings>
    <SMTPHost>yourmailserver</SMTPHost>
    <SMTPPort>25</SMTPPort>
  </OutgoingServerSettings>
</EmailAccount>
Also ensure that NotificationMode="EMAIL" is set in the same file.

2. Set the AIA Error Handler role
Ensure that the AIA Error Handler defaults to the ‘AIAIntegrationAdmin’ role.
Edit $AIA_HOME/config/AIAConfigurationProperties.xml and ensure the following is set:
<ModuleConfiguration moduleName="ErrorHandler">
  .
  .
  .
  <Property name="EH.DEFAULT.ACTOR.ROLE">AIAIntegrationAdmin</Property>
  .
  .
  .
</ModuleConfiguration>
3. Create user account
a. Log in to Enterprise Manager (http://host:7777/em)
b. Click on “oc4j_soa”
c. Click on “Administration”
d. Click on “Security Providers”
e. Click on “Instance Level Security”
f. Click on “Realms”
g. Click on the number below ‘Users’
h. Click on “Create”
i. Enter username, password, and select ‘AIAIntegrationAdmin’ as the role
j. Click on “OK”

* The JAZN user information created above is stored in $ORACLE_HOME/j2ee/oc4j_soa/config/system-jazn-data.xml.
4. Set property for BPM user
Edit $ORACLE_HOME/bpel/system/services/config/users-properties.xml and add a new UserObject as follows:
<userObject>
  <name>Ahmed Aboulnaga</name>
  <description>Ahmed Aboulnaga</description>
  <email>ahmed.aboulnaga@somerandomsite.info</email>
  <title>AIAIntegrationAdmin</title>
  <firstName>Ahmed</firstName>
  <lastName>Aboulnaga</lastName>
  <timeZone>America/New_York</timeZone>
  <languagePreference>en-US</languagePreference>
  <notificationPreferences>Mail</notificationPreferences>
</userObject>
Logging in to the BPM Worklist
a. Navigate to BPM Worklist (http://host:7777/integration/worklistapp/Login)
b. Enter username and password


Searching for assigned tasks
a. Click on “My Tasks”
b. Search for ‘My & Group’, ‘Any’, and ‘Assigned’


Claiming, reviewing, and closing tasks
a. Select the action “Claim” and click on “Go”
b. Review the error. Note the following at minimum:

Reporting Date Time         <-- Timestamp
Fault Message Text           <-- Error
Faulting Service ID            <-- BPEL process name
Faulting Servicenstance ID <-- BPEL instance ID
You may optionally log in to the BPEL Console to do further troubleshooting/analysis of the issue.
c. Select the task action “COMPLETED” and click on “Go”    <-- if you want to close the task
Querying the AIA_ERROR_TOPIC from the database
The SQL query is as follows:
SELECT q_name, enq_uid, msgid, expiration, enq_time, a.user_data.text_len, a.user_data.text_vc
FROM aia_error_topic_table a
SYS.AQ$_JMS_TEXT_MESSAGE has the following for data types:
  • header        AQ$_JMS_HEADER
  • text_len      INT
  • text_vc        VARCHAR2(4000)
  • text_lob      CLOB
 This has been tested on a rather older version of AIA 2.0.

5 comments:

Anonymous said...

Hi Ahmed ,

Thanks for your note. I have some questions here.

step2)
==> NotificationMode="EMAIL"
Question 1) where should I add this ? can you give the "property" name and it's "attributes" ?

step3)
===> Enter username, password, and select ‘AIAIntegrationAdmin’ as the role
Question 2) which is username/pwd ?

step4)
===> Edit $ORACLE_HOME/bpel/system/services/config/users-properties.xml and add a new UserObject as follows:
Question 3) user object for which user shd be created ? which user details ?

===> Logging in to the BPM Worklist
Question 4) login as which user ? oc4jadmin ?!!

Regards,
Prem

Ahmed Aboulnaga said...

Hello Prem,

Answer 1) The last sentence in this section was incorrect. It should have been included as the last sentence in Step 1. I have fixed the blog post.

But basically, edit $ORACLE_HOME/bpel/system/services/config/ns_emails.xml and locate the following:

<EmailAccounts xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"
EmailMimeCharset=""
NotificationMode="NONE">

Change the value of "NONE" to "EMAIL".

Answer 2) This is your new BPM Worklist account. So just specify a new username and password.

Answer 3) These are the attributes for the user just created in Step 3. The <name> element should match the username created in Step 3. Make sure that the <email> element contains a valid email address, and make sure that <notificationPreferences> is set to "Mail".

Answer 4) Log in as the username created in Step 3.

Veeresh said...

Hi,

When you call AIA error notification process from BPEL, In Worklist this message always set to Assigned state for that user.
How to send the error message status as Suspended/Alerted state to worklist from AIA.
Please help on this.

Ahmed said...

Hello Veeresh,

Unfortunately, I currently don't have access to an environment where I can to figure this out. I might need a few weeks to set one up. Sorry!

Mood said...

Hi Ahmed, how about that AIA environment?
Thanks!