Implementation Guide for Oracle Self-Service E-Billing > Using the Reporting Engine > Components Used by the Reporting Engine >

Report XML


The report XML describes how to generate a report. The report XML includes the dataSource section and the transformer section. The dataSource section describes how to retrieve data from data source, and the transformer manipulates the data before sending it to the template.

Samples of report XML files are located in the EDX_HOME/config/rpt directory. To get a complete list of all the valid report XML elements and attributes, see the report.xsd file, under the EDX_HOME/config/rpt directory. In the path, EDX_HOME is the directory where you installed Oracle Self-Service E-Billing.

The following topics describe some of the main features of the Reporting Engine and explain how to use report XML to implement them.

Element <reports>

This is the root element of report XML. This element can include <report>, <localizer>, <prompts> and <templates> elements. The following XML shows that structure:

<reports>
<templates>...</templates>
<localizer>...</localizer>
<prompts>...</prompts>
<report>...</report>

</reports>

Element <localizer>

This element defines how the localization of the reports will be done. For details, see Internationalization and Localization of Reporting for more information.

The <localizer> element has the attributes described in Table 13.

Table 13. Attributes for <localizer>
Name
Required
Description

enableMessageResources

No

This attribute allows you to use Struts MessageResource to look for the resource bundles for reports. This means you can use the same copy of resource bundle files defined in a struts config file without reloading another copy of it. The default is true.

defaultCode

No

This attribute enables you to define the default behavior if a resource is not found.

  • A value of 0 means to use the key as the default value.
  • A value of 1 means to use Struts notion of "Text<locale>.<key>Text"

A value of -1 means to throw an exception.

Localizer can include <resourceBundle> as its child elements.

Element <resourceBundle>

This element specifies one resource bundle property file name to be used for report localization. For more information about localization, see Localizing the User Interface.

For example:

<resourceBundle name="config/l10n/message" />

This example means the property file, config/l10/message_<locale>.properties, found in the EDX_HOME directory (the directory where you installed Oracle Self-Service E-Billing) is used for localization.

Element <prompts>

The <prompts> element has the same format as the one defined under <dataSource>. However, because it is defined at the global level, it can be shared and referenced by other reports. This significantly reduces duplication of the report XML contents, and makes it easier to maintain report XML files. For more details, see the <prompts> definitions in Element <dataSource>.

Element <templates>

This element allows you define a list of global templates that can be included and parsed into other templates. For example, the paging.vm is used to generate paging UI and could be included by other templates, like report_body.vm.

For example, to define a template:

<templates>
<template id="paging.vm" name="template/common/reporting/paging.vm"/>
</templates>

This example means there is a template named paging.vm, located in the EDX_HOME/template/common/reporting/ directory.

Then you can include the paging.vm from another template like this:

#parse ($transformerConfig.getTemplateName("paging.vm"))

The method transformerConfig.getTemplateName("paging.vm") returns this template, paging.vm, from the EDX_HOME/template/common/reporting/paging.vm directory.

NOTE:  If you have a template that has the same ID defined inside the transformer element, then the ID in transformer takes precedence over the what is in the global template list. This allows an individual transformer to use its own template.

Element <template>

This element defines a global template, which has following attributes described in Table 14.

Table 14. Attributes for the <template> Element
Name
Required
Description

ID

Yes

The ID is a unique identifier among all the global templates. Note you can use the same ID for the transformer template ID. In this case, the transformer template takes precedent of the global one.

name

Yes

The name attribute is the full class path name of the template.

Element <report>

This element defines a report. A report can include zero or more <dataSource> elements, one or more <transformer>s, and zero or one of <customList>, <printList> and <downloadList>.

<report id="reportId" name="MyReport">
<downloadList>...</downloadList>
<printList>...</printList>
<customList>...</customList>
<dataSource>...</dataSource>
<transformer>...</transformer>
</report>

The <report> element has two attributes:

  • id. The ID identifies this report. All the reports defined in the report XML files in reportList.properties must have unique IDs. This ID must start with an alphabetic character, and can include numbers and underscores.
  • Name. This is the name of the report. This name is used to search the report bundle to get a localized version of the report name. For example, in the Report List page, the names of reports are from this attribute.

Element <dataSource>

This element defines how to retrieve data from the data source.

<dataSource id="" uri="jdbcJNDI:edx.report.databasePool">

<query dynamic="true">

</query>

<columns>

<column id="" type=""/>

</columns>

<inputBindings>

<inputBinding />

</inputBindings>

</dataSource>

The data retrieved from the data source is represented as a List of Lists of simple Java objects, such as Strings, Date/Time/Timestamp or Numbers. The data does not use a two-dimensional array because a List of Lists gives you the potential to increase its size if required, and Velocity does not support accessing array elements through the [ ] operator.

