SureTax - Installation and Configuration

Summary

This article describes the SureTax integration with EngageIP. SureTax is an integration that allows for the automation of transaction and usage taxing in EngageIP by making use of the SureTax webbased back end to calculate the correct rate.

SureTax is an integration that allows for the automation of transaction and usage taxing in EngageIP by making use of the SureTax web based back end to calculate the correct rate.

SureTax Web-Based Interface

URL: 

Key Features

• Taxing using Service Tax Categories on a Service

• Taxing based on Service Type and Termination Type

• User tax exemption levels - add exemptions on overview of the account by clicking 'Add' in the components section

• SureTax is setup as a SERVER for configuration

• Writes to TAXLOG

• Handles credits and reversals from taxlog

• Works the same as billsoft, i.e. will look up to the parent user for settings (exempt, service address, billing address)

• Works with real time rating

Zip Code and NPA-NXX

All service levels taxes are calculated using ZIPCODE or ZIPCODE+4. UDR will be taxed using NPANXX or ZIPCODE based on termination code which will be implemented in the script.

Tax Exemption Components

A user level tax exemption component will be made available on the overview screen.

Open

To add an exemption from the below list, do the following:

1. Go to the users Overview page that you want to exempt from a tax

2. On the right side under components, click Add

3. Select 'Tax exempt Level'

   1. Select the exemption level from the first drop down menu

   2. Leave the second drop down blank

   3. Click Save

4. Repeat as needed to assign other exemption codes to the  account. When billing runs, it will look at those exemptions and no taxes will be calculated if they exist.

Exemption Codes

Transaction Codes on Services

A service will have a transaction code.

Sample:

• 050102 VOIP Monthly Charge - Amount Attributable To Local Service

• 050103 VOIP Monthly Charge - Amount Attributable To Intrastate Toll Service

• 050104 VOIP Monthly Charge - Amount Attributable To Interstate Toll Service

• 050105 Usage-Based Charges

• 050110 Activation/Deactivation Charges

• 050112 VOIP-Enabled Vertical Features

• 050113 IP Centrex Line

• 050114 Fax over IP - Fixed

Installation

Installation overview:

1. Import XML

2. Configure tax codes

3. Add tax categories on services

4. Configure your SureTax account and URL in the server configuration

5. Test that taxes are applied
   
   

Detailed Installation Process:

1. Import the SureTax Server Information using the 'Import' link on the setup page. Paste each section of code one at a time into the textarea on the import page and click 'import'. This will install the key components of the SureTax integration on the Top Owner where the top ownername is 'Logisense Corporation'.
   Note: To use this for other branded owners, replace 'Logisense Corporation' with  'Branded Owner Name'
   
   

   <?xml version="1.0"?> <Import> <GenericXML Enabled="True" /> <ServerType Name="SureTax" Owner="Logisense Corporation" AddedScript="" RemovedScript="" EnabledScript="" DisabledScript="" ProfileChangedScript="" ReferenceName="SERVERTYPE1"/> <ProfileQuestion Name="ClientNumber" Question="ClientNumber" DataType="Text" ReferenceName="P1"/> <ProfileQuestion Name="ValidationKey" Question="ValidationKey" DataType="Text" ReferenceName="P2"/> <ProfileQuestion Name="URL" Question="URL" DataType="Text" ReferenceName="P3"/> <ProfileQuestionFilter ProfileQuestion="@P1" Role="/Owner=Logisense Corporation/Role=admin" ModifyAnswer="true" DeleteAnswer="true" ViewAnswer="true" /> <ProfileQuestionFilter ProfileQuestion="@P2" Role="/Owner=Logisense Corporation/Role=admin" ModifyAnswer="true" DeleteAnswer="true" ViewAnswer="true" /> <ProfileQuestionFilter ProfileQuestion="@P3" Role="/Owner=Logisense Corporation/Role=admin" ModifyAnswer="true" DeleteAnswer="true" ViewAnswer="true" /> <ServerTypeAttributeProfileQuestion ServerType="@SERVERTYPE1" ProfileQuestion="@P1" ReferenceName="STAPQ1" /> <ServerTypeAttributeProfileQuestion ServerType="@SERVERTYPE1" ProfileQuestion="@P2" ReferenceName="STAPQ2"/> <ServerTypeAttributeProfileQuestion ServerType="@SERVERTYPE1" ProfileQuestion="@P3" ReferenceName="STAPQ3"/> <Server Name="SureTax" Address="127.0.0.1" Owner="Logisense Corporation" ServerType="@SERVERTYPE1" ReferenceName="S1"/> <ProfileAnswer ProfileQuestion="@P1" Value="000000999" ReferenceName="PA1"/> <ProfileAnswer ProfileQuestion="@P2" Value="9999-99999" ReferenceName="PA2"/> <ProfileAnswer ProfileQuestion="@P3" Value="https://testapi.taxrating.net/Services2/V01/SureTax.asmx" ReferenceName="PA3" /> <ServerAttributeProfileAnswer ServerTypeAttributeProfileQuestion="@STAPQ1" Server="@S1" ProfileAnswer="@PA1" /> <ServerAttributeProfileAnswer ServerTypeAttributeProfileQuestion="@STAPQ2" Server="@S1" ProfileAnswer="@PA2" /> <ServerAttributeProfileAnswer ServerTypeAttributeProfileQuestion="@STAPQ3" Server="@S1" ProfileAnswer="@PA3" /> </Import>

    

