PRPC V4.2 SP5 and V5.1, Localizing an Application (Full Guide)

Localizing an Application

PegaRULES Process Commander

© Copyright 2006 Pegasystems Inc., Cambridge, MA

All rights reserved.

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 Commander’s architecture is designed to provide multi-language 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 user’s 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 1

Overview

Unicode Support Details Version 4 of Process Commander supports the Unicode standard, which accommodates handling, importing, and exporting character sets beyond the Roman character set (ASCII). “Unicode” is actually a general term encompassing many aspects of different character sets. UTF-8 is a one- to four-byte encoding of Unicode, and is used by PegaRULES when writing output or HTTP on the file system. UTF-16 is a two-byte form of Unicode. Process Commander runs in the Java Virtual Machine (JVM); by default, the JVM strings are UTF-16. Process Commander uses standard JDBC interfaces to integrate with the PegaRULES database. As long as the database supports Unicode, the JDBC drivers (which run as part of the JVM) should take care of the data transformation from UTF-16 to whatever data type the database expects. Thus, Process Commander supports whatever the customer database and their chosen JDBC drivers support, including both UTF-8 and UTF-16. Important: For most non-localized Release 4.2 installations using Microsoft SQL Server, the following setting is included, either in the JDBC URL or the DataSource setting: SendStringParametersAsUnicode=false The SendStringParameters setting controls whether the data sent to the database is translated into Unicode or not. When using a Unicode database with a localized version of Process Commander, this setting must be deleted. (If the database is not Unicode, then having this setting greatly improves system performance, as the system does not unnecessarily change all the data to a Unicode format for storage.)

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, non-

existent 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 IBM’s 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 3

Overview

4 CONFIDENTIAL

Enabling Localization in PegaRULES

Setting the Locale The first step in localization is to set the locale for each user to their preferred language/country setting and to insure that the client is properly configured for that language. As PegaRULES localization applies to the user experience, the locale configuration is done on each user’s machine (not on the server). There are several ways this can be done:

• Client-side settings in the browser • Operator ID rule • The Set Locale tool • Application-specific user interface using PegaRULES APIs

Client-side Settings Setting the locale in the user’s 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 browser’s 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 5

Setting the Locale

At the bottom of this screen, click on Languages.

The language that is displayed at the top of the Preference list is the default language that will be used for the Locale setting.

6 CONFIDENTIAL

Setting the Locale

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 “fr-FR” rather than just “fr.”

CONFIDENTIAL 7

Setting the Locale

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 locale-specific RuleSet List is refreshed (see the Localized RuleSets section), and the new locale’s 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 one’s 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

Setting the Locale

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 Microsoft’s instructions and conventions. In general (when using IE6), appropriate fonts can’t 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 user’s 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

CONFIDENTIAL 9

Setting the Locale

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

Setting the Locale

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

Setting the Locale

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 client’s 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/ (Netscape’s 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

ftp://ftp.netscape.com/pub/communicator/extras/fonts/windows/

http://babel.uoregon.edu/yamada/fonts.html

Setting the Locale

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

Setting the Locale

Locale

It is also possible to set a user’s 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.)

Set Locale tool Users may wish to view Process Commander in a specific language that may not be their default (due to the work they are processing), or they may wish to reset Process Commander temporarily to work with a particular customer or company. In this case, the default locale within PegaRULES may be changed by using the Set Locale button, which is located as an option at the bottom of the Tools window:

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

Setting the Locale

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

Setting the Locale

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

Setting the Locale

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

Setting the Locale

In the example above, although the Browser settings are set to en_US, the Locale has been changed to French (fr_FR).

Application-specific user interface Depending upon the access provided, end-users may not see the Set Locale button from the Tools menu. The developer may wish to provide the application’s end-users with a custom button (or buttons) to change their locale for different customers, or provide some other functionality. It is possible to change the Locale by creating an application-specific user interface using PegaRULES APIs. The Locale may be changed programmatically, by calling the setLocale Java API (method in Interface PRThread) from a Java step. (This is the basis for the functionality of the Set Locale tool.) This provides the ability for a developer to define their own user interface – for example, they could create links on a form, which when clicked, will run an activity to change the Locale. For more information on PegaRULES Java APIs, please refer to the PegaRULES V4 javadocs.

18 CONFIDENTIAL

