3. Integration

3.1. Building the Notification class

To compile your Notification class, you need to have the rwrun.jar in your classpath. The rwrun.jar file is in the $ORACLE_HOME/reports/jlib directory. If you are using Oracle9i JDeveloper (Oracle9iDS) just add the Reports Runtime library to your project

The complete mail notification example used in this tutorial is avaibable in the resources section.

3.2. Deploying the classes on your server

To deploy the notification classes on your server, you can either:

• Deploy Java classes
• Deploy a JAR file.

3.2.1. Deploy Java Classes

If you are running a Reports Server version 9.0.2.0.4 or lower, you should:

1. Create a classes directory in your $ORACLE_HOME/reports/ directory
2. Copy your classes to this new directory ($ORACLE_HOME/reports/classes)

If you are running a Reports Server version 9.0.2.0.5 or higher, you should copy your classes to the $ORACLE_HOME/reports/jlib/classes directory.

3.2.2. Deploy a JAR file

If you packaged your classes in a JAR file, you need to manually modify the class path to point to the JAR file.

The Java class plath of your Report Server depends on the way that you use the server : In-Process or Stand-Alone. You can find more information in chapter Specifying an In-Process Server of Publishing Reports to the Web Using Oracle9iAS Reports Services manual.

The In-Process server configuration is the default. The In-Process server enables faster response time since, it reduces the communication expense between processes and consequently increases response times. In this context, the Reports Server starts automatically, whenever it receives the first request from the client via the Reports Servlet (rwservlet) or a Reports JSP.

If you configure the server as a Stand-Alone server you should start it manually with the rwserver command line. In this context Reports Server and the application server processes are independent. You can use this configuration when debugging your reports extension, stopping and starting the Reports Server without any effect on your application server.

If you are using the "In-Process" server (the class path used by Oracle9i Reports is the OC4J path).

1. Copy the JAR file in a directory, often we use the $ORACLE_HOME/reports/jlib directory to store Oracle9i Reports related JAR files.
2. Open the OC4J configuration file $ORACLE_HOME/j2ee/<instance_name>/config/server.xml. The <instance_name> represents the name of the OC4J where the reports are executing, by default in Oracle9iDS the instance is Oracle9iDS and in Oracle9iAS it is OC4J_BI_Form
3. Add the JAR file to the class path using this XML entry, for example if you put the JAR file under $ORACLE_HOME/reports/jlib directory
   <library path="../../../reports/jlib/MailNotification.jar" />
   

If you are using the "Stand-Alone" server:

1. Copy the JAR file to the $ORACLE_HOME/reports/jlib directory
2. Add file address $ORACLE_HOME/reports/jlib/MailNotification.jar to the REPORTS_CLASSPATH environment variable. On Windows the REPORTS_CLASSPATH is in the registry. On unix you can modify the REPORTS_CLASSPATH in the $ORACLE_HOME/bin/reports.sh file.

 3.3. Registering the new notification

To register the new notification, new XML entry for the notification plug-in in the Reports Server configuration file.

Open the Reports Server configuration file ($ORACLE_HOME/reports/conf/rep_<your server>.conf), and add a new XML entry.

For example, in the mail notification example, the entry looks like this:

	
   <notification id="mailNotifyExample" class="oracle.reports.plugin.notification.mail.PluginMailNotification">
      <property name="mailServer" value="smtp.mycompany.com"/>
      <property name="reportServer" value="mailnote"/>
      <property name="successMailPriority" value="high"/>
      <property name="failureMailPriority" value="high"/>
      <property name="successNote" value="succnote.txt"/>
      <property name="failureNote" value="failnote.txt"/>
      <property name="successRecipients" value="john.doe@company.com"/>
      <property name="failureRecipients" value="john.doe@company.com,administrator@company.com"/>          
  </notification>

The notification tag has two attributes:

• id contains the complete class name of the main public class of your Notification.
• class  contains the complete class name of the notification.
  

If your notification needs some specific parameters you can use the property tag to create name-value pairs. The parameters used by the mail notification are:

• mailServer: name of the outgoing mail that you want to use to send the notification
• reportServer: name of the your report server (use as sender address)
• successMailPriority: priority of the mail sent when a job is finished with success
• failureMailPriority: priority of the mail sent when a job is finished with failure
• successNote: name of file that contains the success notification message, by default this file is in $ORACLE_HOME/reports/templates directory. If you want to put the message file in another directory you need to add this directory to the REPORTS_PATH environment variable. You can create your own message file using the proper syntax, see next section.
• failureNote: name of file that contains the failure notification message, by default this file is in $ORACLE_HOME/reports/tesmplates directory. If you want to put the message file in another directory you need to add this directory to the REPORTS_PATH environment variable. You can create your own message file using the proper syntax, see next section.
• successRecipients: list of the email addresses, separated by comma, notified in case of success
• failureRecipients: list of the email addresses, separated by comma, notified in case of failure

Create a message file for the notification

You can create your own message file and use it in the successNote or failureNote parameter. A sample content for the message could be:

The Job &jobname on Report Server &servername has successfully finished at &timefinished.

You can use lexical references to customize the message. The list of the property that you can reference using & as prefix are:

• jobname : contains the jobId
• servername : contains the name of the report server
• timefinished : contains the time of the job termination
• errorstring : contains the error message in case of job failure.
  

 3.4. Using your new notification

Now your new mail notification is deployed and registered with your Reports Server. The Reports Server call the notify method of each registered notification after a job execution. You can override the properties mentioned in the configuration file during a job execution by sending the value using command line or URL parameters. You would then use these parameters in the notify method. Notification are supported for rwservlet, rwclient and jsp engine report. The rwrun command line tool does not support custom parameters, but use the configuration file properties.

The mail notification sample can receive parameter from the command line for example:

http://server:port/reports/rwservlet?module=myReports.rdf&desformat=PDF&destype=cache&userid=scott/tiger@mydb&successRecipients=john.doe@mycompany.com

The mail notification sample supports as parameter:

• successRecipients: list of the different recipients, comma as separator, when a job is finished with success
• successMailPriority: priority of the mail when a job finished with success. Possible values are highest, hight, normal, low, lowest.
• failureRecipients: list of the different recipients, comma as separator, when a job is finished with failure
• failureMailPriority: priority of the mail when a job finished with failure. Possible values are highest, hight, normal, low, lowest.

With the URL specify above the Mail notification class will sent a mail to the address specified in the successRecipients parameter.