Skip Headers
Oracle® Communications Billing and Revenue Management Calculating Taxes
Release 7.5

E16722-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

3 Setting Up Tax Calculation for Taxware

This chapter describes how to set up your Oracle Communications Billing and Revenue Management (BRM) system to use Taxware Sales and Use and Taxware WorldTax tax calculation.

To use Taxware Sales and Use and Taxware WorldTax calculation with BRM, you must install Taxware Manager.

Important:

Taxware Manager is an optional feature that you install separately.

See "About Calculating Taxes" for more information about calculating taxes.

See "Customizing Tax Calculation" for more information about customizing the Taxware Data Manager (DM).

Migrating Taxware Data Files

If you already use Taxware, you need to migrate your Taxware data files. Contact Taxware for information on automating the migration process.

Installing Taxware Manager

To install Taxware Manager, see "Installing Tax Calculation Managers" in BRM Installation Guide.

Installing the Taxware software

Install the Taxware software on the same machine as the Taxware DM. See the Taxware documentation.

Configuring the Taxware DM

To configure the Taxware DM, you must complete the following tasks:

See the Taxware DM configuration file for more information about its contents.

For more information about configuration file, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.

Replacing the Common API Shared Library Stubs

In the BRM_Home/lib directory, replace the Common API (CAPI) shared library stubs, libtaxcommono and libworldtax, with the following files provided by Taxware.

  • Use files with extension .so for Linux and Solaris.

    • libsalesusetax

    • libstep

    • libverazip

    • libworldtax

    • libtaxcommono

  • For AIX, copy the .so versions of the following files into the BRM_Home/lib directory.

    • libsalesusetax

    • libstep

    • libverazip

    • libworldtax

    In addition, move libtaxcommono.so and a second copy of libworldtax.so into BRM_Home/lib and change the file extensions to .a. You should have two versions of libworldtax (one with extension .so and one with extension .a), and one version of libtaxcommono (with extension .a).

    Important:

    Do not use the .a versions of these files supplied by Taxware.

    You must then replace the stub versions of these libraries with the Taxware libraries.

Specifying the Taxware Input and Output Files

When you install the Taxware software, you set the environment variables for the Taxware input and output files. These environment variables specify file paths used by Taxware. You also need to specify these file paths in the Taxware DM configuration file.

  1. Open the Taxware DM configuration file (BRM_Home/sys/dm_taxware/pin.conf).

  2. Edit the lines in the Taxware Environment Variable Paths section.

    For example:

    - dm_taxware      home          Taxware_Home
    - dm_taxware      utl           Taxware_Home/utl
    - dm_taxware      audit         Taxware_Home/audit
    - dm_taxware      indata        Taxware_Home/indata
    - dm_taxware      outdata       Taxware_Home/outdata
    - dm_taxware      st_indata     Taxware_Home/indata
    - dm_taxware      st_outdata    Taxware_Home/outdata
    - dm_taxware      vz_indata     Taxware_Home/indata
    - dm_taxware      vz_outdata    Taxware_Home/outdata
    - dm_taxware      temp          Taxware_Home/temp
    #- dm_taxware     wt_indata     Taxware_Home/indata
    #- dm_taxware     wt_outdata    Taxware_Home/outdata
    #- dm_taxware     wt_lang       ENG
    #- dm_taxware     wt_country    US
    

    Important:

    You must comment out the entries for Taxware programs you don't use. For example, if you don't use WorldTax, comment out the wt_ entries.
  3. Save and close the file.

  4. Stop and restart the Taxware DM.

    For more information, see the discussion of starting and stopping the BRM system in BRM System Administrator's Guide.

Specifying the Point of Title Passage

When calculating taxes, the point of title passage indicates whether the title to tangible property is transferred at the ship-from location (origin) or at the ship-to location (destination). In almost all cases, the point of title passage is the destination.

