Oracle BI Publisher Blog

Good news for all EBS BI Publisher enthusiasts! Now you can deliver faxes directly from the BI Publisher Delivery
Manager to any fax destination through RightFax 9.3 or above. To learn more about RightFax you can visit their
website - http://www.captaris.com/rightfax.

Oracle Collections team has implemented BI Publisher - RightFax integration for Strategy Dunning Program. You can find the details of this implementation and patch download option in metalink (patch details at the end).

BI Publisher Delivery Manager can now make use of RightFax XML interface to submit a fax job and to query the
status of the job. These XML requests and responses are transmitted over HTTP/S. RightFax can convert the XML request into FCL (Facsimile Command Language) on the server side. So we do not have to worry about embedding FCL code on client (BI Publisher) side anymore. RightFax supports PDF, Postscript and PCL documents and may also support Microsoft Office documents depending on its Server configuration. The Delivery Manager supports a single fax destination per delivery request; therefore, to send fax to multiple destinations, you will have to submit multiple delivery jobs.

Here are the steps to set up the RightFax Delivery Channel in BI Publisher Delivery Manager

1. Create a Delivery Manager instance
2. Create a Delivery Request instance
3. Add the request properties
4. Set your document to the DeliveryRequest instance
5. Submit the delivery request

And here is a sample code.....

  // create delivery manager instance
  DeliveryManager  dm = new DeliveryManager();

  // create a delivery request
  DeliveryRequest  req = dm.createRequest(DeliveryManager.TYPE_RIGHTFAX);

  // required host information (hostname / IP address / reference name from config file)
  req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_HTTP_HOST,"myhost");

  // required sender information
  req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_SENDER_RFUSER,"Administrator");
  

  // Optional properties
  req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_SENDER_FROM_NAME,"Dave Taylor");
  req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_SENDER_FROM_COMPANY,"ABC, Ltd.");


  // required destination
  req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_FAX_TO_NUMBER,"555-1111");

  // Optional properties
  req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_FAX_TO_NAME,"Fred Flintstone");
  req.addProperty(DeliveryPropertyDefinitions.RIGHTFAX_FAX_TO_COMPANY,"Acme, Inc.");

  // set the document
  req.setDocument("/document/invoice.pdf");

  // submit the request
  req.submit();

  // close the request
  req.close();


Did you say what all RightFax Delivery Properties?
Ok, so here goes a long list of delivery properties supported for RightFax delivery 
channel. It shows the corresponding RightFax XML interface element for submitting a 
fax job. Here RIGHTFAX_HTTP_HOST, RIGHTFAX_SENDER_RFUSER, RIGHTFAX_FAX_TO_NUMBER
are the only required properties, rest are optional.



  

    
Delivery Property
    
Description
    
Rightfax XML
interface element
for submitting
a fax job
  
  

    
RIGHTFAX_HTTP_HOST
    
Required.
HTTP host of the RightFax server.
    
 
  
  

    
RIGHTFAX_HTTP_PORT
    
Optional.
HTTP port of the RightFax server.
Default=80.
    
 
  
  

    
RIGHTFAX_HTTP_REMOTE_DIRECTORY
    
Optional.
Enter the remote directory name.
Default value is “/rfxml”.
    
 
  
  

    
RIGHTFAX_HTTP_REMOTE_FILENAME
    
Optional.
Enter the remote filename.
Default is “/RFWebCon.dll".
    
 
  
  

    
RIGHTFAX_HTTP_AUTHTYPE
    
Optional.
HTTP authentication type of the 
RightFax server url. Valid values are
RIGHTFAX_HTTP_AUTHTYPE_NONE,
RIGHTFAX_HTTP_AUTHTYPE_BASIC,
RIGHTFAX_HTTP_AUTHTYPE_DIGEST.
Default value is
RIGHTFAX_AUTHTYPE_NONE.
    
 
  
  

    
RIGHTFAX_HTTP_USERNAME
    
Optional.
HTTP username for the RightFax
server url. Required when
RIGHTFAX_HTTP_AUTH_TYPE is set to
values other than
RIGHTFAX_HTTP_AUTHTYPE_NONE.
    
 
  
  

    
RIGHTFAX_HTTP_PASSWORD
    
Optional.
HTTP password for the RightFax server
url. Required when
RIGHTFAX_HTTP_AUTH_TYPE is set to
values other than
RIGHTFAX_HTTP_AUTHTYPE_NONE.
    
 
  
  

    
RIGHTFAX_HTTP_ENCTYPE
    
Optional.
The encryption type can be set to
either of the following:
RIGHTFAX_HTTP_ENCTYPE_NONE
– no encryption (default)
RIGHTFAX_HTTP_ENCTYPE_SSL
– use Secure Socket Layer
    
 
  
  

    
RIGHTFAX_HTTP_USE_FULL_URL
    
Optional.
Set to “true” to send the full URL
for the HTTP request header. Valid
values are “true” or “false” (default).
    
 
  
  

    
RIGHTFAX_HTTP_TIMEOUT
    
