EasyLink Services

Document Sample
EasyLink Services Powered By Docstoc
					                                User Manual




                            EasyLink Services


       EasyLink GlobalFax for
     Citibank Version 1.0.3.28.08
                                   June 09, 2008

                                   User Manual




EasyLink Services Corporation   Page 1 of 28       6/09/2008
                                                                        User Manual




Overview ............................................................................................................................................................................. 3
Description .......................................................................................................................................................................... 3
Hardware and Software Requirements ................................................................................................................................ 3
Installing the Package .......................................................................................................................................................... 4
Installing from a tar file ....................................................................................................................................................... 5
  Files Installed during the installation. .............................................................................................................................. 5
Checking the version numbers ............................................................................................................................................ 6
Configuration files ............................................................................................................................................................... 6
  Globalfax.cfg – globalfax Configuration file .................................................................................................................. 6
     Sample globalfax.cfg file: ........................................................................................................................................... 8
  ZipFaxReader.cfg – zipfaxreader Configuration File ...................................................................................................... 9
     Sample ZipFaxReader.cfg File .................................................................................................................................. 10
Running the applications ................................................................................................................................................... 11
  GlobalFax ...................................................................................................................................................................... 11
     globalfax –help .......................................................................................................................................................... 11
     globalfax –version ..................................................................................................................................................... 12
     globalfax –send.......................................................................................................................................................... 12
     globalfax –cancel ....................................................................................................................................................... 12
     globalfax –getpasswd ................................................................................................................................................ 13
     Required Arguments:................................................................................................................................................. 13
     Optional Arguments .................................................................................................................................................. 14
     ITUT Format ............................................................................................................................................................. 15
     Sample Invocation of globalfax -send. ...................................................................................................................... 15
     Sample invocation of globalfax cancel. ..................................................................................................................... 15
     Error Codes Returned from globalFax ...................................................................................................................... 16
     File Types supported by GlobalFax ........................................................................................................................... 16
  ZipFaxReader ................................................................................................................................................................ 16
     Sample Notification format for SMTP and ZipFaxReader ........................................................................................ 17
     Sample Invocation of ZipFaxReader ......................................................................................................................... 18
     Stopping ZipFaxReader ............................................................................................................................................. 18
  Local Number Dialing Support ..................................................................................................................................... 19
Alias List Management Webtool. ...................................................................................................................................... 20
  Overview ....................................................................................................................................................................... 20
  Logging into the web based tool.................................................................................................................................... 20
  Creating a Broadcast or Alias list .................................................................................................................................. 21
     Importing a csv file into a Broadcast List .................................................................................................................. 23
     Import File Format .................................................................................................................................................... 23
  Modifying a Broadcast List ........................................................................................................................................... 24
     Export a List .............................................................................................................................................................. 25
     Delete a List............................................................................................................................................................... 25
     Modify a List ............................................................................................................................................................. 25
  Account Management Menu ......................................................................................................................................... 26
  Logging Off ................................................................................................................................................................... 26
Setting up a User For globalfax ......................................................................................................................................... 27
TroubleShooting ................................................................................................................................................................ 27




EasyLink Services Corporation                                          Page 2 of 28                                                                                 6/09/2008
                                                              User Manual


Overview
EasyLink has been contracted by Citigroup to replace their Zip Fax application with an Easylink
developed client applications. This application interfaces with other Citigroup applications and was
designed by Easylink to be very similar to the existing interface to minimize modification
requirements to the fax aware applications at Citigroup. This manual describes the installation,
features, functionality, and troubleshooting of the applications.

Description
The global fax client application communicates with Easylink Services over http and https using a
SOAP 1.1 protocol. The client application consists of two parts; globalfax to send the faxes and
ZipFaxReader that checks for status of the faxes. In addition, a web based list management
interface has been developed for creating and maintaining alias lists. With the availability of the web
based the list interface, local alias support has been discontinued as per the requirements.

A dataflow diagram is shown below.

                                                      Customer
                                                      GlobalFax
                 Server                          Server(s) requests via                           Server


                                                       http/https
        globalfax -send -name dthakker@easylink.com -                         zipfaxreader -name dthakker@easylink.com -password
          password passwd -server coverpage -subject                                                passwd
         “subject” -notify dthakker@easylink.com -from
                   “Divyesh Thakker -cc “R&D”



                                                                                         EasyLink
                                                         Internet/VPN
                                                                                           Fax
                                                          connection
                                                                                        Processing
                                                                                         Servers




    Easylink Web Servers
  (faxadmin.easylink.com)

                                                                                 Fax
                                                                               Messages



                                                               Receiver Fax
                                      Receiver Fax




Hardware and Software Requirements

The client globalFax application is certified to run on a Sun Solaris 8 (SunOS version 5.8) with a
least 30 Mega bytes of free space. The minimum memory requirements for a Solaris 8 OS (~
512MB) meets the needs of this application, although for faster throughput additional memory is
necessary. Network connectivity between the Citigroup site where this application is installed and
Easylink is a necessity for the proper functioning. This application writes logs and the level of
logging can be tuned as per each site’s requirements. Any user using the application must have the
necessary permissions to write to the logs.


EasyLink Services Corporation                                Page 3 of 28                                                          6/09/2008
                                         User Manual




