The first step consists in getting a subscription allowing you to use Avalara tax management solution with CPQ. You will have to follow the AvaTax account activation process on www.avalara.com.

The Avalara connector is natively integrated in Smart CPQ, meaning that you don’t have to download or install anything. You will just have to follow the steps below explaining how to setup the connector.

Once your subscription valid, you have to fulfill the section of the cameleon.properties file dedicated to Avalara with the service URL and credentials (user / password), and the path to the AvalaraMapping.xml file on the CPQ server.

If activated, you can fill in these parameters by leveraging the CPQ Designer Manage File menu:

In order to have the right granularity for the tax computation of all your products, you will have to associate a tax code to every eligible product in the Catalog. The simplest way consists in defining a specific Business Property in the Catalog and associating it with every product concerned.

To see a listing of all available AvaTax System tax codes, please click the following URL: http://taxcode.avatax.avalara.com

In the quote spreadsheet, two columns are required for the call to AvaTax: one to store the tax amount and one to store the product tax code from the Catalog.

They have to be defined as follows in the Quote Designer: In the Quote Designer:

1. Go to Spreadsheet Builder > Grid > Columns.
2. Define the two following columns:
   
   
   • Map the Avalara Tax Code on the corresponding attributes of the Catalog (using Xpath for instance). This column might be hidden if required.
     • Define the Avalara Tax column as Computed/Internal.
3. Save the model and clear the model cache.

CALL TO AVATAX

Calling AvaTax from the Quote to calculate taxes can be done by leveraging triggers or on-demand actions. The corresponding actions have to be setup in the Quote Designer and could apply at the Quote and/or at the Quote line level.

In the Quote Designer:

1. Go to Spreadsheet Spreadsheet Builder > Actions.
2. For an action at the line level, go in the onDemand Line Actions section and create a new action with the following characteristics:
   • Name: Calculate tax
   • Type: Predefined > AvalaraTax
   • Activation Conditions: Single on CT7 lines
   • Help Message: Calculate Tax
   • Read-only mode: Yes
   • Access rights: open

     By opening the line action box on a specific quote line, and by clicking on “Calculate Tax”, the call to AvaTax is made for the product on the quote line and the resulting tax amount, if any, is displayed in the Avalara Tax column.

3. For an action at the grid level, go in the onDemand Grid Actions section and create a new action with the following characteristics:
   • Name: CalculateAllTaxes
     • Type: Predefined > AvalaraTaxAll
     • Title: Calculate All Taxes
     • Help message: Calculate taxes for all the products
     • Read-only mode: Yes
     • Access Rights: open

       By clicking on the “Calculate All Taxes” button on the Quote interface, a call to AvaTax is

       made for all the products contained in the quote and the resulting tax amount, if any, is displayed in the Avalara Tax column.

4. For a trigger in the quote, go in the Automated Action section and create a new trigger with the following characteristics:
   • Triggers: AvalaraTaxTrigger
     • Name: AvalaraTaxCalculation
     • Type: AvalaraTax

       You can then trigger this action on a change of price or quantity on a product line for instance and make a new call to AvaTax every time to get the tax computed again.

       Note: In case where your quote contains a large number of products, computing all the taxes with an on demand grid action or computing the quote again via a trigger could be time consuming.

ADDRESS VALIDATION

CPQ provides, as a complement of the Avalara Connector, an action based on a Java class allowing the end-user to validate the addresses contained in the mapping file. This action can be associated with a button to integrate where relevant in the quote model.

Once defined, a click on the button will request the Avalara Address Validation service for all the addresses in the AvalaraMapping.xml file and return a message.

AVATAX AVAILABILITY

CPQ provides, as a complement of the Avalara Connector, an action based on a Java class allowing the end-user to test the connection with AvaTax. This action can be associated with a button to integrate where relevant in the quote model.

Once defined, a click on the button will request Avalara and return a message giving the status of the connection.

When making calls to AvaTax at runtime, CPQ must provide the required input parameters for the request to be successful. These input parameters are retrieved by CPQ - possibly from different sources such as the Quote, a CRM, etc. – and passed in the request for tax calculation.

MAPPING FILE

The definition of each parameter of the request is done in a dedicated file on the CPQ

server: AvalaraMapping.xml. If activated, you have the ability to view the file by leveraging the CPQ Designer Manage File menu.

Here is an example of a standard mapping file:

MAPPING STRUCTURE

Structure of the AvalaraMapping.xml file:

The file is divided in 5 sections:

• The global <AvalaraMapping> tag encapsulates all the file structure The <Settings> section contains configuration parameters for CPQ
• The <Global> section contains parameters valid for all quotes of the specific instance of Avalara associated with CPQ
• The <Line> section contains parameters specific to each product, and thus to retrieved from each

  quote line

• The <Addresses> section is used to define the origin and destination addresses required for the tax calculation. Each address is encapsulated in an <Address> tag.

Each section contains a set of <fieldMapping>, each one defining the mapping between a parameter required by AvaTax and a CPQ element. Each <fieldMapping> is composed of:

• A field attribute corresponding to the name of the AvaTax parameter
• A cpqType corresponding to the type of CPQ element to map on the AvaTax field. It could be:
  • Constant: take cpqExpr as is
  • CartColumn: find the value in the column identified by cpqExpr
  • CartTotal: find the value in the total cell identified by cpqExpr
  • CartField: find the value in cart fields
  • CartAttribute: find the value in cart attributes
• A cpqExpr defining the expression or the reference to the CPQ element providing the value to map on the AvaTax field
• Optionally a defaultValue, if no cpqExpr can be provided

MAPPING CONTENT

Definition of the AvaTax fields in the AvalaraMapping.xml file:

• Settings
  • LineTypes: types of CPQ quote lines on which the taxes have to be calculated
  • LogMessages: Activate or not the traces of the requests between CPQ and Avalara
• Global
  • CustomerCode: ID to flag the customer as exempted
  • ExemptionNo: number used for product exempted of tax
  • DocCode: invoice number or sales order of the transaction (quote ID)
  • CompanyCode: ID of the company in Avalara
    • DocType: The DocType field drives whether or not the transaction is recorded to the AvaTax admin console and the type of transaction being recorded
• Line
  • Amount: total price of the product in the quote
  • ResultColumn: quote column where to store the result of the request
  • Quantity: quantity of the product in the quote
  • ProductName: product description
  • TaxCode: code used to trigger taxability rules specific to the product
  • ItemCode: item identifier or SKU
  • DestinationAddressCode: code of the destination address in the addresses list
  • OriginAddressCode: code of the origin address in the addresses list
• Address
  • AddressCode: code of the address necessary to associate an address to the destination/origin address in the “Line” section
  • Line1: first part of the address
  • Line2: second part of the address
  • Line3: third part of the address
  • City: address city
  • Region: address region
  • PostalCode: address postal code
  • Country: address country