Optional.
Enter a length of time in milli-
seconds after which to terminate the
request if a connection is not made
to the HTTP server.
The default is 60000 (1 minute).
    
 
  
  

    
RIGHTFAX_HTTP_PROXY_HOST
    
Optional.
Enter the proxy server host name.
    
 
  
  

    
RIGHTFAX_HTTP_PROXY_PORT
    
Optional.
Enter the proxy server port number.
Default=80.
    
 
  
  

    
RIGHTFAX_HTTP_PROXY_AUTHTYPE
    
Optional.
Valid value is either of the following.
RIGHTFAX_HTTP_PROXY_AUTHTYPE_NONE
– no authentication
RIGHTFAX_HTTP_PROXY_AUTHTYPE_BASIC
– Use HTTP basic authentication
RIGHTFAX_HTTP_PROXY_AUTHTYPE_DIGEST
– Use HTTP digest authentication.
    
 
  
  

    
RIGHTFAX_HTTP_PROXY_USERNAME
    
Optional.
Enter the username for proxy
authentication.
    
 
  
  

    
RIGHTFAX_HTTP_PROXY_PASSWORD
    
Optional.
Enter the password for HTTP proxy
authentication.
    
 
  
  

    
RIGHTFAX_SENDER_FROM_NAME
    
Optional.
Enter the name of the sender.
    
SENDER/FROM_NAME
  
  

    
RIGHTFAX_SENDER_EMPID
    
Optional.
Enter the employee id of the sender.
    
SENDER/EMP_ID
  
  

    
RIGHTFAX_SENDER_FROM_COMPANY
    
Optional.
Enter the name of the sender’s company.
    
SENDER/FROM_COMPANY
  
  

    
RIGHTFAX_SENDER_FROM_DEPARTMENT
    
Optional.
Enter the name of the sender’s
department.
    
SENDER/FROM_DEPARTMENT
  
  

    
RIGHTFAX_SENDER_FROM_PHONE
    
Optional.
Enter sender’s phone number.
    
SENDER/FROM_PHONE
  
  

    
RIGHTFAX_SENDER_RETURN_EMAIL
    
Optional.
Enter sender’s return email address.
    
SENDER/RETURN_EMAIL
  
  

    
RIGHTFAX_SENDER_BILLINFO1
    
Optional.
Enter the billing code of the fax
owner.
    
SENDER/BILLINFO1
  
  

    
RIGHTFAX_SENDER_BILLINFO2
    
Optional.
Enter the secondary billing code
of the fax owner.
    
SENDER/BILLINFO2
  
  

    
RIGHTFAX_SENDER_RFUSER
    
Required.
Enter the name of the sender’s
RightFax user name.
    
SENDER/RF_USER
  
  

    
RIGHTFAX_FAX_TO_NUMBER
    
Required.
Enter the fax number where the
document will be sent.
    
DESTINATIONS/FAX/TO_FAXNUM
  
  

    
RIGHTFAX_FAX_TO_NAME
    
Optional.
Enter the recipient’s name.
    
DESTINATIONS/FAX/TO_NAME
  
  

    
RIGHTFAX_FAX_TO_COMPANY
    
Optional.
Enter the recipient’s company name.
    
DESTINATIONS/FAX/TO_COMPANY
  
  

    
RIGHTFAX_FAX_TO_ALTNUMBER
    
Optional.
Enter the alternative fax number.
    
DESTINATIONS/FAX/ALT_FAX_
NUM
  
  

    
RIGHTFAX_FAX_TO_CONTACTNUMBER
    
Optional.
Enter the contact phone number of
the recipient.
    
DESTINATIONS/FAX/TO_
CONTACTNUM
  
  

    
RIGHTFAX_FAX_COVERSHEET
    
Optional.
Enter the coversheet template for
the current document. The file name
can be either a full path on the
RightFax server machine or a path
relative to RightFax\Production\Covers.
    
DESTINATIONS/FAX/COVERSHEET
  
  

    
RIGHTFAX_COVERTEXT
    
Optional.
Enter the text that should appear on
the coversheet.
    
COVERTEXT
  
  

    
RIGHTFAX_COVERTEXT_TYPE
    
Optional.
Enter the type of the coversheet
text. TXT (default) or RTF
    
COVERTEXT/type
  
  

    
RIGHTFAX_COVERTEXT_ENCODING
    
Optional.
Enter the encoding of the coversheet
text. NONE (default) BASE64
QUOTEDPRINTABLE
    
COVERTEXT/encoding
  
  

    
RIGHTFAX_CONTENT_TYPE
    
Optional.
Enter the MIME content type of 
the document. Default value
“application/octetstream”.
    
Set to Content-Type field
of file attachment.
  

Note: In addition to the above listed RightFax specific properties, all delivery manager
common properties, including BUFFERING_MODE (for document redelivery) and FILTER (for
document conversion), are supported.


You want to set the RightFax Server in a configuration file?
I am sure you already know that BI Publisher supports a delivery configuration file to
manage delivery servers, delivery properties and custom delivery channels. Now RightFax
server has been added to this list with server type as 'rightfax' 

  <server name="myhost" type=”rightfax”> 