There are two distribution methods by which this application can be installed.
   1. Via a Solaris Package. The latest version of this application is available at
       ftp.easylink.com/Cititest. The file is called EasyWSAPI.pkg.
   2. Via a tar file. The latest version is available at ftp.easylink.com/Cititest

Note: If the tar file is used to install the application, the configuration file must be updated with
      appropriate values.

Installing the Package
   1.   Log on to the application server where this needs to be installed with "root" account access
   2.   Copy the "EasyWSAPI.pkg.gz" file into any temporary folder on the server
   3.   Extract the package by using gunzip EasyWSAPI.pkg.gz
   4.   Install the package with: pkgadd -d EasyWSAPI.pkg
   5.   The install will prompt for the directory in which to install the package. On a typical
        Citigroup install, the install directory would be /export/opt/EasyWSAPI, but the installer
        can choose any directory to install.
   6.   In order to support the local number dialing, the installer will prompt for a few values which
        need to set in the configuration files. The default while installing assumes US dialing
        patterns. There are three questions to be answered to support local number dialing. See usage
        section for more details on this feature.
            a. Enter Country Code (1): This value is the country code that will be pre-pended to
                 the fax number when a fax provided to globalfax meets the criteria for local number
                 dialing.
            b. Enter Area Code (732): This value is the area code that will be pre-pended to the
                 fax number when a fax number provided to globalfax meets the criteria for local
                 number dialing.
            c. Enter Dial Digits (7): This value is used to determine if the fax number provided to
                 globalfax is a local dialed number. If the number of digits entered in globalfax
                 matches in length to this value, then the country code and area code are pre-pended to
                 the fax number prior to sending the message to Easylink for delivery.
   7.   The default log directory is /var/tmp/EasyWSAPI. If you want to change the location of the
        log, enter the new location in both the globalfax.cfg and zipfaxreader.cfg. Please ensure that
        the new directories exist (create if necessary) and the appropriate write permissions (777) are
        granted to these directories.
   8.   The zipfaxreader binary requires a temporary directory for its processing. By default that
        directory is {EasyWSAPI install dir/reports}. This can be changed to any other directory
        by modifying the zipfaxreader.cfg TempFileLocation parameter. During the install, please
        ensure that the directory exists (create if necessary) and grant full write permissions to all
        (777).
   9.   If access to the internet is via a proxy server, input the correct values in the proxyhost and
        proxyport parameters in both globalfax.cfg and zipfaxreader.cfg files. The system
        administrator maintaining these servers will have that information.



EasyLink Services Corporation           Page 4 of 28                                         6/09/2008
                                         User Manual

   10. If the proxy servers that these applications are connecting to require authentication, please
       enter the ID and password in the proxyuser and proxypassword parameters. If not sure about
       these values, please ask your local system administrator.
   11. Installing from a package only supports the install of one version. To install a newer version,
       remove the package and install the later one.

Installing from a tar file
   1. Log on to the application server where this needs to be installed with "root" account access
   2. Change to the install directory: cd /export/opt
   3. Make a directory called EasyWSAPI: mkdir EasyWSAPI.
                     i.Note:     This application can be installed in any directory, but is typically
                        installed in the /export/opt/EasyWSAPI directory.
   4. Copy the "EasyWSAPI.tar.gz" file into the directory where this application will be installed
       on the server
   5. Extract the tar file by using gunzip EasyWSAPI.tar.gz
   6. Un-tar the file using: tar –xvf EasyWSAPI.tar.
   7. Edit the globalfax.cfg to set the following values (the file is located in the installation
       directory):
            a. country_code: This is the country code that is pre-pended to the fax number when a
                fax provided to globalfax meets the criteria for local number dialing.
            b. area_code: This is the area code that is pre-pended to the fax number when a fax
                number provided to globalfax meets the criteria for local number dialing.
            c. dial_digits: This value is used to determine if the fax number provided to globalfax
                is a local dialed number. If the number of digits entered in globalfax matches in
                length to the number entered here, then the country code and area code are pre-
                pended to the fax number prior to sending the message to Easylink for delivery.
   8. The default log directory is /var/tmp/EasyWSAPI. If you want to change the location of the
       the log file, change the value in both the globalfax.cfg and zipfaxreader.cfg. Please ensure
       that these directories exist (create if necessary) and appropriate write permissions (777) are
       granted to these directories.
   9. The zipfaxreader binary requires a temporary directory for its processing. By default that
       directory is {EasyWSAPI install dir/reports}. The location can be changed to any other
       directory by modifying the zipfaxreader.cfg TempFileLocation parameter. During the
       install, please ensure that the directory exists (create if necessary) and grant full write
       permissions to all (777).
   10. If access to the internet is via a proxy server, provide correct values in the proxyhost and
       proxyport parameters in both the globalfax.cfg and zipfaxreader.cfg files. The system
       administrator maintaining these servers will have that information.
   11. If the proxy servers that these applications are connecting to require authentication, please
       enter the ID and password in the proxyuser and proxypassword parameters in both the
       globalfax.cfg and zipfaxreader.cfg files. If not sure about these values, please ask your local
       system administrator.

Files Installed during the installation.
The following files are installed in the directory:

EasyLink Services Corporation            Page 5 of 28                                      6/09/2008
                                        User Manual

      globalfax.cfg – globalfax configuration file
      ZipFaxReader.cfg – ZipFaxReader configuration File.
      globalfax – executable file for sending faxes, mimics globalfax.pl
      ZipFaxReader - executable file for used for status checking of faxes.
      Cabundle.crt – client SSL certificates for encryption.
      libEasyWSAPI.so – API’s library
      libSBCrypt.so – Encryption library – provided by Citigroup
      SolarCrypt – Part of the Encryption package provided by Citigroup.