RuleSets and Localization

RuleSets and Localization Beginning with Release 4.1, PegaRULES Process Commander supports international languages and characters, as well as dynamic switching between these languages (for example, changing from French to German without having to restart the PegaRULES server). This functionality requires the creation of international RuleSets for both Process Commander and the customer’s application, to “localize” the PegaRULES system to the user’s area. Important note: RuleSets for international language/variant combinations are not shipped as a standard option with PegaRULES Process Commander. Should a customer require a localized version of Process Commander, they must request the appropriate Language Pack from Pegasystems (see section below on Language Packs). Following the ISO standards for identifying locales, the name of a localized RuleSet consists of up to three parts, separated by underscores: 1. Language 2. Country 3. Variant Thus, if the language is French, the country is Luxembourg, and the variant is Pre-Euro, the RuleSet for the Acme Company’s application would be: AcmeCo_fr_LU_PREEURO If the language is Hindi, and the country is India, the RuleSet would be: AcmeCo_hi_IN For each RuleSet in a user’s profile, RuleSets can be included that reflect each level of localization, in descending order of specificity: AcmeCo_fr_LU_PREEURO:04-02 AcmeCo_fr_LU:04-02 AcmeCo_fr:04-02 AcmeCo:04-02 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


Localizing Process Commander RuleSets: Language Packs In addition to localizing the rules in an application, some rules in Process Commander must be localized. These rules, including the majority of the visible links on the Portal, along with a number of rules which are used by most applications, are stored in locked Pega- RuleSets (Pega-ProCom, Pega-WB). These Pega- RuleSet rules are not available for application developers to edit, but have been localized by Pegasystems. Beginning with Service Pack 5, all the labels for Portal layout, the Gadgets on the portal, the standard reports included with the base Process Commander application, and many of the small translations required for an application (messages, button text, etc.) have been created as Field Values (instances of Rule-Obj-FieldValue) which can be localized. All of these Field Value rules are stored in the Pega-ProCom and the Pega-WB RuleSets. From these Field Value rules, Pegasystems has developed Language Packs to facilitate localization. Language Packs are translated instances of the Process Commander Field Values, provided in localized RuleSets. For example, for French, the Language Pack includes Field Values in the following RuleSets:

• Pega-ProCom_fr • Pega-WB_fr

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-02Pega-WB:04-02

Pega-RULES:04-02

20 CONFIDENTIAL


Localizing Application RuleSets For each RuleSet that is used in the application, the developer must create a RuleSet in the locale (or locales) for each language. Example: RulePro application for Acme Corp. RuleSets required for this application: AcmeSubscription: 01-01 AcmeProducts:03-02 AcmeRulePro:04-01 AcmeBase:04-02 Acme Corp in France – French: Localized RuleSets created by the developer: AcmeSubscription_fr_FR: 01-01 AcmeSubscription_fr: 01-01 AcmeProducts_fr_FR:03-02 AcmeProducts_fr:03-02 AcmeRulePro_fr_FR:04-01 AcmeRulePro_fr:04-01 AcmeBase_fr_FR:04-02 AcmeBase_fr:04-02 Final RuleSet: AcmeSubscription_fr_FR: 01-01 AcmeSubscription_fr: 01-01 AcmeSubscription: 01-01 AcmeProducts_fr_FR:03-02 AcmeProducts_fr:03-02 AcmeProducts:03-02 AcmeRulePro_fr_FR:04-01 AcmeRulePro_fr:04-01 AcmeRulePro:04-01 AcmeBase_fr_FR: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

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


Assembling Localized RuleSet Lists When a user first logs into the PegaRULES system, a requestor is created for that user, with the permissions that have been allocated to that user. Most requestors end up being type BROWSER (standard interactive user); when a BROWSER requestor is created, the RuleSet List instances for BROWSER are read out of the Data-Admin-Requestor record and given to the requestor’s authentication object, which then adds the localization RuleSets (as described in the previous section). As the user’s Profile of RuleSets is assembled, each time a base RuleSet is added to the list, the system tests to see if a Rule-RuleSet-Name instance for a localized version of that RuleSet is defined in the database. If it is, the existing localized variants of that RuleSet are inserted automatically before the base RuleSet. When the user’s Organization, Division, or Access Group RuleSets are added, the localization RuleSets are included automatically as well. When the RuleSets are fully assembled, each requestor will have two RuleSet Lists associated with it: the basic RuleSet List (which appears in the user’s Profile), and the localized RuleSet List, which is associated with the requestor itself on the Clipboard.

