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:
Vertex Sales Tax Q Series: Calculates sales and use taxes.
Vertex Communications Tax Q Series: Calculates telecommunication taxes.
To use Vertex Sales Tax Q Series or Vertex Communications Tax Q Series with BRM, you must install one of the following:
Vertex Manager: Supports Vertex Sales Tax Q Series and Vertex Communications Tax Q Series.
Vertex Quantum Manager: Supports Vertex Sales Tax Q Series. This manager does not support Vertex Communications Tax Q Series.
Important:
Each of these managers is an optional component that you install separately.See "About Calculating Taxes" for more information about calculating taxes.
See "Customizing Tax Calculation" for information about customizing the Vertex Data Manager (DM).
To implement Vertex tax calculation, perform the following tasks:
To install Vertex Manager or Vertex Quantum Manager, see "Installing Tax Calculation Managers" in BRM Installation Guide for more information.
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.
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:
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.
Table 3-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 3-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
|
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:
Open the Vertex DM configuration file (BRM_Home/sys/dm_vertex/pin.conf).
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}
Save and close the file.
Stop and restart the Vertex DM.
See the discussion about starting and stopping the BRM system in BRM System Administrator's Guide for more information.
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
Table 3-2 lists the entries in the BRM_Home/sys/dm_vertex/pin.conf file used to configure the Vertex DM for Communications Tax Q Series:
Table 3-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
|
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:
Open the Vertex DM configuration file (BRM_Home/sys/dm_vertex/pin.conf).
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}
Save and close the file.
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.
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 Communications Tax Q Series
Note:
Record the port and database numbers entered in your Vertex DM pin.conf file. These entries are also used in the CM pin.conf file.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:
Open the Vertex DM configuration file (BRM_Home/sys/dm_vertex/pin.conf).
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.
Save and close the file.
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.
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:
Open the Vertex DM configuration file (BRM_Home/sys/dm_vertex/pin.conf).
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
Specify the Communications Tax Q Series configuration name in the commtax_config_name entry.
For example:
- dm_vertex commtax_config_name CTQ_Test
Specify the category codes that use ChargeTo as the primary place of use (PPU) location.
For example:
- dm_vertex use_charge_to_category_codes 12,40,10
Save and close the file.
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.
To set up tax suppliers in the BRM database:
Define at least one tax supplier (/config/tax_supplier object).
See "Defining Tax Suppliers" for more information.
Edit the tax_supplier_map file.
See "Providing Tax Supplier Data in a tax_supplier_map File" for more information.
Configure the taxcodes_map file.
See "Providing Entries for Vertex Tax Codes in the taxcodes_map File" for more information.
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.
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 3-3 provides a list of the entries in the tax_supplier_map file:
Table 3-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:
You can leave portions of this string blank, but you must include the semicolons for each address element. Examples:
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:
You can leave portions of this string blank, but you must include the semicolons for each address element. Examples:
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:
Provide the necessary information on each tax supplier. See Table 3-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
Save and close the file.
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.
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.
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 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:
Go to the directory where the taxcodes_map file is located. The default location is BRM_Home/sys/cm.
Open the taxcodes_map file.
Edit the file. For example:
# Taxcode Pkg Code1 Code2 Si Wt_code Cmdty_code # --------------- --- ----- ----- -- ------- ---------- # 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.
Save and close the file.
Stop and restart the CM.
See the discussion of starting and stopping the BRM system in BRM System Administrator's Guide, for more information.
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:
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:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf).
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.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.
Save and close the file.
You don't need to restart the CM to enable these entries.
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:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf).
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.
Save and close the file.
You don't need to restart the CM to enable this entry.
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:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf).
Edit the provider_loc entry. For example:
- fm_rate_pol provider_loc Middletown, CA 95222 USA
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.
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:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf).
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
Save and close the file.
Stop and restart the CM.
See the discussion of starting and stopping the BRM system in BRM System Administrator's Guide, for more information.
To specify the location of the tax_supplier_map file:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf).
Add the tax_supplier_map entry. For example:
- fm_rate tax_supplier_map BRM_Home/sys/cm/tax_supplier_map
Save and close the file.
Stop and restart the CM.
See the discussion of starting and stopping the BRM system in BRM System Administrator's Guide, for more information.
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:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf).
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
Save and close the file.
Stop and restart the CM.
See the discussion of starting and stopping the BRM system in BRM System Administrator's Guide, for more information.
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:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf).
Add the following entry:
- fm_rate tax_return_juris itemize
To summarize the taxes, change the entry to summarize instead of itemize.
Save and close the file.
Stop and restart the CM.
See the discussion of starting and stopping the BRM system in BRM System Administrator's Guide, for more information.
Some of the Vertex CTQ 2.00.05 and later jurisdiction codes are different from the internal BRM jurisdiction codes to which they are mapped. Table 3-4 lists the Vertex-to-BRM mappings whose codes differ:
Table 3-4 Numbering Differences in Vertex-to-BRM Jurisdiction Code Mapping
| Jurisdiction | Vertex Code | BRM Code |
|---|---|---|
|
Other Municipality |
6 |
12 |
|
County District |
7 |
10 |
|
City District |
9 |
11 |
Important:
You must use the new BRM jurisdiction codes (12, 10, and 11) while specifying the account's tax exemptions and also while interpreting the jurisdiction codes in the /event object.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.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]
Save the text file to the BRM_Home/setup/scripts directory.
Start dm_vertex.
Open the BRM_Home/sys/cm.pinlog file and verify there are no errors.
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.