If there are any problems installing the package, please make sure that a super user (root) is
executing the package and appropriate free space is available. If the problem persists, please contact
EasyLink Services Corp customer service.

The executable files globalfax and zipfaxreader are installed with the permissions 755,
owner: read, write and execute permissions,
group: read and execute permissions,
others: read and execute permissions.

Easylink does not support installing multiple versions of the same application on the same server.

Checking the version numbers
Both globalfax and ZipFaxReader will display the version number when run with the –v option.
This version number should be provided to Easylink when requesting support.

To get the version number for globalFax, run the following command:
    {full path to directory where application is installed}/globalfax –v

To get the version number for ZipFaxReader, run the following command
   {full path to directory where application is installed}/ZipFaxReader -v

Configuration files
This section describes the configuration files for each application and what values should be set for
each parameter.

Globalfax.cfg – globalfax Configuration file

globalfax uses the globalfax.cfg configuration file to store user and system parameters. The file is
required for the application to function correctly. The only required parameters are host and port

The following parameters reside in the globalfax.cfg file:

#WebService Parameters
host:
        The name of the webservice host on Easylink’s side that will
        accept globalfax calls. Currently set to
        webservicestest.easylinkcom for testing. The production site is
        faxadmin.easylink.com
port:


EasyLink Services Corporation          Page 6 of 28                                         6/09/2008
                                User Manual

           Port where the https connections will be made on the Easylink
           Server. Set to 443
user:
         For future use
password :
         For Future use

#Proxy Parameters
proxyhost:
        HTTP proxy server (if required)*
proxyport:
        IP port of HTTP proxy server (if required)*
proxyuser:
        HTTP proxy user (if required)
proxypassword:
        HTTP proxy user’s password (if required)

#Sending Fax Parameters
TSI:
        The Transmitter Sending ID, TSI. This is the ID that is sent on
        all outgoing faxes
DeliveryNoticeType:
        Select the type of notices you want. Set the value to
               “ALL” to receive delivery and nondelivery notices
               “DELONLY” to receive only delivery notices
               “NONONLY” to receive only nondelivery notices
               “NONE” if you do not want to receive any notices
DeferValue:
        Reserved for future use
ServiceRef:
        Reserved for future use
AccountCode:
        The default Account Code that will be used for every fax if an
        Account Code is not supplied on the command line when sending a
        fax.


#Logging Parameters
logdir: /var/tmp/EasyWSAPI/
      The location of the log directory, default is /var/tmp/EasyWSAPI/.
      Change this parameter if you’d like to write the log to a different
      directory.
tracelevel: 0
      The trace level; 0 is the default. Set this parameter to
      0xFFFFFFFF if full trace is needed or 0x0000ffff if only errors and
      summary trace is required.
logretention:0
     (Not currently used. For future enhancements).
separator:!
     This is the separator to use in the faxnumber field. Valid values
     are “!” or “;”

#Fax Number Parameters

EasyLink Services Corporation   Page 7 of 28                        6/09/2008
                                        User Manual

country_code:
     Used for local number dialing support. The value entered here is
     automatically prepended to the faxnumber provided when the local
     number match is met. Numeric value only
area_code:
     Used for local number dialing support. The value entered is
     automatically prepended to the faxnumber provided the local number
     match is met. Numeric value only
dial_digits:
     The number of digits for a fax number that represent local dialing.
     Numeric value only.

                      In the past , due to Networking issues, only a few Citibank Proxy servers
                       currently had access to the Easylink Test site. It is our understanding that this
                       has been resolved. However, if the problem still persists, please set the the
                       proxy host and port to 192.193.221.141 and 8080.

Sample globalfax.cfg file:
# WebService parameters
url:
host:webservicestest.easylink.com
port:443
user:
password:

# Proxy parameters
proxyhost:
proxyport:
proxyuser:
proxypassword:

# Send parameters
TSI:TSI
DeliveryNoticeType:ALL
DeferValue:
ServiceRef:
AccountCode:

# Log output directory
logdir:/var/tmp/EasyWSAPI/
tracelevel:0xffffffff
logretention:0

separator:!

#fax number parameters
country_code:1
area_code:732
dial_digits:7
# WebService parameters
url:
host:webservicestest.easylink.com
port:443
user:
password:

# Proxy parameters

EasyLink Services Corporation           Page 8 of 28                                         6/09/2008
                                User Manual

proxyhost:
proxyport:
proxyuser:
proxypassword:

# Send parameters
TSI:TSI
DeliveryNoticeType:ALL
DeferValue:
ServiceRef:
AccountCode:

# Log output directory
logdir:/var/tmp/EasyWSAPI/
tracelevel:0xffffffff
logdir:/var/tmp/EasyWSAPI/
tracelevel:0xffffffff
logretention:0

separator:!

#fax number parameters
country_code:1
area_code:732
dial_digits:7



ZipFaxReader.cfg – zipfaxreader Configuration File

#WebService Parameters
host:
      The name of the webservice host on Easylink’s side that will accept
      global calls. Currently set to webservicestest.easylinkcom for
      testing.
port:
      Port where the https connections will be made on the Easylink
      Server.
