Creating Excel Templates in oracle XML report

3.1 Overview

An Excel template is a report layout designed in Microsoft Excel for retrieving and formatting enterprise reporting data in Excel. Excel templates provide a set of special features for mapping data to worksheets and for performing additional processing to control how the data is output to Excel workbooks.

3.1.1 Features of Excel Templates

With Excel templates you can:

• Define the structure for the data in Excel output
  
• Split hierarchical data across multiple sheets and dynamically name the sheets
  
• Create sheets of data that have master-detail relationships
  
• Use native XSL functions in the data to manipulate it prior to rendering
  
• Use native Excel functionality
  

3.1.2 Limitations of Excel Templates

The following are limitations of Excel templates:

• For reports that split the data into multiple sheets, images are not supported. If the template sheet includes images, when the data is split into multiple sheets, the images are displayed only on the first sheet.
  
• BI Publisher does not provide a tool to facilitate the markup of the template with BI Publisher tags; all tags must be manually coded. Some features require the use of XSL and XSL Transformation (XSLT) specifications
  

3.1.3 Prerequisites

Following are prerequisites for designing Excel templates:

• Microsoft Excel 2003 or later. The template file must be saved as Excel 97-2003 Workbook binary format (*.xls).
  
• To use some of the advanced features, the report designer must have experience with XSL and XSLT.
  
• The report data model has been created.
  

3.1.4 Supported Output

Excel templates generate Excel binary (.xls) output only.

3.1.5 Desktop Tools

You can use the Template Viewer to preview Excel templates from your desktop.
The Template Viewer is installed automatically when you install the Template Builder for Word. For information on obtaining the utility, see the topic "Installing Oracle BI Publisher Desktop Tools" in the Oracle Business Intelligence Publisher Installation Guide.

3.2 Concepts

Similar to RTF template design, Excel template design follows the paradigm of mapping fields from the XML data to positions in the Excel worksheet. Excel templates make use of features of Excel in conjunction with special BI Publisher syntax to achieve this mapping. In addition to direct mapping of data elements, Excel templates also utilize a special sheet (the XDO_METADATA sheet) to specify and map more complex formatting instructions.

3.2.1 Identifying Data Field Placeholders and Groups

Excel templates use named cells and groups of cells to enable BI Publisher to insert data elements. Cells are named using BI Publisher syntax to establish the mapping back to the XML data. The cell names are also used to establish a mapping within the template between the named cell and calculations and formatting instructions that are defined on the XDO_METADATA sheet.
The template content and layout must correspond to the content and hierarchy of the XML data file used as input to the report. Each group of repeating elements in the template must correspond to a parent-child relationship in the XML file. If the data is not structured to match the desired layout in Excel it is possible to regroup the data using XSLT preprocessing or the grouping functions. However, for the best performance and least complexity it is recommended that the data model be designed with the report layout in mind.

Note:

See Section 3.6, "Preprocessing the Data Using an XSL Transformation (XSLT) File" and Section 3.5.3, "Grouping Functions" for more information about these options.

3.2.2 Use of Excel Defined Names

The Excel defined names feature is used to identify data fields and repeating elements. A defined name in Excel is a name that represents a cell, range of cells, formula, or constant value.

Tip:

To learn more about defined names and their usage in Microsoft Excel 2007, see the Microsoft help topic: "Define and use names in formulas."

The defined names used in the Excel template must use the syntax described in this chapter, as well as follow the Microsoft guidelines described in the Microsoft Excel help document. Note that BI Publisher defined names are within the scope of the template sheet.

3.2.3 About the XDO_ Defined Names

The BI Publisher defined names are Excel defined names identified by the prefix "XDO_". Marking up the placeholders in the template files creates the connection between the position of the placeholders in the template and the XML data elements, and also maintains the ability to dynamically grow data ranges in the output reports, so that these data ranges can be referenced by other formula calculations, charts, and macros.

3.2.4 Using Native Excel Functions

You can use the XDO_ defined names in Excel native formulas as long as the defined names are used in a simple table. When a report is generated, BI Publisher automatically adjusts the region ranges for those named regions so that the formulas calculate correctly.
However, if you create nested groups in the template, then the cells generated in the final report within the grouping can no longer be properly associated to the correct name. In this case, the use of XDO_ defined names with native Excel functions cannot be supported.

3.2.5 About the XDO_METADATA Sheet

Each Excel template requires a sheet within the template workbook called "XDO_METADATA". Use this sheet to identify the template to BI Publisher as an Excel template. This sheet is also used to specify calculations and processing instructions to perform on fields or groups in the template. BI Publisher provides a set of functions to provide specific report features. Other formatting and calculations can be expressed in XSLT.
It is recommended that you hide the XDO_METADATA sheet before you upload the completed template to the BI Publisher repository. This specification prevents report consumers from seeing it in the final report output.

Note:

For more information see Section 3.3.4.1, "Format of the XDO_METADATA Sheet" and Section 3.5, "Defining BI Publisher Functions."

3.3 Building a Simple Template

This section demonstrates the concepts of Excel templates by walking through the steps to create a simple Excel template and testing it with the Template Viewer. This procedure follows these steps:

• Step 1: Obtain Sample XML Data from the Data Model
  
• Step 2: Design the Layout in Excel
  
• Step 3: Assign the BI Publisher Defined Names
  
• Step 4: Prepare the XDO_METADATA Sheet
  
• Step 5: Test the Template
  

3.3.1 Step 1: Obtain Sample XML Data from the Data Model

You need sample data in order to know the element names and the hierarchical relationships to properly mark up the template.
To save data from the report viewer:

1. From the Report Editor or from the Reports page, select View.
   
2. If no layouts are defined for your report, then the output type will default to xml, otherwise, choose data for the output type.
   
3. Select Export. Save the results as an XML file to a local directory
   

The sample data for this example is a list of employees by department. Note that employees are grouped and listed under the department.

