How to Schedule a Report with BI Publisher Web Service?

This is part of the BI Publisher Web Service series. I have already covered ‘How to use BI Publisher Web Service with JDeveloper 11G’ and ‘How to Run a Report with BI Publisher Web Service’. If you haven’t checked the posts and are interested in please click the above links to check.

Today, I’m going to talk about how to schedule a BI Publisher report with the Web Service within a Java application.

Which Method to Schedule Report?

So which method we can use to schedule ? It’s like the ones for running a report, there are two methods. One is ‘scheduleReport() and another is ‘scheduleReportInSession()’. ‘scheduleReport() takes a username and password while scheduleReportInSession takes a session token along with a ‘ScheduleRequest’ object. And both returns a job id, which you can use to monitor and manage the scheduled job later.

Definition:

• String scheduleReport(ScheduleRequest srequest, String username, String password)
• String scheduleReport(ScheduleRequest srequest, String SessionToken)

With those methods you can do pretty much the same things you can do from the UI. I’m going to use scheduleReport() method for my example below.

 

How to Call scheduleReportInSession()

Before you run the scheduleReportInSession() method, first you need to create a ReportRequest object by giving a report path for the report you want to run. This is exactly the same step I mentioned in the last post with runReportInSession().

Second, you need to create a DeliveryRequest object if you need to deliver the report. You can set a delivery option and its delivery type specific information here.

Third, now you need to create a ScheduleRequest object by setting the ReportRequest and DeliveryRequest objects.

And finally you can call the scheduleReportInSession() method to schedule a report.

Here is a list of those four steps:

1. Create DeliveryRequest object
2. Create ReportRequest object
3. Create ScheduleRequest object
4. Call scheduleReportInSession() method

So, let’s take a look at the each step.

 

Create DeliveryRequest Object

1) Create Delivery Option to Set Delivery Information

First you need to create a DeliveryOption object. There are different types of the objects, each of which is for each delivery type. So if you want to deliver your report by email then there is a one DeliveryOption for Email called ‘EmailDeliveryOption’. And it goes the same for other delivery options. Here is a list of the delivery options available for you with BI Publisher.

• Email
• Fax
• FTP
• Local File System
• Printer
• WebDAV

And all the options are available with the Web Service. When you create the DeliveryOption you can set each of the delivery option specific information. For example, if you want to use the email delivery option then you can set the email delivery related information such as an email subject,  an email address shown as ‘from’ or ‘cc’, etc.

Here is a list of the DeliveryOption types and a list of methods that you can use to set the delivery related information.

EmailDeliveryOption

Method	Description
void setEmailTo(String)	You can set a To Email address.
void setEmailSubject(String)	You can set a Email subject.
void setEmailFrom(String)	You can set a Email From address.
void setEmailCC(String)	You can set a CC Email Address.
void setEmailBody(String)	You can set a Email body message.

FaxDeliveryOption

Method	Description
void setFaxNumber(String)	You can set a fax number.
void setFaxServer(String)	You can set a fax server name which is the one that has already been registered at your BI Publisher Server.

Printer

Method	Description
void setPrinterName(String)	You can set a Printer name that has already been registered at your BI Publisher server environment.
void setPrintNumberOfCopy (String)	You can set a number of copy that you want to print the report in.
void setPrintRange(String)	You can set a range of pages of the report that you want to print.
void setPrintSide(String)	You can set both sides printing.
void setPrintTray(String)	You can specify which printer tray you want to use for your printing.

FTP

Method	Description
void setFtpServerName (String)	You can set a FTP server name that has already been registered at your BI Publisher server.
void setFtpUserName(String)	You can set a username for the FTP server.
void setFtpUserPassword (String)	You can set a password for the FTP server.
void setRemoteFile(String)	You can set a file name for the report output.
void setSftpOption(String)	You can set SFTP option.

Local File System

Method	Description
void setDestination(String)	You can set a full path for the report output including the report output file name so that the report can be saved on the specified location on the server’s file system.

WebDAV

Method	Description
void setServer (String)	You can set a WebDAV server name that is registered at your BI Publisher server.
void setRemoteFilePath (String)	You can set a file name for the report output and the path.
void setUserName (String)	You can set a username for the WebDAV server.
void setPassword (String)	You can set a password for the WebDAV server.
void setDeliveryAuthType (String)	You can set an authentication type of the WebDAV server.
void setDeliveryAuthTypeBasic (String)	You can set Basic authentication type.
void setDeliveryAuthTypeDigest (String)	You can set Digest authentication type.

Note that you need to setup the delivery servers appropriately from your BI Publisher Server UI before you use the delivery options with the Web Service. For example, if you want to use the Email delivery option then you need to setup a default Email server from the UI. Only the delivery options configured appropriately at the server can be used from the Web Service.

Example:

//Create a Delivery Option for Email delivery EMailDeliveryOption em = new EMailDeliveryOption(); //Set Email delivery related information em.setEmailTo("kanichiro.nishida@oracle.com"); em.setEmailSubject("This is a BIP Web Service Test..."); em.setEmailFrom("bip_admin@oracle.com"); em.setEmailCC("kanaugust@gmail.com"); em.setEmailBody("Test");

 

