Using Stationery Editor

Template Preparation and Sample Data

After selecting to customize a template such as a confirmation letter, or folio, two files (*.rtf and *.xml) are downloaded to the client workstation and Microsoft Word automatically opens the [filename].rtf. Use the Oracle BI Publisher toolbar to load the corresponding XML data (select Data, select Load XML Data, and then select the applicable XML file).

Note:

The Oracle BI Publisher toolbar appears in Microsoft Word after installation of the Oracle BI Publisher software. If the toolbar does not appear automatically, select View, select Toolbars, and then select Template Builder to add it to the existing toolbar display. Alternatively, you can use the Oracle BI Publisher function menu, which always appears with the other function menus at the top of Microsoft Word once the Oracle BI Publisher software has been installed.

The Load XML Data menu option is used to load sample data for the template. Sample data consists of every XML tag (field) available for inclusion in the template. This default data is used when previewing the customized report to view how the report looks once it is generated within OPERA Cloud.

Figure 8-1 Load XML Data

Select the XML file from the download directory on the workstation that corresponds to the type of template you want to customize. The XML file should be the sample_xxx that corresponds to the template you are customizing. For example, if you are creating a confirmation letter for your resort and you named the file “email_confirmation,” you will not see a corresponding XML file. Rather, you would select the file “sample_guest_confirmation.xml” to load the available elements for customization on the template.

Figure 8-2 sample_guest_confirmation.xml file

Once the XML is selected, a “Data loaded successfully” message appears and informs you that the sample XML data is now loaded for use in customization.

Microsoft Word functionality is used to add style elements to the report (for example, font styles and sizes, font color and weight, and so on). To add text, simply type the text where you would like it to appear.

Note:

Only standard operating-system packaged fonts are supported.

Note:

Although this tool utilizes Microsoft Word for customization, not all elements can be used on the template. An RTF template is a document which describes how data is presented. It does not contain knowledge of how to extract data, only tags containing field names. Macros cannot be used because the report is stored in *.RTF format.

Adding and Editing Form Fields

Form fields can be added or edited directly from the report template in the following ways:

• clicking an existing field or selecting Tools and then selecting Field Browser to edit existing fields or

• clicking Insert and then selecting Field to add a new field to the template document.

When editing existing fields using the Field Browser, select a field from the list to view or modify the corresponding XML tag. Once your fields are modified, click the Update button to apply your changes and then click Close to exit the Field Browser.

Figure 8-3 Selecting a Field from the List of Field Values

It is recommended that tables are used to keep the field positions static. When creating a new table in Word, be sure to set the AutoFit behavior to ‘AutoFit to Contents’ to avoid truncating fields larger than the actual cell size or resizing a cell to accommodate a field with a longer description than the display data. Refer to Microsoft Word Help (F1) for more details.

After the XML data has been loaded into the Template document, use the Insert and Field menu items to insert new fields in the document and edit accordingly.

Select the XML tag or field to add to the customizable report from the list of available fields. The Tree of available fields is divided into the sections applicable to the report, (for example, header, footer, body, and so on). You can add fields by highlighting and dragging to the document or double clicking on a selected field from this list.

Advanced Layout Options

Adding and Editing IF Statements for Conditional Regions of the Template

Notice that IF statements appear throughout the document template. IF and ENDIF represent the IF and END IF statements provided with the sample reports. All content contained within the IF to ENDIF statements only appears based on the conditions of the IF statement being met. For instance, if a guest has a reservation where a deposit is not required for their stay, the IF statement suppresses the field DEPOSIT_DUE from displaying on the confirmation.

To add new IF statements to the report template, select Insert and then select Field to add a new field to the template document. Next, double click the newly created field to display the Text Form Field Options screen and then click the Add Help Text button to create your IF statement.

Figure 8-4 Adding IF Statements

Viewing and/or editing the condition of an existing IF statement can be done one of two ways. First, double-click on the field for the IF statement you want to modify. The Text Form Field Options screen appears. Click the Add Help Text button. The Form Field Help Text screen appears. From here you can manually edit the IF statements to meet your requirements.

The conditional regions rely on expressions <?if:?> and <?end if?>.

<?if: [ELEMENT][CONDITION]?>