<?xml version="1.0" encoding="UTF-8"?>
<DATA>
 <DEPT>
   <DEPARTMENT_ID>20</DEPARTMENT_ID>
   <DEPARTMENT_NAME>Marketing</DEPARTMENT_NAME>
     <EMPS>
       <EMPLOYEE_ID>201</EMPLOYEE_ID>
       <EMP_NAME>Michael Hartstein</EMP_NAME>
       <EMAIL>MHARTSTE</EMAIL>
       <PHONE_NUMBER>515.123.5555</PHONE_NUMBER>
       <HIRE_DATE>1996-02-17T00:00:00.000+00:00</HIRE_DATE>
       <SALARY>13000</SALARY>
     </EMPS>
     <EMPS>
       <EMPLOYEE_ID>202</EMPLOYEE_ID>
       <EMP_NAME>Pat Fay</EMP_NAME>
       <EMAIL>PFAY</EMAIL>
       <PHONE_NUMBER>603.123.6666</PHONE_NUMBER>
       <HIRE_DATE>1997-08-17T00:00:00.000+00:00</HIRE_DATE>
       <SALARY>6000</SALARY>
     </EMPS>
  </DEPT>
<DEPT>
...
...
</DEPT>
</DATA>

3.3.2 Step 2: Design the Layout in Excel

In Excel, determine how you want to render the data and create a sample design, as shown in Figure 3-1.

Figure 3-1 A Sample Design

The design shows a department name and a row for each employee within the department. You can apply Excel formatting to the design, such as font style, shading, and alignment. Note that this layout includes a total field. The value for this field is not available in the data and requires a calculation.

3.3.3 Step 3: Assign the BI Publisher Defined Names

To code this design as a template, mark up the cells with the XDO_ defined names to map them to data elements. The cells must be named according to the following format:

• Data elements: XDO_?element_name?
  where
  XDO_ is the required prefix and
  ?element_name? is either:
  
  • the XML tag name from the data delimited by "?"
    
  • a unique name that you use to map a derived value to the cell
    
  For example: XDO_?EMPLOYEE_ID?
  
• Data groups: XDO_GROUP_?group_name?
  where
  XDO_GROUP_ is the required prefix and ?group_name? is either
  
  • the XML tag name for the parent element in the XML data delimited by "?".
    
  • a unique name that you use to define a derived grouping logic
    
  For example: XDO_GROUP_?DEPT?
  Note that the question mark delimiter, the group_name, and the element_name are case sensitive.
  

3.3.3.1 Applying a Defined Name to a Cell

To apply a defined name to a cell:

1. Click the cell in the Excel worksheet.
   
2. Click the Name box at the left end of the formula bar. The default name is displayed in the Name box. By default, all cells are named according to position, for example: A8.
   
3. In the Name box, enter the name using the XDO_ prefix and the tag name from the data. For example: XDO_?EMP_NAME?
   
4. Press Enter.
   Figure 3-2 shows the defined name for the Employee Name field entered in the Name box.
   
   Figure 3-2 Defined Name for the Employee Name Field Entered in the Name Box

   
5. Repeat for each of the following data fields: DEPARTMENT_NAME, EMPLOYEE_ID, EMAIL, PHONE_NUMBER, and SALARY.
   
   Tip:

   If you navigate out of the Name box without pressing Enter, then the name that you entered is not maintained.
   You cannot edit the Name box while you are editing the cell contents.
   The name cannot be more than 255 characters in length.
   
6. For the total salary field, a calculation is mapped to that cell. For now, name that cell XDO_?TOTAL_SALARY?. The calculation is added later.
   

After you have entered all the fields, you can review the names and make any corrections or edits using the Name Manager feature of Excel. Access the Name Manager from the Formulas tab in Excel, as shown in Figure 3-3.

Figure 3-3 The Name Manager

The Name Manager dialog is shown in Figure 3-4 after completing all cell entries for this example:

Figure 3-4 The Name Manager Dialog

You can review all your entries and update any errors through this dialog.

3.3.3.2 Understanding Groups

A group is a set of data that repeats for each occurrence of a particular element. In the sample template design, there are two groups:

• For each occurrence of the <EMPS> element, the employee's data (name, e-mail, telephone, salary) is displayed in the worksheet.
  
• For each occurrence of the <DEPT> element, the department name and the list of employees belonging to that department are displayed.
  

In other words, the employees are "grouped" by department and each employee's data is "grouped" by the employee element. To achieve this in the final report, add grouping tags around the cells that are to repeat for each grouping element.
Note that the data must be structured according to the groups that you want to create in the template. The structure of the data for this example

<DATA> 
   <DEPT>
      <EMPS>

establishes the grouping desired for the report.

3.3.3.3 Creating Groups in the Template

To create groups in the template:

1. Highlight the cells that make up the group. In this example the cells are A8 - E8.
   
2. Click the Name box at the left end of the formula bar and enter the name using the XDO_GROUP_ prefix and the tag name for the group from the data. For example: XDO_GROUP_?EMPS?
   
3. Press Enter.
   

Figure 3-5 shows the XDO_GROUP_ defined name entered for the Employees group. Note that just the row of employee data is highlighted. Do not highlight the headers. Note also that the total cell XDO_?TOTAL_SALARY? is not highlighted.

Figure 3-5 The XDO_GROUP_ Defined Name Entered for the Employees Group

To define the department group, include the department name cell and all the employee fields beneath it (A5-E9) as shown in Figure 3-6.

Figure 3-6 The Department Name Cell and All Employee Fields

Enter the name for this group as: XDO_GROUP_?DEPT? to match the group in the data. Note that the XDO_?TOTAL_SALARY? cell is included in the department group to ensure it repeats at the department level.

3.3.4 Step 4: Prepare the XDO_METADATA Sheet

BI Publisher requires the presence of a sheet called "XDO_METADATA" to process the template. This sheet must follow the specifications defined here.

3.3.4.1 Format of the XDO_METADATA Sheet

The XDO_METADATA sheet must have the format shown in Figure 3-7.

Figure 3-7 Format of the XDO_METADATA Sheet

The format consists of two sections: the header section and the data constraints section. Both sections are required. In the header section, all the entries in column A must be listed, but a value is required for only one: Template Type, as shown. The Data Constraints section does not require any content, but also must be present as shown.
This procedure describes how to set up the sheet for this sample Excel template to run. For the detailed description of the functionality provided by the XDO_METADATA sheet see Section 3.5, "Defining BI Publisher Functions".

