Table of Contents | ||||
---|---|---|---|---|
|
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.
Normally within EngageIP taxes are calculated based on user-defined rates. A Tax Code which defines a geographical region will be setup under an Owner, within the Tax Code are rates which apply within the region (i.e. federal, state, county, city). To accurately tax a given customer, all necessary information regarding applicable taxes must be pre-populated by the Owner. A Tax Code which uses the EngageIP taxing system is setup using the Local tax vendor.
...
If no jurisdiction code is present for a contact's address when EngageIP tries to charge taxes, EngageIP will attempt to retrieve the proper code. If the code is found it will be stored in the database and EngageIP will continue with tax calculations. If this fails (or for some other reason a tax rate cannot be found) a record gets created to indicate that the statement detail was not taxed. EngageIP will reattempt to charge tax on this detail when the invoice is closed. If it is successful, then it will add the tax to the detail, and remove the flag that indicates taxing was unsuccessful. However, if taxing is still unsuccessful, then the flag will stay set. When the user's next invoice is closed, EngageIP will reattempt to tax these old details. If it is successful, it will create a new $0.00 detail on the current invoice with taxes on it, and a description to indicate that they're previously failed taxes. Currently, EngageIP will try indefinitely to charge the taxes for an account with each closed invoice.
Info |
---|
Note: to prevent EngageIP from continuing to attempt to charge failed taxes, you can remove the statementdetails row from StatementDetailsFailedTaxes table. |
Jurisdiction Updates
Billsoft automatically updates jurisdictional boundaries when billsoft updates are applied. Any alterations in jurisdictional boundaries (such as an expansion of a city limit) will be reflected in the JCode of locations that are situated within the expanded jurisdiction area. The Avalara tax research staff monitors jurisdiction taxation activity to maintain current and accurate taxation information. The results of this research is applied to monthly updates which are provided to insure the most accurate taxation is applied to the records processed by the billsoft Engine. JCodes change as monthly updates are applied, it is the users responsibility to re-populate their database tables with the new JCodes every time a Billsoft update is provided. If this task is not performed, the Billsoft Engine will return incorrect tax calculations for jurisdictions that have been updated. However, when a transaction is submitted with the stable and location sensitive p-code, the Billsoft Engine can use internal functions to obtain the correct jurisdiction. Since the Billsoft Engine is updated with the re-mapped jurisdiction information monthly, tax calculations are always performed with the most current jurisdiction taxation information that applies to the address defined by the p-code.
...
Taxes are applied based on the following criteria in order of precedence:
If service tax category or account tax category exist on the service or the account, take this into account when checking 2 and 3
If the tax code exists on account, tax based on tax code
Else if Service Contact exists, tax service based on Service Contact address
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).
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
If EngageIP is running on a 64bit server:
Ensure you installed the 64bit version of Billsoft
Verify the IIS APP POOL has 'Allow 32 bit' set to false
Verify HANDLERS in IIS has only one .rails pointing to FRAMEWORK64 (Check this for the AdminPortal and default sites)
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)
Reboot the system for the Path changes to take effect
In the EngageIP AdminPortal, Setup
...
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);
Configure the Billsoft tax vendor for transactional or invoice level taxing
To configure taxation per transaction:
Load the Setup page
Load Tax Vendor
Click Add
In the TaxVendor Type list select BillSoft
Click Save
For Vendor enter Billsoft
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);
Click Save
To configure taxation on invoice close:
See the invoice level taxing section below
Enable the tax log, detailed here (further down page) This is required for reporting and reconciliation purposes
Check on the Configuration page in the EngageIP AdminPortal to ensure scripts are compiling correctly. If not, check for errors
Update the Billsoft install folder (default install directory name is 'BillSoft') granting EVERYONE - FULL CONTROL permissions
In the AdminPortal
...
/ Setup
...
page add a Tax Code called 'Default' as shown below
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
Import Service Tax Categories or Setup Custom Billsoft Tax Types (EngageIP 8.5.17.0+ required)
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:
...
...
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.0See the Setting up Custom Billsoft Tax Types section below if you wish to setup Custom Billsoft Tax Types
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'Import Account Tax Categories using the XML
...
provided in the 'Import Documents' area below or Configure Tax Categories on the Setup
...
page and add them to the customer accounts as required
...
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
For EngageIP 8.5.26.0+ Installs:
Download, extract and run the
...
EZTaxTaxTypeMappingInsertScript provided below on the EngageIP DB server to create and populate the EZTaxTaxTypeMapping table
Import Documents:
|
| ||||||||
|
Post Configuration Steps
Testing
To validate that the Billsoft integration is working in EngageIP, do the following:
Add an Account
Load the Contacts
...
page / Billing Contact
Add an Address Contact Pointy Type to the Billing Contact
Verify that the Billing Contact Address has a Jurisdiction Code Component added to it automatically (if not see Troubleshooting section below)
Add a Package that contains a Service to the account. The tax should be automatically calculated out of the EZtax database
Check the customer invoice or Transactions
...
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
To add jurisdiction codes to all customers in the system (if you've configured Billsoft after customer Accounts were already present in EngageIP) without the need to navigate to and save every Address Contact Point Type, you can use the updater tool on the webserver located here:
...
C:\Program
...
Files
...
(x86)\EngageIP\Tools\
Double click the 'ContactPointAddressUpdate.exe' executable. This tool when run will look at all Users and attempt to add Jurisdiction Codes where there are none.
...
Setting up Custom Billsoft Service Tax Types
...
Info |
---|
Note: These do not work for the Avatax implementation or cloud implementation. This only works for on premise Billsoft. For Avatax cloud, add items with correct T/S pair to the EZTaxTaxTypeMapping table in the database |
...
. |
...
Requires EngageIP 8.5.17.0 or higher
Load the Setup
...
page
Click on Service Tax Categories
Click the Add button
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)
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
Click Setup
...
Click Services
Click on the name of the desired service
Click the Add button under Components
Select Service Tax Category
Select the appropriate item
Click the Save button
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.
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
INSERT INTO EngageIPOption (Name,VALUE) VALUES ('CDRLevelTax','true') |
...
The rating script should look something like below and have the 'Set UDR Taxing' processor in it:
...
Info |
---|
Note: UDRBillerTax and StatementdetailsTax may both contain information, however only one is referenced based on the CDRLevelTax configuration described above. |
International Taxing
International taxing with functions very similarly to the way US and Canada taxing functions. In the postal code text box, enter a valid code, and ensure that the country on setup has a valid ISO defined, 2 character. This will match to the CountryISO table in the EngageIP database.
...
<TaxType Owner="admin" TaxType="Telephony Service"/>
TransType | TRANS_ALIAS | ServType | SERVICE_ALIAS |
15 | Telephony | 7 | Service |
15 | Telephony | 624 | Wireless Service |
15 | Telephony | 627 | Internet Access |
15 | Telephony | 629 | Messaging Services |
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.
Info |
---|
Note: you need to have the UserAttributeTaxExempt and UserAttributeTaxExemptLevel Role Permissions configurd on your Role to see each option under components on an account. |
Info |
---|
Note: an exemption at the parent level will apply to all sub account levels as well so there is no need to duplicate exemptions on child / sub accounts. Parent and Sub account refer to specific EngageIP account levels. This does not apply to Owner accounts. Accounts in EngageIP are one of these these types, Owners, Parents, Sub accounts (where you may have sub accounts of sub accounts also for more levels) |
All - this exempts ALL Billsoft taxes
Federal
County
State
Local
County_Local
Other
State_County_Local
Unincorporated
Info |
---|
Note: if you want to exempt County, State and Local taxes, which may tax individually, you need to add each individually rather than just selecting 'State_County_Local'. The 'State_County_Local' is only for tax line items that are an aggregate tax for these three definitions. |
Configuring Tax Exempt Levels
...
Info |
---|
Note: Tax exempt types as of 8.5.17.x are added into the TaxExemptType table for use in the exemption levels component during upgrades. When the upgrade occurs to EngageIP, it loads the current tax types from the billsoft dlls and adds them to the existing list of tax types which you can then use going forward. If Billsoft has new tax types but they do not exist in EngageIP, you can manually add them to the TaxExemptType table, reset IIS and restart services, and then test their application on accounts to confirm exemptions are working as expected. |
Tax Exempt Type Import XML file: TaxExemptTypes
View file | ||
---|---|---|
|
Account Level Tax Exemption:
Click on the Overview
...
page of the account you wish to apply tax exemption to
On the right side under Components click Add
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
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)
To TestTesting:
Add a transaction that taxes with the tax you want to exempt
Confirm the tax is charged as expected
Add the new exemption
Add a new transaction for the same amount
Confirm that the tax amount is zero for that same tax type
Tax Override Options
Info |
---|
Note: If overrides exist that are the same in multiple places, there may be errors in the Billing service log file (or other service log files) stating that tax overrides cannot be added. This is due to there being multiple overlapping overrides or tax exclusions and Billsoft is tossing out the duplicate overrides where encountered. This is a non-issue as taxes will be applied correctly using the first override that Billsoft processes. |
There are two basic ways to override taxes when using the Billsoft integration
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.
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.
...
Excluding Country or State Taxes Per Owner
Tip |
---|
New feature in EngageIP 8.5.27.0 |
The configuration steps below describe how to exclude taxes per Owner at a Country level (both Federal and State taxes) or at a State level (State/Provincial taxes only).
...
Tax Exclusion Configuration:
Load the Setup
...
page
Under the Taxes heading click on Tax Exclusions
Click Add
Enter the details for the location you wish to exclude from taxation
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)
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
View file | ||
---|---|---|
|
Then do the following:
Load the Setup
...
page
Click on Import
Either click Choose File or paste the XML into the XML Data field
Click Save and you should see a 'Import successful.' message
Return to the Setup
...
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.
Open BOSS database
Execute table creation queries as below
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)'Reset IIS - this is required for EngageIP to read the table after you've updated it
Login to adminportal
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:
Code Block | ||
---|---|---|
| ||
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"] |
...
Configuring Inclusive Taxes on Services
Tip |
---|
New feature in EngageIP 8.5.25.0 |
When added to a Service the 'Inclusive Taxes' Component cause taxes to be calculated within the set price of the Service in question. Inclusive tax calculations are performed by Billsoft with EngageIP using the returned values to set the revenue and taxes on Services.
Info |
---|
Note: Inclusive Tax is not applicable to transaction reversals, credits or usage. |
Inclusive Tax System Configuration
Access the EngageIP host
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)
Using a Text Editor add the following line at the end of this file
reversecalcsession=on
Save and close the file
Load the EngageIP Adminportal Setup
...
page and select Tax Vendor
Edit the BillSoft tax vendor and replace the existing script with the one listed below
BillSoft Tax Vendor ScriptCode 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
Login into the AdminPortal
Load the Setup
...
page
Select Roles and enable ServiceAttributeInclusiveTaxes permissions for the roles that need to be able to add/delete the Inclusive Taxes component
Return to the Setup
...
page and click on Services
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:
Login to Avalara Support site with your username and password
Download the update zip file for the monthly update
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
Extract to the webserver on C:\BillSoftInstallFiles (the folder name is irrelevant as long as its extracted)
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
Start services as needed from step #3
Reset IIS
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)
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
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)
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:
Go to a known good taxing account or where taxes have been applied previously
Click on their billing contact
Click on the Address contact point
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
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.
...
If jurisdiction codes are not able to be found, the Billsoft integration will simply assign a zero for the pcode (jurisdiction code). To locate and update these in an automated fashion, the following action can be implemented to set generic pcodes in states / provinces where its not able to locate a specific pcode.
Event:
Event can be timer.midnight. Be sure that there is a timer named that in the database.
Open BOSS database
Open table 'WorkflowEventTimer'
Enter name in name column
Enter hours and minutes in same named columns, this is 24 hour time. 23 = 11pm
Hit enter. The first and last column can be left null and will be updated by the system.
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.
Info |
---|
Note: of the two scripts below, one is for ID based states (state predefined) and one is for manually entered states (not predefined). |
The below is for free form state entry, where state is not configured as predefined so this looks by state name, not ID. Need to determine which the system users and select the appropriate action 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).
Create override file using rate logic modifier application - provided by Avalara
Copy or save the .ovr file that you created in step 1 to c:\billsoft\data\eztax.ovr (as shown in the image below)
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:
Run this command in SQL:
Code Block language sql INSERT INTO EngageIPOption (Name,VALUE) VALUES ('TaxLog','True')
Restart billing, event, job services.
Reset IIS
The TaxLog table has nothing to do with billing, it simply logs the tax taxes that was were calculated and applied.
Temporary Disabling Billsoft Integration
...
Ensure that no taxcodes are associated to Billsoft taxvendor, if they are, the next item will error with foreign key error.
Remove the TaxVendor EZtax (or named Billsoft)
Remove all the workflows related, ie i.e. pcode action that sets jurisdiction code
...
Failed: An EZTaxSession hasn't been specified for this transaction
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
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
Ensure you are viewing the invoice to verify that taxing is occurring (taxes are not reflected in the 'Amount' column on the Packages list)
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
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
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
Check the Event Log Report for taxing errors
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
Ensure a valid address is entered (address must include a valid Country, State, City and Postal Code)
Ensure that the EngageIP Event Manager is running on the EngageIP App Server. The Event Manager assigns Jurisdiction Codes
Check the Event Log Report for taxing errors
EZTax.EZTaxInit() failed -- likely a license problem
...
Jurisdiction Code Equals Zero
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')
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
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
...
To auto update these with an action, see the 'Zero Jurisdiction Code Updater Action' section belowabove.
Rate / Tax Bundler
If you're using the tax bundler file and entering more rows, the max number of a row is 32000 so if you try to use 50000 it won't be used.
...
To assign in EngageIP, add a new service tax category with that bundle name and IDs per format below.
CustomEZTax(BundleLongDistanceBucket,20000,20003) |
...
Invoice Charge Script - Taxing on Invoice Close
Info |
---|
Note: this functionality requires EngageIP 8.5.27.0 or newer to function. |
As the name implies tax on invoice close (a.k.a. InvoiceLevelTaxing) calculates and applies tax when closing an invoice. If the invoice is opened, taxes will remain but if the invoice is closed again taxes will be recalculated. Taxlog entries will be removed accordingly and added back in a reopen/close invoice scenario.
...