localization 0402

8/2/2019 Localization 0402

1/92

Localizing an Application

PegaRULES Process Commander


2/92

Copyright 2006Pegasystems 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 StreetCambridge, MA 02142-1590

Phone: (617) 374-9600Fax: (617) 374-9620www.pega.com

PegaRULES Process CommanderDocument: Localizing an ApplicationSoftware Version 4.2 SP5 and 5.1Updated: August 23, 2006


3/92

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


4/92

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 lookuptag........................................................................................... 70

Using the pega:lookup localization feature......................................... 71


5/92

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


6/92


7/92

Introduction

Overview

For companies which need to incorporate multi-language support in their BPM/BREsolutions, PegaRULES Process Commanders 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 userand the customer, which is useful in customer service settings. Thus, multi-lingual usersthat handle calls from multi-lingual customers can optionally see structural information intheir preferred language, while seeing scripts, descriptions, and correspondence as thecustomer would see them. The rules architecture seamlessly integrates elements basedon user preferences and the language of the current customer.

Although the core development environment is based in English, beginning in Version 4.2Service Pack 5, PegaRULES has the ability to present users with forms and ruletranslations in their preferred language. The default English presentation may beoverridden with the users choice of language in the following key areas:

Application screens, fields, reports, and some error messages

Customer correspondence templates

User interface for workers and managers

Note that only the user interface functionality is being localized. The PegaRULESlocalization technology is an aidto customers who wish to translate their application; it isnot 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 wouldsee 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 willmake localization and maintenance of the application much easier and moreefficient.

CONFIDENTIAL 1


8/92

Overview

Unicode Support Details

Version 4 of Process Commander supports the Unicode standard, which accommodateshandling, importing, and exporting character sets beyond the Roman character set(ASCII).

Unicode is actually a general term encompassing many aspects of different charactersets. UTF-8 is a one- to four-byte encoding of Unicode, and is used by PegaRULESwhen 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 stringsare UTF-16.

Process Commander uses standard JDBC interfaces to integrate with the PegaRULESdatabase. As long as the database supports Unicode, the JDBC drivers (which run aspart of the JVM) should take care of the data transformation from UTF-16 to whatever datatype the database expects. Thus, Process Commander supports whatever the customerdatabase 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 istranslated into Unicode or not. When using a Unicode database with a localized version ofProcess Commander, this setting must be deleted. (If the database is notUnicode, thenhaving this setting greatly improves system performance, as the system does notunnecessarily change all the data to a Unicode format for storage.)

Prerequisites

Companies which are writing Process Commander applications which will belocalized must have Version 4.2, Service Pack 5 or a later release (whichincludes Version 5.1).

The reader of this document must be familiar with rules and other structuresrequired for the development of applications in Process Commander, and mustbe skilled in development of these applications.

VITAL: Companies doing localization must have set up their database to handleUnicode, both in the Stream (BLOB) column and in all the exposed columns. Ifthe existing database does not have Unicode on all the columns, the databasemust be changed. For some databases, this may require reinstalling the