user:
      Not used
password:
      Not used

# Proxy parameters
proxyhost:
     HTTP proxy server (if required)
proxyport:
     IP port of HTTP proxy server (if required)
proxyuser:
     HTTP proxy user (if required)
proxypassword:
     HTTP proxy user’s password (if required)

# Query parameters




EasyLink Services Corporation   Page 9 of 28                      6/09/2008
                                 User Manual

sleep:300
     The amount of time (in seconds) to wait before querying for a sent
     fax results; minumun setting is 300 seconds.
ShellFileToCall:/{install dir}/notify.sh
     The location of the program needed to read notifications send by
     ZipFaxReader; the program is located in the installation directory.
     If you changed the default installation directory, enter the new
     location. A sample script is provided with the installation.
TempFileLocation:/{install dir}/reports
     The location of the temporary work directory. If you changed the
     default installation directory, you enter the new location.

# Log output directory
Logdir: ./Log
     The location of the log directory. To change the location of the
     log directory, enter the value here. Make directory structure you
     enter exists on the machine.
Tracelevel: 0
     Determines the amount of trace statements that are logged. Set to
     0xFFFFFFFF if full trace is needed or 0x0000ffff if only errors and
     summary trace is required.
Logretention:0
     Not currently used. For future enhancements.

Sample ZipFaxReader.cfg File
# WebService parameters
url:
host:webservicestest.easylink.com
port:443
user:
password:

# Proxy parameters
proxyhost:
proxyport:
proxyuser:
proxypassword:

# Query parameters
Sleep:300
ShellFileToCall:/opt/EasyWSAPI/notify.sh
TempFileLocation:/opt/EasyWSAPI/reports

# Log output directory
logdir:/var/tmp/EasyWSAPI/
tracelevel:0
logretention:0

"ZipFaxReader.cfg" [Read only] 23 lines, 347 characters
logretention:0




EasyLink Services Corporation   Page 10 of 28                    6/09/2008
                                           User Manual

Running the applications

GlobalFax
Globalfax is the client application that sends or cancels messages to be faxed to the EasyLink
network. The application has the ability to send faxes to a single or multiple recipients at one time.
The application was developed as per Citigroup specifications to mimic the existing Citibank global
fax application.

globalFax supports the following calls:

                       globalfax        –help
                       globalfax        –version
                       globalfax        –send
                       globalfax        –cancel
                       globalfax        –getpasswd



globalfax –help

Using this option will show the help screen, similar to the one displayed here.

        usage: ./globalfax [-send|-cancel|-version|-getpasswd|-help] args ...

        To send a fax:

                   ./globalfax -send args file [file...]

                   where mandatory args are:
                           -name globalfax-account-name
                           -password encrypted form of globalfax-account-password
                           -server server-name
                           -subject subject
                           -notify mail-address
                           -from sender-name
                           -cc cost-center

                   where at least one of the following args must be included:
                           -to "fax-number!recipient-name" [...]
                           -alias zip-addressbook-alias [...]
                           -addrfile filename [...]

                   where optional args are:
                           -timetolive maximum-number-of-minutes
                           -maxtries maximum-number-of-attempts
                           -period minimum-number-of-minutes-between-tries
                           -nocover
                           -resolution fine|std
                           -comments filename

        To cancel a fax:

                   ./globalfax -cancel args faxid


EasyLink Services Corporation             Page 11 of 28                                    6/09/2008
                                        User Manual


               where mandatory args are:
                       -name globalfax-account-name
                       -password encrypted form of globalfax-account-password
                 -faxid – Fax Id to be cancelled
       To get the encrypted password:

                  ./globalfax -getpasswd args pasword
                  where mandatory args are:
                          -password 6 digit globalfax-account-password


globalfax –version
This will display the version number of the binary executable. For example: Version: 1.0.2.7.08


globalfax –send
This is the command used to send faxes to the easylink network.

globalfax -send args file [file...]

            where mandatory args are:
                    -name globalfax-account-name
                    -password the encrypted globalfax-account-password
                    -server server-name
                    -subject subject
                    -notify mail-address
                    -from sender-name
                    -cc cost-center

            where at least one of the following args must be included:
                    -to "fax-number!recipient-name" [...]
                    -alias zip-addressbook-alias [...]
                    -addrfile filename [...]

            where optional args are:
                    -timetolive maximum-number-of-minutes
                    -maxtries maximum-number-of-attempts
                    -period minimum-number-of-minutes-between-tries
                    -nocover
                    -resolution fine|std
                    -comments filename
                    -s For enhanced logging


globalfax –cancel
This is the command to cancel a fax sent to the easylink network that is still in progress.


globalfax -cancel args faxid


EasyLink Services Corporation          Page 12 of 28                                          6/09/2008
                                            User Manual

             where mandatory args are:
                     -name globalfax-account-name
                     -password encrypted globalfax-account-password

             where optional args are:
                     -s For enhanced logging



globalfax –getpasswd
This command will return the encrypted password to use in the globalfax send and cancel
commands


globalfax -getpasswd args 6-digit-password

             where mandatory args are:
                     -password globalfax-account-password


Required Arguments:
name        This is a username that is provisioned on the Easylink network. The username is in the form of
            an SMTP address (globalfax@citigroup.com). Note that the username must be preregistered on
            the EasyLink network, or the application will not work.