The <dataSource> element has following attributes:

  • id: A unique ID identifies this data source in this report. You must define it even there is only one data source. It is not required that the ID be unique across all reports. This ID must start with an alphabetic character, and can include numbers and underscores.
  • uri: A Universal Resource Identifier identifies the location of the data source. Oracle Self-Service E-Billing supports three data sources: SQL data source, object data source, and DSV data source. This example focuses on the SQL data source. For information about object data sources, see Object Data Source and for DSV data source, see DSV Data Source.

    For an SQL data source, there are three URIs:

    • jdbcJDNI:<dataSource_JNDI_NAME>.The jdbcJNDI indicates that this is a JDBC data source identified by its JDNI name. For example, jdbcJDNI:edx.report.databasePool means there is a JDNI data source named edx.report.databasePool.
    • jdbcRef:<dataSource_REF_NAME>. The jdbcRef indicates that this is a JDBC data source identified by its local reference name, either defined in the web.xml or ejb-jar.xml file. For example, you can have an entry similar to this in the web.xml file:

    <resource-ref>
    <res-ref-name>jdbc/rptDataSource</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    </resource-ref>

    With this entry, you can use following URI: jdbcRef:jdbc/rptDataSource. You must also resolve this local reference through the weblogic.xml file or another vendor-specific XML file.

    • jdbcDirect:<jdbc_config_property_file_class_path>. The jdbcDirect means that there is no connection pool and the Reporting Engine must make a direct JDBC connection to the Oracle Self-Service E-Billing database. You must specify the class path to the DB config file. For example, jdbcDirect:config/db/jdbcConfig.properties. For the format of the config file, look at the sample jdbcConfig.properties file coming with the product. Avoid using this URI if your application can access a connection pool.
This element can include <query>, <inputBindings>, <prompts> and <columns> elements.

Element <query>

The <query> element defines the query used to retrieve data from the data source. The <query> element applies to an SQL data source but not to an object data source.

<query dynamic="false" maxRows="1000"> <![CDATA[select name, amount from summary where user_id=? ]]></query>

The value for <query> is enclosed in a CDATA topic, which can include any SQL.

The question mark in the SQL means that a variable must be resolved (bound) before the SQL can be executed. Variables are resolved through the <inputBindings> element.

Table 15 describes the attributes of the <query> element.

Table 15. Attributes for <query> Element
Name
Required
Description

dynamic

No

This attribute indicates whether to parse this SQL as a Velocity template before execution. This allows you to use a Velocity template to generate a SQL dynamically. For information about how to write dynamically generated SQL, see Dynamic SQL. The value can be True or False. The default value is False.

maxRows

No

This attribute indicates the Boolean number of rows will be retrieved from the data source. The value must be an integer. The default value is 1000.

Element <inputBindings>

This element defines a list of input bindings that are used to bind the SQL variables defined in the <query> element. It has no attribute, and includes an <inputBinding> element.

Element <inputBinding>

This element defines a single input binding. There are two kinds of bindings: objects and prompts. The order of the <inputBinding> elements is the same as the order of the SQL variables. That means the nth <inputBinding> is used to bind the nth SQL variable. Object binding means binding an object or its property to an SQL variable.

For example:

<inputBinding object="bean" property="userId" />

This means there is an object called bean in the report context, this object is a JavaBean, and it has a property named userId. The value returned by bean.getUserId() will be used to bind the SQL variable. Usually, the JavaBean is a Struts Action Bean object. If the object returned by the property is a Collection, then each element in the Collection will be used for binding.

<inputBinding object="myObject" />

In this case, there is no property defined, so myObject is not assumed to be a JavaBean. If the myObject is not a Collection, then myObject is used to bind to the SQL variable directly. If the myObject is a Collection, then each element in the myObject Collection will be used to bind to the SQL variables in its natural order in the collection. This latter case is very useful where the number of SQL variables is dynamic, such as a name in a (?...?) clause. For more information about using dynamic SQL, see Dynamic SQL.

Prompt binding is a special case of object binding. Prompt binding means that the binding object is from the user prompt, which allows you to bind the value of the prompt to a SQL variable.

<inputBinding object="form" property="<bean_property>" prompt="<prompt_id>" />

You can use a map-backed Action Bean also. For example, the ReportForm from the Oracle Self-Service E-Billing application is a map-backed form. It has map-methods, such as getParameter(String name) and setParameter(String name, Object value). You can use this syntax in a property or prompt attribute:

  • <inputBind object="form" property="parameter(callType)" />
  • <inputBind object="form" property="parameter(callType)" prompt="parameter(callType)"/>

Table 16 describes the attributes of the <inputBinding> element.

Table 16. Attributes for the inputBinding Element
Name
Required
Description

object

Yes

The name of the object in the report context used for binding. This object must be put into report context.

In the case of prompt binding, the Reporting Engine automatically retrieves the prompt value from the prompt form, and puts this object into the report context. The ReportActionHelper class puts the value of the prompt into the context with that name.

In the non-prompt case, the caller of Report engine must put this object into context.

property

No

This attribute is optional. When it appears, it means the object is a JavaBean and the value of the property of this JavaBean is used to bind SQL variable.

If this property is not there, then it means the object identified by object attribute is used for binding.

NOTE:  A map-backed property is supported, such as parameter(callType).

prompt

No

This attribute indicates that this input binding is from a prompt, and the value of it must be the ID of the prompt defined in the <prompts> element.

NOTE:  The object name for the prompt form is fixed to form and you must use object=form for prompt.

Element <prompts>

This element defines an HTML form whose input is used for data source input bindings. Each input field in the form is called a prompt. You configure where the prompt gets its original data (from the Oracle Self-Service E-Billing database or from a fixed value list), and how it will be presented by the report XML. The Reporting Engine builds the report prompt (input) UI, which is fully customizable (it uses a template to generate the UI).

