The Glossary Mechanism provides a way to translate CRM.COM terms to any language that is supported by CRM.COM. This section explains how to use the mechanism when creating custom pages and is applicable from CRM.COM R9.0.0 onwards.
What does this section cover?
General Idea
All CRM.COM terms that appear on screen should be replaced in both .xml and .java files with keys. A key must have the following format: key_<unique_phrase> and should always be in lowercase. i.e. key_priceplan, key_price_plan. A key can only be defined once but it can be used multiple times.
Properties File
Properties file is used to store the keys and their translation. Properties file for English translation is named translation_eng.properties can be found under <project_directory>/Crm/WebContent/labels. Note that all keys must be unique.
Properties file for English translation
<properties>
<comment>eng Translation</comment>
<entry key="key_life_cycle_state">Life Cycle State</entry>
<entry key="key_all">All</entry>
<entry key="key_n/a">N/A</entry>
<entry key="key_billing_information">Billing Information</entry>
<entry key="key_view">View</entry>
.
.
.
</properties>
For every term that its key is not defined in the properties file 'No translation' will be displayed.
Non-translated terms Example
keys used: key_name, key_alternativecode, key_description
key_alternativecode has not been defined in properties file.
<fieldlist>
...
<field>
<fieldname>PRODUCTTYPES.PRODTYPENAME</fieldname>
<caption>key_name</caption>
<summary>true</summary>
<filter>true</filter>
<filtercaseinsensitive>true</filtercaseinsensitive>
<link>page.do?xml=products/type&act=itm&jndi=ejb/CRMUIProductType&fc=loadForm&pv0=((PRODUCTTYPES.PRODTYPEID))&pvc=1</link>
</field>
<field>
<fieldname>PRODUCTTYPES.PRODTYPEALTCODE</fieldname>
<caption>key_alternativecode</caption>
<summary>true</summary>
<available>true</available>
<filter>true</filter>
</field>
<field>
<fieldname>PRODUCTTYPES.PRODTYPEDESC</fieldname>
<caption>key_description</caption>
<summary>true</summary>
<filter>false</filter>
</field>
...
</fieldlist>
Summary Pages
This section shows how to use the Glossary Mechanism when creating summary pages.
Search Fields
When defining search fields in summary pages the following rules must be followed:
- caption tag should always contain a key in order for its value to be translated by the glossary mechanism.
- fixedlookup tag should make use of a key to define the value that will be displayed when no option is selected from the drop-down list and no filtering is to be made based on the search field.
Example
keys used: key_life_cycle_state, key_all
<field>
<fieldname>LIFECYCLESTATE_FILTER</fieldname>
<fieldfunction>ACCOUNTSRECEIVABLE.LIFECYCLESTATE</fieldfunction>
<caption>key_life_cycle_state</caption>
<summary>false</summary>
<filter>true</filter>
<filtertextoption>equal</filtertextoption>
<fixedlookup>ejb/CRMUIAccountReceivable.getLifeCycleStateOptions:key_all</fixedlookup>
</field>
Summary Fields
When defining summary fields the following rules must be followed:
- caption tag should always contain a key in order for its value to be translated by the glossary mechanism.
- fixedlookup tag should make use of a key to define the value that will be displayed when the field's value is not included in the available options.
Example
keys used: key_life_cycle_state, key_n/a
<field>
<fieldname>LIFECYCLESTATE</fieldname>
<fieldfunction>ACCOUNTSRECEIVABLE.LIFECYCLESTATE</fieldfunction>
<caption>key_life_cycle_state</caption>
<summary>true</summary>
<filter>false</filter>
<fixedlookup>ejb/CRMUIAccountReceivable.getLifeCycleStateOptions:key_n/a</fixedlookup>
</field>
Drill Downs
When defining drill downs in summary pages the following rules must be followed:
- caption tag should always contain a key in order for its value to be translated by the glossary mechanism.
- label tag should always contain a key in order for its value to be translated by the glossary mechanism.
Example
keys used: key_billing_information, key_view
<field>
<fieldname>BILLINGINFORMATION</fieldname>
<fieldfunction>''</fieldfunction>
<caption>key_billing_information</caption>
<summary>true</summary>
<fieldtype>label</fieldtype>
<label>key_view</label>
<link>drilldown:billing/bills;hidefilters~true~BILLS.ACCRECID~((ACCOUNTSRECEIVABLE.ACCRECID))</link>
</field>
Actions
When defining actions in summary pages the following rule must be followed:
- caption tag should always contain a key in order for its value to be translated by the glossary mechanism
Example
keys used: key_new, key_set_privacy_level
<actions>
<action>
<caption>key_new</caption>
<topmenu>true</topmenu>
<link>page.do?xml=communications/communication&act=new&jndi=ejb/CRMUICommunication&fc=createButton&pvc=0</link>
</action>
<action>
<caption>key_set_privacy_level</caption>
<modal>true</modal>
<link>javascript:displayModalCreate('communications/setPrivacyLevel','ejb/CRMUICommunication','loadPrivacyLevelForm','java.util.ArrayList@[[SummaryComponent_((component))]]','edit',null,'','')</link>
</action>
</actions>
Data Entry Pages
This section shows how to use the Glossary Mechanism when creating data entry pages.
Definition File
In data entry definition files, all name, label, sidelabel, truelabel, falselabel, tipexpression tags must contain only keys in order for their values to be translated by the glossary mechanism.
Title
The following example demonstrates how to make use of the glossary mechanism when defining the title of a data entry page.
Example
keys used: key_communication
<?xml version="1.0" encoding="UTF-8"?><page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../xsd/dataEntry.xsd">
<id>communications/communications</id>
<name>key_communication</name>
<datapath>number</datapath>
.
.
.
</page>
Main Menu
The following examples demonstrate how to make use of the glossary mechanism when implementing the main menu of a data entry page.
Example 1
keys used: key_new
<mainmenu>
<components>
<component>
<id>cmpNew</id>
<name>key_new</name>
<visiblemodes>read</visiblemodes>
<hideinmodal>true</hideinmodal>
<elements>
<button>
<id>btnNew</id>
<name>key_new</name>
.
.
.
</button>
</elements>
</component>
.
.
.
</components>
</mainmenu>
Example 2
keys used: key_cmdactions, key_follow_up, key_set_privacy_level
<mainmenu>
<components>
.
.
.
<component>
<id>cmpActions</id>
<name>key_cmdactions</name>
<visiblemodes>read,edit</visiblemodes>
<elements>
<menu>
<id>menuActions</id>
<name>key_actions</name>
<visiblemodes>read,edit</visiblemodes>
<menuitems>
<modal>
<id>mdlFollowUp</id>
<name>key_follow_up</name>
<visibilityconditions>
'[[getValue,java.lang.String,lifeCycleState]]'=='COMPLETED'
</visibilityconditions>
.
.
.
</modal>
<modal>
<id>mdlSetPrivacyLevel</id>
<name>key_set_privacy_level</name>
<visiblemodes>read</visiblemodes>
.
.
.
</modal>
</menuitems>
</menu>
</elements>
</component>
</components>
</mainmenu>
Components
Component name tag should always contain a key in order for its value to be translated by the glossary mechanism.
Example
keys used: key_key_dates
<component>
<id>cmpKeyDates</id>
<name>key_key_dates</name>
<isgroup>true</isgroup>
<columns>4</columns>
<elements>
.
.
.
</elements>
</component>
Elements
When defining an element, label, sidelabel, tipexpression tags must contain only keys in order for their values to be translated by the glossary mechanism.
Label Example
keys used: key_type
<elements>
<selectbox>
<id>slbType</id>
<label>key_type</label>
.
.
.
</selectbox>
</elements>
Sidelabel Example
keys used: key_allow_creating_access_tokens_with_no_identifier_and_pass_code
<elements>
<checkbox>
<id>chkOnAllowNoIdentifierPassCode</id>
<sidelabel>key_allow_creating_access_tokens_with_no_identifier_and_pass_code</sidelabel>
.
.
.
</checkbox>
</elements>
Tipexpression Example
keys used: key_tipexpression_rewards_award_expiration_run_definition_cmp_award_expired_x_days_ago
<elements>
<textbox>
<id>txtAwardExpiredXDaysAgo</id>
<tipexpression>key_tipexpression_rewards_award_expiration_run_definition_cmp_award_expired_x_days_ago</tipexpression>
.
.
.
</textbox>
</elements>
Layout File
In the data entry layout files, all name and instruction tags must contain only keys in order for their values to be translated by the glossary mechanism.
Section
The following example demonstrates how to make use of the glossary mechanism when defining a section in order for its name and instructions to be translated.
Section Example
keys used: key_main_information, key_instruction_segments_segment_sec_main_information
<sections>
<section>
<id>secMainInformation</id>
<name>key_main_information</name>
<instruction>key_instruction_segments_segment_sec_main_information</instruction>
.
.
.
</section>
</sections>
Search Pages
This section shows how to use the Glossary Mechanism when creating search pages.
When implementing a search page, the following rules must be followed:
- searchcaption and label tags should always contain a key in order for their values to be translated by the glossary mechanism.
- displaytype tag should make use of keys to define the available search criterion options.
Search Page Example
keys used: key_search_accounts_receivable, key_life_cycle_state, key_active, key_suspended, key_terminated
<searchcaption>key_search_accounts_receivable</searchcaption>
.
.
.
<fields>
<fielditem>
<field>ACCOUNTSRECEIVABLE.LIFECYCLESTATE</field>
<label>key_life_cycle_state</label>
<expression>VALUE</expression>
<datatype>ftXString</datatype>
<fieldlen>10</fieldlen>
<searchcriteria>1</searchcriteria>
<visible>1</visible>
<executable>1</executable>
<displaytype>combobox;;;ACTIVE;key_active;SUSPENDED;key_suspended;TERMINATED;key_terminated</displaytype>
<indexorder>50</indexorder>
</fielditem>
.
.
.
</fields>
.
.
.
Dashboards
This section shows how to use the Glossary Mechanism when creating dashboards.
When implementing a dashboard, the following rules must be followed:
- name, description, primaryfieldlabel, groupbyfieldlabel and caption tags should always contain a key in order for their values to be translated by the glossary mechanism.
- fixedlookup should make use of a key to define the value that will be displayed when no option is selected from the drop-down list and no filtering is to be made based on the search field.
Search Page Example
keys used: key_buy_in_advance_requests_per_duration_and_subscription_type, key_buy_in_advance_requests_per_duration_and_subscription_type_stacked_bar_chart, key_number_of_buy_in_advance_requests, key_view_buy_in_advance_requests_of, key_duraition, key_Subscription_type, key_all
<dashboardcomponent>
<name>key_buy_in_advance_requests_per_duration_and_subscription_type</name>
<description>key_buy_in_advance_requests_per_duration_and_subscription_type_stacked_bar_chart</description>
<primaryfieldlabel>key_number_of_buy_in_advance_requests</primaryfieldlabel>
<groupbyfieldlabel>key_duration,_subscription_type</groupbyfieldlabel>
.
.
.
<fields>
<field>
<fieldname>BUYINADVANCE_PERIOD</fieldname>
<caption>key_view_buy_in_advance_requests_of</caption>
<summary>true</summary>
<filter>true</filter>
<fixedlookup>ejb/CRMUIBillDashboard.getBuyInAdvanceRequestsPerDurationAndSubscriptionTypePeriodOptions:key_all</fixedlookup>
<filtertextoption>equal</filtertextoption>
</field>
</fields>
.
.
.
</dashboardcomponent>
Fields
This section shows how to use the Glossary Mechanism when defining metadata fields.
When defining metadata fields name tag should always contain a key in order for its value to be translated by the glossary mechanism.
Metadata Fields Example
keys used: key_number, key_description
<mainfield>
<id>number</id>
<name>key_number</name>
.
.
.
</mainfield>
<fields>
<field>
<id>description</id>
<name>key_description</name>
</field>
.
.
.
</fields>
.
.
.
Entities
This section shows how to use the Glossary Mechanism when defining metadata entities.
When defining metadata entities name tag should always contain a key in order for its value to be translated by the glossary mechanism.
Entity Example
keys used: key_account_classification
<entity>
<id>ACCCLASSIFICATIONS</id>
<name>key_account_classification</name>
.
.
.
</entity>
Messages
This section shows how to use the Glossary Mechanism when defining metadata messages.
When defining metadata messages, expression tag should always contain a key in order for its value to be translated by the glossary mechanism.
Message Example
keys used: key_com_crm_exception_mandatoryfieldexception
<message>
<code>COM.CRM.EXCEPTION.MANDATORYFIELDEXCEPTION</code>
<expression>key_com_crm_exception_mandatoryfieldexception</expression>
<description>A mandatory field is not specified.</description>
</message>
Applications
This section shows how to use the Glossary Mechanism when defining metadata applications.
When defining metadata applications, applicationdescription tag should always contain a key in order for its value to be translated by the glossary mechanism.
Application Example
keys used: key_the_rewards_application.
<applications>
<application>
<applicationid>REWARDS</applicationid>
<applicationname>REWARDS</applicationname>
<applicationdescription>key_the_rewards_application.</applicationdescription>
</application>
.
.
.
</applications>
This section shows how to use the Glossary Mechanism when defining metadata menu options.
When defining metadata menu options, name and description tags should always contain a key in order for their values to be translated by the glossary mechanism.
Menu Option Example
keys used: key_manage_rewards_participants
<menuoptions>
<menuoption>
<id>MANAGE_REWARD_PARTICIPANTS</id>
<name>key_manage_rewards_participants</name>
<description>key_manage_rewards_participants</description>
<menuoptionparentid>REWARDS</menuoptionparentid>
<menuoptionordernum>3</menuoptionordernum>
<menuoptionurl>page.do?act=summary&xml=rewards/participants</menuoptionurl>
</menuoption>
.
.
.
</menuoptions>
Modules
This section shows how to use the Glossary Mechanism when defining metadata modules.
When defining metadata modules, modulename, moduledescription, featurename, featuredescription, name and description tags should always contain a key in order for their values to be translated by the glossary mechanism.
Module example
keys used: key_rewards, key_rewards_module_description
<modules>
<module>
<moduleid>REWARDS</moduleid>
<modulename>key_rewards</modulename>
<moduledescription>key_rewards_module_description</moduledescription>
.
.
.
</module>
.
.
.
</modules>
Common processes
The following example demonstrates how to make use of the glossary mechanism when defining the common processes of a module.
Module common processes example
keys used: key_create_reward_scheme, key_create_a_new_reward_scheme.
<commonprocesses>
<process>
<id>CREATE_REWARD_SCHEME</id>
<name>key_create_reward_scheme</name>
<description>key_create_a_new_reward_scheme.</description>
.
.
.
</process>
.
.
.
</commonprocesses>
Additional processes
The following example demonstrates how to make use of the glossary mechanism when defining the additional processes of a module.
Module additional processes example
keys used: key_activate_reward_scheme, key_activate_a_reward_scheme.
<additionalprocesses>
<process>
<id>ACTIVATE_REWARD_SCHEME</id>
<name>key_activate_reward_scheme</name>
<description>key_activate_a_reward_scheme.</description>
.
.
.
</process>
.
.
.
</additionalprocesses>
Dashboard components
The following example demonstrates how to make use of the glossary mechanism when defining the additional processes of a module.
Module dashboard components example
keys used: key_rewards_participants_per_scheme_bar_chart
<dashboardcomponents>
<dashboardcomponent>
<id>PARTICIPANTS_PER_SCHEME</id>
<name>key_rewards_participants_per_scheme_bar_chart</name>
<description>key_rewards_participants_per_scheme_bar_chart</description>
<filename>rewards/participantsPerScheme</filename>
</dashboardcomponent>
.
.
.
</dashboardcomponents>
Reports
The following example demonstrates how to make use of the glossary mechanism when defining the reports of a module.
Module reports example
keys used: key_rewards_participants_balance, key_view_the_wallet_balance_of_each_effective_rewards_participant
<reports>
<report>
<id>REWARDPARTICIPANT_BALANCE_REPORT</id>
<name>key_rewards_participants_balance</name>
<description>key_view_the_wallet_balance_of_each_effective_rewards_participant</description>
<reportfilename>Rewards/Participants_Balance.crxml</reportfilename>
</report>
.
.
.
</reports>
Web APIs
The following example demonstrates how to make use of the glossary mechanism when defining the web APIs of a module.
Note: In Web API's case the name tag should contain the method's name which will not be translated.
Module Web APIs Example
keys used: key_show_rewards_award_transactions_web_api
<webapis>
<webapi>
<id>REWARD_AWARD_TRANSACTIONS_SHOW</id>
<name>reward_transactions/awards/show</name>
<description>key_show_rewards_award_transactions_web_api</description>
<classname>CRMAPIRewardTransactionBean</classname>
<method>awardsShow</method>
</webapi>
.
.
.
</webapis>
Printouts
The following example demonstrates how to make use of the glossary mechanism when defining the printouts of a module.
Module printouts example
keys used: key_warranty, key_view_the_warranty_policy_printout
<printouts>
<printout>
<id>WARRANTY_PRINTOUT</id>
<name>key_warranty</name>
<description>key_view_the_warranty_policy_printout</description>
<printoutfilename>InstalledItems/warranty_policy_printout.jrxml</printoutfilename>
<entityid>INSTALLEDITEMS</entityid>
</printout>
.
.
.
</printouts>
Exceptions
This section shows how to use the Glossary Mechanism when creating exceptions.
The following examples demonstrate how to make use of the glossary mechanism when defining and throw an
Defining an exception example
1. Create the exception class.
public class OnlyOneRecordException extends CRMValidationException {
/**
* Only one %1 %2 must be specified.
*
* @param crmSession - the session object
* @param value1 - the exception first value
* @param value2 - the exception second value
* @throws Exception
*/
public OnlyOneRecordException(CRMSession crmSession, String value1,String value2) throws Exception {
super();
ArrayList<String> parameters = new ArrayList<String>();
parameters.add(value1);
parameters.add(value2);
try
{
setMessage(this.getClass().getName().toUpperCase(), crmSession, parameters);
}
catch (Exception e)
{
e.printStackTrace();
}
}
}
2. Define the exception in the messages.xmlfile. Use a unique key for the expression tag. Keys used: key_com_crm_exception_onlyonerecordexception
<messages>
<message>
<code>COM.CRM.EXCEPTION.ONLYONERECORDEXCEPTION</code>
<expression>key_com_crm_exception_onlyonerecordexception</expression>
<description>Only one record must be specified.</description>
</message>
.
.
.
</messages>
3. Define the exception in the properties file, by using the expression tag key defined in metadata messages file as the entry key, and specifying the exception message.
<properties>
<entry key="key_com_crm_exception_onlyonerecordexception">Only one %1 %2 must be specified.</entry>
.
.
.
</properties>
Thowing an exception example
A key should be used for every exception input parameter that needs to be translated. Keys used: key_email_type
if (emailTypes.contains(emailDto.getType().toString()))
{
throw new OnlyOneRecordException(getCRMSession(), "key_email_type",emailDto.getType().getLabel());
}
Questions
This section shows how to use the Glossary Mechanism when creating questions.
Question example
keys used: key_invoice, key_confirm_financial_transaction_saved_as_posted
question code used: CONFIRM_FINANCIAL_TRANSACTION_SAVED_AS_POSTED
1. Use showConfirmQuestion method to display the confirmation question.
public CRMDOInvoice postInvoiceButton(CRMDOInvoice invoice)throws Exception{
showConfirmQuestion(
"CRMUIInvoice",
"postInvoice",
"CONFIRM_FINANCIAL_TRANSACTION_SAVED_AS_POSTED",
new String[]{"key_invoice"});
return invoice;
}
2. Define the question code in metadata messages file.
<messages>
<message>
<code>CONFIRM_FINANCIAL_TRANSACTION_SAVED_AS_POSTED</code>
<expression>key_confirm_financial_transaction_saved_as_posted</expression>
<description>Confirm Action</description>
</message>
</messages>
3. Define the question in the properties file, by using the expression tag key defined in metadata messages file as the entry key, and specifying the question message.
<properties>
<entry key="key_confirm_financial_transaction_saved_as_posted">%1 is going to be saved as Posted. Do you wish to continue?</entry>
.
.
.
</properties>
This section shows how to use the Glossary Mechanism when creating informational messages.
Informational message example
keys used: key_access_token_passcode_reset_success_msg
informatinal message code used: ACCESS_TOKEN_PASSCODE_RESET_SUCCESS_MSG
1. Use showInfoMessage method to display the informational message.
public CRMDOAccessToken resetPassCode(CRMDOAccessToken accessToken) throws Exception {
...
InfoMessage infoMsg = new InfoMessage(getCRMSession(),
"ACCESS_TOKEN_PASSCODE_RESET_SUCCESS_MSG",
new String[]{ accessToken.getAlias("passCodeAfterReset").toString() },
getCRMSession().getRealPath(),
getOrganisationID());
showInfoMessage(infoMsg);
...
}
2. Define the question code in metadata messages file.
<messages>
<message>
<code>ACCESS_TOKEN_PASSCODE_RESET_SUCCESS_MSG</code>
<expression>key_access_token_passcode_reset_success_msg</expression>
<description>Access token pass code has been reset successfully</description>
</message>
</messages>
3. Define the informational message in the properties file, by using the expression tag key defined in metadata messages file as the entry key, and specifying the message.
<properties>
<entry key="key_access_token_passcode_reset_success_msg">The access token pass code has been reset to %1.</entry>
.
.
.
</properties>
String Concatenation
This section shows how to use the Glossary Mechanism when concatenating strings.
String concatenation example
keys used: key_rule
Use getTranslation method to get the translation of the different strings you want to concatenate.
public CustomerEventAutomation addPaymentMediumTypeAutomationButton(CRMDOCustomerEventDefinition customerEventDefinition) throws Exception {
PaymentMediumTypeAutomation paymentMediumTypeAutomation = new PaymentMediumTypeAutomation();
...
paymentMediumTypeAutomation.setRuleName(getCRMSession().getTranslation("key_rule")+" "+ruleNumber);
customerEventAutomation.setPaymentMediumTypeAutomation(paymentMediumTypeAutomation);
return customerEventAutomation;
}
Mandatory Fields
This section shows how to use the Glossary Mechanism when defining mandatory while creating business object classes.
Mandatory fields example
keys used: key_website
@Override
protected LinkedHashMap<String, String> getMandatoryFields(CRMDO dto) throws Exception {
LinkedHashMap<String, String> mandatoryFields = new LinkedHashMap<String, String>();
mandatoryFields.putAll(super.getMandatoryFields(dto));
mandatoryFields.put("key_website", "website");
return mandatoryFields;
}