3.3.4.2 Creating the XDO_METADATA Sheet

1. Create a new sheet in the Excel workbook and name it "XDO_METADATA".
   
2. Create the header section by entering the following variable names in column A, one per row, starting with row 1:
   
   • Version
     
   • ARU-dbdrv
     
   • Extractor Version
     
   • Template Code
     
   • Template Type
     
   • Preprocess XSLT File
     
   • Last Modified Date
     
   • Last Modified By
     
3. Skip a row and enter "Data Constraints" in column A of row 10.
   
4. In the header region, for the variable "Template Type" enter the value: TYPE_EXCEL_TEMPLATE
   

3.3.4.3 Adding the Calculation for the XDO_?TOTAL_SALARY? Field

Earlier in this procedure, you assigned the defined name XDO_?TOTAL_SALARY? to the cell that is to display the total salaries listed in the SALARY column. In this step, you add the calculation to the Data Constraints section of the XDO_METADATA sheet and map the calculation to the XDO_?TOTAL_SALARY? field.
To add the calculation to the field:

1. In the Data Constraints section, in Column A, enter the defined name of the cell: XDO_?TOTAL_SALARY?
   
2. In Column B enter the calculation as an XPATH function. To calculate the sum of the SALARY element for all employees in the group, enter the following: <?sum(.//SALARY)?>
   

The completed XDO_METADATA sheet is shown in Figure 3-8.

Figure 3-8 A Completed XDO_METADATA Sheet

3.3.5 Step 5: Test the Template

The Template Viewer is installed when you install the Template Builder for Word; see Section 3.1.5, "Desktop Tools" for more information.
To preview with the Template Viewer:

1. Open the Template Viewer:
   From the Windows desktop, click Start, then Programs, then Oracle BI Publisher Desktop, then Template Viewer.
   
2. Click Browse to locate the folder that contains the sample data file and template file. The data file and template file must reside in the same folder.
   
3. Select Excel Templates. The Data and Template regions display all XML files and all XLS files present in the directory, as shown in Figure 3-31.
   
   Figure 3-9 The Data and Template Regions Showing All .xml and .xls Files

   
4. Click the appropriate data and template files to select them.
   
5. From the Output Format list, select Excel.
   
6. Click Start Processing.
   The Template Viewer merges the sample data with the template and the output document is opened in a new workbook. Figure 3-10 shows the preview of the template with the sample data.
   
   Figure 3-10 A Preview of a Template with Sample Data

   
   If the template preview is not generating the results expected, then you can use the Template Viewer to enable trace settings to view debug messages, see Section 3.7, "Debugging a Template Using the Template Viewer."
   

3.4 Formatting Dates

Excel cannot recognize canonical date format. If the date format in the XML data is in canonical format, that is, YYYY-MM-DDThh:mm:ss+HH:MM, you must apply a function to display it properly.
One option to display a date is to use the Excel REPLACE and SUBSTITUTE functions. This option retains the full date and timestamp. If you only require the date portion in the data (YYY-MM-DD), then another option is to use the DATEVALUE function. The following example shows how to use both options.
Example: Formatting a Canonical Date in Excel
Using the Employee by Department template and data from the first example, assume you want to add the HIRE_DATE element to the layout to and display the date as shown in Column E of Figure 3-11.

Figure 3-11 The Employee by Department Template Showing the Hire Date

To format the date:

1. Copy and paste a sample value for HIRE_DATE from the XML data into the cell that is to display the HIRE_DATE field. For example:
   Copy and paste
   1996-02-03T00:00:00.000-07:00
   into the E8 cell.
   
2. Assign the cell the defined name XDO_?HIRE_DATE? to map it to the HIRE_DATE element in the data, as shown in Figure 3-12.
   
   Figure 3-12 Assigning the Defined Name XDO_?HIRE_DATE?

   
   If you do nothing else, the HIRE_DATE value is displayed as shown. To format the date as "3-Feb-96", you must apply a function to that field and display the results in a new field.
   
3. Insert a new Hire Date column. This is now column F, as shown in Figure 3-13.
   
   Figure 3-13 The New Hire Date Column in Column F

   
4. In the new Hire Date cell (F8), enter one of the following Excel functions:
   
   • To retain the full date and timestamp, enter:
     

     =--REPLACE(SUBSTITUTE(E8,"T"," "),LEN(E8)-6,6,"")
     

   • To retain only the date portion (YYY-MM-DD), enter:
     

     DATEVALUE(LEFT(E8,10))
     

   After you enter the function, it populates the F8 cell as shown in Figure 3-14.
   
   Figure 3-14 Hire Date Cell (F8) Populated

   
5. Apply formatting to the cell.
   Right-click the F8 cell. From the menu, select Format Cells. In the Format Cells dialog, select Date and the desired format, as shown in Figure 3-15.
   
   Figure 3-15 Applying the Format for the Date in the Format Cells Dialog

   
   The sample data in the F8 cell now displays as 3-Feb-96.
   
6. Hide the E column, so that report consumers do not see the canonical date that is converted.
   Figure 3-16 shows column E hidden.
   
   Figure 3-16 Column E Hidden

   

3.5 Defining BI Publisher Functions

BI Publisher provides a set of functions to achieve additional reporting functionality. You define these functions in the Data Constraints region of the XDO_METADATA sheet.
The functions make use of Columns A, B, and C in the XDO_METADATA sheet as follows:
Use Column A to declare the function or to specify the defined name of the object to which to map the results of a calculation or XSL evaluation.
Use Column B to enter the special XDO-XSL syntax to describe how to control the data constraints for the XDO function, or the XSL syntax that describes the special constraint to apply to the XDO_ named elements.
Use Column C to specify additional instructions for a few functions.
The functions are described in the following three sections:

• Section 3.5.1, "Reporting Functions"
  
• Section 3.5.2, "Formatting Functions That Rely on Specific Data Attribute Values"
  
• Section 3.5.3, "Grouping Functions"
  

3.5.1 Reporting Functions

Table 3-1 lists functions that you can add to a template using the commands shown and a combination of BI Publisher syntax and XSL. A summary list of the commands is shown in Table 3-1. See the corresponding section for details on usage.

Table 3-1 Reporting Functions

Function	Commands
Section 3.5.1.1, "Splitting the Report into Multiple Sheets"	XDO_SHEET_? with XDO_SHEET_NAME_?
Section 3.5.1.2, "Declaring and Passing Parameters"	XDO_PARAM_?n?
Section 3.5.1.3, "Defining a Link"	XDO_LINK_?link object name?
Section 3.5.1.4, "Importing and Calling a Subtemplate"	XDO_SUBTEMPLATE_?n?
Section 3.5.1.5, "Referencing Java Extension Libraries"	XDO_EXT_?n?

3.5.1.1 Splitting the Report into Multiple Sheets

Note:

Images are not supported across multiple sheets. If the template sheet includes images, when the data is split into multiple sheets, the images are displayed only on the first sheet.

Use the set of commands to define the logic to split the report data into multiple sheets, as described in the following list:

• Use XDO_SHEET_? to define the logic by which to split the data onto a new sheet.
  
• Use XDO_SHEET_NAME_? to specify the naming convention for each sheet.
  

Table 3-2 describes the column entries.

Table 3-2 Column Entries

Column A Entry	Column B Entry	Column C Entry
XDO_SHEET_?	<?xsl_evaluation to split the data?> Example: <?.//DEPT?>	n/a
XDO_SHEET_NAME_?	<?xsl_expression to name the sheet?> Example: <?concat(.//DEPARTMENT_NAME,'-',count(.//EMP_NAME))?>	(Optional) <?original sheet name?> Example: <?Sheet3?>

XDO_SHEET_? must refer to an existing high-level node in the XML data. The example <?.//DEPT?> creates a new sheet for each occurrence of <DEPT> in the data.
If the data is flat, then you cannot use this command unless you first preprocess the data to create the desired hierarchy. To preprocess the data, define the transformation in an XSLT file, then specify this file in the Preprocess XSLT File field of the header section of the XDO _METADATA sheet. For more information, see Section 3.6, "Preprocessing the Data Using an XSL Transformation (XSLT) File."
Use XDO_SHEET_NAME_? to define the name to apply to the sheets. In Column B enter the XSL expression to derive the new sheet name. The expression can reference a value for an element or attribute in the XML data, or you can use the string operation on those elements to define the final sheet name. This example:

<?concat(.//DEPARTMENT_NAME,'-',count(.//EMP_NAME))?>

names each sheet using the value of DEPARTMENT_NAME concatenated with "-" and the count of employees in the DEPT group.
The original sheet name entry in Column C tells BI Publisher on which sheet to begin the specified sheet naming. If this parameter is not entered, BI Publisher applies the naming to the first sheet in the workbook that contains XDO_ names. You must enter this parameter if, for example, you have a report that contains summary data in the first two worksheets and the burst data should begin on Sheet3. In this case, you enter <?SHEET3?> in Column C.
Example: Splitting the data into multiple sheets
Using the employee data shown in the previous example. This example:

• Creates a new worksheet for each department
  
• Names each worksheet the name of the department with the number of employees in the department, for example: Sales-21.
  

To split the data into sheets:

1. Enter the defined names for each cell of employee data and create the group for the repeating employee data, as shown in Figure 3-17.
   
   Figure 3-17 Defining Employee Data and the Group for Repeating Employee Data

   
   Note:

   Do not create the grouping around the department because the data is split by department.
2. Enter the values that are described in Table 3-3 in the Data Constraints section of the XDO_METADATA sheet.
   
   Table 3-3 Data Constraints Values

   Column A Entry	Column B Entry
   XDO_SHEET_?	<?.//DEPT?>
   XDO_SHEET_NAME_?	<?concat(.//DEPARTMENT_NAME,'-',count(.//EMP_NAME))?>

The entries are shown in Figure 3-18.

Figure 3-18 Entries for Data Constraints

Figure 3-19 shows the generated report. Each department data now displays on its own sheet, which shows the naming convention specified.

Figure 3-19 Example of a Generated Report

3.5.1.2 Declaring and Passing Parameters

To define a parameter, use the XDO_PARAM_?n? function to declare the parameter, then use the $parameter_name syntax to pass a value to the parameter. A parameter must be defined in the data model.
To declare the parameter, use the command that is described in Table 3-4.

Table 3-4 Command for Declaring Parameters

Column A Entry	Column B Entry
XDO_PARAM_?n? where n is unique identifier for the parameter	<?param@begin:parameter_name;parameter_value?> where parameter_name is the name of the parameter from the data model and parameter_value is the optional default value. For example: <?param@begin:Country;US?>

To use the value of the parameter directly in a cell, refer to the parameter as $parameter_name in the definition for the XDO_ defined name, as described in Table 3-5.

Table 3-5 Using a Parameter Directly

Column A Entry	Column B Entry
XDO_PARAM_?parameter_name? For example: XDO_PARAM_?Country?	<?$parameter_name?>. For example: <?$Country?>

You can also refer to the parameter in other logic or calculations in the XDO_METADATA sheet using $parameter_name.
Example: Defining and Passing a Parameter
To declare and reference a parameter named Country:

1. In the template sheet, mark the cell with a defined name. In the figure below, the cell has been marked with the defined name XDO_?Country?
   
   Figure 3-20 Cell Marked with the Defined Name XDO_?Country?

   
2. In the hidden sheet assign that cell the parameter value, as shown in Figure 3-21.
   
   Figure 3-21 Assigning a Parameter Value to the XDO_?Country?Cell

   

3.5.1.3 Defining a Link

Use the XDO_LINK_? command to define a hyperlink for any data cell, as described in Table 3-6.
Example: Defining a Link

Table 3-6 Defining a Link

Column A Entry	Column B Entry
XDO_LINK_?cell object name? For example: XDO_LINK_?INVOICE_NO?	<xsl statement to build the dynamic URL> For example: <xsl:value-of select="concat('https://server.company.com/documents/invoice_print.show?c_rptno=',./INVOICE_NO)"/>

Assume your company generates customer invoices. The invoices are stored in a central location accessible by a Web server and can be identified by the invoice number (INVOICE_NO).
To generate a report that creates a dynamic link to each invoice:

1. In the template sheet, assign the cell that is to display the INVOICE_NO the XDO defined name: XDO_?INVOICE_NO?, as shown in Figure 3-22.
   
   Figure 3-22 Assigning the Defined Name XDO_?INVOICE_NO?

   
2. In the XDO_METADATA sheet, enter the appropriate values, as described in Table 3-7:
   
   Table 3-7 Generating a Report with a Link

   Column A Entry	Column B Entry
   XDO_LINK_?INVOICE_NO?	<xsl:value-of select="concat('https://server.company.com/documents/invoice_print.show?c_rptno=',./INVOICE_NO)"/>

   The entries in Excel are shown inFigure 3-23.
   
   Figure 3-23 XDO_LINK?_?INVOICE_NO? Entries in Excel

   

The report output is displayed as shown in Figure 3-24. The logic that is defined in the XDO_METADATA sheet is applied to create a hyperlink for each INVOICE_NO entry.

Figure 3-24 Example of the Report Output

3.5.1.4 Importing and Calling a Subtemplate

Use these commands to declare XSL subtemplates that you can then call and reference in any of the XDO_ commands.

Note:

The Template Viewer does not support preview for templates that import subtemplates.

To import the subtemplate, enter the command shown in Table 3-8.

Table 3-8 Importing a Subtemplate

Column A Entry	Column B Entry
XDO_SUBTEMPLATE_?n? where n is a unique identifier. For example: XDO_SUBTEMPLATE_?1?	<xsl:import href="xdoxsl:///path to subtemplate"/> For example: <xsl:import href="http://server.company.com:8080/subtemplates/PaymentsSummary-SubTemplate.xsl"/>

To call the subtemplate, declare the cell name for which the results should be returned in Column A, then enter the call-template syntax with any other XSL processing to be performed. The commands are shown in Table 3-9.

Table 3-9 Calling a Subtemplate

Column A Entry	Column B Entry
XDO_?cell object name?	<xsl:call-template name="template_name"> </xsl:call-template>

Example: Importing and Calling a Subtemplate
Assume you have the following subtemplate to evaluate the value of a parameter named pPayType and based on the value, will return a string that indicates the payment type:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="2.0"
 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="/">
    </xsl:template>
      <xsl:template name="BRM_PAY_TYPES">
         <xsl:param name="pPayType" select="string('ALL')"/>
         <xsl:choose>
            <xsl:when test="$pPayType = '0'">UNDEFINED</xsl:when>
            <xsl:when test="$pPayType=string('10000')">PREPAID</xsl:when>
            <xsl:when test="$pPayType=string('10001')">INVOICE</xsl:when>
            <xsl:when test="$pPayType=string('10003')">CREDIT CARD</xsl:when>
            <xsl:when test="$pPayType=string('10005')">DIRECT DEBIT</xsl:when>
            <xsl:when test="$pPayType=string('10011')">CASH</xsl:when>
            <xsl:when test="$pPayType=string('10012')">CHECK</xsl:when>
            <xsl:when test="$pPayType=string('ALL')">ALL</xsl:when>
            </xsl:choose>
        </xsl:template>
</xsl:stylesheet>

In the Excel template, you have defined a field with the XDO Defined Name XDO_?TYPE?, which is populated based on the string returned from code performed in the subtemplate, as shown in Figure 3-25.

Figure 3-25 Populated XDO_?TYPE? Field

Enter the commands shown in Table 3-10 in the Data Constraints region.

Table 3-10 Commands for Data Constraints Region

Column A Entry	Column B Entry
XDO_SUBTEMPLATE_?1?	<xsl:import href="http://server.company.com:8080/subtemplates/PaymentsSummary-SubTemplate.xsl"/>
XDO_?TYPE?	<xsl:call-template name="BRM_PAY_TYPES"> <xsl:with-param name="pPayType" select="string('10000')"/> </xsl:call-template>

The XDO_SUBTEMPLATE_?1? function imports the subtemplate from the specified location.
The XDO_?TYPE? cell entry maps the results of the subtemplate processing entered in Column B.

3.5.1.5 Referencing Java Extension Libraries

You can include the reference to a Java extension library in the template and then call methods from this library to perform processing in the template. Use the command shown in Table 3-11 to reference the Java extension libraries.

Table 3-11 Referencing Java Extension Libraries

Column A Entry	Column B Entry
XDO_EXT_?n? where n is a unique identifier. Example: XDO_EXT?1?	<?namespace:xmlns:bipext="extension library"?> Example: <?namespace:xmlns:bipext="http://www.company.com/XSL/Transform/java/ company.com.xmlpublisher.reports.BIPExtension"?>

You can have multiple extension libraries defined in a single template file.
Example: Calling a Java Extension Library
Assume the extension library includes the following two methods that you want to call in the template:

• bipext:infTimeToStr()
  
• bipext:infStrToTimet()
  

After you have declared the library as shown above, specify the cell to which you want to apply the method by entering the XDO defined name in Column A and calling the function in Column B. Table 3-12 shows example commands.

Table 3-12 Example: Calling a Java Extension Library

Column A Entry	Column B Entry
XDO_?PARAM_START_DATE?	<xsl:value-of select="bipext:infTimeToStr(bipext:infStrToTimet((.//PARAM_START_DATE)[1],2),3)"

The entries in the XDO_METADATA sheet to declare and call the Java extension libraries are shown in Figure 3-26.

Figure 3-26 Entries in the XDO_METADATA Sheet to Declare and Call the Java Extension Libraries

3.5.2 Formatting Functions That Rely on Specific Data Attribute Values

The following commands require that specific formatting attributes be present in the XML data file. A summary list of the commands is shown in Table 3-13. See the corresponding section for details on usage.

Table 3-13 Commands for Specific Formatting Attributes

Function	Command
Section 3.5.2.1, "Defining Border and Underline Styles"	XDO_STYLE_n_?cell object name?
Section 3.5.2.2, "Skipping a Row"	XDO_SKIPROW_?cell object name?

3.5.2.1 Defining Border and Underline Styles

While you can define a consistent style in the template using Excel formatting, the XDO_STYLE command enables you to define a different style for any data cell dynamically based on the XML data.
With the XDO_STYLE command you specify the cell to which to apply the style, the logic to determine when to apply the style, and the style type to apply. The style value must be present in the XML data. Table 3-14 provides examples.

Table 3-14 Defining Border and Underline Styles

Column A Entry	Column B Entry	Column C Entry
XDO_STYLE_n_?cell_object_name? For example: XDO_STYLE_1_?TOTAL_SALARY?	<xsl evaluation that returns a supported value> For example: <xsl:value-of select=".//TOTAL_SALARY/@borderStyle"/>	Style type For example: BottomBorderStyle

BI Publisher supports the normal Excel style types and values as shown in Table 3-15.

Table 3-15 Excel Style Types and Values

Style Type	Supported Values (Must be in returned by evaluation in Column B)	Supported Types (Enter in Column C)
Normal	BORDER_NONE BORDER_THIN BORDER_MEDIUM BORDER_DASHED BORDER_DOTTED BORDER_THICK BORDER_DOUBLE BORDER_HAIR BORDER_MEDIUM_DASHED BORDER_DASH_DOT BORDER_MEDIUM_DASH_DOT BORDER_DASH_DOT_DOT BORDER_MEDIUM_DASH_DOT_DOT BORDER_SLANTED_DASH_DOT	BottomBorderStyle TopBorderStyle LeftBorderStyle RightBorderStyle DiagonalLineStyle

You can also set a color using one of the types shown in Table 3-16.

Table 3-16 Color Types

Style Type	Supported Value (Must be in returned by evaluation in Column B)	Supported Types (Enter in Column C)
Normal	When you set Color Style, give the value in RRBBGG hex format, for example: borderColor="0000FF"	BottomBorderColor TopBorderColor LeftBorderColor RightBorderColor DiagonalLineColor

BI Publisher also supports the underline type with the values shown in Table 3-17.

Table 3-17 Underline Types

Style Type	Supported Values (Must be in returned by evaluation in Column B)	Supported Type (Enter in Column C)
Underline	UNDERLINE_NONE UNDERLINE_SINGLE UNDERLINE_DOUBLE UNDERLINE_SINGLE_ACCOUNTING UNDERLINE_DOUBLE_ACCOUNTING	UnderlineStyle

You can have multiple underline styles defined for a single cell.
Example: Defining Styles
To apply a style in a template, the style value must be present in the data. In this example, a border style and an underline style are applied to the DEPT_TOTAL_SALARY field shown in the Excel template.
For this example, the following data is used. Note that the DEPT_TOTAL_SALARY element in the data has these attributes defined:

• borderStyle
  
• underLineStyle
  
• borderColor
  

The value of each of these attributes is used to apply the defined style based on logic defined in the template.

<?xml version="1.0" encoding="UTF-8"?>

<EMPLOYEES>
  <G_DEPT>
    <DEPARTMENT_ID>10</DEPARTMENT_ID>
    <DEPARTMENT_NAME>Administration</DEPARTMENT_NAME>
    <LIST_G_EMP>
      <G_EMP>
        <EMPLOYEE_ID>200</EMPLOYEE_ID>
        <EMP_NAME>Jennifer Whalen</EMP_NAME>
        <EMAIL>JWHALEN</EMAIL>
        <PHONE_NUMBER>515.123.4444</PHONE_NUMBER>
        <HIRE_DATE>1987-09-17T00:00:00.000-06:00</HIRE_DATE>
        <SALARY>4400</SALARY>
      </G_EMP>
    </LIST_G_EMP>

    <DEPT_TOTAL_SALARY borderStyle="BORDER_DOUBLE" 

underLineStyle="UNDERLINE_DOUBLE_ACCOUNTING" 

borderColor="0000FF">4400</DEPT_TOTAL_SALARY>
  </G_DEPT>
  <G_DEPT>
    <DEPARTMENT_ID>20</DEPARTMENT_ID>
    <DEPARTMENT_NAME>Marketing</DEPARTMENT_NAME>
    <LIST_G_EMP>
      <G_EMP>
        <EMPLOYEE_ID>201</EMPLOYEE_ID>
        <EMP_NAME>Michael Hartstein</EMP_NAME>
        <EMAIL>MHARTSTE</EMAIL>
        <PHONE_NUMBER>515.123.5555</PHONE_NUMBER>
        <HIRE_DATE>1996-02-17T00:00:00.000-07:00</HIRE_DATE>
        <SALARY>13000</SALARY>
      </G_EMP>
      <G_EMP>
        <EMPLOYEE_ID>202</EMPLOYEE_ID>
        <EMP_NAME>Pat Fay</EMP_NAME>
        <EMAIL>PFAY</EMAIL>
        <PHONE_NUMBER>603.123.6666</PHONE_NUMBER>
        <HIRE_DATE>1997-08-17T00:00:00.000-06:00</HIRE_DATE>
        <SALARY>6000</SALARY>
        </G_EMP>
      </LIST_G_EMP>

      <DEPT_TOTAL_SALARY borderStyle="BORDER_DOUBLE" 

underLineStyle="UNDERLINE_DOUBLE_ACCOUNTING" 

borderColor="0000FF">19000</DEPT_TOTAL_SALARY>
  </G_DEPT>

...

</EMPLOYEES>

To define a style:

1. In the Excel template, assign the defined name XDO_?DEPT_TOTAL_SALARY? to the field that is to display the DEPT_TOTAL_SALARY from the data, as shown in Figure 3-27.
   
   Figure 3-27 Assigning the Defined Name XDO_?DEPT_TOTAL_SALARY?

   
2. In the XDO_METADATA sheet, enter the following:
   
   • To define the top border style, use the entries shown in Table 3-18.
     
     Table 3-18 Top Border Style

     Column A Entry	Column B Entry	Column C Entry
     XDO_STYLE_1_?DEPT_TOTAL_SALARY?	<xsl:value-of select=".//DEPT_TOTAL_SALARY/@borderStyle"/>	TopBorderStyle

     The entry in Column A maps this style command to the cell assigned the name XDO_?DEPT_TOTAL_SALARY?
     The entry in Column B retrieves the style value from the attribute borderStyle of the DEPT_TOTAL_SALARY element. Note from the sample data that the value for borderStyle is "BORDER_DOUBLE".
     The entry in Column C tells BI Publisher to apply a TopBorderStyle to the cell.
     
   • To define the top border color, use the entries shown in Table 3-19.
     
     Table 3-19 Top Border Color

     Column A Entry	Column B Entry	Column C Entry
     XDO_STYLE_2_?DEPT_TOTAL_SALARY?	<?.//DEPT_TOTAL_SALARY/@borderColor?>	TopBorderColor

     The entry in Column A maps this style command to the cell assigned the name XDO_?DEPT_TOTAL_SALARY?
     The entry in Column B retrieves the style value from the attribute borderColor of the DEPT_TOTAL_SALARY element. Note from the sample data that the value for borderColor is "0000FF" (blue).
     The entry in Column C tells BI Publisher to apply a TopBorderColor to the cell.
     
   • To define the underline style, use the entries shown in Table 3-20.
     
     Table 3-20 Underline Style

     Column A Entry	Column B Entry	Column C Entry
     XDO_STYLE_3_?DEPT_TOTAL_SALARY?	<?.//DEPT_TOTAL_SALARY/@underLineStyle?>	UnderlineStyle

     The entry in Column A maps this style command to the cell assigned the name XDO_?DEPT_TOTAL_SALARY?
     The entry in Column B retrieves the style value from the attribute underLineStyle of the DEPT_TOTAL_SALARY element. Note from the sample data that the value for underLineStyle is "UNDERLINE_DOUBLE_ACCOUNTING".
     The entry in Column C tells BI Publisher to apply the UnderLineStyle to the cell.
     

Figure 3-28 shows the three entries in the Data Constraints region.

Figure 3-28 Entries for Data Constraints

When you run the report, the style commands are applied to the XDO_?DEPT_TOTAL_SALARY? cell, as shown in Figure 3-29.

Figure 3-29 A Generated Report Showing Style Commands Applied to the XDO_?DEPT_TOTAL_SALARY? Cell

3.5.2.2 Skipping a Row

Use the XDO_SKIPROW command to suppress the display of a row of data in a table when the results of an evaluation defined in Column B return the case insensitive string "True". Example entries are shown in Table 3-21.

Table 3-21 Skipping a Row

Column A Entry	Column B Entry
XDO_SKIPROW_?cell_object_name? For example: XDO_SKIPROW_?EMPLOYEE_ID?	<xsl evaluation that returns the string "True"/> For example: <xsl:if test="string-length(./EMPLOYEE_ID/@MANAGER) != 0"> <xsl:value-of select="./EMPLOYEE_ID/@MANAGER"/> </xsl:if>

Example: Skipping a Row Based on Data Element Attribute
In this example, the Excel template suppresses the display of the row of employee data when the EMPLOYEE_ID element includes a "MANAGER" attribute with the value "True".
Assume data as shown below. Note that the EMPLOYEE_ID element for employee Michael Hartstein has the MANAGER attribute with the value "True". The other EMPLOYEE_ID elements in this set do not have the attribute.

<?xml version="1.0" encoding="UTF-8"?>

<EMPLOYEES>
  <G_DEPT>
    <DEPARTMENT_ID>20</DEPARTMENT_ID>
    <DEPARTMENT_NAME>Marketing</DEPARTMENT_NAME>
    <LIST_G_EMP>
      <G_EMP>
        <EMPLOYEE_ID MANAGER="TRUE">201</EMPLOYEE_ID>
        <EMP_NAME>Michael Hartstein</EMP_NAME>
        <EMAIL>MHARTSTE</EMAIL>
        <PHONE_NUMBER>515.123.5555</PHONE_NUMBER>
        <HIRE_DATE>1996-02-17T00:00:00.000-07:00</HIRE_DATE>
        <SALARY>13000</SALARY>
       </G_EMP>
       <G_EMP>
        <EMPLOYEE_ID>202</EMPLOYEE_ID>
        <EMP_NAME>Pat Fay</EMP_NAME>
        <EMAIL>PFAY</EMAIL>
        <PHONE_NUMBER>603.123.6666</PHONE_NUMBER>
        <HIRE_DATE>1997-08-17T00:00:00.000-06:00</HIRE_DATE>
        <SALARY>6000</SALARY>
       </G_EMP>
       <G_EMP>
        <EMPLOYEE_ID>652</EMPLOYEE_ID>
        <EMP_NAME>William Morgan</EMP_NAME>
        <EMAIL>WMORGAN</EMAIL>
        <PHONE_NUMBER>219.123.7776</PHONE_NUMBER>
        <HIRE_DATE>1994-10-17T00:00:00.000-06:00</HIRE_DATE>
        <SALARY>8000</SALARY>
       </G_EMP>
      </LIST_G_EMP>
  </G_DEPT>

...

</EMPLOYEES>

To suppress the display of the row of the employee data when the MANAGER attribute is set to "True", enter the entries shown in Table 3-22 in the Data Constraints section.

Table 3-22 Skipping a Row Based on Data Element Attribute

Column A Entry	Column B Entry
XDO_SKIPROW_?EMPLOYEE_ID?	<xsl:if test="string-length(./EMPLOYEE_ID/@MANAGER)!= 0"> <xsl:value-of select="./EMPLOYEE_ID/@MANAGER"/> </xsl:if>

The output from this template is shown in Figure 3-30. Note that the employee Michael Hartstein is not included in the report.

Figure 3-30 Output for a Skipped Row

3.5.3 Grouping Functions

Use the functions shown in Table 3-23 to create groupings of data in the template.

Table 3-23 Creating Groupings of Data

Function	Command
Section 3.5.3.1, "Grouping the data"	XDO_GROUP_?group element?
Section 3.5.3.2, "Regrouping the Data"	XDO_REGROUP_?

3.5.3.1 Grouping the data

Use the XDO_GROUP command to group flat data when the layout requires a specific data grouping, for example, to split the data across multiple sheets. Example entries are shown in Table 3-24.

Table 3-24 Grouping the Data

Column A Entry	Column B Entry	Column C Entry
XDO_GROUP_?group element? For example: XDO_GROUP_?STATE_GROUP?	<xsl beginning groupng logic/> For example: <xsl:for-each-group select="current-group()" group-by="./STATE"> <xsl:for-each-group select="current-group()" group-by="./RESOURCE_NAME"> <xsl:for-each select="current-group()">	<xsl ending groupng tags/> For example: </xsl:for-each> <xsl:for-each-group> <xsl:for-each-group>

Define the XSL statements to be placed at the beginning and ending of the section of the group definition marked up by XDO_?cell object name?. You can mark multiple groups nested in the template, giving each the definition appropriate to the corresponding group.

3.5.3.2 Regrouping the Data

The XDO_REGROUP regroups the data by declaring the structure using the defined names. It does not require the XSLT logic. Entries are shown in Table 3-25.

Table 3-25 Regrouping the Data

Column A Entry

Column B Entry

XDO_REGROUP_?

XDO_REGROUP_?UniqueGroupID?levelName?groupByName?sortByName?sortByName?sortByName? where UniqueGroupID is the ID of the group. It can be the same as the levelName or you can assign it unique name. levelName is the XML level tag name in the XML data file or current-group() in the context of the XDO_ grouping structure. groupByName is the field name that you want to use for the GroupBy operation for the current group. This name can be empty if the XDO_REGROUP_? command is used for the most inner group. sortByName is the field name that you want to sort the group by. You can have multiple sortBy fields. If no sortByName is declared, then the data from the XML file is not sorted.

Table 3-26, Table 3-27, and Table 3-28 show an example of how to create three nested groupings.

Table 3-26 Creating Nested Groupings, Example 1

Column A Entry	Column B Entry
XDO_REGROUP_?	XDO_REGROUP_?PAYMENTSUMMARY_Q1?PAYMENTSUMMARY_Q1?PAY_TYPE_NAME?

In the definition shown in Table 3-26, the most outer group is defined as PAYMENTSUMMARY_Q1, and it is grouped by PAY_TYPE_NAME

Table 3-27 Creating Nested Groupings, Example 2

Column A Entry	Column B Entry
XDO_REGROUP_?	XDO_REGROUP_?COUNTRYGRP?XDO_CURRGRP_?COUNTRY?

The definition shown in Table 3-27 creates a second outer group. The group is assigned the name COUNTRY_GRP and it is grouped by the element COUNTRY.

Table 3-28 Creating Nested Groupings, Example 3

Column A Entry	Column B Entry
XDO_REGROUP_?	XDO_REGROUP_?STATEGRP?XDO_CURRGRP_?STATE?

The definition shown in Table 3-28 creates the inner group STATEGRP and it includes a sortByName parameter: STATE.

3.6 Preprocessing the Data Using an XSL Transformation (XSLT) File

For the best performance, you should design the data model to perform as much of the data processing as possible. When it is not possible to get the required output from data engine, you can preprocess the data using an XSLT file that contains the instructions to transform the data. Some sample use cases may be:

• To create groups to establish the necessary hierarchy to support the desired layout
  
• To add style attributes to data elements
  
• To perform complex data processing logic that may be impossible in the Excel Template or undesirable for performance reasons
  

Note:

The Template Viewer does not support preview for templates that require XSLT preprocessing.

To use an XSLT preprocess file:

1. Create the file and save as .xsl.
   
2. Upload the file to the report definition in the BI Publisher repository, as you would a template:
   
   1. Navigate to the report in the repository.
      
   2. Click Edit.
      
   3. Click Layouts.
      
   4. Click Browse to locate the XSL file and then click Upload.
      
   5. Save the report definition.
      
3. In the Excel template, on the XDO_METADATA sheet, in the Header section, enter the file name for the Preprocess XSLT File parameter. For example: SplitByBrand.xsl
   

Note:

For testing purposes, you can create a Layout for the XSL file to enable you to view the intermediate data when the XSL template is applied to the data. To create the Layout:

1. With Layouts selected in the left pane, click New.
   
2. In the Layout General Settings pane, enter the following:
   
   • Name - enter a name for this layout.
     
   • Template - select the XSL template that you uploaded.
     
   • Template Type - select XSL Stylesheet (XML)
     
   • Output Format - All Formats
     
3. Click Save.
   
4. Run the report, applying the Excel template. If the output is not as expected in the Report Viewer, select the XSL template in the Report Viewer to view the preprocessed output.
   

After testing is complete, delete the XSL layout definition from the report so that users will not see it as an option.

3.7 Debugging a Template Using the Template Viewer

If the template preview is not generating the results expected, then you can use the Template Viewer to enable trace settings to view debug messages. The Template Viewer also enables you to save and view the intermediate XSL file that is generated after the sample data and template are merged in the XSL-FO processor. If you are familiar with XSL, then this can be a very useful debugging tool.
The Template Viewer is installed when you install the Template Builder for Word; see Section 3.1.5, "Desktop Tools" for more information.

Note:

The Template Viewer does not support preview for templates that require XSLT preprocessing.

To preview with the Template Viewer and view log messages:

1. Open the Template Viewer:
   From the Windows desktop, click Start, then Programs, then Oracle BI Publisher Desktop, then Template Viewer.
   
2. Click Browse to locate the folder that contains the sample data file and template file. The data file and template file must reside in the same folder.
   
3. Select Excel Templates. The Data and Template regions display all .xml files and all .xls files present in the directory, as shown in Figure 3-31.
   
   Figure 3-31 The Data and Template Regions Showing All .xml and .xls Files

   
4. Click the appropriate data and template files to select them.
   
5. Select the log level.
   
6. From the Output Format list, select Excel.
   
7. Click Start Processing.
   The Template Viewer merges the selected data with the selected template and spawn the appropriate viewer. View any log messages in the message box, as shown in Figure 3-32.
   
   Figure 3-32 Log Messages

   

To view the generated XSL:

1. In the Template Viewer, select the data and template files and choose Excel output.
   
2. On the Tools menu, select Generate XSL file from and then choose Excel Template, as shown in Figure 3-33.
   
   Figure 3-33 The Excel Template Option

   
3. At the prompt, save the generated XSL file.
   
4. Navigate to the saved location and open the XSL file in an appropriate viewer.
   

---