Introduction

This guide explains how to define tax data in the $IS_HOME/share/system/config/cluster/taxdataset.properties file. It describes tax classes and jurisdiction settings, the usage, and how to share taxation data. It also describes how to check the current settings in the database.

Taxation Data Auto-Update Mechanism

The $IS_HOME/share/system/config/cluster/taxdataset.properties file is the central point where tax classes, tax rates, and tax jurisdictions are defined in the system. Every change of this file triggers an update of the tax-related database entries during the next application server startup. When the system detects a change in the taxdataset.properties file during startup, it applies the settings and creates a file named taxdataset.lastupdate in the same directory. This file contains information about the last update so that the system can recognize whether an update needs to be performed during the next system startup. That file should never be modified manually. However, it may be deleted to force the system to apply the taxdataset.properties settings during the next application server start. If, after a server restart, no new taxdataset.lastupdate file is written, although the taxdataset.properties file has been changed, check the error log and debug log for problems.

Properties File Syntax

The default settings can be completely overwritten by the settings in the taxdataset.properties file.

Channel or Organization Specification

It is not necessary to have a default channel/organization, but having it allows you to omit the channel/organization/domain assignment from the different entries for the tax class and tax jurisdiction definitions for those that are commonly used.

Specify the default channel, domain, or organization to which jurisdictions and tax classes should belong. If not specified, each jurisdiction and tax class must be assigned to a specific channel, domain, or organization. If both are specified, the specific assignment takes precedence over the default one.

Channel or Organization Specification

Default.channel=                        {EITHER optional: name of default channel}
Default.organization=                   {OR     optional: name of default organization}
Default.domain=                         {OR     optional: name of default domain}

Tax Jurisdictions

For tax jurisdictions, it is necessary to define aliases (mappings), so that every possible different way to have the jurisdiction name in the address table can be assigned to the right jurisdiction.

The country name mappings should include the values that indicate the country stored in the COUNTRYCODE field of the BASICADDRESS (until 7.7) and CUSTOMERADDRESS tables.

Any number of jurisdictions may be specified, distinguished using different {id}s. If a jurisdiction does not belong to the Default.channel/.organization, one of Jurisdiction.{id}.channel/.domain/.organization must be specified. Any number of country/state assignments may be defined, distinguished using numbers {int}. Values must match the actually used values in addresses.

Tax Jurisdictions

Jurisdiction.{id}.name=                 {name of tax jurisdiction}
Jurisdiction.{id}.channel=              {EITHER optional: name of channel to which jurisdiction belongs, fallback to Default.channel/.domain/.organization}
Jurisdiction.{id}.organization=         {OR     optional: name of organization to which jurisdiction belongs, fallback to Default.channel/.domain/.organization}
Jurisdiction.{id}.domain=               {OR     optional: domain to which jurisdiction belongs, fallback to Default.channel/.domain/.organization}
Jurisdiction.{id}.default={true|false}  {optional: whether this is the default jurisdiction, false if not specified}
Jurisdiction.{id}.mapping.{int}.country={optional: jurisdiction-country assignment - must be given if state is given}
Jurisdiction.{id}.mapping.{int}.state=  {optional: jurisdiction-state assignment}

Tax Classes

Any number of classes may be specified, distinguished using different {id}s. If the class does not belong to Default.channel/.domain/.organization, one of Class.{id}.channel/.organization must be specified.

Tax Classes

Class.{id}.code=                        {code of tax class, the ID via that objects like products are assigned to this class}
Class.{id}.name=                        {name of tax class}
Class.{id}.channel=                     {EITHER optional: name of channel to which class belongs, fallback to Default.channel/.domain/.organization}
Class.{id}.organization=                {OR     optional: name of organization to which class belongs, fallback to Default.channel/.domain/.organization}
Class.{id}.domain=                      {OR     optional: domain to which class belongs, fallback to Default.channel/.domain/.organization}
Class.{id}.description=                 {description of tax class}
Class.{id}.default={true|false}         {optional: whether this is the default tax class, false if not specified}

Tax Rates

A tax rate may be defined for each jurisdiction/tax class pair. The jurisdictions and tax classes are identified using their {id}s.

Tax Rates

Rate.{jurisdiction id}.{class id}.value=    {xx.yyy eg 7.5%=0.075, tax rate valid from .validfrom if given}
Rate.{jurisdiction id}.{class id}.validfrom={dd.mm.yyyy e.g 16.01.2004 optional date when .previous rate becomes invalid and .value becomes valid}
Rate.{jurisdiction id}.{class id}.previous= {xx.yyy eg 7.5%=0.075, optional tax rate valid previous to validfrom date}

Sharing Tax Data Sets

If desired, a tax data set belonging to one channel/domain/organization can be shared with one or more other channels/domains/organizations. Each sharing relationship is distinguished using an {id}. It is important to note that tax data sets can only be shared by defining direct relations. Sharing a tax data set involves specifying the source that provides the tax data set and the target that uses the tax data set. It is also possible to mix up these properties, for example, sharing from an organization to a channel.

Sharing Tax Data Sets

Sharing.{id}.from.channel=              {EITHER specify channel providing its tax data set}  
Sharing.{id}.to.channel=                {AND specify channel using the tax data set}  
Sharing.{id}.from.organization=         {OR     specify organization providing its tax data set}  
Sharing.{id}.to.organization=           {AND     specify organization using its tax data set} 
Sharing.{id}.from.domain=               {OR     specify domain providing its tax data set}  
Sharing.{id}.to.domain=                 {AND     specify domain using its tax data set}  
Sharing.{id}.relationDefinitionName=    {the relation definition name, either TAX_CLASS or TAX_JURISDICTION - If omitted both tax relations will be created.}