database software (and then reinstalling any other software - such as applicationservers - that require being installed after the database software.

Assumptions

This tech note is a description of how to enable localization features in ProcessCommander, and is intended for application developers who are very familiar with writingapplications in PegaRULES. This document is nota description of how a company should

2 CONFIDENTIAL


9/92

Overview

approach localizing their application. It is assumed that the developer has a solidunderstanding of globalization concepts, and has designed their application accordingly.

For example, common fields must be designed by the application developer to acceptdata 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() is highly recommendedfor an overview of globalization.

This tech note also references IBMs International Components for Unicode (ICU)technology, which is exploited by PegaRULES to facilitate globalization. Please seehttp://www.ibm.com/software/globalization/icu for further details.

In this technical note, references may be made to user, developer, and customer. It isassumed that the developerwill be writing an application for their company, and that thisapplication will aid interactions between usersof the application at that company andcustomersof that company. For example, the developermay write a financial applicationinvolving a mortgage loan process for a bank; the userwould use this application to opena mortgage for a customerof the bank.

CONFIDENTIAL 3


10/92

Overview

4 CONFIDENTIAL


11/92

Enabling Localization in PegaRULES

Setting the Locale

The first step in localization is to set the locale for each user to their preferredlanguage/country setting and to insure that the client is properly configured for thatlanguage. As PegaRULES localization applies to the userexperience, the localeconfiguration is done on each users 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 users browser is a permanent way to enable a particularlanguage for that user. Every time the user starts Process Commander, that language willbe the default.

There are two parts to setting a language/country on a client machine:

browser support (to set the locale) font support (to be able to display the chosen language properly)

Browser Support

The default locale for a PegaRULES user is based on the browsers locale settings(language settings). Once the appropriate fonts are installed onto the client-side PC, thebrowser 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


12/92

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 thatwill be used for the Locale setting.

6 CONFIDENTIAL


13/92

Setting the Locale

To add a new language, click on the Add button and choose the new language from theavailable list.

It is also possible to add your own language in the User defined field. NOTE: Localesentered in the User defined field should be in the language-countryformat (using a dash)and not in language_countryformat (using an underscore) that is accepted by Java. (Forexample, Hindi should be added in the browser as hi-in and not hi_in.) Also, InternetExplorer will not validate whether a valid locale is entered it is necessary to know theappropriate locale designation beforehand.

NOTE: Internet Explorer has a number of language (or locale) choices that consist ofonly a language (not the country or variant see the Localized RuleSetssection of thisdocument). However, PegaRULES uses the country component of the locale designationto determine how to display dates and numbers, which are attributes of locale that vary bycountry, not just language. Better results will be obtained by choosing a designation of fr-FR rather than just fr.

CONFIDENTIAL 7


14/92

Setting the Locale

Important: Once the new language has been added to the Preferences screen, it mustbe 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 willmove 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 newlocales 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 thatusers avoid changing locales in the midst of processing a single work item.Unexpected behavior or erroneous data interpretation can occur if locale is changed whenones forms are displayed. (For example, a form containing dates formatted for a Hindilocale cannot be interpreted in an English locale. The calendar pop-ups are prone to thisissue.) Complete the processing of a given form, and thenchange the locale and beginprocessing in the new locale.

Important Note: The changes made to the browser will persist. If the user closesPegaRULES and exits the browser, and then later starts the browser again, the defaultlocale will remain as it was set.

Font Support

If a web page is displayed that includes characters for which suitable fonts are notinstalled, some of the characters may display as little boxes (or as question marks orother glyphs on an XP system) instead of the appropriate character. It may be necessaryto 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 InternetOptions from the IE menu. From the General tab, click on the Fonts button.

8 CONFIDENTIAL


15/92

Setting the Locale

Using the Language script dropdown box, navigate to the script or character set that isnot being displayed properly and select it. If the font is available in the system, it will behighlighted in the Web page font or Plain text font dropdown box, and the appropriatefont will be demonstrated in the field below each.

If a script is selected for which no font is available, it may be possible to add the font to the

system. Fonts and language support may be installed by following Microsofts instructionsand conventions. In general (when using IE6), appropriate fonts cant be downloaded fromWindows Update, but instead, support must be installed from either a Windows 2000,Windows XP or Microsoft Office CD (depending upon the users platform).

Notes on this process:

1. Even if a font is displayed in a script in the dialog window, the language may not displaycorrectly in all situations (e.g., proper display of Hindi-Devanagari script in a dropdown list

CONFIDENTIAL 9


16/92

Setting the Locale

requires the Mangal font, even though Arial Unicode MS is sufficient to display most othertext on a web page.)

1. Visiting a web page that uses an encoding (other than UTF-8 or UTF-16) for which anappropriate display font is not installed will result in a prompt to install the appropriatelanguage pack. The Windows 2000 or Windows XP CD will be needed in order tosuccessfully complete this task.

2. Language support may be added by using the Regional Settings applet from theControl Panel. Select Start | Settings | Control Panel and click on Regional and LanguageOptions.

(NOTE: The Windows 2000 screen for this setting may look different.)

Choose the Languages tab.

10 CONFIDENTIAL


17/92

Setting the Locale

On this tab, check the additional language support desired and click Apply. This mayinstall some fonts that are already present on your system, prior to prompting for theWindows 2000 or Windows XP CD.

NOTE: If Cancel is clicked when prompted for the CD, the installed fonts are notremovedand the web page maynow display correctly. If Cancel is clicked, the language selectedis not completely installed, and the checkbox is removed from the Language Settings forthe System panel.

If the additional files are installed from the CD, other languages may now display correctlyalso, since some fonts are shared across multiple scripts. (For example, after clickingCancel during the install for Traditional Chinese, a font suitable for it was available, but nosupport for Japanese. After completing the full installation for Traditional Chinese, a fontthat was suitable for Japanese was alsopresent and some, but not all, glyphs inSimplified 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 clickChange.

CONFIDENTIAL 11


18/92

Setting the Locale

Depending upon the version of Microsoft Office installed, make the appropriate selectionsto add additional features and select International Support, adding the appropriate fontsand selections.

Note that Pegasystems does notredistribute fonts with PegaRULES; it is the clientsresponsibility to obtain and install suitable fonts for the languages they require. There areuntestedfonts from other sources which may work:

ftp://ftp.netscape.com/pub/communicator/extras/fonts/windows/ (Netscapesfree 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.htmlhttp://babel.uoregon.edu/yamada/fonts.htmlftp://ftp.netscape.com/pub/communicator/extras/fonts/windows/


19/92

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

On the Availability tab, the Time Zone field allows entry of a specific time zone for thisuser.

Important: This setting will override the Localization settings (such as the setting in thebrowser), as well as the client machine timestamp setting for the session applicationprocessing. If this setting is entered, the user must be certain that their time zone will notenter data that conflicts with localization settings into their work objects.

CONFIDENTIAL 13


20/92

Setting the Locale

Locale

It is also possible to set a users locale permanently through the Locale Settings field.

On the Security tab of the Operator ID record, enter the appropriate locale for the userinto the Always Use Locale field. The locale should be entered in standardinternationalization format: xx_XX (example: en_US).

Important: This setting will override any other localization settings, including the browsersetting, in the Process Commander application. (It will not change the browser setting, butwill override it in the application only.)

Set Locale tool

Users may wish to view Process Commander in a specific language that may not be theirdefault (due to the work they are processing), or they may wish to reset ProcessCommander temporarily to work with a particular customer or company. In this case, thedefault locale within PegaRULES may be changed by using the Set Locale button, whichis 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 localesavailable in the ICU are included in the dropdown list, whether or not there are RuleSetscurrently present for those locales.

14 CONFIDENTIAL


21/92

Setting the Locale

If another locale is preferred, select the appropriate locale from the Use Locale list, andclick Update. This will take the original RuleSet List and re-localize it based on the newsetting.

NOTES:

Clicking Update will create work items in the chosen language (if the localizedRuleSet Lists are present). However, it will not immediately change the Portal tothe new language. To change the Portal also, hit the F5 key to refresh thescreen.

When the new locale is chosen, then the Use Locale dropdown list will appear inthe language chosen for the new Locale. The list is also sorted based on thecollation rules for the selected new Locale. In the example below, French(France) was chosen and the Use Locale dropdown list is now displayed inFrench:

CONFIDENTIAL 15


22/92

Setting the Locale

Important Note: The changes made using Set Locale do not persistfrom one session tothe 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, notfrom the last Set

Locale change. Also, changing the Locale by using Set Locale will notchange thedefault in the browser.

Clicking on the Settings button will bring up a small window showing the default Localeand Time Zone information (read from the browser):

NOTE: The Settings button uses a Java applet; in order to use this button, the user musthave Java 1.3.1, 1.4.x, or Java 5 installed on their client machine.

16 CONFIDENTIAL


23/92

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 Demowindow will display all information based on the chosen Locale:

However, if the Locale is changed withinthe Locale Settings screen, and then theCompute 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


24/92

Setting the Locale

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

Application-specific user interface

Depending upon the access provided, end-users may not see the Set Locale button fromthe Tools menu. The developer may wish to provide the applications end-users with acustom button (or buttons) to change their locale for different customers, or provide someother functionality.

It is possible to change the Locale by creating an application-specific user interface usingPegaRULES APIs. The Locale may be changed programmatically, by calling thesetLocale Java API (method in Interface PRThread) from a Java step. (This is the basisfor the functionality of the Set Locale tool.) This provides the ability for a developer todefine their own user interface for example, they could create links on a form, whichwhen clicked, will run an activity to change the Locale. For more information onPegaRULES Java APIs, please refer to the PegaRULES V4 javadocs.

18 CONFIDENTIAL


25/92

RuleSets and Localization


Beginning with Release 4.1, PegaRULES Process Commander supports internationallanguages and characters, as well as dynamic switching between these languages (forexample, changing from French to German without having to restart the PegaRULES

server). This functionality requires the creation of international RuleSets for both ProcessCommander and the customers application, to localize the PegaRULES system to theusers area.

Important note: RuleSets for international language/variant combinations are notshipped as a standard option with PegaRULES Process Commander. Should a customerrequire a localized version of Process Commander, they must request the appropriateLanguage Pack from Pegasystems (see section below on Language Packs).

Following the ISO standards for identifying locales, the name of a localized RuleSetconsists of up to three parts, separated by underscores:

1. Language2. Country3. Variant

Thus, if the language is French, the country is Luxembourg, and the variant is Pre-Euro,the RuleSet for the Acme Companys 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 users profile, RuleSets can be included that reflect each level oflocalization, 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 localizedRuleSets:

the application RuleSet

the Process Commander RuleSet

CONFIDENTIAL 19


26/92


Localizing Process Commander RuleSets: Language Packs

In addition to localizing the rules in an application, some rules in Process Commandermust 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 availablefor 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 ofthe small translations required for an application (messages, button text, etc.) have beencreated as Field Values (instances of Rule-Obj-FieldValue) which can be localized. All ofthese 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 facilitatelocalization. Language Packs are translated instances of the Process Commander FieldValues, provided in localized RuleSets. For example, for French, the Language Packincludes 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) isprovided.

Anyone who wishes to write an application in a language other than English, or localize anexisting English application into another language, would begin by obtaining theappropriate Language Pack, and then developing/translating their own application rulesinto that language.

Thus, for the standard PegaRULES RuleSets, the following is an example of the list of the

RuleSets and locale variants:

AcmeCo_fr_LU_PREEURO:04-02

AcmeCo_fr_LU:04-02

AcmeCo_fr:04-02

AcmeCo:04-02

Pega-ProCom_fr:04-02

Pega-ProCom:04-02

Pega-IntSvcs:04-02

Pega-WB_fr:04-02

Pega-WB:04-02

Pega-RULES:04-02

20 CONFIDENTIAL


27/92


Localizing Application RuleSets

For each RuleSet that is used in the application, the developer must create a RuleSet inthe 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-01AcmeSubscription_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


AcmeProducts_fr_FR:03-02


AcmeProducts:03-02

AcmeRulePro_fr_FR:04-01


AcmeRulePro:04-01

AcmeBase_fr_FR:04-02

AcmeBase_fr:04-02

AcmeBase:04-02


Pega-ProCom:04-02

Pega-IntSvcs:04-02

Pega-WB_fr:04-02

Pega-WB:04-02Pega-RULES:04-02

CONFIDENTIAL 21


28/92


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


AcmeProducts_fr_CA:03-02


AcmeProducts:03-02

AcmeRulePro_fr_CA:04-01


AcmeRulePro:04-01AcmeBase_fr_CA:04-02

AcmeBase_fr:04-02

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


AcmeProducts_es:03-02

AcmeProducts:03-02

AcmeRulePro_es:04-01

AcmeRulePro:04-01AcmeBase_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


29/92


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, theRuleSet List instances for BROWSER are read out of the Data-Admin-Requestor recordand given to the requestors authentication object, which then adds the localizationRuleSets (as described in the previous section). As the users Profile of RuleSets isassembled, each time a base RuleSet is added to the list, the system tests to see if aRule-RuleSet-Name instance for a localized version of that RuleSet is defined in thedatabase. If it is, the existing localized variants of that RuleSet are inserted automaticallybefore the base RuleSet. When the users Organization, Division, or Access GroupRuleSets are added, the localization RuleSets are included automatically as well. Whenthe RuleSets are fully assembled, each requestor will have two RuleSet Lists associatedwith it: the basic RuleSet List (which appears in the users Profile), and the localizedRuleSet 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 listof PegaRULES Process Commander rules will be swapped.

The base RuleSets for PegaRULES Process Commander are in US English (bydesign), as well as the developer environment. If a company is developing amultilingual application for locales other than en_US, it is suggested that the baseapplication RuleSets also be in US English, even though that may not be thepreferred language for the customer. Since the customer will be building severallocalized RuleSets, and as the PegaRULES RuleSets are all in US English,having the application RuleSets in US English also will provide consistencyacross the product. For example, if a French company (La Paniere) creates an

application, their base RuleSet would be in English (PaniereCo: 01-01), and theirRules would be stored in their localized RuleSet (PaniereCo_fr_FR:01-01).

The system tests each possible localization against the Rule-RuleSet-Name (forthe base RuleSet) only notagainst any Rule-RuleSet-Versions. Once it hasdetermined the appropriate name for the RuleSet (by taking the existing baseRuleSet and adding the appropriate localization designation), it will search for theRuleSet and Version which match the existing base RuleSet and Version. Forexample, 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 dont exist, standard RuleResolution 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 outsidethe major version (AcmeProducts_fr:03-05)cannot.

Developers must therefore be careful when naming application RuleSets. If theapplication base RuleSet is version 04-02, do notcreate a localized version ofthat RuleSet and start the version numbering again at 01-01 (since its a newversion of the RuleSet). The localized RuleSet version (AcmeProducts_fr:03-02) must match the base version (AcmeProducts:03-02).

CONFIDENTIAL 23


30/92


If a user changesthe locale (either by changing it in the browser or by using theSet 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 localeinformation.

If RuleSets for the new locale are not present in the system, no errorwill be

displayed. The system will put RuleSet entries into the RuleSet List based on theLocale setting, regardless of whether the RuleSets exist. The system will notattempt to create localized RuleSets if they do not already exist. During RuleResolution, the system will search all RuleSets and (because the others do notexist or are empty) use the base RuleSets.

Thus, using the Acme RulePro example above, if a user were to log in as eitherFrench (in France) or French Canadian, they would get a list of 18 RuleSets. Ifthey were to switch to Spanish, they would only receive 14 RuleSets, as there arefewer Spanish RuleSets available.

Displaying Localized RuleSetsAs stated above, the localized RuleSets will not be displayed in a users profile, which willcontinue to show only the base RuleSets:

24 CONFIDENTIAL


31/92


The entire localized list of RuleSets can be displayed using the Clipboard Viewer(available from the Tools bar in the PegaRULES portal):

CONFIDENTIAL 25


32/92


Developing with Localized RuleSets

Unlike users, developers who are localizing an application will need to see the localizationRuleSets 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 theorder they appear on the clipboard. Thus, the most specific localization RuleSets shouldbe listed beforethe less specific localized RuleSets, which in turn should be listed beforethe base PegaRULES RuleSets, to assure appropriate Rule Resolution processing.

26 CONFIDENTIAL


33/92

Building a Localized Application

Localizing the user experience for PegaRULES Process Commander can be divided intotwo 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 managers reports. Note that the developer tools (such as WhereAm I? are not localized.)

The Work Item (or items) are the focus of applications written in Process Commander, andas such, are custom to each application. These must be localized by the developer, usingthe processes described in this section.

Important: Note that functionality is provided to translate Process Commanderapplications into other languages. This does notmean that a translation engine isprovided, where the developer can create an application in English and then press abutton to magically translate that application into other languages. The application mustbe built according to the rules of localization, and Field Values must be created and thensaved into the base application RuleSet (and then into localized RuleSets) to translate theuser-visible labels for these rules.

Localization Building Blocks: Field ValuesLocalization in Process Commander is done by creating Field Value records for all labelsthat 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


34/92

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 thenlabels 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


35/92


(A customer would undoubtedly customize the sections which are shipped with theproduct, and may have some different labels.)

For each of these labels that a customer would see on a work item, a Field Value must becreated.

When originally designed, the Field Value rules were used to create a drop-down list ofvalues to choose for a particular property. Thus, it was necessary to define the FieldValue on the same class as the property, and specify the property in the Field Namesection, 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 allareas where this label may be used. Therefore, most Field Valuesare defined on @baseclass.

For History/Audit information, the assumption is made that theseentries would only be created in relation to a work item. All theHistory memo Field Values are defined on the class Work-.

Field Name The name of the grouping property to which this Field Valueinstance belongs. (See the Field Value Groupingssection below fordetails.)

Field Value The lookup key name of this field value. This name: may contain spaces (Time in Work Status New)

may contain up to64 characters

(See the Naming Field Valuessection below for more details.)

CONFIDENTIAL 29


36/92


Field Description

Short Description The full description of the text string for this Field Value. This fieldmay contain up to 255 characters.

NOTE: The Field Values that are shipped with Process Commanderare in English (the base language of the product). For any LanguagePacks that are created from these base Field Values, the ShortDescription will remain in English, while the Localized Label field willbe translated.

Localized Label The localized version of this entry. For the Field Values shipped withthe system, this field will be contain the Short Description informationdisplayed in English; for any of the Language Packs, this field willcontain the Short Description text in the appropriate language.

NOTE: This field mustbe filled in with text, not only for the localizedversions, but also for the base language (usually English). If the field

is not filled in, then blanks will appear instead of labels in the baselanguage application.

In addition, for the localization Field Values, the Usage Field on the History tab shouldcontain 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 theform), the meaning of the phrase is clear and does not need further explanatory text inorder to translate it correctly. However, for a Field Value such as Back or Cost, it isnecessary to have some contextual information provided in order to specify whether this isa 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 anappropriate Field Value, or to ascertain whether one with the same or a similar name hasbeen created, groupings have been created. Unlike their original use, the Field Values

30 CONFIDENTIAL


37/92


created for localization do not apply only to one specific property. Nevertheless, severalproperties 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 userwhat 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 (flowsonly)

pyStatusLabel @baseclass the status of the Assignments,and also information from theprocess the system is completing(creating, saving, deleting)

IMPORTANT: For all rules which have autogenerated HTML, it is required to define newfield 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 alabel in a specific group; if the Field Value has been defined in a different group, then thesystem 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 andtheir associated grouping are listed.

CONFIDENTIAL 31


38/92


When adding Field Values to the application, it is important to define them not only on thecorrect grouping property, but also on the correct class. Process Commander containsField 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 applicationclasses. If the Field Value is defined on only one of those classes, then it is not possible togain efficiency by reusing some of the Field Values in other classes, and even more mustbe 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 mayalso contain spaces. This is to facilitate creating Field Value names that are easilyunderstandable when viewed in a list.

Depending upon where in the system the label is located, as well as its length, the FieldValue 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 keyname of Operator ID. If there is an existing section with that label, no actual change isneeded 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 thisopen work item and determine whether it is valid; if it is valid, then send to your managerfor approval, that is too long a name for the actual Field Value. In this case, the FieldValue key name might be something like, ValidItemManagerApproval, and the full textwould be in the Short Description field. In this case, the key name then must be enteredinto 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 fieldand 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 developermust take care to be sure that not only the Short Description but also the translated labelmust 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 Valuefield) 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 orin the localized Pega- RuleSets, the system will use the (translated) label in the LocalizedLabel field of that Field Value.

