Configuration‎ > ‎

Attachment To PDF Documentation

posted Jan 24, 2012, 4:50 PM by Unknown user   [ updated Mar 8, 2012, 4:05 PM by Greg Kent ]
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

<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
 
Comments