This article is outdated. To learn how to configure custom PDF conversion tools for BSS, use the following instructions:
Description
This article describes two additional PDF converting utilities for Billing:
PD4MLhttp://pd4ml.com/wkhtmltopdfhttp://wkhtmltopdf.org/
These utilities must be installed along with Billing. They are used for generating notifications sent to Customers and Mass Printing.
Disclaimer: Any supplementary scripts and libraries are not the part of Billing solution and are not officially (fully) supported.
The main requirements for these tools:
- The ability to create PDF files that are one on one copy of the html notification template;
- Support of special characters - like currency signs, etc;
- Support of formatting features - like pageformat, paper size, orientation, etc;
- Support for Mass Printing.
PD4ML
a. Installation
PD4ML is a commercial library for use in Java and .NET program code. However it is supplied with precompiled java class which can be used from the command line.
In order to use PD4ML features you need to install java JRE package on your Billing Application container. Following package is preferred (for CentOS):
java-1.7.0-openjdk
1) Obtain the library.
Here http://pd4ml.com/download.htm we can obtain the trial version of the library.
The library is supplied in two editions - Standard and Pro. As described in the products comparison chart, some features (merging the documents for Mass Printing and embedding the fonts in order to support special characters) are supported only in Pro version.
2) Unzip the archive in some internal directory on Billing Application Server, for example:
/usr/local/bm/tools/pd4ml
3) Change <PD4ML_ROOT>/lib directory owner to pba:
# cd <PD4ML_ROOT>/lib
# chown -R pba:pba lib
4) Download fonts archive http://download.pa.parallels.com/csd/PDFCONVERTERS/fonts.zip and extract it into PD4ML_ROOT/lib directory
Note: These fonts are not supported by Odin.
5) Download script http://download.pa.parallels.com/csd/PDFCONVERTERS/pd4ml.pl and place it into <PD4ML_ROOT>/lib directory.
Note: This script is the example of integration PD4ML and Billing and it is not supported officially.
6) Allow file to be executed:
# chmod +x pd4ml.pl
7) Edit the script file:
$pd4ml_root - <PD4ML_ROOT>/lib directory;
$page_width - width of the page in the document. Must correspond the width in html template;
$orientation - document orientation (portrait or landscape);
$fonts_dir - directory with fonts to be embedded;
$page_format - document page format (A4, Letter, etc);
Note: this script is the example of how the library can be used. It does not implement all the features and parameters that library support.
To configure more print parameters you can edit script lines 27 (for single PDF conversion) and 34 (for Mass Printing). In the following example you can see how parameters can be added (e.g. -fitapage, -ttf etc):
system ("java -Xmx512m -Djava.awt.headless=true -cp pd4ml_demo.jar Pd4Cmd file:$input_file $page_width $page_format -fitapage -ttf $fonts_dir -debug -orientation $orientation -out $output_file") == 0
8) Configure Billing: System > Settings > System > Notifications > Other > PDF Conversion Settings
Set the following parameters:
PDF Conversion Command : <PD4ML_ROOT>/lib/pd4ml.pl @@SrcName@ @@DstName@
PDF Conversion Command for Mass Printing : <PD4ML_ROOT>/lib/pd4ml.pl @@SrcNames@ @@DstName@
b. Usage
For how to configure notification templates and enable notifications in PDF format see general Billing Documentation. After everything is configured correctly notifications will be sent in PDF format converted by PD4ML utility. Mass Printing is done manually in Billing.
The full list of the parameters and their values that can be set for this utility can be seen here http://pd4ml.com/html-to-pdf-command-line-tool.htm
To use these parameters they must be manually added to pd4ml.pl script file.
c. Limitations
It is important to mention that Mass Printing can be done only with PD4ML Pro edition. It is done with the help of its merge function.
Support for special characters is also available only with Pro edition. The reason for this is that PD4ML by default support only Latin-1 character set and the support for unicode characters is done by embedding the necessary fonts into the document.
So, to get access to embedded fonts and mass printing you need to obtain PRO verion of library. Just put the font files you need to <PD4ML_ROOT>/lib/fonts directory and run pd4font.properties generation command.
For details see:
PD4ML Reference Manual: http://pd4ml.com/reference.htm
TTF Embedding: http://pd4ml.com/support/pd4ml-html-css-pdf-tips-tricks-f7/ttf-embedding-t42.html
wkhtmltopdf
a. Installation
wkhtmltopdf is open source (LGPL) command line tool to render HTML into PDF using the QT Webkit rendering engine.
1) Download the installation package: http://wkhtmltopdf.org/downloads.html
2) Install the package in your OS
For example, in CentOS:
# yum --nogpgcheck localinstall wkhtmltox-0.12.2.1_linux-centos6-amd64.rpm
3) Configure Billing: System > Settings > System > Notifications > Other > PDF Conversion Settings
Set the following parameters:
PDF Conversion Command : /usr/local/bin/wkhtmltopdf @@SrcName@ @@DstName@
PDF Conversion Command for Mass Printing : /usr/local/bin/wkhtmltopdf @@SrcNames@ @@DstName@
b. Usage
For how to configure notification templates and enable notifications in PDF format see general Billing Documentation. After everything is configured correctly notifications will be sent in PDF format converted by wkhtmltopdf utility. Mass Printing is done manually in Billing.
Formatting and other parameters are set directly in the Conversion command. To comply the requirements these parameters must be used:
--page-size <size> - this sets the page size in the document (A4, Letter, etc);
--orientation <orientation> - this sets the page orientation (portrait, landscape);
--encoding <encoding> - this sets the encoding to use (i.e. utf-8). It is necessary to get support for special characters.
As an example of PDF Convertion Command:
/usr/local/bin/wkhtmltopdf --page-size A4 --orientation portrait --encoding utf-8 -B 5 -L 5 -R 5 -T 5 @@SrcName@ @@DstName@
All other parameters of formatting (page margins, page height and width, footers and headers) can be seen here http://wkhtmltopdf.org/usage/wkhtmltopdf.txt
To make fonts in the email and attached PDF equal (in other words, to make special characters like Euro currency sign appear in PDF) you can:
install used in email fonts on Billing Appplication node. Below some free linux fonts packages that can be installed:
texlive-texmf-errata-fonts-2007-7.1.el6.noarchurw-fonts-2.4-10.el6.noarchxorg-x11-fonts-75dpi-7.2-9.1.el6.noarchxorg-x11-fonts-Type1-7.2-9.1.el6.noarchtexlive-texmf-fonts-2007-38.el6.noarchfontconfig-2.8.0-3.el6.x86_64xorg-x11-font-utils-7.2-11.el6.x86_64fontconfig-devel-2.8.0-3.el6.x86_64libfontenc-1.0.5-2.el6.x86_64libXfont-1.4.1-2.el6_1.x86_64ghostscript-fonts-5.50-23.1.el6.noarch- or you can use Google Web Fonts. Here is the guide how to use Google Web Fonts: http://designshack.net/articles/css/a-beginners-guide-to-using-google-web-fonts/.
For support of Chinese characters install wqy-zenhei-fonts (yum install wqy-zenhei-fonts).
c. Limitations
No special limitations found.
Conclusion
wkhtmltopdf is powerful and simple to use. It can be supported by Billing as an alternative to htmltodoc. This tool allows to get printable document one on one as the html template including all document styles.
PD4ML has a number of limitations:
1) Mass Printing only in Pro Edition;
2) Unicode characters only in Pro Edition;
3) By design library doesn't allow to merge at the same time multiple files into single document. As workaround supplementary script can be used.
PD4ML library can not be officially supported by Billing and it is not recommended to use.