german | english

HylaFAX with transmission reports in PDF format

A custom extension to the open source fax server

HylaFax is a robust, powerful and freely available open source fax server, suited for small home server installations as much as for large enterprise environments. While it offers a wide range of features, it unfortunately lacks a simple option to receive fax transmission reports in PDF format. This website introduces a simple extension to HylaFAX to add this missing feature.

I am running Asterisk (1.8.13) with IAXmodem (1.2.0) and HylaFAX (6.0.6) on a Seagate Dockstar with Debian Wheezy (7.8). All fax transmissions from and to this server are sent through VOIP. While in theory fax messaging over VOIP can be troublesome, I found this setup to be very reliable and luckily experience no issues with sending and receiving fax messages. The only thing I was missing from HylaFAX was the option to receive a proper PDF transmission report, as provided in print by most classic analog fax modems, in order to easily document outgoing fax calls.

Since I did not find a previously published and readily available solution to this, I decided to add the feature myself and share it with other HylaFAX users.

About current file attachment options

HylaFAX can attach a copy of submitted or received fax documents to its notification e-mails, in TIFF, PDF, postscript and raw format. Two functions, namely 'BuildAttachArgs()' and 'ConvertFile()', are used to create and append the requested attachments. These functions are located in the shell script:

/var/spool/hylafax/bin/common-functions

They are executed by 'notify' and 'faxrcvd', two further shell scripts which are invoked after fax messages have been sent ('notify' is run) or received ('faxrcvd' is run).

The file formats in which documents are attached to e-mail notifications can easily be specified by editing two files, which are parsed as shell scripts:

/etc/hylafax/FaxNotify
/etc/hylafax/FaxDispatch

'FaxNotify' applies to outgoing fax messages and 'FaxDispatch' to received documents. To have have documents attachments in PDF format one would add the line:

RETURNFILETYPE=pdf

More than one file format can be chosen. HylaFAX will then attach a copy in each of the designated formats:

RETURNFILETYPE= "tif pdf ps raw"

'BuildAttachArgs()' determines the requested file formats and executes 'ConvertFile()' if any format conversions are necessary. Neither 'BuildAttachArgs()' nor 'ConvertFile()' discern whether they have been executed by 'notify' oder 'faxrcvd'.

Introducing a new file format to HylaFAX

In order to obtain the desired PDF fax reports I made the following amendments to HylaFAX:

By applying these modifications, the new file format REPORT is introduced to HylaFAX. This format can now be referred to in 'FaxNotify'. To request a PDF fax report, the following line is added to 'FaxNotify':

RETURNFILETYPE=report

The new file format can be combined with any previously available file type. Thus, PDF reports can be received in addition to copies of sent documents:

RETURNFILETYPE="tif pdf ps raw report"

If REPORT+ is chosen, a PDF copy of the sent document will be added to the report file:

RETURNFILETYPE=report+

How to install the extension

To install the extension, a copy of the file 'custom-functions', available for download from this website, needs to be located in the HylaFAX bin directory:

/var/spool/hylafax/bin/

This can be achieved from the command prompt:

$ wget http://1024k.de/hylafax/scripts/en/HylaFAX_custom-functions.tar.gz
$ tar -xvzf HylaFAX_custom-functions.tar.gz -C /var/spool/hylafax/bin/ --strip-components 1
$ rm HylaFAX_custom-functions.tar.gz

In the file 'notify', likewise located in the HylaFAX bin directory, the following line has to be added, ideally right after 'common-functions' is included:

. bin/custom-functions

Thereby the new functions are added to HylaFAX. In 'notify' it is then necessary to redirect the original invocation of 'BuildAttachArgs()'

ATTACH_ARGS="$ATTACH_ARGS "`BuildAttachArgs $ft`

to the new and extended function 'BuildAttachArgsMod()':

ATTACH_ARGS="$ATTACH_ARGS "`BuildAttachArgsMod $ft notify`

The original line is therefore replaced with the new one which also includes the added parameter 'notify'.

