8 Localizing OSM

Localizing the XML Import/Export Application

If you localized OSM, you must also localize the XML Import/Export application. Localizing the XML Import/Export application involves the following high-level steps:

1. Uncompress the OSM_home/SDK/XMLImportExport/classes/modelHandler.jar file.

   Set the environment variable PATH to JDK_home/bin, then from a command prompt run the command:

   jar xvf modelHandler.jar
   

2. Localize the sql/default_data.sql file.

   To localize the default_data.sql file, you must understand the relationship between the data that was localized in the XML files from the omsmodel_l10n.jar file, and the insert scripts defined in the default_data.sql file. The following example provides that understanding:

   Suppose om_state.xml of omsmodel_l10n.jar is localized. The localization corresponds to the INSERT statements of the table OM_STATE defined in default_data.sql in the om_state.xml file. For example, if the <state_description> of <state_mnemonic>received</state_mnemonic> is localized as <state_description>TEMP_received</state_description>, in default_data.sql the INSERT statement that is inserting received state in the OM_STATE table must be localized to:

   [INSERT INTO OM_STATE (STATE_ID, STATE_MNEMONIC, STATE_CATEGORY_ID, STATE_DESCRIPTION,STATE_ICON_ID, CARTRIDGE_ID) VALUES (1, 'received', 1, 'TEMP_received', 0, 0); ]

   Following this example, all fields that are localized in the XML files of omsmodel_l10n.jar must also be localized in default_data.sql.

3. Compress modelHandler.jar.

   After you have localized the sql/default_data.sql file, open a command prompt, navigate to the directory that contains the JAR file, and run the command:

   jar cvf modelHandler.jar .
   

Localizing the Encoding Element

To support localization, the <encoding> element in the config.xml file determines the appropriate language. For information on the config.xml file, see OSM System Administrator's Guide.

• Configure the following line in the config.xml file with the appropriate ISO character code, shown in bold, below:

  <encoding>ISO-8859-2</encoding
  

• Be sure that your Microsoft Windows operating system is localized for your language. See Microsoft documentation for instructions.

• Some pattern restrictions for entity names in the XML model schema are provided with the XML Import/Export application. For non-English environments, you must customize the schema for entity name patterns.

Support for Different Locales

Locales are linguistic regions that share spelling conventions. A locale consists of a language code, followed by an optional country code, followed by an optional variant code. For example, "en_US" specifies English in the United States, while "en_GB" specifies English in Great Britain.

Operating systems such as Windows, Linux, Oracle Solaris, and HP-UX support the locale model and provide facilities to properly read and format locale-specific information. Additionally, newer programming languages such as Java provide similar facilities to support localization.

However, HTML does not support localization or have solutions for date or time issues. The localization of HTML requires support from the OSM server and Javascript code sent to the browser.

Character Set Encoding and Fonts

Characters in an HTML file are stored as numeric values with a range from 0 to 255. When a web browser displays a character symbol, it uses the numeric value to find the correct symbol to display. The set of symbols displayed for each number is known as a character set. As 256 numbers is insufficient to describe all possible characters that may need to be displayed in all languages, you must specify what character set the browser is to use when it displays an HTML page.

By default, HTML uses the ISO-8859-1 character set, which can display all characters needed for Western European Languages. When you create HTML pages using other character sets (such as ISO-8859-2 for Eastern European Languages), you must use the corresponding encoding.

You must ensure that a font appropriate for the text you intend to use has been installed on the system.

Localization of Settings

OSM supports localized Windows regional settings: All number, currency, date, and time formats displayed in the Administration area of the OSM Order Management web client come from the Windows regional settings.

You can also localize regional settings through the OSM properties file. See "Task Web Client Localization Resource Bundles" for more information on how to do this.

For more information on Windows regional settings, see the Microsoft Windows documentation.

Oracle Database Character Set

OSM stores its text data in CHAR and VARCHAR2 columns in an Oracle database. The database character set determines what languages can be represented in the database. So, you must install OSM in an Oracle database with a character set that meets your language requirements.

You can specify a character set when creating a database using the CHARACTER SET clause of the CREATE DATABASE statement. A complete list of character sets supported by Oracle is included in the Oracle documentation.

You can use the v$nls_parameters view to determine the existing database character set.

OSM does not use the NCHAR, NVARCHAR2, or NCLOB data types and so has no specific requirements for the alternate character set for the database.

To determine the existing character set:

1. Connect to the Oracle server using SQL*Plus as a user who has access to the v$nls_parameters view.

2. At the SQL*Plus prompt, enter the following:

   SQL> select value from v$nls_parameters where parameter = 'NLS_CHARACTERSET';
   

   Information similar to the following is returned:

   VALUE
   ----------------------------------------
   WE8ISO8859P1
   

   You can use the CHARACTER SET clause of the ALTER DATABASE statement to change the character set for an existing database.

   Note:

   You must have SYSDBA system privileges.

