Page Comparison

Summary

This article describes how the on-prem Avalara billsoft integration functions and is configured in EngageIP. If you are configuring the AvaTax Cloud version please see the Avalara AvaTax Cloud – Configuration article instead.

...

Taxes are applied based on the following criteria in order of precedence:

1. If service tax category or account tax category exist on the service or the account, take this into account when checking 2 and 3

2. If the tax code exists on account, tax based on tax code

3. Else if Service Contact exists, tax service based on Service Contact address

4. Else (if none of the above are applicable) tax based on Billing Contact address

Sub Account Taxing

If a parent account in EngageIP has a taxable address, then any sub account created that has no address or tax code component of their own will be taxed based on the parents details. To tax a sub account differently ensure the sub account has either a valid address with an associated jurisdiction code address component or has a tax code component override (tax exempt or override).

...

To begin installation you will need to downloaded the installer from Avalara (this should be named something like win64_xxxx.zip).

1. Download either the 32bit or 64bit installer files. Which you choose will of course depend on whether the server you are installing it on is 64bit or 32bit. Extract the files. Run update.exe. This will walk you through installing the Billsoft software. Avalara strongly suggests using the default directories (i.e. C:\BillSoft). The EngageIP library expects to find EZtax in this location

2. If EngageIP is running on a 64bit server:

   1. Ensure you installed the 64bit version of Billsoft

   2. Verify the IIS APP POOL has 'Allow 32 bit' set to false

   3. Verify HANDLERS in IIS has only one .rails pointing to FRAMEWORK64 (Check this for the AdminPortal and default sites)
      

3. Configure the Environment Variables as outlined by the Billsoft Documentation *** Environment Path should be equal to: C:\BillSoft\EZTax\DLL;C:\BillSoft\EZTax\EXE; (Make sure no spaces are used and that the semicolons are in place)

   Image Modified

4. Reboot the system for the Path changes to take effect

5. In the EngageIP AdminPortal, Setup

...

1. page add the following Workflow to update p-codes based on the users address
   Create an "Action"
   Name: EZtax pcode
   Event: ContactPointAddress.Create,ContactPointAddress.Update
   Code:

   Code Block
   int id = Int32.Parse(context["ContactPointAddressID"].ToString()); return EZTaxWrapper.GetPcode(id);

2. Configure the Billsoft tax vendor for transactional or invoice level taxing

   1. To configure taxation per transaction:

      1. Load the Setup page

      2. Load Tax Vendor

      3. Click Add

      4. In the TaxVendor Type list select BillSoft

      5. Click Save

      6. For Vendor enter Billsoft

      7. For the Charge Script enter

         Code Block
         TaxCode taxCode = (TaxCode)context["taxCode"]; double taxableAmount = (double)context["taxableamount"]; StatementDetails sd = (StatementDetails)context["statementdetails"]; int taxTypeId = (int)context["taxtypeid"]; return TaxVendorManager.GetTaxes(taxCode, taxableAmount, sd, taxTypeId);

      8. Click Save

   2. To configure taxation on invoice close:

      1. See the invoice level taxing section below

3. Enable the tax log, detailed here (further down page) This is required for reporting and reconciliation purposes

4. Check on the Configuration page in the EngageIP AdminPortal to ensure scripts are compiling correctly. If not, check for errors

5. Update the Billsoft install folder (default install directory name is 'BillSoft') granting EVERYONE - FULL CONTROL permissions

6. In the AdminPortal

...

1. / Setup

...

1. page add a Tax Code called 'Default' as shown below

   Image Modified

   Note: the less you configure in the Tax Code the more customers it will apply to. I.e. if you do not populate any location details (Country, State, County, City) then all accounts under the owner will use the Tax Code and therefore use Billsoft. If you need to tax services slightly different by way of tax categories, you can create multiple tax codes called Default with different location configurations to meet your requirements
   

