Integrating Order Management with Third-Party Taxation Applications

This chapter describes how to set up and use Taxware applications. It contains the following topics:

About Third-Party Taxation Applications

Taxes are calculated on quotes as part of the eSales - Complete Checkout Process workflow. The Calculate Taxes step calls the Tax Calculator business service, which uses the Taxware Adapter Service business service to make a call to Taxware. The calculated sales tax from Taxware is copied to the quote. When the quote is turned into an order, the tax information is copied to the order.

Note: The preconfigured integration allows tax calculations for the many countries supported by Taxware. For the latest list of supported countries, see www.taxware.com.

Taxware Applications

Taxware International is a third-party service used to calculate the sales tax on orders. Siebel eSales is designed to work with the following Taxware modules:

Sales/Use. This module calculates sales and use taxes on purchases made in the United States and Canada. You can configure Sales/Use for product-specific taxation, using the Taxware Sales/Use Toolkit to map the product’s part number in the Siebel Business Application to its Tax Code in Sales/Use.
WORLDTAX. This module calculates sales and use taxes on purchases made outside the United States and Canada. You can configure WORLDTAX for product-specific taxation, using the Taxware WORLDTAX Toolkit to map the product’s part number in the Siebel Business Application to its Commodity/Service Code in WORLDTAX.
STEP. This module enables sales tax exemptions and works in conjunction with the Sales/Use module. A Siebel eSales customer is exempt from sales tax if the Siebel account with which the customer is associated has a tax certificate lodged in the STEP module. You implement this feature by entering the Siebel account ID (row ID) in the STEP Customer ID field on the STEP certificate entry form.
Universal Tax Link (UTL). UTL integrates external applications with the Sales/Use and WORLDTAX modules through a common gateway.
VERAZIP. Used for address verification, this module matches state, ZIP Code, city, and county information to make sure that an address is correct and complete, so that the Sales/Use Tax Application can locate the correct taxing jurisdiction.

For more information, see your Taxware documentation.

Note: A product’s part number can be found in the Products screen of your Siebel Business Application. You find the row ID of an account by clicking the menu button and selecting About Record with the account selected in the Accounts screen.

Installing Taxware Applications on Windows

Siebel Business Applications support the use of Taxware software on the Windows NT and Windows 2000 operating systems.

The tasks for installing Taxware applications on Windows are as follows:

Installing Sales/Use on Windows
Installing STEP on Windows
Installing UTL on Windows
Installing WORLDTAX on Windows
Setting up the Windows environment

Note: The drive on which Taxware applications are installed must have at least 1GB of free disk space. Over time, the sizes of Taxware applications increase as log files and tax certificates are generated.

For information on installing Taxware applications, see the Taxware documentation. For information on which versions of Taxware are supported by Siebel Business Applications, see Siebel System Requirements and Supported Platforms on Oracle Technology Network.

Note: For Siebel CRM product releases 8.1.1.9 and later and for 8.2.2.2 and later, system requirements and supported platform certifications are available from the Certification tab on My Oracle Support. For details about the Certification application see 1492194.1 (Article ID) on My Oracle Support.

Setting Up Taxware Applications on Windows

After installation, you must do certain tasks, including setting an administrator user name and password, checking environment variables, loading files, and putting your company information into the application.

The tasks for setting up Taxware applications you installed on Windows are as follows:

Setting Up Sales/Use on Windows
Setting Up STEP on Windows
Setting Up WORLDTAX on Windows

For information on setting up Taxware applications, see your Taxware documentation.

Installing and Setting Up Taxware Applications on UNIX

Siebel Business Applications support the use of Taxware software on Oracle Solaris and AIX operating systems.

The tasks for installing and setting up Taxware applications on UNIX are as follows:

Installing Taxware Applications on UNIX
Setting Up Sales/Use on UNIX
Setting Up WORLDTAX on UNIX

Note: The drive on which Taxware applications are installed must have at least 1GB of free disk space. Over time, the sizes of Taxware applications increase as log files and tax certificates are generated.

After installation, you must do certain tasks, including setting an administrator user name and password, checking environment variables, loading files, and putting your company information into the application.

For information on installing and setting up Taxware applications, see the Taxware documentation. For information on which versions of Taxware are supported by Siebel Business Applications, see Siebel System Requirements and Supported Platforms on Oracle Technology Network.