To change the character set:

1. Initiate the database in restricted mode. For example, use the SQL*Plus STARTUP RESTRICT command.

2. Connect to server Manager (svrmgrl in UNIX or svrmgr30 on Windows XP).

3. At the prompt, enter:

   ALTER DATABASE db1 CHARACTER SET WE8ISO8859P1;
   

   Note:

   The source character set must be a strict subset of the target character set.

NLS Environment

For the OSM Order Management web client Administration area to support localization, the Oracle NLS parameters must be configured properly in Windows XP.

On UNIX, the Oracle NLS parameters are configured as environment variables. On Windows XP, the Oracle NLS parameters are configured as registry entries under HKEY_LOCAL_MACHINE/SOFTWARE/ORACLE.

NLS_LANG = language_territory.charset

om_application_function

Table 8-3 lists the application functions defined for OSM. The file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/user/privelege/_table/_data directory. Localize the values in the right column.

om_attribute_type

Table 8-4 lists the attribute types used by OSM. The file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/ordertemplate/_table/_data directory. Localize the values in the description column.

om_order_data_dictionary

Table 8-5 describes the data dictionary. The data dictionary contains one element, which is a dictionary element for the root node in the OSM master order template. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/ordertemplate/_table/_data directory. Localize the text that appears in the business_name column.

om_order_remarks_type

Table 8-6 describes the order remarks localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/ordertemplate/_table/_data directory. Localize the text that appears in the remarks_type_description column.

om_order_type_category

Table 8-7 describes the order type localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/ordertemplate/_table/_data directory. Localize the text that appears in the order_type_category_descr column.

om_process

Table 8-8 describes the order process localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/process/_table/_data directory. Localize the text that appears in the process_id_description column.

om_process_status

Table 8-9 describes the process status localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/process/_table/_data directory. Localize the text that appears in the process_status_description column.

om_responsibility

Table 8-10 describes the responsibility localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/user/privelege/_table/_data directory. Localize the text that appears in the responsibility_description column.

om_rule_def

Table 8-11 describes the rule definition localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/rule/_table/_data directory. Localize the text that appears in the rule_description and rule_comment columns.

Null Rule is the rule that always evaluates to true.

om_state

Table 8-12 describes the state description localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/process/_table/_data directory. Localize the text that appears in the state_description column.

om_state_category

Table 8-13 describes the state category description localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/process/_table/_data directory. Localize the text that appears in the state_category_description column.

om_status_category

Table 8-14 describes the status category description localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/process/_table/_data directory. Localize the text that appears in the status_category_description column.

om_task

Table 8-15 describes the task description localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/process/_table/_data directory. Localize the text that appears in the task_description column.

om_view_order_node_label

Table 8-16 describes the view order node label localization. This file is located in your OSM_home/Database/osm-db-installer-core/install/OMS/main/model/ordertemplate/_table/_data directory. Localize the text that appears in the label column.

om_generic_mnemonic

Table 8-17 describes the generic mnemonic localization. Localize the text that appears in the description column.

Task Web Client Localization Resource Bundles

After you unpack the oms.ear file (see "Unpacking the oms.ear File"), the localizable resources for the Task web client are contained in the OSM_home/SDK/Customization/resources/resources directory.

This directory contains the resources.properties file. This file contains all localizable strings and image references for the Task web client. Several other properties files are included in the resources directory as samples, including:

• resources_cs.properties (localized for the Czech Republic)

• resources_zh.properties (localized for China)

• resources_en.properties

To create a new localization property file:

1. Copy the resources.properties file and create a new file using the following naming convention:

   resources_locale.properties
   

   where locale is a locale code. For example, resources_ja.properties for Japan.

2. For each parameter in the resources_locale.properties file, provide a replacement value in the new locale. If you do not provide a replacement value, the Task web client uses the default value.

Localizing the Process History Pages

The Process History pages in the Task web client user interface use the Oracle JavaScript Extension Toolkit (JET), which has built-in support for internationalization and localization.

When a user connects to this client using a web browser, the OSM server attempts to determine their preferred locale. If no customization can be found for the preferred locale, the default locale (English) is used. All modern web-browsers support an Accept-Language header which indicates locale preferences. If you specify multiple language preferences, OSM uses the top one listed to locate localization resources.

After you unpack the oms.ear file (see "Unpacking the oms.ear File"), the localizable resources for the Process History pages in the Task web client are contained in the OSM_homeSDK/Customization/osm-ui-web/js/resources/nls/ directory.

This directory contains the bundle.js property file. This file contains all localizable strings for the Process History page. The bundle.js file is loaded by the server by default, if no customization is found. Several other properties files are included in the nls directory as samples, including:

