ReplixFax OutBound Fax API

ReplixFax Java SOAP API Tutorial

Using the ReplixFax Cloud Service to send faxes is straightforward. All you need is a valid username and password, a destination fax number and a document to be sent as the fax. This tutorial describes the steps to create a Java application that sends a fax using the ReplixFax SOAP API. It does not use any JAVA IDE, but you could adapt the instructions if you prefer to use an IDE. Also we will be using a Windows system, but the same code should work on a UNIX system.

You can Download the completed tutorial or follow the steps below.

Requirements

JDK 7 or later.
The Apache Commons Codec library will be used to encode the password. This is optional but is recommended.

Set up Development Environment

Open a command prompt to a folder called “c:\tutorial”. Your JDK executables should be in the PATH.

Import WSDL

Run wsimport.exe located in the JDK bin folder:

wsimport.exe https://api.rpxtest.com/softlinx/replixfax/wsapi -d c:/tutorial

The directory tree: com/softlinx/replixfax will get created and will contain classes that can be used to communicate to the ReplixFax Cloud service.

Apache Commons Codec

Get the commons-codec-1.10.jar file. This is included in the Softlinx tutorial zip or can be downloaded from the Apache web site. Put the jar file in the c:\tutorial folder.

Create a tutorial.java file

Use notepad or any other text editor to create the tutorial.java file. Add the following imports and Define the class and a static main() function.

import com.softlinx.replixfax.*;
import javax.xml.ws.*;
import org.apache.commons.codec.binary.Base64;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.Path;

public static void main(String[] args) {
    try {
    } catch (Exception ex) {
        System.out.println("Exception: " + ex.getMessage());
    }
}

Create ReplixFaxService and ReplixFaxPort objects

ReplixFaxService service = new ReplixFaxService();
ReplixFaxPort port = service.getReplixFaxPort();
((BindingProvider) port).getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "anonymous");
((BindingProvider) port).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "https://api.rpxtest.com/softlinx/replixfax/wsapi");

You can change the EndpointAddress after testing to point to production: https://api.rpxfax.com/softlinx/replixfax/wsapi

Since we are NOT using basic authentication, USERNAME_PROPERTY is set to “anonymous”. We will be passing the real username and password inside the SOAP message.

Now create a new Authentication object and set the username and password. We will be using the Apache Commons library to encode the password. You should replace <organization name>, <username> and <password> with your credentials.

Authentication auth = new Authentication();
auth.setLogin("<username>");
String password="<password>";

auth.setPassword(org.apache.commons.codec.binary.Base64.encodeBase64String(password.getBytes()));
auth.setRealm("<organization name>");
auth.setPasswordSecurity("base64");

Create a SendFaxInput object

When making any ReplixFax web service call, you must pass a corresponding input object. Since we are going to send a fax, we need to create a SendFaxInput object and set its Authentication to the Authenitcation object created in the previous step.

SendFaxInput sendFaxInput = new SendFaxInput();
sendFaxInput.setAuthentication(auth);

Now set the recipient. You can have a list of recipients, but for this tutorial, we will have a single recipient. Also each recipient can have attributes set, such ad company and title. These attributes are only used if a ReplixFax coverpage template is being used. Since we are not using a cover page, then all we need is the fax number for the recipient.

FaxRecipient recipient = new FaxRecipient();
recipient.setFaxNumber("<fax number>");
sendFaxInput.getFaxRecipient().add(recipient);

Once the recipient is specified, you should add the attachment. You can have a list of attachments, but for the tutorial we will only have one file. The order you specify the attachments dictates the page order of the fax. So if you had your own cover page, you could specify that file as the first attachment and have a second attachment as the remainder of the fax.

Attachment attachment = new Attachment();
attachment.setFileName("report.pdf");

Path path = Paths.get("c:\\temp\\test.pdf");
byte[] data = Files.readAllBytes(path);
attachment.setAttachmentContent(data);

sendFaxInput.getAttachment().add(attachment);

Make a SendFax Request

To send the fax request to the server, call SendFax and pass in the SendFaxInput object. As mentioned before all ReplixFax service calls require a corresponding input object. They also return a corresponding output object. In this case, SendFaxOutput.

SendFaxOutput result = port.sendFax(sendFaxInput);

The SendFaxOutput object will contain a status code and optional message. It will also contain the fax job IDs created. There will be a fax job id for each recipient. Since we only specified a single recipient, we only have one fax job id.

System.out.println("StatusCode = " + result.getRequestStatus().getStatusCode());
System.out.println("StatusText = " + result.getRequestStatus().getStatusText());
if (result.getRequestStatus().getStatusCode().compareTo("0") == 0){
    System.out.println("Fax ID = " + result.getFaxInfo().get(0).getFaxId());
}

Compile and Run

In the command prompt, run the following:

javac -cp .;./commons-codec-1.10.jar tutorial.java

A tutorial.class file should have been created. Now run the application.

java -cp .;./commons-codec-1.10.jar; tutorial

If all went well, you should see a fax id of a newly created fax request.

Check the status of the Outgoing Fax

When a fax request is made, it must be processed by the system and then it is scheduled to be faxed. The system processing includes converting all document files to tiff and generating cover pages if a ReplixFax template cover page is being used. When a fax is ready to be sent, potentially the recipient fax machine (or server) is busy and does not have any open lines. Therefore it is difficult to determine when a fax will be successfully sent and received by the recipient fax machine or server.

In order to check the status of a fax, you need to query the system. Look at the Query Sent Faxes sample to see how to do this.

Next steps

The Java samples show how to perform other common Fax tasks. If you have questions about this tutorial or other API related items, contact Softlinx support.

ReplixFax Tutorials