32 CONFIDENTIAL


39/92


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 mustbe filled in with text for allField Values, not only

for the localized versions, but also for the base language (usually English). If the field isnot 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 textin that field. So from the first example, if no matching Field Values were present, then thesystem would display Operator ID. In the second example, the system would displayValidItemManagerApproval.

NOTE: The recommended process for localizing an application is to create all the FieldValues 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 notrequiredto have all of the Field Values in the base language (English, for example);different Field Value rules couldbe 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 inother languages, then for a particular label in the application, Field Values would beneeded for alllanguages, and must be present in allapplication RuleSets (localized ornot).

b. Due to the volume of Field Values required for most applications, if the application is tobe translated into more than one language, then it is important for the developer to haveall the Field Values in oneRuleSet, in order to be able to track in one place - which FieldValues have been created.

Valid Field Value EntriesBeginning in Version 4.2 Service Pack 5, the Field Value rule has been enhanced toenable use of both property references and parameter references. For each of thesereferences, a specific tab delimiter syntax must be used in order for the property orparameter substitution to take place. This syntax includes the Field Value key name, thetab 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 itmakes sense in the translated language. The message in English might read (forexample) :

Entered by at .

1Steps 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 hierarchywhich meets the criteria. If this is the rule in the localized RuleSet (higher in the Rule Resolutionhierarchy), then that will be used; otherwise, one of the standard ProCom or WB rules will be used.