• zh/bundle.js (localized for China)

• cs/bundle.js (localized for the Czech Republic)

To create a new localization property file:

1. Create a new directory with the name of the language code and copy the bundle.js file to the directory you created. For example, create a directory with the name fr (localized for France) and copy the bundle.js file to the fr directory.

2. For each parameter in the fr/bundle.js properties file, provide a replacement value in the new locale. If you do not provide a replacement value, the Task web client uses the default value.

3. Add the new locale to the list of locales provided in the default bundle.js file.

   For example, if you want to localize the Process History pages for France, add the string "fr":1 to OSM_HOME/SDK/Customization/osm-ui-web/js/resources/nls/bundle.js as shown below:

                            define({
                               root: {
                                     appName: "Order and Service Management",
                                                      ...
                                                     ....
                                             }
                                              "cs": 1,
                                              "zh": 1,
                                               "fr" : 1
                                     });
   

4. Pack the oms.ear file and redeploy it to the WebLogic server.

5. Change the language settings in the browser to the language you want to use.

Localizing Date, Time and Currency Formats

To differentiate between 2:00:00 pm EST and 2:00:00 pm CST, modify the resource.properties file by changing the format.datetime.input setting to include time zone.

To specify this, you must:

1. Open the resources.properties file.

2. Specify date time input and display format. For example:

   format.datetime.input=MM/dd/yy hh:mm:ss a

   format.datetime.display=MM/dd/yy hh:mm:ss a

   Table 8-18 lists the localization data properties.

You must edit the mask.date and mask.time properties together. You cannot edit one property and leave the other one empty.

Table 8-19 lists the available values for the mask.date and mask.time properties.

Table 8-20 lists the available values for the mask.currency property.

You must change the on-window text of the HTML pages produced by the OSM UI, and, if necessary, indicate the character set encoding.

Localizing Text and Error Messages

If text and error messages (that is, messages in the resource file that begin with text or error), contain parameterized values, for example: {0}, {1}, {2}, and so on, ensure the localized message uses the same parameterized values.

Localizing Page Titles

Page titles in the resource file begin with page.

Localizing Image References

Image references consist of two parameters:

• image.name.alt: The HTML alternate text to display for the image

• image.name.src: The location of the image file in oms.war (see "Inserting New Images").

Inserting New Images

All images that display in the Task web client are contained in the oms.war file packed in the oms.ear file. You can insert new images anywhere inside oms.war as long as your reference the correct location in the locale's resource.properties file. Oracle recommends that you create a directory for each localization and name the directory images_locale, where locale is a code for the location.

Editing the First Day of the Week

By default, the Task web client date and time calendar assumes Sunday is the first day of the week. However, this value is set automatically based on the user's locale.

Editing the Boolean Data Element Values

The Task web client displays boolean data element values in drop-down lists in several views. You can change the Boolean data element values the Task web client displays by editing the Boolean display value fields in the resources.properties file.

For example:

# Boolean display values
text.boolean.yes=Yes
text.boolean.no=No

Editing the Number of Records Displayed in the Worklist

You can change the number of records displayed in the Worklist view from the default by editing the oms-config.xml file.

See the chapter on configuring OSM with oms-config.xml in OSM System Administrator's Guide for detailed instructions on accessing and modifying the oms-config.xml file.

To change the number of records displayed in the Worklist view:

1. Open the oms-config.xml file for editing.

2. Search for max_worklist_rows, and update the <oms-parameter-value> tag with the new value.

3. Save and close the oms-config.xml file.

Editing and Replacing Task Web Client Icons

You can edit or replace the icon graphics that appear in the Task web client. To do this, replace the graphical content of the existing icon files with your own, customized graphics.

When creating or editing an icon graphic, ensure you maintain the file name. For example, if you replace the graphical content of the about.gif file, ensure you name the resulting file about.gif.

Oracle recommends that you only customize or replace existing icon graphics if the original graphic introduces ambiguities or errors when you localize the Task web client.

All of the OSM icon files are located in the OSM_home/SDK/Customization/osm-war/images directory.

Changing the Order Management Web Client Logo Image and Text

To change the Order Management web client logo image and text:

1. Go to the OSM_home/SDK/Customization/osmwebui/images folder.

2. Change any images with the Oracle logo. Do not change the image names or file types.

   For example:

   • splash.jpg: This image is used in the Order Management web client login and about screens and contains the Oracle logo at the top left corner.

   • splash.bmp: This is the Order Management web client background and contains the Oracle logo at the top left corner.

3. Open OSM_home/SDK/Customization//resources/xliff/oracle/communications/
   ordermanagement/ui/order3columnBundle.xlf using a text editor.

