Introduction

BI Publisher allows the use of advanced form fields such as checkboxes to both ease development and create a more professional, modern looking product.

Often, report requirements specify functionally working checkboxes reflecting report data rather than a static image.  We can insert checkboxes into our RTF documents that are controlled by the data at the time of generation.

Checkboxes in RTF templates are created by a special MS Word control rendering based upon a True/False condition.   These are translated at runtime as per the server’s BI Pub configuration file into a special font character inserted into the page.

The font is most often “Wingdings”, which contains several characters representing checked and unchecked boxes.  It is important to note that the font characters chosen for checked/unchecked boxes are set at the server level, not the individual report.   Once you decide on a specific checkbox style, all reports generated on that server will use the same font character for a checked/unchecked box.

Configure MS Word for BI Pub Checkmarks

Install the BI Publisher Design Helper Plug-in for Microsoft Word and Excel.

The design helper for your version of BI Publisher can be found in your PeopleSoft application. 

Navigation: Home > Reporting Tools > BI Publisher > Setup > Design Helper

Be sure to choose the correct 32/64 bit version depending on which version of MS Word is installed on your machine.

Enable the “Developer” tools on MS Word’s Ribbon Menu.

In MS Word, click on “File”

then “Options”

Select the “Customize Ribbon” menu and then check the “Developer” box

Configure the xdo.cfg on your local machine

Xdo.cfg is the file BI Publisher uses to set various parameters and defaults.    We need to alter this file so templates rendered on your local machine at design time will have the checkbox.

Find the directory on your local machine.  Since I’m using the 64-bit version of MS Word and matching 64-bit template helper, my config file is located here:

C:\Program Files\Oracle\BI Publisher\BI Publisher Desktop\Template Builder for Word\config\

“xdo.cfg” Vs. “xdo example.cfg”

If this is the first time modifying this file, there may not be an “xdo.cfg” file, but “xdo example.cfg” will exist in this directory.   Copy “xdo example.cfg” to “xdo.cfg”.   Edit only the “xdo.cfg” file.

There are two sections to update: properties and fonts.

Properties

Add the following snipped to the <properties> section:

<property name="rtf-checkbox-glyph">Wingdings;254;168</property>

Fonts

 Add the following snipped to the <fonts> section:

      <!-- Windows Wingdings font -->
      <font family="Wingdings" style="normal" weight="normal">
       <truetype path="C:\Windows\Fonts\wingding.ttf" /> 
      </font>

Config File Path References

 Review that paths in the config file to ensure they are correct.  In particular, ensure the “system-temp-dir” property points to a valid directory on your computer and the font paths are correct.

See Appendix A for a full listing of my xdo.cfg file.

rtf-checkbox-glyph Parameters

The “rtf-checkbox-glyph” has three parameters:

1. Font
2. Font Character if true
3. Font Character if false (not true)

The Template is going to pass the glyph and a true/false Boolean value to the server at that specific report character render time.  The server will place the appropriate font character in the report.

Often used Wingdings Fonts

Character	Description	Glyph
254	Checked Box
253	“X” Box
168	Unchecked Box

You may choose whichever font and characters you like for the checkboxes.  Remember these choices will be used for the checkboxes in every report rendered on that machine, not just one specific report.

Configure BI Pub configuration file on all servers

Every server that generates BI Pub reports must have the configuration file updated.  If not, the check boxes will render to something in the report’s default font, but not a checkbox.

Remember that both Report and Application servers have BI Pub servers installed.

Installing BI Publisher, fonts and configuration files is usually the responsibility of the PS Admins.   Once the xdo.cfg is defined for an implementation, it must become part of their procedures for every time a new server is added, or upgrade/patch is installed, affecting the configuration files on each server.

Adding a checkbox to an RTF Template

Adding a checkbox to the template is easy.  Just add a checkbox control and define the Boolean evaluation controlling the checkbox.

Place your cursor where you would like the checkbox.

Choose “Developer” on the Ribbon menu and ensure “Design Mode” is enabled

Click the down arrow next to the “Legacy Tools” icon and choose the checkbox from the “Legacy Forms” group.

Add the logic to the checkbox

1. Double click on the checkbox control
2. Default Value = Not Checked
3. Click on the “Add Help Text” button
4. Add in the BI Publisher xsl tag to activate it based upon a value of a field by creating a Boolean evaluation.      

Example:  If the field fld_PAY_CONFIRM_RUN = “Y”, then the checkbox will check, else it will default to Not Checked.

<?fld_PAY_CONFIRM_RUN='Y'?>

BI Publisher will be looking for the exact values to check the box. 

• The value can be a multiple character value or numeric value.  If it doesn’t match exactly, it won’t check.
• String values denoted by the single quote              <?fld_NAME=’Bob’?>
• Numeric values are not quoted:                                 <?fld_COST=5?>

Test your template.

Documentation

PeopleTools PeopleBooks BI Publisher

Oracle Document 1428009.1

Where’s My Checkboxes

Fusion Middleware Report Designer’s Guide for Oracle Business Intelligence Publisher

Appendix A

“xdo.cfg” listing for Windows 10 machine using 64-bit MS Word

<config version="1.0.0"  xmlns="http://xmlns.oracle.com/oxp/config/">
    <!-- Properties -->
    <properties>
        <!-- System level properties -->

        <!-- PLEASE SELECT A VALID TEMPFILE DIRECTORY!!! -->
        <property name="system-temp-dir">c:/Temp</property>

        <!-- PDF compression -->
        <property name="pdf-compression">true</property>

        <!-- PDF security -->
        <property name="pdf-security">false</property>
        <property name="pdf-open-password">user</property>
        <property name="pdf-permissions-password">owner</property>
        <property name="pdf-no-printing">true</property>
        <property name="pdf-no-changing-the-document">true</property>

        <property name="rtf-checkbox-glyph">Wingdings;254;168</property>  
    </properties>

   <!-- Font setting -->
    <fonts>

      <!-- Windows Wingdings font -->
      <font family="Wingdings" style="normal" weight="normal">
       <truetype path="C:\Windows\Fonts\wingding.ttf" /> 
      </font>

      <font family="GnuMICR" style="normal" weight="normal">
       <truetype path="C:\Windows\Fonts\GnuMICR.ttf" /> 
      </font>

      <font family="Times New Roman" style="normal" weight="normal">
       <truetype path="C:\Windows\Fonts\TIMES.ttf" /> 
      </font>

      <font family="3 of 9 Barcode" style="normal" weight="normal">
       <truetype path="C:\Windows\Fonts\3of9.ttf" /> 
      </font>

    </fonts>
</config>