Oracle BI Publisher Blog

Carrying on from where we left off yesterday in ths series of articles on the XMLP delivery manager, today we'll take a look at the APIs themselves and how you can use ... we're not going to touch EBS yet, just get some basics around the APIs. Before we start, arm yourself with the following documents:

XML Publisher Users Guide incl Developers Guide
XML Publisher release 5.6.1 Core Components API (javadoc)

Overview
The basic flow to deliver documents is as follows:

1. Create DeliveryManager instance
   
2. Create DeliveryRequest instance by createRequest() method
   
3. Add request properties such as where to send to the DeliveryRequest. Most of properties require a string value. Take a look at the supported properties of each delivery channel for more detail.
   
4. Set your document to the DeliveryRequest
   
5. Call submit() to submit the delivery request.

One delivery request can handle one document and one destination. This is because it makes simple and easy to track down each delivery status and re-submit the request if it failed to deliver.

The DeliveryRequest allows you to set the documents in two ways, these are;

• Getting OutputStream from the DeliveryReqeust and writing the document to the OutputStream. You don't need to close the OutputStream, but you can just call submit() method right after you finish writing the document to the OutputStream.-->
  
• Setting InputStream of the document to the DeliverRequest. The DeliveryRequest will read the InputStream when you call submit() for the first time. The DeliveryRequest doesn't close the InputStream so you need to take care of closing it.
  
• Setting the file name of the document to the DeliveryRequest. The DeliveryRequest will pick up the document from the file system when you call submit().

Those are the basic steps you need to follow, how about in practice?

EMail
With all of the delivery channels its a case of setting the required properties and then calling the apprpriate API. 

create delivery manager instance
   DeliveryManager dm = new DeliveryManager();
   // create a delivery request
   DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_SMTP_EMAIL);
   // set email subject
   req.addProperty(DeliveryPropertyDefinitions.SMTP_SUBJECT, "Invoice");
   // set SMTP server host
   req.addProperty(
     DeliveryPropertyDefinitions.SMTP_HOST, "mysmtphost");
   // set the sender email address
   req.addProperty(DeliveryPropertyDefinitions.SMTP_FROM, "myname@mydomain.com");
   // set the destination email address
   req.addProperty(
     DeliveryPropertyDefinitions.SMTP_TO_RECIPIENTS, "user1@mydomain.com, user2@mydomain.com" );
   // set the content type of the email body
   req.addProperty(DeliveryPropertyDefinitions.SMTP_CONTENT_TYPE, "application/pdf");
   // set the document file name appeared in the email
   req.addProperty(DeliveryPropertyDefinitions.SMTP_CONTENT_FILENAME, "invoice.pdf");
   // set the document to deliver
   req.setDocument("/document/invoice.pdf");
    // submit the request
   req.submit();
   // close the request
   req.close();

Simple stuff right?

This was just a simple example, you have complete control over the email and its attachments, there are more examples in the developer guide and the javadocs for the APIs.

FAX
The Delivery API supports the delivery of documents to fax modems configured on CUPS using the Internet Printing Protocol. XMLP uses a CUPS instance on Linux or UNIX to act as the delivery server. Its straightforward to set up, check the developers guide for instructions.
You can configure the fax modems on CUPS with efax and FAX4CUPS. By the default setting, CUPS can fax the document in Postscript and PDF document formats.  We have not done much research on Fax over a Windows Server, there are commercial software packages that can use the IPP. Another alternative is to use one of the many Fax over Email solutions out there, we have several customers using it very sucessfully.

Sample FAXing code 

// create delivery manager instance 
DeliveryManager dm = new DeliveryManager();
// create a delivery request 
DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_IPP_FAX);
// set IPP fax host 
req.addProperty(DeliveryPropertyDefinitions.IPP_HOST, "myhost");
// set IPP fax port 
req.addProperty(DeliveryPropertyDefinitions.IPP_PORT, "631");
// set IPP fax name 
req.addProperty(DeliveryPropertyDefinitions.IPP_PRINTER_NAME, "/printers/myfax");
// set the document format 
req.addProperty(DeliveryPropertyDefinitions.IPP_DOCUMENT_FORMAT, "application/postscript");
// set the phone number to send 
req.addProperty(DeliveryPropertyDefinitions.IPP_PHONE_NUMBER, "9999999");
// set the document 
req.setDocument("/document/invoice.pdf");
// submit the request 
req.submit(); 
// close the request 
req.close();

