practical setup and implementation of xml publisher...

Practical Setup and Implementation of XML Publisher Templates Session #30733 Tuesday, March 20, 2012 (10:45 AM – 11:45 AM)

Agenda/Contents • Overview • Your presenter • Deloitte • What are we talking about? • The basics – code examples • More advanced – code examples • Best practices • Summary

Overview • Not about 3C communications

– Campus Solutions Letter configuration – Communication Generation (CommGen)

• Not about setting up XML Publisher

– Data Sources – Report Definitions

• Alliance 2010: Communications Configuration and

Communication Generation – Common Questions and Helpful Hints

Presenter

Presentation Notes

Alliance 2010: Communications Configuration and Communication Generation – Common Questions and Helpful Hints - http://www.heug.org/p/do/sd/topic=991&sid=10077 However, I will use admissions letters as examples because that is what I’m most familiar with. But I have worked on the advisement report template and a few custom reports and the principles are the same.

Overview • All about XML Publisher RTF templates

• Concepts common to 3C communication templates,

custom report templates, transcript templates, etc.

• Coding examples

• Based on my own experience creating complex XMLP Templates

Presenter

Presentation Notes

When I started designing more complex templates, I found that The available documentation was lacking – While there is lots of documentation out there, little of it has to do with coding the templates. And what is out there is rather lengthy, covering lots of different topics, and not a good way to get started.� The language I’d come to use was incorrect, often because I didn’t really know what I was doing – I found myself referring to an “XML template” while talking with a technical person and received a confused look. When I needed to figure out how to do something new, I didn’t know what to look for – In this presentation I not only want to show you a few useful functions but also give you a bit of knowledge so you can find what you need.

Your Presenter • Michael Eastwood

– A senior specialist with Deloitte. – Based out of Halifax, NS. – Eleven years experience in higher education. – Cover campus community, recruiting & admissions, student

records, and academic advisement modules of PeopleSoft Campus Solutions.

– Has acted as a functional lead for upgrades and implementations of both versions 8.9 and 9.0.

– Fourth time presenting at Alliance.

Presenter

Presentation Notes

This presentation is kind of a follow up to my 2010 presentation. Would have like to do it last year but I was not able to attend.

Deloitte. • Deloitte Touche Tohmatsu is an organization of member firms around the world

devoted to client service excellence. Member firms offer services in audit, tax, consulting and financial advisory.

• Consultants from Deloitte member firms help organizations plan, grow and structure their business to address key issues such as strategy, technology and change management.

• Consulting services include: • Enterprise Applications • Human Capital • Technology Integration • Strategy and Operations • Regulations (Enterprise Risk Services) • Security and Privacy (Enterprise Risk Services)

• Deloitte has an established and growing Higher Education Practice in North America

• Deloitte has developed proprietary Total CampusTM Tools and Methodologies specific to Higher Education

What are we talking about?

What are XMLP Templates? • XML - stands for eXtensible Markup Language

– designed to carry data, not to display data – does not really DO anything

• XSL - stands for eXtensible Stylesheet Language – Style sheets for XML – Style sheets describe how documents are presented on

screens and in print

Presenter

Presentation Notes

XMLP = XML Publisher = BI Publisher – I still use XMLP because BIP Templates just sounds weird. XML was designed to carry data and does not really do anything.

What are XMLP Templates? • XML is the format of the data

• XSL displays the data on the screen

• XMLP templates are RTF documents marked up

with BI Publisher’s simplified XSL

Presenter

Presentation Notes

RTF = Rich Text Format XMLP Templates and not XML at all, it is XSL

What is XSL? • eXtensible Stylesheet Language

• Consists of three parts

– XSLT – eXtensible Stylesheet Language Transformations

– XSL-FO – eXtensible Stylesheet Language Formatting Objects

– XPath – a language for navigating attributes and elements in

XML documents

Presenter

Presentation Notes

Not going into detail about this because it is a bigger topic and could consume an hour by it’s self. It is enough to know that XMLP templates use XSL, which is made up of these three parts. If you find you self looking for how to do something, using XSL, XSLT, or XPath in your Google search will help you get good results.

What does this mean in XMLP? • BI Publisher’s RTF Template Parser converts RTF documents

