How do I correctly Tag a document for PDF-eXPLODE processing - what are the rules for a tag?

ISSUE:

Incorrect exploded file names or archived folders are only a few of the errors I seem to get in the Log. What are the rules for a Tag?



ANSWER:

What is a "TAG"?

A "Tag" is a string of text embedded in the report, in a specific format conforming to some rules you set, which allows the report to communicate with PDF-eXPLODE. PDF-eXPLODE will process the rules based on the order of the Tag text from left to right, provided that the tag conforms to the rules shown below. 

The tag consists of 3 sections, each optional but at least one part must exist on a page between a pair of front and back nodes ( <pdfexplode> </pdfexplode> )

You insert PDF-eXPLODE tags in your documents to indicate which settings to use when exploding and e-mailing documents. The general format is:

<pdfexplode> variables% messageID# e-mails </pdfexplode>

The ‘%’ indicates the end of Variables , whereas as ‘#’ confirms that the word infront of it is a Message ID . The email address must always be at the end of the tag.  Each part is optional. You must have at least one or more of Variables, Message ID or email addresses. If you have nothing between the open and close nodes, then PDF-eXPLODE will convert that page to a 'blanktag.pdf'. 

You insert a "tag" on each page, typically as the first line in the page header, as this tag will automatically be displayed on each page. However there is no restriction to creating a tag in the body of your report or even the Group header or footer; however since Group headers and footers do not always repeat on each page, this means that you may not achieve your desired delivery result.  The tag can be in the following standard format:

<pdfexplode>Message_ID_name#client@email.com</pdfexplode> OR
<pdfexplode>client@email.com</pdfexplode>

• All tags must start ("open") with <pdfexplode> and end ("close") with </pdfexplode> - these are known as "nodes" or "Left/Right Identifiers"
• Open and close tags (aka Identifiers) must match one another in case (i.e. both must be either uppercase or  lowercase).
• All tags should include a client identifier like an e-mail address or a filename e.g.:  <pdfexplode> my_name@myDomain.com </pdfexplode>  or <pdfexplode> Commission </pdfexplode>
• An optional message identifier, if used, must precede the client identifier and be followed by a pound sign (#) e.g.:  <pdfexplode> Invoices# my_name@MyDomain.com</pdfexplode>
• Tags must be formatted with the Arial or Times New Roman font, and the color may be set to White to hide the tag. The tag's font pitch must be NO LESS than 7 pitch.
• All tags must fit entirely on one line and must never run into other document text or graphics
• You may include as many tags per page as desired, each on a separate line
• The total length of a tag excluding the "open"/"close" <pdfexplode> nodes must be less than 190 characters (Version 2 & 3) and 225 characters (Version 4 ++)

The Maximum Tag length allowance is dependent on two Windows restrictions - MAX_PATH is a Windows imposed restriction that takes :

•  the length of the [File Path] +  length of the [File name including extension]   must be <= 259 characters

             Where this is exceeded, Windows will block the creation of the file

The other consideration is the Maximum Filename length

• The temporary filename made out of the tag text cannot exceed 255 characters. Keep in mind that PDF-eXPLODE exploding engine creates a temporary file of all pages with the exact same tag and the filename assigned, is the full tag text. To this Tag text, the exploding engine adds ' _expl.pdf ' (9 characters) plus 1 character for the end of file marker, a total of 10 characters. So essentially:
• the tag text cannot exceed 255 - 10 - length of Master PDF path (generally around 20 characters if your Master is saved in the default C:\PDF-eXPLODE\PDFS\ file path). So in this case, the maximum tag text length including spaces is 255 - 10 (temporary file add-on) -20 (default Master PDF path) = 225 characters. However, this maximum tag text length will vary depending on the Master PDF file path length.

If  your actual tag length + path > 255,   the program will "Hang" or you get a Windows error and no further processing will occur.

If that happens, reduce the size of your tag and move the file save path to a shorter exploding folder path. Alternatively, contact 3000AD Systems for a pdfexplode.dll patch (exploding engine) if you are using PDF-eXPLODE Version 4.1.26.97 Nov 2016 or later. 

 Use of Illegal or 'Reserved characters in  Tag Text

Do not use any of these common illegal characters/symbols:  

Also, keep these rules in mind.

• Don’t start or end your filename with a space, period, hyphen, or underline.
• Keep your file names to a reasonable length and generally to a maximum of 31 characters.   

FOR PDF-eXPLODE :

The following rule must be borne in mind when deciding on which character can and can't be used in the PDF-eXPLODE tag

Tag text cannot contain any  Windows illegal characters  like

PDF-eXPLODE Tag  Variables or the Message ID text cannot contain these reserved characters:

Article ID: 33
Created On: Thu, Dec 4, 2014 at 5:20 PM
Last Updated On: Wed, Sep 1, 2021 at 1:27 AM

Online URL: https://kb.pdf-explode.com/article/how-do-i-correctly-tag-a-document-for-pdf-explode-processing-what-are-the-rules-for-a-tag-33.html