To control the look and feel of prompts, reporting uses a technique similar to tiles. Layout format is controlled by layout.vm, and prompt rendering is controlled by prompt.vm.

The <prompts> element has a list of prompt blocks. Each block is separated by that dark blue bar at the top, and you can define a label for each blue bar. Inside each block, you can define a list of groups, where each group has a list of prompts. Each prompt group acts like <tr> in an HTML table, and all prompts within a prompt group display horizontally in a row. Each prompt must belong to a group. Prompts can be HTML input or a plain label. In the preceding example UI, Data range is a group with two prompts: the start date and end date. Usage type is another group that has two prompts: usage type and call type.

The <prompts> definition used to generate the example UI is:

<prompts id="prompts1" formName="reportForm" action="report.action"
method="post" templateID="layout.vm">
<block>
<group label="Date Range:" >
<text id="fromDate" size="12" value="1/1/2004"
imgSrc="_assets/images/calendar.gif" label="From:"
labelPosition="top"/>
<text id="toDate" size="12" value="12/1/2004"
imgSrc="_assets/images/calendar.gif" label=" To:"
labelPosition="top"/>
</group>
<group>
<select id="parameter(usageType)" report="prompt_usageType"
displayColumnId="usage_type_name"
valueColumnId="usage_type_key" value="2"
label="Usage Type:"/>
<select id="parameter(callType)" report="prompt_callType"
displayColumnId="call_type_name"
valueColumnId="call_type_key" value="2"
label="Call Type:"/>
<image name="display" src="_assets/images/display.gif" />
</group>
<group label=" Billing Reports">
<select report="prompt_reportList" value="first" name="reportId" onChange="cleanupHiddenValues()"/>
</group>

</block>
</prompts>

You can define <prompts> under <reports> and it will be global. To refer to a global <prompts> from inside <dataSource>, use the following:

<prompts id="billingPrompts"/>

This expression means that there is a global <prompts> whose ID is billingPrompts. If the same <prompts> is used across multiple data sources, then global <prompts> helps you to maintain only one copy of it.

The <prompts> element has the attributes described in Table 17.

Table 17. Attributes for the <prompts> Element
Name
Required?
Description

id

Yes

A unique ID is used to identify this prompts list in this data source. Oracle Self-Service E-Billing supports one prompts element for each data source.

label

No

The label displayed for the entire set of prompts.

formName

No

The name of the HTML form and default reportForm. This attribute is only useful if you want to use JavaScript to manipulate the form.

action

Yes

The action of the HTML form. Use report.action for the action because it is used as the default. If you change the action name defined in Struts config XML, then you must search all your JSP pages and Velocity templates to replace it.

method

No

The default is post.

templateID

Yes

The template ID specifies the layout template ID. The template must be either defined in corresponding transformer's <templates> or in the global <templates>.

enctype

No

The encryption type.

onReset

No

The name of JavaScript being called when Reset is called on the HTML form.

onSubmit

No

The name of JavaScript being called when Submit is called on the HTML form.

The <prompts> elements contain one or more <block> elements.

Element <block>

This is an optional element. If you do not define it, then you can define group directly under <prompts>, and all the groups will be put, implicitly, under a block. You can define a label for a block and the label will be displayed in the blue bar of the prompt.

Element <group>

This element defines a group of prompts. This group of prompts will be displayed horizontally in one line. Different groups of prompts will be displayed vertically.

The <group> element has the attributes described in Table 18.

Table 18. Attributes for the <group> Element
Name
Required?
Description

label

No

The label displays at the beginning of the each prompt group.

description

No

The description displays for the rollover question mark.

There are eight types of prompts, which correspond to input types in an HTML form (except Label).

Some supported HTML forms are: text, check box, select, radio, image, submit, reset and label. Image, submit, reset, label are purely for HTML form rendering and manipulation. Their values are not used for report SQL input bindings. Check box, select, radio and text can be used for SQL input bindings.

Attributes for prompt related configuration in XML file, most of attributes are from an HTML form, others are required by the Report Engine.

The <group> element can include one of the following attributes: <checkBox>, <select>, <radio>, <text>, <image>, <label>, <submit> and <reset>.

Element <select>

This element defines a select prompt. A select prompt allows you to select one or more values from a list of values. A select prompt must associate with a report whose result set is used to populate the select list. For example:

<select id="parameter(callType)"
report="prompt_callType"
displayColumnId="call_type_name"
valueColumnId="call_type_key"
value="2"
label="Call Type:"/>

A select list requires two types of information: display values and actual values. The display values are for displaying, and the actual values are for querying. For example, you can display May 2010, but use an internal value 5 for a query. For example:

<select>
<option value="5">May 2010</option>
</select>

To render the preceding UI, get the options values and display names from the associated reports. Table 19 describes the select options.

Table 19. Attributes for the <select> Element
Name
Required?
Description

id

Yes

Identifies this prompt in this prompts list. The ID is used as the name of the input prompt in the HTML forms, which means that it determines which Action Bean property is used to hold this input value. In the example, the billPeriod property of Action Bean holds the value of the select box.

If there is no corresponding property in the Action Bean (if it is a map-backed form), you can use the Parameter property (a map-backed property) to get the value into the ActionForm.

The following example creates a prompt for call type, which is not a property of ActionForm:

<inputBinding object="form" property="parameter(callType)" prompt="parameter(callType)"/>

The prompt is declared as:

<select id="parameter(callType)" label="Call Type:">.

NOTE:  When using parameter(calltype) as id (and therefore the HTML input file name), JavaScript might not recognize the name. In that case, you might want to extend your Action Beanimplementation to be a regular JavaBean property, which allows you to use <select id="callType" >.

label

No

The label of this prompt. Used for display.

labelPosition

No

Display the label position against the prompt. Top, bottom, left, and right are supported:

  • Top. The label is at the top of the prompt.
  • Bottom. The label is at the bottom of the prompt.
  • Left. The label is to the left of the prompt.
  • Right. The label is to the right of the prompt.

size

No

Size of the HTML input field.

report

Yes

The ID of the report, whose result set will be used to populate the Select element. The report can load data from the Oracle Self-Service E-Billing database or it can load from a DSV data source which is useful if the data in the list is fixed.

displayColumnId

No

The column ID of the report, whose values will be used as the display names of the <option> fields of <select> list. The first column of the report is used when displayColumnId is not specified.

valueColumnId

No

The column ID of the report, whose values will be used as the values of the <option> fields of <select> list. The second column of the report is used when valueColumnId is not specified.

value

No

The default value for the <select> list. It can be:

  • first, using the first value in the valueColumnId column of the report
  • last, using the first value in the valueColumnId column of the report

An integer N, such as 1 or 2, which indicates the nth value in valueColumnId column of the report. Note the index starts from 1.

multiple

No

Specifies that multiple items can be selected. The value can be True or False. The default value is False.

onBlur

No

Name of JavaScript being called for onBlur event.

onChange

No

Name of JavaScript being called for onChange event.

onClick

No

Name of JavaScript being called for onClickevent.

onFocus

No

Name of JavaScript being called for onFocus event.

The report used to generate <prompt> must meet the following requirements:

  • Have two columns: one column for display, and another for prompt value. The display column ID must match the displayColumnId attribute defined, and the value column ID must match the valueColumnId attributed defined. If the report only has only one column, then you can have both displayColumnId and valueColumnId point to the same column.
  • The report ID of the prompt report must match the report attribute defined.
  • You can format the prompt display names by using pattern attribute of column element of the report.

Element <checkBox>

The checkBox prompt allows you to print the prompt values in a list of check boxes. For example:

<checkBox id="billPeriod" label="Bill Period:"
report="prompt_billPeriod"
onClick="alter('onClick')"
displayColumnId="bill_period_name"
valueColumnId="bill_period_key"
value="last"/>

In the example, the bill period prompt is defined as a set of check boxes, where you can check one or more bill periods. The display names and values of bill period come from the prompt_billPeriod report. The <checkBox> element has the same attributes as <select>, except multiple does not apply. For information about using the <select> element, see Element <select>. You can think of the checkBox element as just another view presenting the same prompt, similar to a multiple-select list. The data retrieved from data source for the <checkbox> element must be either true or false.

Element <radio>

This prompt presents a list of radio buttons, only one of which can be selected.

<radio id="billPeriod" label="Bill period:"
report="prompt_billPeriod"
onClick="alert('onclick')"
value="last" />

In the example, the bill period prompt is defined as a set of radio buttons, where you can only check one of the bill periods. The display names and values for bill period come from the prompt_billPeriod report.

The <radio> has the same attributes as <select>, except multiple does not apply. See <select> for more information. In fact, you can just think radio as another view of presenting the same prompt. <radio> is like a single-select list.

The data retrieved from the data source used for <radio> must be either true or false, and only one can be true.

Element <text>

This element allows you to define a text box and use the user-entered value as the prompt value.

<prompt id="billPeriod" label="Bill period:">
<text
report="prompt_billPeriod"
maxLength="10"
onBlur="alert('onBlur')"
onChange=" alert('onChange')"
onFocus=" alert('onFocus')"
onSelect=" alert('onSelect')"
size="10"
value="06/2004"/>
</prompt>

In the text prompt, size attribute determines the width of the prompt.

Element <image>

This element allows you to define an image. For example this usage creates an image submit button:

<image name="display" src="_assets/images/display.gif" />

NOTE:  The <image> element is different from the <img> HTML tag.

Table 20. Attributes for the <image> Element
Name
Required?
Description

name

Yes

The display name of the image.

scr

Yes

The image src.

align

No

Left or right.

Table 20 describes the attributes for the <image> element.

Element <label>

This element defines text to display in the form. For example:

<label name="ccc_toll_lbl" value=" and " />

Table 21. Attributes for the <label> Element
Name
Required?
Description

name

No

Not used.

Value

Yes

The text to be displayed as it is on the screen

Table 21 describes the attributes for the <label> element.

Element <reset>

This element displays an HTML reset button. For example:

<reset name="reset" value="reset" />

Table 22. Attributes for the <reset> Element
Name
Required?
Description

name

Yes

Name of the reset button.

value

Yes

The display value of the reset button.

onClick

No

JavaScript to invoke.

Table 22 describes the attributes for the <reset> element.

Element <submit>

This element displays an HTML submit button. For example:

<submit name="submit" value="ok" />

Table 23. Attributes for the <submit> Element
Name
Required?
Description

name

Yes

Name of the submit button.

value

Yes

