Post date: Jan 25, 2012 12:50:56 AM
The latest version of the Attachment To PDF service is now stand alone. It no longer requires any interaction with the QDS site and can be hosted locally.
Installation
Prior to deploying the AttachmentToPDF plugin the WebSupergoo ABCpdf.NET library must first be installed. It can be obtained from this site: http://www.websupergoo.com/abcpdf-1.htm. The current version of the AttachmentToPDF plugin (released 01/24/2012) supports ABCpdf.NET 8.1. Both 32Bit and 64Bit versions are available. Please us the 32Bit version. If you need to use the 64Bit version please contact QDS support at services.support@quandis.com.
A license will also need to be purchased from WebSupergoo.
Once the ABCpdf.NET library has been installed the qbo.Attachment.ABCPdf.dll will need to be copied to the C:\Program Files (x86)\Quandis\Quandis Business Objects v2.0.0\Bin folder.
The plugin supports ASP.NET v2 and ASP.NET v4
This plugin can be used as both an Attachment Template or an Event end point as a local assembly.
Attachment Template
To use the plugin with an AttachmentTemplate first register the dll in the AttachmentTemplate.config
Design -> Configuration -> Commands -> Attachment Template
Name: HtmlToPDF
Assembly: C:/Program Files (x86)/Quandis/Quandis Business Objects v2.0.0/Bin/qbo.Attachment.ABCPdf.dll
Assembly Namespace: qbo.Attachment.ABCPdf
<AttachmentTemplateAssembly>
<Name>HtmlToPDF</Name>
<AssemblyFile>C:/Program Files (x86)/Quandis/Quandis Business Objects v2.0.0/Bin/qbo.Attachment.ABCPdf.dll</AssemblyFile>
<NameSpace>qbo.Attachment.ABCPdf</NameSpace>
</AttachmentTemplateAssembly>
Then associate the plugin with an AttachmentTemplate. To Do so select it from the "Attachment Service" drop down.
The plugin expects an xml payload. At a minimum the xml must conform to the following:
<Root>
<PDFAttributes>
<Method/>
</PDFAttributes>
<Html>
<!--Html Content goes here-->
</Html>
</Root>
The <Method> element will contain the type of PDF operation requested. The details of this element will be covered below.
Typically the xml payload is produced by associating an xslt file with the Attachment Template which will also incorporate any associated report data and output the required xml specified above.
If you wish to override the default PDF generation settings you may include optional override values in a <PDFAttributes> element.
<Root>
<PDFAttributes>
<Method/>
<Landscape/>
<PaperSize/>
<AddFooter/>
<Footer/>
<AddPageNumber/>
<AddStandardFonts/>
<EmbedStandardFonts/>
<SaveTemporaryFiles/>
<Credentials>
<UserName/>
<Password/>
</Credentials>
<TempPath/>
<ImageQuality/>
<TimeOut/>
<RetryCount/>
<AddLinks/>
</PDFAttributes>
<Html>
<!--Html Content goes here-->
</Html>
</Root>
The details of these override elements will be covered below.
Event
To use the plugin with an event you must first register the dll in the Event.config
Design -> Configuration -> Commands -> Event Configuration
Name: HtmlToPDF (LocalEvent)
Assembly File: C:/Program Files (x86)/Quandis/Quandis Business Objects v2.0.0/Bin/qbo.Attachment.ABCPdf.dll
Assembly Name: HtmlToPDF
Assembly Namespace: qbo.Attachment.ABCPdf
<EventService>
<Compression>None</Compression>
<Name>HtmlToPDF</Name>
<Description />
<EventType>4</EventType>
<AssemblyFile>C:\Program Files (x86)\Quandis\Quandis Business Objects v2.0.0\Bin\qbo.Attachment.ABCPdf.dll</AssemblyFile>
<AssemblyName>HtmlToPDF</AssemblyName>
<AssemblyNamespace>qbo.Attachment.ABCPdf</AssemblyNamespace>
</EventService>
Then associate the event assembly with an Event. It should appear as one of the radio button options.
The event end-point expects an xml AttachmentCollection payload. At a minimum it must conform to the following:
<Action>
<Method Name="">
<ImportCollection>
<AttachmentCollection>
<!--More than one AttachmentItem can be included in the request. The PDF gneration engine will iterate through each and convert them to PDFs-->
<AttachmentItem>
<ObjectID/>
<Object/>
<SubscriberID/>
<Attachment/>
<!--***ONLY 1 of the 3 elements listed below should be provided***-->
<Content><!--Base 64 encoded html document--></Content>
<BodyHTML><!--Raw Html data--></BodyHTML>
<BodyText><!--Raw Html data--></BodyText>
</AttachmentItem>
</AttachmentCollection>
</ImportCollection>
</Method>
</Action>
The "Name" attribute of the <Method> element will contain the type of PDF operation requested. The details of this element will be covered below.
Typically the xml payload is produced by associating an xslt file with the Event which will also incorporate any associated report data and output the required xml specified above.
If you wish to override the default PDF generation settings you may include optional override values in a <Parameters> element.
<Action>
<Method Name="">
<ImportCollection>
<Parameters>
<Landscape/>
<PaperSize/>
<AddFooter/>
<Footer/>
<AddPageNumber/>
<AddStandardFonts/>
<EmbedStandardFonts/>
<SaveTemporaryFiles/>
<Credentials>
<UserName/>
<Password/>
</Credentials>
<TempPath/>
<ImageQuality/>
<TimeOut/>
<RetryCount/>
<AddLinks/>
</Parameters>
<AttachmentCollection>
<!--More than one AttachmentItem can be included in the request. The PDF gneration engine will iterate through each and convert them to PDFs-->
<AttachmentItem>
<ObjectID/>
<Object/>
<SubscriberID/>
<Attachment/>
<!--***ONLY 1 of the 3 elements listed below should be provided***-->
<Content><!--Base 64 encoded html document--></Content>
<BodyHTML><!--Raw Html data--></BodyHTML>
<BodyText><!--Raw Html data--></BodyText>
</AttachmentItem>
</AttachmentCollection>
</ImportCollection>
</Method>
</Action>
The details of these elements will be covered below.
Supported Methods
The AttachmentToPDF plugin supports the following operations:
HTML_ATTACHMENT_TO_PDF
This operation converts Raw Html or Base64 binary html data from within a content node in an AttachmentItem to a PDF document.
MERGE_PDF_ATTACHMENTS
This operation merges multiple PDF attachments within an attachment collection into a single PDF.
Attachments are appended from 1st to last. That is to say the 2nd attachment is appended to the end of the 1st. The 3rd is appended to the merged 1st and 2nd attachments, the 4th is appended to the merged 1st, 2nd, and 3rd attchments etc.
The final merged attachment will have the same name as the 1st AttachmentItem's <Attachment> element prefixed with "MergedPDFDoc_" and with the existing file extension replaced with "_.pdf". If you wish to change this value it is recommended that you use a poste-event transformation and replace the <Attachment> element's value as desired. The remaining AttachmentItem properties will remain unmodified. Only a single merged PDF will be returned within a single AttachmentItem.
MERGE_HTML_TO_PDF_ATTACHMENTS
This operation converts Raw Html or Base64 binary html data from within a content node in an AttachmentItem to a PDF document. It then merges the resulting PDF attachments into a single PDF.
***When the AttachmentToPDF plugin is used in an Attachment Template it only supports the HTML_ATTACHMENT_TO_PDF operation.
The operation name is to be placed within the <Method> element when the AttachmentToPDF plugin is used in an Attachment Template.
When using the AttachmentToPDF plugin from an event the operation name is to be placed in the "Name" attribute of the <Method> element.
Optional PDF generation override properties
Listed below are the AttachmentToPDF plugin properties. Each property has a default value that is automatically set. The default values maybe overridden as described below.
Landscape
Determines if the PDF produced is in Landscape mode or Portrait mode.
Accepts "true" or "false".
The DEFAULT value is "false".
PaperSize
Determines the paper size for each of the pages within the PDF
Accepts the following values:
"A3"
"A4"
"A5"
"B4"
"B5"
"Letter"
"Legal"
"Tabloid"
"Ledger"
"Statement"
"Executive"
"Folio"
"Quarto"
"10x14"
The DEFAULT value is "Letter"
AddFooter
Adds a footer to the bottom of each PDF page. Accepts "true" or "false".
The DEFAULT value is "true".
Footer
The default footer value can be overriden by providing a value in the <Footer> element. Doing so automatically sets the <AddFooter> value to "true".
Accepts a string value.
The default footer value is: "© 2004 - <CurrentYear> Quandis, All Rights Reserved. http: //www.quandis.com"
AddPageNumber
Adds a page number to the bottom of each page.
Accepts "true" or "false".
The DEFAULT value is "false".
AddStandardFonts
When a client opens the PDF Acrobat will attempt to find the exact same font on the client system. If the exact font is not available then a substitute font will be chosen using the font description to determine the best match.
The following fonts are guaranteed to be available on every system.
Times-Roman
Times-Bold
Times-Italic
Times-BoldItalic
Helvetica
Helvetica-Bold
Helvetica-Oblique
Helvetica-BoldOblique
Courier
Courier-Bold
Courier-Oblique
Courier-BoldOblique
Symbol
ZapfDingbats
Accepts "true" or "false".
The DEFAULT value is "false".
***If you wish to add a font not included in this list contact services.support@quandis.com
EmbedStandardFonts
The font name, a description of the font style and the the font glyph descriptions themselves are placed into the document. This ensures that the document will always display perfectly on every system and that font substitutions will never need to be made. There are a number of reasons you may not wish to embed fonts and instead use the AddFont method. Embedding fonts can increase the size of your PDF considerably. Additionally by distributing a PDF with an embedded font you are actually redistributing the font itself. You should check with your font supplier or legal department that you have permission to do this.
Accepts "true" or "false".
The DEFAULT value is "false".
***If you wish to embed a font contact services.support@quandis.com
SaveTemporaryFiles
Whenever a PDF is generated a copy of the raw html file and the produced PDF file are created on the file system using globally unique names. During normal operations these two files are automatically deleted as soon as operation is completed. Being able to view these files can be an aid in trouble shooting. Setting this value to "true" will prevent the operation from deleting these files.
Accepts "true" or "false".
The DEFAULT value is "false".
Credentials
In the event that images referenced in the raw html are located on a secured website, a user name and password can be provided to use for authentication. Once logged in ABCpdf stays logged in until the session times out. These properties are related to authentication methods built into HTTP. Methods like Basic (forms) Authentication and Windows Integrated Authentication. If the html page requires ASP.NET forms authentication please contact services.support@quandis.com.
The <Credentials> element contains two child elements; <UserName> and <Password>.
Each accepts a string value.
The DEFAULT behavior is not to use authentication.
TempPath
As mentioned above, whenever a PDF is generated a copy of the raw html file and the produced PDF file are created on the file system using globally unique names. The location of these temporary files can be overridden by changing the value of the <TempPath> element. Provided that the new value is a valid file path the operation will attempt to create it if it does not already exist.
Accepts a string value which should be a valid file path.
The DEFAULT location is "D:\Websites\temp\AttachmentToPDF_ScratchPad".
This value can also be overriden in the appsettings.config file: <add key="qbo.ABCpdf.TempPath" value="D:\Websites\temp\AttachmentToPDF_ScratchPad4" />.
ImageQuality
The quality of compression acceptable for continuous tone images such as JPEGs embedded within the PDF. Qualities should range between 0 and 100 (75 is a reasonable value). Values higher than 100 will result in lossless compression being used in all situations.
Accepts an integer value between 0 and 100.
The DEFAULT value is "75".
This value can also be overridden in the appsettings.config file: <add key="qbo.ABCpdf.ImageQuality" value="75" />.
TimeOut
The maximum amount of time allowed for obtaining a page. Increase this value if you have a large page of a large number of images, or large images.
Accepts an integer value.
This value is measured in milliseconds.
The DEFAULT value is 15500.
This value can also be overridden in the appsettings.config file: <add key="qbo.ABCpdf.TimeOut" value="20000" />.
RetryCount
The number of times a page should be retried if unavailable or invalid. The ABCpdf.NET library has a built in web browser that it uses to process the Html payload. HTML rendering may fail one time but succeed the next. This is often for reasons outside the control of ABCpdf. So ABCpdf may attempt to re-request a page if it is not immediately available. This is analogous to clicking on the refresh button of a web browser if the page is failing to load.
Accepts an integer value.
The DEFAULT value is 5.
This value can also be overriden in the appsettings.config file: <add key="qbo.ABCpdf.RetryCount" value="10" />.
AddLinks
This property determines whether links in HTML are reproduced as links in the final PDF output. Links which are not live look exactly like links but do not link through to a destination when you click on them. Live links are reproduced exactly as specified on the page and link through to the web pages specified. These web pages will open in a new browser window.
Accepts "true" or "false".
The DEFAULT value is "true"
Samples and DLLs
The DLL can be found in "Source\core.quandis.com.2.0\CompiledOutput\"
The file name is qbo.Service.AttachmentToPDF_20.dll
Samples seed scripts can be found in "Source\core.quandis.com.2.0\qbo.Core\Database Tier\qbo.Database.Attachment\Create Scripts"
You will need these two files for the Attachment Template:
Minimal PDF.xslt
Setup.AttachmentTemplate.HtmlToPdf.xml
You will need this file for the Event
Setup.Event.HtmlToPDF.xml
Changing Scratchpad path
By default, abc.pdf will write temp files to a default scratchpad location in C:\windows\temp\. QDS has observed the component does not always clean up after itself and files accumulate. This can put the OS drivespace at risk. You can optionally override this folder by adding registry key:
For 32 bit IIS running on x64 (default)
regedit
HKLM/SOFTWARE/Wow6432Node/WebSupergoo/ABCpdfNET/7
Add string value->"TempDirectory"
We use D:\temp\AttachmentToPDF\ScratchPad\
Ensure path exists and users have full control
IIS reset will clear the folder regardless of where the path is set