To specify the point of title passage:

  1. Open the Taxware DM configuration file (BRM_Home/sys/dm_taxware/pin.conf).

  2. Change the title entry:

    • To set the point of title passage to the point of destination, enter the letter D. This is the default.

    • To set the point of title to the point of origin, enter the letter O.

    For example:

    - dm_taxware title D
      
    
  3. Save and close the file.

  4. Stop and restart the Taxware DM.

    See the discussion of starting and stopping BRM in BRM System Administrator's Guide.

Configuring the CM for Taxware Tax Calculation

You configure the Connection Manager (CM) for Taxware tax calculation by editing the CM configuration file (pin.conf). For more information on editing configuration files, see "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide.

When you configure the CM, you complete these tasks:

Specifying Connection Entries

When you install BRM, you specify connection entries. You must change these entries if you change the Taxware database number, the host name, or the port number of the Taxware DM.

To specify the Taxware DM connection entry:

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

  2. Edit the dm_pointer entry.

    - cm  dm_pointer  database  ip  hostname  port
      
    

    where:

    • database is the database number, such as 0.0.0.1.

    • hostname is the IP address or host name of the computer on which the DM is installed.

    • port is the port number of the DM service.

    The database number, host name, and port number must match the values in the Taxware DM configuration file.

  3. Edit the taxware_db entry.

    - fm_rate  taxware_db  Taxware_Homedatabase  /_tax_db  0
      
    

    where database is the database number specified in the Taxware DM configuration file.

  4. Save and close the file.

You don't need to restart the CM to enable these entries.

Specifying whether to Validate ZIP Codes

If there is an error in an account's ZIP code, Taxware will return a tax amount of 0. If you set up Taxware to validate ZIP codes at registration, you ensure that taxes are calculated correctly. This option specifies that Taxware checks the state and ZIP code when an account is created. If the ZIP code is not valid, customer registration cannot be completed.

Important:

If you enable this option, the Taxware DM must be running when customers register. If the connection to Taxware is off line, you can change this option to skip validating ZIP codes. This allows customers to register.

To specify whether to validate ZIP codes:

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

  2. Edit the tax_valid entry.

    Note:

    Make sure that dm_taxware is running.
    • To enable ZIP code validation for Taxware Sales and Use, enter 1.

    • To enable ZIP code validation for Taxware WorldTax, enter 2.

    • To disable ZIP code validation, enter 0. This is the default.

  3. Save and close the file.

You don't need to restart the CM to enable this entry.

Defining a Default Ship-From Locale

This option provides a ship-from locale in case a tax supplier can't be found. You need to define at least one tax supplier. See "About Tax Suppliers" for more information.

To define a default ship-from locale:

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

  2. Edit the provider_loc entry. For example:

    - fm_rate_pol provider_loc Middletown; CA; 95222; USA
      
    
  3. Save and close the file.

The new value becomes effective immediately and all subsequent tax calculations use the new address. You don't need to restart the CM.

Specifying How to Calculate Taxes

You use the cycle_tax_interval entry to determine whether deferred taxes are calculated separately for a parent and its subordinate (nonpaying) child accounts or are consolidated into a single tax item for both the parent and child accounts. See "About Tax Calculation for Account Groups" for more information.

Important:

Regardless of the option you select for the entry, Bill Now always rolls activities for each subordinate bill unit into the parent bill unit and calculates taxes for the parent only. The single tax item for the parent includes taxes from both the parent and subordinate bill units.

To specify how to calculate taxes:

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

  2. Edit the cycle_tax_interval entry:

    • To forward the tax from the child account to the parent account, enter billing. BRM calculates taxes for the parent account only, but the single tax item on the parent account includes taxes from both the parent and child accounts.

    • To calculate the taxes separately for the parent and child accounts, enter accounting. BRM lists the taxes as separate items on the parent bill.

    For example:

    - fm_bill  cycle_tax_interval  billing
      
    
  3. Save and close the file.

  4. Stop and restart the CM.

    For more information, see the discussion of starting and stopping the BRM system in BRM System Administrator's Guide.

Specifying the Location of the tax_supplier_map File