2. Import Service Tax Categories or Setup Custom Billsoft Tax Types (EngageIP 8.5.17.0+ required)

   1. Import Service Tax Categories using the the instructions provided below. You will need to make this list into an XML file for import using the following format: XML Files and Data Formatting
      
      The ‘Service TaxTypes Import’ xml file can be found below these steps under ‘Import Documents’
      
      Note: Service Tax Categories if used at all should be added to ALL services that require taxing to be sure the correct tax is applied. Please contact Avalara support for further assistance here
      
      Note: if you are running an EngageIP version below 8.5.17.0 and want taxes to be applied by Billsoft, you MUST use the service tax categories that Billsoft recognizes. Custom Service Tax Categories are not available prior to EngageIP 8.5.17.0
      

   2. See the Setting up Custom Billsoft Tax Types section below if you wish to setup Custom Billsoft Tax Types

3. Setup / Import Account Tax Categories (Billsoft supports the following tax categories - Residential, Residential Incorporated, Business, Business Incorporated)
   Note: An account tax category of just 'Residential' implies that the account is 'unincorporated'. The same is true for a 'Business' account tax category, it really means 'Business Unincorporated'

   1. Import Account Tax Categories using the XML provided in the 'Import Documents' area below or Configure Tax Categories on the Setup

...

1. 1. page and add them to the customer accounts as required

   2. Account Tax Categories are added as components on the customers 'Overview' page. Load the customer's Account and under the Components section click Add and then Account Tax Category. Select the Appropriate tax category and click Save
      Note: Account Tax Category needs to exist on the sub account and on the main account to tax the account specific packages and services correctly

2. For EngageIP 8.5.26.0+ Installs:

   1. Download, extract and run the EZTaxTaxTypeMappingInsertScript provided below on the EngageIP DB server to create and populate the EZTaxTaxTypeMapping table
      

Import Documents:

...

To validate that the Billsoft integration is working in EngageIP, do the following:

1. Add an Account

2. Load the Contacts

...

1. page / Billing Contact

2. Add an Address Contact Pointy Type to the Billing Contact

3. Verify that the Billing Contact Address has a Jurisdiction Code Component added to it automatically (if not see Troubleshooting section below)

   Image Modified

4. Add a Package that contains a Service to the account. The tax should be automatically calculated out of the EZtax database

5. Check the customer invoice or Transactions

...

1. page to verify that taxes are being applied

Reporting

To add visibility into Accounts which may be missing Jurisdiction Codes (JCodes) you can setup a Custom Report in EngageIP. See the article Find Missing Jurisdiction Codes for setup instructions.

Applying Jurisdiction Codes to All Accounts

...

...

1. Load the Setup

...

1. page

2. Click on Service Tax Categories

3. Click the Add button

4. Enter the name in this custom format CustomEZTax(Name,<transactionType>,<serviceType>)

   • the format above cross-references the Tax Type Name to the Transaction/service types

   • e.g. a Tax Type with the name CustomEZTax(MyTaxType,1,2) would configure a custom tax type with transaction type 1, and service type 2

   • the Name must be entered without slashes or spaces, i.e. CustomEZTax(VPNxxxMPLS,61,586)

5. Click Save when finished or Save/New to save the new custom Tax Type and create another one

Configuring Service Tax Categories

...

Adding Service Tax Categories to Services

1. Click Setup

...

2. Click Services

3. Click on the name of the desired service

4. Click the Add button under Components

   • Select Service Tax Category

   • Select the appropriate item

   • Click the Save button

5. Done - Repeat the steps to configure additional service tax categories on services as needed

Multiple Branded Owners Install

...

The below will loop through all branded owners and insert the taxvendor script, one for each branded owner in a system where there are multiple owners needing the tax vendor configuration.

CREATE TABLE tempBillSoftXYZ44
(
OwnerID INT,
[Name] nvarchar(255),
ChargeScript ntext,
InvoiceChargeScript ntext
)

INSERT INTO tempBillSoftXYZ44 (OwnerID) SELECT o2.ID AS OwnerID FROM [Owner] AS o2 INNER JOIN ViewOwnerParent vop ON vop.OwnerParentID = o2.ID WHERE o2.ID NOT IN (SELECT o.ID FROM [Owner] o INNER JOIN TaxVendor tv ON o.ID = tv.OwnerID WHERE tv.Name = 'BillSoft') AND vop.Branded = 1;