Note: For Siebel CRM product releases 8.1.1.9 and later and for 8.2.2.2 and later, system requirements and supported platform certifications are available from the Certification tab on My Oracle Support. For details about the Certification application see 1492194.1 (Article ID) on My Oracle Support.

Enabling Tax Calculation

To use Taxware applications with Siebel eSales, you must set certain parameters for the eSales Object Manager component of the Siebel Server.

This topic contains the following subtopics:

Enabling Tax Calculation with the Sales/Use Tax System

To use the Sales/Use Tax System with Siebel eSales, you need to have company information defined in the Sales/Use Tax System Toolkit and on the Siebel Server.

To enable tax calculation with the Sales/Use Tax System

In the Sales/Use Tax System Toolkit, define your Company ID and Company Location, for example SIEBEL and SAN MATEO.
In your Siebel employee application, navigate to Administration - Server Configuration screen, Servers, Components, and then Parameters view.
In the Components list, select eSales Object Manager.

In the Component Parameters list, set values for the eSales Object Manager parameters listed in the table that follows.

Parameter	Value
Company ID for Sales Tax	Your company’s sales tax ID
Company Location for Sales Tax	Your company’s sales tax location
Enable Sales Tax	TRUE
Sales Tax Type	Taxware

Enabling Tax Calculation with WORLDTAX

To use the WORLDTAX application with Siebel eSales, you need to have company information defined in the WORLDTAX Toolkit and on the Siebel Server.

To enable tax calculation with WORLDTAX

In the WORLDTAX Toolkit, define your Company ID and Business Location, for example SIEBEL_FR and FR (France).
In your Siebel employee application, navigate to Administration - Server Configuration screen, Servers, Components, and then Parameters view.
In the Components list, select eSales Object Manager.

In the Component Parameters list, set values for the eSales Object Manager parameters listed in the table that follows.

Parameter	Value
Company ID for Sales Tax	Your company’s sales tax ID
Company Location for Sales Tax	Your company’s sales tax location
Enable Sales Tax	TRUE
Sales Tax Type	Taxware

In Siebel Tools, modify the user properties of the Tax - Configuration (Taxware) integration object, shown in the following table.

Integration Object User Property	Value
SHIPFROMCOUNTRY	ISO country code of the ship-from country (for example, FR for France)
WorldTaxInstalled	Y

SHIPFROMCOUNTRY can also be passed dynamically by modifying the Tax Integration (Siebel Quote Output) integration object and the data map to the Tax Integration (Taxware Input) integration object.

Taxing Customizable Products

Tax calculation is more complicated for customizable products because not all product components may need to be taxed. By default, for tax calculation, Siebel eSales submits the price of the product that is rolled up from its components. This means that if some of the component items do not need to be taxed, then the tax calculation is inaccurate.

You have the option of calculating tax at the component level for any customizable product. For information about setting up taxation at the component level, see Siebel Product Administration Guide.

Taxware Integration with Siebel eSales

Integrating Siebel eSales with third-party taxation applications involves two business services:

Tax Calculator. See Tax Calculator Business Service.
Taxware Adapter Service. See Taxware Adapter Business Service.

Tax Calculator Business Service

The Tax Calculator business service controls the process shown in the following.

Siebel EAI passes data from a quote record and the method name to a Siebel output integration object.
The Siebel Data Transformation Engine maps the Siebel output integration object to a Taxware input integration object.
The Siebel EAI XML Converter converts the Taxware input integration object into XML, using the CC XML Converter Business Service, and passes the XML data and method name to the Taxware Adapter Service.
The Taxware Adapter Service business service processes the data and uses Siebel eScript to call the Taxware API.
The Taxware Adapter Service gets the calculated sales tax from Taxware using the Taxware API.
The Taxware Adapter Service formats the sales tax data into an XML string.
The Siebel EAI XML Converter converts the XML into a Taxware output integration object.
The Siebel Data Transformation Engine maps the Taxware output integration object to a Siebel input integration object.
Siebel EAI updates the quote record with the calculated sales tax.

The Tax Calculator business service has one method, CalculateTax, with the following input arguments:

Siebel to Vendor Map Name
Vendor to Siebel Map Name

The Tax Calculator business service user properties are used to set the values given in the following table.

Table Tax Calculator Business Service User Properties