to XSL-FO

• You can add data fields and other markup to templates using BI Publisher's simplified tags for XSL

• BI Publisher also supports pure XSL elements in a template

• In fact, you can include any XSL element, many FO elements, and a set of SQL expressions extended by BI Publisher

Presenter

Presentation Notes

Note: For XSL equivalents of BI Publisher tags, see XSL Equivalent Syntax, page 8-15 of Oracle BI Publisher - Report Designer's Guide

What does this mean in XMLP? • If you use BI Publisher’s simplified tags, you are one step

removed from real XSL

• Pro: Easier to understand

• Con: Harder to find solutions to more complicated requirements

The Basics Coding Examples

The Basics • BI Publisher supports two methods for creating RTF

templates: 1. Basic RTF Method 2. Form Field Method

• To use XSL or XSL-FO code rather than the simplified syntax, you must use the form field method

Presenter

Presentation Notes

Basic RTF Method Use any word processing application that supports RTF version 1.6 writer (or later) to design a template using BI Publisher's simplified syntax. Form Field Method Use Microsoft Word's form field feature to place the syntax in form fields, rather than directly into the design of your template.

The Basics • The examples that follow are all from RTF templates

created in MS Word using the BI Publisher add-in

• All use the simplified syntax and form field method

• The code shown is contained within form fields in the actual templates, unless otherwise noted

Sample XML Data <SCCquery_DS_ADMA_PROGRAMS numrows="2" queryname="DS_ADMA_PROGRAMS"> <row_DS_ADMA_PROGRAMS rownumber="1"> <APPL_PROG_NBR>0</APPL_PROG_NBR> <ACAD_CAREER>UGRD</ACAD_CAREER> <ACAD_PROG>BA</ACAD_PROG> <PROG_DESCR>Bachelor of Art</PROG_DESCR> <ACAD_PLAN>BABIOL</ACAD_PLAN> <PLAN_DESCR>Biology (BA)</PLAN_DESCR> <PROG_STATUS>CN</PROG_STATUS> <PROG_ACTION>DENY</PROG_ACTION> <ACTION_DESCR>Denied</ACTION_DESCR> <ADMIT_TERM>1118</ADMIT_TERM> <TERM_DESCR>Fall 2011</TERM_DESCR> </row_DS_ADMA_PROGRAMS> <row_DS_ADMA_PROGRAMS rownumber="2"> <APPL_PROG_NBR>1</APPL_PROG_NBR> <ACAD_CAREER>UGRD</ACAD_CAREER> <ACAD_PROG>BA</ACAD_PROG> <PROG_DESCR>Bachelor of Art</PROG_DESCR>

Presenter

Presentation Notes

This is a sample XML file, the data. Notice that there can be multiple child elements within a single parent. Each element can have attributes, in this example, one on the parent to indicate the number of children (rows) and one on each child to indicate the row number.

For-Each Statement • Allows you to repeat the same text or conditional test for

each row, a.k.a., a loop (XSLT)

<?for-each:row_DS_ADMA_PROGRAMS?>

<?sort:APPL_PROG_NBR;'ascending';data-type='text'?>

- <?PROG_DESCR?> <?PLAN_DESCR?> - <?ACTION_DESCR?>

<?end for-each?>

Presenter

Presentation Notes

Syntax: <?for-each:element_name?> <?end for-each?> The sort statement is also based on XSLT. <?PROG_DESCR?> is a placeholder for the value of that element in the XML file.

If Statement • Used to perform a conditional test against the data (XSLT)

<?if:PROG_STATUS = ‘WT’?> Insert text and markup code here. <?end if?>

• Inlines <?if@inlines:PROG_ACTION = ’DENY’?>Insert text and markup code here.<?end if?>

Presenter

Presentation Notes

Syntax: <?if:expression?> <?end if?> Inlines keeps the if statement in line with the current block, for example, the current paragraph of text. When using “inlines” you, of course, want to avoid any line breaks between the code, in this example the if statement, and the text you want to display or not depending on the results of the condition. No ELSE statement with this IF statement. This is usually not a problem because you can easily have two if statements, one the opposite of the other.