Tax Data Sharing

taxdataset.properties: Settings in the Out-of-the-Box Installation

• The default organization is Operations.

• The tax classes are defined system-wide in the Operations organization.

• The tax jurisdictions are defined system-wide in the Operations organization.

• No sharing definitions are needed, because the default relations ensure that everything is shared from Operations.

These settings can be applied in all systems where the same tax data are valid for every channel and organization.

Changing Default Tax Data Sharing

By default, every channel in the domain shares the tax classes and tax jurisdictions of the Operations organization, regardless of the settings in taxdataset.properties. This is hard coded into the pipeline logic for the channel creation. To change this behavior for one or all sites/organizations/repositories, overwrite the appropriate creation hook pipeline. These are the relevant pipeline descriptor files:

Pipeline Descriptor Files

sld_ch_partner_plugin/staticfiles/cartridge/pipelines/CreateSiteHook.xml
sld_ch_sf_base/staticfiles/cartridge/pipelines/CreateSiteHook.xml
sld_enterprise_app/staticfiles/cartridge/pipelines/CreateSiteHook.xml
sld_ch_partner_plugin/staticfiles/cartridge/pipelines/CreateRepositoryHook.pipeline
sld_ch_b2c_base/staticfiles/cartridge/pipelines/CreateConsumerOrganization.pipeline
sld_ch_partner_plugin/staticfiles/cartridge/pipelines/CreatePartnerOrganization.pipeline
sld_enterprise_app/staticfiles/cartridge/pipelines/CreateSalesOrganization.pipeline
sld_ch_consumer_plugin/staticfiles/cartridge/pipelines/CreateSalesChannel.pipeline

Define Domain Specific Tax Data

To configure domain-specific tax data settings, follow these steps:

1. Find out which data are system-wide and which are domain-specific.

2. Define one channel or organization as the default channel or organization.

3. Define all system-wide settings for this domain.

4. Define different settings for single channels/organizations as needed.

5. Propagate the tax data by defining the appropriate sharing relations.

If the default domain is not Operations, make sure that every organization/channel in the system, that needs tax data, has them defined or shares them from somewhere. If you additionally define settings for Operations, these settings will be applied for every newly created channel (business channel) or customer organization.

If newly created organizations require additional settings, define them in taxdataset.properties and restart the system (see Taxation Data Auto-Update Mechanism).

Example for a Tax Data Set with Domain Specific Tax Jurisdictions and Global Tax Classes

The organization structure is as follows:

TestTaxes is an organization with the MyPartner partner channel.

MyPartner has two partner organizations, one for Germany (DE) and one for Austria (AT). The DE organization has channels that have the German tax jurisdiction as default jurisdiction. At the moment there is just one channel. The AT organization has channels that have the Austrian tax jurisdiction as default jurisdiction. At the moment there are two channels.

In parallel, there still exists inSPIRED, which has the US tax jurisdiction as default.

1. Tax classes are shared throughout the system (FullTax, ReducedTax and NoTax).

2. The default organization is Operations.

3. The tax classes are defined in the Operations channel.

4. The default tax jurisdictions are defined in the Operations channel.

5. There are separate jurisdictions defined for the AT organization.

6. There are separate jurisdictions defined for the DE organization.

7. The data of the AT organization are shared to AT-MyATChannel and AT-OtherATChannel.

8. The data of the DE organization are shared to DE-MyDEChannel.

9. Tax rates are defined for all combinations of tax jurisdictions and classes.

If, for example, a different channel is created for the DE organization in the future, it will inherit the Operations settings with US as the default tax jurisdiction. To change these to the DE organization channel, update taxdataset.properties and configure a sharing relation from the DE organization to the new channel similar to the existing ones.

See attached taxdataset.properties file.

Query the Database for the Current Tax Settings

Here are some useful queries to verify which data were prepared:

Useful Queries

-- In which domains are the tax classes in my system defined?
SELECT domainname, b.* 
FROM basictaxclass b, domaininformation d
WHERE d.domainid = b.domainid;

-- In which domains are the tax jurisdictions in my system defined?
SELECT domainname, b.* 
FROM taxjurisdiction b, domaininformation d
WHERE d.domainid = b.domainid;

-- Which Domain shares which tax data whereto?
SELECT d2.domainname FromDomain, d1.domainname ToDomain, relationdefinitionname, r.lastmodified 
FROM relation r, domaininformation d1, domaininformation d2
WHERE relationdefinitionname like 'TAX%'
AND d1.domainid = domain1_ID
AND d2.domainid = domain2_ID;

--Which country names are defined for which domain in the basic address table? (until ICM 7.7)
SELECT DISTINCT di.domainname, ba.countrycode, ba.state
FROM basicaddress ba, domaininformation di
WHERE di.domainid = ba.domainid
ORDER BY domainname, countrycode;

--Which country names are defined for which domain in the customer address table? (since version ICM 7.8)
SELECT DISTINCT di.domainname, ca.countrycode
FROM customeraddress ca, domaininformation di
WHERE di.domainid = ca.domainid
ORDER BY domainname, countrycode;

-- select default tax classes
SELECT domainname,tc.name, tcc.* 
FROM basictaxclassCONFIG tcc, basictaxclass tc, domaininformation di
where tcc.defaulttaxclassid = tc.uuid
and tcc.domainid = di.domainid

-- select default tax jurisdictions
SELECT domainname,tj.name, tjc.* 
FROM TAXJURISDICTIONCONFIG tjc, taxjurisdiction tj, domaininformation di
WHERE tjc.defaulttaxjurisdictionid = tj.uuid
AND di.domainid = tjc.domainid