CONFIDENTIAL 33


40/92


In another language, the appropriate translation may end up being:

entered this item at .

It is important to reorder the text and the references when translating the Localized Labelfield, 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 areproperty or parameter references in the Short Description. It is up to the developer toknow that a particular Field Value requires parameter or property references, and providethem 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, forexample), as the developer will have to provide parameter information for each referenceeach time this Field Value is used.

The parameter numbers refer to the parameters specified in the Message Key where thisField Value is called. Thus, using the example at the beginning of this section, if theLocalized 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 MessageKey field in an activity (see Using Field Valuessection below for full details) would providethis 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 tabdelimiter, which is specified withinthe quotes. This is followed by a plus sign and the firstparameter name; spaces may be put between the references and the plus sign, but arenot required. The two parameter references are also separated by a plus sign andanother tab delimiter in quotes. If further parameters were specified, they would continueto be added and separated by the tab delimiter:

EnteredBy\t + param.operatorID + \t + param.timestamp +

\t + param3 + \t + param4 + \t + param5

34 CONFIDENTIAL


41/92


Note, however, that if the Field Value only uses two parameters, any additionalparameters in the Message Key field will be ignored. It is not possible to change the FieldValue to use more parameters simply by including them in the Message Key; the FieldValue rule itself must be changed and resaved.