2) Create Delivery Request

Once you have created the DeliveryOption then you can create a DeliveryRequest object by passing the DeliveryOption object.

Here is a list of the methods that you can use to set the DeliveryOption to create a DeliveryRequest.

• void setEmailOption (EMailDeliveryOption)
• void setFaxOption (FaxDeliveryOption)
• void setPrintOption (PrintDeliveryOption)
• void setFTPOption (FTPDeliveryOption)
• void setLocalOption (LocalDeliveryOption)
• void setWebDAVOption (WebDAVDeliveryOption)

Example:

DeliveryRequest dr = new DeliveryRequest(); dr.setEmailOption(em);

 

Create ReportRequest Object

This is exactly the same process as I talked at the last post. So take a look at the post if you don’t know how to create the ReportRequest object.

Create ScheduleRequest Object

When you create the ScheduleRequest object you can set a report to schedule and the delivery information by setting the above mentioned two objects, DeliveryRequest and ReportRequest.

Also, you can set the following information to the ScheduleRequest object.

• Email Address for Notification
• Indication of Saving the Data
• Indication of Saving the Report Output
• Repeat Count
• Repeat Interval
• Start Date for the Scheduling
• End Date for the Scheduling
• Calendar for Scheduling
• Time Zone for Scheduled Time
• Job Name
• Delivery Request
• Report Request
• Indication of Public Scheduling
• Bursting Delivery

If you don’t set the Start Date then it would be the same as ‘immediately run’ option.

And here is a list of the methods that you can use to set such options.

Function	Method	Description
Report Request	void setReportRequest (ReportRequest)	You can set a ReportRequest object to select a report that you want to schedule and run.
Delivery Request	void setDeliveryRequest (DeliveryRequest)	You can set a DeliveryRequest object to set a delivery option. See ‘Pre-Requisite for Delivery’ section for the detail of how to set the delivery settings.
Start Date for the Scheduling	void setStartDate(Calendar)	You can set a start date for the scheduling to start. If it’s null or not specified then the scheduled job will run immediately.
End Date for the Scheduling	void setEndDate(Calendar)	You can set an end date for the scheduling.
Job Name	void setUserJobName(String)	You can set a name for this scheduling job.
Calendar	void setJobCalendar(Calendar)	You can set which calendar to use for the scheduling time. E.g. Gregorian
Time Zone	void setJobTZ(String)	You can set an appropriate time zone that you want to use for the specified time for the scheduling.
Repeat Count	void setRepeatCount(int)	You can set a repeat count for the scheduled job.
Repeat Interval	void setRepeatInterval(int)	You can set an interval time for the scheduled job to run.
Email Address for Notification	void setNotificationTo(String)	You can set an email address to send a notification of the scheduled job.
Request to send a notification message when failed	void setNotificationWhenFailed (boolean)	You can specify whether you want to send a notification message when the scheduled job fails or not.
Request to send a notification message when Success	void setNotificationWhenSuccess (boolean)	You can specify whether you want to send a notification message when the scheduled job runs successfully or not.
Request to send a notification message when Warning	void setNotificationWhenWarning (boolean)	You can specify whether you want to send a notification message when the scheduled job ends with warning or not.
Indication of Saving the Data	void setSaveDataOption(boolean)	You can specify whether you want to save the data for the scheduled job or not. The data will be saved when it’s set True and it can be accessed only through BI Publisher Enterprise UI.
Indication of Saving the Report Output	void setSaveOutputOption(boolean)	You can specify whether you want to save the report output for the scheduled job or not. The output will be saved when it’s set True and it can be accessed only through BI Publisher Enterprise UI.
Indication of Public Scheduling	void setSchedulePublicOption (boolean)	You can specify whether you want to make the scheduled job to be publicly accessible or not.
Bursting Delivery	void setScheduleBurstringOption (boolean)	You can specify whether you want to use the bursting option that is pre-configured for this report or not. In order to use this option you need to make sure that the report you’re scheduling has been configured for the bursting option through BI Publisher Enterprise UI.

Example:

ScheduleRequest sreq = new ScheduleRequest(); //Set DeliveryRequest sreq.setDeliveryRequest(dr); //Set ReportRequest sreq.setReportRequest(req); //Set scheduling information sreq.setNotificationTo("kanichiro.nishida@oracle.com"); sreq.setSaveDataOption(true); sreq.setSaveOutputOption(true); sreq.setScheduleBurstringOption(false); sreq.setSchedulePublicOption(true); sreq.setUserJobName("WebService Job1");

 

Call scheduleReportInSession()

Now you can set the ScheduleRequest and the session token to run the scheduleReprotInSession() method. It returns a job id when it runs successfully, which you can use to monitor and manage the job. For example, in future when you need to suspend or delete the job then you will need this job id to do such.

Example:

job_id = publicReportService.scheduleReportInSession(sreq, sid);

And that’s it! Once you run the scheduleReportInSession() successfully then you should see a new job created from the BI Publisher’s scheduler UI page.