All it takes to completely deactivate the extensions and restore HylaFAX's default behaviour at any given time, is the restoration of the original line and the removal of the previous inclusion of 'custom-functions', or alternately the restoration of a 'notify' backup.

Please notice that HylaFAX updates may install newer versions of 'notify'. In this case, any changes to the file will be lost and have to be renewed. The same applies to 'faxrcvd' (see below)

If REPORT or REPORT+ is requested as file format, the new function 'CreateFaxReport()' is executed by 'ConvertFileMod()'. This function rescales the first page of a PDF file it is presented with to 60% of its original size and inserts the outcome into a transmission report. The transmission report is created in postscript format to begin with and occupied with the relevant fax transmission data. It is then equipped with appropriate header information (i.e., the fax transmission date as document creation date) and returned in PDF format.

'Identify()', a function provided by Imagemagick, is used to determine the dimensions of the given PDF file. This requires for Imagemagick to be installed:

$ apt-get install imagemagick

If this is undesired, page dimensions can instead be assessed with ghostscript and the postscript file 'pdf_info.ps' from the ghostscript toolbin. In this case the function 'PrepareReportCreation()' needs to be adapted (and the 'Identify()' command has to be be removed):

DIMENSIONS=($(gs -dNODISPLAY -q -sFile=$PDFIN -dDumpMediaSizes \ /var/spool/hylafax/bin/pdf_info.ps | \ grep MediaBox | sed "s/.*\[\(.*\)\].*/\1/")) PGWIDTH=${DIMENSIONS[2]};PGHEIGHT=${DIMENSIONS[3]}

Ghostscript is installed with HylaFAX by default. Should the script be modified in the before mentioned manner, 'pdf_info.ps' is expected to be in the HylaFAX bin directory. If the postscript file is saved elsewhere, the path to the file needs to be adjusted in the script.

The result: PDF fax transmission report

If everything was installed correctly, the content of the PDF report looks like this (without black bars in the original file, obviously):

example of a fax transmission report created by the extension to HylaFAX

Customizing attachment file names

Besides adding the option to receive PDF fax reports this HylaFAX extension also enables custom attachment file names. In order to not only use this feature with outgoing messages but also with incoming transmissions, the file 'faxrcvd' needs to be altered in similar fashion to the changes previously applied to 'notify'. The new functions have to be included by adding the line

. bin/custom-functions

and the invokation of 'BuildAttachArgs()' has to be redirected to 'BuildAttachArgsMod()':

ATTACH_ARGS="$ATTACH_ARGS "`BuildAttachArgsMod $ft faxrcvd`

This is once again achieved by replacing the original line with this new one. Please notice that the added argument is now 'faxrvcd' and not 'notify'.

Custom file names can then be set up in 'FaxNotify' and 'FaxDispatch'. An entry in the form of

CUSTOMNAME=fax_document

will have the following outcome:

Attachment name/old: doc12.ps
Attachment name/new: fax_document.12.ps
Attachment name/old: fax000000012.tif
Attachment name/new: fax_document.12.tif

The file numbering is inherited from HylaFAX and can be turned of:

FILENUMBERING=no

CUSTOMFILENAME is read as string. Underscores will be substituted for any characters but literals (i.e., letters and numbers), dots, hyphens and underscores. The fax transmission time and date are substituted for valid time and date sequences marked by a leading %-sign. Refer to the 'date()' man-page for details. With this file name pattern, for example:

CUSTOMFILENAME=%Y-%d-%m_fax_%H-%M-%S

a fax message sent on December, 24th in 1970 at 09:38:59 will result in filenames as follows:

Attachment name/old : doc12.ps Attachment name/new : 1970-12-24_fax_09-38-59.12.ps Attachment name/without no.: 1970-12-24_fax_09-38-59.ps

The custom file names are only applied to e-mail attachments. The original file names of documents on the server and in queue and log entries are not altered by design.