Important Notes about Localized RuleSets

• When changing the Locale, it is not possible to switch out individual RuleSets – the entire list of PegaRULES Process Commander rules will be swapped.

• The base RuleSets for PegaRULES Process Commander are in US English (by

design), as well as the developer environment. If a company is developing a multilingual application for locales other than en_US, it is suggested that the base application RuleSets also be in US English, even though that may not be the preferred language for the customer. Since the customer will be building several localized RuleSets, and as the PegaRULES RuleSets are all in US English, having the application RuleSets in US English also will provide consistency across the product. For example, if a French company (“La Paniere”) creates an application, their base RuleSet would be in English (PaniereCo: 01-01), and their Rules would be stored in their localized RuleSet (PaniereCo_fr_FR:01-01).

• The system tests each possible localization against the Rule-RuleSet-Name (for

the base RuleSet) only – not against any Rule-RuleSet-Versions. Once it has determined the appropriate name for the RuleSet (by taking the existing base RuleSet and adding the appropriate localization designation), it will search for the RuleSet and Version which match the existing base RuleSet and Version. For example, if a valid base RuleSet exists with a current version (“AcmeProducts:04-02”), the system will look for the localized version of that RuleSet (“AcmeProducts_fr:04-02”). If that RuleSet and Version don’t exist, standard Rule Resolution rules will apply: other RuleSets and Versions within the major version (“AcmeProducts_fr:04-01” or “AcmeProducts_fr:04-02-10”) can be used, but RuleSets and Versions outside the major version (“AcmeProducts_fr:03-05”) cannot.

Developers must therefore be careful when naming application RuleSets. If the application base RuleSet is version 04-02, do not create a localized version of that RuleSet and start the version numbering again at 01-01 (since it’s a new version of the RuleSet). The localized RuleSet version (“AcmeProducts_fr:03-02”) must match the base version (“AcmeProducts:03-02”).

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.

Displaying Localized RuleSets As stated above, the localized RuleSets will not be displayed in a user’s profile, which will continue to show only the base RuleSets:

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


Developing with Localized RuleSets Unlike users, developers who are localizing an application will need to see the localization RuleSets in their Profile, as they will be saving existing Rules into the localized RuleSets.

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

Building a Localized Application Localizing the user experience for PegaRULES Process Commander can be divided into two main parts:

• the application (Work Items) • Process Commander (the Portal, standard reports)

The Portals for Work Users and Work Managers are localized in the Language Packs, along with the standard manager’s 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.

Localization Building Blocks: Field Values Localization in Process Commander is done by creating Field Value records for all labels that a user or manager would see. For each of the application rules requiring localization, the labels must be translated. These rules include:

• Harnesses • Sections • Flow Actions • Flows

CONFIDENTIAL 27

Localization Building Blocks: Field Values

Below is an example section:

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 Description Applies To

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.

Field Value Groupings The Language Packs contain nearly 1800 Field Values. In order to be able to find an appropriate Field Value, or to ascertain whether one with the same or a similar name has been created, “groupings” have been created. Unlike their original use, the Field Values

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: “Grouping” property

Available “Applies To” classes

Usage

pyActionPrompt

@baseclass

tooltips, text that tells the user what action to take

pyButtonLabel

@baseclass

buttons, URLs, “clickable” items

pyCaption

@baseclass, Work-

labels, headers, fieldsets, etc.

pyConfirmationNote

Work-

Confirmation Notes (flows only)

pyCountry

Data-Party

names of all countries

pyCountryCode

@baseclass

codes for all the countries

pyHistoryMemo

Work-

history messages, Audit Notes (flows)

pyInstructions

@baseclass

Instructions (flows only)

pyMessageLabel

@baseclass

alerts, error messages, help

pyStatusWork

Work-

the status of the work item (flows only)

pyStatusLabel

@baseclass

the status of the Assignments, and also information from the process the system is completing (creating, saving, deleting)

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.

