Configuring Vertex Manager

About Implementing Vertex Tax Calculation

Vertex Manager connects BRM with the Vertex tax calculation database, which maintains current tax rates for various tax jurisdictions. Using Vertex, you can simplify how taxes are calculated and use the latest tax rates.

To calculate taxes using Vertex, you install BRM Vertex Manager and then run the Vertex Data Manager.

Note:

BRM audits tax calculation data, but does not support the Vertex auditing features.

Installing the Vertex Software

You install BRM Vertex Manager when you install BRM.

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 Sales Tax Q Series Shared Libraries

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

Use files with the extension .so for Linux and Solaris:

libvst

Note:

For BRM 12.0 Patch Set 4 and later, you must rename the libvst.so file to libvst64.so.
libloc
libqutil

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

Specifying Storage Manager Shared Library for Sales Tax Q Series

To configure the Vertex DM for Sales Tax Q Series, edit the BRM_home/sys/dm_vertex/pin.conf entries in Table 7-1.

Table 7-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	A valid Oracle user 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 5.0, specify dm_vertex_stq500.

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.

Configuring the Communications Tax Q Series Shared Libraries

Ensure the following libraries are in the BRM_home/lib directory or your $LD_LIBRARY_PATH. These shared libraries come with the Vertex Communications Tax Q Series software.

libadm.so
libcch.so
libcfg.so
libcli.so
libctq.so

Note:

For BRM 12.0 Patch Set 4 and later, you must rename the libctq.so file to libctq64.so.
libctz.so
libdbcper.so
libgeo.so
libhsh.so
libobj.so
libreg.so
librpt.so
librte.so
libutl.so
libxmlparse.so

Specifying Storage Manager Shared Library for Communications Tax Q Series

Table 7-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 7-2 pin.conf Entries for Vertex DM (Communications Tax Q Series)

Entry	Description
commtax_config_path	The location of the 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 2.02.16, specify dm_vertex_ctq20216 CTQ 3.00.02, specify dm_vertex_ctq300

Entry

Description

commtax_config_path

The location of the 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 2.02.16, specify dm_vertex_ctq20216
CTQ 3.00.02, specify dm_vertex_ctq300

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.

Configuring the Vertex DM for Sales Tax Q Series

To configure 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:

Add the QuantumDB password to the BRM client wallet using pin_config_editor:

pin_config_editor -setconf -wallet wallet/client -parameter dm_vertex.quantumdb_passwd -pwd
Enter the value:
Enter the password for the wallet:
Setting the entry dm_vertex.quantumdb_passwd is SUCCESSFUL

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
```
Note:
If you choose to keep your passwords in pin.conf file rather than wallet, uncomment the following entry according to the instructions in the file:
```
#- 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.
  Note:
  
  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 multithreading. The ISAM version of Vertex does not support multithreading.
Save and close the file.
Stop and restart the Vertex DM.

Configuring 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
```
Save and close the file.
Stop and restart the Vertex DM.

Configuring the CM for Vertex Tax Calculation

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:

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, such as 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.

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 account creation, 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 invalid, account creation cannot be completed.

Note:

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 create accounts. If the connection to Vertex is offline, you can change this option to skip validating ZIP codes. This allows customers to create accounts.

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.
Save and close the file.

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

Itemizing or Summarizing Taxes for Each Jurisdiction Level

You can 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.

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 7-3 lists the Vertex-to-BRM mappings whose codes differ.

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

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.

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.

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