password    This is the encrypted password. When the account is provisioned on the Easylink Network, a six-
            digit password is provided. This password can be used as a parameter to global –getpasswd
            command. The output from that command is to be used as the password value. As per
            requirements, a clear password will not be accepted.

server      This value determines which cover page to user for the fax. Validation is done on the value
            specified in this parameter. If the value does not exist, a non-valid cover page name, on the
            Easylink Network, the message is rejected. Note that the username and server (cover page)
            combination have to be a valid combination preregistered on the EasyLink network. If a new
            cover page is required, please contact Easylink support.

subject     This is text that is placed on the cover page. This field supports double byte character sets.

notify      This value is an SMTP (email) address where Easylink Servers will send an email notification
            regarding the final status of the fax (es). Note that this is a required parameter. Easylink uses this
            address to when sending notifications; this parameter must be a valid SMTP address or
            notifications will not be delivered. See section “Sample Notifications” for a sample of the
            notifications. In cases where there is more than one recipient for the message (broadcast), a
            notification is sent only after the entire broadcast is complete.
from        This text will be put on the cover page

cc          This is the CitiGroup cost center value. It is text of up to 16 characters in length. It appears on
            Easylink invoices and web tools for accounting functions.

At least one of the following three arguments are required.



EasyLink Services Corporation              Page 13 of 28                                              6/09/2008
                                              User Manual

to "fax-number!recipient-name"
           Fax number must be all digits and at least 7 characters long. It must be in the ITUT format, i.e.
           country code, areacode, and number. Multiple fax numbers, separated by commas(,) is also
           supported.

               The recipient name will appear on the cover page. The default separator between the fax-number
               and recipient-name is the “!”. This application also supports the “;” (semi colon) as a separator
               value. The separator character used to parse the –to parameter is defined in globalfax.cfg
               configuration file separator: parameter. Currently the “!” and “;” values are supported as
               separators. This application also supports the local number dialing pattern. See section on “Local
               Number Dialing Support” for a more detailed explanation.

alias          Use this parameter to specify a valid name of a list that is stored on Easylink’s servers. Note that
               the list created on Easylink’s servers must belong to the user that is sending the fax, otherwise an
               error will occur. A webtool that supports list management has also been developed to use along
               with this application. See section, “Alias List Management Webtool” on details of how to use
               this feature.

addrfile       This parameter provides the ability of specifying a file that contains fax numbers to send a fax.
               The document to be faxed is sent to all faxnumbers that are in the file specified in this parameter..
               The format of the faxnumbers contained in the file is:
                          fax-number!recipient-name
                          fax-number!recipient-name


Optional Arguments

timetolive
        This parameter is not supported by Easylink at this time. However, globalfax accepts this parameter
        to preserve the existing interface.

maxtries
       This parameter is supported by Easylink at the server level is preconfigured for each provisioned
       user. The user is not able to change this value for each fax being sent out.

period
           This parameter is supported by Easylink at the server level and is preconfigured for each provisioned
           user. The user is not able to change this value for each fax being sent out.

nocover
        If this option is specifed , the name of the cover page specified in the server name is ignored and
        nocover page is sent
.
resolution
        Sets the resolution of the fax to fine or standard mode. The values are “fine” or “std”. The default is
        fine.

comments
     This is a name of a file which can contain upto 4 lines of text, each line is no longer than 50
     characters. If a comment is provided, the text is appended to the subject line parameter and placed on
     the cover page of the fax.



EasyLink Services Corporation                Page 14 of 28                                             6/09/2008
                                            User Manual

-s       This parameter supports the enhanced logging. When this parameter is used errors that ocurr when
         sending faxes to EasyLink are written to stdout in the format of a negative number; maximum -255,
         When the fax is successfully transmitted, the Easylink transaction identifier (TID) is written to
         stdout. The error message is written to the log as well as the error code. Also, when this option is
         used, the trace level for logging is automatically set to the highest level. In addition, all trace for
         messages that are successfully delivered to the EasyLink service are written into the log. If this
         optional parameter is not used, then failure messages, not the error code, are written to stdout.



ITUT Format
It is important to note that all the fax numbers should be in ITUT format,. If local number dialing support has
not been configured, each number must be represented as: “CountryCode+AreaCode+FaxNumber”. For
example:
      A fax going to a destination in the United States is entered as “17325551212”; where “1” is the
         country code for the US, “732” is the area code, and “5551212” is the fax number.
      A fax to the United Kingdom would be formatted as “442075518845”; where “44” is the country
         code, “207” is the area code, and “5518845” is the fax number.


Sample Invocation of globalfax -send.
An example of the command to run to send the fax using one input file is as follows:

globalfax –send –s -name janedoe@easylink.com –password
   03e86d74651a4384e75b21bb27a532c4 –server CG_COVER –notify
   jackdoe@patmedia.net –from “Divyesh Thakker” –cc “Engineering” –to
   “17323526796!John Doe” –subject “This is a subject line”
   /usr/operations/testfile.txt

     The above fax is being sent from registered user “janedoe@easylink.com”, whose password is
     “03e86d74651a4384e75b21bb27a532c4”, requesting a cover page “CG_COVER”. Notices are sent to
     jackdoe@patmedia.net, the cover page will say the fax is from “Divyesh Thakker”, have a subject of
     “This is a Subject Line”, and the To will say “John Doe”. The fax contained in the file
     “/usr/operatons/testfile.tx” is being sent to 17323526796. The –s means that in the case of an error, the
     error code is written to stdout, on success the TID is written to std out.