Naming Field Values As stated above, the Field Value key name can contain up to 64 characters, and may also contain spaces. This is to facilitate creating Field Value names that are easily understandable when viewed in a list. Depending upon where in the system the label is located, as well as its length, the Field Value key name could either be a reference or a text string. For example, if on a Section, the label to be localized is “Operator ID”, then the Field Value can be created with a key name of Operator ID. If there is an existing section with that label, no actual change is needed to the section rule itself; only the Operator ID Field Value needs to be created. On the other hand, if there is an Instruction that says something like, “Please review this open work item and determine whether it is valid; if it is valid, then send to your manager for approval,” that is too long a name for the actual Field Value. In this case, the Field Value key name might be something like, “ValidItemManagerApproval”, and the full text would be in the Short Description field. In this case, the key name then must be entered into the Instructions field (instead of the long text message) for localization lookup (when users are working with the system). The longer text message for the Field Value is stored in both the Short Description field and the Localized Label field. The Short Description field has a limit of 255 characters, which is also the recommended limit for the Localized Label field. Thus, the developer must take care to be sure that not only the Short Description but also the translated label must be able to fit within 255 characters – if the English message is just at 255 characters, translating it into another language might require truncating or rewording.

Field Value Processing For all label fields for which localization is enabled, the lookup functionality is as follows: 1. The system checks to see if there is a Field Value with a key name (the Field Value field) which matches the text in the label field. 2. If a Field Value with a matching key name is found in a localized application RuleSet or in the localized Pega- RuleSets, the system will use the (translated) label in the Localized Label field of that Field Value.

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).1 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.

Valid Field Value Entries Beginning in Version 4.2 Service Pack 5, the Field Value rule has been enhanced to enable use of both property references and parameter references. For each of these references, a specific “tab delimiter” syntax must be used in order for the property or parameter substitution to take place. This syntax includes the Field Value key name, the tab delimiter (“\t”), and then the list of references, separated by additional tab delimiters. (See examples below.) Note that in the Localized Label field, the text for the message must be arranged so that it makes sense in the translated language. The message in English might read (for example) : “Entered by <operatorID> at <timestamp>.” 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:

The Message Key reference for this Field Value is as follows: "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.

Using Field Value References in Activity Methods Beginning with Service Pack 5, there are several activity methods that have been enhanced to use the new Field Value functionality:

• Property-Set-Messages • Page-Set-Messages • History-Add

Property-Set-Messages and Page-Set-Messages

These two methods will save a message to the specified item:

• Property-Set-Messages will save a message to the specified property (the Field value)

• Page-Set-Messages will save a message to the specified page (the Page value)

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 Value Message

“FailedAddToFolder\t” + pxThread.pxMethodStatus

Field

.pyFolderID

Category

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 user’s 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.

The Audit Note Field

The Audit Note field, which is found on some properties in flows, has the same functionality as described above in the Field Values section of this document; this field will accept both parameters and property references.

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.

The History-Add Method

The History-Add method contains a number of parameters, as shown in the table below.

Parameter Description of Value ForOperatorID

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.

HistoryModel

for future functionality

HistoryMemo

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.

RuleAction

for future functionality

Category*

This field contains the name of the “grouping property” which should be used to identify the history message. This field defaults to .pyHistoryMemo.

42 CONFIDENTIAL


MessageKey*

This field contains the Field Value key name (the Field Value data). This field can also contain any tab-delimited 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 name-value 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

Creating the Application


Overview When creating an application that will be localized, it is vital to keep localization functionality in mind when designing the work item processes (flows, flow actions), and the work item itself (harnesses and sections). Recommended practice for a developer who is creating an application to be localized would be to write the application itself, creating the necessary Field Values as the other Rules are created, and then, after the application is mostly complete, create the localized RuleSets and translate the appropriate Field Values. Currently, in Release 4.2 of PegaRULES Process Commander, the Rule forms themselves cannot be localized. In addition, any error messages generated by the base PegaRULES engine will continue to be displayed in US English for the Service Pack 5 release. However, most parts of the product that the end user will see can be localized. Important: In Service Pack 5, the Application Accelerator does not yet have full localization functionality. If a company begins their development with the Application Accelerator, it will be necessary to go in to the Accelerator-created rules and check the Localize? checkbox on the HTML rules. (See the following sections for details.) After the application has been designed and created with localization in mind, the high-level steps in the localization process include: 1. Obtain and install the appropriate Language Pack 2. Create the localized RuleSet(s) for the application 3. Determine which rules require localization in the application. These include: a. harnesses b. sections c. flow actions d. flows e. any other rules which contain labels or messages to the user (such as activities, which might contain a History entry) 4. Determine the labels on these rules which need localization 5. Verify that the Field Values for these rules have been created in the base language RuleSet (and create any that are missing) 6. For harnesses, sections, and flow actions, enable localization on the rule forms 7. Save the Field Values into each localized application RuleSet 8. Translate the Field Values into the appropriate language for each RuleSet Details of the rule localization steps are contained in the following sections.

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”:

Properties Field

Field Value Definitions: Applies To class

Field Name (group)

Audit Note

Work-

pyHistoryMemo

Confirmation Note

Work-

pyConfirmationNote

Instructions

@baseclass

pyInstructions

StatusWork

Work-

pyStatusWork

StatusAssign

@baseclass

pyStatusLabel

Creating Flow Actions The flow action rules are all displayed in the Take Action drop-down menu, where the user chooses an action for the work item. Some of these may be custom-created by the developer, or the developer may use the standard ones provided with Process Commander.

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. Setting Description Localization value Auto Generated HTML

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 shouldn’t be overwritten with generated HTML.

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


Setting Description Localization value Generate for JSP

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.

generate for JSP Almost all flow actions from Service Pack 5 have already been generated for JSP.

Localize?

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.

checked (enabled) Localization is dependent upon the system looking up all the Field Values

Omit extra spaces?

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.)

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.” Label type

Usage

Field Value Applies To class

Field Name (grouping property)

Action Instructions caption

Instructions (the tooltip info at the bottom of the screen)

@baseclass

pyMessageLabel

Caption

buttons, URLs

@baseclass

pyButtonLabel

Label

Short Description

@baseclass

pyCaption

Title

header, tabs

@baseclass

pyCaption

Tooltips

button, URL, icon

@baseclass

pyActionPrompt

Value

labels

@baseclass

pyCaption

Flow Action Help

It is possible to create custom Help text for each particular flow action. This text is entered into the Information box at the bottom of the Form tab, and then linked to the Help generation section of the HTML tab. If Define Help is chosen, the text will be automatically generated into HTML code in the Help Source box.

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.

Creating the Work Items Harnesses

Much of the localization functionality for harnesses is similar to the flow action features described above. The HTML tab should have the following settings:

• Generate for: JSP • Localize?: enabled (checked)

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 user-visible 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.” Label type

Usage



Caption

buttons, URLs

@baseclass

pyButtonLabel

Title

header, tabs

@baseclass

pyCaption

Tooltips

button, URL, icon

@baseclass

pyActionPrompt

Value

labels

@baseclass

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.” Label type

Usage



Caption

buttons, URLs

@baseclass

pyButtonLabel

Title

header, tabs

@baseclass

pyCaption

Tooltips

button, URL, icon

@baseclass

pyActionPrompt

Value

labels

@baseclass

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.

This field is localized using the pyMessageLabel grouping.

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

Usage



Caption (Content or Drill Down tab)

report labels

@baseclass

pyCaption

Caption (Organize tab)

button or link captions

@baseclass

pyButtonLabel

Full Description field (History tab)

report title

@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 doesn’t 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

Usage



Field Label (Display Fields tab)

Column headings

@baseclass

pyCaption

Caption (Organize tab)

button or link captions

@baseclass

pyButtonLabel

Full Description field (History tab)

report title

@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 user’s 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 base-language 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

Using Custom Code in a Localized Application

Process Commander Best Practice states that all applications should be written using the tools provided in the Process Commander software. The developer should create standard rules, and not write a lot of customer Java or HTML code, as that is more difficult to maintain and change. If a developer does choose to use custom code, there are special localization features which should be employed, to make sure that this custom code is still localizable.

Localization References in HTML Code As stated in the previous sections, the generated HTML rules (such as harnesses and sections) have had localization functionality added in Service Pack 5. There are other HTML rules where the code is not automatically generated, but the HTML is written directly in the rule. These include:

• Rule-Obj-HTML • Rule-HTML-Fragment • Rule-HTML-Property

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

Localization References in HTML Code

JSP lookup tag The ActionAddAttachment2 rule provides an example of hard-coded English in an HTML rule.

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


