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

E16722-04
Go to Documentation Home
Home
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

4 Setting Up Tax Calculation for Vertex

This chapter describes how to set up your Oracle Communications Billing and Revenue Management system to use Vertex. BRM supports the following Vertex tax packages:

To use Vertex Sales Tax Q Series or Vertex Communications Tax Q Series with BRM, you must install one of the following:

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

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

Installing Vertex Manager or Vertex Quantum Manager

To install Vertex Manager or Vertex Quantum Manager, see "Installing Tax Calculation Managers" in BRM Installation Guide for more information.

Installing the Vertex Software

Install the Vertex Sales Tax Q Series and Communications Tax Q Series software on the same machine as the Vertex Data Manager (DM). The Vertex software must be installed, configured, and tested as indicated in the Vertex documentation before any attempt is made to configure the Vertex DM.

See the Vertex documentation for installation instructions. You can install either package or both.

Note:

The Sales Tax Q Series and Communications Tax Q Series database can reside in the same tablespace as the BRM database, but it is recommended that you create a new tablespace for it.

Write down the values you entered for the following when you installed the Vertex Sales Tax Q Series.

  • Datasource For Register Database

  • Server Name For Register Database

  • User Id For Register Database

  • Password For Register Database

These values are used later when you configure the pin.conf entries.

Configuring the Vertex Software

To configure the Vertex software, set up the Sales Tax Q Series or Communications Tax Q Series shared libraries as described in the following sections:

Configuring the Sales Tax Q Series Shared Libraries

Make sure the following libraries are in the BRM_Home/lib directory or in your $LD_LIBRARY_PATH. These are shared libraries that come with the Sales Tax Q Series software.

Use files with extension .so for HP-UX IA64, Linux, and Solaris:

  • libvst

  • libloc

  • libqutil

Note:

For AIX, change the extension of these files to .a.

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

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

Specifying Storage Manager Shared Library for Sales Tax Q Series

Table 4-1 lists the pin.conf entries in the BRM_Home/sys/dm_vertex/pin.conf file used to configure the Vertex DM for Sales Tax Q Series:

Table 4-1 pin.conf Entries for Vertex DM (Sales Tax Q Series)

Entry Description

quantumdb_source

The schema where the STQ tables reside.

Note: This parameter is required if the default tablespace for the user name and password parameters is not the same as the one that contains the STQ tables.

For Indexed Sequential Access Method (ISAM) databases, this parameter specifies the ISAM data file directory.

quantumdb_server

The network identifier for the database on the server.

For ISAM databases, this parameter should be commented out.

quantumdb_user

The user as a valid Oracle login name.

For ISAM databases, this parameter should be commented out.

quantumdb_passwd

The user password.

quantum_sm_obj

The Storage Manager shared library that the DM uses to interact with a particular version of the Vertex STQ system. To use

  • STQ 3.1.6, specify dm_vertex_stq316

  • STQ 3.2.21, specify dm_vertex_stq3221

  • STQ 4.0.6, specify dm_vertex_stq406


To specify the appropriate Storage Manager shared library, set the value for quantum_sm_obj entry in the pin.conf file for Vertex DM to the particular version of Vertex STQ that you intend to use:

  1. Open the Vertex DM configuration file (BRM_Home/sys/dm_vertex/pin.conf).

  2. Locate the quantum_sm_obj entry displayed in the following format in the file:

    - dm_vertex quantum_sm_obj ./dm_vertex_stqVersion${LIBRARYEXTENSION}
      
    

    where Version represents the STQ version.

    For example, the following entry specifies that the Vertex DM needs to use STQ 4.0.6.

    - dm_vertex quantum_sm_obj ./dm_vertex_stq406${LIBRARYEXTENSION}
      
    
  3. Save and close the file.

  4. Stop and restart the Vertex DM.

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

Configuring the Communications Tax Q Series Shared Libraries