WebDAV
This delivery channel can direct your documents to any repository that supports the WebDAV protocol, whether that be Oracle Files Online, XDB or a third party solution. The document can be pushed into a directory on the repository as an archive or into a personal folder for viewing later by the recipient.
Again, its a simple case of setting properties and then calling the APIs submit method:

   // create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_WEBDAV);
      // set document content type
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_CONTENT_TYPE, "application/pdf");
     // set the WebDAV server hostname
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_HOST, "mywebdavhost");
     // set the WebDAV server port number
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_PORT, "80");
     // set the target remote directory
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_REMOTE_DIRECTORY, "/content/");
     // set the remote filename
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_REMOTE_FILENAME, "xdotest.pdf");
     // set username and password to access WebDAV server
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_USERNAME, "xdo");
     req.addProperty(DeliveryPropertyDefinitions.WEBDAV_PASSWORD, "xdo");
     // set the document
     req.setDocument("/document/test.pdf");
      // submit the request
     req.submit();
     // close the request
     req.close();

FTP
Another protocol that is very widely used to move files to specific locations for a daemon to recognize and have picked up by another process.

     // create delivery manager instance
     DeliveryManager dm = new DeliveryManager();
     // create a delivery request
     DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_FTP);
 
     // set hostname of the FTP server
     req.addProperty(DeliveryPropertyDefinitions.FTP_HOST, "myftphost");
     // set port# of the FTP server
     req.addProperty(DeliveryPropertyDefinitions.FTP_PORT, "21");
     // set username and password to access WebDAV server
     req.addProperty(DeliveryPropertyDefinitions.FTP_USERNAME, "xdo");
     req.addProperty(DeliveryPropertyDefinitions.FTP_PASSWORD, "xdo");
     // set the remote directory that you want to send your document to
     req.addProperty(DeliveryPropertyDefinitions.FTP_REMOTE_DIRECTORY, "pub");
     // set the remote file name 
     req.addProperty(DeliveryPropertyDefinitions.FTP_REMOTE_FILENAME, "test.pdf");
     // set the document
     req.setDocument("/document/test.pdf");
 
     // submit the request
     req.submit();
     // close the request
     req.close();

HTTP
Finally, HTTP ... The Delivery API supports to deliver documents to the HTTP servers. The following sample is sending a document through HTTP POST method. Technically, you can send not only documents, but also anything you want. But the servers should be capable to accept your custom HTTP requests in advance, such as your custom Servlet or CGI program.

 // create delivery manager instance 
 DeliveryManager dm = new DeliveryManager();
 // create a delivery request
 DeliveryRequest req = dm.createRequest(DeliveryManager.TYPE_HTTP);
 // set request method
 req.addProperty(DeliveryPropertyDefinitions.HTTP_METHOD, DeliveryPropertyDefinitions.HTTP_METHOD_POST);
 // set document content type
 req.addProperty(DeliveryPropertyDefinitions.HTTP_CONTENT_TYPE, "application/pdf");
 // set the HTTP server hostname
 req.addProperty(DeliveryPropertyDefinitions.HTTP_HOST, "myhost");
 // set the HTTP server port number
 req.addProperty(DeliveryPropertyDefinitions.HTTP_PORT, "80");
 // set the target remote directory
 req.addProperty(DeliveryPropertyDefinitions.HTTP_REMOTE_DIRECTORY, "/servlet/");
 // set the remote filename (servlet class)
 req.addProperty(DeliveryPropertyDefinitions.HTTP_REMOTE_FILENAME, "uploadDocument");
 // set the document
 req.setDocument("/document/test.pdf");
 // submit the request 
 req.submit();
 // close the request
 req.close(); 

So thats the APIs and brief introduction to their use, some of you will have noticed a glaring exception to the list ... where the printing APIs?

They are present and use the IPP much like the fax. They are in my opinion superior to the current concurrent manager printing abilities but, I suspect that many of you have already been through the fun and games (NOT!) that is printer setup in Apps and have got them working ... it might not be quitre what you users want in the age of tray switching and duplex printing but if it ain't broke dont fix it! For those that are interested I'll cover printing another time. The other delivery channel I'll cover later is the custom channel, many of you will have thrid parties delivery software that you would like to hook up to the XMLP flow (if they have not done it for you), the custom channel can help.

Next week ... how to get these APIs running in the EBS and delivering your docs for you.