Using the pega:lookup localization feature

All localized values for the lookup tags are stored as Rule-Obj-FieldValue instances. As stated previously, the Rule-Obj-FieldValue class contains three key properties:

• Class Name (pyClassName) – the class the Field Value is defined on • Field Name (pyFieldName) – the name of the property the Field Value is defined

on (in localization, the name of the “grouping property”) • Field Value (pyFieldValue) – the actual key name of the 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 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

Attribute Name Description property

required the class name of the property in the database

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 rule-resolved 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

Attribute Name Description property

required the Field Name – the name of the “grouping” property of the Field Value rule. (May include the “pxRequestor” page.)

value

required the Field Value (key name) of the Rule-Obj-FieldValue rule in the system

formatOutput

optional true/false value that determines whether or not the output will be formatted using a Rule-HTML-Property Rule.

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-Obj-FieldValue instance):

• Add New Party • Export To Excel • Refresh List

etc.

Referencing getLocalizedTextForString in HTML Properties

Once the Field Values have been created, they may be referenced by getLocalizedTextForString in HTML rules. These references may be set up in hundreds of ways (as most references can be). The first decision the developer must make when determining how to reference getLocalizedTextForString is whether to cache the information or not. If the string text is going to be referenced several times in the rule, then it is more efficient to cache that information locally and retrieve it from the cache, rather than going out to the database to

74 CONFIDENTIAL


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=Assign-Worklist&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(MESSAGE-noAssignmentsFound)}</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 doesn’t 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

Creating New Field Value Groups

Creating New Field Value Groups As stated in the Field Values section of this document, there are a number of “grouping” properties that are defined in Service Pack 5, including pyActionPrompt, pyButtonLabel, pyCaption, etc. These are the values which must be used when creating new localization Field Values for harnesses, sections, and other rules where the HTML code is automatically generated. However, if the customer wishes to create their own custom HTML rules, it is also possible that they could create some additional “grouping” properties to reference in these rules. Pegasystems recommends not creating too many, or the capability to find one particular Field Value quickly will be lost. (Creating 100 groups for 100 Field Values will not aid a customer to find a particular Field Value.) There are three steps to creating and using a new Field Value group:

• create the new “grouping” property • define Field Values on this property • specify these Field Values in custom HTML

Create the Property The first step in creating a new Field Value group is to create the grouping property. This property should be defined on a class which is at the most general level possible in the hierarchy, in order to allow the Field Values in this group to be used by the widest possible number of classes (i.e., to promote reuse). Most of the grouping properties shipped with Process Commander are defined on @baseclass; some are defined on Work-. The property should be a Single Value property, of type Identifier.

78 CONFIDENTIAL

Creating New Field Value Groups

Define Field Values Once the new grouping property is created, define the appropriate Field Values on this property. For example, the customer might create a new grouping property called Products, and then define localization Field Values on that property.

In the above example, the Field Value Computer Monitor was defined on the new grouping property Products.

Use in custom HTML After the Field Values have been defined on the new grouping property, they can be referenced in custom HTML rules. These references could be either a lookup reference, or a getLocalizedTextForString reference.

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


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 Rule-HTML-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


DateTime-Medium – i18n DateTime-Short DateTime-Short – i18n

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-HTML-Property 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


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.

Localizing Prompt List Properties

A Prompt List Table Edit shows a list of values, and then displays the labels the user would see for those values (the “prompts”).

CONFIDENTIAL 83


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.

Localizing Local List Properties

Other properties may have a Local List type of Table:

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


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.

Localizing Field Value Properties with PromptFieldValue

As stated in the Field Values section of this document, originally the Field Value rules were used to create a drop-down list of values to choose for a particular property. If there were a large list of values which were expected to change frequently (for example, a list of countries of the world), then rather than typing them all into a Local List or a Prompt List in the property and having to continually update this list, they could be created as Field Values (which would allow for more modular updating).

For properties which are defined using Field Values as their Table Edit, the HTML Property PromptFieldValue was created.

CONFIDENTIAL 85


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

Date post:	04-Jan-2017
Category:	Documents
Upload:	lamduong
View:	239 times
Download:	3 times

PRPC V4.2 SP5 and V5.1, Localizing an Application (Full Guide)

Documents