The display value of the submit button.

onClick

No

The JavaScript to invoke.

Table 23 describes the attributes for the <submit> element.

Element <columns>

This element, under <dataSource>, defines the list of columns retrieved from the data source. As described previously, the data retrieved from the data source is a two-dimensional matrix with rows and columns. For an SQL query, the rows are the rows from the SQL table, and the columns are the SQL table columns. Most of the transformer operations, such as sorting, grouping and calculation, are based on the types of the columns. Only the type of the column is important, not the definition of the column. For example, you can summarize if the type is Number. It does not matter if the definition is Air Fee or Toll Charge. That is the primary reason to use a List of Lists of objects to present all the data.

You must define all the columns retrieved from the data source in this element, in the same order as the data source. For example, if you are using a SQL data source, the order of selected columns from Select must be the same as the order defined in the XML element. The same is true for object data sources.

Element <column>

This element describes the column retrieved from the data source. You must define the type of the column in this element. The order of <column> elements must be the same as the order of columns retrieved from the data source and for each column in the data source, you must have one of this XML element defined for it.

The element <column> includes the attributes described in Table 24.

Table 24. Attributes for the <column> Element
Name
Required?
Description

ID

Yes

Uniquely identifies this column in the data source.

type

Yes

Type of column. The legal types are all simple Java object types. A column can be sorted if its type is java.lang.Comparable. or it can take a calculator operation (aggregation), if its type is java.lang.Number.

default

No

This attribute indicates the default value for this column if the value returned from data source is null.

Column types can be one of the following:

  • Java.lang.Object. A generic type. Avoid using this if you want to sort or format on the column. Use a more specific type instead.
  • Java.lang.Double. A double value, which can be sorted and aggregated.
  • Java.lang.Float. A float value, which can be sorted and aggregated.
  • Java.lang.Integer. An integer, which can be sorted and aggregated.
  • Java.lang.Long. A Long value, which can be sorted and aggregated.
  • Java.lang.Short. A Short value, which can be sorted and aggregated.
  • Java.lang.BigDecimal. A BigDecimal, which can be sorted and aggregated.
  • Java.long.String. A String value, which can be sorted.
  • Java.sql.Date. A Date value (a Date has no time information). It can be sorted.
  • Java.sql.Time. A Time value (a Time has no date information). It can be sorted.
  • Java.sql.Timestamp. A Timestamp value, which includes both date and time information. It can be sorted.
  • Java.lang.Boolean. A Boolean value, which can be sorted.
  • Java.lang.Byte. A Byte value, which can be sorted.

Attributes can be one of the following:

  • Number. The default value is parsed as a Number string using the parseXXX method on the corresponding Java class. For example, use Double.parseDouble() if it is a double. It can only include digits and decimal point.
  • Timestamp. You must supply the default value formatted as yyyy-mm-dd hh:mm:ss.
  • Date. You must supply the default value formatted as yyyy-mm-dd.
  • Time. You must supply the default value formatted as hh:mm:ss.
  • String. The default value is used as it is.
  • Boolean. The default value can be true or false.

Element <transformer>

This element defines a transformer for this report. A report can include zero or more transformers. Transformer is key element of the report engine. It is responsible for transforming the data retrieved from data source into a format suitable for presentation.

The <transformer> element has the attributes described in Table 25.

Table 25. Attributes for the <transformer> Element
Name
Required?
Description

Id

Yes

Uniquely identifies this transformer in this report. Note, you are allowed to have two transformers with same ID if they are from different reports.

datasourceId

No

The ID of the data source where the transformer gets data. Note, a transformer is not required to have a data source. If a transformer does have a data source, then the Reporting Engine is usually used as a pure Template engine, and no meaningful data transformation is done inside transformer. That means that all the reporting functionality, such as sorting and paging, will not apply. For example, in the Telco.xml file, the transformer with report_header.vm defined has no data source.

pageSize

No

This attribute enables paging and defines the number of rows that will be displayed in one page. All the data will be presented in one page if this attribute is not specified.

viewType

No

This attribute sets the view type. The value can be portrait, landscape, or tree. The default value is portrait.

displayReport

No

This attribute determines whether the report portion of the UI is displayed. The values can be true or false. The default value is true.

displayPrompts

No

This attribute determines whether the prompts portion of the UI is displayed. The values can be true or false. The default value is true.

showTitle

No

This attribute determines whether the title portion of the UI is displayed. The values can be true or false. The default value is true.

showItems

No

This attribute determines whether the (Number of Items) portion of the UI is displayed. The values can be true or false. The default value is true.

showHeader

No

This attribute determines whether the header portion of the UI is displayed. The values can be true or false. The default value is true.

hiddenResultCount

No

This attribute determines whether the report table and chart are displayed. If the report result size is less than or equal to the value of the hiddenResultCount attribute, then the table and chart are hidden. The default value is -1.

divClass

No

This attribute sets the CSS class for <div class="contentbox">. The default value is empty, which uses contentbox.

tableClass

No

This attribute sets the CSS class for <table="rpt">.

Background

No

This attribute sets the background colors. By default, the background shows different colors for even and odd rows. You can set this to blank.

chartPosition

No

This attribute sets the chart position relative to the report table. The value can be one of the following: top, bottom, left, right, topInside, bottomInside, leftInside, rightInside. The default value is top.