Choose Statement • Allows you to express multiple conditional tests (XSLT)

<?choose:?> <?when:PROG_STATUS='AD'?> Insert text and markup code here. <?end when?> <?when:PROG_STATUS=‘WT'?> Insert text and markup code here. <?end when?> <?otherwise:?> Insert text and markup code here. <?end otherwise?> <?end choose?>

Presenter

Presentation Notes

Syntax: <?choose?> <?when:expression?> <?end when?> <?otherwise:?> <?end otherwise?> <?end choose?> You can have multiple when statements within the choose and the otherwise is not required but is nice because it acts as an else, i.e., if the criteria of the various when statements is not met then it will execute what is contained in the otherwise.

More Advanced Coding Examples

Specifying Attributes and Elements

• Select an attributes (XPath) – the @ symbol is used to select the value of an attribute

<?SCCquery_DS_ADMA_PROGRAMS/@numrows?>

• Reference the value of an element in a specific node (XPath) – square brackets hold predicates, which reference specific

nodes <?row_DS_ADMA_PROGRAMS[1]/PLAN_DESCR?>

Presenter

Presentation Notes

ExpressionDescription nodenameSelects all child nodes of the named node /Selects from the root node //Selects nodes in the document from the current node that match selection no matter where they are .Selects the current node ..Selects the parent of the current node @Selects attributes This example selects the PLAN_DESCR child element of the first row_DS_ADMA_PROGRAMS element.

Specifying Attributes and Elements

• Example of this used in an if statement – compare PROG_ACTION element of the first

row_DS_ADMA_PROGRAMS element with the second

<?if:row_DS_ADMA_PROGRAMS[1]/PROG_ACTION = row_DS_ADMA_PROGRAMS[2]/PROG_ACTION?>

Insert text and markup code here. <?end if?>

Presenter

Presentation Notes

To someone familiar with the Admissions module, this example is saying, if the program actions on the first and second program choices are equal then do something.

Sub-Templates • Useful for reducing the amount of repeated text/code

within a single template or across many templates

• Include a sub-template <?import:psxmlp://ADM_LETTERS_STMPLT?>

• Include a sub-template for testing <?import:file:///c:/temp/ADM_LETTERS_STMPLT.rtf?>

Presenter

Presentation Notes

Syntax: <?import:psxmlp://name_in_content_library?> <?import:file:///file_path_and_file_name?> The first example is to reference the sub-template in the Content Library in XMLP in PS. I typically do not put the import in a form field.

Sub-Templates • Start a template

<!–-This is used as the header for all emails-->

<?template:Email_Header?>

Insert text and markup code here. <?end template?>

• Call a portion of the sub-template <?call:Email_Header?><?end call?>

Presenter

Presentation Notes

Syntax: <?template:template_name?> <?end template?> <?call:template_name?><?end call?> You can also use comments in the sub-template. Comments are enclosed within . Comments cannot be placed in the main RFT among form fields in this format. The template declaration does not go inside a form field but the template can contain form fields. You can use a mix of markup code and form fields in sub-templates.

Sub-Template Parameters • Template that accepts a parameter

 <?template:Program_Status?><?param:rownum;0?> Insert text and markup code here. <?end template?>

• Pass a parameter <?call@inlines:Program_Status?><?with-param:rownum;1?><?end call?>

Presenter

Presentation Notes

Syntax: <?template:template_name?><?param:parameter_name;default_value?> <?end template?> <?call:template_name?><?with-param:parameter_name;parameter_value?><?end call?> The example of a template that returns program status for a particular row number is from an admissions letter at an institution that uses multiple program choices on a single application. In this case all the program choices are returned by the custom data source query and then here the status on one particular program choice is being displayed.

Extended SQL and XSL Functions • BI Publisher has an extended set of SQL and XSL

functions

• The syntax for extended SQL functions is

<?xdofx:expression?>

• The syntax for extended XSL functions is

<?xdoxslt:expression?>

Extended SQL and XSL Functions • Cannot mix xdofx and xdoxslt in the same context

• Listed in the Oracle BI Publisher – Report

Designer’s Guide starting on page 8-2

• Example, if-then-else statement (extended SQL)