UPDATE tempBillSoftXYZ44 SET [Name] = 'BillSoft', ChargeScript = 'TaxCode taxCode = (TaxCode)context["taxCode"];
double taxableAmount = (double)context["taxableamount"];
StatementDetails sd = (StatementDetails)context["statementdetails"];
return EZTaxWrapper.GetTaxes(taxCode, taxableAmount, sd);', InvoiceChargeScript = ''

UPDATE TaxVendor SET ChargeScript = 'TaxCode taxCode = (TaxCode)context["taxCode"];
double taxableAmount = (double)context["taxableamount"];
StatementDetails sd = (StatementDetails)context["statementdetails"];
return EZTaxWrapper.GetTaxes(taxCode, taxableAmount, sd);'
WHERE Name='BillSoft'

INSERT INTO TaxVendor (OwnerID, [Name], ChargeScript, InvoiceChargeScript) SELECT * FROM tempBillSoftXYZ44

DROP TABLE tempBillSoftXYZ44

...

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

INSERT INTO EngageIPOption (Name,VALUE) VALUES ('CDRLevelTax','true')

...

Tax Exemption Options

NOTE: These are specific to on premise Billsoft installations and may not work with Avatax deployments

Tax exemption is now available at multiple levels, as below.

...

• All - this exempts ALL Billsoft taxes

• Federal

• County

• State

• Local

• County_Local

• Other

• State_County_Local

• Unincorporated

...

Account Level Tax Exemption:

1. Click on the Overview

...

1. page of the account you wish to apply tax exemption to

2. On the right side under Components click Add

3. Select Tax Exempt Level (To determine the correct selections, see the description below this list describing how to find it)

   • Select the specific exemptions such as Federal exemption.

   • Optionally: select the tax exempt type (as illustrated in the image where there is a federal base exemption and the type is ADVANCED...)

   • Click Save

4. Repeat this process if you need to apply multiple tax exemptions at different levels to the user account (the above image shows to exemptions applied, one for state taxes and one for federal taxes)

Determining the exempt level selections:

...

Type: FCC_REGULATORY_FEE_VOIP (where the type is basically what is shown in the transaction detail with the additional VOIP element attached.) (Similar bracketed values may include 'WIRELESS' and such)

Testing:

1. Add a transaction that taxes with the tax you want to exempt

2. Confirm the tax is charged as expected

3. Add the new exemption

4. Add a new transaction for the same amount

5. Confirm that the tax amount is zero for that same tax type

Tax Override Options

There are two basic ways to override taxes when using the Billsoft integration

1.  With the tax manager software provided by Avalara you can manage overrides, customization's, etc.

   • With the manager, one can make .OVR files which are placed in the BillSoft/Data folder and processed when Billsoft starts. The manager is not needed if you have an OVR file from another system

   • If you have your own  custom override file where the manager is not installed on the system you're updating, ensure the file is named 'eztax.ovr'

   • Do an IISReset after this to ensure all is reloaded here.

2. Implement EngageIPOption table items to force EngageIP to tax a specific rate at a specific value

EngageIPOption Method:

This method uses the EngageIPOption table to hardcode an amount for a specific rate that Billsoft would otherwise tax at the going rate.

...

Tax Exclusion Configuration:

1. Load the Setup

...

1. page

2. Under the Taxes heading click on Tax Exclusions

3. Click Add

4. Enter the details for the location you wish to exclude from taxation

   Image Modified

   • Country ISO: enter a two or three digit ISO Code for the Country (e.g. US or USA are both valid entries). If you wish to exempt all Federal and State taxes enter the Country ISO alone without any State value

   • State: enter the two digit State or Province abbreviation to exclude taxation at a State level (the image above shows how to exclude California State Taxes)

5. Select an option to Save the Tax Exclusion

   • Save/New will add the exclusion and proceed to add another exclusion

   • Save on 'X' Branded Owners will add the Tax Exclusion to the current Owner you are configuring and the Branded Owners that exist underneath the current Owner

Importing Tax Exclusions