collectionId

No

For Web Services, the name of a list, or group, of objects in a report.

Element <columns>

This element defines a list of columns for the transformer. You are not required to define a column in the transformer for each column in the data source. It is not necessary that the order of columns in the transformer match the order of the columns in the data source. However, following those two rules will make your code easier to maintain.

This XML element has no attribute and contains <column> elements.

Element <column>

This XML element defines a column for the transformer. The transformer will render the columns in a table format. This is one of the most important XML element.

<column
id="myColumnId"
name="Column Name"
Hidden="false"
sortable="true"
defaultSort="true"
caseInsensitiveSort="true"
pattern="MM/dd/yyyy"
link="report.action?reportId=myReport&#x26;parameter(myColumnId)=$col"
localize="true"
/>

Table 26 lists all the attributes for the <column> XML element.

Table 26. Attributes for the <column> Element
Name
Required?
Description

id

Yes

This ID must match one of the IDs defined in the data source.

name

Yes

The name of the column. The name is localized and presented as the table column name.

hidden

No

A template string. The parsing result is either true or false.

sortable

No

This attribute defines whether this column is sortable. If true, then the template generates a URL link for this column. The value can be True or false. The default is False.

defaultSort

No

This attribute defines whether to sort this column when the report generates. The value can be True or false. The default is false.

caseInsensitiveSort

No

This attributes defines whether you want a case-insensitive sort when the column type is java.lang.String. The value can be True or false. The default is false.

onlineOnly

No

This attribute defines whether this column shows on the Web page only, and not in the CSV download file. The value can be True or false. The default is false.

downloadOnly

No

This attribute defines whether this column shows only in CSV download file only, and not on the Web page. The value can be True or false. The default is false.

Element <link>

This element allows you to define a drilldown link, which can also be defined as an attribute of the <column> element. The benefit of using it as an attribute is that you can wrap the content in CDATA without escaping the special characters.

Element <templates>

This element includes a list of template elements. It has no attributes, and includes only one element, template.

Element <template>

This element defines one template used by the transformer. A transformer can define one or more templates and each template represents a presentation view. For example, you can define one template for HTML, one for XML and another for CSV. You specify which view or template to use to render the UI by passing the template ID through Ireport.writeTemplate().

<templates>
<template
id="HTML_TEMPLATE"
name="template/common/reporting/report_body.vm"/>
</templates>

Table 27 describes the attributes for the <template> element.

Table 27. Attributes for the <template> Element
Attribute
Required
Description

id

Yes

The ID identifies this template inside this transformer. An ID must be unique to this transformer.

name

Yes

The class path of the template name. Because the class loader loads the template by default, this template must exist on the classpath (such as on the WEB-INF/classes directory or packaged into a JAR file). For example, if your template is located under the template/templ/my.vm directory and that is on the class path, then you must use the template/temp/my.vm directory as the name.

localize

No

True or false. True means this template is localized. There is one template for each locale, and the report engine finds the correct template based on the locale. For example, the email template has a lot of static text, therefore define one template for each locale and specify this attribute as true to associate the correct template for each locale.

For information about creating PDF templates, see Creating a PDF Template for Reporting.

Element <groups>

This element allows you to group the data retrieved from a data source into groups, where each group is presented inside a table. For example, you might want to group on all types, so that all the local calls are presented in one table, and international calls are presented in another table. Only single column grouping is supported.

You can define multiple groups. You can define one of them as default grouping, so when the data is retrieved from the data source, it will be grouped by that default grouping. Call Itransformer.group() in your calling program to switch to another group.

This element has no attributes, and can include the <group> element.

Element <group>

This XML element defines a single group. The <column> element defines the columns you want to group on. You can only define one column. For example:

<group id="group_by_type" default="true">
<column id="type"/>
</group>

Table 28 describes the <group> element attributes.

Table 28. Attributes for the <group> Element
Name
Required
Description

id

Yes

Defines a unique ID that identifies this group in this transformer. The group ID must only be unique among the groups defined in this transformer.

default

Optional

This flag indicates that this group is the default one, so when data is retrieved from data source, the data will be grouped (only one group can be default). The data will not be grouped if there is no default group defined. The default is False.

Element <column>

This <column> element is defined as part of the <group> element, and identifies the column where grouping will happen. It has the attributes described in Table 29.

Table 29. Attributes for the <column> Element
Name
Required
Description

id

Yes

This is the column ID defined in data source. This ID must match the ID of the column of the data source where you want the grouping to happen.

Element <calculator>

This element defines a calculator for the report. The calculator can perform a set of operations, for example: summarize (subtotal), average, Boolean and minimal. The operations are grouped together into an operation group. calculator contains one or more <operationGroup> elements. For example:

<calculator>
<operationGroup name="Total">
<operation type="sum" columnId="Charges" />
<operation type="sum" columnId="taxes" />
</operationGroup>
<operationGroup name="Average">
<operation type="ave" columnId="Charges" />
<operation type="ave" columnId="taxes" />
</operationGroup>

</calculator>

For example, the Reporting Engine generates a table similar to the example in Table 30.

Table 30. Example of Table Generated by the Reporting Engine
Invoice Number
Charges
Taxes

12345

10.01

0.23

23456

12.11

1.03

Total

22.12

1.26

Average

11.06

0.63

Element <operationGroup>