Make sure the following libraries are in the BRM_Home/lib directory or in your $LD_LIBRARY_PATH. These are shared libraries that come with the Vertex Communications Tax Q Series software. Use files with extension .so for HP-UX IA64, Linux, and Solaris:

  • libadm

  • libcch

  • libcfg

  • libcli

  • libctq (For AIX only, change the extension of this file to .a.)

  • libctz

  • libdbcper

  • libgeo

  • libhsh

  • libobj

  • libreg

  • librpt

  • librte

  • libutl

  • libxmlparse

Specifying Storage Manager Shared Library for Communications Tax Q Series

Table 4-2 lists the pin.conf entries in the BRM_Home/sys/dm_vertex_pin_conf file used to configure the Vertex DM for Communications Tax Q Series:

Table 4-2 pin.conf Entries for Vertex DM (Communications Tax Q Series)

Entry Description

commtax_config_path

The location of Communications Tax Q Series configuration file (ctqcfg.xml).

The default location is CTQ_Home/vertex/cfg, where CTQ_Home is the directory where you installed the Vertex software.

commtax_config_name

The Communications Tax Q Series configuration name.

This name must match the configuration defined in the ctqcfg.xml file that is used with BRM.

See the Vertex documentation for more information about defining configurations.

commtax_sm_obj

The Storage Manager shared library that the DM uses to interact with a particular version of the Vertex CTQ system. To use

  • CTQ 1.01.06, specify dm_vertex_ctq10106

  • CTQ 1.00.13, specify dm_vertex_ctq10013

  • CTQ 2.00.05, specify dm_vertex_ctq20005


To specify the appropriate Storage Manager shared library, set the value for commtax_sm_obj entry in the pin.conf file for Vertex DM to the particular version of Vertex CTQ that you intend to use:

  1. Open the Vertex DM configuration file (BRM_Home/sys/dm_vertex/pin.conf).

  2. Locate the commtax_sm_obj entry displayed in the following format in the file:

    dm_vertex commtax_sm_obj ./dm_vertex_ctqVersion${LIBRARYEXTENSION}
      
    

    where Version represents the CTQ version.

    For example, the following entry specifies that the Vertex DM needs to use CTQ 2.00.05.

    dm_vertex commtax_sm_obj ./dm_vertex_ctq20005${LIBRARYEXTENSION}
      
    
  3. Save and close the file.

  4. Stop and restart the Vertex DM.

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

Configuring the Vertex DM

You use the Vertex DM configuration file (BRM_Home/sys/dm_vertex/pin.conf) to configure the DM. The file includes information for editing its contents. See "Using Configuration Files to Connect and Configure Components" in BRM System Administrator's Guide for information about configuration files.

The following procedures provide specific information about configuring the Vertex DM:

Configuring the Vertex DM for Sales Tax Q Series

You specify the required pin.conf entries in the BRM_Home/sys/dm_vertex/pin.conf file to configure the Vertex DM for Sales Tax Q Series:

  1. Open the Vertex DM configuration file (BRM_Home/sys/dm_vertex/pin.conf).

  2. Change the following entries according to the instructions in the file:

    - dm_vertex quantumdb_source tablespace_for_Sales_Tax_C_Series_tables
    - dm_vertex quantumdb_server database_name
    - dm_vertex quantumdb_user database_user
    - dm_vertex quantumdb_passwd database_user_password
      
    

    where:

    • the values for quantumdb_source, quantumdb_server, quantumdb_user, and quantumdb_passwd are the same values used when you installed the Sales Tax Q Series software. See "Installing the Vertex Software".

    • quantumdb_source is required if the default tablespace for the user ID and password parameters is not the same tablespace that contains the Sales Tax Q Series tables.

      Important:

      If the Vertex Sales Tax Q Series installation uses an ISAM database:
      • quantumdb_source should point to the ISAM data file directory (as opposed to the Oracle data source).

      • quantumdb_server, quantumdb_user, and quantumdb_passwd should be commented out.

      • dm_n_fe and dm_n_be should be set to 1 to prevent multi-threading. The ISAM version of Vertex does not support multi-threading.

  3. Save and close the file.

  4. Stop and restart the Vertex DM.

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