The order that the parameters are specified in the Message Key field will identify theirnumbers. Thus, if the message Entered by operatorIDat timestamp is desired using theabove Message Key data, then the Localized Label field of the Field Value would containthe expression above. If the message At timestamp, the operatorIDentered this item isdesired, 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 canbe 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 aparameter reference.

Localizing Parameter References

For some Field Values, the parameters that are passed in may be property referenceswhich themselves require localization.

CONFIDENTIAL 35


42/92


For example, the AssignmentCompleted Field Value actually has slightly different textthan 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 propertyPrimary.pyInstructions, which contains instructions. A run-time resolving of this FieldValue might result in a message such as:

Assignment to Review item and return to managercompletedby 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 belocalized. Since it is only a parameter reference in the Field Value, the localization lookupmust be done as part of the formatting.

In this example, both InstructionsLookupand CaptionLookupare Rule-HTML-Propertyinstances which are lookup formatting rules:

The information in the HTML Property gives the system information to look up a FieldValue 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 theHTML Property functionality. The Field Value Select Type of Correspondence forinvolves formatting the name of the Party in bold characters.

36 CONFIDENTIAL


43/92


The HTML code in the HTML Property PartyRuleLookupBold contains the boldfunctionality.

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, noparameters arerequired in the Message Key field. For this type of Field Value, the Message Key fieldwould only contain the key name:

InstructionToUser

Important: For this type of Field Value, the properties that are referenced must existonthe clipboard page at the time the field value is called. So for example, if this Field Valuewere referenced in an activity method, the properties .pyInstructions and.pyActionPrompt must existand have a valid valuewhen that activity ran and the FieldValue was called.

CONFIDENTIAL 37


44/92


Formatting Property References

Property references in Field Values may also be formatted.

The Field Value ChangeDivisionFromTo includes formatting to display the propertyreference value (.pyOwnerDivision) in bold text, by using the HTML propertydataStyleFontBold.

Using Field Value References in Activity Methods

Beginning with Service Pack 5, there are several activity methods that have beenenhanced 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 Fieldvalue)

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

38 CONFIDENTIAL


45/92


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

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 frompxThread.pxMethodStatus.

CONFIDENTIAL 39


46/92


The FailedAddToFolder Field Value is assumed to be in the class of the Activity (Work-) orabove (it is actually defined on @baseclass, so it is inherited by Work-), and the Categoryparameter 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 Addto Folder Failed, Status = value of pxThread.pxMethodStatus

Page-Set-Messages have similar functionality to the Property-Set-Messages processdescribed above; however, instead of setting the message on the specified property, itwould be set on the specified page.

Backward compatibility

Originally, the Message field of Page-Set-Messages and Property-Set-Messages referredto a Rule-Message instance. To ensure backward compatibility with existing activities inapplications written before the release of Service Pack 5, this functionality will still besupported.

If the Category field is blank, then the data in the Message field is parsed as aRule-Message instance.

If the Category field contains data, then the data in the Message field is parsedas a Rule-Obj-FieldValue instance.

History/Audit Fields

The functionality of storing and displaying History or Audit data in general is different thanother 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 ofOpening a New Item, for example, and the system does the localization lookup anddisplays the new work item in the users chosen language. History messages, however,have two distinct steps when a user completes an action:

creatingand storing/saving the data

displayingthe data

The History message may be created when a user completes an action transferring awork item, resolving it, etc. but it will not be vieweduntil the user actually clicks on theView History button.

40 CONFIDENTIAL


47/92


Therefore, localizing the History data should be done on the second step displayingonly. For a company which has users who employ more than one language, it isimportant 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 severalpeople 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-speakeraccomplished a step in the process) and then one line in French and one line inSpanish.

the list of items intheirlanguage - not in the language of the person who openedthe item, or who worked on it, or who resolved it.

In Service Pack 5, the functionality of History was changed. The History-Add methodand the Audit field were both enhanced to allow Field Values to be specified. When thehistory message is created and saved, only the Message Key and the valueof thereferences (at the time the message is created) are saved. Then, when the History pageis displayed, all of the Message Keys are localized to display in the language of the userviewing the page.

The Audit Note Field

The Audit Note field, which is found on some properties in flows, has the samefunctionality as described above in the Field Valuessection of this document; this field willaccept both parameters and property references.