This element defines a group of operations. Different operations in the group must operate on different columns, but it is not required that groups have the same operation types. That is, you can mix sum with avg in the same operation group.

In general, do not define an operation on the first visible column of the table. That column will be used to display the name of the operationGroup. However, if it is necessary to define an operation on the first visible column, then you can change the report_body.vm by replacing the operationGroup name with the operation value you define.

The <operationGroup> element has one attribute, name, which is described in Table 31.

Table 31. Attributes for the <operationGroup> Element
Name
Required
Description

name

Yes

The name of this group of operations. The default template, report_body.vm, presents the group in the first column of the operation row of the table.

This element can contain one or more <operation> elements.

Element <operation>

The <operation> element defines a single calculator operation on a single column. It has the attributes described in Table 32.

Table 32. Attributes for the <operation> Element
Name
Required
Comments

type

Yes

The type of operation:

  • summary. Finds the summary of all the values of the column identified by columnId attribute.
  • avg. Finds the average of all the values of the column identified by columnId attribute.
  • max. Finds the Boolean value of all the values of the column identified by the columnId attribute.
  • min. Finds the minimal value of all the values of the column identified by the columnId attribute.

count. Finds the total number of rows. In this case, columnId is optional.

columned

Yes

The ID of the column that the operation will apply to.

Element <charts>

This element allows you to define one or more charts for a single transformer. For example:

<charts>
<chart id="c1"
type="BAR_VERT_CLUST"
style="config/chart/vertical_bar_chart.properties"
chartTitle="global.title.accountBillingOverview"
xAxisTitle="global.label.accounts"
yAxisTitle="global.label.dollars">
<datasets>
<dataset><column id="Total"/></dataset>
</datasets>
<xlabel><column id="Billing_Account"/></xlabel>
</chart>
<chart id="c2"
type="PIE"
style="config/chart/pie_chart.properties"
chartTitle="global.title.plan">
<datasets>
<dataset><column id="total"/></dataset>
</datasets>
<xlabel><column id="rate_plan"/></xlabel>
<compress threshold="2" label="global.label.other" append="true"/>
</chart>
</charts>

Element <chart>

This element defines a single chart for this transformer. Oracle Self-Service E-Billing supports two chart types: Bar chart and Pie chart. The data of the chart must come from the columns of the data source.

The <chart> element includes the attributes described in Table 33.

Table 33. Attributes for the <charts> Element
Name
Required
Description

id

Yes

Uniquely identifies this chart among all the charts defined in this transformer. Note, you can use the same chart IDs in different transformers.

type

Yes

The type of the chart. Oracle Self-Service E-Billing supports the following types of chart:

  • BAR_VERT_CLUST. Vertical bar chart.
  • BAR_HORIZ_CLUST. Horizontal bar chart.
  • BAR_VERT_STACK. Vertical stack bar chart.
  • BAR_HORIZ_STACK. Horizontal stack bar chart.
  • PIE. Pie chart.
  • LINE. Line chart.

style

Yes

Path to the name of the DVT chart properties file. For information on configuring the properties file for DVT charting, see Customizing Charts.

chartTitle

No

Defines the title of the chart.

xAxisTitle

No

The title of the X-axis.

yAxisTitle

No

The title of the Y-axis.

The <chart> elements also include following two elements: <datasets> and <xlabel>.

Element <datasets>

This element allows you to define multiple data sets used to draw the chart. Only one dataset for each chart is supported.

Element <dataset>

This element defines a data set used for charting. A data set must come from the column of the data source. Currently, you can only define one column for on dataset. It has no attributes and contains one element: <column>.

Element <column>

This element defines the column whose values will be used as the data set for DVT charting. For example, for the BAR_VERT_CLUST chart, the dataset is used for the Y-axis values. For PIE, the dataset is used for the pie chart data.

The <column> element of Report XML includes one attribute, which is described in Table 34.

Table 34. Attributes for the <column> Element
Name
Required
Description

id

Yes

The ID of the column where the chart will get its data. The type of the column must be a number.

Element <xlabel>

This element defines the values for the x-axis. The x-label must come from the data source column. It has no attributes, and contains one element: <column>. You can only define one column for each x-label.

Element <column>

This element defines the column used for the x-label. The values of the column are used for the x-axis values. This element only includes one attribute, which is described in Table 35.

Table 35. Attributes for the <column> Element
Name
Required
Description

id

Yes

The ID of the column where the chart will get its x-axis values.

Element <downloadList>

This element defines a list of downloads available for this report. For example, you can define XML, CVS, and PDF downloads. For each download, the template generates a download link. You can define multiple downloads for one report. For example:

<downloadList name="Download">
<download
name="Download CSV"
type="csv"
description="CSV download"
templateId="CSV_TEMPLATE" />
</downloadList>

The <downloadList> element has one attribute, which is described in Table 36.

Table 36. Attributes for the <downloadList> Element
Name
Required
Description

name

No

The name of this downloadList. Depending on your template, you can use this name for different purposes. For example, you can build a list of downloads and use this name as the name of the list.

Element <download>

The <download> element defines one download for the report. It has the attributes described in Table 37.

Table 37. Attributes for the <download> Element
Name
Required
Description

type

Yes

The type of the download. You can name any type you want. The type is used as the download file extension. For example, use csv for CSV download and use xml for XML download.

