CCH® SureTax® for Dynamics 365 Field Service User Guide

Updated: Sept 30, 2024

Introduction and Pre-Requisites

Welcome to CCH SureTax for Microsoft Dynamics 365 Field Service

CCH SureTax for Dynamics 365 Field Service helps you accurately calculate sales tax and to validate addresses.

  • CCH SureTax package is composed of the following:
    • CCH SureTax Sales solution
      • This contains the CCH SureTax Power App
        • CCH SureTax Configurations are performed here
    • CCH SureTax Field Service solution
  • Supported industries: General Sales
  • Supported Modules:
    • Microsoft Dynamics 365 Field Service version 8.xx.xx.xxxx (online)
  • Supported countries: United States and Canada
  • Supported Dynamics 365 Field Service forms and workflows for tax calculation:
    • Opportunities
    • Quotes
    • Orders
    • Invoices
    • Work Orders
    • Purchase Order

CCH SureTax Pre-requisites and Configuration

For this add-on to function correctly, you must have the following:

  • Valid client number and validation key for CCH SureTax V07 (Calculation) and CCH SureTax Data API enabled for your account.
    • Endpoint URLs for CCH SureTax V07 and Data API.
      • The URL for CCH SureTax will typically look like the following:
        • https://<hostname>/Services/V07/SureTax.asmx
      • The URL for CCH SureTax Data API will typically look like the following:
        • https://<hostname>/v01/
    • Your CCH SureTax Client Number and Validation key are typically identical for both of the above.
    • Please contact your CCH SureTax representative for any questions.
  • From the CCH SureTax portal (you can get your login and URL from your CCH SureTax representative), you must do the following:
    • Nexus Configuration
    • SKU/Product mapping setup
      • SKU named 'Freight' must be setup.
      • At a minimum, we recommend that you create a SKU mapping to act as your default SKU mapping, which allows you to use unmapped SKUs:
        • E.g.
          • SKU / Product Value = -1
          • Customer Type = 99 -- Default
          • Regulatory Code = 99 -- Default
          • Transaction Type Code can be set to the default product you want to use (for example, 990101 - General Sales)

For this add-on to function correctly, you must have the following:

  • Valid client number and validation key for CCH® SureAddress™ V02 API enabled for your account.
    • Endpoint URLs for CCH® SureAddress™ V02.
      • The URL for CCH® SureAddress™ will typically look like the following:
        • https://\<hostname\>/v02/SureAddress.asmx
    • Please contact your CCH® SureAddress™ representative for any questions.

Installation and Configuration

Installing CCH SureTax for Dynamics 365 Field Service