There are more BI Publisher WebService APIs available, but these I’ve covered are the most common. If you have some other APIs that you want me to cover let me know, I can talk about that too.

Here is my whole source code for this scheduling exercise.

package project1; import com.oracle.xmlns.oxp.service.publicreportservice.AccessDeniedException; import com.oracle.xmlns.oxp.service.publicreportservice.AccessDeniedException_Exception; import com.oracle.xmlns.oxp.service.publicreportservice.DeliveryRequest; import com.oracle.xmlns.oxp.service.publicreportservice.EMailDeliveryOption; import com.oracle.xmlns.oxp.service.publicreportservice.InvalidParametersException; import com.oracle.xmlns.oxp.service.publicreportservice.InvalidParametersException_Exception; import com.oracle.xmlns.oxp.service.publicreportservice.LocalDeliveryOption; import com.oracle.xmlns.oxp.service.publicreportservice.OperationFailedException; import com.oracle.xmlns.oxp.service.publicreportservice.OperationFailedException_Exception; import com.oracle.xmlns.oxp.service.publicreportservice.PublicReportService; import com.oracle.xmlns.oxp.service.publicreportservice.PublicReportServiceClient; import com.oracle.xmlns.oxp.service.publicreportservice.PublicReportServiceService; import com.oracle.xmlns.oxp.service.publicreportservice.ReportRequest; import com.oracle.xmlns.oxp.service.publicreportservice.ReportResponse; import com.oracle.xmlns.oxp.service.publicreportservice.ScheduleRequest; import java.io.IOException; import java.io.OutputStream; import java.io.PrintWriter; import java.net.URL; import java.util.Calendar; import java.util.Date; import java.util.GregorianCalendar; import javax.servlet.*; import javax.servlet.http.*; import javax.xml.datatype.DatatypeConfigurationException; import javax.xml.datatype.DatatypeFactory; import javax.xml.datatype.XMLGregorianCalendar; import javax.xml.namespace.QName; public class BipServletTest extends HttpServlet {     private static final String CONTENT_TYPE =         "text/html; charset=windows-1252";     private static PublicReportServiceService publicReportServiceService;     public void init(ServletConfig config) throws ServletException {         super.init(config);     }     public void doGet(HttpServletRequest request,                       HttpServletResponse response) throws ServletException,                                                            IOException {         response.setContentType(CONTENT_TYPE);         OutputStream os = response.getOutputStream();         //PrintWriter out = response.getWriter();         String sid = "";         publicReportServiceService = new PublicReportServiceService(new URL("http://knishida-lap.us.oracle.com:7001/xmlpserver/services/PublicReportService"),                                                new QName("http://xmlns.oracle.com/oxp/service/PublicReportService",                                                          "PublicReportServiceService"));         PublicReportService publicReportService =             publicReportServiceService.getPublicReportService();         //To get a session id        try {             sid = this.getSessionID("Administrator", "Administrator", publicReportService);         } catch (AccessDeniedException_Exception e) {             System.out.println("invalid user");          }        String job_id = this.scheduleReportInSession(publicReportService, sid);         try {             publicReportService.logout(sid);         } catch (InvalidParametersException_Exception e) {             System.out.println(e);         } catch (AccessDeniedException_Exception e) {             System.out.println(e);         }     } public String getSessionID(String username, String password, PublicReportService publicReportService) throws AccessDeniedException_Exception {     String sid = publicReportService.login(username, password);     return sid; } public String scheduleReportInSession(PublicReportService publicReportService,                                     String sid){     // Set Report request attributes     ReportRequest req = new ReportRequest();     req.setAttributeFormat("pdf");     req.setAttributeLocale("en-US");     req.setAttributeTemplate("Simple");     req.setReportAbsolutePath("/HR Manager/Employee Salary Report/Employee Salary Report.xdo");     EMailDeliveryOption em = new EMailDeliveryOption();     em.setEmailTo("kanichiro.nishida@oracle.com");     em.setEmailSubject("This is a BIP Web Service Test...");     em.setEmailFrom("bip_admin@oracle.com");     em.setEmailCC("kanaugust@gmail.com");     em.setEmailBody("Test");     DeliveryRequest dr = new DeliveryRequest();     dr.setEmailOption(em);     ScheduleRequest sreq = new ScheduleRequest();     //Set DeliveryRequest     sreq.setDeliveryRequest(dr);     //Set ReportRequest     sreq.setReportRequest(req);     sreq.setNotificationTo(kanichiro.nishida@oracle.com);     sreq.setSaveDataOption(true);     sreq.setSaveOutputOption(true);     sreq.setScheduleBurstringOption(false);     sreq.setSchedulePublicOption(true);     sreq.setUserJobName("WebService Job1");     String job_id ="";     try {         job_id = publicReportService.scheduleReportInSession(sreq, sid);         System.out.println(job_id);     } catch (InvalidParametersException_Exception ie) {         System.out.println(ie);     } catch (AccessDeniedException_Exception ae) {         System.out.println(ae);     } catch (OperationFailedException_Exception oe) {         System.out.println(oe);     }      return job_id; } }