4. Change the text associated with the customized Oracle logo images.

   For example:

   <?xml version="1.0" encoding="windows-1252" ?>
   <xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
     <file source-language="en" original="oracle.communications.ordermanagement.ui.order3columnBundle"
           datatype="xml">
       <body>
         <trans-unit id="OSM_APP_NAME">
           <source>custom_name</source>
           <target/>
         </trans-unit>
         <trans-unit id="HOME_PAGE_TITLE">
           <source>custom_name2</source>
           <target/>
         </trans-unit>
         <trans-unit id="DENIED_SEARCH_MSG">
           <source>You are not authorized to perform search</source>
           <target/>
         </trans-unit>
         <trans-unit id="ERROR_MSG_SUBJECT">
           <source>Error</source>
           <target/>
         </trans-unit>
       </body>
     </file>
   </xliff>
   

   where custom_name is the text associated splash.jpg and custom_name2 is the text associated with splash.bmp.

5. Save and close the file.

Unpacking the oms.ear File

Before you can work with a configuration file that is packed in the oms.ear file, you must unpack the oms.ear file.

To unpack the oms.ear file:

1. Copy the oms.ear file from the domain_home/servers/admin_server_name/upload/oms/app/ directory to your OSM_home/SDK/Customization directory:

   where admin_server_name is the name of the WebLogic administration server.

   Note:

   Oracle recommends that you make a backup copy of your original oms.ear file, in case you need to restore the default settings.

2. From the OSM_home/SDK/Customization directory, use a text editor to do one of the following:

   • On UNIX or Linux, open unpackOMS.sh and set the JAVA_HOME variable to the path to the JDK on your system.

   • On Windows, open unpackOMS.bat and set the JAVA_HOME variable to the path to the JDK on your system.

     Note:

     If the path in JAVA_HOME contains a space, enclose the path in quotation marks. For example:

     set JAVA_HOME="C:\oracle\middleware test\jdk170_67"
     

3. Save and close the file.

4. Do one of the following:

   • On UNIX or Linux, run unpackOMS.sh.

   • On Windows, run unpackOMS.bat.

   The script unpacks the oms.ear file and creates the following new sub-directories in the Customization directory:

   • osm-ear

   • osm-ejb

   • osm-war

   • osmwebui

   • resources

Packing the oms.ear File

When you finish editing a configuration file, you must pack the oms.ear file and redeploy it to the OSM WebLogic server so that your edits take effect.

To pack the oms.ear file:

1. From the OSM_home/SDK/Customization directory, use a text editor to do one of the following:

   • On UNIX or Linux, open packOMS.sh and set the JAVA_HOME variable to the path to the JDK on your system.

   • On Windows, open packOMS.bat and set the JAVA_HOME variable to the path to the JDK on your system.

     Note:

     If the path in JAVA_HOME contains a space, enclose the path in quotation marks. For example:

     set JAVA_HOME="C:\oracle\middleware test\jdk170_51"
     

2. Save and close the file.

3. Do one of the following:

   • On UNIX or Linux, run packOMS.sh.

   • On Windows, run packOMS.bat.

   The script creates a new oms.ear file.

4. Copy the new oms.ear file to the domain_home/servers/admin_server_name/upload/oms/app/ directory:

   where admin_server_name is the name of the WebLogic administration server.

5. Do one of the following:

   • Stop and restart the WebLogic server. For information about starting and stopping the WebLogic server, see OSM Administrator's Guide.

   • Redeploy the oms.ear file:

     1. Log in to the WebLogic Administration Console.

     2. In the Domain Structure pane, click Deployments.

     3. In the Deployments window, select the box next to oms, click Stop, and select the option appropriate for your situation.

     4. With the box next to oms selected, click Delete.

     5. Click Activate Changes.

     6. Click Install.

     7. In the Install Application Assistant window, browse to the location of the updated oms.ear file and click Finish.

     8. Select the box next to oms and click Start and Servicing all Requests.

Undeploying and Redeploying the oms.ear File

Undeploying and redeploying the oms.ear file makes any changes you have made active on the OSM server.

To undeploy and redeploy the oms.ear file:

1. Log in to the WebLogic Server Administration console as a user with administrative privileges.

2. In the Domain Structure pane, click Deployments.

3. In the Deployments table, select the oms enterprise application deployment by clicking the check box for that row.

4. From the Stop menu in the Deployments table, select either When work completes or Force stop now.

5. When the server has stopped, select the oms deployment again and click Delete.

6. Click Install.

   The Install Application Assistant window is displayed.

7. Browse to the location of the new version of the oms.ear file and select oms.ear.

8. Click Next.

9. Select Install this deployment as an application and click Next.

10. Click Finish.

    You are returned to the Deployments window with the oms deployment added and active.