You can import Tax Exclusions by using the EngageIP XML Import feature. First create the XML (sample TaxExclusionImport xml)

Then do the following:

1. Load the Setup

...

1. page

2. Click on Import

3. Either click Choose File or paste the XML into the XML Data field

4. Click Save and you should see a 'Import successful.' message

5. Return to the Setup

...

1. page and load the Tax Exclusions page to verify the imported exclusions are present

Excluding Specific Rates Per Owner

NOTE: These are specific to on premise Billsoft installations and may not work with Avatax deployments

An advanced configuration exists where you can tell EngageIP to only tax particular rates across an owner, or exclude particular rates across an owner. This requires EngageIP version 8.4.5.1 or greater. To configure this, two tables need to be created with below query.

1. Open BOSS database

2. Execute table creation queries as below

3. In the include or exclude tables enter the Owner ID (gathered from owner table) and the tax rate name.
   Note: this is the short name, not the long name. Examples are 'Sales Tax' or 'E911 (VoIP)'

4. Reset IIS - this is required for EngageIP to read the table after you've updated it

5. Login to adminportal

6. Add a transaction for testing purposes to confirm that either the tax rates defined were excluded, or if in the include table, ONLY those tax rates were applied for the owner they are attached to.

If there is something in the TaxVendorTaxInclude table for that owner, then this table will be used. It will only charge tax for the tax name (Tax Description) in this table. You can have Multiple entries:

...

Create Tables SQL:

CREATE TABLE [dbo].[TaxVendorTaxInclude](
[ID] [INT] IDENTITY(53,1) NOT NULL,
[OwnerID] [INT] NOT NULL,
[TaxName] [nvarchar](255) NOT NULL,
CONSTRAINT [PKC_TaxVendorTax
Include_ID] PRIMARY KEY CLUSTERED
(
[ID] ASC
)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
) ON [PRIMARY]

GO

ALTER TABLE [dbo].[TaxVendorTaxInclude] WITH CHECK ADD CONSTRAINT [FK_TaxVendorTaxInclude_Owner] FOREIGN KEY([OwnerID])
REFERENCES [dbo].[Owner] ([ID])
GO

ALTER TABLE [dbo].[TaxVendorTaxInclude] CHECK CONSTRAINT [FK_TaxVendorTaxInclude_Owner]
GO

CREATE TABLE [dbo].[TaxVendorTaxExclude](
[ID] [INT] IDENTITY(30,1) NOT NULL,
[OwnerID] [INT] NOT NULL,
[TaxName] [nvarchar](255) NOT NULL,
CONSTRAINT [PKC_TaxVendorTaxExclude_ID] PRIMARY KEY CLUSTERED
(
[ID] ASC
)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
) ON [PRIMARY]

GO

ALTER TABLE [dbo].[TaxVendorTaxExclude] WITH CHECK ADD CONSTRAINT [FK_TaxVendorTaxExclude_Owner] FOREIGN KEY([OwnerID])
REFERENCES [dbo].[Owner] ([ID])
GO

ALTER TABLE [dbo].[TaxVendorTaxExclude] CHECK CONSTRAINT [FK_TaxVendorTaxExclude_Owner]
GO[cce lang="sql"]

...

Inclusive Tax System Configuration

1. Access the EngageIP host

2. Open the BillSoft installation folder and edit/add the EZtax.cfg file in the Data sub-directory (e.g. C:\BillSoft\EZTax\Data\EZTax.cfg)

3. Using a Text Editor add the following line at the end of this file

   reversecalcsession=on

4. Save and close the file

5. Load the EngageIP Adminportal Setup

...

1. page and select Tax Vendor

2. Edit the BillSoft tax vendor and replace the existing script with the one listed below
   BillSoft Tax Vendor Script

   Code Block
   TaxCode taxCode = (TaxCode)context["taxCode"]; double taxableAmount = (double)context["taxableamount"]; StatementDetails sd = (StatementDetails)context["statementdetails"]; int taxTypeId = (int)context["taxtypeid"]; return TaxVendorManager.GetTaxes(taxCode, taxableAmount, sd, taxTypeId);

