DocumentBurster™ variables are pieces of information from the input report, evaluated and processed individually for each output report.
Variables can be used to define dynamic configurations as well as data to be included in the delivery of documents. For example, using an email message template together with variables it is possible to define a personalized email subject/message for each individual recipient.
Variables can be used to define custom dynamic values for the following configurations
- Burst File Name
- Output Folder
- Backup Folder
- Quarantine Folder
- Upload (FTP, File Share, etc.) commands and URLs can be dynamically generated
- Email To, CC and BCC fields can be dynamically generated
- Email subject and message text can be personalized using variables
- Email connection settings can be customized using variables. From Name, From Email Address, Host, User Name, User Password and Port settings are all configurable using variables.
Using variables, the values of the above configurations can be dynamically populated at run-time with information coming from the report which is being burst.
While it is possible to define static values for the output folders, it is not advisable. In order to avoid the output reports to get overridden from one burst session to another, with the help of variables, it is better to define dynamic time-stamp based output folder configurations.
Following are few situations in which variables will help
- The same report is being burst at different times. Bursting the same report to the same statically defined output folders will override the files generated during previous burst sessions.
- Few different reports are using the same burst tokens (for example the email address of the same client). Having a common output folder will result in getting the generated reports to be overridden between different burst sessions. This is happening because the same burst token is found in different input reports.
Using variables, with unique time-stamp based values generated at run-time, it is possible to overcome the above described problems by defining unique output folder names per each different burst session.
Output Folder, Backup Folder and Quarantine Folder configurations are all defined using the same pattern $input_document_name$/$now; format="yyyy.MM.dd_HH.mm.ss"$
When bursting the input sample document
Payslips.pdf,
by default, the output files are being generated in a folder
similar
with
Payslips.pdf/2010.10.28_19.13.13
-
$input_document_name$/$now;
format="yyyy.MM.dd_HH.mm.ss"$.
Built-In vs. User-Defined Variables
DocumentBurster™ has two types of variables
Built-In Variables
User-Defined Variables
Built-in variables can be the name of the report to burst, the date (in various formats) when the bursting is happening or the current burst token.
Following built-in variables are available to be used within DocumentBurster™
- $input_document_name$ - the file name of the input report
- $input_document_extension$ - the file extension of the input report. It will be pdf for PDF input reports, xls for Excel versions prior to 2007 and xlsx for Excel 2007 and Excel 2010.
- $burst_token$ - the burst token which is used for bursting the current file
- $burst_index$ - the index of the burst file. For example, a file which will be burst fourth will have the value 4
- $output_folder$ - the output folder where the last file was extracted
- $extracted_file_path$ - the path to the last extracted file
- $now; format="yyyy.MM.dd_HH.mm.ss"$
- the current date and time displayed in the specified format.
Custom
date formats
can be specified also, for example it is possible
to
display the full date/time or display
one or a
combination of year,
month, week, day, hour, minute,
second.
yyyy.MM.dd_HH.mm.ss
is the format which is provided with the software.
Note
Windows doesn't allow to use the character : when defining folder and file names.
- $now_default_date$ - shortcut to the default date format in the computer's locale settings. U.S. Locale example would be Jun 30, 2009
- $now_short_date$ - shortcut to the short date format in the computer's locale settings. U.S. Locale example would be 6/30/09
- $now_medium_date$ - shortcut to the medium date format in the computer's locale settings. U.S. Locale example would be Jun 30, 2009
- $now_long_date$ - shortcut to the long date format in the computer's locale settings. U.S. Locale example would be June 30, 2009
- $now_full_date$ - shortcut to the full date format in the computer's locale settings. U.S. Locale example would be Tuesday, June 30, 2009
Using built-in variables it is possible to build an advanced foldering and archiving solution for the output reports.
Following different foldering options are possible. Combinations of the following are also possible
Generate one different output folder per each input report
Generate one different output folder per each different burst token
Date related options - generate one output folder per year, financial quarter, month, week in month, day in week and up to the level of hours, minutes and seconds.
DocumentBurster™ is coming with the following default settings
Burst File Name - $burst_token$.$input_document_extension$
When bursting the
samples/Payslips.pdf
report following three
files are being generated. The three email
addresses are the burst tokens and
pdf
is the input
document extension.
User defined variables can be any text from the report which is being burst or distributed.
User variables might be used for sending emails with a personalized subject and a personalized message text or for generating dynamic file names and folder names for the output burst reports.
DocumentBurster™ has support for up to 10 (ten) user defined variables $var0$, $var1$, $var2$, $var3$, $var4$, $var5$, $var6$, $var7$, $var8$ and $var9$. While the variable names are not impressive they are for sure handy to use.
The values for the user defined variables are being populated with text content from the report which is being burst. Usually the variables will have different values for each different burst token (or for each different recipient).
In order to populate the user defined variables with values, DocumentBurster™ engine is looking inside the report for patterns like the following
<0> any text which should be assigned as a value to the first variable </0> or
<1> any text which should be assigned as a value to the second variable </1>
DocumentBurster™ engine supports up to 10 (ten) different variables, so the last variable will look like <9> any text which should be assigned as a value to the 10th variable </9>.
User defined variables can be used to dynamically generate any of the following Burst File Name, Output Folder, Backup Folder, Quarantine Folder, Upload(FTP, File Share, etc.) commands and URLs, Email To, CC and BCC fields, Email Subject, Email Message Text, From Name, From Email Address, Host, User Name, User Password and Email Server Port.
With the default settings, DocumentBurster™ is generating the output file names using the following configuration
Burst File Name
-
$burst_token$.$input_document_extension$
where
$burst_token$
is the system built-in variable used to burst
the separate files and
$input_document_extension$
is the input file
extension (i.e.
pdf, xls or xlsx).
Requirement
For example, a requirement might be to generate the output file names (Burst File Name) using the following pattern
Customer name-Invoice number-Invoice date.pdf
The requirement can be achieved with the help of user defined
variables.
Please check
samples/Invoices-Oct.pdf
sample report to see that
Invoice number
field is configured as burst token and
Customer name
and
Invoice date
fields are mapped to
$var1$
and
$var0$
user variables.
Burst File Name
will be defined as
$var1$-$burst_token$-$var0$.pdf
$burst token$, $var0$ and $var1$ variables will be populated at run-time with values fetched from each separate report.
- Variables are fetched at run-time from each separate invoice. DocumentBurster™ is looking for <N>value</N> patterns in each invoice, where N is from 0 to 9.
-
In the above example the name of the generated file will be
Alpha Electric-0011-Oct 10, 2011.pdf
Using the previous configuration, bursting
samples/Invoices-Oct.pdf
will generate
the following four distinct files
Note
Use a white font color for the start and the end tags of the variables, (e.g. <0> and </0>) so that the visual appearance and the layout of the report will not be affected.
Important
Before going to production, it is advisable to practice the use of variables on few sample reports. This is to avoid any unpleasant situation of sending wrong data to clients or customers.
While the concept and the usage for the user defined variables are the same with the PDF reports, Excel user defined variables are defined like the following example
- If required, Excel user-defined variables can be declared in the userVariables column from burst metadata sheet
- Similarly with the PDF variables, Excel user-defined variables are enclosed in between <0>value</0>,<1>value</1> and so on.
- The value for var0 user variable (associated with Germany burst token) is Alfreds Futterkiste and the value for var1 is Berlin. The values for the USA burst token are the ones which are presented in the screenshot.