2. Import the TaxVendor Script
   Note: To use this for other branded owners, replace 'Logisense Corporation' with  'Branded Owner Name'

   1. For EngageIP 8.6 and lower:

       

   2. For EngageIP 9.x, add a new tax vendor on setup, select Suretax, then enter name of Suretax and paste this code: TaxCode taxCode = (TaxCode)context["taxCode"]; double taxableAmount = (double)context["taxableamount"];StatementDetails sd = (StatementDetails)context["statementdetails"];return SureTaxWrapper.GetTaxes(taxCode, taxableAmount, sd);

3. Delete unneeded elements
   Note: These steps are only needed on first install, if you are adding branded owners, this does not need to be completed

   1. Delete the records in TaxExemptLevel and TaxExemptType using MSSQL if any data exists, for example if you are moving from BillSoft to SureTax

   2. Delete BillSoft/previous tax vendors from Setup > Tax Vendor

   3. Run the SQL below on the BOSS database after a backup has been completed

       

   4. Restart IIS

   5. Restart all EngageIP Windows services

4. Import the TaxExemptLevel
   Note: This import step is only needed on first install, if you are adding branded owners, this does not need to be completed
   Note: These tables must be empty before you import the TaxExemptLevel

    

5. Import the Service Tax Categories
   Note: This import step is only for first install, if you are installing on branded owners, this does not need to be completed
   Note: You need to check 'Use Generic XML' for this to import, the standard TaxType import xml doesn't import the tax vendor transaction codes
   
   

    

6. Configure the TaxCode to Default

   Open

   

    

7. Delete all the TaxCodes for the Owner or change existing so it is set to Default and the TaxVendor is SureTax

8. Add Service Tax Category to a Service

    

9. Server Configuration of Live or Test dataTo enter in the live account data or test data do the following:

   1. Click Setup

   2. Click Servers

   3. Click on 'SureTax' server

   4. Define the three profile answers:

      1. Client Number

      2. ValidationKey

      3. URL (Testing URL: 

         )

      4. LIVE URL: 

   5. Finally, do an IISRest to be sure the configuration is read

   6. Also restart service that will tax such as Billing, Event Manager, RatingThe server config should look similar to below:

       

10. Ensure Billing Contact's are setup with addresses

Tax Log Reporting

The tax log in the database can be used to reconcile or trouble shoot applied taxes. A custom report can be made using the below VIEW create query to return results from the tax log in a custom report format.

Reconciling Suretax Granular report to Taxlog:

To reconcile Suretax and Taxlog - you must first export the 'granular' report from the suretax interface. This has the 'TransID' which relates to the 'ReferenceID' in the taxlog.

Steps (example for March data from Suretax):

1. Go to Suretax Taxlog Report