This server type expects values for Host, port, uri, username, password, authType, 
encType, proxyPort, proxyUsername, proxyPassword, proxyAuthType, filter and
filterOutputContentType. 

Please check the BI Publisher ‘Administrator’s and Developer’s Guide’ to know more
about the delivery configuration file.

Sample Delivery Configuration file (xdodelivery.cfg) -


<?xml version='1.0' encoding='UTF-8'?>
<config  xmlns="http://xmlns.oracle.com/oxp/delivery/config">
  <!--   ========================================================  -->
  <!--     servers section                                         -->
  <!--     List your pre-defined servers here.                     -->
  <!--   ========================================================  -->
  <servers>
        <server  name="myhost" type="rightfax" default="true"  >
        <host>myrightfax1.companyname.com</host>
        <port>80</port>
        <uri/>
        <username/>
        <password/>
        <authType/>
        <encType/>
        <proxyHost/>
        <proxyPort/>
        <proxyUsername/>
        <proxyAuthType/>
        <filter/>
        <filterOutputContentType/>
        </server>
        </servers>
  <!--   ========================================================  -->
  <!--     properties section                                      -->
  <!--     List the system properties here.                        -->
  <!--   ========================================================  -->
  <properties>
        <property  name="ds-temp-dir">/tmp</property>
        <property  name="ds-buffering">true</property>
  </properties>
  <!--  ========================================================  -->
  <!--      channels section                                       -->
  <!--      List the custom delivery channels  here.               -->
  <!--   ========================================================  -->
  <channels/>
</config> 
 
Can we monitor the Job Status?

When the BI Publisher Delivery Manager submits a job, it receives an XML response from
RightFax server. This response includes the unique id for the fax job, which can be used to
check status of the job by submitting a separate request to RightFax server. However, BI
Publisher Delivery Manager is not using this unique fax job id approach. Instead, we
recommend the standard approach used by all delivery channels to get the job status.

In this approach, after a job is submitted the client program can make ‘asynchronous’ 
call using delivery manager APIs. You can create your own callback logic by implementing 
DeliveryResponseListener interface. You must implement the responseReceived() method. 
This method should  be called when the delivery request completes. You can pass this
callback when you invoke the submit() method of the DeliveryRequest. This will initiate
the delivery process in the background and the submit() method will immediately return
the control to DeliveryResponseListener to get the delivery status. Sample code follows:
static class MyListener implements DeliveryResponseListener{
public void responseReceived(DeliveryResponse pResponse){
      System.out.println("Request  done!");
      int  status = pResponse.getStatus();
      System.out.println("Request  status id : " + status);
      String  msg = pResponse.getStatusMessage();
      System.out.println("Request  status message : " + msg);
      //  Update the status in database here...
      }
}
public static void main(String[] args){
      try
          {
                DeliveryManager  dm = new DeliveryManager();
                DeliveryRequest  req =
                dm.createRequest(DeliveryManager.TYPE_RIGHTFAX);
                req.setDocument("d:/tmp/test.ps");
                req.submit(new  MyListener());
          }
      catch  (Exception e)
          {
                e.printStackTrace();
          } 
}
In asynchronous mode, server status is checked once per minute by default but you 
can control this interval by setting ASYNCH_CHECK_INTERVAL delivery property before
submitting the request.
Check the status codes returned by the Delivery Manager and its corresponding status
codes/error codes on the RightFax server.

  

    
Delivery Manager Status/Error Code
    
RightFax Status/Error Code
  
  

    
STATUS_CLIENT_IN_PROCESS
    
 
  
  

    
STATUS_FAILED_BUSY
    
 
  
  

    
STATUS_FAILED_CLIENT_ERROR
    
 -1 (failure to load XML DOM – possibly XML
formatting error)
 -4 (XSL info missing)
 -5 (unknown XML operation type)
  
  

    
STATUS_FAILED_INVALID_RECIPIENT
    
 
  
  

    
STATUS_FAILED_INVALID_REQUEST
    
 
  
  

    
STATUS_FAILED_INVALID_USER
    
 
  
  

    
STATUS_FAILED_IO_ERROR
    
 
  
  

    
STATUS_FAILED_SERVER_ERROR
    
 -3 (failed to connect to RightFax Server)
 -2 (failed to load XSL into DOM)
  0 (submit/query failure)
  9 (Too many errors)
  10 (Duplicate)
  11 (Error)
  12 (Needs attention)
  13 (Needs attention)
  Any other status code
  
  

    
STATUS_FAILED_TIMEOUT
    
 
  
  

    
STATUS_NOT_DELIVERED
    
 
  

 


So I believe you are all set to try the document delivery to a RightFax Server.. 
Happy faxing !! Please note down the patch numbers -



The patch number for EBS 11i (for XML Publisher 5.6.3) is -
7665602 - RIGHT FAX CHANNEL SUPPORT WITH PROVISION FOR DELIVERY STATUS AT LATER TIME

The patch number for EBS 11i (for Collections) is -
8435600 - UNABLE TO SEE FAILURE REASON IN THE CONCURRENT PROGRAM LOG FILE