STANDARDS & BEST PRACTICES

STANDARDS & BEST PRACTICES

Oracle Appstech EMEA

XML Publisher Standards

Author: Serge Vervaet & Kevin Bouwmeester

Creation Date: February 27, 2007

Last Updated: February 18, 2008

Document Ref: NL/AppsTech/XMLP/Standards

Version: 1.4

File Ref: 080218_XML_Publisher_Standards_1.4.doc (v. 1.4 )

Doc Ref: NL/AppsTech/XMLP/Standards February 18, 2008

Document Control ii

Document Control

Change Record

3

Date Author Version Change Reference

15-Oct-07 Kevin Bouwmeester 1.0 Genesis

15-Nov-07 Kevin Bouwmeester 1.1 Comments of Marc Smeenge

19-Dec-07 Serge Verveat & Kevin Bouwmeester

1.2 SME Discussion

27-Jan-08 Kevin Bouwmeester 1.3 Remarks of Pieter Breugelmans

18-Feb-08 Kevin Bouwmeester 1.4 Remarks of Joost Voordouw. Added XDOLoader description.

Reviewers

Name Position

Marc Smeenge AppsTech NL PC Leader

Pieter Breugelmans Support Analyst

Joost Voordouw Application Developer



Document Control iii

Contents

Document Control ................................................................................................................ ii

Introduction ........................................................................................................................... 1

Why Standards............................................................................................................... 1 Scope of this Document................................................................................................. 1 Structure of this Document........................................................................................... 1 Vocabulary...................................................................................................................... 2 References ....................................................................................................................... 2 List of Figures................................................................................................................. 2

1. Standards for Layout Templates..................................................................................... 4

Form Field Usage........................................................................................................... 4 Subtemplates .................................................................................................................. 7 Headers and Footers...................................................................................................... 8 Naming Standards......................................................................................................... 8 Version Control .............................................................................................................. 9 Best Practices for Layout Template Building ............................................................. 9

2. Standards for XML Data ................................................................................................ 11

Where to get the XML ................................................................................................. 11

3. Standards for Data Template ........................................................................................ 12

Data Template Elements ............................................................................................. 12 Group Filters & Aggregate Functions ....................................................................... 17 Naming Standards....................................................................................................... 18 XML Elements and Structure ..................................................................................... 18

4. Standards for Bursting Control File.............................................................................. 20

Dynamic Data............................................................................................................... 20 Naming Standards....................................................................................................... 20

5. Standards for E-Business Suite Setup........................................................................... 21

Data Definition Setup.................................................................................................. 21 Template Definition Setup.......................................................................................... 22 Concurrent Program setup ......................................................................................... 23

Appendix A. Metadata Query........................................................................................... 25

Appendix B: Overview Naming Convention.................................................................. 26

Open and Closed Issues for this Deliverable .................................................................. 27

Open Issues................................................................................................................... 27 Closed Issues ................................................................................................................ 27



Introduction 1 of 1

Introduction

The need for standards and best practices was identified during the work on XML Publisher for several customers. Developing XML data structures and designing RTF templates seems easy, but without the structure of guidelines, collaboration between consultants and customers becomes very difficult. The absence of guidelines made the creation of templates and XML data structures needlessly complicated.

Why Standards

You might be skeptical about the use of standards and best practices for XML Publisher. Especially when you are just starting to build your first template, or when you are doing one time development for just one simple layout.

Despite the doubts that you might have against the standards, imagine the number of XML Publisher templates that will be developed in the coming years. Especially if you consider that Fusion is coming, where XML Publisher will be the only reporting tool. All these templates will need some maintenance and multiple consultants from EMEA (or maybe even worldwide) will be adjusting each other's templates. Without standards the work of your colleagues will not be as easy to read (and adapt) as it could be.

This document guides all the development being done on XML Publisher documents in EMEA. All names, color schemes and setup will be structured in the same way, what makes the templates of other's as intuitive as your own! Without a development standard much time will be lost in figuring out how it works and how it was build. With the standards and guidelines that are presented in this document the work of the consultants doing XML Publisher development will be much easier. And besides that, there are a few development best practices that can shorten the development process of XML Publisher documents.

Scope of this Document

This document focusses on best practices and standards for developing reports with XML Publisher. For information on how to work with XML Publisher, please see the Administration and Developer's Guide for more information on that.

This guide is written for Appstech E-Business Suite development. The focus is especially on the E-Business Suite releases 11i and 12. Although most of the content is also applicable for XML Publisher development outside the E-Business Suite. The target audience are the Oracle consultants working on XML Publisher templates. The primary focus is on EMEA, but this document can be useful worldwide.

The standards are discussed for the following elements; layout templates ( we only discuss the RTF template, allthough most of the standards also apply PDF template), data template for describing where the XML data comes from and how it looks like, the bursting control file and finally the setup in the E-Business Suite.

Oracle Reports is out of scope for the standards defined in this document.

Structure of this Document

This document is structured according to the elements that an XML Publisher developer has to deal with.



Introduction 2 of 2