Where element is the field name and condition is what must evaluate to true. Ensure the [ELEMENT] from the XML is referenced in uppercase.

IF can be combined with other string functions.

CONTAINS

Using the CONTAINS function, an expression can be constructed to output conditional text when an element contains a specific string value. This is similar to a LIKE operator.

<?if: contains(ELEMENT,’txt_to_search_for’)=’true’?>Yes it does <?end if?> 

For example:

<?if:(VIP='V1')

STARTS-WITH

To evaluate the start of a string, use the STARTS-WITH function:

<?if: starts-with(COMPANY_NAME,'Oracle')?><?end if?>

Or, you can use the Field Browser (select Tools and then select Field Browser) to view and/or edit the condition of an IF/ENDIF statement and then click the Update button to apply your modifications.

Figure 8-5 Field Browser screen

Adding Conditions for Internal Parameters

Each customizable report contains internal parameters that are used for report generation. These parameters can be utilized when creating conditions for report generation. For example, if a property wants to display a graphic on a confirmation letter only when generating output in a PDF format, these internal parameters would be used. The XML Tags of Param Name and Param Value are displayed in the available fields list.

Figure 8-6 Internal Parameters List

To see the list of available internal parameter values, open the [filename].xml that is downloaded to the workstation along with the customizable [filename].rtf file (where [filename] is the name of the file you have customized).

In this example, a condition is created for text to only appear if the report output is PDF format. To accomplish this, add the field Param_Name and then double click to edit. In the Form Field Help Text screen, insert the following line:

<?if:PARAM_VALUE[../PARAM_NAME='DESFORMAT']='PDF'?>

Figure 8-7 Form Field Help Text screen

Insert an ENDIF statement to close the condition, then click OK and OK again to return to the customized report.

Inserting Images

There are two methods for inserting images into templates. For HTML email delivery (for example, confirmation letters), images must be published to a web server and the URL reference method must be used to reference the URL to the image. Referencing the image using the URL method provides a faster load/processing time for the template file since the file is smaller when the image is referenced rather than imbedded in the file.

Note:

There is a file size limit of 2MB for RTF templates.

Directly Inserting Images

For PDF output, images can be inserted directly into the RTF template.

Insert the jpg, gif, or png image directly in the template by selecting Insert and then selecting Pictures.

Inserting Images with URL References

Reference to a web image means the image is fetched at runtime; the image can be updated at any time without the need to modify the template(s).

Include an alternative text link for an image.

To insert images with URL references:

1. Insert a dummy graphic into the layout in Word by selecting Insert and then selecting Pictures.

2. Right-click the image and select the Format Picture option and then click the Alt Text tab.

3. Enter the following syntax to reference the image location:

   URL:{'http://<image location>'}
   

   Some examples for web images:

   URL:{'http://www.example.com/images/ora_log.gif'}
   

   URL:{'http://www.hotelserver.com/images/logo.gif'} 
   

At runtime, the dummy graphic is replaced with the image published at the specified web address.

Figure 8-8 Format Picture and Alt Text tab

Graphic Image Size

The external images used within the document should be sized to suit the layout of the document and then published to the web server. The dummy graphic (used as a place holder within the RTF) can also be set to the required image size using picture tools.

Formatting Date and Number Fields

In addition to preformatted date strings in the XML, all date fields are also provided as canonical date/time values. These fields are identified with the suffix _ISO in the element name. Canonical dates can be formatted in BI Publisher using one of the following methods for specifying the desired output format:

• Specify an explicit date format mask using Microsoft Word’s native date format mask.

• Specify an explicit date format mask using Oracle’s format-date function.

Note:

Only one method should be used. If both the Oracle and MS Word format masks are referenced for a field, the data is formatted twice causing unexpected behavior.

To apply the Oracle BI Publisher format mask to a date field:

1. Open the Form Field Options dialog box for the placeholder field.

2. Set the Type to Regular Text.

3. Click the Add Help Text button to open the Form Field Help Text dialog.

4. Insert the following syntax to specify the date format mask:

   <?format-date: [DATE FIELD]; ’[MASK]’?>
   

For example:

<?format-date:ARRIVAL_DATE_ISO;’YYYY-MM-DD’?>

