Report Localization Customization
Objective
You want to provide localized versions of your custom reports in your Windchill Business Reporting (WBR) system.
Background
The Windchill Business Reporting (WBR) solution uses Windchill and Cognos objects. There are both Data Source and Report objects that contain text that can be localized. Localizing the text in these objects allows the text to be displayed in the client's locale.
Scope/Applicability/Assumptions
This documentation assumes that the Windchill Business Reporting (WBR) solution (that is, Cognos) has been successfully installed and configured. The Windchill instance name is referred to as <WindchillInstanceName>. The Cognos root URL is referred to as <WBRHomeURL>. Typically, if the WBR solution is installed on <WBRHost>, then the <WBRHomeURL> would be http://<WBRHost>/cognos8/cgi-bin/cognos.cgi. It is assumed that you can login to <WBRHomeURL> and you have sufficient Cognos privileges to view Windchill Data Source objects and create reports.
• Assume you have access to create files in the source directory associated with <MyPackage> in <WindchillHome>.
• Assume you have created an Info*Engine task <MyTask> in its associated sub-directory <MyTaskPackage> in <WindchillHome>.
• Assume you have created the ReportTemplate, <MyReportTemplate> in the Site context of <WindchillHome>.
• Assume you have created a Windchill Report object, <MyReport> in the Site context.
• Assume you have created a Cognos Report, <MyCognosReport> in the Windchill folder.
For WBR integration, you must also have access rights to update the reporting meta model. This document describes procedures for using standard Java resource bundles to externalize text used in the WBR system. To support localized text, a language specific resource bundle must be created and the text translated to the appropriate language. It is assumed that you require support for more than one language and you have the ability to translate text to your supported languages. The text elements that are referred to in this document consist of report names, parameters, and columns. The actual data displayed in WBR reports is returned from Data Sources. Localizing this data is not covered in this document.
Intended Outcome
The end result of this solution is the use of your WBR reports in more the one language based on the client locale.
Solution
External localized text to Java resource bundles that can be translated to support a specific client locale.
Prerequisite knowledge
To achieve this objective, you need to have an understanding of the following:
• Info*Engine User's Guide
• JConsole User Interface
• Cognos User Interface
• Report Management User Interface
Solution Elements
|
Element
|
Type
|
Description
|
|
<MyTask>
|
Info*Engine Task
|
The Info*Engine task for retrieving and manipulating Windchill data.
|
|
<MyTaskResource>
|
Resource Bundle Info Properties File
|
The resource bundle info file used to localize Info*Engine task text items.
|
|
<MyReportTemplate>WindchillReportTemplate
|
Windchill Object
|
The Windchill object that specifies a query for retrieving Windchill data.
|
|
<MyReportTemplateResource>
|
Resource Bundle Info Properties File
|
The resource bundle info file used to localize ReportTemplate text items.
|
|
<MyReport>WindchillReport
|
Windchill Object
|
The Windchill object that is displayed to end users in the Windchill User Interface. It acts as a proxy to a corresponding Cognos Report object.
|
|
<MyReportResource>
|
Resource Bundle Info Properties File
|
The resource bundle info file used to localize Report text items.
|
|
<MyCognosReport> Cognos Report
|
Cognos Object
|
The Cognos object for a report that contains the definition of the query and specifies the presentation formatting.
|
|
<MyCognosReportResource>
|
Resource Bundle Info Properties File
|
The resource bundle info file used to localize Cognos Report static text.
|
Procedure - Localizing an Info*Engine Task Data Source
1. Create the file, <WindchillHome>/src/<MyPackage>/<MyTaskResource>.rbInfo. Add entries, as necessary, for the task method name, parameter names, and column names. Create language specific versions of <MyTaskResource>.rbInfo and generate the associated java source and compiled class files.
2. Edit the task XML file, <WindchillHome>/tasks/<MyTaskPackage>/<MyTask>.xml to specify the resource bundle. The following line should be added to the task comments.
{resouceBundle: <MyPackage>.<MyTaskResource> }
3. Update the Cognos model to incorporate the localized text. Launch JConsole from installed Windchill shortcuts. Connect to the PTC Embedded Servlet Engine (based on Tomcat) JVM instance. Select reporting management bean from the MBeans tab, “com.ptc > Monitors > ReportingSystem”. From the Operations tab, click "updateModel".
Procedure - Localizing a ReportTemplate Data Source
1. Create the file, <WindchillHome>/src/<MyPackage>/<MyReportTemplateResource>.rbInfo. Add entries, as necessary, for the task method name, parameter names, and column names. Create language specific versions of <MyReportTemplateResource>.rbInfo and generate the associated java source and compiled class files.
2. Update <MyReportTemplate> to specify the resource bundle. Navigate to the Windchill > and launch the Report Managementutility. From the Report Management UI, select <MyReportTemplate> and click "Update" to launch Query Builder. Select the > menu item and enter <MyPackage>.<MyReportTemplateResource> into the "Resource Bundle" text field. Click "OK" and save the changes.
3. Update the Cognos model to incorporate the localized text. Launch JConsole from installed Windchill shortcuts. Connect to the PTC Embedded Servlet Engine (based on Tomcat) JVM instance. Select reporting management bean from the MBeans tab, “com.ptc > Monitors > ReportingSystem”. From the Operations tab, click "updateModel".
Procedure - Localizing a Windchill Report Object's Name
1. Create the file, <WindchillHome>/src/<MyPackage>/<MyReport>.rbInfo. Add an entry for the Report Object's Name. Create language specific versions of <MyReportResource>.rbInfo and generate the associated java source and compiled class files.
2. Update <MyReport> to specify the resource bundle. Navigate to the Windchill "Site > Reports" page, select the edit action for <MyReport>. Enter "<MyPackage>.<MyReportResource>" into the "Resource Bundle" text field and click "OK".
3. Verify the Report attribute "localizedName" is the translated text based on the client locale.
Procedure - Localizing a Cognos Report
1. Once the Cognos meta model is localized (See “Procedure - Localizing an Info*Engine Task Data Source” and “Procedure - Localizing a ReportTemplate Data Source” above), there is only a single step required to localize the report's name, parameters, and columns. The Report Studio locale must be set to a locale, for which you want to view the localized reports, before authoring the report.
2. Verify the report name, parameters, and columns is the translated text based on the client locale when the report is executed. Use the "Run with options…" action to run the report.
Customization Points
Procedure - Localizing Cognos Report Static Text
When the above Procedure — Localizing a Cognos Report is followed all report parameter and column names are automatically localized based on the Data Source meta-model information. Any additional text added to a report such as banners or labels is not automatically localized. This can be accomplished using Windchill utilities.
1. Add the static text fields to <MyCognosReport>.
2. Create the file, <WindchillHome>/loadFiles/cognosReports/custom/<MyCognosReportXML>.xml based on an <MyCognosReport>t. Use Cognos Report Studio menu item "Tools > Copy Report to Clipboard" to copy the XML definition to the system clipboard. Then, paste the clipboard contents into a text editor and save it to file.
3. Generate the base resource bundle file, <WindchillHome>/src/<MyPackage>/<MyCognosReportResource>.rbinfo using the CongosProxy utility.
windchill com.ptc.windchill.cognos.CognosProxy outputrbinfo
<WindchillHome>/loadFiles/cognosReports/custom/<MyCognosReportX
ML>.xml
<WindchillHome>/src/<MyPackage>/<MyCognosReportResource>.rbinfo
4. Create language specific versions of <MyCognosReportResource>.rbInfo and generate the associated java source and compiled class files.
5. Create the file, <WindchillHome>/loadFiles/cognosReports/custom/<MyCognosReportAttributes>.properties. The base names from this and step 2 must match exactly (e.g. MyCognosReport.xml and MyCognosReport.properties).
type=report
defaultName=<MyCognosReport>
resourceBundle=<MyPackage>/<MyCognosReportResource>.rbinfo
6. Load <MyCognosReport> using the following command.
windchill com.ptc.windchill.cognos.CognosProxy loadreports
<WindchillHome>/loadFiles/cognosReports/custom/<MyCognosReportA
ttributes>.properties
7. Verify the report in Cognos. Refresh the "Public Folders > Windchill" folder and the <MyCognosReport> object should be listed. Use the "Run with options…" action to run the report. Try setting different client locales to ensure that the static text is translated properly.
Limitations
To localize a Cognos report, the Report Studio locale must be set to "en_ZW" before authoring a report. Cognos reports reference localized data source and column names based on the Report Studio locale. Any change to these data source and column names for this locale will result in not being able to look up the translated text in another locale. The official workaround recommended by Cognos is to use non-volatile names in a special locale. This special locale is "en_ZW".
Sample Code
Examples of Usage in Windchill Code
All out-of-the-box reports are localized for all Windchill supported locales.
Related Packages/Class Javadoc
• Foundation modulue
wt.query.template
• Reporting module
com.ptc.windchill
Other Related Windchill Documentation
• Report Management online help
Related Websites