Business Service User Property	Value
Taxware:Adapter Business Service	Taxware Adapter Service
Taxware:Configuration Object	Tax - Configuration (Taxware)
Taxware:Input IntObject Name	Tax Integration (Taxware Input)
Taxware:Output IntObject Name	Tax Integration (Taxware Output)

For more information on business services, see Using Siebel Tools.

Integration Objects

Integration objects pass static or dynamic values to the business service. The architecture is modular in that you can create and use different integration objects for the same core business service. For example, while the preconfigured integration supports the Quote business component, you can create integration objects to calculate taxes directly on the Order business component.

The Tax Calculator business service uses the following integration objects:

Tax - Configuration (Taxware). Its user properties are shown in the following table.

Table Tax - Configuration (Taxware) User Properties

Integration Object User Property	Value	Comments
AUDFILEIND	2	Audit File Indicator: 1: Audit File/Suspense File 2: No Record stored on file 3: Suspense File 4: Audit File
EXEMPTUSEFLAG	Y	Exemption Use Flag: Y: Call STEP, use default record. L: Call STEP, do not use default record. P: Call STEP, search by product code. D: Call STEP, search by reason code and accept default customer. N: Do not call STEP.
InputIntObjectName	Tax Integration (Taxware Input)	None
OutputIntObjectName	Tax Integration (Taxware Output)	None
SHIPFROMCOUNTRY	US	None
SalesUseInstalled	Y	None
VendorDll	taxcommono	Name of the shared library.
WorldTaxInstalled	N	None

Tax Integration (Siebel Quote). Its integration components are shown in the following table.

Table Tax Integration(Siebel QuoteIntegration Components)

Integration Component	Fields
Quote	Account Id
	Currency Code
	Current Quote Ship To City
	Current Quote Ship To Country
	Current Quote Ship To Postal Code
	Current Quote Ship To State
	EAI Error Message
	Quote Number
	Tax Amount
Quote Item	Extended Line Total
	Extended Quantity
	Line Number
	Line Total
	Part Number
	Quantity
	Row Id
	Sales Product Flag
	Sales Service Flag
	Tax Amount
	Tax Subcomponent Flag
	Taxable

Tax Integration (Taxware Input). Its integration components are shown in the following table.

Table Tax Integration(Taxware Input)Integration Components

Integration Component	Fields That Pass Data from Siebel
Invoice	Currency Code
	Customer Id
	Document Number
	Invoice Number
	Ship To City
	Ship To Country
	Ship To Postal Code
	Ship To State
Invoice Item	Line Number
	Line Total
	Part Number
	Quantity
	Sales Product Flag
	Sales Service Flag
	Ship to City
	Ship to Country
	Ship to Postal Code
	Ship to State

See your Taxware documentation for more fields that can be passed. For information on how to pass more fields to Taxware, see Passing Data from Other Fields in the Siebel Database.

Tax Integration (Taxware Output). Its integration components are shown in the following table.

Table Tax Integration (Taxware Output) Integration Components

Integration Component	Fields That Pass Data from Taxware
Invoice	City Tax Amount County Tax Amount Error Message Federal Tax Amount Invoice Number Secondary City Tax Amount Secondary County Tax Amount Secondary State Tax Amount State Tax Amount
Invoice Item	City Basis Amount	City Completion Code	City Tax Amount
	City Tax Rate	County Basis Amount	County Completion Code
	County Tax Amount	County Tax Rate	Federal Basis Amount
	Federal Completion Code	Federal Tax Amount	Federal Tax Rate
	General Completion Code	General Completion Code Desc	Line Number
	Secondary City Basis Amount	Secondary City Completion Code	Secondary City Tax Amount
	Secondary City Tax Rate	Secondary County Basis Amount	Secondary County Completion Code
	Secondary County Tax Amount	Secondary County Tax Rate	Secondary State Basis Amount
	Secondary State Completion Code	Secondary State Tax Amount	Secondary State Tax Rate
	State Basis Amount	State Completion Code	State Tax Amount
	State Tax Rate

See your Taxware documentation for more fields that can be passed.

For more information on integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration and Using Siebel Tools.

Data Maps

Data maps are used to map fields in one integration object to another integration object. You can view data maps by navigating to the Administration - Integration screen, and then the Data Maps view.

The data maps used in tax calculation, shown in the following table are specified in the call to the Tax Calculator business service.

Table Tax Calculation Data Maps

