Users Guide – Easylink SendFax Web Service v1.0

What’s in this release?

This release is a downloadable binary install file in either a .zip or .tar.gz format. Once extracted the release will expand into a directory easylink_soa_java_sendfax-1_0. This install contains the following directories

/apps – Contains the required Apache Axis-1_4 installation and jars

/bin – Contains runtime scripts to run the standard fax functions

/data – Sample data for faxing

/docs – Documentation and JavaDocs

/lib – Contains the pre-built jars for the SendFax application

/src – The source code for the samples and ELSFaxManager object

/wsdl – The web service description language files for the SendFax service

Installation

You will first need to validate that you have a Java runtime installed. Please do this by typing “java -version” at the command prompt. You should see text that says Java™ 2 Runtime Environment, Standard Edition (built 1.5.0_02) or similar. You must have at least a Java 1.4 or better runtime installed. If you do not have this please visit http://java.sun.com/javase/downloads/index.jsp

and install the Java SE Development Kit.

To install the Easylink SendFax Web Service first download the installation package as a .zip or .tar.gz binary from Easylink’s developer section of the web site.

Unpack the file into your local development environment. This should create a folder like /dev/easylink_soa_java_sendfax-1_0

To communicate with Easylink via SSL, a certificate is required. A keystore easysendfax.keystore is included in the package and contains the certs needed to communicate with both the test and production Easylink sites. If you do not wish to use the provided keystore, you can specify your own in the command lines to call any of the functions. Instructions on how to create a keystore are also provided in this guide.

Running the Samples

The SendFax package comes with a number of pre-built samples that you can use for testing. The source code for the samples are contained in the easylink_soa_java_sendfax-1_0/src/com/easylink/services/sample package.

To run the samples all you need to do is navigate to the bin folder. Contained in this folder are scripts for running the four sample applications.

· SendFax – Send a fax through the easylink. Network

· ResendFax – Resend a fax already sent with SendFax

· KillFax – Terminate a fax that is waiting to be sent

· QueryFax – Query the Status of a fax on the Easylink Network

$Text Box: SendFax – Send a fax to the destination Usage : sendfax –h<host> -p<Port> -s keystore -e<EmailAddress> -P<Password> -d<Destination number> -f<filepath> [options] Parameters: - h – The Host Name of the destination service. - p – The Port of the destination service. , ie 443 unless using a proxy. - e – The Email Address of the registered account - s - Send in secured mode and full path and name of keystore. –s{filepath}mykeys.keystore. - P – Password for the registered account - d – Destination fax number - f – filepath of file(s) to be faxed to destination. There must be at least one. Separate multiple files with a semi-colon ; Options: - t – TSI The Optional Fax Server Identification String - a – Alternative delivery E-mail address - T – To String value - A – Account Code for tracking the fax 16 digits max - u - User Code for tracking the fax 20 Char max Example: SendFax -hwebservicestest.easylink.com –p443 –s c:\dev\bin\easysendfax.keystore -emytest@acme.com –Ppassword0 -d15557415335 –u12121212 -fc:\\dev\\easylink_soa_sendfax-1_0\\data\\EasyLinkSendFaxTest.doc$

$Text Box: ResendFax – Resend a fax to the destination Usage : resendfax –h<host> -p<Port> -e<EmailAddress> -P<Password> -d<Destination number> -u<UserCode> Parameters: - h – The Host Name of the destination service. - p – The Port of the destination service - e – The Email Address of the registered account - P – Password for the registered account - d – Destination fax number - u - User Code for tracking the fax 20 Char max Example: ResendFax -hwebservicestest.easylink.com –p443 –s c:\dev\bin\easysendfax.keystore -emytest@acme.com –Ppassword0 -d15557415335 –u12121212$

$Text Box: QueryFax – Query the status of a fax Usage : queryfax –h<host> -p<Port> -e<EmailAddress> -P<Password> -u<UserCode> Parameters: - h – The Host Name of the destination service. - p – The Port of the destination service - e – The Email Address of the registered account - P – Password for the registered account - u - User Code for tracking the fax 20 Char max Example: queryfax -hwebservicestest.easylink.com –p443 –s c:\dev\bin\easysendfax.keystore -emytest@acme.com –Ppassword0 –u12121212$

$Text Box: KillFax – Terminate a fax that is waiting to be sent or is in a retry mode Usage : killfax –h<host> -p<Port> -e<EmailAddress> -P<Password> -u<UserCode> Parameters: - h – The Host Name of the destination service. - p – The Port of the destination service - e – The Email Address of the registered account - P – Password for the registered account - u - User Code for tracking the fax 20 Char max Example: killfax -hwebservicestest.easylink.com –p443 –sc:\dev\bin\easysendfax.keystore -emytest@acme.com –Ppassword0 –u12121212$

Samples

The source code for the sample applications are contained in the src/com/easylink/services/sample package. There are java files in this package for each of the sample applications.