� Chapter 1 discusses standards for the layout template. � Chapter 2 discusses standards for the XML data on which the layout is based. � Chapter 3 discusses standards for the data template. � Chapter 4 discusses standards for the bursting control file. � Chapter 5 discusses standards for the setup in E-Business Suite.

Vocabulary

Naming convention for XML Publisher related items. This is the vocabulary used in this document:

� Report the file that is generated by XML Publisher. � Data Template the xml template that defines and describes the data that

is being used. � Layout Template the rtf template file that defines the layout structure for

the report. � Data Definition an element of setup in the E-Business Suite to describe

the origin of the data for the report. � Layout Definition an element of setup in E-Business Suite to describe what

layout(s) can be used for the report. � XSL eXtensible Stylesheet Language, this term is used for the

set of standards for XSL (XSL-T, XSL-FO and Xpath). � Data Statements XML Publisher statements on the layout template that

print data. � Control Statements XML Publisher statements on the layout template that

do not print data but control repetition and conditions. � Bursting Control File XML file with the options and settings for the bursting

and delivery process.

References

Oracle® XML Publisher, Administration and Developer's Guide Release 11i Part No. E05321-01

XML Publisher Website, http://bipublisher.us.oracle.com/

XML Publisher Forum, http://forums.oracle.com/forums/forum.jspa?forumID=245

Oracle BI Publisher Documentation, http://www.oracle.com/technology/products/xml-publisher/xmlpdocs.html

Metalink Note 458794.1 Oracle Business Intelligence Publisher Performance Tuning Guide includes several additional performance tips.

List of Figures

The following figures are used in this document:

Figure 1: Give clear names to form fields ......................................................................... 4 Figure 2: Example RTF template layout with data in form field names ...................... 5 Figure 3: Hide control statements...................................................................................... 6 Figure 4: Layout template with control statements hidden ........................................... 7 Figure 5: Layout template with control statements visible ............................................ 7 Figure 6: Subtemplate dropdown list................................................................................ 8 Figure 7: Version comment in RTF layout template ....................................................... 9 Figure 8: Example of XML data generated by Report .................................................. 11 Figure 9: Data template header........................................................................................ 12 Figure 10: Data template structure .................................................................................. 12



Introduction 3 of 3

Figure 11: Data Definition code ....................................................................................... 13 Figure 12: XML root element name ................................................................................. 13 Figure 13: Data template properties................................................................................ 13 Figure 14: Error when db_fetch_size is too large .......................................................... 14 Figure 15: Data template parameters .............................................................................. 14 Figure 16: Parameter token name.................................................................................... 15 Figure 17: Data template queries ..................................................................................... 16 Figure 18: Data template data triggers............................................................................ 16 Figure 19: Data template data structure ......................................................................... 17 Figure 20: Group filter example....................................................................................... 18 Figure 21: Example XML .................................................................................................. 19 Figure 22: Display fields in the XML data ...................................................................... 19 Figure 23: Bursting control file example......................................................................... 20 Figure 24: XML Publisher setup in E-Business Suite .................................................... 21 Figure 25: Data Definition................................................................................................. 21 Figure 26: Concurrent Program Definition..................................................................... 22 Figure 27: Template Definition ........................................................................................ 22 Figure 28: Use XDODTEXE for Data Templates............................................................ 23 Figure 29: Concurrent program parameters .................................................................. 24 Figure 30: Example of metadata query ........................................................................... 25



1. Standards for Layout Templates 4 of 4

1. Standards for Layout Templates

Best practices for layout templates. It is important that the layout template is readable and that it resembles the layout of the report. This chapter gives several guidelines to achieve this.