An example of the command to run to send more than one file to fax is as follows:

globalfax –send –name janedoe@easylink.com –password passwd –server
   CG_COVER –notify jackdoe@patmedia.net –from “Divyesh Thakker” –cc
   “Engineering” –to “17323526796!John Doe” –subject “This is a subject
   line” /usr/operations/testfile.txt /tmp/file2.pdf

     The multiple files are listed at the end of the command line separated by a space.

A successful invocation of globalfax will output a Transaction ID (TID) to the screen. This
Transaction ID can be used to track the fax and its status.

Sample invocation of globalfax cancel.
An example of the command to run to cancel a previously sent fax is as follows:



EasyLink Services Corporation              Page 15 of 28                                             6/09/2008
                                            User Manual

globalfax – cancel –name janedoe@easylink.com –password
   03e86d74651a4384e75b21bb27a532c4 01244337651340980000

    The sender, associated password, and the TID is required for this command. In the above example,
    01244337651340980000 is the Transaction ID that was returned when globalfax ran. Note that Easylink
    cannot guarantee that the fax will be cancelled, due to the processing nature of the fax application.


Error Codes Returned from globalFax

If a failure occurs while sending a message to Easylink, the globalfax will exit with an error code. The
following are the possible error codes that globalfax will return.

Error Code     Description                                       Solution
1              SOAP Error                                        Possible connectivity error. See log for
                                                                 details
2              SOAP not Initialized correctly                    SOAP Library not loaded correctly. Possible
                                                                 environment issue. Make sure
                                                                 LD_LIBRARY_PATH is correct or reinstall
                                                                 the application.
3              SOAP Default Error                                Possible certificate error. Make sure
                                                                 certificate is in the directory and is valid.
4              File to be faxed not found or 0 length            The file to be faxed is missing or 0 length
5              Cannot Read comments file                         The file name specified for comments could
                                                                 not be found.


File Types supported by GlobalFax
This application at the time the manual is written supports the following files for faxing via global fax.
     Office 2003 documents
     PostScript files
     Txt files
The file extensions should reflect the type of document being sent, ie a word file should have the extension
.doc and a text file should have an extension of .txt

The file types supported by this application can change and new ones can be added. For the latest list of file
types supported by this application, please contact Easylink.


ZipFaxReader
The zipfaxreader client application is installed as part of the EasyWSAPI package. This application
periodically polls the EasyLink network for status. The program runs as a Unix daemon. Each
zipfaxreader application polls the EasyLink network for status for a single user. Since multiple
users of globalfax can be run on the same server, it is important to note that each instance of
zipfaxreader polls for status of a single user only. To poll for multiple users, you must start up a
ZipFaxReader for each user.

When the ZipFaxReader obtains status is passes the entire contents of the notification to a shell
script whose name is taken from the zipfaxreader.cfg ShellFileToCall parameter. When the shell
script is executed successfully, ZipFaxReader notifies the Easylink servers of successful receipt of
the notification so that EasyLink servers will not resend the notice the next time ZipFaxReader runs.

EasyLink Services Corporation             Page 16 of 28                                             6/09/2008
                                            User Manual

It is important to note that if notifications are required, the ZipFaxReader must be running at all
times.

Note: ZipFaxReader notification is in addition to the SMTP message sent out from the Easylink
      server to the notify argument on the globalfax command line. Appropriate alarming should
      be added to ensure this daemon is running if so desired.

Sample Notification format for SMTP and ZipFaxReader

Sample Failure Message

Your recent fax job delivery report:



 Succeeded
 ------------------------------------------------------------------------------


Failed Delivery
 ------------------------------------------------------------------------------

   1 To patmedia                                   [failed @ 11:31] try 3/3



 Call History - Succeeded
 ------------------------------------------------------------------------------


Call History - Failed Delivery
 ------------------------------------------------------------------------------

   1 To patmedia......................................Fax no: 17326523729
          09/01-11:31:11 TERMINATED with error "NO CONNECT"



 Execution Details
 ------------------------------------------------------------------------------
      Job Related:
            Subject - This test
            Pages   - 1 (including cover, if any)
            Fax ID - 0233201062445550900
      Routing Related:
            Queue   -
            Server -

       Process Related:
             Submitted - 2006/09/01-11:25:23
             Completed - 2006/09/01-11:43:10


Sample Successful Delivery Notification.

Your recent fax job delivery report:



 Succeeded
 ------------------------------------------------------------------------------


EasyLink Services Corporation              Page 17 of 28                                     6/09/2008
                                         User Manual
   1 To patmedia                                 [completed @ 11:27] try 1/3




 Call History - Succeeded
 ------------------------------------------------------------------------------

   1 To patmedia......................................Fax no: 17323526796
          09/01-11:27:20 SUCCEEDED - 0:24, answered as "0400455062445561000"




 Execution Details
 ------------------------------------------------------------------------------
      Job Related:
            Subject - This test
            Pages   - 2 (including cover, if any)
            Fax ID - 0233201062445555200
      Routing Related:
            Queue   -
            Server -

       Process Related:
             Submitted - 2006/09/01-11:25:54
             Completed - 2006/09/01-11:31:18


      The times in the report will be in GMT.
      The call history section will list details of the last attempt only.
      The Queue line item in the Routing section will be blank.