Configuring the Vertex DM for Communications Tax Q Series

You set the required pin.conf entries in the BRM_Home/sys/dm_vertex/pin.conf file to configure the Vertex DM for Communications Tax Q Series:

To configure the Vertex DM for Communications Tax Q Series:

  1. Open the Vertex DM configuration file (BRM_Home/sys/dm_vertex/pin.conf).

  2. Specify the path to the Communications Tax Q Series configuration file in the commtax_config_path entry.

    The following entry specifies the default path:

    - dm_vertex commtax_config_path CTQ_Home/vertex/cfg
      
    
  3. Specify the Communications Tax Q Series configuration name in the commtax_config_name entry.

    For example:

    - dm_vertex commtax_config_name CTQ_Test
      
    
  4. Save and close the file.

  5. Stop and restart the Vertex DM.

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

Setting up Tax Supplier Information

To set up tax suppliers in the BRM database:

Defining Tax Suppliers

To define tax suppliers, edit the BRM_Home/sys/data/config/pin_tax_supplier.xml file. See "Defining Tax Suppliers and Loading them into the BRM Database" for more information.

Providing Tax Supplier Data in a tax_supplier_map File

You provide tax supplier data in a tax_supplier_map file that you edit. See "Allowing Your Sales and Use Tax Software to Determine Tax Supplier Data" for more information.

Table 4-3 provides a list of the entries in the tax_supplier_map file.:

Table 4-3 Entries in tax_supplier_map File

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 the product is shipped to (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 semicolons for each address element.

Examples:

  • ;;;US

  • ;CA;95003;US

In most cases, you do not need to enter the city. See the Vertex documentation for correct state and country entries.

Company ID

The company ID specified in the Vertex TDM (Tax Decision Maker) or company file. This name is also entered in the PIN_FLD_NAME field when you define tax suppliers. It is also displayed in Pricing Center.

This entry must match the name exactly as entered in the TDM or company file. If you use the TDM, the entry will be a four-character code.

Business Loc

The business location specified in the Vertex TDM 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 semicolons for each address element.

Examples:

  • ;;;US

  • ;CA;95003;US

See the Vertex documentation for correct state and country entries.

Regulated

The flag that identifies the utility or company that is billing as regulated (0) or unregulated (1). Some taxes apply to regulated or unregulated utilities only; this flag determines which types of taxes are applied.


To create the tax_supplier_map file:

  1. Provide the necessary information on each tax supplier. See Table 4-3 for an explanation of 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
      
    
  2. Save and close the file.

  3. Edit the CM configuration file (BRM_Home/sys/cm/pin.conf) to supply 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 file. See "Specifying the Location of the tax_supplier_map File" for more information.

Specifying Divisions for Tax Suppliers

Some companies operate divisions with locations that can impact the tax calculation. Use the Business Loc column in the tax_supplier_map file to add information about divisions for tax suppliers. The data in this column is mapped to the Division field in Sales Tax Q Series. This data should match what is stored in the Sales Tax Q Series TDM database.

For example, suppose the tax supplier Acme has two divisions, one in California and one in Illinois. You can configure the tax_supplier_map file to assign customers to the appropriate location. For example:

# Product    ShipTo    Company Id  Business Loc   ShipFrom               Regulated
# -------    ------    ----------  ------------   --------               ---------
electrical : ;;CA;US : Acme      : West         : Cupertino;CA;95014;US : 1
electrical : ;;TX;US : Acme      : Central      : Oak Brook;IL;60523;US : 1
  

With this configuration, for customers in California, BRM sends West as the division to Sales Tax Q Series. The tax supplier's address will be Cupertino, CA. Similarly, customers in Texas will be assigned to the Central division with the Oak Brook, IL address.

Providing Entries for Vertex Tax Codes in the taxcodes_map File

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

To provide the Vertex entries in the taxcodes_map file, you need the following information:

  • The names you will use for tax codes.

  • The corresponding Vertex product codes.

  • Whether the product is for sale (S) or resale (R).

    Note:

    Wt_code and Cmdty_code apply to the Taxware products only. They do not apply to Vertex.

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

To provide Vertex tax codes in the taxcodes_map file:

  1. Go to the directory where the taxcodes_map file is located. The default location is BRM_Home/sys/cm.

  2. Open the taxcodes_map file.

  3. 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  :   234 :  1234 :  R  :        :
    #   usage2          :  Q  :    01 :    01 :  S  :        :
    #   direct          :  C  :    01 :    01 :  S  :        :
    #   toll            :  C  :    04 :    02 :  S  :        :
    #   direct2         :  B  :    01 :    04 :  S  :        :
    #   toll2           :  B  :    01 :    01 :  S  :        :
    #   user_code       :  U  :  10.0
    monthlyCard         :  Q  :    03 :    03 :  S  :        :
    installVertex       :  Q  :    03 :    03 :  S  :        :
    interCommtax        :  C  :    04 :    01 :  S  :        :
    intraCommtax        :  C  :    01 :    02 :  S  :        :
    ipUsage             :  Q  :    03 :    03 :  S  :        :
      
    

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

  4. Save and close the file.

  5. Stop and restart the CM.

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

Configuring the CM for Vertex Tax Calculation

You configure the Connection Manager (CM) for Vertex 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.

Configure CM for Vertex calculation by completing these tasks:

Specifying Vertex DM Connection Entries in CM Configuration File

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

To specify the Vertex DM connection entry in the CM configuration file:

  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 identifies the Data Manager, for example, 0.0.8.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.

    Note:

    The database number, host name, and port number must match the values in the Vertex DM configuration file, BRM_Home/sys/dm_vertex/pin.conf.
  3. Edit the vertex_db entry.

    - fm_rate  vertex_db  database  /_tax_db  0
      
    

    where database is the database number specified in the Vertex 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, Sales Tax Q Series returns a tax amount of 0. If you set up Sales Tax Q Series to validate ZIP codes at registration, you ensure that taxes are calculated correctly. This option specifies that Sales Tax Q Series checks the city, state and ZIP code when an account is created. If the ZIP code is not valid, customer registration cannot be completed.

Important:

  • Communications Tax Q Series does not validate addresses and always returns a valid result.

  • If you enable this option, the Vertex DM must be running when customers register. If the connection to Vertex is offline, 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. Change the tax_valid entry:

    • To enable ZIP code validation, enter 3.

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

    See "About Validating Customer Addresses" for more information.

  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 cannot 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 do not 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.

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

Specifying the Location of the tax_supplier_map File

To specify the location of the tax_supplier_map file:

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

  2. Add the tax_supplier_map entry. For example:

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

  4. Stop and restart the CM.

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

Specifying the Location of the taxcodes_map File

You use the taxcodes_map file to map tax codes to Vertex 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. The default location is BRM_Home/sys/cm.)

    For example:

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

  4. Stop and restart the CM.

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

Itemizing or Summarizing Taxes for Each Jurisdiction Level

You can opt to show the details of the tax types returned by Communications Tax Q Series for each tax jurisdiction level. These details can be mapped to a general ledger (G/L) ID and be shown on the invoice.

To itemize the taxes for each jurisdiction:

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

  2. Add the following entry:

    - fm_rate tax_return_juris itemize
      
    

    To summarize the taxes, change the entry to summarize instead of itemize.

  3. Save and close the file.

  4. Stop and restart the CM.

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

Verifying That Taxes Are Being Calculated

After you have installed and configured the Vertex software, you can run the following test to verify that the Vertex 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 "Providing Entries for Vertex Tax Codes in the taxcodes_map File" 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] "installVertex"
    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_vertex.

  4. Open the BRM_Home/sys/cm.pinlog file and verify there are no errors.

  5. 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 number for PIN_FLD_RATE_TAX_CALC.