The general rule for creating templates is to stick to the KISS principle (http://en.wikipedia.org/wiki/KISS_principle) or in other words, keep it as simple a possible. Do not create any programming in the layout template if it can be done in the XML data (e.g. data template). Calculations can be done more easily in SQL than in the layout template.

Form Field Usage

In order to define a layout with XML Publisher we need to use several statements. These statements can become quit long and disort the layout of the template. In order to hide the XML Publisher statements it is recommended to use as much form fields as possible.

Form Field Naming

You can give a name to each form field. In order to make the layout template more readable, that the names should be understandable and readable. It is recommended that you do not group different statements together in one form field. On the other hand, it is a good idea to put logic that belongs together (e.g. setting and getting the same variable) in one form field.

Figure 1: Give clear names to form fields

For control statements – statements that do not print data on the report – the names should be short but descriptive. A suggestion for the most common control statements:

� Repetition (for-each): FE: G_USER and EFE: G_USER It is important that you set the group name that is repeated in the form field name. This way it is clear to the reader of the template what a specific for-each statement does.

� Condition (if): IF and EIF � Variable setter (set_variable): SVAR � Variable getter(get_variable): GVAR

For data statements – statements that do print data – the names should represent the data that is printed. Or even better: it should be an example of the data. An example: when you want to print a bill-to address on an invoice, you should print: 26-Feb-2002 instead of the XML element name: FU_START_DATE. See Figure 2: Example RTF template layout with data in form field names.




Figure 2: Example RTF template layout with data in form field names

This way, it is completely clear what is printed and the correct length for the data in the form field is shown. During designing it is easy to see how the report will look like and that makes building layout templates much easier. Doing this allows you to see if the columns widths are wide enough for displaying the data.

Form Field Layout

Example mark-up color schema for control statements:

• Repetition: FE:G_USER (yellow background with bold black text) • Condition: IF (green background with bold black text) • Variables / page totals: VAR (red background with bold black text) • Other special statements: start:body (blue background with bold black text)

Please note: we can’t use color schemes for statements that print data, as the layout will be applied on the printed data. This section therefore only applies to the form fields with statements that control data – but do not print data.

Fields without any color formatting are used to print data. All other text, not in a form field is treated as normal 'hard-coded' text.

Another way to make the template more readable is to show only the form fields that are printing data. We can hide the control form field in the Font option window.




Figure 3: Hide control statements

After this is done, it is easy to switch on and off the visibility of the control statements with the show/hide icon:

Together with the naming rule that states that the name should be an example of the data, this makes the layout resemble the report as much as possible.

Layout Template Example

Please see Figure 4 and Figure 5 for an example of how the readability of the layout template is influenced by the standards we propose here. In Figure 4 only the form fields, which contain data statements are shown and the layout resembles the layout of the report. All the other form fields (the control statement) are using the ‘Format – Font – Hidden’ functionality from Microsoft Word. These control statements form fields are formatted according to their colorschema to make them more visible (see Figure 5).




Figure 4: Layout template with control statements hidden

Figure 5: Layout template with control statements visible

Subtemplates

When designing multiple layout templates with the same layout region (e.g. header, payment options), you should increase maintainability by using subtemplates. You can define a subtemplate by using this construct: <?template:NAME?> and <?end




template?>. When you load this layout template into the E-Business Suite, you can use it in all of your other templates layouts.

Please note: it is important that you check the checkbox for subtemplate when creating the template definition in E-Business Suite. This cannot be done after the template definition is created.

Figure 6: Subtemplate dropdown list

First you need to import the subtemplate in the calling template with:

� In E-Business Suite from the database (version 5.6.2 and higher).: <?import:xdo://MYMODULE.MYSHORTCODE.en.US?>

� During development from your local driver: <?import:file:D:////My Documents/XXOCS_COMMON.rtf?>

Then you can use <?call:NAME?> to re-use the layout from the subtemplate.

Please be reminded that the data structure should contain the same elements for the two instances in which you call the subtemplate.

Headers and Footers

There are several ways to define the layout for the headers and footers of the report. One drawback however, is that Microsoft Word does not allow form fields in its headers and footers. An option is to type out the content of the form fields, but this will result in long statements (a less readable template).

As long as you have the same header/footer on each page of your report you should use the statements <?start:body?> and <?end:body?>. Everything between these statements is positioned in the body of the report. All layout before the <?start:body?> becomes the header and everything after <?end:body?> becomes the footer. In this way you can use form fields and the layout-template will be more readable. Whenever you want a different first page header/footer you can't use the <?start:body?> and <?end:body?>. We advise you to call a subtemplate from the standard Word header or footer region.

When there is a universal header or footer (i.e. one that is used in multiple templates) then the alternative for the headers and footers are subtemplates. You can define one subtemplate for the header and one for the footer. Finally, call them in the header and footer region of Microsoft Word.

Naming Standards

The name of the layout template should comply with the naming standards for customizations. This means that it should start with the customization schema name.




The template file should contain the CODE field from the Template Definition in the E-Business Suite (see Template Definition Setup).

CCCC_GG_DDDDD.rtf or CCCCGGDDDDD.rtf

CCCC = Custom Application short name GGG = Two- or three-letter functional group code DDDDD... = The code of the template definition (you can use more than 5 characters here).

For example if we are creating an Invoice with code (RAXINV) the name can be anything like:

� XXES_AR_RAXINV.rtf

� ESARINV.rtf

Version Control

The E-Business Suite does not support versioning of uploaded layout templates. Therefore it is important to indicate the version or state of the layout template. We cannot do this in the filename, because any CVS or SVN system will not recognize files with changing names, so we need some comment field in the layout template. This method allows the developer to see which version is uploaded in the environment. When you do not use a version control system, then it is a good practice to add a timestamp to the template name (e.g. ESARINV_20071218.rtf).

See Figure 7 for an example of a version comment in the RTF template. The XML Publisher statement <?if:1=2?> makes sure the text is never printed. You can hide this comment text, so that it only appears when you want to see the control statements.

<?if:1=2?> ##########################################################################

Application : application of the template definition

Module : code of the template Definition

Author : First Name Last Name

Date Created : DD-MON-YYYY Description : This is the XML Publisher template for

code of the template Def Modification History ==================== Who When Ver. What === ========== === ====

First Name Last Name DD-MON-YY 1.0 Created ##########################################################################

<?end if?>

Figure 7: Version comment in RTF layout template

Best Practices for Layout Template Building

This paragraph gives several best practices that you should follow when building a layout template.

Output Types

Start thinking about the output types of your document, before developing. It could well be that a perfectly build document for one format will not produce a correct output in another output type. For example, Excel and Word display tables differently. A good way to build for multiple output types, is to check what features work for both types and test regurarly in both output types.




Performance Consideration

Take the grouping structure of the XML data into account when selecting data. If you use XPath statements to reach higher data groups in the XML, it will have a negative influence on the performance of the report. This because the XSL-FO engine needs to do a lot of scope swapping between current and higher levels in the XML data.

For example, if you need to access a XML element on the root level of your XML data multiple times, it is advisable to put the value in a variable and access the variable instead of the XML element. This will save the XSL-FO engine a lot of scope swapping and thus will have better performance.

Metalink Note 458794.1 Oracle Business Intelligence Publisher Performance Tuning Guide includes several additional performance tips.

Use Word Tables

Whenever you try to position data on the layout template, it is best to do this with a Word table. Tables in Microsoft Word have several advantages:

� It is easy to insert lines and borders to your layout template by enabling the option for borders in the table. Also you can use the background color of cells and rows to format the layout of your template.

� By changing the width and height of cells you can position the data exactly where it needs to be. It is also possible to merge cells in a way that they span over multiple rows or columns.

� With table you can enable certain Word options. First, to repeat one row as a header row on top of each page. Second, to dis-allow or allow splitting the row on a line break.

� Tables work well in combination with the repetition and conditional statements. The repetition of a complete row is done by starting the for-each in the first cell of the row and end it with the end for-each in the last cell of the row.



2. Standards for XML Data 11 of 11

2. Standards for XML Data

Basically, the XML data file is out of scope for XML Publisher (except maybe for data templates). You are free to use whatever means to get the XML data for your report. However, there are some best practices you might want to comply to.

It is important to ask yourself several questions about the XML data before you are beginning to define the XML structure. These questions can be:

� How many different layout templates are you going to develop on this XML? Take the requirements of each of the templates into account when thinking about the XML structure.

� Do you want to use bursting? If yes, then all elements outside the scope of bursting won't be accessible after the bursting process.

Where to get the XML

One of the key characteristics of XML Publisher is that it can work with any data source, as long as the data provided is in the XML format.

When you are free to choose your data source, the best way is by using Data Templates. This was added in XML Publisher 5.6.1 and is fully integrated into the E-Business Suite. The significant advantage is that it is up to 30% faster than Oracle Reports. In addition to that, it won’t require the customer to license Oracle Reports Builder to maintain the data source.

Most of the times XML Publisher is brought in as a replacement for older reports build with Oracle Reports. The whole data structure is already defined in the Oracle Reports and then for compatibility you can simply use the Oracle Report to produce the XML data. Because no Data Template has to be built, the advantage is that deployment of XML Publisher is really quick.

Figure 8: Example of XML data generated by Report

The drawback however is that the customer needs a license for Oracle Reports and for big reports the performance might downgrade. But since the original report was there anyway, the customer probably already has a license.

Oracle Reports are out of scope for the standards defined in this document. But you can comply with the conventions described in the next paragraph.

Please note: you can use the migration tool to convert Report 10g to XML Publisher Data Templates. See XML Publisher’s website: http://bipublisher.us.oracle.com/. Here you can also find a tool to convert the Report's layout to an RTF template.

3. Standards for Data Template 12 of 12

3. Standards for Data Template

The XML Publisher data engine enables you to rapidly generate any kind of XML data against any database in a scalable, efficient manner. The data template is the method by which you communicate your request for data to the data engine. It is an XML document whose elements collectively define how the data engine will process the template to generate the XML.

Because the data template is defined as an XML file we should use XML based comments for version tracking. Every data template should start with a comment header.











     

 

Figure 9: Data template header

Data Template Elements

A data template contains the following elements: parameters, data queries, data-triggers and a data structure. This chapter describes standards and best practices for each of these elements.

Figure 10: Data template structure

Data Template Root Element

The root element has four attributes. The name and the version attributes are required.

� name Required. This will be the name of the root element of the XML data generated by the data template. Make sure the name is equal to the CODE of the data definition in E-Business Suite (see the two figures below).




Figure 11: Data Definition code

Figure 12: XML root element name

� description Required. Use the name from the data definition in E-Business

Suite (see Data Definition Setup). � defaultPackage Optional. The PL/SQL package name to resolve any lexical

references, group filters, or data triggers defined in the template. The naming standard for this package: XXOCS_XDO_<code of the Data Definition>_PKG

� version Required. This is a required field containing the version of the data template definition, currently this is 1.0.

Data Template Properties

This section of the data template describes some settings for the workings of the data engine of XML Publisher.

The values you use for these setting depend on the requirements of your report. Regard the instructions we provide here as a guideline.

<properties> <property name="include_parameters" value="true" /> <property name="include_null_element" value="true" /> <property name="xml_tag_case" value="upper" /> <property name="db_fetch_size" value="500" /> <property name="scalable_mode" value="off" /> <property name="include_rowsettag" value="true" /> <property name="debug_mode" value="off" /> </properties>

Figure 13: Data template properties

� include_parameters This option lets you print the parameter and the values in the XML data. We might need this information in the layout template, so set this to true.

� include_null_element This option lets you hide empty elements in the XML data. We might need some element to test if it is empty,




when the element is not in the XML data we cannot do that. Set this value to true.

� xml_tag_case The case of the XML elements. XML Publisher is case-sensitive in selecting the element. To avoid confusing it is important to have this always to upper. Oracle Reports also generated XML data with upper-case element names.

� db_fetch_size Sets the number of rows fetched at a time through the jdbc connection. The default value is 500. Whenever you receive an error about exhausted memory, you need to lower the fetch size. Important: For large queries with many columns, set the value to 20. Otherwise the memory footprint is significantly increased.

Figure 14: Error when db_fetch_size is too large

� scalable_mode Sets the data engine to execute in scalable mode. This is required when processing a large volume of data. When you are not processing large amounts of data set this to off.

� include_row_settag This option lets you add a grouping element arounf your row element in the XML data. For example, all G_USER elements will be included in a LIST_G_USER group. This has some advantages when testing for existence of groups. Some XPath statements are dependent on the structure of the XML data. Be sure not to change this when layout development has started, otherwise you might need to redo all Xpath queries. If you have only one SQL statement without a data structure in the data template, then this option is always true.

� debug_mode This prints additional debug lines to the concurrent request log. During development of the template. set this to on, since this gives information about SQL queries, bind variables and timings. In production this should be off in order to limit the log size.

Data Template Parameters

A parameter is a variable whose value can be set at runtime. Parameters are especially useful for modifying SELECT statements and setting PL/SQL variables at runtime. The Parameters section of the data template is optional.

<parameters> <parameter name="P_USER_ID" dataType="number" defaultValue="1"/> </parameters>

Figure 15: Data template parameters

� name Required. The name of the parameter. Make sure this always starts with a P_ and that the name is in uppercase. Example: P_USER_ID.




� dataType Optional (default: character). Specify the parameter data type as "character", "date", or "number". Default value is "character".

� defaultValue Optional. This value will be used for the parameter if no other value is supplied from the data at runtime.

Figure 16: Parameter token name

Within the E-Business Suite the parameter name is entered via the token field (case-sensitive).

Data Template Data Queries

This is a required section for defining one or multiple queries for fetching the data for the report. In the XML data it is very important to have information about start date, requestor, data template update date, database name etc. Therefore it is recommended to use some sort of metadata query, see appendix A for an example of a query for metadata. The following column types are selectable:

� VARCHAR2, CHAR

� NUMBER

� DATE, TIMESTAMP

� BLOB. The BLOB must be XML or an image. Images are retrieved into your results XML as base64 encoding. You can retrieve any image type that is supported in the RTF template (jpg, gif or png). You must use specific syntax to render the retrieved image in your template.

� CLOB The CLOB must contain text or XML.

� XMLType

Make sure that all column aliases in all the data templates are unique. This will avoid a lot of confusion that duplicate names can cause. Furthermore, by using a query prefix in the name of each column, it is clear from which query the data is coming from.

When writing the SQL statements keep in mind that XML Publisher is using a “hashing methodology” to index the content. Therefore it is advised to keep the length of names short but still descriptive enough.

Make sure you create data queries for the same groups you want to print in your report. So if you need headers and lines in the report, make two queries Q_HEADERS and Q_LINES.




Figure 17: Data template queries

� name Required. The name of the query. Make sure this always starts with a Q_ and that the name is in uppercase. Example: Q_USER. Make sure that the column alias names are unique with the query.

Data Template Data Triggers

The data triggers execute PL/SQL functions at specific times: before or after the execution and generation of XML output. Using the conditional processing capabilities of PL/SQL for these triggers, you can do things such as perform initialization tasks and access the database. Data triggers are optional, and you can have as many <dataTrigger> elements as necessary. Alternatively, you can use GroupFilter to filter the groups in the XML during processing (see section on Group Filters).

The location of the trigger indicates at what point the trigger fires:

� Place a beforeReport trigger anywhere in your data template before the <dataStructure> section. A beforeReport trigger fires before the dataQuery is executed. An example of a function of the BeforeReport trigger is to order the data depending on a parameter.

� Place an afterReport trigger after the <dataStructure> section. An afterReport trigger fires after you exit and after XML output has been generated. An example of a function of the AfterReport trigger is that the second layout needs to be generated, or to call the Bursting concurrent program.

<dataTriggers> <dataTrigger name = "beforeReport" source = "XXOCS_XDO_<code of the DataDef>_PKG.beforeReport()"/> <dataTrigger name = "beforeReport" source = "XXOCS_XDO_<code of the DataDef>_PKG.beforeReport(:PARAM)"/> </dataTrigger>

Figure 18: Data template data triggers




� name Required. The event name to fire this trigger. This can be beforeReport or afterReport.

� source Required. The PL/SQL <package name>.<function name> where the executable code resides.

Data Template Data Structure

In the datastructure section you define what the XML output will be and how it will be structured. The complete group hierarchy is available for output. You can specify all the columns within each group and break the order of those columns. You can use summaries, and placeholders to further customize within the groups. The datastructure section is required for multiple queries and optional for single queries.

The source attribute of the group element references a query. This can be the same query on different groups in the data structure, in order to generated multiple nested groups based on a single query.

<dataStructure> <group name="G_USER" source="Q_USER"> <element name="FU_USER_ID" value="FU_USER_ID" /> <element name="FU_USER_NAME" value="FU_USER_NAME"/> <group name="G_RESP" source="Q_RESP"> <element name="RSP_APPLICATION_NAME" value="RSP_APPLICATION_NAME" /> <element name=" RSP_START_DATE " value="RSP_START_DATE"/> </group> </group> </dataStructure>

Figure 19: Data template data structure

� name Required. Defines the name for the group. Give the group a name that starts with G_ and give the element a name that is unique for the XML file.

� source Required. For group elements, defines from which query the data comes.

� value Required. For the element , the name of the column or the column alias within the query where the data comes from.

Group Filters & Aggregate Functions

Filters enable you to conditionally remove records selected by your queries, however, this approach impacts performance. Groups can have user-created filters, using PL/SQL. The PL/SQL function must return a boolean value (TRUE or FALSE). Depending on whether the function returns TRUE or FALSE, the current record is included or excluded from the XML data output.

It is strongly recommended that you use a WHERE clause instead of a group filter to exclude records from your extract. As the WHERE clause is performed by the database whereas the filter is processed by the application server. The database is performance-wise a better choice.

For example, a sample PL/SQL group filter function might be:

FUNCTION G_EMPFilter RETURN boolean IS BEGIN IF :EMP_SAL < 1000 THEN RETURN (FALSE); ELSE RETURN (TRUE); END IF; END;




For this function the group filter in your data template definition can be something like:

<group name = "G_DEPT" source = "Q_DEPT" groupFilter="XXOCS_XDO_<code of the DataDef>_PKG.G_EMPFilter(:DEPTSAL)"> <element name="DEPT_NUMBER" value="DEPTNO" /> <element name="DEPT_NAME" value="DNAME"/> <element name="DEPTSAL" value="G_EMP.SALARY" function="SUM()"/> …

Figure 20: Group filter example

Sometimes you need to perform an update every time a report has being printed (AR Invoice). This can be solved with a GroupFilter: logging and debugging, insert, update and delete of data.

Aggregate Functions

You can use aggregate functions in the element of the data structure. Examples are the SUM(), AVG(), COUNT(), MIN(), MAX() functions (currently only on numeric values). See the SUM function in Figure 20: Group filter example.

Naming Standards

The name of the data template should be descriptive and it should be clear that it belongs to the data definition. Furthermore, because several XML files are created (bursting control file, preview data, data template), there needs to be a way to distinguish between them. Create the name in capitals and end the filename with _DT.xml.

CCCC_GG_DDDDD_DT.xml or CCCCGGDDDDD_DT.xml

CCCC = Custom Application short name GGG = Two- or three-letter functional group code DDDDD = The code of the data definition (you can use more than 5 characters here).

For example: XXES_AR_RAXINV_DT.xml or ESARINV_DT.xml

XML Elements and Structure

It is important that the XML data follows some general rules.

Naming Standards

Because selection of data in the layout template is done by name, it is important that the element names from the XML are unique. This will make sure you do not accidentally select the wrong data in the layout template. A good practice is to use a short name for the group that you are in and use that as a prefix for the elements within that group. See the example below. Here we have three nested groups; GENINFO, USER and RESP, the elements all have a prefix resp. GEN, FU, RSP. This makes elements such as START_DATE and END_DATE – which exist within multiple groups – unique.




Figure 21: Example XML

In order to have a clear distinction between data element and data group make sure that each group name starts with G_. See example in Figure 21: Example XML.

Nesting

Nearly all reports that are created with XML Publisher have a number of repeating groups in it. Ideally, the nesting structure of the XML data should resemble the repeating structure in the layout-template.

The alternative is to re-group (for-each-group statements) the XML data based on the requirements of the layout template. Unfortunately, regrouping the XML takes up a lot of calculations and memory which will have a negative influence on the performance of the report.

Display Fields

The data in the XML file can be divided into two groups: calculation data and display data. Calculation fields contain raw data, for example a number in the American format. XML Publisher can only calculate with numbers in this format.

If we like to display a number in another format we can include display fields in the XML data. You can create display fields by using the to_char function. Make sure these display fields have the prefix: ‘D_’.

<INVOICE_AMOUNT>1234.89</INVOICE_AMOUNT> <D_INVOICE_AMOUNT>1.234,89</D_INVOICE_AMOUNT>

Figure 22: Display fields in the XML data



4. Standards for Bursting Control File 20 of 20

4. Standards for Bursting Control File

The bursting control file is relatively new for XML Publisher. It was introduced with bursting in XML Publisher 5.6.1. This chapter discusses some standards for this file.

<?xml version="1.0" encoding="UTF-8"?> <xapi:requestset xmlns:xapi="http://xmlns.oracle.com/oxp/xapi" type="bursting"> <xapi:request select="/ROOT/G_USER"> <xapi:delivery> <xapi:email id="123" server="rgmemeasmtp.oraclecorp.com" port="25" from="[email protected]"> <xapi:message id="123" to="${FU_EMAIL_ADDRESS}" attachment="true" subject="${EMAIL_SUBJECT}"> Dear ${FU_USER_NAME},

Please find message attached.

Regards,

${FU_SENDER} </xapi:message> </xapi:email> <xapi:print id="printer" printer="ipp://printer.oracle.com" copies="1"/> </xapi:delivery> <xapi:document output="${FU_USER_NAME}" output-type="pdf" delivery="123"> <xapi:template type="rtf" filter="FU_EMAIL_ADDRESS IS NOT NULL]" location="xdo://AR.RAXINV.en.00/?getSource=true"/> </xapi:document> </xapi:request> </xapi:requestset>

Figure 23: Bursting control file example

Dynamic Data

As shown in Figure 23: Bursting control file example, dynamic data can be used within the bursting control file with: ${XML_ELEMENT}. You should use as many dynamic references as possible, as this makes the bursting control file more dynamic. All necessary data should be present in the XML data under the group on which bursting is taking place.

Naming Standards

The name of the bursting control file should be descriptive and it should be clear that it belongs to the data definition. Furthermore, because several XML files are created (bursting control file, preview data, data template), there needs to be a way to distinguish between them. Create the name in capitals and end with _BC.xml.

CCCC_GG_DDDDD_BC.xml or CCCCGGDDDDD_BC.xml

CCCC = Custom Application short name GGG = Two- or three-letter functional group code DDDDD = The code of the data definition

For example: XXES_AR_RAXINV_BC.xml or ESRAXINV_BC.xml



5. Standards for E-Business Suite Setup 21 of 21

5. Standards for E-Business Suite Setup

The setup of XML Publisher documents is done under the XML Publisher Administrator responsibility. You can setup two elements: the data definition and the template definition (see Figure 24: XML Publisher setup in E-Business Suite). This chapter describes the standards for this setup.

Figure 24: XML Publisher setup in E-Business Suite

Data Definition Setup

The name of the concurrent program should be used in the name of the data definition. But the name should have a prefix with the customization. For example XXOCS: User(s) + Responsibilities.

Figure 25: Data Definition

The application for whihc you create the data definition should be the same as the application of the concurrent program. Also, the code of the data definition should be the same as the short name of the concurrent program.




Figure 26: Concurrent Program Definition

Template Definition Setup

When defining a template definition you can provide your own value for the code field. There are no restrictions on it, except that it should be unique. If you are creating only one template definition for the data definition, then it is a good practice to use the same code as the data definition (the concurrent program’s short name).

If you are defining multiple templates upon one data definition, then make sure that the codes are understandable.

Think about all the codes you want to use before defining anything, because the code field cannot be changed after creation of the template definition (or the data definition).

Figure 27: Template Definition

The name of the concurrent program should be used for the name of the data definition. You can also use this name for the Template Definition name. Allthough, when there are multiple templates based on one data definition, all template definitions should have a unique and understandable name. The code of the template can be different from the code of the data definition (i.e. and therefore different from the short name of the concurrent program).




Setting a Default Template

You can select a default template that will be sent by the concurrent manager to XML Publisher to publish the report unless the user selects another. This default template will display in the Submit Request form. Using this feature, your users do not have to explicitly select the template every time they run the report.

Select a default template in the Update Concurrent Program page available from the System Administration responsibility. Please note that this field is available only from System Administration and that it is not available from the System Administrator Forms interface.

Translations

You can upload translations (XLIFF definition) with the Template Definition in E-Business Suite. Each translation should be written in an XLIFF file. These files should have a name that includes the code of the template definition it belongs to and also should indicate towards what language the translation takes place. For example: OCSFNDUSER_LIST.nl.xlf.

Concurrent Program setup

The restrictions on a concurrent program that you want to use with XML Publisher are the following:

The output format of the concurrent program should be XML. When you want to use a data template the executable should be XDODTEXE.

Figure 28: Use XDODTEXE for Data Templates

When defining a parameter for the concurrent program, make sure you use the exact name in the token field as the name you have defined in the data template for the parameter (see Figure 15: Data template parameters).




Figure 29: Concurrent program parameters

XDO Loader

For loading XML Publisher elements such as RTF template, data template or the bursting control file you should use the XDO Loader tool. You can call this from the driver script that installs your customization. The arguments for this tool are listed below in an exampl e to load a RTF template.

The LOB_TYPE should indicate what type of file is being loaded:

• TEMPLATE_SOURCE – load a template • DATA_TEMPLATE – load a data template defined in XML format. • BURSTING_FILE – load a bursting control file defined in XML format.

Respectively the XDO_FILE_TYPE should be

• RTF – RTF template • XML-DATA-TEMPLATE – data template • XML-BURSTING-FILE – bursting control file

Do not forget the last line: CUSTOM_MODE FORCE. This makes sure already loaded elements will be overwritten. If you forget this line the file will not be loaded when was changed or loaded by some other tool or user.

/opt/java1.5/bin/java oracle.apps.xdo.oa.util.XDOLoader \ UPLOAD \ -DB_USERNAME apps \

-DB_PASSWORD apps \

-JDBC_CONNECTION sand:1535:NADV \

-LOB_TYPE TEMPLATE_SOURCE \

-APPS_SHORT_NAME XXCUST \

-LOB_CODE XXCUST_CP \

-LANGUAGE en \

-TERRITORY US \

-XDO_FILE_TYPE RTF \

-FILE_CONTENT_TYPE 'application/rtf' \ -FILE_NAME XXCUST_CP.rtf \

-NLS_LANG $NLS_LANG \

-CUSTOM_MODE FORCE \



Appendix A. Metadata Query 25 of 25

Appendix A. Metadata Query

When XML data is generated it is impossible to see how and when it was generated. Therefore it is necessary to have some metadata information in each XML file that is generated. In Figure 30: Example of metadata query you can see an example of a query that should be added to the data template in order to have some descriptive information in each generated XML data.

<sqlStatement name="Q_GENINFO"> <![CDATA[

SELECT fcp.CONCURRENT_PROGRAM_NAME gen_cp_name , fcr.argument_text gen_cp_arguments , fcpa.argument1 gen_template_application , fu.USER_NAME gen_requestor , fcpa.ARGUMENT2 gen_template_code , xt.TEMPLATE_NAME gen_template_name , xl.LAST_UPDATE_DATE gen_template_last_update_date , db.name gen_db_name , fcr.REQUEST_ID gen_request_id

FROM fnd_concurrent_requests fcr , fnd_concurrent_programs fcp , fnd_conc_pp_actions fcpa , fnd_user fu , xdo_templates_vl xt , xdo_lobs xl , v$database db

WHERE fcr.REQUEST_ID = fnd_global.CONC_REQUEST_ID

AND fcpa.CONCURRENT_REQUEST_ID (+) = fcr.REQUEST_ID

AND fcpa.ACTION_TYPE (+) = 6

AND fcp.CONCURRENT_PROGRAM_ID (+) = fcr.CONCURRENT_PROGRAM_ID

AND xt.APPLICATION_SHORT_NAME (+) = fcpa.argument1

AND xt.TEMPLATE_CODE (+) = fcpa.ARGUMENT2

AND fu.USER_ID = fcr.REQUESTED_BY

AND xl.APPLICATION_SHORT_NAME (+) = fcpa.ARGUMENT1

AND xl.LOB_CODE (+) = fcpa.ARGUMENT2

AND xl.LANGUAGE (+) = fcpa.ARGUMENT3

AND xl.TERRITORY (+) = fcpa.ARGUMENT4

AND xl.LOB_TYPE (+) = 'TEMPLATE' ]]> </sqlStatement>

Figure 30: Example of metadata query

Some other suggestions for meta-data: � production system Y or N � sysdate � Data Definition used � Data Definition last_update_date � Data Template used � Data Template last_update_date � Bursting Control File used � Bursting Control File last_update_date � Template used � Template last_update_date � Descriptive Flexfield attached to the template (date mask, number mask)



Appendix B: Overview Naming Convention 26 of 26

Appendix B: Overview Naming Convention

The following names are to be used for the files concerned in XML Publisher extensions:

CCCC = Custom Application short name GGG = Two- or three-letter functional group code DDDDD = The code of the data definition (you can use more than 5 characters here)

File Type Naming Standard

Data Template CCCGGGDDDDD_DT.xml

Bursting Control File CCCGGGDDDDD_BC.xml

Preview XML Data CCCGGGDDDDD_PD.xml

Package Specification CCCGGGDDDDD_PKG.pks or CCCGGGDDDDD.pls

Package Body CCCGGGDDDDD_PKG.pkb or CCCGGGDDDDD.plb

Layout Template CCCGGGDDDDD_YYMMDD.rtf

or when using SVN/CVS: CCCGGGDDDDD.rtf

XLIFF File CCCGGGDDDDD_nl_00.xlf (language, territory)

FND Download (Data Def and Template Def)

CCCGGGDDDDD.xdd



Open and Closed Issues for this Deliverable 27 of 27

Open and Closed Issues for this Deliverable

Open Issues

ID Issue Resolution Responsibility Target Date Impact Date

None.

Closed Issues

ID Issue Resolution Responsibility Target Date Impact Date

None.

STANDARDS & BEST PRACTICES

Documents

Transcript of STANDARDS & BEST PRACTICES