PDF fax reports triggered by REPORT and REPORT+ are labelled with distinct suffixes which precede the file extension in order to make them easily recognizable. The default names of fax reports thus end with '.report.pdf' and '.report+.pdf'. The suffixes can be customized in 'FaxNotify':

CUSTOMSUFFIXREPORT=simple
CUSTOMSUFFIXREPORT+=plus

will result in:

doc12.simple.pdf
doc12.plus.pdf

The suffixes can be removed entirely by configuring empty values:

CUSTOMSUFFIXREPORT=""
CUSTOMSUFFIXREPORT+=""

CUSTOMSUFFIXREPORT and CUSTOMSUFFIXREPORT+ are read as stings. Anything but letters, numbers, dots, hyphens, underscores and the plus-sign will be substituted with underscores.

Merging files if multiple documents are sent

When multiple documtens are sent in a single fax transmission, HylaFAX adds a seperate attachment for each file to its notification e-mails. This extensions adds the option to have all files of the same file format merged into a single file. This is enabled in 'FaxNotify':

FILEMERGING=yes

The setting is applied to all file formats except RAW. It is assumed that documents are supposed to remain as unaltered as possible if the file type RAW is selected. Thus no file merging is applied in this case.

The final touch

To make sure that fax reports are only received if fax transmissions have been successful and not if any errors occur which trigger an e-mail response with attached fax documents, an if-else statement can be used in 'FaxNotify', e.g.:

if [ "$WHY" != "done" ]; then
 RETURNFILETYPE="pdf"
else
 RETURNFILETYPE="pdf report"
fi

The variable '$WHY' carries information about the transmission status. Unless the status is 'done' no fax report is attached to e-mails. In cases of errors, only a copy of the sent document is returned. Alternatively one could go without individual copies of the sent documents entirely and merely request a REPORT+ in the success case.

To make incoming fax messages available over SMB, further code can be added to 'FaxDispach'. PDF copies of incoming fax messages are then shared in a designated network folder:

## PDF2Samba
##
## Creates a read accessible copy of incoming fax files in
## /smb/networkshares/fax

# example for website: original file name without file extension
# n=$(basename $FILE .tif)

# custom file name with transmission date/time
REGEXP="^[0-9]*:[0-9]*:[0-9]* [0-9]*:[0-9]*:[0-9]*$"
if [[ "$RECEIVED" =~ $REGEXP ]] ; then
 TXTIME=$(echo $RECEIVED | sed 's/^\([0-9]*\):\([0-9]*\):\([0-9]*\)/\1-\2-\3/')
else
 TXTIME=$(date +"%Y-%m-% %H:%M:%S")
fi
n=$(date +"%Y-%m-%d_fax_%H-%M-%S" -d "$TXTIME")

# defining target destination
t=/smb/networkshares/fax/$n

# creating PDF in target destination
$TIFF2PDF -o $t.pdf $FILE

# granting file access
chmod 644 $t.pdf

That's it! I hope you enjoy the added features or can benefit from the shared code in some other way.

If this site seems useful to you and you would like to say thanks, what I appreciate the most is a simple old school postcard from wherever you live (see imprint for address). If you make use of the shared information in a business environment, feel free to send me a small sample of whatever your business is involved with. This is completely optional, though. Only do this, if it sounds like a fun idea to you.

The publication of this site is mainly an attempt to give something back to the open source 'community', which has put tremendous effort into creating and documenting HylaFAX and related software (Debian, Asterisk, IAXmodem, ...), freely available for anyone to try out.

Please also notice that I cannot offer individual support or promise that I will maintain the extension if changes in future versions of HylaFAX require a major adaptation of the code. After all I am not a professional programmer but work in a completely different field and only do this out of fun and as a hobby.

Addendum

This text is a short version of an extended article in German language, which describes the installation of Asterisk, IAXmodem and HylaFAX in more detail.

This shorter summary is focused on my custom extensions to HylaFAX and intended to provide the necessary information for the installation and use of the extended features. The files offered on this site provide a fax report in English language.

If you prefer a PDF report in German language, please have a look at the corresponding chapter in the German article and use the localized files.