Name	Source Object Name	Target Object Name
TaxCalculation_QuoteToTaxware	Tax Integration (Siebel Quote)	Tax Integration (Taxware Input)
TaxCalculation_TaxwareToQuote	Tax Integration (Taxware Output)	Tax Integration (Siebel Quote)

For more information on modifying integration objects and data maps, see Integration Platform Technologies: Siebel Enterprise Application Integration and Using Siebel Tools.

Taxware Adapter Business Service

The Taxware Adapter Service business service:

Receives input from the Tax Calculator business service in XML format.
Passes the following information to Taxware:
- Static information from the Tax - Configuration (Taxware) integration object
- Dynamic information from the Tax Integration (Taxware Input) integration object
Receives information back from Taxware.
Passes XML data back to the Tax Calculator business service.

The Taxware Adapter Service consists of the following methods:

CalculateTax. This is the main method for calculating the tax. It converts the input XML string to a property set and calls the Taxware software to get the tax information as a property set. It then converts the tax information to an XML string as an output.
Initialize. This method uses the input property set to initialize the variables for the business service.
OpenClose. This method opens and closes files used by Taxware to calculate taxes.

Audit File

Taxware uses an Audit File to store transactional information for tax reporting purposes. The Audit File for Sales/Use is a text file that you can edit. There is a special editor for the WORLDTAX Audit File that marks transactions that have been altered.

When calculating taxes in Siebel eSales, set the audit file indicator (AUDFILEIND) to 2 (No Record) because the customer has not yet confirmed the order.

To write to the audit file, a separate call to Taxware must be made from the order. This setup requires creating Order integration objects and mappings to the Taxware integration objects.

You can set the value for AUDFILEIND by changing the value in the Tax - Configuration (Taxware) integration object user properties. For orders, you can set a separate default value in the data mapping.

Address Verification for Taxware

Completion codes are returned that indicate the status of the process running UTL if one of the following occurs:

The customer enters an improper city/state/zip combination.
In most cases the completion code appears, indicating that a jurisdiction error occurred, which means something was wrong with the zip/state combination.
The customer enters a city/state/zip combination that maps to more than one jurisdiction.
Taxware defaults to the most likely match and applies that rate for the transaction. The application generally uses the jurisdiction with the highest population, as rates for heavily populated areas are usually higher than those for areas with less population. However, the default rate used is not always the highest rate out of the possible matches.

Customizing Taxware Integration

You can customize Siebel eSales integration with Taxware. Some examples are passing more fields to Taxware, and performing tax calculations on data in other business components.

This topic contains the following subtopics:

Passing Data from Other Fields in the Siebel Database

You can add data fields to those passed to Taxware. You must add the desired field to the appropriate integration objects and map the fields from your Siebel Business Application to Taxware, and from Taxware to your Siebel Business Application.

For more information on modifying integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration. For more information on modifying scripts, see Using Siebel Tools.

To add a data field

In Siebel Tools, add the field to the appropriate integration objects.
Activate the appropriate fields in Tax Integration (Taxware Input) and Tax Integration (Taxware Output) integration objects.
In your Siebel Business Application, navigate to the Integration Administration screen, and then the Data Map Editor.
Update the data map so that the appropriate Siebel data is passed to Taxware and an appropriate result is passed back to the Siebel database.

Passing Data from Fields Not in the Siebel Database

There are three ways to pass data from fields that do not exist in the Siebel database:

Add the field to the database, add it to the necessary integration object, and then update the data map.
Set an existing business service user property in the Tax Calculator business service, or create a new one, with a static value for all transactions. These values are read when the business service is initialized.
Any data passed dynamically using the integration objects will overwrite the value in the business service user property for that particular transaction.
Set a value for an integration object field by setting the value in the data map.
You cannot set a default value for an integration object user property because the Tax Calculator business service does not look for this value at initialization.

Calling the Tax Calculator Business Service from Other Places in Siebel eSales

You can call a business service from any of the following:

Button, if the applet the button is in is of the CSSBCBase class
Workflow
Script, either Siebel eScript or Siebel VB

For information on configuring applications and calling business services, see Using Siebel Tools.

To call the Tax Calculator business service from other places in Siebel eSales

Use the GetService() method to get an instance of the business service.
Use Service_InvokeMethod() to call a method of the business service.
Use SetProperty() to pass values for the business service method arguments that need to be set.
See Tax Calculator Business Service for the arguments of the CalculateTax method of the Tax Calculator Business Service.