Property references may also be included in the Field Values defined for this field. Whenthe flow goes through Java generation, the Field Values which are referenced in all theproperties are opened and checked for property references. If there are any property

CONFIDENTIAL 41


48/92


references for the Audit Note, the appropriate property name and value for that referenceare found and then copied into an embedded page in the History record.

Important: When defining Field Values for the Audit field, the Field Value (groupingproperty) mustbe specified as .pyHistoryMemo, so that these will display in the SmartPrompt 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 whocaused this particular history memo to be created. Inmost 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 theuser exactly as it is typed no localization is available

for this parameter.

NOTE: This field provides backwards compatibility withthe original (non-localized) functionality.

RuleAction for future functionality

Category* This field contains the name of the grouping propertywhich should be used to identify the history message.This field defaults to .pyHistoryMemo.

42 CONFIDENTIAL


49/92


MessageKey* This field contains the Field Value key name (the FieldValue data). This field can also contain any tab-delimited parameters.

As explained in the previous section, the Rule-Obj-FieldValue class contains three keyproperties:

Class Name

Field Name Field Value

There is also another field on the rule, .pyLocalizedValue, which is the value in theLocalized Label field which holds the translation of the Short Description. In order to findthe appropriate Field Value and return the Localized Label field for display, the systemuses the following data:

Class Name - the class of the primary page of the activity that is being run whenthe 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, backwardcompatibility is provided: if the Category field is filled in, then the MessageKey field isparsed as a Field Value. If the Category field is blank, then the MessageKey field isparsed as a Rule-Message instance.

At assembly time, the system will generate the code necessary to construct the messagedescriptor from the literals and property references in the Categoryand MessageKeyfields. When this code is executed, the message will display the value that the parametersheld when they were stored.

Important: For Field Values which are created to work with the History-Add method, it isnot possible to have property references defined in the Field Value rule itself. If thelocalized history message includes a property reference, that property reference mustbedefined in the MessageKey field:

CONFIDENTIAL 43


50/92


Unlike the functionality on flows, when History-Add runs, the Field Values which arereferenced are notopened to check for property references, and the appropriate name-value pairs are notsaved to the embedded page of the History record. Thus, any propertyreferences for History-Add mustbe in the MessageKey field.

44 CONFIDENTIAL


51/92

Creating the Application


OverviewWhen creating an application that will be localized, it is vital to keep localizationfunctionality in mind when designing the work item processes (flows, flow actions), and thework item itself (harnesses and sections). Recommended practice for a developer who iscreating an application to be localized would be to write the application itself, creating thenecessary Field Values as the other Rules are created, and then, after the application ismostly complete, create the localized RuleSets and translate the appropriate Field Values.

Currently, in Release 4.2 of PegaRULES Process Commander, the Rule formsthemselves cannot be localized. In addition, any error messages generated by the basePegaRULES engine will continue to be displayed in US English for the Service Pack 5release. 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 fulllocalization functionality. If a company begins their development with the ApplicationAccelerator, it will be necessary to go in to the Accelerator-created rules and check theLocalize? 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 Pack2. Create the localized RuleSet(s) for the application3. Determine which rules require localization in the application. These include:

a. harnesses

b. sectionsc. flow actionsd. flowse. 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 localization5. 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 forms7. Save the Field Values into each localized application RuleSet8. 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


52/92


Creating Flows

As the developer is creating flows for the application, they must localize certain fieldswhich 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 populatethe Properties boxes.

46 CONFIDENTIAL


53/92


Depending upon the type of shape, there are different Properties boxes that aredisplayed:

CONFIDENTIAL 47


54/92


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 isalso localized.

In order to be able to localize the application, the text that is in these fields must resolve toa Field Value. (NOTE: If the text does notresolve to an existing Field Value, the text itselfwill be displayed as the label.)

48 CONFIDENTIAL


55/92


For some of the example flows, Field Values have been created:

However, developers creating their own applications can also create their own customflows. In this case, they must also create Field Values for these Properties fields. TheField Values must be created in the following groups:

Properties FieldField 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 ActionsThe flow action rules are all displayed in the Take Action drop-down menu, where theuser chooses an action for the work item. Some of these may be custom-created by thedeveloper, or the developer may use the standard ones provided with ProcessCommander.

HTML Tab

The developer must begin by ascertaining that localization is possible for a particular flowaction. When creating an application, one of the recommended procedures is to copyexisting flow actions; in order to enable localization, the developer should start with a flow

action rule from Service Pack 5.

CONFIDENTIAL 49


56/92


There are a number of settings on the HTML tab which affect localization.

Setting Description Localization value

Auto GeneratedHTML

Choice: enabledor disabledThis checkbox determineswhether there is custom HTML inthis window. If auto generate ison, the system generates theHTML from the information on theForm tab. If auto generate is off,the system assumes that customHTML has been entered into thiswindow and shouldnt beoverwritten with generated HTML.

checked (enabled)

In order for localization tobe enabled, the HTMLmustbe auto-generated. Ifthis box is unchecked, theLocalize box willautomatically uncheck.

50 CONFIDENTIAL


57/92


Setting Description Localization value

Generate for JSP Choice: generate for JSPor forHTMLWhen the system auto-generates