<?xdofx:if PROG_STATUS = ‘WT’ then result1 else result2 end if?>

Presenter

Presentation Notes

Syntax: <?xdofx:if expression then result1 else result2 end if?> Remember how the regular if statement does not have an else. You would need to use multiple if statements of the choose statement.

Updateable Variables • Set an updateable variable (extended XSL)

<?xdoxslt:set_variable($_XDOCTX, ’AdmComm’, 'variable value goes here')?>

• Get an updateable variable (extended XSL)

<?xdoxslt:get_variable($_XDOCTX, ’AdmComm’)?>

Presenter

Presentation Notes

Syntax: <?xdoxslt:set_variable($_XDOCTX, ‘variable_name’, value)?> <?xdoxslt:get_variable($_XDOCTX, ‘variable_name’)?> Another example: <?xdoxslt:set_variable($_XDOCTX, 'x', xdoxslt:get_variable($_XDOCTX, 'x'+ 1)?> There are other variables (e.g., <?variable:name?>) that can be used but once their value is set once, that’s it, it cannot be changed. The $_XDOCTX specifies the global document context for the variables.

Best Practices

RTF Template Best Practices Use Form Fields • Keep the template clean • Supported by the Template Builder Field Browser • Can be colored or hidden to help understand the

structure • Caveat: MS Word header and footer do not allow form

fields

(Oracle Business Intelligence Publisher Best Practices)

Presenter

Presentation Notes

Re: can be in a different font color, e.g., <?template: Email_Header?> can be in green font through out your sub-template to make it easy to see where one template ends and another one begins.

RTF Template Best Practices Don’t overcomplicate your template • Keep it easy to understand, debug and maintain • In general better to have different business documents in

different templates • Try to limit the logic in templates to simple if or loop

statements • Use sub templates to simplify documents if necessary • Many calculations are better performed in the data

model


Presenter

Presentation Notes

Easy to say, “don’t over complicate” but much harder in practice. Re: different business documents in different templates – in other words, don’t try to do too much in a single template if you can break it out into multiple. Re: try to limit the logic – difficult or just plain messy result if you did this for some more complex requirements. Re: use sub templates – on one hand they can be used to reduce repetition of text/code, streamlining your template. On the other, it makes for more documents you need to retrieve and review when debugging.

Interesting Side Note Data Model Design Guidelines Element Naming

• Avoid re-using the same name for element names; it can cause confusion in template design – For example, CITY under SHIPPING_ADDRESS and BILLING_ADDRESS. But in many cases you are better off using different names, e.g., S_CITY and B_CITY


Presenter

Presentation Notes

I find it interesting that Oracle did not follow this guideline in designing the Campus Solutions communication data source. rs_PER_NAME_ADDR, rs_PER_NAME_EXTRA, and rs_PER_NAME_SAL reuse all the same element names. Solution: <?rs_PER_NAME_SAL/fld_FIRST_NAME?>

Reference Material • w3schools.com

– http://www.w3schools.com

• Oracle BI Publisher - Report Designer's Guide – http://docs.oracle.com/cd/E12844_01/doc/nav/portal_booklist.htm

• Oracle Business Intelligence Publisher Best Practices – http://www.oracle.com/technetwork/middleware/bi-publisher/bip-

best-practices-515163.pdf

http://www.w3schools.com

http://docs.oracle.com/cd/E12844_01/doc/nav/portal_booklist.htm

http://www.oracle.com/technetwork/middleware/bi-publisher/bip-best-practices-515163.pdf

http://www.oracle.com/technetwork/middleware/bi-publisher/bip-best-practices-515163.pdf

Summary • XSL is the style sheet language for XML

• BI Publisher uses a simplified version of XSL

• Basics: for-each, if, choose

• Advanced: attributes, sub-templates, updateable variables

• Use form fields where you can

• Don’t overcomplicate things, unless it’s necessary

Questions?

Contact • Michael Eastwood

Senior Specialist, Consulting Deloitte E-mail: [email protected]

This presentation and all Alliance 2012 presentations are available for download from the Conference site at

www. heug.org www.psugonline.org

www.federalusersnetwork.com Presentations from previous meetings are also available

practical setup and implementation of xml publisher...

Documents