The following section includes instructions for installing the following CCH SureTax for Microsoft Dynamics 365 Field Service.

  1. Unzip the package file CCH_SureTax_for_Dynamics_365_FieldService_Package_AppSource.zip
  2. Unzip package.zip
  3. There should be 2 solutions
    1. package/PkgAssets/CCHSureTaxSales.zip
    2. package/PkgAssets/CCHSureTaxFieldService.zip
  4. CCH SureTax solutions can be installed directly through Microsoft Power Apps
    1. Navigate to https://make.powerapps.com
    2. Select the desired environment at the top right corner.
    3. Select Solutions at the bottom left corner.
    4. Import each solution in the order shown below
      1. Import CCH® SureTax Sales Solution zip file with the name CCHSureTaxSales.zip
      2. Import CCH® SureTax Field Service Solution zip file with the name CCHSureTaxFieldService.zip
      3. Click on Publish all Customizations.
  5. CCH SureTax solutions can be installed directly through your environment
    1. Navigate to your D365 environment (ex https://sample.crm.dynamics.com/)
    2. Select Settings at top right corner => Advanced Settings => Customization => Solutions
    3. Follow Step 3d from above.
  6. CCH SureTax Package can be installed using the Microsoft CRM tool PackageDeployment.
    1. Unzip the package.zip from
    2. Copy over the following files from package.zip to the root of your PackageDeployment folder
      1. PkgAssets
      2. CCH.SureTax.CE.FS.PackagingDeployment.dll
    3. Run the PackageDeployer.exe
    4. Select the environment to be deployed.
    5. Follow all steps until successfully deployed.

User Security Tasks & Security Roles

Security roles allow you to assign user permissions for various parts of this add-on. Assign roles to your users to ensure they have access.

  • SureTax Power User
    • Have permissions to edit and view all CCH SureTax fields on supported forms
  • SureTax Basic User
    • Have permissions to view CCH SureTax fields on supported forms.
    • Edit permissions are allowed for header/line item CCH SureTax settings for Opportunities, Quotes, Orders, Work Orders, and Invoices.
  • NOTE: CCH SureTax settings for Products, Accounts, and Contacts can be edited if user has access to these Entities.

CCH SureTax Basic Config

This section configures the connection settings required for tax calculation and data setup. This data is stored at the Dynamics 365 Business Unit (Team/User) level.

To configure settings, do the following:

  • Open CCH SureTax Power App -> Click on Basic Config under Setup
  • Basic Configuration -- General Settings:
    • All fields are required, except for CCH SureTax Business Unit (note that this is different from Dynamics 365 business unit).
    • Enable SureTax -- If 'No', then this integration will be disabled for most part except Basic Config (above screen).
    • Disable Auto Calc --
      • If set to 'Yes', the calculation on all taxable form will be triggered only when 'Calculate Tax' button on each of the Transaction forms is used.
      • If set to 'No' the integration will calculate tax on all Transaction forms' tax relevant field updates.
    • After values are filled in continue to SureTax Data API tab.
  • SureTax API:
    • All fields in this section are required to establish connection with SureTax and Calculate Tax on relevant transaction forms.
  • SureTax Data API:
    • All values in this section are needed to connect to CCH SureTax Data API. All fields are required.
    • After all fields are entered, click Save
    • Click on the button 'Import SureTax Data' to setup CCH SureTax data on your system.
      • This uses connection data stored for SureTax Data API to import tax data into relevant CCH SureTax entities.
      • Imported data from here is stored at the Organization level.
      • Note that feature checks to see if used SureTax Entities used to import data into have any failed Keys during creation (see Known issues). If any Failed keys are found, jobs will be made to activate keys for Entities used for SureTax Data. User will have to wait for the jobs to complete before attempting to Import SureTax Data again.
    • 'Validate' button -- Can be used to verify that your values are valid.
    • 'Copy Settings' button -- If you have more than 1 Dynamics 365 business unit, you can use 'Copy Settings' button to copy CCH SureTax settings
      • Basic Config
      • Sales Config
      • Field Service Sales Config
      • Field Service Purchasing Config
      • Project Operations Sales Config

from another business unit. It is recommended to use this after 1 Dynamics 365 business unit has been setup completely with CCH SureTax settings as all settings will be copied.

  • 'Update Plugin Steps' -- Can be used to update plugin steps if more than one of our solutions is installed
    • If 'CCH SureTax Sales' solution is installed and 'CCH SureTax Field Service' solution is installed after it, then use this button to make sure all the required filtering and image attributes are in the respective plugin.
    • Even if the order is reversed for installation of our solutions, use the button to make sure all the required filtering and image attributes are in the respective plugin.

Configuring CCH SureTax Field Service Setup Sales Config

The Field Service > CCH SureTax Sales Config form contains settings that can be configured at the Dynamics 365 business unit level. To configure settings, do the following:

  1. Open CCH SureTax Power App -> Field Service -> Click on Sales Config
    1. Sales Config
  2. Enable SureTax - You can select specific forms to enable taxcalculation for.
  3. Update Order Lines - selection, select Yes/No. This determines when to update transaction lines for an order/invoice when a header level setting is updated.
  4. Tax Rule Override -- Default Tax Logic is recommended, but you can select other options based on your business needs (This sets 'RuleOverride' value sent to CCH SureTax during calculation).
  5. Calc Option for Non-Taxable items --

    1. Do Not Send Item to SureTax

      1. On each taxable transaction form, we do not send the line item to SureTax for tax calculation if the item is nontaxable.

    2. Send Item as Full Exempt

      1. On each taxable transaction form, we send the item to SureTax for tax calculation as fully exempt if the item is nontaxable.

    3. Note Opportunity Products do not have taxability option.

    4. Note Quotes, Sales Orders, and Work Order service lines do have taxability options - So when a user creates an invoice from a Sales > Order/Work Order, we use the original order's line item's taxability for invoice tax calculation based on the above option.

  6. Product Line Defaults and Service Line Defaults section contains all defaults used for tax calculation based on the line type
    1. Tax Exemption Code. Example: 00 -- No Exceptions.
    2. Regulatory Code. Example: 99 (DEFAULT).
    3. Sales Type Code. Example: T (Retail).
    4. Transaction Type Code. Select the most frequently used Transaction Type Code for your business. Example: "990101 - General Sales."
    5. Unit type Code. Example: Select 99 for General Sales.
    6. Tax Situs Rule. Example: Select 22 for General Sales.
    7. Tax Exempt Reason Code.
  7. Freight Defaults:
    1. Tax Situs Rule -- Only used for freight. Example: Select 22 for General Sales.
    2. Transaction Type Code -- Only used for freight if Stocking Unit preference is set to Transaction Type Code.
  8. Click Save to save the options on the CCH SureTax Field Service Config form.
  9. Ship-From Address:
    1. Enter the default Ship From Address used for tax calculation.
    2. ShipFromAdress
      1. Please enter all values, only Address Street 2 is not needed.
        1. Country is expected to be 2 digits abbreviation (e.g. US, CA, et1.)
    3. Click Save

SKU Preference and Data Exchange

The Field Service > CCH SureTax Sales Config and Field Service Purchasing Config form contains SKU Preference settings and Data Exchange that can be configured at the Dynamics 365 business unit level. To configure settings, do the following:

  1. SKU Preference:
    1. Sku Pref
    2. The SKU Preference feature is a way for user to set the SKU for each Product line item of Opportunities, Quotes, Sales Orders, and Invoices. The SKU can be assigned a value from a specific set of columns from relevant database Tables.
    3. To use this feature, Select the one record with Transaction Type as "Product Lines" will open up the SKU Preference form for user to edit.
    4. If the Stocking Unit Preference is "Transaction Type Code", the SureTax Transaction Type code associated with the product for a line item will be sent as the SKU. (For example, the common TransTypeCode 990101-General Sales will be assigned as the SKU)
    5. Keep in mind, Transaction Type Code is the default selection.
    6. However, if user change the Stocking Unit Preference to "SKU", the SKU Preference Table is now selectable.
    7. User can then select the Database Table. Only relevant tables are shown to the specific Transaction Form. (For example: Quote, Quote Detail, and Product tables are shown for the Transaction Form: Quote)
    8. On select of a table, its corresponding column names are populated in the SKU Preference Column dropdown list. User can now set the column fiel1.
    9. The value of that column will be sent as the SKU to SureTax for a line item. (For example: setting the column "name" for the table "Quote" means that the quote's name will be sent as the SKU for all line items of that quote.)
  2. Data Exchange:
    1. Data Exchange
    2. The Data Exchange feature is a way for user to set the value of each of the 15 Data Exchange parameters. Each parameter can be assigned a value from a specific set of columns from relevant Tables. Or it can be assigned a static text with the "Manual Text Entry" option.
    3. These 15 parameters are optional fields that are sent with each line items to SureTax. They can be set for each Product line item of Opportunities, Quotes, Sales Orders, and Invoices.
    4. To use this feature, first select the Transaction Form you want to edit. The corresponding subgrid will be shown.
    5. When user click on a record of the parameter they want to edit, the Data Exchange form will open.
    6. User can then select the Database Table. Only relevant tables are shown to the specific Transaction Form. (For example: Quote, Quote Detail, and Product tables are shown for the Transaction Form: Quote)
    7. The option of "Manual Text Entry" is also there that will allow you to set a static text for this parameter. Once selected in the Table dropdown, the Manual Text Entry field will be editable for user to enter.
    8. However, on select of a table, its corresponding column names are populated in the Column dropdown list. User can now set the column field.
    9. The value of that column will be sent as the parameter to SureTax for a line item. (For example: setting the column "name" for the table "Quote" for the Parameter "Cost Center" means that the quote's name will be sent as the CostCenter field for all line items of that quote.)

Configuring CCH SureTax Field Service Setup Purchase Config

The Field Service -> CCH SureTax Purchase Config form contains settings that can be configured at the Dynamics 365 business unit level. To configure settings, do the following:

  1. Open CCH SureTax Power App -> Field Service -> Click on PurchasingConfig
    1. Purchase Config
  2. Enable SureTax - You can select specific forms to enable tax calculation for.
  3. Update Order Lines - Determines if each transaction line item levelsettings will be updated when a header level setting is updated.
  4. Tax Rule Override -- Default Tax Logic is recommended, but you can select other options based on your business needs (This sets 'RuleOverride' value sent to CCH Sure Tax during calculation).
  5. Line Defaults and Service Line Defaults section contains all defaults used for tax calculation based on the line type
    1. Tax Exemption Code. Example: 00 -- No Exceptions.
    2. Regulatory Code. Example: 99 (DEFAULT).
    3. Sales Type Code. Example: T (Retail).
    4. Transaction Type Code. Select the most frequently used Transaction Type Code for your business. Example: "990101 - General Sales."
    5. Unit type Code. Example: Select 99 for General Sales.
    6. Tax Situs Rule. Example: Select 22 for General Sales.
    7. Tax Exempt Reason Code.
  6. Shipping Defaults:
    1. Transaction Type Code -- Only used for freight if Stocking Unit preference is set to Transaction Type Code.
  7. Click Save to save the options on the CCH SureTax Field Service Purchase Config form.

Configuring CCH SureTax Settings for Products

Optional settings that override default values used for tax calculation can be configured for Products.

To configure settings, do the following:

  • Sales 🡪 navigate to Products 🡪 Select an Existing product
  • Click on CCH SureTax Dropdown 🡪 Settings Button
    • Product Settings
  • It will open a new form (shown above), where you can set:
    • Tax Situs Rule
    • Transaction Type Code

Configuring CCH SureTax Settings for Customers (Accounts and Contacts)

Optional settings that override default values used for tax calculation can be configured for Customers (Accounts and Contacts).

To configure settings, do the following:

  • Sales 🡪 navigate to Accounts or Contacts 🡪 Open existing Account/Contact
  • Click on CCH SureTax Dropdown 🡪 Settings Button
    • Account Settings
    • It will open a new form (shown above), where you can set:
      • Enable SureTax
      • Tax Exemption Code
      • Sales Type Code
      • Tax Exempt Reason Code

Using CCH SureTax for Dynamics 365 Field Service

Tax Calculation

  • Tax is calculated on supported forms if CCH SureTax is enabled. Tax calculation with CCH SureTax is triggered at the following:
    • On save at the header level.
    • Product (Line Item) is added/edited.
    • Only changes to tax relevant fields are used to determine when tax calculation is triggered.
  • Features specific to Invoices:
    • Invoice Paid - is supported by posting to CCH SureTax
      • Note: CCH SureTax will post the whole invoice regardless of Status Reason being Complete or Partial, as partial posting not supported correctly by Dynamics 365 Sales.
        • Complete Invoice
        • Partial Invoice
    • Cancel Invoice - will cancel the posted invoice in CCH SureTax

Configuring CCH SureTax Header Settings

The CCH SureTax Settings form is available at the header level for all supported forms, is used to modify settings used for CCH SureTax calculation. Initial values are set based on default configured in CCH SureTax Sales Config, but CCH SureTax Settings set on Products and Customers take precedence (used if they are set).

  • Open supported form -> Fill in tax relevant details -> Save
  • Click on the CCH SureTax Dropdown 🡪 Header Settings button to view/edit CCH SureTax Settings.
    • Header Settins button
    • Header Settings Screen
  • You can modify the following fields:

    1. General Settings:

      1. Enable SureTax

    2. Date Settings:

      1. Transaction Date -- Date used for tax calculation date and initialized to when associated entity (e.g. Opportunity, Quote, Order, Invoice) is created.
      2. Compliance Date -- Available only for Invoices. Date used for Compliance Year/Month for tax calculation. If blank, the posting date of invoice used, otherwise, the entered date is used.
        1. Date Settings

    3. Header Settings Field Service:

      1. Tax Exemption Code
      2. Tax Exempt Reason Code
      3. Regulatory Code
      4. Sales Type Code
      5. Tax Situs Rule. Select the default Tax Situs Rule (e.g., 22 for General Sales).
      6. Transaction Type Code.
      7. Unit Type Code. Select the default code (e.g., 99 for General Sales).
      8. All these fields will be available for Product line as well as Service line

    4. Freight Settings:

      1. Transaction Type Code.
      2. Tax Situs Rule. Select the default Tax Situs Rule (e.g., 22 for General Sales).
      3. Any form that supports Freight and Shipping, and would want to support CO Retail Delivery Fee, the Freight Amount needs to be entered into field even if its $0.

Configuring CCH SureTax Line Settings

Line settings are like the above for header settings but can be set for line items (Products).

  • Open supported form -> Fill in tax relevant details -> Save
  • Add Product (line item) and fill in details (or open existing).
  • While viewing the line item, CCH SureTax Dropdown 🡪 Line Settings button to view/edit CCH SureTax Settings.
    • Line Settings Button
    • Line Settings Screen
  • You can modify the following fields:
    • Line Settings:
      • Enable SureTax
      • Tax Exemption Code
      • Regulatory Code
      • Sales Type Code
      • Transaction Type Code.
      • Unit Type Code. Select the default code (e.g., 99 for General Sales).
      • Tax Situs Rule. Select the default Tax Situs Rule (e.g., 22 for General Sales).
      • Tax Exempt Reason Code

Ship-To and Ship-From addresses used for CCH SureTax Calculation

Sales tax calculation requires a ship-to and ship-from address to accurately calculate sales/use tax. The CCH SureTax add-on uses the following on each supported form:

  • Ship-From Address:
    • 'Default Ship-From Address' set in CCH SureTax Field Service Config.
  • Ship-To Address:
    • The address entered at each supported form.
  • Purchase Order forms
    • Ship-From Address:
      • Vendor Address
    • Ship-To Address
      • Whichever option is selected in "ShipTo" field of Purchase order.
      • Based on that field, an address will be populated in the Address Tab of Purchase Order.

Viewing CCH SureTax Tax Details

Once tax is calculated, you can view details on supported forms (at header level), by view CCH SureTax Tax Details tab.

  • Open any supported form at header level.
  • Ensure you have calculated tax.
  • Click on CCH SureTax Dropdown 🡪 Tax Details Button.
  • Here you can view detailed tax data.
  • Tax Details
  • Note that you can expand the Line item to quickly see more information (refer above screenshot)
  • To view more details for line items, click on the line item and the '->' icon on the right.
    • Line Item Details
  • While viewing the line-item tax details, you can click on CCH SureTax Tax Details tab to view tax jurisdiction level tax data.
    • Jurisc Details

Uninstalling and Updating

Uninstalling the CCH SureTax Add-on

To uninstall the CCH SureTax add-on, you can delete the CCH SureTax solutions:

  • Go to Power Apps site (e.g. https://make.powerapps.com/)
  • Select your environment.
  • Select Solutions from the left navigation.
  • Delete solutions in below order
    1. Delete CCH SureTax Field Service solution
    2. Delete CCH SureTax Sales solution.
  • Note: This will delete all data, so please backup CCH SureTax data (if needed) before proceeding.

Updating a CCH SureTax Add-on

To update to a newer version of the CCH SureTax add-on, do the following:

  • Follow the same directions and install the CCH SureTax Add-on. This will update the existing solutions.

Appendix

How CCH SureTax API is used

  • All calculation requests are sent as Quotes to CCH SureTax, except for Finalized requests, which are made when an Invoice is paid.
    • If CCH SureTax returns an error during tax calculation, the add-on stops the system from posting the document within Dynamics 365 Sales.
  • Freight is sent as a separate line item to CCH SureTax.
    • If Stocking Unit preference > Transaction Type Option is set to SKU, "Freight" must be mapped in CCH SureTax.
  • Country field used in all Address fields expect a 2 digits ISO code. If no country is set, CCH SureTax will send a blank string for country code.
  • Currency is expected to be for the country of the Ship-To address (CCH SureTax API does not perform currency conversion).
  • Discounts:
    • Discounts are subtracted from line item amounts before they are sent to CCH SureTax for tax calculation.
    • Header Discounts are applied proportionally to all line items before they are sent to CCH SureTax for tax calculation.

CCH SureTax API Mapping for Tax Calculation

For the below, left is CCH SureTax data and the right describes what is used from Dynamics 365.

Each CCH SureTax transaction is created with the following data at the header level:

  • <ClientNumber> - From CCH SureTax Basic Config
  • <ValidationKey> - From CCH SureTax Basic Config
  • <DataYear>, <DataMonth> - Transaction Date from CCH SureTax Settings
  • <CpmlDataMonth>, <CpmlDataYear> - Compliance Date from CCH SureTax Settings
  • <ResponseType> - "12C<CURRENCY_PRECISION>", e.g. if currency precision is 2 in Dynamics 365, then 12C2 would be used, the number 2 (on the right) sets the tax calculation response's decimal precision.
  • <ResponseGroup> - "00"
  • <STAN> - blank
  • <TotalRevenue> - Sum of all line amounts including Freight with discounts subtracted.
  • <ReturnFileCode> - "Q" used all times except "0" for when invoice is posted.

Each CCH SureTax line item is created with the following data (Freight is considered as a line item):

  • <InvoiceNumber> - The ID of the respective entity, which can be Opportunity ID, Order ID, Quote ID, or Invoice ID.
  • <LineNumber> -- In order and increments starting with 0, but 'freight' is the value used for the Freight line item.
  • <CustomerNumber> - Account Name or Customer Name
  • <RegulatoryCode> - The Regulatory Code (Provider) from Field Service > CCH SureTax Sales Config
  • <SalesTypeCode> - The Sales Type Code (Customer) from Field Service > CCH SureTax Sales Config or Accounts/Contacts CCH SureTax Settings
  • <LocationCode> - blank
  • <TransDate> - Transaction Date from CCH SureTax Settings
  • <Revenue> - Amount for the line item. Any discount will be subtracted before in the price sent.
  • <TaxIncludedCode> - "0"
  • <Units> - Line item's Quantity
  • <FreightOnBoard> - "blank" (default). Can be configured in CCH SureTax Shipping Method Settings
  • <AuxRevenueType> - "01" (default)
  • <AuxRevenue> - "0" (default)
  • <TaxSitusRule> - Use "22" for General sales. This is configured at Field Service > CCH SureTax Sales Config and Products CCH SureTax Settings.
  • <RuleOverride> - "0" (Default). This can be configured in Field Service > CCH SureTax Sales Config.
  • <UnitType> - Use "99" for General sales. This is configured at Field Service > CCH SureTax Sales Config and Products CCH SureTax Settings.
  • <CommonCarrier> - "blank" (default). Can be configured in CCH SureTax Shipping Method Settings
  • <CurrencyCode> - Dynamics 365 Currency Code
  • <TaxExemptionCodeList> - From Field Service > CCH SureTax Sales Config or Account/Contacts CCH SureTax Settings.
  • <ExemptReasonCode> - From Field Service > CCH SureTax Sales Config or Account/Contacts CCH SureTax Settings.
  • <TransTypeCode>
    • Field Service > CCH SureTax Sales Config > Stocking Unit preference drives whether to use Transaction Type Code or SKU information (note SKUs must be mapped in CCH SureTax to use the SKU option)
      • If set to Transaction Type Code, the Transaction Type Code will be used for the GP Item.
        • This is configured at Field Service > CCH SureTax Sales Config and Products CCH SureTax Settings.
      • If set to SKU, the Product ID will be used. For write-in Products, Write-In Product (User entered value) will be used.
        • If Field Service > CCH SureTax Sales Config -> SKU Option is set to Product Family, then the Product ID of the parent is used.
  • <ShipToAddress> - Ship To address entered on the form.
    • Note that Will Call toggle on supported forms do not affect tax calculation, the correct Ship To address is expected to be filled on the form.
  • <ShipFromAddress>
    • Default Ship From address entered in Field Service > CCH SureTax Sales Config.
  • <BillToAddress> - Bill To address entered on the form.

Customized Entities and Plugins

This CCH SureTax add-on uses customized entities and plugins to integrate seamlessly with Dynamics 365 Field Service.

Please view the CCH SureTax for Dynamics 365 Field Service Detailed Technical Documentation (DTD) for more information.

Known Issues

  • Entity Key creation may fail after installation of the Package. This can affect Entities used for 'Import SureTax Data'. If there are any failed keys, 'Import SureTax Data' will check for and attempt to fixed failed keys. If this happens, you must wait for system jobs to finish before attempting to 'Import SureTax Data'.