Sample Invocation of ZipFaxReader

Run the ZipFaxReader application as shown below. The ZipFaxReader is a daemon that will
periodically query the Easylink server to get notifications and will execute the script specifed in the
zipfaxreader.cfg parameter ShellFileToCall and pass in as an argument the notification file.

./ZipFaxReader -name Id -password 03e86d74651a4384e75b21bb27a532c4

This will start the ZipFaxReader as a daemon.

Stopping ZipFaxReader
    In order to stop the daemon, find the process ID (PID) of the zipfaxreader by issuing:
           ps –ef |grep –i zipfaxreader
      Issue the kill command: kill PID.

For example, the output of the ps command is a UNIX PID (process Id):

#ps –ef | grep –i zipfaxreader

root 12831     1 0 11:41:59 ?         0:06 ./ZipFaxReader –name
    dthakker@easylink.com -password 19b2eeb3f66bed4a7303d3c144

EasyLink Services Corporation           Page 18 of 28                                        6/09/2008
                                                User Manual


#kill 12831

Local Number Dialing Support
The Easylink network expects each fax number to be in ITUT format. However, modifications have
been made to the globalfax application to enable local number dialing. During the installation of
the application, the installer is prompted for the country code, area code and length of digits used
when dialing a local number. The script stores the values in the globalfax.cfg configuration file.

When the Local Number Dialing information is entered, each fax number entered on the global fax
command line, is checked for the number of digits enters. If the length of digits entered is equal ot
the value entered for dial_digits, the API will prepend the country code and city code to the number
before sending the message to EasyLink. If the length of digits does not match, the number entered
is used without being altered. This feature works for a single country and city code defined in the
configuration file. It does not support multiple country or city codes. The values in the
configuration file can be changed at any time.

For example, if the application were to be installed in any location in the US, (area code 732), the
configuration file should be set to country_code: 1, area_code: 732 and dialed_digits: 7.

If the globalfax -to line is something similar to “3526796!John Doe”, the application will prepend
1732 (Country Code + Area code from configuration file) to the fax number 3526796 prior to
sending to Easylink network. This is because the length of 3526796 is 7 which matches the
dial_digits value of 7.

If the user entered 19083526796, no modifications will be made to the fax number. So if the user
enters a 7 digit number (as entered in the config file) the application will always prepend the country
code and area code. If the fax number is not local, then a full ITUT fax number is required.





 When installing the pkg you are prompted for this information. If installing the tar file, you need to manually edit the
configuration files.

EasyLink Services Corporation                 Page 19 of 28                                                  6/09/2008
                                            User Manual


Alias List Management Webtool.

Overview
In order to support the alias feature of global fax, Easylink has developed a web based List Management
utility tool that facilitates the management of lists of fax numbers. Using this tool, a user will have the
capability to manage alias or Broadcast lists and change their passwords.

Logging into the web based tool
During the testing phase, this tool will be available at the following URL:
https://webservicestest.easylink.com

In order to login to the tool, use the Easylink supplied UserId and 6 digit password that is also used
in globalfax –getpasswd




                                           Figure 1 –Login Screen

The user Management menu item contains the sub menus for creating and maintaining Broadcast
or Alias lists.




EasyLink Services Corporation              Page 20 of 28                                            6/09/2008
                                       User Manual

Creating a Broadcast or Alias list
Once logged in, the screen will look like the one below.




                                  Figure 2 –Broadcast List Screen




EasyLink Services Corporation         Page 21 of 28                 6/09/2008
                                        User Manual

Click on Broadcast List then Create List to create a broadcast list.




                                Figure 3 –Broadcast Create List Screen

The Create List screen provides the ability to create broadcast or alias lists. The name specified in
the Broadcast List Name can then be used in the alias parameter of the globalfax command.

      The Destination field is used to enter the fax number.
      The Contact name is used to enter the name of the person to contact regarding the list.
      Both these fields are required.
      Click on the ADD button. This opens an entry screen that allows you to enter numbers one at
       a time or import numbers from a comma delimited (csv) file. The name of your new list as
       well as the number appear in a list box on the right.

Some basic rules regarding the input of fax numbers
   1) A faxnumber is at least 7 digits
   2) A fax number cannot start with a 0
   3) If a fax number starts with a 1, then the length has to be 11 digits
   4) A fax number is only numeric values. Any formatting characters entered such as (),+, spaces
      will be removed when saving to the database.
   5) Contact Info is required
   6) Duplicate fax numbers are allowed, but a warning is displayed.

EasyLink Services Corporation          Page 22 of 28                                        6/09/2008
                                            User Manual




                                          Figure 4 –List Input Screen


Importing a csv file into a Broadcast List
This tool provides the ability to import csv files that contain fax numbers and contact information into the list.
     Click on the IMPORT button and specify the name of the file that contains the contact information
        and fax numbers.
       Click on the SAVE button to save the list just created to the database. Failure to do so will
        not save the lists in the database. When the SAVE button is clicked, all the data that is in the
        right side list box is saved to the database and can be used in globalfax –alias command.

Import File Format
The format of the file to be imported must be a “.CSV” file and contain the fax number and recipient name in
the following format: “Fax Number”, “Recipient Name”,

A sample of data in the file is as follows:

                “442075518846”,”Peter Doe”
                “19085551234”,”Jane Doe”

Note that all alias names are case sensitive If the file contains invalid fax numbers, the entire import
will fail. Some basic rules regarding fax numbers and importing lists”