Adding the Inclusive Tax Component to Services

1. Login into the AdminPortal

2. Load the Setup

...

1. page

2. Select Roles and enable ServiceAttributeInclusiveTaxes permissions for the roles that need to be able to add/delete the Inclusive Taxes component

3. Return to the Setup

...

1. page and click on Services

2. Add the new Inclusive Taxes component on the Services where Inclusive taxes are required

To verify Taxing is working, first follow the Testing Billsoft  TaxingBillsoft Taxing section below, and then add the appropriate package to a test account and verify that inclusive taxation is occurring by referencing the Transactions tabpage.

Canadian Billsoft Tax Code Configuration

...

Avalara provides monthly updates which must be installed on your webserver for taxes to be calculated correctly. Avalara also provides monthly update instructions but generally they are as is listed below:

1. Login to Avalara Support site with your username and password

2. Download the update zip file for the monthly update

3. Stop the following services: (this is required as these may be 'holding onto' the EZtax dll's)

   • EngageIP Event Manager service

   • EngageIP Billing service

   • EngageIP Job Service

   • EngageIP Tier Sync service (if installed) (administrative tools/services)

   • Any other potential processes connected to EngageIP

4. Extract to the webserver on C:\BillSoftInstallFiles (the folder name is irrelevant as long as its extracted)

5. Execute 'update.exe' (based on BillSoft's instructions)

   • Check in the BillSoft /data folder that all files were updated - Billsoft will usually prompt you if a reboot is needed

6. Start services as needed from step #3

7. Reset IIS

8. Reboot of the server to fully release DLLs and clear any .TMP files that exist in the BillSoft folder (the Billsoft update may also request a reboot)

9. Testing / Confirmation

   • In the AdminPortal,  go to the top owner and click Configuration. At the bottom of the configuration page is the status of the BillSoft install as it relates to EngageIP. There should be no errors reported there, if there are, please contact LogiSense Customer Care

     Image Modified

   • Test that taxing is taking place. If not, review the Alerts report and event log report for detail

     • load the test customer acccount

     • add a transaction ($1.00 for example)

     • confirm taxes are applied and accurate
       Note: the first transaction added can take up to 5 minutes to load since the Billsoft files have to be initialized after the updates from Billsoft are installed on your system

   • Ensure that rating is running and working after the updates application (if you have usage rating in place and configured)

10. Check the Backup folder (C:\BillSoft\EZTax\Data\BACKUP) to ensure that back-up files are not consuming excessive disk space. Purge old files as needed

Extra Information

• Two attachments describing the list of tax categories Billsoft supplementary documents can be found in the Billsoft install directory (i.e. C:\BillSoft\win32_v9_0806\support\Docs). In this path you'll find tax category mapping information and other detailed info relating to your Billsoft installation

• Extra or missing p-codes can be found in a flat file here for reference: C:\BillSoft\EZTax\Txt\all_adr.txt

...

To test, you can perform the list of procedures below:

1. Go to a known good taxing account or where taxes have been applied previously

2. Click on their billing contact

3. Click on the Address contact point

4. Notice the 'Jurisdiction code'. This is auto generated by the Billsoft integration

   • Delete the jurisdiction code on the billing contact by clicking the 'delete' link beside it

   • Click save on the address screen (this will prompt the system to regenerate the code)

   • Click on the address contact point again and see if the jurisdiction code has been added again

   • If not, see troubleshooting below - possibly the Event Manager service isn't running or there is a larger issue

5. Next, on a good known taxing account that you can use for testing, add a test charge that should prompt the calculation and addition of taxes. i.e. add a $10 charge and confirm that taxes have been automatically calculated and applied

If both steps 4 and 5 are working, Billsoft has been updated correctly and is functioning correctly. If either one is not working, see troubleshooting steps below.

...

Event can be timer.midnight. Be sure that there is a timer named that in the database.

1. Open BOSS database

2. Open table 'WorkflowEventTimer'

3. Enter name in name column

4. Enter hours and minutes in same named columns, this is 24 hour time. 23 = 11pm

5. Hit enter. The first and last column can be left null and will be updated by the system.

6. Remember the exact naming here as it will be entered on the action below

Action:

It should not be triggered off of ContactPoint.Update or add since that will fight for resources with the general jurisdiction code updater script.

...

Description: The rate logic modifier provided by Avalara requires minor configuration in EngageIP to tell Billsoft the location of the override file (as sent through the API).

1. Create override file using rate logic modifier application - provided by Avalara

2. Copy or save the .ovr file that you created in step 1 to c:\billsoft\data\eztax.ovr  (as shown in the image below)

   Image Modified

3. Restart the following services

   • Event Manager service

   • EngageIP Billing service

   • IIS - (command: iisreset)

Billsoft Logging

Sometimes specific formats for taxes are required when submitting taxes payable to government departments or other organizations. The Tax Log was created as a way to provide a more direct export and streamlined format for the display of taxes payable. To ensure logging is being kept, you can turn it on in EngageIP by updating the EngageIPOption table:

1. Run this command in SQL:

   Code Block
   language sql
   INSERT INTO EngageIPOption (Name,VALUE) VALUES ('TaxLog','True')

2. Restart billing, event, job services.

3. Reset IIS

The TaxLog table has nothing to do with billing, it simply logs the taxes that were calculated and applied.

...

Failed: An EZTaxSession hasn't been specified for this transaction

1. Ensure that Environment Variables are setup and include a semicolon to separate the values. Also ensure that the server was rebooted after the Environment Variables were setup

2. Verify that the correct EZtax installer was run (32-bit or 64-bit)

Error: Initialize Failed

• If an OVR or UPR file was added or changed recently try reverting or removing those files and rebooting the server to confirm if those are the cause.

• Check that there is not an outdated EZTax2.dll in adminportal/bin or Services folders or anywhere else. They should be removed - The integration should really only ever rely on the Environment Variables to find that file in the Billsoft installation directory.

Taxes are not being Applied

1. Ensure you are viewing the invoice to verify that taxing is occurring (taxes are not reflected in the 'Amount' column on the Packages list)

2. If you are taxing using the Service or Billing Contact 'Address' ensure a Jurisdiction Code is present as a Component on the Address Contact Point (the JCode will be added automatically by EngageIP)

   • To see all accounts with no Jurisdiction Codes you can setup a Custom Report, see Find Missing Jurisdiction Codes for instructions. Refer to the 'Jurisdiction Code is not being added as a Component on the Address' section below for further troubleshooting steps

3. If a Jurisdiction Code is present ensure tax is applicable, for example some US States have no sales tax. Setup an account with an address which taxes are applicable to, for instance in Ontario HST is applied to all sales. If the JCode is being returned as zero, see the 'Jurisdiction Code Equals Zero' section below

4. Ensure the Account in question and its Parent Accounts (if any) do not have a 'Tax Exempt' or 'Tax Exempt Level' component present which would exempt the taxes you are attempting to apply

5. Check the Event Log Report for taxing errors

6. Make sure the default tax code (when in the US) is using the country name 'USA'. Having 'United States' specified there will not work as Billsoft wants to see 'USA'.

Jurisdiction Code is not being added as a Component on the Address

1. Ensure a valid address is entered (address must include a valid Country, State, City and Postal Code)

2. Ensure that the EngageIP Event Manager is running on the EngageIP App Server. The Event Manager assigns Jurisdiction Codes

3. Check the Event Log Report for taxing errors

EZTax.EZTaxInit() failed -- likely a license problem

...

Jurisdiction Code Equals Zero

1. For taxing in the United States run the INSERT script for 8.5.26.x that adds ISO code - INSERT INTO CountryISO (Name, ISOCode) values ('USA', 'US')

2. Ensure the correct State name is used next to the state short name: CA = California. Ensure other States are up to date accordingly as well

3. If you are running an EngageIP version previous to 8.5.17.0 and want taxes to be applied by Billsoft , you MUST use the service tax categories that Billsoft recognizes. Custom Service Tax Categories are not supported in earlier EngageIP versions

P-codes that Cannot be Found

...