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.

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.

translation_eng.properties

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

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

Life Cycle State Search Field

<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

Life Cycle State Summary Field

<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

Billing Information Drill Down

<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

Summary page actions

<actions>
		<action>
			<caption>key_new</caption>
			<topmenu>true</topmenu>
			<link>page.do?xml=communications/communication&amp;act=new&amp;jndi=ejb/CRMUICommunication&amp;fc=createButton&amp;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

Data entry page title

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

New menu option

<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

Actions menu option

<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

<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

Selectbox element

<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

checkbox element

<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

textbox element

<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

section

<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

search page

<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

search page

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

Metadata

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

metadata fields

<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

<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

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

Application

<applications>
	<application>
			<applicationid>REWARDS</applicationid>
			<applicationname>REWARDS</applicationname>
			<applicationdescription>key_the_rewards_application.</applicationdescription>
	</application>
	.
	.
	.
</applications>

Menu options

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

Menu Option

<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&amp;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

Module

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

Module common process

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

Module additional process

<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

Module dashboard component

<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

Module report

<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

Module 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

Module 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 exception.

Defining an exception example

1. Create the exception class.

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

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

translation_eng.properties

<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

Throwing Exception

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.

Show 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.xml

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

translation_eng.properties

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

Informational Messages

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.

Show 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.xml

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

translation_eng.properties

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

Get translation

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

CRMBOWebCustomerEventBean

@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;
}

Use Glossary Mechanism

General Idea

Properties File

Summary Pages

Search Fields

Summary Fields

Actions

Data Entry Pages

Definition File

Title

Main Menu

Components

Elements

Layout File

Section

Search Pages

Dashboards

Metadata

Fields

Entities

Messages

Applications

Menu options

Modules

Common processes

Additional processes

Dashboard components

Reports

Web APIs

Printouts

Exceptions

Questions

Informational Messages

String Concatenation

Mandatory Fields