3 Creating Tax Codes
In Oracle Communications Billing and Revenue Management (BRM), you use tax codes to assign taxes to the products and services that you sell to your customers. For example, you use tax codes to apply taxes differently for usage and physical goods charges.
Topics in this document:
About Creating Tax Codes
Tax codes define which tax to apply to a charge. For example, a telephone handset uses a different tax code than an online service subscription. The tax code identifies the tax amount or percentage to apply for each jurisdiction.
You can configure tax codes in the following ways:
-
Using the PDC UI. See "Creating Tax Codes" in PDC Online Help.
-
Using the ImportExportPricing utility. See "Creating Tax Codes Using ImportExportPricing".
After you finish creating tax codes, you can associate them with your charges, discounts, and chargeshares.
You can also assign tax codes to charges, discounts, and chargeshares using tax selectors. Tax selectors decide the tax code to apply based on account, service, event, and profile attributes. You can create tax selectors in the following ways:
-
Using the PDC UI. For information, see "Creating a Tax Selector" in PDC Online Help.
-
Using the ImportExportPricing utility. For information, see "Creating Tax Selectors Using ImportExportPricing".
Creating Tax Codes Using ImportExportPricing
You create tax codes in PDC and publish them to BRM and Elastic Charging Engine (ECE) using the ImportExportPricing utility.
To implement tax codes:
- Define your tax codes in an XML file. You can base your tax codes on
those provided in the Sample_Tax_Code.xml file available in the
PDC_home/apps/Samples/Examples directory, where PDC_home is
the directory in which the PDC software is installed.
The sample file contains examples of tax codes for calculating taxes based on a custom implementation or Vertex. For more information about XML elements specific to Vertex or custom tax codes, see:
- Import the XML file into PDC using the ImportExportPricing
utility:
ImportExportPricing -import -config MyTaxCodes.xml
where MyTaxCodes is the name of the XML file where you defined the tax codes.
You can also modify existing tax codes using the -ow parameter.
See "Importing Pricing and Setup Components" and "ImportExportPricing" in PDC Creating Product Offerings for more information about the utility's syntax and parameters.
The ImportExportPricing utility also publishes the tax codes to the real-time rating engine (RRE) and ECE.
Note:
You cannot publish tax codes to the batch rating engine (BRE). -
Map your tax codes to G/L IDs in ECE. Do the following for each tax code you configured in MyTaxCodes.xml:
-
Access the ECE configuration MBeans in a JMX editor, such as JConsole. See "Accessing ECE Configuration MBeans" in ECE Implementing Charging for more information.
-
Expand the ECE Configuration node.
-
Expand charging.taxation.
-
Expand Operations.
-
Click addTaxDetails.
-
Specify values for the following attributes:
-
taxCode: Enter a tax code. The tax code must match a value in the <code> element of your MyTaxCodes.xml file.
-
taxGlId: Enter the General Ledger ID to use for the tax impact.
-
-
Creating Tax Codes for a Flat Tax or Custom Implementation
You implement simple flat taxes by defining them in an XML file that you import into PDC. In the file, you enter a tax code and assign it to one or more tax rates, which are differentiated by criteria such as validity date and jurisdiction.
The following XML example shows custom tax codes:
<taxCodes> <name>CustomTaxCode</name> <priceListName>Default</priceListName> <obsolete>false</obsolete> <code>CustomTaxCode</code> <taxPackageType>CUSTOM</taxPackageType> <taxCodeValidityPeriods> <validFrom>20220101</validFrom> <validTo>20230120</validTo> <taxCodeMaps> <description>TRS1</description> <percent>4.0</percent> <taxJurisdictionLevel>FEDERAL</taxJurisdictionLevel> <taxJurisdictions>US</taxJurisdictions> <taxRuleType>TAX</taxRuleType> </taxCodeMaps> </taxCodeValidityPeriods> <taxCodeValidityPeriods> <validFrom>20240101</validFrom> <validTo>20300120</validTo> <taxCodeMaps> <description>TRS2</description> <percent>8.0</percent> <taxJurisdictionLevel>LOCATION</taxJurisdictionLevel> <taxJurisdictions>EU</taxJurisdictions> <taxRuleType>INCLUSIVE</taxRuleType> </taxCodeMaps> <taxCodeMaps> <description>TRS3</description> <percent>8.0</percent> <taxJurisdictionLevel>LOCATION</taxJurisdictionLevel> <taxJurisdictions>ASIA</taxJurisdictions> <taxRuleType>NCS</taxRuleType> </taxCodeMaps> </taxCodeValidityPeriods> </taxCodes>
- <percent>: If you include this element, the elements described in Table 3-1 are also required.
- <transType_CategoryCode_Rate>: If you include this element, no other elements are supported in the tax code map.
Table 3-1 describes the critical XML elements specific to custom tax codes.
Table 3-1 XML Elements in the Tax Code File for Custom Tax Codes
Element | Description |
---|---|
code | The tax code. A unique alphanumeric value that defines categories with different tax treatments. |
taxPackageType | The package type. For flat taxes and custom implementations, this is always CUSTOM. |
validFrom | The start date of the validity period for the tax rate in
yyyymmdd format.
Note: You can use multiple validity periods to create different rates for a single tax code, as shown in the example, but the validity periods must not overlap. |
validTo | The end date of the validity period for the tax rate in yyyymmdd format. |
description | A brief description of the tax code. |
percent | The tax rate in percent. For example, 4.25 means
4.25%.
For prepaid purchase events that grant negative currency balances, the corresponding tax associated with it should also be negative. For example, -4.25. |
taxJurisdictionLevel | The jurisdiction level for which this rate is applicable. Values are FEDERAL, STATE, COUNTY, CITY, and LOCATION. |
taxJurisdictions |
The jurisdiction where the rate applies. Similar to a nexus for the corresponding jurisdiction level. For example, if the taxJurisdictionLevel value is STATE, the taxJurisdictions values must be state-level jurisdictions. |
taxRuleType |
Determines how taxes will be computed. Values are:
|
Creating Tax Codes for Vertex
You specify to calculate taxes using Vertex by mapping tax codes to Vertex product codes in an XML file that you import into PDC. The Vertex product codes are used to apply the tax rate.
The following XML example shows the two types of Vertex tax codes. The three elements under the taxCodeMaps element are the only ones supported for Vertex tax codes.
<taxCodes> <name>VQTaxCode</name> <priceListName>Default</priceListName> <obsolete>false</obsolete> <code>VQTaxCode</code> <taxPackageType>VERTEX_QUANTUM</taxPackageType> <taxCodeValidityPeriods> <taxCodeMaps> <transType_CategoryCode_Rate>01</transType_CategoryCode_Rate> <transSubType_ServiceCode>01</transSubType_ServiceCode> <salesIndicator>SALE</salesIndicator> </taxCodeMaps> </taxCodeValidityPeriods> </taxCodes> <taxCodes> <name>VCTaxCode</name> <priceListName>Default</priceListName> <obsolete>false</obsolete> <code>VCTaxCode</code> <taxPackageType>VERTEX_COMMTAX_21</taxPackageType> <taxCodeValidityPeriods> <taxCodeMaps> <transType_CategoryCode_Rate>4</transType_CategoryCode_Rate> <transSubType_ServiceCode>2</transSubType_ServiceCode> <salesIndicator>SALE</salesIndicator> </taxCodeMaps> </taxCodeValidityPeriods> </taxCodes>
Table 3-2 describes the important XML elements specific to Vertex tax codes.
Table 3-2 XML Elements in the Tax Code File for Vertex
Element | Explanation |
---|---|
code | The tax code. A unique alphanumeric value that defines categories with different tax treatments. |
taxPackageType | The tax package you use:
|
transType_CategoryCode_Rate | The field value is determined by the tax package you use.
|
transSubType_ServiceCode | The field value is determined by the tax package you use.
|
salesIndicator | For Vertex Communications Tax Q Series and Vertex Sales Tax Q Series, this is the resale flag field, which indicates if the charge offer is for sale (SALE) or resale (RESALE). The default is SALE. |
See your tax package documentation for information about product codes, service codes, and service indicators.
When configuring Vertex tax calculation, you also need to configure tax suppliers. See "Creating Tax Suppliers".
Creating Tax Selectors Using ImportExportPricing
You can create tax selectors in an XML file and publish them to PDC, BRM, and ECE using the ImportExportPricing utility.
To implement tax selectors using ImportExportPricing:
-
Define your tax selectors in an XML file. You can base them on the sample tax selectors provided in the PDC_home/apps/Samples/Examples/SampleTaxSelector.xml file.
See "Creating an XML File for Tax Selectors" for more information about the XML elements in the file.
-
Import the XML file into PDC using the ImportExportPricing utility:
ImportExportPricing -import -pricing MyTaxSelectors.xml
where MyTaxSelectors is the name of the XML file where you defined the tax selectors.
The ImportExportPricing utility publishes the tax selectors to the PDC database, real-time rating engine (RRE), and ECE.
Note:
You cannot publish tax selectors to the batch rating engine (BRE).Creating an XML File for Tax Selectors
You can implement tax selectors by defining them in an XML file that you import into PDC. In the file, you enter a tax selector and then define the rules for assigning tax codes to charges, discounts, and chargeshares.
The following sample XML shows how to create tax selectors:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><pdc:PricingObjectsJXB xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing"> <taxSelector xmlns:pdc="http://xmlns.oracle.com/communications/platform/model/pricing"> <name>Sample_TAX_SELECTOR</name> <description>Sample TAX_SELECTOR</description> <pricingProfileName>Convergent Usage</pricingProfileName> <priceListName>Default</priceListName> <obsolete>false</obsolete> <stereoType>TAX_SELECTOR</stereoType> <productSpecName>TelcoGsmSms</productSpecName> <eventSpecName>EventDelayedSessionTelcoGsm</eventSpecName> <validityPeriod> <validFrom>0</validFrom> <rule> <name>Rule1</name> <result> <resultName>VAT</resultName> </result> <fieldToValueExpression> <operation>REGEX</operation> <seperator>;</seperator> <fieldName>EventDelayedSessionTelcoGsm.CALLED_ID</fieldName> <fieldValue>1800.*</fieldValue> <fieldKind>EVENT_SPEC_FIELD</fieldKind> </fieldToValueExpression> </rule> <rule> <name>Rule2</name> <result> <resultName>toll</resultName> </result> <fieldToValueExpression> <operation>REGEX</operation> <seperator>;</seperator> <fieldName>EventDelayedSessionTelcoGsm.CALLED_ID</fieldName> <fieldValue>.*</fieldValue> <fieldKind>EVENT_SPEC_FIELD</fieldKind> </fieldToValueExpression> </rule> </validityPeriod> </taxSelector></pdc:PricingObjectsJXB>
Table 3-3 describes the important XML elements specific to tax selectors.
Table 3-3 XML Elements in the Tax Selector File
Element | Description |
---|---|
name | The name of the tax selector. |
description | A description of the tax selector. |
pricingProfileName |
The pricing profile to associate with the tax selector. |
priceListName | The name of the price list to which the selector applies. |
stereoType | The type of pricing object: TAX_SELECTOR. |
productSpecName |
The service type to which the tax selector applies. |
eventSpecName |
The event type to which the tax selector applies. |
validityPeriod |
Indicates when the rules in the tax selector are valid. The default effective period starts immediately and never ends. |
name |
The name of a rule. |
resultName | The name of the tax code to apply when all criteria in the rule are met. |
operation | The operator to apply, which is dependent on the field. The valid values are: REGEX, EQUAL_TO, NOT_EQUAL_TO, GREATER_THAN, GREATER_THAN_EQUAL, LESS_THAN, LESS_THAN_EQUAL, IN_LIST, and MAPS_TO. |
seperator |
The character that is used to separate the field values, such as a semicolon (;). |
fieldName |
The name of the field to evaluate. |
fieldValue |
The required value of the field. |
fieldKind |
The type of attributes to be selected for assigning the tax code. The valid values are: EVENT_SPEC_FIELD, PRODUCT_SPEC_FIELD, CUSTOMER_SPEC_FIELD, and PROFILE_SPEC_FIELD. |