Vertex Interface

Purpose: The Vertex Interface provides a bridge between Order Administration and the Vertex Sales Tax system to calculate the tax information on your orders at strategic points, such as:

order entry
order maintenance
pick slip preparation
billing

Order Administration communicates with Vertex files to determine the appropriate tax rate at each stage of the order's life cycle. Vertex determines the appropriate tax rate based on the “ship-from” and “ship-to” addresses on the order.

The Vertex Sales Tax system stores the tax rates for each taxing jurisdiction in the United States and Canada, and provides the necessary reporting for each jurisdiction in which you sell or operate.

If you use the Vertex interface, you don't need to keep current with the tax rates and reporting requirements of each taxing jurisdiction, and you no longer have to maintain these rates on Order Administration. Also, the system does not consider any item tax exemptions set up through Working with Item Tax Exemptions (WITX) or Working with GST Tax Exemption Status (MGTX). Instead, you should use Vertex to set up any tax exemptions for items.

Note:

You cannot use both Vertex and tax-inclusive pricing (VAT) in the same company. See Tax Included in Price (E70) for more information on VAT.

Compatibility:

Order Management System version 19.2 or later, or Order Administration, is compatible with Vertex Indirect Tax O Series® On Demand 9.0, but continues to support integration with 7.0 and 8.0 using 7.0 messages.
Order Management System version 15.1 or later, or Order Administration, is compatible with Vertex Indirect Tax O Series® On Demand 7.0 and 8.0. The 7.0 messages are used for both releases.
Support for Vertex Indirect Tax O Series® On Demand 7.0 and 8.0 using 7.0 messages ends in September 2021.

For more information: See:

Vertex Setup for information on setting up Order Administration to support communication with Vertex. Also, see your Vertex documentation for detailed information on setup requirements within Vertex.
Vertex Troubleshooting

In this topic:

Tax Calculation Processing Overview

Overview: The Vertex Interface passes order and tax information between Order Administration and Vertex at various points in the order cycle (from order entry to billing).

Vertex evaluates and calculates the tax amount on the order at each phase and updates transactions appropriately.

Communication between Order Administration and Vertex: When Order Administration needs tax information during order entry or maintenance, pick slip preparation, or billing, it sends a tax request message to Vertex using web services. The TAX_INT integration layer job defines the wsdl (Web Services Definition Language) file that controls the integration.

For troubleshooting purposes, Order Administration writes the tax request message to the Trace Log, masking the vertex user ID and password passed in the request. Additional processing is logged to the Application Log.

For more information: See Vertex Setup for more information on configuring the integration.

What is taxed? Based on its current data on tax rules for the shipping address on the order and the additional rules that you define for customer or item exceptions, Vertex indicates the tax amounts for merchandise, freight (order-level or line-level), handling charges, duty, shipper-item charges, and additional freight.

Tax Overrides, Customer Exemptions, and Item or Class Exceptions

Tax override: You can set the Tax override flag in the Order Detail table to Y when you create an order through the generic order API. If this flag is set to Y, Vertex does not calculate the tax amount for the item at any point in the order cycle and just uses the specified tax override amount; however, if there are any line-level freight, handling, or gift wrap charges, these charges may be subject to tax even if the order detail line has a tax override.

Similarly, you can override tax on freight through the order API by specifying a freight_tax_amount and setting the freight_tax_override to Y.

Note:

There is no way to set the Tax override flag through interactive order entry.
The system does not set the Tax override flag in the Order Detail table unless there is a tax amount specified in the inbound order message. As a result, you cannot use this setting to create an order line with no tax amount in interactive order entry. The only way to exempt an order line from tax is to set up an item or product class exception in Vertex.

For more information: See the Send Tax to Tax Interface as Quote Not Invoice (L11) system control value for a discussion on how the system sends different request types to Vertex based on the setting of this system control value and whether the tax is overridden.

Customer tax exemptions: If a customer is flagged as tax exempt in Order Administration and has a tax identification number, the merchandise and charges on the customer’s orders are not taxable. Order Administration passes the exemption number to Vertex. Although Order Administration does not pass the customer’s tax exempt expiration date, order entry does not let you create an order flagged as tax-exempt if the customer’s expiration date has passed.

Item or item class exceptions: When you use Vertex, you need to set up item and product class exceptions in Vertex rather than in Order Administration. For example, if you have two item classes that are not normally taxable, you can map these item classes to product classes in Vertex. See Creating the Product Class under Vertex Setup for more information on mapping this information.

Note:

Even if an item on an order is not subject to tax, Vertex still calculates tax for any freight, handling charges, and gift wrap charges if the order is otherwise subject to tax.

Vertex Troubleshooting

Purpose: Troubleshooting information includes:

Error in order entry: The message Error calling Tax Interface, check configuration in order entry indicates that one or more of the required files were not found. See Configuration Files for more information.

Processing Errors

Troubleshooting for the integration between Order Administration and Vertex begins with checking the TRACE.log and CWDirect.log files.

The TRACE.log file is typically located under /domain/conf/OMSFiles/Logs/TRACE/ on your application server, where domain is the WebLogic domain directory for Order Administration.
The CWDirect.log file is typically located under /domain/log/CWDirect.log on your application server, where domain is the WebLogic domain directory for Order Administration.

Note:

In addition to the errors written to log files, you will also see an error message in order entry if the extended order line price is over a million: Error occured on CALL to program Cwwebservice. Vertex does not support tax calculation for order line values that high.

Error in TRACE.log File	Explanation	How to Correct:
Initial Configuration Issues
ERROR TRACE - Class not found: ERROR TRACE - TAX_INT web service error: - null	A required class was not installed during the initial installation process.	Contact your Order Administration representative.
ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: User login failed: invalid_user. ; nested exception is: User login failed: invalid_user.	Possible causes: An incorrect user ID and password were entered as the `UserName` and `Password` in the Vertex User ID and Password, or The user ID specified in the Vertex User ID and Password was not created correctly in Vertex.	Check the contents of the Vertex User ID and Password and confirm that the user ID and password exist in Vertex and have authority to the correct partition in Vertex. See Set up Data within Vertex Vertex Setup and your Vertex documentation for more information. After you change the user ID and password in the Vertex User ID and Password, you need to stop and restart Order Administration. See Restarting Order Administration for more information.
ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: SAX processing failed on input stream SAX processing failed when attempting to create new element. (parent element=com.vertexinc.tps.xml.calc.parsegenerate.builder.ParticipantData, new element=null, local element name=PhysicalOrigin	No physical origin is being passed. The physical origin is the address of the warehouse for the order detail line. Possible causes: The Default Values by Company XML File was not set up correctly Warehouse list setup in Order Administration is not correct	Default Values by Company XML File: Confirm that the file exists for the company, contains valid data, and is in valid XML format. See Working with Warehouse Lists (WWHL) for information on setting up warehouse lists in Order Administration.
AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: SAX processing failed on input stream Non-fatal error detected during SAX parsing. Verify document against schema or contact document supplier. (URI=null, line number=30, error=cvc-datatype-valid.1.2.1: '' is not a valid value for 'integer'.)	The Default Warehouse (A04) is not listed in the Warehouses XML File .	Warehouses XML File: Confirm that the Default Warehouse (A04) is included in this file.
Tax Calculation Failing After Initial Setup
ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: ; nested exception is: java.net.ConnectException: Connection refused: connect; nested exception is: java.net.ConnectException: Connection refused: connect	Order Administration can no longer reach Vertex.	Contact your Order Administration representative.
ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: An error occured during CalcEngine.calculateTax. This may be an incorrect use of the calculation engine. Please contact your software vendor. Error trying to calculate tax. Cannot find tax areas. Please verify that the address or tax area id provided for the location is correct and retry.	The postal code passed in the tax request message from Order Administration is incorrect, or is associated with a city that does not exist in Vertex. To confirm, log onto Vertex and advance to the Tax Area Lookup Tool, then search for the shipping address that is causing the error. A message such as the following indicates that the postal code is incorrect: `No tax areas were found during the lookup. The address fields are inconsistent for the specified asOfDate. (Street Information=24 PRIME PKWY, Postal Code=01701, City=NATICK, Sub Division=null, Main Division=MA, Country=USA, As Of Date=20060627)`	Correct the postal code information in Order Administration.
ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: ; nested exception is: java.net.SocketException: No buffer space available (maximum connections reached?): connect	The Order Administration server is out of memory.	Reboot the Order Administration server.
ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: (404)Not Found; nested exception is: (404)Not Found	The URL specified for Vertex in the Vertex URL property is incorrect.	Correct the URL in the Vertex URL property. Stop and restart Order Administration. See Restarting Order Administration for more information.
Miscellaneous Log Messages
WARN TRACE - WARNING: Responses for DISTRIBUTE not found in configuration xml.	The log includes this message when Order Administration requests tax information for an order that includes a tax override.	No need to correct; message is informational only.
TRACE - message: com.sun.xml.ws.fault.ServerSOAPFaultException: Client received SOAP Fault from server: An unit based tax rule cannot be applied to a line item with a quantitiy of zero. Please ensure that the quantity is not zero and retry. Please see the server log to find more detail regarding exact cause of the failure.	Certain states, such as Tennessee, require a quantity for tax calculation, and this error occurs when the quotation request includes a zero quantity for freight or additional freight charges.	Add a new rule in Vertex to change the quantity to 1 for the related product classes.

Tax Calculation Rules

Situation	Explanation
New settings in Vertex apply when you use the Vertex Transaction Tester, but not when Order Administration requests tax information	If you have Vertex configured to cache information for improved performance, it might be retrieving tax rules from cached information when Order Administration requests tax information. Caching does not apply when you use the Transaction Tester. Consult your Vertex documentation for more information on configuring caching.
An item on an order is not taxable based on its item or product class settings in Vertex, or on the Tax override flag for the order line; but there is still tax on the order	Even if an item on an order is not taxable, freight, handling, gift wrap, additional freight, and duty can still be subject to tax.
You receive an order that includes an item with a tax override through the generic order interface, but the order line is still taxed	Even if the `tax_override` flag is set to Y in the inbound order message, Order Administration does not apply a tax override unless the inbound order message also specifies a tax amount greater than zero for the order line.
You make a change to the Vertex wsdl (Web Service Definition Language) File , but the changes do not take effect	Before your changes take effect, you need to restart Order Administration. See Restarting Order Administration for more information.
You change the user ID and password in the Vertex User ID and Password, but the changes do not take effect	Before your changes take effect, you need to restart Order Administration. See Restarting Order Administration for more information.