Calling the Tax Calculator Business Service from Other Business Components

You can call the Tax Calculator business service from other business components besides Quote, for example Order. You can use the existing Tax Integration (Taxware Input) and Tax Integration (Taxware Output) integration objects for mapping.

To call the Tax Calculator business service from an order

Choose where to call the business service (button, workflow, or script).
In Siebel Tools, create integration objects for the Order business component to pass the correct data to the business service.
In your Siebel employee application, navigate to the Administration - Integration screen, and then the Data Map Editor.
Create integration object maps for the Order integration objects and the Taxware integration objects.

Handling Unicode Conversion Errors

Taxware applications use the ASCII codepage. Fields that are passed from Siebel eSales to Taxware applications are therefore converted from Unicode UTF-16 characters to ASCII characters.

This topic contains the following subtopics:

For general information about Unicode support in Siebel Business Applications, see Siebel Global Deployment Guide.

Error Prevention During Codepage Conversion

If non-ASCII characters are entered into a required field, then an error is generated during the codepage conversion. The error is contained in the Error Message field of the integration object. The order will not be stopped by an error, but an employee will have to manually calculate the tax. It is therefore important to:

Generate guidance messages and error messages to prevent customers from entering non-ASCII characters in a required field. A list of required fields is given in the following table.
Only use lists of values that contain ASCII-compliant values.

Table Fields Required for the Taxware Integration

Taxware Field	Siebel Field	Siebel Location	Required in Sales/Use	Required in WorldTax
Company ID	Company ID	Configuration file	Yes	Yes
Ship-From Country Code	Ship From Country	Business service integration object	Yes	Yes
Destination/Ship-To Country Code	Ship To Country	Database	Yes	Yes
POO Country Code	From Taxware	Business service integration object	Yes	Yes
POA Country Code	From Taxware (Defaulted to the setting in the Taxware Toolkit.)	Business service integration object	Yes	Yes
Line Item Amount	Line Total	Database	Yes	Yes
State Code	Ship To State	Database	Yes	No
Zip Code	Ship To Postal Code	Database	Yes	No
Document Number	Quote #	Database	No	Yes
Tax Point	Set in Adapter business service	Set in Adapter business service	No	Yes
Transaction Type	Set in Adapter business service (value of 1)	Set in Adapter business service (value of 1)	No	Yes
Seller Registration	From Taxware	Set in the Taxware Toolkit. You can pass dynamic data by configuration.	No	Yes
WT Code	Siebel Sales Product Flag (set to 01) or Siebel Service Product Flag (set to 23)	Siebel Sales Product Flag (set to 01) or Siebel Service Product Flag (set to 23)	No	Yes
Commodity Code	Part Number	Database	No	Yes
Primary Currency Code	Currency Code	Database	No	Yes

Defining Required Fields in Codepage Conversion

You can define which fields that are passed to Taxware are required and whether a field is required for WorldTax, Sales/Use, or both applications.

To define required fields in codepage conversion

In Siebel Tools, from the View menu, select Options.
In the Development Tools Options dialog box, select Object Explorer.
Move Integration Object to the far pane of the dialog box and click OK.
Select the integration object Tax Integration (Taxware Input).
Select Integration Component Field from the Object Explorer.
To make a field required, check the External Required column.
To make a field required for:
- Both WorldTax and Sales/User, leave the External DataType as String.
- WorldTax only, change the External DataType to StringWT.
- Sales/User only, change the External DataType to StringSU.

Configuring Error Messages in Codepage Conversion

You can perform the following configurations related to codepage errors:

You can configure the eSales - Complete Checkout Process workflow so that the order process stops when a codepage error is returned by Taxware. The default behavior is to allow the order process to continue.
You can configure the error messages displayed in the Quote Summary and Order Confirmation views of your employee application.
You can change the error messages that are displayed to customers on the Quote Form applet - Summary (eSales) applet and Order Form Applet - Confirmation (eSales) applet of your Siebel eSales Web site.

To configure error messages in codepage conversion

In Siebel Tools, select either the Quote Form - Summary (eSales) applet or Order Form Applet - Confirmation (eSales) applet.
Select Applet User Prop in the Object Explorer.
Replace the EAI Error Message text with the text of your choice in the user property that has the value LabelTaxNotCalculated.