2. Filter by 3/1 to 3/31, and set dropdown as month (this groups the report per image 

    

3. Remove check marks on all columns except for Amount, AmountExemption,AmountProcessed and Created Date

4. Click update

5. Log into Suretax web interface, export the 'Granular' report from the reports menu for March

6. Open this in Excel and compare the totals at the bottom of the report to the 'Amount' returned in the EngageIP Taxlog custom report

Testing

If you are using one of SureTax's test servers (i.e. testapi), then the you will need to enable TestMode (see below), if you are testing in a production environment you should not enable TestMode.

Enabling TestMode sets the month to a value of -1 overriding EngageIP's default behavior of posting to the current month/year.  This avoids problems with the EngageIP posting date being mismatched with the SureTax test server date. Instructions on enabling TestMode can be found below.

Enabling TestMode:

1. Access your EngageIP test environment

2. Load the Setup page and under the Communication Services heading click on Server Types

3. Click on the SureTax server type and once the edit page loads scroll down to the Components heading at the bottom click the Add button

4. Select Profile Question

5. On the Add Profile Question page enter:

   • the Name as TestMode

   • set type 'Select from List with options 'True,False' (this enforces a boolean value when entered)

6. Restart IIS and the EngageIp Billing Service for TestMode to take effect (note: this must also be done when disabling TestMode)

That will set the Month to a value of -1, and allow you to apply taxes regardless of the date set in the test environment.  At this point you can add a UserPackage or Transaction and the tax should be shown:

UDR / CDR Taxing

To turn on UDR and CDR level taxing using AvaTax, execute the following SQL:

If this setting is not present, it effectively means that its OFF or FALSE.

If this setting is false the system will calculate tax and insert it into the statementdetailstax table and use that for invoice presentation. Tax will be calculated based on the Service Tax Category of the service which is stamped on the Telecom Usage transaction.

If the setting is true EngageIP will use the tax found (previously calculated during rating) in the UDRBillerTax table.  It will sum up the UDRBillerTax value and then stamp that as the statementdetailsTaxID on the associated statementdetail record.

If this setting does not exist the system will use the TaxTypeID on the UDRBiller table. The TaxTypeID is set by the rating service, this is found by looking at the service where the rateplan exists on the User that is associated and uses the Service Tax Category from that service.

The UDRBiller.TaxTypeID comes from the ServiceAttributeTaxType of that User’s UserService listed in UUIH or UserserviceAttributeUDRBucket(USAUB). Depending on the rules set in your specific UUIH script that might be the Userservice related to the RatePlan OR the Userservice where the DID/UUIH.Identifier was located, and those could be different….If the UserID has multiple valid entries in UUIH each UUIH.Userservice’s TaxTypeID will have a UDRBiller for it.

UDRBillers are also created for USAUBs and reflect their Userservice-ServiceAttributeTaxType.

UDRBiller Taxing Requirements (not UDR level taxing)

If you are taxing simply at the statementdetails / transactions level and not using the UDRLevelTax flag as mentioned above, there are some key items to configure:

1. UDRBillers will need taxcodeID populated for historical data

2. Services will all need Service Attribute Tax Code component added with the SureTax taxcode selected (usually 'Default'). This will be the config that allows UDRBiller.create events to associate the taxcodeID for new udrbillers going forward

3. You will need a custom SureTax taxvendor script  - existing one for statementdetails level taxing relies on 'serviceid' in the statementdetails record which does not exist in UDR deployments and so returns zero taxes. The custom script will tell sure tax that IF the transaction detail starts with 'Telecom Usage', to look up the taxtype to be relayed to SureTax from the udrbiller table taxtype.

SureTax Tax Vendor code in this case:

TaxVendorScriptSuretaxMay2019:

Open

Troubleshooting

• If the system is not calculating tax, ensure that you have reset IIS, and restarted all services

• If you add a new owner or partner, make sure to restart IIS and services to be sure the system starts taxing according to configuration

• ReferenceID in the taxlog matches the 'Trans ID' in SureTax reports at the granular level

• To see transactions, use Granular report option (needs to be turned on by SureTax if its not in the dropdown for reports available). The granular report gets you the referenceID that you can link to taxlog / associate. If you are using 'TEST' mode on servers on the setup page, that sets the period date back one month so if you added transaction dated in April, run report for March (one month prior) to see the data

• Reversed or voided transactions will exist in taxlog per referenceID but the granular report excludes these reversed transactions. Taxlog has positive and negative items for the same referenceID

• CreatedDate in taxlog is the date used in the granular report to group items by