Figure 8-9 Date Format Mask

BI Publisher has a number of predefined format masks that can be used with the <?format-date> function for _ISO date fields:

Table 8-1 Predefined Format Masks

Mask	Output for US Locale
SHORT	12/31/1999
MEDIUM	Dec 31, 1999
LONG	Friday, December 31, 1999
SHORT_TIME	12/31/99 6:15 PM
MEDIUM_TIME	Dec 31, 1999 6:15 PM
LONG_TIME	Friday, December 31, 1999 6:15 PM
SHORT_TIME_TZ	12/31/99 6:15 PM GMT
MEDIUM_TIME_TZ	Dec 31, 1999 6:15 PM GMT
LONG_TIME_TZ	Friday, December 31, 1999 6:15 PM GMT

Country locales can also be used to format a date value using a national character set. For localized stationery, any ISO date field set to output a ‘LONG’ mask outputs a translated string.

Alternatively, the Microsoft Word format mask can also be used on ISO date elements. Open the field properties and set the field type as date and select the date format mask required for the field.

Figure 8-10 Text Form Field Options with field type as a Date

Number formatting is achieved using similar method to date formatting. BI Publisher supports two methods for specifying the number format:

• Specify an explicit format mask using Microsoft Word’s native number format mask.

• Specify an explicit format mask using Oracle’s format-number function.

To use Microsoft Word format mask, open the field properties and set the field type as number and select the number format mask required for the field.

Figure 8-11 Text Form Field Options with field type as a number

To use the Oracle BI Publisher format mask, specify an explicit format mask using Oracle’s format-number function.

1. Open the Form Field Options dialog box for the placeholder field.

2. Set the Type to Regular Text.

3. Select the Add Help Text button to open the Form Field Help Text dialog.

4. Insert the following syntax to specify the number format mask:

   <?format-number:fieldname;'999G999D99'?>
   

   Figure 8-12 Form Field Help Text

   
   
   

Note:

For further information on formatting dates and numbers, refer to https://docs.oracle.com/middleware/12211/bip/BIPRD/GUID-7BD3C665-851A-43FE-BA2D-7501390D95AC.htm

Adding Hyperlinks for PDF and HTML Output

The RTF template can contain links to web locations. When generated to PDF or HTML format, you can click the hyperlink to open the website. (This feature is typically used in HTML confirmation letters.)

1. Within the template, select an area of text and select insert and then select hyperlink.

   Figure 8-13 Inserting a link in the template

   
   
   
2. In the dialog box, enter the URL and click OK.

   Figure 8-14 Entering the URL for the link

   
   
   
3. Links can also be defined on images in the template for PDF and HTML output. Select an image and select Insert and then select hyperlink. In the resulting email or PDF file, the image is a button the recipient can click to launch the URL.

   Figure 8-15 Defining a link for an image

   
   
   

Non-Western Fonts

Only OS-packaged, standard fonts are supported. To support internationalization and non-Western character sets, a unicode font must be used in the RTF template. Arial Unicode and Lucida Sans Unicode are two standard Unicode fonts installed with Microsoft Windows and Microsoft Office.

Format any string or date field that outputs non-Western characters with Arial or Lucida Sans Unicode to ensure correct output.

Figure 8-16 Selecting a Unicode font

Extended SQL and XSL Functions

BI Publisher has extended a set of SQL and XSL functions for use in RTF templates. The syntax for these extended functions are the following:

<?xdofx:expression?> for extended SQL functions 

<?xdoxslt:expression?> for extended XSL functions

An SQL example is IF-THEN-ELSE used for a conditional region.

<?xdofx:if [ELEMENT][condition] then result1 else result2 end if?>

For further information, refer to https://docs.oracle.com/middleware/12212/bip/BIPRD/GUID-B39D756A-C54D-4C64-A822-DD2CFFC3A54E.htm#BIPRD3160.

Preview and Finalize the Template

Once the customization is complete, you can preview your customized template from within Microsoft Word to verify the layout and information is correct. The Preview feature is available in several formats: PDF, HTML, Excel, or RTF. Refer to step 11 in the Creating and Running Custom Reports topic for more information on uploading the modified RTF template.

Figure 8-17 Preview Options for Custom Report