Introduction

This guide explains how to define the tax data in the file $IS_HOME/share/system/config/cluster/taxdataset.properties. It describes the settings regarding tax classes and jurisdiction, 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 file $IS_HOME/share/system/config/cluster/taxdataset.properties 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 on the next application server startup. When the system detects a change in the file taxdataset.properties on 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 at 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 on the next application server start. If, after a server restart, no new taxdataset.lastupdate file is written, although the file taxdataset.properties was changed, check the error log and debug log for problems.

Changing Default Tax Data Sharing

By default, and independent from the settings in taxdataset.properties, every channel in the domain shares the tax classes and tax jurisdictions of the organization 'Operations'. This is hard coded into the pipeline logic for the channel creation. If you wish to change this behavior for one or all sites/organizations/repositories you have to overwrite the appropriate creation hook pipeline. These are the relevant 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

Properties File Syntax

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

The syntax used in the file is described in the comments at the beginning of the file $IS_HOME/share/system/config/cluster/taxdataset.properties.example. Here are some hints on how to use these properties:

1. <ID>
   This ID can be any string. By this ID, the tax data set preparer identifies which properties belong to one definition of the given type. These IDs are also used to map the jurisdiction and class assignments into the tax rates. This ID itself is not stored into the database.

2. Default channel OR organization
   It is not actually necessary to have a default channel/organization, but to have it allows 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.

   Note

   The default defined here is NOT used as default source when a new channel is created!

3. 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 cover the values to indicate the country that are stored in COUNTRYCODE field of the table BASICADDRESS (until 7.7) respectively CUSTOMERADDRESS

4. Either domain OR organization OR channel:
   For tax jurisdictions or tax classes, you can define in which domain the tax data should be created:

   • organization has to refer to an existing organization
   • domain may refer to any existing domain of any type
   • channel refers to the default channel domain of an existing channel
   The data (tax jurisdictions or tax classes) will be created in just one domain.

   You can have only one of these properties per ID. If none of these properties is given, the data for this domain will be created in the default domain/organization.
   If channel is given, the data will be created in the channel default domain, and sharing relations to site and organization will be created.

5. Sharing tax data sets
   relationDefinitionName: Can be either TAX_CLASS or TAX_JURISDICTION. If omitted both tax relations will be created.

   Sharing tax data sets

   # define the source domain:
   # either
   Sharing.<id>.from.channel=      {specify channel providing its tax data set}
   # or
   Sharing.<id>.from.organization= {specify organization providing its tax data set}
   # define the target:
   # either
   Sharing.<id>.to.channel=        {specify channel to use the provided tax data set}
   # or
   Sharing.<id>.to.organization=   {specify organization to use the tax data set}

   Relations have always to be defined directly from the source to the target. No sharing over several steps is allowed.

   If the target is a channel, relations for all three channel domains (site, repository, organization) are created.

taxdataset.properties Settings in the Out of the Box Installation

• The default organization is Operations.
• The tax classes are defined system wide in the organization Operations.
• The tax jurisdictions are defined system wide in the organization Operations.
• 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.

Define Domain Specific Tax Data

If domain specific tax data settings are required the usual procedure is:

1. Find out which data are system wide and which are domain specific.
2. Define one channel or organization as the default channel/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 happen to define settings for Operations, these settings will be applied for every newly created channel or (business channel) customer organization.

In case that newly created organizations need other settings, define them in the taxdataset.properties and restart the system (see Taxation Data Auto-Update Mechanism)

Example for a Taxdataset With Domain Specific Tax Jurisdictions and Global Tax Classes

The organization structure is like this:

TestTaxes is an organization with a partner channel MyPartner.

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 channel Operations.
4. The default tax jurisdictions are defined in the channel Operations.
5. There are separate jurisdictions defined for the organization AT.
6. There are separate jurisdictions defined for the organization DE.
7. The data of organization AT are shared to AT-MyATChannel and AT-OtherATChannel.
8. The data of organization DE 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 organization DE later, it would get the settings of Operations with US as default tax jurisdiction on creation. To change these to the DE organization channel, the taxdataset.properties would have to be updated, and a sharing relation from the organization DE to the new channel had to be configured similar to the existing ones.

See attached file taxdataset.properties.

Query the Database for the Current Tax Settings

Here are some helpful queries to check which data really were prepared:

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