Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  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)

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

  5. In the EngageIP AdminPortal, Setup tab 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);

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

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

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

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

  10. In the AdminPortal > / Setup tab 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

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

  12. 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 tab 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

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

...

  1. Add an Account

  2. Load the Contacts tab > page / Billing Contact

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

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

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

  6. Check the customer invoice or Transactions tab page to verify that taxes are being applied

...

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

...

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.

...

  1. Load the Setup tab 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

...

Adding Service Tax Categories to Services

  1. Click Setuptab

  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

...

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
languagesql
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
languagesql
INSERT INTO EngageIPOption (Name,VALUE) VALUES ('CDRLevelTax','true')

...

Account Level Tax Exemption:

  1. Click on the Overview tab 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)

...

Tax Exclusion Configuration:

  1. Load the Setup tab 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

    • 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

...

Then do the following:

  1. Load the Setup tab 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 tab page and load the Tax Exclusions page to verify the imported exclusions are present

...

Create Tables SQL:

Code Block
languagesql
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"]

...

  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 tab page and select Tax Vendor

  6. 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);

...

  1. Login into the AdminPortal

  2. Load the Setup tab page

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

  4. Return to the Setup tab page and click on Services

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

...

  1. Run this command in SQL:

    Code Block
    languagesql
    INSERT INTO EngageIPOption (Name,VALUE) VALUES ('TaxLog','True')
  2. Restart billing, event, job services.

  3. Reset IIS

...