7 Configuring Vertex Data Manager for Vertex Q Series

In Oracle Communications Billing and Revenue Management (BRM), you can configure Vertex Data Manager to calculate taxes.

Topics in this document:

About Implementing Vertex Q Series Tax Calculation

Vertex Data Manager (DM) connects BRM with the Vertex Tax Q Series 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 Tax Q Series, 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 "Additional BRM Software Requirements" in the BRM Compatibility Matrix for information on supported versions of the Vertex software.

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 Tax Q Series software:

  • Data Source 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 in your $LD_LIBRARY_PATH. These are shared libraries that come with the Sales Tax Q Series software.

  • libvst.so

  • libloc.so

  • libqutil.so

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. For example, use dm_vertex_stq100 to interact with STQ v10.0.

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. Set the quantum_sm_obj entry, which is displayed in the following format in the file: 

    - dm_vertex quantum_sm_obj ./dm_vertex_stqVersion${LIBRARYEXTENSION}

    replace Version with the STQ version, such as 100 for STQ 10.0.

  3. Save and close the file.

  4. 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 in 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

  • 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 3.02, specify dm_vertex_ctq302.

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. Set the commtax_sm_obj entry, which is displayed in the following format in the file: 

    dm_vertex commtax_sm_obj ./dm_vertex_ctqVersion${LIBRARYEXTENSION}

    replace Version with the CTQ version, such as 302 for CTQ 3.02.

  3. Save and close the file.

  4. 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 entries in the BRM_home/sys/dm_vertex/pin.conf file:

  1. 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 Password for the wallet: 
Setting the entry dm_vertex.quantumdb_passwd is SUCCESSFUL

  2. Open the Vertex DM configuration file (BRM_home/sys/dm_vertex/pin.conf).

  3. 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 the 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.

  4. Save and close the file.

  5. 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:

  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.

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 hostname, 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 Vertex database number, such as 0.0.8.1.

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

    • port is the port number of the DM service.

    Note:

    The database number, hostname, 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 number of the Vertex database. It must match the value entered in the dm_vertex pin.conf file.

  4. Save and close the file.

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

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

  1. Go to BRM_home/sys/data/config.
  2. Use the following command to create an editable XML file from the rating instance of the /config/business_paramsobject:
    pin_bus_params -r BusParamsRating bus_params_rating.xml

    This command creates an XML file named bus_params_rating.xml.out in your current directory. If you do not want this file in your current directory, specify the path as part of the file name.

  3. In bus_params_rating.xml.out, set BusParamsRating to itemize:
    <TaxReturnJuris>itemize</TaxReturnJuris>

    The default value is summarize.

    Caution:

    BRM uses the XML in this file to overwrite the existing instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM configuration.
  4. Save and exit the file.
  5. Rename the bus_params_rating.xml.out file to bus_params_rating.xml.
  6. Use the following command to load your changes into the /config/business_params object:
    pin_bus_params bus_params_rating.xml

    You should run this command from the BRM_home/sys/data/config directory, which includes support files used by the utility. To run it from a different directory, see "pin_bus_params" in BRM Developer's Guide.

  7. Read the object with the testnap utility or the Object Browser to verify that all fields are correct.

    For general instructions on using testnap, see "Using the testnap Utility to Test BRM" in BRM Developer's Guide. For information on how to use Object Browser, see "Reading Objects" in BRM Developer's Guide.

  8. Stop and restart the Connection Manager (CM).

    For more information, see "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 Vertex software, you can run the following test to verify that the Vertex software is calculating taxes.

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