Introduction
This guide outlines configuration and administration options with respect to locales, tax data, currencies and exchange rates. This document is addressed to system administrators or DevOps who configure and maintain Intershop Commerce Management instances.
Info
Prior to Intershop version 7.7 the information provided in this document were part of the Administration and Configuration Guide that can be found in the Knowledge Base.
In Intershop Commerce Management, locales, tax data, currencies and exchange rates are configured centrally by the system administrator, using a set of *.properties files. The system checks these configurations on application server startup. In case new configurations are detected, or changes to existing ones, the system automatically triggers the necessary updates, inserts, or deletions in the database.
Note
All relevant setup options are to be configured in advance via dedicated deployment script files, before actually executing the deployment. So be aware that if you modify the Intershop Commerce Management configuration after it is deployed, the next deployment will override all changes with the settings specified for your deployment.
Glossary
| Concept | Description |
|---|---|
| locale | Locale refers to a set of parameters that defines the user's language, country and any special variant preferences that users expect to see in their user interface. |
| localization | Localization is the process of adapting internationalized software for a specific region or language by adding locale-specific components and translating text. Localization (which is potentially performed multiple times, for different locales) uses the infrastructure or flexibility provided by internationalization. |
| internationalization | Internationalization is the process of designing a software application so that it can potentially be adapted to various languages and regions without engineering changes. It is an integral part of ongoing development. Internationalization must consider different languages and writing systems, different numeral systems, punctuation etc., as well as different economic conventions, including variations in number formats, address formats, currencies, systems of measurement, etc. |
References
You should be familiar with the main concepts of the Intershop Commerce Management infrastructure. Refer to Overview - Infrastructure, Scaling and Performance.
For development-related information about locales and currencies, refer to Cookbook - Locales and Currencies.
Server Start Pipeline
The update mechanism for locales, tax data, currencies and exchange rates is based on a set of pipelines which are executed on server startup. The initial pipeline to start the update mechanism is configured in the <IS.INSTANCE.SHARE>/system/config/cluster/appserver.properties, using the following entry:
intershop.pipelines.ExecuteUponServerStart = DefaultServerStartPipeline-Start
In a standard installation, this pipeline is already configured.
Prepare Locales
Locale Configuration Files
To add one or more locales and/or to set a new lead locale, you must create
- the file localization.properties that lists the new locales
- for every new locale, a formats configuration file <ISOLanguageCode>_<ISOCountryCode>.properties (such as en_US.properties.)
The files are stored in <IS.INSTANCE.SHARE>/system/config/cluster/.
Check the example files in <IS.INSTANCE.SHARE>/system/config/cluster/, including localization.properties.example, de_DE.properties.example, en_GB.properties.example and en_US.properties.example.
Add Locale
The configuration file localization.properties lists the locales to be added to the system in the following syntax
key = <ISOLanguageCode> <ISOCountryCode> <ISOCurrencyCode> <usedAsLeadLocale>
for example,
japanese = ja JP JPY false
Set Lead Locale
To set a new lead locale, use the last argument usedAsLeadLocale of the locale key, as defined in localization.properties, setting it true. Following the example above, use the following key to set Japanese as the new lead locale:
japanese = ja JP JPY true
Caution
Only change the lead locale at project start, otherwise applications will no longer be visible in the back office.
Delete Locale
To delete existing locales, use the key deleteLocales in localization.properties. Each locale to be deleted must be identified by its ISOLanguageCode and ISOCountryCode joined by an underscore.
To delete Japanese and German, for example, use
deleteLocales = ja_JP de_DE
Set Locale-Specific Patterns
The configuration files <ISOLanguageCode>_<ISOCountryCode>.properties list format patterns for numbers, date, etc. to be used in the corresponding locale. The syntax of the patterns is identical to that documented in the JDK API specification for the classes DecimalFormat and SimpleDateFormat.
When adding a locale, adjust the patterns according to this locale and save the file as, for example, ru_RU.properties in <IS.INSTANCE.SHARE>/system/config/cluster/.
Note
*Pattern keys. To define the characters to be displayed, use the *GroupingCharacter and *DecimalSeparator keys. In addition, escape non-ASCII characters with their UCN entities.A locale configuration file for Russian may look, accordingly, like this:
decimalNegativePattern = - #,##0.0######### decimalPositivePattern = #,##0.0######### decimalGroupingCharacter = \u0020 decimalDecimalSeparator = , shortCurrencyNegativePattern = - #,##0.00######## shortCurrencyPositivePattern = #,##0.00######## # currency symbol longCurrencyNegativePattern = - #,##0.00######## * longCurrencyPositivePattern = #,##0.00######## * # currency ISO code mnemonic # longCurrencyNegativePattern = - #,##0.00######## M # longCurrencyPositivePattern = #,##0.00######## M currencyGroupingCharacter = \u0020 currencyDecimalSeparator = , longDatePattern = dd.MM.yyyy shortDatePattern = dd.MM.yyyy timePattern = HH:mm:ss dateTimeAMString = dateTimePMString = integerNegativePattern = -#,##0 integerPositivePattern = #,##0 integerGroupingCharacter = \u0020 integerDecimalCharacter = , shortQuantityNegativePattern = - #,##0.########## shortQuantityPositivePattern = #,##0.########## longQuantityNegativePattern = - #,##0.########## * longQuantityPositivePattern = #,##0.########## * quantityGroupingCharacter = \u0020 quantityDecimalCharacter = , inputDecimalNegativePattern = -#,##0.0######### inputDecimalPositivePattern = #,##0.0######### inputCurrencyNegativePattern = -#,##0.00######## inputCurrencyPositivePattern = #,##0.00######## inputDatePattern = dd.MM.yyyy inputTimePattern = HH:mm inputDateTimePattern = dd.MM.yyyy HH:mm inputIntegerNegativePattern = -#,##0 inputIntegerPositivePattern = #,##0 inputQuantityNegativePattern = -#,##0.########## inputQuantityPositivePattern = #,##0.########## inputDatePatternUserHint = \u0434\u0434.\u043c\u043c.\u0433\u0433\u0433\u0433 inputTimePatternUserHint = \u0447\u0447:\u043c\u043c impexDateTimePattern = dd.MM.yyyy HH:mm:ss
Locale Update Process
Upon adding a new locale, the system creates the "last modified" marker file <IS.INSTANCE.SHARE>/system/config/cluster/localization.lastupdate. This file records the "last modified" time and a backup of the actual configuration file for comparison at the next server start. If localization.properties is changed, the database will be updated again; if, however, the comparison does not indicate any changes, no action will be taken.
Prepare Tax Data Sets
Tax data sets can be configured for one or more channels or organizations, and define tax jurisdictions, tax jurisdiction mappings to countries and states, tax classes, a tax rate matrix and tax data set sharing relationships.
Note
Tax Data Configuration Files
To update tax data in the database at server start, you must create the file taxdataset.properties in <IS.INSTANCE.SHARE>/system/config/cluster/.
This file comprises five sections: channel/organization specification, tax jurisdictions and country/state mappings, tax classes, tax rates, and tax sharing relationships.
The syntax is described below.
Channel/Organization Specification
Key | Description |
|---|---|
Default.channel Default.organization | Used to specify either the default channel or the default organization to which the tax data belong (optional). If not specified, each jurisdiction and tax class must be specifically assigned to a channel or organization. |
Tax Jurisdiction and Country/State Mappings
<jid> is an identifier to group the attributes for one tax jurisdiction.
Key | Description |
|---|---|
Jurisdiction.<jid>.name | Specifies the name for the tax jurisdiction |
Jurisdiction.<jid>.channel | Specifies either the channel to which the tax jurisdiction belongs If different from Default.channel or the organization to which the tax jurisdiction belongs if different from Default.organization (optional). |
Jurisdiction.<jid>.default | Specifies whether this is the default jurisdiction, false if not specified (optional) |
Jurisdiction.<jid>.mapping.<n>.country | Specifies a jurisdiction-country assignment Make sure to specify all relevant names, identifiers etc. that may occur in your system for each country, like Germany and DE for Germany. |
Jurisdiction.<jid>.mapping.<n>.state | Specifies a jurisdiction-state assignment (optional) |
Tax Classes
<cid> serves as tax class ID. It is also used as an identifier to group the attributes for a tax class.
Key | Description |
|---|---|
Class.<cid>.code | Specifies the tax class code |
Class.<cid>.name | Specifies the name of the tax class |
Class.<cid>.channel | Specifies either the channel to which the tax class belongs If different from Default.channel or the organization to which the tax class belongs if different from Default.organization (optional). |
Class.<cid>.description | Specifies a short description of the tax class. |
Class.<cid>.default | Specifies whether this is the default tax class, false if not specified (optional). |
Tax Rates
Key | Description |
|---|---|
Rate.<jid>.<cid>.value | Specifies the tax rate in the format xx.yyy, e.g., for 7.5%, set 0.075 |
Rate.<jid>.<cid>.validfrom | Specifies a valid-from date in the dd.mm.yyyy, e.g., 16.01.2004 Optional when |
Rate.<jid>.<cid>.previous | Specifies an optional tax rate valid previous to |
Tax Data Sharing
Each relationship needs to define:
- The channel or organization from which the data is shared, and
- The channel or organization to which the data is being shared.
Sharing the same tax data set with more than one channel(s)/organization(s) requires the definition of multiple relationships.
Note
Note that an identifier (<id>) is used to group sharing relationships.
Key | Description |
|---|---|
Sharing.<id>.from.channel | Specifies either the channel or the organization that provides its tax data set to other channels/organizations |
Sharing.<id>.to.channel | Specifies either the channel or the organization that uses the tax data set provided by other channels/organizations |
Sharing.<id>.relationDefinitionName | Specifies the relation definition name, either TAX_CLASS or TAX_JURISDICTION |
Example Configuration File
The following lines illustrate the tax data settings using one of Intershop Commerce Management's demo channels as an example.
# ### 1. Domain specification ####### Default.channel=PrimeTech-PrimeTechSpecials # ### 2. Tax Jurisdictions ########## Jurisdiction.GERMANY.name=Germany Jurisdiction.GERMANY.default=true Jurisdiction.GERMANY.mapping.1.country=Germany Jurisdiction.GERMANY.mapping.2.country=DE Jurisdiction.OTHER.name=Outside Germany # ### 3. Tax Classes ################ Class.NORMAL.name=FullTax Class.NORMAL.description=Full Tax charged Class.NORMAL.default=true Class.REDUCED.name=ReducedTax Class.REDUCED.description=Reduced Tax charged Class.ZERO.name=NoTax Class.ZERO.description=No Tax charged # ### 4. Tax Rates ################## Rate.GERMANY.NORMAL.value=0.19 Rate.GERMANY.REDUCED.value=0.07 Rate.GERMANY.ZERO.value=0.0 Rate.OTHER.NORMAL.value=0.0 # ### 5. Sharing tax data sets ###### Sharing.1.from.channel=PrimeTech-PrimeTechSpecials Sharing.1.to.channel=PrimeTech-ResellerChannel
Tax Data Update Process
Upon setting new tax data for a domain, the system creates the "last modified" marker file <IS.INSTANCE.SHARE>/system/config/cluster/taxdataset.lastupdate. This file records the "last modified" time and a backup of the current configuration file for comparison at the next server start. If taxdataset.properties is changed, the database will be updated again. If, however, the comparison does not indicate any changes, no action will be taken.
Prepare Currencies
The currency configuration file lists those currencies that should be enabled in the server, and, optionally, names a currency to be set as the lead currency.
Currency Configuration File
To update currency information in the database at server start, you must create the file activecurrencies.properties in <IS.INSTANCE.SHARE>/system/config/cluster/.
This file lists the enabled currencies in the following syntax:
ActiveCurrency.<n>=<ISOCurrencyCode>
To enable a new lead currency, set
LeadCurrency=<ISOCurrencyCode>
A complete currency configuration file could look like this:
# Specifies which currencies should be set active LeadCurrency=EUR ActiveCurrency.1=GBP ActiveCurrency.2=EUR
Applying this file to a standard Intershop Commerce Management installation, the currency EUR would replace USD as lead currency and USD would be no longer be listed as an active currency in the system.
Currency Update Process
Upon setting new currencies, the system creates the "last modified" marker file <IS.INSTANCE.SHARE>/system/config/cluster/activecurrencies.lastupdate. This file records the "last modified" time and a backup of the actual configuration file for comparison at the next server start. If activecurrencies.properties is changed, the database will be updated again; if, however, the comparison does not indicate any changes, no action will be taken.
Back-Office Currency Precision Configuration
The price display precision in the back office is configurable for each used currency. It is set via DBInit with the PrepareCurrencies preparer of the core cartridge, which reads the required values from the file currencies.resource, located in core/javasource/com/intershop/beehive/core/dbinit/data/currency.
This file contains comma-separated entries for each currency, and the last value specifies the rounding and display precision.
978;EUR;\u20AC;\u20AC;Euro;c;Cent;100;0.01;2;
The default precision value set for EUR is 2, so a value of 10.124, for example, is automatically rounded and displayed in the back office as 10.12.
Prepare Exchange Rates
The exchange rate configuration file lists those exchange rates that should be enabled in the server. The items listed in the file are inserted into or updated in the database as appropriate.
Exchange Rate Configuration File
To update exchange rates in the database at server start, you must create the file exchangerates.properties in <IS.INSTANCE.SHARE>/system/config/cluster/.
This file lists the enabled exchange rates in the following syntax:
ExchangeRate.<n>.From=<ISOCurrencyCode> ExchangeRate.<n>.To =<ISOCurrencyCode> ExchangeRate.<n>.Rate=a.b
where a.b is the from-to exchange rate with a dot (.) as decimal separator. For example, the following file
ExchangeRate.1.From=EUR ExchangeRate.1.To =GBP ExchangeRate.1.Rate=0.67
would delete all existing exchange rates apart from EUR to GBP and change the existing EUR-GBP rate to 0.67 (1 EUR is worth 0.67 GBP).
Exchange Rate Update Process
Upon setting new exchange rates, the system creates the "last modified" marker file <IS.INSTANCE.SHARE>/system/config/cluster/exchangerates.lastupdate. This file records the "last modified" time and a backup of the actual configuration file for comparison at the next server start. If exchangerates.properties is changed, the database will be updated again; if, however, the comparison does not indicate any changes, no action will be taken.