the HTML code, for custom tagswithin that code, it can either usePega directives (HTML), orstandard JSP tags (JSP).Process Commander BestPractice states that for allapplications built on theSmartBuild Release or later, allrules which generate HTMLshould use JSP tags.

generate for JSP

Almost all flow actions from

Service Pack 5 havealready been generated forJSP.

Localize? Choice: enabledor disabledThis checkbox determineswhether the system will treat the

fields on the Form tab as just textto be displayed to the user, or asField Value entries to be lookedup by the system.

checked (enabled)

Localization is dependent

upon the system lookingup all the Field Values

Omit extra spaces? Choice: enabledor disabledThis checkbox determineswhether the PegaRULES enginecompresses the generated HTMLcode (stream) before sending itfrom the server to the client.(Compressing the HTML streamallows data to be sent faster from

the server, resulting in greaterefficiency in server responsetime.)

checked (enabled)

NOTE: If the rule has AutoGenerate checked bydefault, then this checkboxwill also be checked bydefault, andit will begrayed out (the user will

not be able to change it).

(NOTE: The Define Form dropdown box and the Portlet Compliant checkbox are notrelevant to localization. For more details on these settings, please consult the on-line Helpor other Process Commander documentation.)

Important: In order for localization to be enabled on flow actions, the Localize?checkbox and the Auto Generate checkbox mustbe checked.

Form Tab

In order to localize flow actions, it is necessary that the rules be displayed in smartframes. The old column-and-field-based forms have not been tested to supportlocalization.

CONFIDENTIAL 51


58/92


The Short Description field at the top of the flow action contains the text that the user willsee in the Take Action drop-down box. Therefore, the developer must ascertain that aField Value is created for this item.

In addition to the Short Description, a Field Value must also exist (for localization) for eachof the labels that a user sees. In the smart frames version of this rule, each area of theflow action may be clicked to display information about the properties that make up thatarea. For example, clicking on the Completion Note section of the above Flow Action willdisplay the following information:

52 CONFIDENTIAL


59/92


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 fieldmust contain a Field Value reference.

CONFIDENTIAL 53


60/92


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 UsageField ValueApplies To class

Field Name (groupingproperty)

Action Instructionscaption

Instructions (thetooltip info at thebottom of thescreen)

@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 isentered into the Information box at the bottom of the Form tab, and then linked to theHelp 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


61/92


CONFIDENTIAL 55


62/92


Help text can be longer than the limit allowed by a Field Value; therefore, if the flow actionis going to be localized (i.e., when the Localize? box is checked), the Information box onthe Form tab should notbe used. Instead, on the HTML tab, reference a Rule-Obj-HTMLinstance.

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 whichwill be used for the Help information. This HTML rule can then contain either all thetranslated text for the Help file, or the references to one or more Field Values whichcontain the Help text.

Creating the Work Items

Harnesses

Much of the localization functionality for harnesses is similar to the flow action featuresdescribed 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 Omitextra spaces features are not present.

56 CONFIDENTIAL


63/92


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


64/92


For the fields on a harness, Field Values should be defined on the following groupingproperties.







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


65/92


As with flow actions, the Layout tab should be displayed in smart frames, and eachuser-visible label should have a corresponding Field Value created in order to localize itstext.

For the fields on a section, Field Values should be defined on the following groupingproperties.







CONFIDENTIAL 59


66/92


Creating Reports

In Service Pack 5, many of the standard Summary View and List View rules have beenlocalized. Their shared localization functionality is described here; for functionality specificto 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 forthe reports.

Unlike harnesses and sections, it is not possible to change the HTML in this tab it isgeneratedHTML only. Thus, the Auto Generate HTML checkbox (and relatedcheckboxes, 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 forService Pack 5; this functionality will occur in a future release.

60 CONFIDENTIAL


67/92


For both List Views and Summary Views, the title of the report (Timeliness of top processowners) 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 flowaction rules, once the Localize? checkbox is checked and localization is enabled, theselabel fields will automatically search for Field Value references. If an appropriate FieldValue is not found, then the system will return the text which is in the label field.

CONFIDENTIAL 61


68/92


On both the Content and the Drill Down tabs, the labels are in Caption fields.

62 CONFIDENTIAL


69/92


The Organize tab, on the other hand, displays the captions for buttons or links on thereport:

Thus, Field Values which are defined for these labels should be in the following groups:



Caption (ContentorDrill Downtab)

report labels @baseclass pyCaption

Caption (Organizetab)

button or linkcaptions

@baseclass pyButtonLabel

Full Descriptionfield (Historytab)

report title @baseclass pyMessageLabel

CONFIDENTIAL 63


70/92


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


71/92


There are a number of Caption fields on the Content tab, but noneof these are localized,as the user doesnt see them.

NOTE: On this tab, there is a checkbox for Convert criteria values from Localevalues? This checkbox does nothave to do with localizing labels; instead, it allowsconversions of date values for calculations. (For full details on this item, please see theOn-Line Help on Completing the Content Tab.)

CONFIDENTIAL 65


72/92


The Organize tab also contains Caption fields; as with the Summary View rule, these arebutton labels or links.

Thus, Field Values which are defined for t

localization 0402

Documents