The sample applications are wrappers for the ELSFaxManager object. These samples take the command line parameters and pass them into the ELSFaxManager and invoke the appropriate call. You can look at the source code for these samples as an example of how to instantiate and invoke the ELSFaxManager object.

Using ELSFaxManager

SendFax is a Web Service that is available on the Internet for sending faxes from your application. To make it easier to use Easylink has packaged up the capabilities of the web service in a manager, ELSFaxManager.java. The source code for this manager can be viewed in src/com/easylink/services/ELSFaxManager.java.

Using ELSFaxManager is very simple. All that is needed is to instantiate an instance of ELSFaxManager, set the host, port, registered email address and password then invoke the appropriate method call.

Text Box: ELSFaxManager efm = new ELSFaxManager();
efm.setHost(host);
efm.setPort(port);
efm.setEmailAddress(“myemail@test.com”);
efm.setPassword(“mypass”);

SendFaxResponse rs = efm.sendFax(…);

Underneath the covers ELSFaxManager uses the Apache Axis 1.2 framework to instantiate a service, make the service call and return the results of the service.

The installation contains all of the services and types already created for the SendFax web-service using the Apache Axis wsdl2java call. These services can be located in src/com/easylink/webtools/services/SendFaxManager under the packages Description, Service and Types.

Of primary interest to you as a developer are the Types package and the SendFaxResponse, QueryFaxResponse, KillFaxResponse, and ResendFaxResponse objects.

When connecting the SendFax service you must use the appropriate host and port. The Easylink service supports the following connections:

webservicetest.easylink.com:443 - Test system secured fax endpoint

faxadmin.easylink.com:443 - Secured production fax endpoint

File Attachments

ELSFaxManager.sendFax(…) requires at least one file attachment as the content to be faxed. These attachments can be any file type supported by the Easylink network. Please refer to FAQ for the supported types.

Running over a secure connection

In a production environment Easylink requires that you connect to a secured endpoint. This means that you will need to set your port to 443 and activate the secured flag on the ELSFaxManager object. You do this by calling setSecured(true).

However to make a secured connection you must have a proper certificate installed into a keystore. You then have to inform the ELSFaxManager where the keystore is.

Text Box: ELSFaxManager efm = new ELSFaxManager();
efm.setHost(host);
efm.setPort(443);
efm.setEmailAddress(“myemail@test.com”);
efm.setPassword(“mypass”);
efm.setSecured(true);
efm.setKeyStore(“/bin/mykeystore.keystore”);

SendFaxResponse rs = efm.sendFax(…);

To setup your environment for running over a secured connection follow these steps:

1. Create a keystore using the java keytool

a. Change to the easylink_soa_java_sendfax-1_0/bin directory and type

keytool -import -file ..\wsdl\webservicestest.easylink.com.crt -keystore .\mykeystore.keystore -alias webservicestest.easylink.com

b. Enter a password for the keystore and type yes at the prompt to trust this certificate

Note: if keytool is not found then you might not have the proper Java Development Kit installed and accessible in your environment.

2. Pass the keystore to the ELSFaxManager by using the setKeyStore(String) method and setSecured(true) to tell the ELSFaxManager to use an https connection. Also make sure to set the port to the secured inbound port, 443.

If you are using the sample applications (SendFax, KillFax, QueryFax, ResendFax) you need to add the –s option with the location of your keystore where you imported the certificate. For example:

SendFax -hwebservicestest.easylink.com –p443 -emytest@acme.com –Ppassword0 -d15557415335 –u12121212 -fc:\\dev\\easylink_soa_sendfax-1_0\\data\\EasyLinkSendFaxTest.doc –s./easysendfax.keystore

Compiling from the WSDL

The ELSFaxManager is built on top of the Axis 1.4 framework and the standard Easylink SendFax web service. The WSDL and XSD descriptions of the service can be found in the /wsdl folder.

If you would like you can compile the Axis 1.2 locater and service yourself. To do so a script has been provided in the /bin folder.

To compile all of the services and types, enter the following at the command prompt

wsdl2java ..\wsdl\SendFaxManagementService.wsdl -o ..\src --all -w

This will create the package com.easylink.webtools.services.SendFaxManagement.

Within this package are the Description, Services and Types packages.

Service contains the SendFaxManagerLocater and Service

Description contains the SendFaxManagerPortType and SoapBindingStub

Types contains the Request, Response and data containers

Compiling the Source

An ANT build script has been provided in the root folder to help compile the package and create the jar.

To compile make sure that you have Ant 1.6 or better installed on your machine and the ANT_HOME environment variable properly set.

Test by typing ant at the command prompt.

Edit the easylink_soa_sendfax-1_0.properties file and set the attributes for ant_home and jdk.home.jdk_1.5.

From the root (where build.xml resides) run Ant. This should compile the source into /classes\production\easylink_soa_java_sendfax-1_0 and create the /lib/easylink_soa-1_0.jar.

TOC