name

No

The name of the download, which depends on the template. It can be shown as a URL link or as a list item.

description

No

Description of the download. Currently, the description is not used by template, but you can modify the template to use it in a pop-up help window.

templateId

Yes

The template ID used to generate the download of the report. It is possible that the same template ID list appears in multiple transformers. If so, then the templates will be parsed and appended together in the order of the templates defined in XML.

Element <printList>

This element defines a list of print-friendly available for this report. Though it is possible, it is unlikely you will define more than one print-friendly. For each print friendly, a print friendly link will be generated through the template.

For example:

<printList name="Print friendly">
<print
name="Print friendly"
description="print friendly account details"
templateId="PRINT_TEMPLATE" />
</printList>

The <printlist> element has one attribute, which is described in Table 38.

Table 38. Attributes for the <printList> Element
Name
Required
Description

name

No

The name of this printList. It is not used by current template

Element <print>

The <print> element defines one print-friendly for the report. It has the attributes described in Table 39.

Table 39. Attributes for the <print> Element
Name
Required
Description

name

No

The name of the print-friendly. The default template renders it as a URL link.

description

No

Description of the print-friendly. Currently it is not used by template, but you can modify the template to use it for a pop-up help window.

templateId

Yes

The template ID used to generate the print-friendly report. It is possible that the same template ID can appear in multiple transformers, so all these templates will be parsed and appended together, in the order of the templates defined in XML.

Element <customList>

This element defines a list of custom reports available for this report. Though possible, it is unlikely that you must define more than one custom report. For each custom report, a custom report link will be generated through the template.

For example:

<customList name="Customize">
<custom
name="Customize"
description="Create a custom report for contract call details"
reportId="telco_cust_std_r4" />
</customList>

The <customList> element has one attribute, which is described in Table 40.

Table 40. Attributes for the <customList>
Name
Required
Description

name

N

The name of this customList. It is not used by current template.

Element <custom>

The <custom> element defines one custom report for the current report. Each custom report must be itself defined as a report. This tag is used to build a link to that custom report. It has the attributes described in Table 41.

Table 41. Attributes for the <custom> Element
Name
Required
Description

name

No

The name of the custom report. The default template renders it as a URL link.

description

No

Description of the custom report. Currently it is not used by template but you can modify template to use it for a pop-up help window.

reportId

Yes

The report ID of the report used to define the custom report: the custom report itself is a report and you must define it as a report.

Using Report Templates

All the report UIs are generated through Velocity templates. For information about how the Velocity templates work, see

http://velocity.apache.org/

Oracle Self-Service E-Billing has changed some of the default Velocity templates. The most important one is that inside for each loop, the $velocityCount variable starts from 0 instead of the default 1.

Oracle Self-Service E-Billing offers a set of example templates that generate useful UIs. These templates are very generic, are not tied to a particular application, and can be used as the base for your customization work.

The templates are all defined in the EDX_HOME/template/common directory. In the directory, EDX_HOME is the directory where you installed Oracle Self-Service E-Billing.

The lib subdirectory includes some Velocity MACRO library files and the reporting subdirectory includes report template files.

Table 42 explains the libraries that are included with the report package.

Table 42. Libraries Included with the Reporting Package
Name
Description

Lib/report_library.vm

This file defines some common MACROs used by the Reporting Engine. You must use it as it is.

Table 43 explains the templates that are included with the report package.

Table 43. Templates Included with the Reporting Package
Name
Description

Common/report_header.vm

This is the header part of the report. Note, this is not the header of the tiles. The tile header is usually the Navigation Tabs. The report header usually includes the report name and the download, print friendly, and custom report links.

Common/report_body.vm

This template renders the table associated with the transformer. Because a report can define multiple transformers, the template can be parsed multiple times for a report.

Common/paging.vm

This template renders the paging navigation part, which has previous, forward buttons for a user to page through the report.

Common/layout.vm

This template is used to define the layout of the prompts of the report.

Common/promt.vm

This template renders each individual prompt of the report.

Common/promt.vm

This template renders each individual prompt of the report.

Common/csv.vm

This template renders the CSV format of a report. The current CSV format does not consider the case of how to escape the special characters like a comma. You must write code to handle that case.

Common/print.vm

This template renders the print friendly format of a report.

Common/custom_report.vm

The template is used for custom reporting. It displays the custom report detail and allows you to type a name for the report to save into the Oracle Self-Service E-Billing database.

common/batch_report.vm

The template is used for batch reporting. It displays the batch report detail and lets you type a name for the report to save into the Oracle Self-Service E-Billing database.

common/xml.vm

This template renders the XML format of a report.

common/rsxml.vm

This template renders the XML format for the REST Web service call for a report.

pdf/PrintSummary.rtf

This template renders PDF format for the Print Summary quick link on Consumer Edition pages.

pdf/StatementSummary.rtf

This template renders PDF format for the Statement Summary report.

pdf/telco_std_r1.rtf

This template renders PDF format of the Account Billing Overview report.

pdf/telco_std_r6.rtf

This template renders the PDF format of Total Cost by Plan report.

pdf/telco_std_r13.rtf

This template renders the PDF format of Service Details report.

Implementation Guide for Oracle Self-Service E-Billing Copyright © 2014, Oracle and/or its affiliates. All rights reserved. Legal Notices.