Implementation Guide for Oracle Self-Service E-Billing > Using the Reporting Engine > Components Used by the Reporting Engine >
Reporting XML
The Reporting XML is central to the Reporting Engine. It describes how to generate a report. The Reporting XML includes the dataSource and the transformer sections. The dataSource describes how to retrieve data from data source, and the transformer manipulates the data before sending it to the template. There are samples of report XML files 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, report.xsd, under the EDX_HOME /config/rpt directory. In the path, EDX_HOME is the directory where you installed Oracle Self-Service E-Billling. The following topics describe some of the main features of the Reporting Engine and explain how to use report XML to implement them. <reports> Element of Report XML
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>
<localizer> Element of Report XML
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 9.
Table 9. Attributes for <localizer>
|
|
|
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 "???<locale>.<key>???"
A value of -1 means to throw an exception. |
Localizer can include <resourceBundle> as its child elements. <resourceBundle> Element of Report XML
This element specifies one resource bundle property file name to be used for report localization. See Internationalization/Localization on page 55 for more information. 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-Billling) is used for localization. <prompts> Element of Report XML
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 <dataSource> Element of Report XML. <templates> Element of Report XML
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 is in the global template list. This allows an individual transformer to use its own template. See <transformer> for detail.
<template> Element of Report XML
This element defines a global template, which has following attributes described in Table 10.
Table 10. Attributes for <template>
|
|
|
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. |
<report> Element of Report XML
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.
<dataSource> Element of Report XML
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. It 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-Billling 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 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.
<query> Element of Report XML
This element defines the query used to retrieve data from the data source. It applies to an SQL data source but not 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 11 describes the attributes of the <query> element.
Table 11. Attributes for <query> Element
|
|
|
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. True or False; the default is False. |
maxRows |
No |
This attribute indicates the Boolean number of rows will be retrieved from the data source. An integer; the default is 1000. |
<inputBindings> Element of Report XML
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. <inputBinding> Element of Report XML
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 ActionForm 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 ActionForm also. For example, the ReportForm from the Oracle Self-Service E-Billling 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 12 describes the attributes of the <inputBinding> element.
Table 12. Attributes for inputBinding Element
|
|
|
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.
<prompts> Element of Report XML
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 a 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.vm controls the layout format, and prompt.vm controls the prompt rendering. 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.do" 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, the global <prompts> helps you to maintain only one copy of it. The <prompts> element has the attributes described in Table 13.
Table 13. Attributes for <prompts> Element
|
|
|
id |
Yes |
A unique ID is used to identify this prompts list in this data source. Oracle Self-Service E-Billling supports one prompts element for each data source. |
formName |
No |
The name of the HTML form and default reportForm. It is only useful if you want to use JavaScript to manipulate the form. |
action |
Yes |
The action of the HTML form. Use report.do for the action because it is used as the default. If you change the action name defined in Struts config XML, 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. <block> Element of Report XML
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. <group> Element of Report XML
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 14.
Table 14. Attributes for <group> Element
|
|
|
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>. <select> Element of Report XML
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 15 describes the select options.
Table 15. Attributes for <select> Element
|
|
|
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 ActionForm property is used to hold this input value. In the example, the billPeriod property of ActionForm holds the value of the select box. If there is no corresponding property in the ActionForm (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)"/>
where 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 ActionForm implementation 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 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. True or False; The default 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, 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.
<checkBox> Element of Report XML
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 <select> Element of Report XML. 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. <radio> Element of Report XML
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. <text> Element of Report XML
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. <image> Element of Report XML
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 16. Attributes for <image> Element
|
|
|
name |
Yes |
The display name of the image. |
scr |
Yes |
The image src. |
align |
No |
Left or right. |
Table 16 describes the attributes for the <image> element. <label> Element of Report XML
This element defines text to display in the form. For example: <label name="ccc_toll_lbl" value=" and " />
Table 17. Attributes for <label> Element
|
|
|
name |
No |
Not used. |
Value |
Yes |
The text to be displayed as it is on the screen |
Table 17 describes the attributes for the <label> element. <reset> Element of Report XML
This element displays an HTML reset button. For example: <reset name="reset" value="reset" />
Table 18. Attributes for <reset> Element
|
|
|
name |
Yes |
Name of the reset button. |
value |
Yes |
The display value of the reset button. |
onClick |
No |
JavaScript to invoke. |
Table 18 describes the attributes for the <reset> element. <submit> Element of Report XML
This element displays an HTML submit button. For example: <submit name="submit" value="ok" />
Table 19. Attributes for <submit> Element
|
|
|
name |
Yes |
Name of the submit button. |
value |
Yes |
The display value of the submit button. |
onClick |
No |
The JavaScript to invoke. |
Table 19 describes the attributes for the <submit> element. <columns> Element of Report XML
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. <column> Element of Report XML
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 20.
Table 20. Attributes for <column> Element
|
|
|
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.
<transformer> Element of Report XML
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 21.
Table 21. Attributes for <transformer> Element
|
|
|
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 it does, 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. |
<columns> Element of Report XML
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. <column> Element of Report XML
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.do?reportId=myReport&parameter(myColumnId)=$col" localize="true" />
Table 22 lists all the attributes for the <column> XML element.
Table 22. Attributes for <column> Element
|
|
|
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, the template generates a URL link for this column. True or false; the default is false. |
defaultSort |
No |
This attribute defines whether to sort this column when the report generates. 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. 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. 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. True or false; the default is false. |
<link> Element of Report XML
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. <templates> Element of Report XML
This element includes a list of template elements. It has no attributes, and includes only one element, template . <template> Element of Report XML
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 23 describes the attributes for the <template> element.
Table 23. Attributes for <template> Element
|
|
|
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. <groups> Element of Report XML 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. <group> Element of Report XML
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 24 describes the <group> element attributes.
Table 24. Attributes for <group> Element
|
|
|
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. |
<column> Element of Report XML
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 25.
Table 25. Attributes for <column> Element
|
|
|
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. |
<calculator> Element of Report XML
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 26.
Table 26. Example of Table Generated by the Reporting Engine
|
|
|
12345 |
10.01 |
0.23 |
23456 |
12.11 |
1.03 |
Total |
22.12 |
1.26 |
Average |
11.06 |
0.63 |
<operationGroup> Element of Report XML
This element defines a group of operations. Different operations in the group must operate on different columns, but it is not required they 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 necessary to define an operation on the first visible column, 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 27.
Table 27. Attributes for <operationGroup> Element
|
|
|
name |
Yes |
The name of this group of operations. The default template, report_body.vm, presents it as the first column of the operation row of the table. |
This element can contain one or more <operation> elements. <operation> Element of Report XML
The <operation> element defines a single calculator operation on a single column. It has the attributes described in Table 28.
Table 28. Attributes for <operation> Element
|
|
|
type |
Yes |
The type of operation:
- summary
. F inds the summary of all the values of the column identified by columnId attribute.
- avg.
F inds the average of all the values of the column identified by columnId attribute.
- max.
F inds the Boolean value of all the values of the column identified by the columnId attribute.
- min.
F inds the minimal value of all the values of the column identified by the columnId attribute.
count. F inds the total number of rows. In this case, columnId is optional. |
columned |
Yes |
The ID of the column that the operation will apply to. |
<charts> Element of Report XML
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>
<chart> Element of Report XML
This element defines a single chart for this transformer. Oracle Self-Service E-Billling 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 29.
Table 29. Attributes for <charts> Element
|
|
|
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-Billling 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>. <datasets> Element of Report XML
This element allows you to define multiple data sets used to draw the chart. Only one dataset for each chart is supported. <dataset> Element of Report XML
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> . <column> Element of Report XML
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 30.
Table 30. Attributes for <column> Element
|
|
|
id |
Yes |
The ID of the column where the chart will get its data. The type of the column must be a number. |
<xlabel> Element of Report XML
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. <column> Element of Report XML
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 31.
Table 31. Attributes for <column> Element
|
|
|
id |
Yes |
The ID of the column where the chart will get its x-axis values. |
<downloadList> Element of Report XML
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 32.
Table 32. Attributes for <downloadList> Element
|
|
|
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. |
<download> Element of Report XML
The <download> element defines one download for the report. It has the attributes described in Table 33.
Table 33. Attributes for <download> Element
|
|
|
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. Depends on the template; it can either be shown as a URL link or as a list item. |
description |
No |
Description of the download. Currently it is not used by template, but you can modify template to use it for 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, the templates will be parsed and appended together in the order of the templates defined in XML |
<printList> Element of Report XML
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 34.
Table 34. Attributes for <printList> Element
|
|
|
name |
No |
The name of this printList. It is not used by current template |
<print> Element of Report XML
The <print> element defines one print-friendly for the report. It has the attributes described in Table 35.
Table 35. Attributes for <print> Element
|
|
|
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. |
<customList> Element of Report XML
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 36.
Table 36. Attributes for <customList>
|
|
|
name |
N |
The name of this customList. It is not used by current template. |
<custom> Element of Report XML
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 37.
Table 37. Attributes for <custom> Element
|
|
|
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://jakarta.apache.org/velocity/index.html Oracle Self-Service E-Billling 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-Billling 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, where EDX_HOME is the directory where you installed Oracle Self-Service E-Billling. The lib subdirectory includes some Velocity MACRO library files and the reporting subdirectory includes report template files. Table 38 explains the libraries that are included with the report package.
Table 38. Libraries Included with Reporting Package
|
|
Lib/report_library.vm |
This file defines some common MACROs used by the Reporting Engine. You must use it as it is. |
Table 39 explains the templates that are included with the report package.
Table 39. Templates Included with Reporting Package
|
|
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 report. It displays the custom report detail and allows you to type a name for the report to save into 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 database. |
common/xml.vm |
This template renders the XML format of a report. |
pdf/PrintSummary.rtf |
This template renders PDF format for the Print Summary quick link on B2C 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. |
|