...
An overview of AvaTax Cloud and related articles can be found in the Avalara AvaTax Cloud Integration article. This article covers how to setup the AvaTax Cloud EngageIP integration and how to test taxation.
...
A high bandwidth internet connection
EngageIP version 9.1.0 or higher
Access to the EngageIP app server and database
Avalara AFC SaaS Pro Tax service login credentials (provided by Avalara)
...
This section explains how to configure AvaTax cloud in EngageIP. If you are presently using the on-prem AvaTax integration in EngageIP you should reference the Avalara Billsoft article instead.
EngageIP and AvaTax cloud integrate through RESTful API, so unlike the older on-prem billsoft solution configuration is simplified. The AvaTax cloud configuration does not require tax vendor scripts or action scripts.
...
Import Service TaxTypes (These will be the 'Service Tax Categories' associated to your services on setup)
click Setup on the left sidebar
under Data Management click Import
import the following service tax types XML: TaxTypes-Import.xml (The 'TaxType' element should be 'name' for the final xml import, example per image below)
the result should indicate success
Optional: setup or import Account Tax Categories (AvaTax supports the following tax categories – Residential, Residential Incorporated, Business, Business Incorporated)
click Setup on the left sidebar
under Data Management click Import
import the following service tax types XML: AccountTaxCategoryXMLImport.xml
Note: you need to update owner in the XML file to match your systemResidential Incorporated
Residential
Business Incorporated
Business
SeniorCitizen
Industrial
SeniorCitizen Incorporated
Industrial Incorporated
If Service Tax Category was not setup in step #1, you can add them manually: setup Service Tax Categories
Populate the Tax Type Mapping table
access the EngageIP Database
run the following script: EZTaxTaxTypeMappingInsertScript
ensure there are no errors and that the EZTaxTaxTypeMapping table is populated
Add a Tax Vendor for AvaTax
...
Enable taxation on invoice close select the 'Invoice Level Taxing' option here. It's recommended that this option always be selected / used
6. Ensure a Default tax code is setup in the AdminPortal
...
7. Test to ensure that taxation is functioning: see the Post Configuration Testing section below
8. Optional: enable UDR (usage) taxing and other required features described below
...
Ensure your mediation code is configured to tax the appropriate tax types (see the usage requirements section above)
Ensure the CDRLevelTax EngageIP option exists in the EngageIP database > EngageIPOptions table. If not add it with the insert statement below
Code Block INSERT INTO EngageIPOption (Name,VALUE) VALUES ('CDRLevelTax','true')Ensure normal usages charges (without tax) are applied for test usage (i.e. usage feeds, UUIH, rates, rate groups, rate plans, tax code setup the service tax category)
On the Setup page under UDR Feeds click the relevant feed to edit it
Under the Processors section click Add
Select SetUDRTaxing, choose a sort order and click Save
Setup a service with a service tax category (in order to apply usage specific taxes)
Ensure a tax code is configured with the service tax category and the tax code's tax vendor is set to the avatax vendor
Add the service with the service tax category to a test package and ensure the package is configured with a UDR Rate Plan containing the proper usage rates
Configure a test account, test user-package and test usage data to ensure usage taxing is working. See the Per Transaction Testing section below for steps
Configuring Batch Taxing Records (UDR)
Enable batch taxing on the Configuration page
Load the Tax Vendor and set the UDR Batch Size (this setting only appears if the 'Batch Taxing On Usage' option described above is enabled)
Note: A maximum batch size of 1,000 is recommended by Avalara as performance degrades above that size
Optional: Access the EngageIP app server and load the EngageIP\Services\UDRBatchTaxService.exe.config file. In the config file verify/adjust the settings to suit your environment:
the frequency that the usage taxes should be processed (pollingDelayInSeconds)
the number of threads to use (MinThread, MaxThread)
how long to retain data on taxes that have been processed (UDRBatchPendingTaxRecordRetentionPeriodInDays)
Follow the same configuration as described in the Configuring Taxing Per Record (UDR) section above
Start Batch Taxing service
Test to ensure taxes are applied in the batch size and time interval you configured. See the Testing Batch Usage Taxation section below for steps
...
Ensure Invoice Level Taxing is enabled on the Tax Vendor (credentials are provided by Avalara)
Follow the same configuration as described in the Configuring Taxing Per Record (UDR) section above
Test to ensure usage is taxed with the appropriate taxes and rates when a test account's invoice is closed. See the Testing Invoice Level Taxation section below for steps
Configuring Usage Taxing on Billing/Invoice Close
To enable taxing on billing or invoice close (whichever occurs first) you simply have to delete the CDRLevel tax entry in the EngageIPOption table. Otherwise the configuration instructions are identical to the Configuring Taxing Per Record (UDR) section above.
Configuring Tax Overrides
...
Testing Batch Usage Taxation
Follow the Testing Usage Taxation steps above
Verify that the batch taxing occurs when the pollingDelayInSeconds (configured frequency) is reached. Even if only one usage record needs to be taxed the data will be sent to the Avalara server for tax calculation (the system will not wait until the batch size is reached)
Generate enough test usage to exceed the UdrBatchSize. When the polling time is reached check the Event Log to verify that the UdrBatchSize is broken up into more than one batch (Event Log 'Action' column can be filtered by 'ProcessBatchUDRTaxes' to find the batch taxing events. The total number of batches and records will be shown in the 'Result' column)
If you wish to see the transactions and taxes applied to the test account, load the account and bill it via Tools > Bill Account. Ensure the date range you bill for covers the date the usage occurred on
...
NOTE: Taxing at an invoice level as configured on the Tax Vendor config on setup will tax based on the invoice date (transaction date is not considered when applying tax in this fashion). When the invoice is closed, the invoice date is calculated based on bill group settings for invoice close date, and at that time, it calculates the tax using the invoice date that is set on the invoice.
Logs and Reports
The Tax Log contains a high level of detail on taxes that have been applied
The Event Log captures system event details and is useful for verifying which events have occurred or failed. For instance, if jurisdiction codes are not being added to contact addresses the event log should contain failure messages indicating the cause (e.g.