If you create a tax_supplier_map file, you need to include its location in the CM configuration (pin.conf) file. If you don't create the file, you don't need this entry. See "About Tax Suppliers" and "Creating a tax_supplier_map File" for more information.

To specify the location of the tax_supplier_map file:

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

  2. Edit the tax_supplier_map entry to include the complete path to the tax_supplier_map file.

    For example:

    - fm_rate  tax_suppier_map BRM_Home/sys/cm/tax_supplier_map
      
    
  3. Save and close the file.

  4. Stop and restart the CM.

    For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Specifying the Location of the taxcodes_map File

You use the taxcodes_map file to map tax codes to Taxware products. See "About Specifying Tax Codes" for more information.

To specify the location of the taxcodes_map file:

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

  2. Edit the taxcodes_map entry to specify the complete path to the taxcodes_map file.

    For example:

    - fm_rate  taxcodes_map  BRM_Home/sys/cm/taxcodes_map
      
    
  3. Save and close the file.

  4. Stop and restart the CM.

    For more information, see the discussion of starting and stopping the BRM system in BRM System Administrator's Guide.

Setting Up Tax Supplier Information in the Taxware Database

If you plan to use Taxware files as the primary source of tax supplier information, you must use the Taxware toolkits to set up tax supplier information in the Taxware database.

  • For the Sales and Use program, create NEXPRO files.

  • For the WorldTax program, create company profiles and registration files.

For more information about using Taxware toolkits, see the Taxware documentation.

See "About Tax Suppliers" for more information about tax suppliers.

Note:

  • If you store all the information necessary to calculate taxes in the BRM database, you don't need to register with Taxware. However, you might receive warnings when Taxware calculates taxes.

  • If you use Taxware Sales and Use or Taxware WorldTax as standalone applications outside of the BRM system, storing information in Taxware files enables you to use that data in both Taxware and BRM.

Setting Up Tax Supplier Information in the BRM Database

To set up tax suppliers:

Defining Tax Suppliers

To define tax suppliers, edit the BRM_Home/sys/data/config/pin_tax_supplier.xml file. See "About Defining Tax Suppliers" for more information.

Creating a tax_supplier_map File

See "Allowing Your Sales and Use Tax Software to Determine Tax Supplier Data" for information about the tax_supplier_map file.

  1. Create the tax_supplier_map file, for example:

    Product     ShipTo   Company ID      Business Loc  ShipFrom               Reg
    _____________________________________________________________________________
    user_code : ;;;US  : Tax supplier1 : loc_1       : Cupertino;CA;95014;US :0
    usage     : ;;;US  : Tax supplier1 : loc_1       : Cupertino;CA;95014;US :0
    usage     : ;;;FR  : Tax supplier2 : loc_2       : Paris;;;FR            :1
      
    

    See Table 3-1 for an explanation of the tax_supplier_map file.

  2. Edit the CM configuration file (BRM_Home/sys/cm/pin.conf) to supply the location of the tax_supplier_map file.

    See "Specifying the Location of the tax_supplier_map File" for more information.

  3. Save and close the file.

  4. Stop and restart the CM.

    For more information, see the discussion of starting and stopping the BRM system in BRM System Administrator's Guide.

Table 3-1 tax_supplier_map File Entries

Entry Description

Product

The name of the product for which taxes will be calculated. Product names are defined in your price list. For more information, see "Setting Up Price List Data" in BRM Setting Up Pricing and Rating.

ShipTo