EasyLink Services Corporation              Page 23 of 28                                             6/09/2008
                                          User Manual


    1) A faxnumber is at least 7 digits
    2) A fax number cannot start with a 0
    3) If a fax number starts with a 1, then the length has to be 11 digits
    4) A fax number is only numeric values. Any formatting characters entered such as (),+, spaces
       will be removed when saving to the database.
    5) Contact Info is required.


Modifying a Broadcast List

In order to modify an alias or Broadcast list, click on the Broadcast List, then Modify Lists menu
items. In order to modify a list, an existing list must be first selected. A screen similar to the one
shown below is used to search for alias or broadcast lists to modify. The List name box supports
partial searches. If left blank, all the lists that belong to the user who has logged in will be displayed.




                                   Figure 5 –Modify List Search Screen

Once the Search button is clicked, a screen similar to the one below will be shown.




EasyLink Services Corporation            Page 24 of 28                                         6/09/2008
                                            User Manual




                                    Figure 6 –List Search Results Screen
The search results screen provides the ability to
       Export the list as a CSV file
       Delete the entire list
       Modify the list

Export a List
In order to export the list, click on Export and enter location of where the file is to be created. This
will create a csv style file that contains the contact information and fax numbers that are currently
stored in the database.

Delete a List
In order to delete a broadcast list, simply click on the Delete button.

Modify a List
In order to Modify any list, click on the Modify button. A screen similar to the one shown below
will be displayed.




EasyLink Services Corporation              Page 25 of 28                                      6/09/2008
                                       User Manual




                                    Figure 7 –Modify List Screen

This screen can be used to add, update or delete fax numbers to the list.
    Add entries by entering the Destination and Contact Name on the left, then clicking the ADD
       button.
    Modify an entry by clicking on the existing data on the right. The data will appear in the
       entry fields on the left. Correct the data then click the MODIFY button.
    Remove and entry by clicking on the data on the right. Then click the REMOVE button.

Note that to save all the work to the database, the SAVE button must be clicked.


Account Management Menu
The Account Management menu item can be used to change passwords. Note that once the
password is changed in this screen, the globalfax –getpasswd command must be called to
obtain a new encrypted output of the password. The encrypted data is what is supplied to
globalfax –send and –cancel commands.

Logging Off
Click on the Logoff menu item to log out of the web based utility.


EasyLink Services Corporation         Page 26 of 28                                  6/09/2008
                                        User Manual

Setting up a User For globalfax
In order to setup a user for the globalfax application, the user must first be provisioned on the
Easylink Network. Please contact Easylink Customer services to setup this user. When contacting
Easylink support, please provide:
     an ID (typically of the form of an smtp id) like smbsm@citigroup.com ,
     a 6-digit password; if a password is not supplied Easylink will create one
     an Easylink Account Number under which add this user. The account number the user is
       added to dictates which cover pages a user is allowed to use.

The user will use the supplied ID and password (in encrypted form) to send faxes via globalfax
and to login to the web based tools to manage alias lists and passwords. Note that the password used
to login to the web based tool will be the unencrypted one.

Easylink customer service will respond with a confirmation when the user has been provisioned and
is ready to start using this service.

TroubleShooting
There are a number of common steps that a user should do to ensure a trouble free experience prior
to calling EasyLink support.

If a user’s faxes are not being delivered, make sure the following steps are completed to avoid
delays in resolving issues.

      Ensure that there is network connectivity between the server the application runs on and
       Easylink. The EasyLink servers that this application will access are available by https over
       the internet. However, Citigroup has a VPN tunnel setup to Easylink and therefore may need
       some additional network configuration setups. There are a number of unix based tools such
       as ping or traceroute that provide conclusive evidence of trouble free network connectivity.
       See your local system administrator for more details.
      The id and password used in the user and password argument of globalfax are valid ID
       and passwords on the EasyLink network.
      The argument used in the server parameter is for a cover page name. Please ensure that id
       specified is authorized to use that cover page and that the cover page is a valid cover page.
      The user executing the command has execute permissions on that server.

If a user is able to send the faxes to the EasyLink Network but no notifications for the status are
being received by the user.
      The id and password used in the user and password argument of globalfax are valid ID and
        passwords on the EasyLink network.
      The SMTP address specified in the notify argument of globalfax is a routable address
        from the outside world. Your local system administrator should be able to verify that.

If the problem still persists, both globalfax and zipfaxreader have the ability to generate copious
amount of logs that Easylink personnel will need to resolve the issue. In order to turn on logging, for
either globalfax or zipfaxreader, complete the following steps
      Edit the globalfax and/or zipfaxreader configuration files. These files will be in the same
        directory as where the application is installed.

EasyLink Services Corporation          Page 27 of 28                                        6/09/2008
                                       User Manual

      Modify the parameter Tracelevel and put in the value 0xffffffff and save the file.
      For a zipfaxreader issue, the daemon will have to be restarted.
      For a globalfax issue, simply reissue the command.
      The logs will be created in the directory specified in the LogDir parameter of globalfax and
       zipfaxreader. Please ensure that the user has appropriate write permissions to that directory.
      Send the logs to Easylink Support and the version number of globalfax and/or
       ZipFaxReader




EasyLink Services Corporation         Page 28 of 28                                       6/09/2008

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:7
posted:12/11/2011
language:English
pages:28