Professional Documents
Culture Documents
Localization 0402
Localization 0402
This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. The document and product are protected by copyright and distributed under licenses restricting their use, copying distribution, or transmittal in any form without prior written authorization of Pegasystems Inc. This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services described. This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant. For Pegasystems trademarks and registered trademarks, all rights reserved. Other brand or product names are trademarks of their respective holders. Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time.
This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA 02142-1590 Phone: (617) 374-9600 Fax: (617) 374-9620 www.pega.com PegaRULES Process Commander Document: Localizing an Application Software Version 4.2 SP5 and 5.1 Updated: August 23, 2006
Contents
Introduction..........................................................................................................1 Overview..............................................................................................................1 Unicode Support Details...............................................................................2 Prerequisites .................................................................................................2 Assumptions .................................................................................................2 Enabling Localization in PegaRULES...............................................................5 Setting the Locale ...............................................................................................5 Client-side Settings.......................................................................................5 Browser Support.................................................................................... 5 Operator ID rule ......................................................................................... 13 Calendar/Time Zone ........................................................................... 13 Locale .................................................................................................. 14 Set Locale tool ........................................................................................... 14 Application-specific user interface............................................................. 18 RuleSets and Localization ............................................................................... 19 Localizing Process Commander RuleSets: Language Packs ................ 20 Localizing Application RuleSets................................................................ 21 Assembling Localized RuleSet Lists......................................................... 23 Important Notes about Localized RuleSets........................................ 23 Displaying Localized RuleSets.................................................................. 24 Developing with Localized RuleSets......................................................... 26 Building a Localized Application.....................................................................27 Localization Building Blocks: Field Values ..................................................... 27 Field Value Groupings............................................................................... 30
Naming Field Values ................................................................................. 32 Field Value Processing.............................................................................. 32 Valid Field Value Entries ........................................................................... 33 Parameter Reference.......................................................................... 34 Property References ........................................................................... 37 Using Field Value References in Activity Methods................................... 38 Property-Set-Messages and Page-Set-Messages ............................ 38 History/Audit Fields.................................................................................... 40 The Audit Note Field............................................................................ 41 The History-Add Method..................................................................... 42 Creating the Application................................................................................... 45 Overview .................................................................................................... 45 Creating Flows........................................................................................... 46 Creating Flow Actions................................................................................ 49 HTML Tab............................................................................................ 49 Form Tab ............................................................................................. 51 Flow Action Help ................................................................................. 54 Creating the Work Items............................................................................ 56 Harnesses ........................................................................................... 56 Sections ............................................................................................... 58 Creating Reports........................................................................................ 60 Summary Views .................................................................................. 61 List Views............................................................................................. 64 Correspondence ........................................................................................ 67 Using Custom Code in a Localized Application............................................69 Localization References in HTML Code ......................................................... 69 JSP lookup tag........................................................................................... 70 Using the pega:lookup localization feature......................................... 71
getLocalizedTextForString ........................................................................ 74 Referencing getLocalizedTextForString in HTML Properties............ 74 Creating New Field Value Groups................................................................... 78 Create the Property ................................................................................... 78 Define Field Values.................................................................................... 79 Use in custom HTML................................................................................. 79 lookup example ................................................................................... 79 getLocalizedTextForString example................................................... 79 Localizing Properties........................................................................................ 80 Number-Formatted Properties .................................................................. 80 Text Properties........................................................................................... 83 Localizing Prompt List Properties ....................................................... 83 Localizing Local List Properties .......................................................... 84 Localizing Field Value Properties with PromptFieldValue ................. 85
Introduction
Overview
For companies which need to incorporate multi-language support in their BPM/BRE solutions, PegaRULES Process Commanders architecture is designed to provide multilanguage capabilities in both the user and application environments (business solutions). Application screens can dynamically integrate the language preferences of both the user and the customer, which is useful in customer service settings. Thus, multi-lingual users that handle calls from multi-lingual customers can optionally see structural information in their preferred language, while seeing scripts, descriptions, and correspondence as the customer would see them. The rules architecture seamlessly integrates elements based on user preferences and the language of the current customer. Although the core development environment is based in English, beginning in Version 4.2 Service Pack 5, PegaRULES has the ability to present users with forms and rule translations in their preferred language. The default English presentation may be overridden with the users choice of language in the following key areas: Application screens, fields, reports, and some error messages Customer correspondence templates User interface for workers and managers
Note that only the user interface functionality is being localized. The PegaRULES localization technology is an aid to customers who wish to translate their application; it is not meant to be an entire complete solution in all languages. The localization process involves the following steps: 1. Set the users environment to their desired language 2. Enable localization in Process Commander 3. Create a localization-ready application, and then translate the labels that users would see into all desired languages. These steps will be reviewed in detail in this document.
Important: As developers create applications to be localized, they should endeavor to comply with all the SmartBuild practices and guard rails; this will make localization and maintenance of the application much easier and more efficient.
CONFIDENTIAL
Overview
Prerequisites
Companies which are writing Process Commander applications which will be localized must have Version 4.2, Service Pack 5 or a later release (which includes Version 5.1). The reader of this document must be familiar with rules and other structures required for the development of applications in Process Commander, and must be skilled in development of these applications. VITAL: Companies doing localization must have set up their database to handle Unicode, both in the Stream (BLOB) column and in all the exposed columns. If the existing database does not have Unicode on all the columns, the database must be changed. For some databases, this may require reinstalling the database software (and then reinstalling any other software - such as application servers - that require being installed after the database software.
Assumptions
This tech note is a description of how to enable localization features in Process Commander, and is intended for application developers who are very familiar with writing applications in PegaRULES. This document is not a description of how a company should
2 CONFIDENTIAL
Overview
approach localizing their application. It is assumed that the developer has a solid understanding of globalization concepts, and has designed their application accordingly. For example, common fields must be designed by the application developer to accept data in formats appropriate to all countries. These include: address fields Postal codes and ZIP codes (numeric in the US, alphanumeric in Canada, nonexistent in some countries) telephone numbers (great difference between the US and other countries) personal address first name, last name, title
The eBusiness Globalization Solution Design Guide by IBM (<http://www.redbooks.ibm.com/redbooks/pdfs/sg246851.pdf>) is highly recommended for an overview of globalization. This tech note also references IBMs International Components for Unicode (ICU) technology, which is exploited by PegaRULES to facilitate globalization. Please see http://www.ibm.com/software/globalization/icu for further details.
In this technical note, references may be made to user, developer, and customer. It is assumed that the developer will be writing an application for their company, and that this application will aid interactions between users of the application at that company and customers of that company. For example, the developer may write a financial application involving a mortgage loan process for a bank; the user would use this application to open a mortgage for a customer of the bank.
CONFIDENTIAL
Overview
CONFIDENTIAL
Client-side Settings
Setting the locale in the users browser is a permanent way to enable a particular language for that user. Every time the user starts Process Commander, that language will be the default. There are two parts to setting a language/country on a client machine: browser support (to set the locale) font support (to be able to display the chosen language properly)
Browser Support
The default locale for a PegaRULES user is based on the browsers locale settings (language settings). Once the appropriate fonts are installed onto the client-side PC, the browser support must be set, to provide the locale information to PegaRULES. In Internet Explorer, click on the Tools menu and choose Internet Options.
CONFIDENTIAL
The language that is displayed at the top of the Preference list is the default language that will be used for the Locale setting.
CONFIDENTIAL
To add a new language, click on the Add button and choose the new language from the available list. It is also possible to add your own language in the User defined field. NOTE: Locales entered in the User defined field should be in the language-country format (using a dash) and not in language_country format (using an underscore) that is accepted by Java. (For example, Hindi should be added in the browser as hi-in and not hi_in.) Also, Internet Explorer will not validate whether a valid locale is entered it is necessary to know the appropriate locale designation beforehand. NOTE: Internet Explorer has a number of language (or locale) choices that consist of only a language (not the country or variant see the Localized RuleSets section of this document). However, PegaRULES uses the country component of the locale designation to determine how to display dates and numbers, which are attributes of locale that vary by country, not just language. Better results will be obtained by choosing a designation of frFR rather than just fr.
CONFIDENTIAL
Important: Once the new language has been added to the Preferences screen, it must be moved to the top in order to make it the default language.
Highlight the language that will be the default for this user, and click Move Up. This will move the language to the top of the list and make it the default. After a user updates their browser locale and submits input to PegaRULES, the localespecific RuleSet List is refreshed (see the Localized RuleSets section), and the new locales formats are applied to the PegaRULES displays. NOTE: Changing the browser locale in the middle of resolving a Work Item will change the language in which that Work Item is displayed. Pegasystems recommends that users avoid changing locales in the midst of processing a single work item. Unexpected behavior or erroneous data interpretation can occur if locale is changed when ones forms are displayed. (For example, a form containing dates formatted for a Hindi locale cannot be interpreted in an English locale. The calendar pop-ups are prone to this issue.) Complete the processing of a given form, and then change the locale and begin processing in the new locale. Important Note: The changes made to the browser will persist. If the user closes PegaRULES and exits the browser, and then later starts the browser again, the default locale will remain as it was set.
Font Support If a web page is displayed that includes characters for which suitable fonts are not installed, some of the characters may display as little boxes (or as question marks or other glyphs on an XP system) instead of the appropriate character. It may be necessary to install additional fonts for various languages to display the web page properly. To confirm whether fonts are available in Internet Explorer, select Tools and then Internet Options from the IE menu. From the General tab, click on the Fonts button.
8 CONFIDENTIAL
Using the Language script dropdown box, navigate to the script or character set that is not being displayed properly and select it. If the font is available in the system, it will be highlighted in the Web page font or Plain text font dropdown box, and the appropriate font will be demonstrated in the field below each.
If a script is selected for which no font is available, it may be possible to add the font to the system. Fonts and language support may be installed by following Microsofts instructions and conventions. In general (when using IE6), appropriate fonts cant be downloaded from Windows Update, but instead, support must be installed from either a Windows 2000, Windows XP or Microsoft Office CD (depending upon the users platform). Notes on this process: 1. Even if a font is displayed in a script in the dialog window, the language may not display correctly in all situations (e.g., proper display of Hindi-Devanagari script in a dropdown list
9
CONFIDENTIAL
requires the Mangal font, even though Arial Unicode MS is sufficient to display most other text on a web page.) 1. Visiting a web page that uses an encoding (other than UTF-8 or UTF-16) for which an appropriate display font is not installed will result in a prompt to install the appropriate language pack. The Windows 2000 or Windows XP CD will be needed in order to successfully complete this task. 2. Language support may be added by using the Regional Settings applet from the Control Panel. Select Start | Settings | Control Panel and click on Regional and Language Options.
(NOTE: The Windows 2000 screen for this setting may look different.) Choose the Languages tab.
10
CONFIDENTIAL
On this tab, check the additional language support desired and click Apply. This may install some fonts that are already present on your system, prior to prompting for the Windows 2000 or Windows XP CD. NOTE: If Cancel is clicked when prompted for the CD, the installed fonts are not removed and the web page may now display correctly. If Cancel is clicked, the language selected is not completely installed, and the checkbox is removed from the Language Settings for the System panel. If the additional files are installed from the CD, other languages may now display correctly also, since some fonts are shared across multiple scripts. (For example, after clicking Cancel during the install for Traditional Chinese, a font suitable for it was available, but no support for Japanese. After completing the full installation for Traditional Chinese, a font that was suitable for Japanese was also present and some, but not all, glyphs in Simplified Chinese.) 3. Font support may be added for multiple languages by installing Microsoft Office International Support (and in particular the so-called Universal Font Arial Unicode MS). See Microsoft Knowledge Base article 287247 for more information.
In Control Panel, select Add/Remove Programs. Then Select Microsoft Office and click Change.
CONFIDENTIAL
11
Depending upon the version of Microsoft Office installed, make the appropriate selections to add additional features and select International Support, adding the appropriate fonts and selections. Note that Pegasystems does not redistribute fonts with PegaRULES; it is the clients responsibility to obtain and install suitable fonts for the languages they require. There are untested fonts from other sources which may work: ftp://ftp.netscape.com/pub/communicator/extras/fonts/windows/ (Netscapes free CJK font developed by Bitstream) http://babel.uoregon.edu/yamada/fonts.html (free fonts) http://www.alanwood.net/unicode (Unicode and Multilingual Support in HTML, Fonts, Web Browsers and Other Applications)
12
CONFIDENTIAL
Operator ID rule
There are two localization-related settings in the Operator ID record for each user.
Calendar/Time Zone
If the user will always be in a particular time zone, it is possible to set that in the operator record.
On the Availability tab, the Time Zone field allows entry of a specific time zone for this user. Important: This setting will override the Localization settings (such as the setting in the browser), as well as the client machine timestamp setting for the session application processing. If this setting is entered, the user must be certain that their time zone will not enter data that conflicts with localization settings into their work objects.
CONFIDENTIAL
13
Locale
It is also possible to set a users locale permanently through the Locale Settings field.
On the Security tab of the Operator ID record, enter the appropriate locale for the user into the Always Use Locale field. The locale should be entered in standard internationalization format: xx_XX (example: en_US). Important: This setting will override any other localization settings, including the browser setting, in the Process Commander application. (It will not change the browser setting, but will override it in the application only.)
The Locale default that will be displayed is read from the browser setting. All the locales available in the ICU are included in the dropdown list, whether or not there are RuleSets currently present for those locales.
14
CONFIDENTIAL
If another locale is preferred, select the appropriate locale from the Use Locale list, and click Update. This will take the original RuleSet List and re-localize it based on the new setting. NOTES: Clicking Update will create work items in the chosen language (if the localized RuleSet Lists are present). However, it will not immediately change the Portal to the new language. To change the Portal also, hit the F5 key to refresh the screen. When the new locale is chosen, then the Use Locale dropdown list will appear in the language chosen for the new Locale. The list is also sorted based on the collation rules for the selected new Locale. In the example below, French (France) was chosen and the Use Locale dropdown list is now displayed in French:
CONFIDENTIAL
15
Important Note: The changes made using Set Locale do not persist from one session to the next. If the user exits the PegaRULES system, and then logs into PegaRULES again, the system will pick up the Locale from the default set in the browser, not from the last Set Locale change. Also, changing the Locale by using Set Locale will not change the default in the browser. Clicking on the Settings button will bring up a small window showing the default Locale and Time Zone information (read from the browser):
NOTE: The Settings button uses a Java applet; in order to use this button, the user must have Java 1.3.1, 1.4.x, or Java 5 installed on their client machine.
16 CONFIDENTIAL
Clicking on the Demo button will show the settings in the system. If the Locale is changed from the Set Locale screen (as described above), then the Demo window will display all information based on the chosen Locale:
However, if the Locale is changed within the Locale Settings screen, and then the Compute button is clicked, then the Default Locale field will display the original (browser) Locale, while the Selected Locale will display the new (selected) Locale.
CONFIDENTIAL
17
In the example above, although the Browser settings are set to en_US, the Locale has been changed to French (fr_FR).
18
CONFIDENTIAL
When a developer is localizing an application, they must begin with two sets of localized RuleSets: the application RuleSet the Process Commander RuleSet
CONFIDENTIAL
19
Note that for the Pega Language Packs, only the first level of localization (language) is provided. Anyone who wishes to write an application in a language other than English, or localize an existing English application into another language, would begin by obtaining the appropriate Language Pack, and then developing/translating their own application rules into that language. Thus, for the standard PegaRULES RuleSets, the following is an example of the list of the RuleSets and locale variants:
AcmeCo_fr_LU_PREEURO:04-02 AcmeCo_fr_LU:04-02 AcmeCo_fr:04-02 AcmeCo:04-02 Pega-ProCom_fr:04-02 Pega-ProCom:04-02 Pega-IntSvcs:04-02 Pega-WB_fr:04-02 Pega-WB:04-02 Pega-RULES:04-02
20
CONFIDENTIAL
CONFIDENTIAL
21
Acme Corp in Canada French: Additional localized RuleSets created by the developer: AcmeSubscription_fr_CA: 01-01 AcmeProducts_fr_CA:03-02 AcmeRulePro_fr_CA:04-01 AcmeBase_fr_CA:04-02 Final RuleSet: AcmeSubscription_fr_CA: 01-01 AcmeSubscription_fr: 01-01 AcmeSubscription: 01-01 AcmeProducts_fr_CA:03-02 AcmeProducts_fr:03-02 AcmeProducts:03-02 AcmeRulePro_fr_CA:04-01 AcmeRulePro_fr:04-01 AcmeRulePro:04-01 AcmeBase_fr_CA:04-02 AcmeBase_fr:04-02 AcmeBase:04-02 Pega-ProCom_fr:04-02 Pega-ProCom:04-02 Pega-IntSvcs:04-02 Pega-WB_fr:04-02 Pega-WB:04-02 Pega-RULES:04-02 Acme Corp in Spain Spanish: Localized RuleSets created by the developer: AcmeSubscription_es: 01-01 AcmeProducts_es:03-02 AcmeRulePro_es:04-01 AcmeBase_es:04-02 Final RuleSet: AcmeSubscription_es: 01-01 AcmeSubscription: 01-01 AcmeProducts_es:03-02 AcmeProducts:03-02 AcmeRulePro_es:04-01 AcmeRulePro:04-01 AcmeBase_es:04-02 AcmeBase:04-02 Pega-ProCom_es:04-02 Pega-ProCom:04-02 Pega-IntSvcs:04-02 Pega-WB_es:04-02 Pega-WB:04-02 Pega-RULES:04-02
22
CONFIDENTIAL
CONFIDENTIAL
23
If a user changes the locale (either by changing it in the browser or by using the Set Locale tool), the system will automatically take the original base list of Rules (that is displayed in the Profile), and re-localize this list based on the new locale information. If RuleSets for the new locale are not present in the system, no error will be displayed. The system will put RuleSet entries into the RuleSet List based on the Locale setting, regardless of whether the RuleSets exist. The system will not attempt to create localized RuleSets if they do not already exist. During Rule Resolution, the system will search all RuleSets and (because the others do not exist or are empty) use the base RuleSets. Thus, using the Acme RulePro example above, if a user were to log in as either French (in France) or French Canadian, they would get a list of 18 RuleSets. If they were to switch to Spanish, they would only receive 14 RuleSets, as there are fewer Spanish RuleSets available.
24
CONFIDENTIAL
The entire localized list of RuleSets can be displayed using the Clipboard Viewer (available from the Tools bar in the PegaRULES portal):
CONFIDENTIAL
25
These localization RuleSets should be added into the developers Access Group, in the order they appear on the clipboard. Thus, the most specific localization RuleSets should be listed before the less specific localized RuleSets, which in turn should be listed before the base PegaRULES RuleSets, to assure appropriate Rule Resolution processing.
26
CONFIDENTIAL
The Portals for Work Users and Work Managers are localized in the Language Packs, along with the standard managers reports. Note that the developer tools (such as Where Am I? are not localized.) The Work Item (or items) are the focus of applications written in Process Commander, and as such, are custom to each application. These must be localized by the developer, using the processes described in this section. Important: Note that functionality is provided to translate Process Commander applications into other languages. This does not mean that a translation engine is provided, where the developer can create an application in English and then press a button to magically translate that application into other languages. The application must be built according to the rules of localization, and Field Values must be created and then saved into the base application RuleSet (and then into localized RuleSets) to translate the user-visible labels for these rules.
CONFIDENTIAL
27
In this section are a number of labels: labels for the headers for each section, and then labels for the properties under each header. These labels include: Effort and Charges Amount Effort Estimate days charged to Actual Satisfaction and Responsiveness Satisfied Acknowledged Time in Work Status New Pending Deadline after Open Time Past Goal Organization Work Originated At Work Originated By through on Resolution and Reopen Work Resolved At Reopened
28
CONFIDENTIAL
(A customer would undoubtedly customize the sections which are shipped with the product, and may have some different labels.) For each of these labels that a customer would see on a work item, a Field Value must be created.
When originally designed, the Field Value rules were used to create a drop-down list of values to choose for a particular property. Thus, it was necessary to define the Field Value on the same class as the property, and specify the property in the Field Name section, and then give the specific value for this part of the property drop-down in the Field Value area. This functionality has been adapted for the localization process. For localization of labels, the Field Value form should be completed as follows: Field Applies To Description The name of the class to which this Field Value applies. NOTES: The Field Value should be defined on a class which is available to all areas where this label may be used. Therefore, most Field Values are defined on @baseclass. For History/Audit information, the assumption is made that these entries would only be created in relation to a work item. All the History memo Field Values are defined on the class Work-.
Field Name
The name of the grouping property to which this Field Value instance belongs. (See the Field Value Groupings section below for details.)
Field Value
The lookup key name of this field value. This name: may contain spaces (Time in Work Status New) may contain up to 64 characters (See the Naming Field Values section below for more details.)
CONFIDENTIAL
29
Field
Description
Short Description
The full description of the text string for this Field Value. This field may contain up to 255 characters. NOTE: The Field Values that are shipped with Process Commander are in English (the base language of the product). For any Language Packs that are created from these base Field Values, the Short Description will remain in English, while the Localized Label field will be translated.
Localized Label
The localized version of this entry. For the Field Values shipped with the system, this field will be contain the Short Description information displayed in English; for any of the Language Packs, this field will contain the Short Description text in the appropriate language. NOTE: This field must be filled in with text, not only for the localized versions, but also for the base language (usually English). If the field is not filled in, then blanks will appear instead of labels in the base language application.
In addition, for the localization Field Values, the Usage Field on the History tab should contain a context sentence to aid in translation of this Field Value.
For some of the longer-named Field Value instances (such as Click here to submit the form), the meaning of the phrase is clear and does not need further explanatory text in order to translate it correctly. However, for a Field Value such as Back or Cost, it is necessary to have some contextual information provided in order to specify whether this is a noun or a verb, and what meaning of the word should be used for translation. This context information is in the Usage field.
30
CONFIDENTIAL
created for localization do not apply only to one specific property. Nevertheless, several properties have been created to group the Field Values for ease of use. Release 4.2, Service Pack 5 contains the following Field Value grouping properties: Available Applies To classes @baseclass
Usage tooltips, text that tells the user what action to take buttons, URLs, clickable items labels, headers, fieldsets, etc. Confirmation Notes (flows only) names of all countries codes for all the countries history messages, Audit Notes (flows) Instructions (flows only) alerts, error messages, help the status of the work item (flows only) the status of the Assignments, and also information from the process the system is completing (creating, saving, deleting)
pyStatusLabel
@baseclass
IMPORTANT: For all rules which have autogenerated HTML, it is required to define new field values in the correct grouping. These rules include: harnesses sections flow actions
The localization functionality for these rules will look for the appropriate Field Value for a label in a specific group; if the Field Value has been defined in a different group, then the system will not find it and will not localize that label. In the sections below which give details about these rules, the label fields on the rule and their associated grouping are listed.
CONFIDENTIAL
31
When adding Field Values to the application, it is important to define them not only on the correct grouping property, but also on the correct class. Process Commander contains Field Values defined mainly on two classes: Work- (for work item labels) @baseclass (for all other labels)
Customers may have work items which descend from several different application classes. If the Field Value is defined on only one of those classes, then it is not possible to gain efficiency by reusing some of the Field Values in other classes, and even more must be created for the application. Field Values should be defined on a very high-level (general) class in the hierarchy, in order to promote reusability.
32
CONFIDENTIAL
3. If no Field Value is found in a localized RuleSet, the system will look in the base RuleSet (possibly Pega-ProCom or Pega-WB). If a Field Value is found in the base RuleSet, the Localized Label for that Field Value will be displayed (generally in English). NOTE: The Localized Label field must be filled in with text for all Field Values, not only for the localized versions, but also for the base language (usually English). If the field is not filled in, then blanks will appear instead of labels in the base language application. 4. If no matching Field Values are found at all, the system will default to returning the text in that field. So from the first example, if no matching Field Values were present, then the system would display Operator ID. In the second example, the system would display ValidItemManagerApproval. NOTE: The recommended process for localizing an application is to create all the Field Values for the labels in English and store them in the base language application RuleSet, and then save the Field Values into each localized RuleSet and translate them. It is not required to have all of the Field Values in the base language (English, for example); different Field Value rules could be created into different localized RuleSets. There are two recommendations against this: a. If the application will be used in the base language (for example, English) as well as in other languages, then for a particular label in the application, Field Values would be needed for all languages, and must be present in all application RuleSets (localized or not). b. Due to the volume of Field Values required for most applications, if the application is to be translated into more than one language, then it is important for the developer to have all the Field Values in one RuleSet, in order to be able to track in one place - which Field Values have been created.
1
Steps 2 and 3 in this process actually happen simultaneously, through Rule Resolution. The system looks for the most appropriate rule to execute, and chooses the rule highest in the hierarchy which meets the criteria. If this is the rule in the localized RuleSet (higher in the Rule Resolution hierarchy), then that will be used; otherwise, one of the standard ProCom or WB rules will be used.
CONFIDENTIAL
33
In another language, the appropriate translation may end up being: <operatorID> entered this item at <timestamp>. It is important to reorder the text and the references when translating the Localized Label field, so that it is appropriate for the language of the localized RuleSet. IMPORTANT: The name of the Field Value may or may not indicate whether there are property or parameter references in the Short Description. It is up to the developer to know that a particular Field Value requires parameter or property references, and provide them correctly in the call for that Field Value.
Parameter Reference
The following is an example of a Field Value with parameter references:
The Localized Label field for this Field Value shows that two parameters are required. Each parameter reference is numbered and surrounded by curly brackets ( { } ). There is no limit to the number of parameters which can be specified in a Field Value, although it is recommended that some reasonable number be used (less than 10, for example), as the developer will have to provide parameter information for each reference each time this Field Value is used. The parameter numbers refer to the parameters specified in the Message Key where this Field Value is called. Thus, using the example at the beginning of this section, if the Localized Label field for the Field Value contains: Entered by {1} at {2}. then {1} would refer to the operatorID, and {2} would refer to the timestamp. The Message Key field in an activity (see Using Field Values section below for full details) would provide this information, using the tab delimiter syntax: EnteredBy\t + param.operatorID + \t + param.timestamp The key name of the Field Value (EnteredBy) is given in quotes, as well as the first tab delimiter, which is specified within the quotes. This is followed by a plus sign and the first parameter name; spaces may be put between the references and the plus sign, but are not required. The two parameter references are also separated by a plus sign and another tab delimiter in quotes. If further parameters were specified, they would continue to be added and separated by the tab delimiter: EnteredBy\t + param.operatorID + \t + param.timestamp + \t + param3 + \t + param4 + \t + param5
34
CONFIDENTIAL
Note, however, that if the Field Value only uses two parameters, any additional parameters in the Message Key field will be ignored. It is not possible to change the Field Value to use more parameters simply by including them in the Message Key; the Field Value rule itself must be changed and resaved. The order that the parameters are specified in the Message Key field will identify their numbers. Thus, if the message Entered by operatorID at timestamp is desired using the above Message Key data, then the Localized Label field of the Field Value would contain the expression above. If the message At timestamp, the operatorID entered this item is desired, the Localized Label field would contain: At {2}, the {1} entered this item.
Combined property and parameter reference in Message Key For a parameter-reference field value, property references and parameter references can be combined in the Message Key field. For example, the AssignmentCompleted Field Value contains two parameters:
"AssignmentCompleted\t" + Primary.pyInstructions + "\t" + Param.actionLabel were Primary.pyInstructions is a property reference, and Param.actionLabel is a parameter reference.
Localizing Parameter References For some Field Values, the parameters that are passed in may be property references which themselves require localization.
CONFIDENTIAL
35
For example, the AssignmentCompleted Field Value actually has slightly different text than shown in the previous section:
Assignment to '{1 InstructionsLookup}' completed by performing a '{2 CaptionLookup}'. As stated earlier, the first parameter for this Field Value is a reference to the property Primary.pyInstructions, which contains instructions. A run-time resolving of this Field Value might result in a message such as: Assignment to Review item and return to manager completed by performing a Return to Manager. Not only must the AssignmentCompleted Field Value text be translated, but also the .pyInstructions property reference (Review item and return to manager) must be localized. Since it is only a parameter reference in the Field Value, the localization lookup must be done as part of the formatting. In this example, both InstructionsLookup and CaptionLookup are Rule-HTML-Property instances which are lookup formatting rules:
The information in the HTML Property gives the system information to look up a Field Value instance for the property reference, thus translating it.
Formatting parameter references In addition to localizing the parameter references, it is possible to format them using the HTML Property functionality. The Field Value Select Type of Correspondence for involves formatting the name of the Party in bold characters.
36
CONFIDENTIAL
The HTML code in the HTML Property PartyRuleLookupBold contains the bold functionality.
Property References
The following is an example of a Field Value with property references:
As there are specific references to properties in the Field Value, no parameters are required in the Message Key field. For this type of Field Value, the Message Key field would only contain the key name: InstructionToUser Important: For this type of Field Value, the properties that are referenced must exist on the clipboard page at the time the field value is called. So for example, if this Field Value were referenced in an activity method, the properties .pyInstructions and .pyActionPrompt must exist and have a valid value when that activity ran and the Field Value was called.
CONFIDENTIAL
37
Formatting Property References Property references in Field Values may also be formatted.
The Field Value ChangeDivisionFromTo includes formatting to display the property reference value (.pyOwnerDivision) in bold text, by using the HTML property dataStyleFontBold.
38
CONFIDENTIAL
Both methods contain two other fields: Message The Message Key field, which contains the expression reference to the Field Value Category This field contains the grouping property name for the Field Value its Field Name property.
The above example contains the following information for a Property-Set-Message: Parameter Message Field Category Value FailedAddToFolder\t + pxThread.pxMethodStatus .pyFolderID pyMessageLabel
The Message parameter states that the key for the Field Value is FailedAddToFolder. This Field Value contains one reference, which will use the value from pxThread.pxMethodStatus.
CONFIDENTIAL
39
The FailedAddToFolder Field Value is assumed to be in the class of the Activity (Work-) or above (it is actually defined on @baseclass, so it is inherited by Work-), and the Category parameter specifies that the Field Value is in the group pyMessageLabel. When this item runs, it will add a message to the specified property .pyFolderID that Add to Folder Failed, Status = value of pxThread.pxMethodStatus Page-Set-Messages have similar functionality to the Property-Set-Messages process described above; however, instead of setting the message on the specified property, it would be set on the specified page.
Backward compatibility Originally, the Message field of Page-Set-Messages and Property-Set-Messages referred to a Rule-Message instance. To ensure backward compatibility with existing activities in applications written before the release of Service Pack 5, this functionality will still be supported. If the Category field is blank, then the data in the Message field is parsed as a Rule-Message instance. If the Category field contains data, then the data in the Message field is parsed as a Rule-Obj-FieldValue instance.
History/Audit Fields
The functionality of storing and displaying History or Audit data in general is different than other localization features, and should be treated separately. This functionality includes: the History-Add method in Activities the Audit field in flows
For most labels, the localization lookup is immediate: the user completes the action of Opening a New Item, for example, and the system does the localization lookup and displays the new work item in the users chosen language. History messages, however, have two distinct steps when a user completes an action: creating and storing/saving the data displaying the data
The History message may be created when a user completes an action transferring a work item, resolving it, etc. but it will not be viewed until the user actually clicks on the View History button.
40
CONFIDENTIAL
Therefore, localizing the History data should be done on the second step displaying only. For a company which has users who employ more than one language, it is important that when the users look at the History of a work item, they should see: the list of History messages is all in one language in other words, if several people have worked on this item, and they each speak a different language, the audit trail should not show one line of data in German (when the German-speaker accomplished a step in the process) and then one line in French and one line in Spanish. the list of items in their language - not in the language of the person who opened the item, or who worked on it, or who resolved it.
In Service Pack 5, the functionality of History was changed. The History-Add method and the Audit field were both enhanced to allow Field Values to be specified. When the history message is created and saved, only the Message Key and the value of the references (at the time the message is created) are saved. Then, when the History page is displayed, all of the Message Keys are localized to display in the language of the user viewing the page.
Property references may also be included in the Field Values defined for this field. When the flow goes through Java generation, the Field Values which are referenced in all the properties are opened and checked for property references. If there are any property
CONFIDENTIAL
41
references for the Audit Note, the appropriate property name and value for that reference are found and then copied into an embedded page in the History record.
Important: When defining Field Values for the Audit field, the Field Value (grouping property) must be specified as .pyHistoryMemo, so that these will display in the Smart Prompt drop-down list.
Parameter ForOperatorID
Description of Value This field contains the name of the operator who caused this particular history memo to be created. In most cases, it points to the current user: pxRequestor.pyUserIdentifier. for future functionality This field is available for free-form customer text notes. Any text that is typed in this field will be displayed to the user exactly as it is typed no localization is available for this parameter. NOTE: This field provides backwards compatibility with the original (non-localized) functionality.
HistoryModel HistoryMemo
RuleAction Category*
for future functionality This field contains the name of the grouping property which should be used to identify the history message. This field defaults to .pyHistoryMemo.
CONFIDENTIAL
42
MessageKey*
This field contains the Field Value key name (the Field Value data). This field can also contain any tabdelimited parameters.
As explained in the previous section, the Rule-Obj-FieldValue class contains three key properties: Class Name Field Name Field Value
There is also another field on the rule, .pyLocalizedValue, which is the value in the Localized Label field which holds the translation of the Short Description. In order to find the appropriate Field Value and return the Localized Label field for display, the system uses the following data: Class Name - the class of the primary page of the activity that is being run when the History-Add method is executed Field Name - the information in the Category field Field Value - the information in the Message Key field
As with the Page-Set-Messages and Property-Set-Messages methods, backward compatibility is provided: if the Category field is filled in, then the MessageKey field is parsed as a Field Value. If the Category field is blank, then the MessageKey field is parsed as a Rule-Message instance. At assembly time, the system will generate the code necessary to construct the message descriptor from the literals and property references in the Category and MessageKey fields. When this code is executed, the message will display the value that the parameters held when they were stored. Important: For Field Values which are created to work with the History-Add method, it is not possible to have property references defined in the Field Value rule itself. If the localized history message includes a property reference, that property reference must be defined in the MessageKey field:
CONFIDENTIAL
43
Unlike the functionality on flows, when History-Add runs, the Field Values which are referenced are not opened to check for property references, and the appropriate namevalue pairs are not saved to the embedded page of the History record. Thus, any property references for History-Add must be in the MessageKey field.
44
CONFIDENTIAL
CONFIDENTIAL
45
Creating Flows
As the developer is creating flows for the application, they must localize certain fields which contain text for the user. The Flow Rule form is localized by default; there is no box to check to enable localization (as there is on other forms). When the flow is opened in Visio, the developer can click on each flow shape to populate the Properties boxes.
46
CONFIDENTIAL
Depending upon the type of shape, there are different Properties boxes that are displayed:
CONFIDENTIAL
47
In the Assignment Properties box, there are several fields that are localized: Instructions StatusWork StatusAssign Confirmation Note
On some other Properties boxes, the Audit Note field will also be displayed; this field is also localized. In order to be able to localize the application, the text that is in these fields must resolve to a Field Value. (NOTE: If the text does not resolve to an existing Field Value, the text itself will be displayed as the label.)
48
CONFIDENTIAL
For some of the example flows, Field Values have been created:
However, developers creating their own applications can also create their own custom flows. In this case, they must also create Field Values for these Properties fields. The Field Values must be created in the following groups:
HTML Tab
The developer must begin by ascertaining that localization is possible for a particular flow action. When creating an application, one of the recommended procedures is to copy existing flow actions; in order to enable localization, the developer should start with a flow action rule from Service Pack 5.
CONFIDENTIAL
49
There are a number of settings on the HTML tab which affect localization.
Description Choice: enabled or disabled This checkbox determines whether there is custom HTML in this window. If auto generate is on, the system generates the HTML from the information on the Form tab. If auto generate is off, the system assumes that custom HTML has been entered into this window and shouldnt be overwritten with generated HTML.
Localization value checked (enabled) In order for localization to be enabled, the HTML must be auto-generated. If this box is unchecked, the Localize box will automatically uncheck.
50
CONFIDENTIAL
Description Choice: generate for JSP or for HTML When the system auto-generates the HTML code, for custom tags within that code, it can either use Pega directives (HTML), or standard JSP tags (JSP). Process Commander Best Practice states that for all applications built on the SmartBuild Release or later, all rules which generate HTML should use JSP tags. Choice: enabled or disabled This checkbox determines whether the system will treat the fields on the Form tab as just text to be displayed to the user, or as Field Value entries to be looked up by the system. Choice: enabled or disabled This checkbox determines whether the PegaRULES engine compresses the generated HTML code (stream) before sending it from the server to the client. (Compressing the HTML stream allows data to be sent faster from the server, resulting in greater efficiency in server response time.)
Localization value generate for JSP Almost all flow actions from Service Pack 5 have already been generated for JSP.
Localize?
checked (enabled) Localization is dependent upon the system looking up all the Field Values
checked (enabled) NOTE: If the rule has Auto Generate checked by default, then this checkbox will also be checked by default, and it will be grayed out (the user will not be able to change it).
(NOTE: The Define Form dropdown box and the Portlet Compliant checkbox are not relevant to localization. For more details on these settings, please consult the on-line Help or other Process Commander documentation.) Important: In order for localization to be enabled on flow actions, the Localize? checkbox and the Auto Generate checkbox must be checked.
Form Tab
In order to localize flow actions, it is necessary that the rules be displayed in smart frames. The old column-and-field-based forms have not been tested to support localization.
CONFIDENTIAL
51
The Short Description field at the top of the flow action contains the text that the user will see in the Take Action drop-down box. Therefore, the developer must ascertain that a Field Value is created for this item. In addition to the Short Description, a Field Value must also exist (for localization) for each of the labels that a user sees. In the smart frames version of this rule, each area of the flow action may be clicked to display information about the properties that make up that area. For example, clicking on the Completion Note section of the above Flow Action will display the following information:
52
CONFIDENTIAL
The Layout box shows information about the Completion Note section of this Rule:
The Title field contains the title of this section. In order to localize the application, this field must contain a Field Value reference.
CONFIDENTIAL
53
Clicking on other parts of the flow action will display other properties:
The Value field contains the Field Value for other properties. For the fields on a flow action, Field Values should be defined on the following grouping properties. Field Value Applies To class @baseclass Field Name (grouping property) pyMessageLabel
Usage Instructions (the tooltip info at the bottom of the screen) buttons, URLs Short Description header, tabs button, URL, icon labels
54
CONFIDENTIAL
CONFIDENTIAL
55
Help text can be longer than the limit allowed by a Field Value; therefore, if the flow action is going to be localized (i.e., when the Localize? box is checked), the Information box on the Form tab should not be used. Instead, on the HTML tab, reference a Rule-Obj-HTML instance.
Reference HTML should be selected from the drop-down list. The screen will then display the HTML Reference field; enter the name of the Rule-Obj-HTML instance which will be used for the Help information. This HTML rule can then contain either all the translated text for the Help file, or the references to one or more Field Values which contain the Help text.
NOTE: Since harnesses are automatically auto-generated, the Auto Generate and Omit extra spaces features are not present.
56
CONFIDENTIAL
As with flow actions, the Layout tab should be displayed in smart frames, and all uservisible labels should have a corresponding Field Value created in order to localize its text.
CONFIDENTIAL
57
For the fields on a harness, Field Values should be defined on the following grouping properties. Field Value Applies To class @baseclass @baseclass @baseclass @baseclass Field Name (grouping property) pyButtonLabel pyCaption pyActionPrompt pyCaption
Sections
Much of the localization functionality for sections is also similar to the flow action features described above. The HTML tab should have the following settings: Auto-generated HTML: enabled (checked) Localize?: enabled (checked) Omit extra spaces: enabled (checked) Generate for: JSP
58
CONFIDENTIAL
As with flow actions, the Layout tab should be displayed in smart frames, and each user-visible label should have a corresponding Field Value created in order to localize its text.
For the fields on a section, Field Values should be defined on the following grouping properties. Field Value Applies To class @baseclass @baseclass @baseclass @baseclass Field Name (grouping property) pyButtonLabel pyCaption pyActionPrompt pyCaption
CONFIDENTIAL
59
Creating Reports
In Service Pack 5, many of the standard Summary View and List View rules have been localized. Their shared localization functionality is described here; for functionality specific to the rule type, please refer to the Summary View or List View sections below. Like the work item Rules, localization begins for both View rules with a Localize? checkbox on the HTML tab. This box must be checked for localization to be enabled for the reports.
Unlike harnesses and sections, it is not possible to change the HTML in this tab it is generated HTML only. Thus, the Auto Generate HTML checkbox (and related checkboxes, like Omit extra spaces) is not necessary and does not display. NOTE: Summary View and List View rules were not converted to use JSP tags for Service Pack 5; this functionality will occur in a future release.
60
CONFIDENTIAL
For both List Views and Summary Views, the title of the report (Timeliness of top process owners) is stored in and displayed from the Full Description field on the History tab.
Summary Views
There are many label fields on the Summary View rules. Just like the section or flow action rules, once the Localize? checkbox is checked and localization is enabled, these label fields will automatically search for Field Value references. If an appropriate Field Value is not found, then the system will return the text which is in the label field.
CONFIDENTIAL
61
On both the Content and the Drill Down tabs, the labels are in Caption fields.
62
CONFIDENTIAL
The Organize tab, on the other hand, displays the captions for buttons or links on the report:
Thus, Field Values which are defined for these labels should be in the following groups:
Label type Caption (Content or Drill Down tab) Caption (Organize tab) Full Description field (History tab)
@baseclass
pyButtonLabel
@baseclass
pyMessageLabel
CONFIDENTIAL
63
List Views
List View rules have different labels than the Summary Views. On the Display Fields tab, the Field Labels contain the column headings for the list.
64
CONFIDENTIAL
There are a number of Caption fields on the Content tab, but none of these are localized, as the user doesnt see them.
NOTE: On this tab, there is a checkbox for Convert criteria values from Locale values? This checkbox does not have to do with localizing labels; instead, it allows conversions of date values for calculations. (For full details on this item, please see the On-Line Help on Completing the Content Tab.)
CONFIDENTIAL
65
The Organize tab also contains Caption fields; as with the Summary View rule, these are button labels or links.
Thus, Field Values which are defined for these labels should be in the following groups:
Label type Field Label (Display Fields tab) Caption (Organize tab) Full Description field (History tab)
@baseclass
pyButtonLabel
@baseclass
pyMessageLabel
66
CONFIDENTIAL
Correspondence
Correspondence rules include: Rule-Obj-Corr Rule-Corr-Fragment
Localizing correspondence is a completely different process than localizing the work item that a user sees. The work item is localized based on the users locale, and displays according to the person who is working on the item. However, there are two people involved in correspondence - the sender and the recipient. Therefore, using Field Values to localize the item in the language of the user who is creating the item may not be correct, as the correspondence really needs to be in the language of the person who is receiving it, so they may read and act upon the information. In this situation, once a correspondence rule is created, the localization must be done by circumstance. As the application is being created, the developer should determine when correspondence will be necessary, and enter a localization property into the work item to be used for the circumstance property (example: CustomerLanguage). After the baselanguage correspondence rule is written, that rule should be copied, and a circumstanced version of that rule should be created, based on the property which indicates in which language a customer wishes to see their correspondence. Below is an example of a base-language correspondence rule (in English), with no circumstance.
CONFIDENTIAL
67
This version of the rule has been circumstanced in French, and the text translated:
68
CONFIDENTIAL
These rules may be generated either to use industry-standard JSP tags (recommended) or to use the custom Pega directives (generate for HTML). As with the other rule localization, where labels are needed, these references must not contain hard-coded English, but must point to Field Values, where the Localized Label field provides a translation into the required language. Different code is used depending upon whether the HTML rule is generated to use JSP or custom Pega (HTML) tags.
Important: As with the generated HTML rules (described in the previous section), if there are no existing Field Values for the reference, the system will return the text label (Expand all).
CONFIDENTIAL
69
In this rule, terms such as Attach File and Upload in Progress . . . are hard-coded into the HTML display. In order to localize this rule, these labels must be changed to Field Value references. JSP tag references are recommended for Process Commander HTML rules, as they are more efficient and also easier to script. When the JSP tags are used in an HTML rule, the references are made using the pega:lookup syntax, and referring to Field Values named Attach File and Upload in Progress . . .
70
CONFIDENTIAL
There is also another field on the rule, .pyLocalizedValue, which is the value in the Localized Label field which holds the translation of the Short Description. In order for a lookup tag to find the appropriate instance in the database to retrieve, it will require all of these tags to be identified. There are two different ways that lookup can be enabled for localization. For each of these, the syntax does not specify the class name of the item; this syntax signals the system to use Rule-Obj-FieldValue as the class.
CONFIDENTIAL
71
Localization Lookup: First Variation Syntax <pega:lookup property=.aProperty /> Example: <pega:lookup property=.pyButtonLabel />
Attributes
Notes When this syntax is used to look up Field Values, there are a number of assumptions made to complete the information needed for the lookup: Class name: Rule-Obj-FieldValue Key Defined on class name: the class of the primary page present at runtime (or its ancestors, which would include @baseclass) Key Field Name: the name of the specified property (the grouping property: .pyButtonLabel) Key Field Value: the value of the specified property at runtime
In this example, the system will use the grouping property name .pyButtonLabel to look up a value. It will look up the Rule-Obj-FieldValue instance with the following information: Class Name (pyClassName) the class of the primary page (in most instances, the system will end up finding the Field Values defined on @baseclass) Field Name (pyFieldName) .pyButtonLabel Field Value (pyFieldValue) the current value of .pyButtonLabel (RemoveFromFolder)
The system would look at the current value of .pyButtonLabel, and then return the ruleresolved value stored in the .pyLocalizedValue. (This could be the German, French, or other language version of the Remove from folder phrase.) Important: For this reference to work correctly, the developer must be sure that there will be a current value of the referenced Field Value on the clipboard at execution time.
72
CONFIDENTIAL
Localization Lookup: Second Variation Syntax <pega:lookup property=somePage.aProperty value=fieldValue/> Example: <pega:lookup property=pxRequestor.pyCaption value=Engage Manager/>
Attributes
Description required the Field Name the name of the grouping property of the Field Value rule. (May include the pxRequestor page.) required the Field Value (key name) of the Rule-Obj-FieldValue rule in the system optional true/false value that determines whether or not the output will be formatted using a Rule-HTML-Property Rule.
value
formatOutput
Notes If the developer wishes to use a specific Field Value and look up its localized value, then this alternate syntax may be used. This syntax requires that a page be specified as part of the property reference, so the system may determine the class name from that page. Since the grouping property is generally just used to group the field values (as opposed to being an actual property), it may not be on an actual page in the clipboard at the time it is referenced. A page needs to be referenced which will always be on the clipboard, so the system may then search the class hierarchy and find the Field Values in @baseclass. Since the requestor page is always present for a work item, that page is frequently used as a placeholder page for the grouping property.
Additional References If the Field Values have parameter or property references defined, these references must have corresponding data in the Field Value call. Thus, if the Field Value definition for Processes for Application was: Processes for Application {1} then the lookup reference would have to include a parameter for that Field Value:
CONFIDENTIAL
73
<pega:lookup property=pxRequestor.pyCaption value=Processes for Application\tparam.StartMortgage/> As with the Field Value references in activity methods, the syntax for the parameter or property references is tab-delimited (\t).
getLocalizedTextForString
In addition to using JSP tags, there is a Java method which is also available for localizing text in HTML rules: getLocalizedTextForString. This feature allows a token to be put into the HTML rule, with a linked Rule-Obj-FieldValue instance which is localizable. getLocalizedTextForString takes two parameters - Ref and String and returns a string. string=tools.getLocalizedTextForString(page.property, Value) As explained in the previous section, the Rule-Obj-FieldValue class contains three key properties: Class Name Field Name Field Value
There is also another field on the rule, .pyLocalizedValue, which is the value in the Localized Label field which holds the translation of the Short Description. The first parameter, Ref, is the reference to the page and property name for the text string to be localized. The system derives the Class Name from the specified page & property reference, and then also uses this property reference as the Field Name. Thus, this reference must be a named page on the clipboard. Frequently, pxRequestor is used, as this is a named page which will always be present on the clipboard, but other pages (pyViewPageLocale, for example) could be used. The second parameter, String, is the actual Field Value (the key name for the Rule-ObjFieldValue instance): etc. Add New Party Export To Excel Refresh List
retrieve the value each time. If there is only going to be one reference to the text in the rule, then caching is probably not necessary. Another decision for the developer is whether to use Java or HTML code to refer to the text string. If the code in the rule is mostly Java, then that may be the most efficient way to reference the string; on the other hand, if the code is mostly HTML, it is also possible to set up the reference so that switching into Java code in the middle of the HTML is not necessary. NOTE: The examples below show how getLocalizedTextForString is used in Process Commander rules. Developers would not be changing these particular rules, but should look at these examples to determine how best to change rules in their own application, or code them properly during the application design.
Example 1: only one reference to strings This code does not include caching, as there is only one reference to the string. This HTML rule is generated for JSP. Code snippet from Rule-Obj-HTML instance Data-Gadget.myWorklistExpandContract
<% ClipboardPage reqPage = tools.getRequestor().getRequestorPage(); String userId = reqPage.getString("pyUserIdentifier"); String userServer = reqPage.getString("pxReqURI"); String SMALLLIST = "small"; String FULLLIST = "full"; String EXPANDTEXT = tools.getLocalizedTextForString("pxRequestor.pyCaption","Expand"); String CONTRACTTEXT = tools.getLocalizedTextForString("pxRequestor.pyCaption","Contract"); // Get the list size, small or full, stored on the Work pyPortalPage String strWorkListSize = SMALLLIST; ClipboardPage pgDataPortal = tools.findPage("pyPortal"); if (pgDataPortal != null) { ClipboardProperty cpPortalPages = pgDataPortal.getProperty("pyPortalPages"); for (int i = 1; i < cpPortalPages.size(); i++) { ClipboardPage pgPortalPage = cpPortalPages.getPageValue(i); if (pgPortalPage.getString("pyCaption").equalsIgnoreCase("Work")) { strWorkListSize = pgPortalPage.getString(".pyPageParams.pyWorkListSize"); break; } } } String strAnchor = (strWorkListSize.equals("full")) ? CONTRACTTEXT : EXPANDTEXT; String srcUrl = userServer + "?pyActivity=Data-Gadget.ShowWorkView&ViewClass=AssignWorklist&ViewPurpose=&ViewOwner=ALL&pyAction=Refresh&showHeader=false&UserID=" + userId + "&ViewHeader=false&glimpseMode=Scripts&workListSize=" + strWorkListSize; %>
In the above example, two strings were being localized: Expand and Contract. A local string variable was defined for each of these (EXPANDTEXT, CONTRACTTEXT), and set
CONFIDENTIAL
75
equal to the Rule-Obj-FieldValue instances for those values in the pyCaption grouping (Expand Contract), using getLocalizedTextForString.
Note that at the top and bottom of this code, the symbols <% and %> are used. These are the HTML references stating that the data enclosed between these symbols is Java code; the < symbol means that this rule has been generated for JSP tags.
Example 2: Cached values using Java This code includes caching. This HTML rule is also generated for JSP. Code snippet from Rule-Obj-HTML: Code-Pega-List.SelectFolderItem <% tools.putSaveValue("CAPTION-expand", tools.getLocalizedTextForString("pxRequestor.pyCaption","Expand"));
String footerQuery = listPage.getString(".pyExpandedQueryName"); if (footerQuery.length() > 0){ String footerCategory = listPage.getString(".pyExpandedQueryCategory"); String footerWindow = listPage.getString(".pyExpandedWindow"); // append a row containing link to a full blown query screen tools.appendString("<tr><td align=center colspan=" + headerArray.length +">"); tools.appendString("<a href=\"javascript:executeList("); tools.appendString("'" + footerQuery + "',"); tools.appendString("'" + footerCategory +"',"); // append parameters of the current list String param = listPage.getString(".pyExpandedQueryParam"); tools.appendString("'&" +param + "',"); tools.appendString("10,10,80,80,"); tools.appendString("'" + footerWindow + "');"); String strExpand = tools.getSaveValue("CAPTION-expand"); tools.appendString("\">" + strExpand + "</a>"); tools.appendString("</td></tr>"); }
In this example, the getLocalizedTextForString reference is cached: the beginning of the code uses putSaveValue. The local variable being used is CAPTION-expand; the capital letters in the grouping allow the reference to be easily found in the code. Like the first example, this code also points to the Expand Rule-Obj-FieldValue instance.
76 CONFIDENTIAL
Example 3: Cached values using HTML In addition to references in Java, references can be made directly in the HTML code. This HTML rule is generated for HTML. Code snippet from Rule-Obj-HTML: Code-Pega-List.Query_ProcessResForDisplay
<HTML> <HEAD> {JAVA} // no assigments message saveValueSet("MESSAGE-noAssignmentsFound", tools.getLocalizedTextForString("pxRequestor.pyMessageLabel","NoAssignmentsFound")); saveValueSet("CAPTION-of", tools.getLocalizedTextForString("pxRequestor.pyCaption","Of")); saveValueSet("CAPTION-expand", tools.getLocalizedTextForString("pxRequestor.pyCaption","Expand")); {/JAVA}
<table width="100%"> {when {%Integer.parseInt(saveValueGet("QueryResultsCount")) > 10 %}} <tr> <td style="width:100%;text-align:center"> <a href='javascript:showUserWorkList("{pxRequestor.pyUserIdentifier}")' >10 {$save(CAPTION-of)} {$save(QueryResultsCount)} - {$save(CAPTION-expand)}<a></td> </tr> {elsewhen {% Integer.parseInt(saveValueGet("QueryResultsCount")) > 0%}} <tr> <td style="width:100%;text-align:center"> <a href='javascript:showUserWorkList("{pxRequestor.pyUserIdentifier}")' >{$save(QueryResultsCount)} {$save(CAPTION-of)} {$save(QueryResultsCount)} {$save(CAPTION-expand)}<a></td> </tr> {else} <tr> <td style="width:100%;text-align:center">{$save(MESSAGEnoAssignmentsFound)}</td> </tr>
In this example, the getLocalizedTextForString references are saved into a cache using saveValueSet in a Java section at the top of the code. However, in the code itself, the reference to the string uses $SAVE. This designation can be used when writing directly in HTML, so the developer doesnt have to drop into Java code (to use the tools.getSaveValue method). If the rule has been generated for JSP tags, the pega:save and pega:getSaved tags can be used. (See the JSP Stream Support tech note for further details.) For full details on using the getLocalizedTextForString Java method, please reference the Process Commander Public Javadocs.
CONFIDENTIAL
77
78
CONFIDENTIAL
In the above example, the Field Value Computer Monitor was defined on the new grouping property Products.
lookup example
In an HTML rule which is generated for JSP, the pega:lookup syntax could be used: <pega:lookup property=pxRequestor.Products value=Computer Monitor/>
getLocalizedTextForString example
This new Field Value reference could also be used with getLocalizedTextForString: tools.putSaveValue("PRODUCTS-monitors", tools.getLocalizedTextForString("pxRequestor.Products","Computer Monitor"));
CONFIDENTIAL
79
Localizing Properties
Localizing Properties
Properties can have different types in the PegaRULES system. Localizing requires different processes based on the property type.
Number-Formatted Properties
The following property types use the default display mechanism: date time of day Date/Time integer number decimal double
Clicking the Demo button in the Set Locale tool displays all property types that will be automatically changed by changing the Locale:
80
CONFIDENTIAL
Localizing Properties
In the example above, although the current browser settings are set to en_US (Default Locale), the Selected Locale has been changed to French (fr_FR). Once the locale has been changed (either through the browser or by using the Set Locale tool), all properties of the above types should automatically display data in the correct format for the locale when either the default Rule-HTML-Property instance or no RuleHTML-Property instance is associated with the property (in the HTML Property field). For example, a DateTime property with no HTML Property specified would display in the default format, which maps to the MEDIUM format: Jan 19, 2004 7:00:00 p.m. If another format is desired, however, the following Rule-HTML-Property instances are available: DateTime-Full DateTime-Full-i18n DateTime-Long DateTime-Long i18n DateTime-Medium
CONFIDENTIAL 81
Localizing Properties
Examples of these Short, Medium, Long, and Full DateTime formats are displayed in the demo screen (previous page).
i18n HTML Property values Each HTML Property entry also has a duplicate value that ends in i18n (see above). These are available if an application needs to pass in a specific locale as a parameter for some reason (for example, in activities), but does not want to change the default locale. For example, a customer may have transactions that occur in Germany, which as part of their processing, must be sent to the US for approval and then sent back. The default locale will stay as Deutsch, but this specific approval activity may want to display the DateTime (and other information) as US English. In this case, the properties involved would use the i18n version of the Rule-HTMLProperty value for the HTML Property field. Then the appropriate formatting will be used for the default locale, but the Rule-HTML-Property instance will accept the specific locale parameter and use that formatting for a different locale passed in as a parameter. If the base (non-i18n) version of the Rule-HTML-Property instance is used, then both the default locale values and the specified locale values would appear in the format of the default locale. Thus:
When the system will only use locale information from the browser (the default locale), the standard Rule-HTML-Property instance should be used. When there will be another locale specified in processing, but the default locale should not be changed, the i18n version of the Rule-HTML-Property should be used.
82
CONFIDENTIAL
Localizing Properties
Text Properties
Properties may be defined so that a drop-down list of choices is displayed to the user for setting a property value. When creating the property, the developer should choose a Table Edit type on the Table Edit tab to populate this list: Local List Field Value Class Key Value Remote List Prompt List
The values specified in the property are displayed to the user through a drop-down list, which is created by entering one of the below Rule-HTML-Property instances into the HTML Property field on the Definition tab of the property: PromptSelect PromptFieldValue
NOTE: In Process Commander Version 4.1, an HTML Property called GetLocalizedValue was created. This HTML Property is no longer used in Version 4.2.
CONFIDENTIAL
83
Localizing Properties
For each choice in the list, both the values and their labels are defined in this property. In order to localize these Prompt Values, the developer must copy this property into each localized RuleSet and then translate the Prompt Values in the property itself. The Standard Value column would remain in the base language (usually English), while the Prompt Value column would be translated. NOTE: No Field Values are involved in localizing this property. As with the other localization functionality, this process will only localize the captions or the labels which the user sees, not the actual value itself that the user may choose. The values for these options (the Standard Value) will still be stored on the clipboard in English, so that any processing done using the values will continue to be valid.
This property simply has values which would be displayed to the user. This type of Table Edit uses the HTML Property PromptSelect to create the drop-down box. Since there is only one list of values, the Table Values are used both as labels and as values. This can cause a problem when localizing the application. If these values are used in processing, then they cannot be localized. For example, if there were conditional code based on these values (When .pySuggestionType = phonetic then . . .) or if the values were themselves part of processing (Set .pyPrinting = .pySuggestionType), then changing the names of these Table Values could cause errors.
84
CONFIDENTIAL
Localizing Properties
In these cases, it is necessary to redefine the property in order to localize it. The property must be changed from a Local List to a Prompt List, so the labels may be localized. If the Table Values are not used in processing (example: they are titles, such as Mr., Mrs., Dr., which should be translated into the local language), then this property may be localized. As with the Prompt List property, just copy the property into the localized RuleSet, and then translate the Table Values in the Local List. Again, no Field Values are used for localization.
For properties which are defined using Field Values as their Table Edit, the HTML Property PromptFieldValue was created.
CONFIDENTIAL
85
Localizing Properties
The developer would specify PromptFieldValue in the HTML Property field of the property. The developer must then save the existing Field Values (assumed to be in the base application RuleSet) into each localized RuleSet, and translate the text. This HTML Property has been updated to use the localized Field Values. Instead of using the Short Description of the Field Value in the base RuleSet, the system will generate a localized drop-down box by displaying the values from the Localized Label fields of the localized Field Values.
86
CONFIDENTIAL