The address to which the product is shipped (your customer's location). Enter the address in this format:

city;state;zip;country

You can leave portions of this string blank, but you must include the semi-colons for each address element.

Examples:

  • ;;;US

  • ;CA;95003;US

In most cases, you don't need to enter the city. See the Taxware documentation for correct state and country entries.

Company ID

The company ID specified in the Taxware NEXPRO file or company file. This name is also entered in the PIN_FLD_NAME field when you define tax suppliers, and is displayed in Pricing Center.

Business Loc

The business location specified in the Taxware NEXPRO file or company file. This value indicates which location should be considered when taxes are calculated.

ShipFrom

The address the product is shipped from. Enter the address in this format:

city;state;zip;country

You can leave portions of this string blank, but you must include the semi-colons for each address element.

Examples:

  • ;;;US

  • ;CA;95003;US

See the Taxware documentation for correct state and country entries.

Regulated

Not used by Taxware.


Configuring Tax Codes

See "About Specifying Tax Codes" for information about tax codes.

To create the taxcodes_map file, you need the following information:

  • The names you will use for tax codes.

  • The corresponding Taxware product codes.

  • For Sales and Use, the Taxware service indicator.

  • For WorldTax, the Taxware commodity/service indicator.

For information about Taxware product codes and service indicators, see the Taxware documentation.

To configure the taxcodes_map file:

  1. Open the taxcodes_map file.

    BRM_Home/sys/cm is the default location. To change the name and location of the taxcodes_map file, see "Specifying the Location of the taxcodes_map File" for details.

  2. Edit the file.

    For example:

    # Taxcode          Pkg    Code1    Code2    Si    Wt_code   Cmdty_code
    # ------------------------------------------------------------------
    usage            :  T  :  85000 :  85000 :  S  :         :
    cycle            :  T  :  61000 :  61000 :  S  :         :
    # t_shirt        :  T  :    899 :    899 :     :         :
    # modem_rent     :  T  :   1234 :   1234 :  R  :         :
      
    

    For an explanation of an entry, see the taxcodes_map file.

  3. Save and close the file.

  4. Stop and restart the CM.

    For more information, see the discussion of starting and stopping the BRM system in BRM System Administrator's Guide.

Verifying That Taxes Are Being Calculated

After you have installed and configured the Taxware software, you can run the following test to verify that the Taxware software is calculating taxes:

Important:

The PIN_FLD_TAX_CODE value determines which tax package to use. This value is defined in the taxcodes_map file and is required to calculate taxes successfully. See "Configuring Tax Codes" for more information.
  1. Create a text file named T502_40 with the following contents:

    0 PIN_FLD_POID                   POID [0] 0.0.0.1 /account 1 1
    0 PIN_FLD_END_T                TSTAMP [0] (938224941) Fri Sep 24 19:02:21 1999
    0 PIN_FLD_ACCOUNT_NO              STR [0] "ROOT"
    0 PIN_FLD_CURRENCY                INT [0] 840
    0 PIN_FLD_CURRENCY_NAME           STR [0] "USD"
    0 PIN_FLD_TAXES                 ARRAY [0] allocated 20, used 10
    1     PIN_FLD_TAX_CODE            STR [0] "interTaxware"
    1     PIN_FLD_AMOUNT_TAXED    DECIMAL [0] 20
    1     PIN_FLD_GL_ID               INT [0] 0
    1     PIN_FLD_SHIP_TO             STR [0] "Cupertino;CA;95014;US;[408572,2,1]"
    1     PIN_FLD_SHIP_FROM           STR [0] "Denver; CO; 80205;US;[303279,2,1]"
    1     PIN_FLD_ORDER_ORIGIN        STR [0] ""
    1     PIN_FLD_ORDER_ACCEPT        STR [0] ""
    1     PIN_FLD_INTERNATIONAL_IND   INT [0] 1
    1     PIN_FLD_LOCATION_MODE      ENUM [0] 2
    1     PIN_FLD_ELAPSED_TIME     TSTAMP [0] (249)
    0 PIN_FLD_VAT_CERT                STR [0] ""
    0 PIN_FLD_INCORPORATED_FLAG      ENUM [0] 0
    0 PIN_FLD_RESIDENCE_FLAG         ENUM [0] 0
    0 PIN_FLD_REGULATED_FLAG         ENUM [0] 
      
    
  2. Save the text file to the BRM_Home/setup/scripts directory.

  3. Start dm_taxware.

  4. Run testnap in the BRM_Home/setup/scripts directory to verify that the taxes are being calculated:

    testnap
    r T502_40 1
    xop 502 0 1
    

    Note:

    502 is the opcode reference for PIN_FLD_RATE_TAX_CALC.