SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and...

42
SoftLink 2.2 for PeopleTools 8.4 and 8.5 Vertex ® Sales Tax Q Series ® 6.0 Supplement to the C Programmer's Guide August 2015

Transcript of SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and...

Page 1: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink 2.2 for PeopleTools 8.4 and 8.5

Vertex® Sales Tax Q Series® 6.0

Supplement to the C Programmer's Guide

August 2015

Page 2: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

Copyright and legal notices

Copyright © 2015 Vertex Global Tax Solutions Ireland Holdings. All rights reserved.

This documentation may not be reproduced, displayed, distributed, modified, posted, republished, or transmitted in any form or by any means, without the prior written consent of Vertex Global Tax Solutions Ireland Holdings or its affiliates (collectively, “Vertex”), except as otherwise specified in a valid, current Vertex license agreement or allowed by law.

Disclaimers

The information contained in this documentation is designed to help users in regard to the subject matter covered. Some of it may be based upon interpretations of federal, state, foreign and other tax laws and regulations. Each entity is responsible for making its own determination of how such laws and regulations apply to its own circumstances and for evaluating the capabilities of, and all data and results generated by, any product that is described in this documentation. Vertex is not engaged in providing legal, tax or accounting advice or services and the information contained in this documentation or in any product cannot replace the advice of competent legal counsel. Further, the information in this documentation is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Trademarks and Service Marks

The trademarks, logos and service marks ("marks") displayed in this documentation are the property of Vertex or other third parties. Users are not permitted to use these marks without the prior written consent of Vertex or the third party that may own the mark.

Third Party Products

Copies of the licenses for some third-party products included with a Vertex product may be found in or with the installation materials for that product.

Page 3: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

August 2015 Page 3

Contents

Preface ............................................................................................................. 5 Contacting Vertex ...................................................................................................................... 5

Technical questions ............................................................................................................. 5 Products and services .......................................................................................................... 6

About Sales Tax Q Series ........................................................................................................... 9 Finding the information you need .......................................................................................... 11 About this supplement ............................................................................................................ 12

Scope ................................................................................................................................. 13 Procedure formatting ........................................................................................................ 13 Data entry fields and command buttons .......................................................................... 13 Keys ................................................................................................................................... 13 Menu selections ................................................................................................................ 13 Information you type ........................................................................................................ 13 Variable text ...................................................................................................................... 13 System messages ............................................................................................................... 14

References ............................................................................................................................... 14 Vertex Sales Tax Q Series library ....................................................................................... 14 Vertex Sales Tax Q Series EC library .................................................................................. 15 Vertex Sales Tax Q Series PL/SQL library ........................................................................... 15

What's new in this supplement? ............................................................................................. 16 September 2015 ................................................................................................................ 16

Chapter 1 Overview .......................................................................................... 17 About SoftLink functions ......................................................................................................... 17

What does SoftLink do? .................................................................................................... 18 PeopleSoft Architecture .................................................................................................... 18 The BI Design Time Plug-in XML file .................................................................................. 21 Sample BI Design Time Plug-in XML file ............................................................................ 22 How SoftLink interfaces with PeopleSoft .......................................................................... 23 Directory structure for STQ and SoftLink on UNIX systems .............................................. 23 Directory structure for STQ and SoftLink on Windows systems ....................................... 24

How SoftLink handles PeopleSoft billing ................................................................................. 24 GeoCode lookups .............................................................................................................. 24 Online tax calculations ...................................................................................................... 25 Batch tax calculations ........................................................................................................ 25 Other PeopleSoft applications .......................................................................................... 25

How SoftLink processes requests from PeopleSoft ................................................................ 25 VERTEX_CALCTAX .............................................................................................................. 25

Page 4: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink 2.2 for PeopleTools 8.4 and 8.5 Contents

August 2015 Page 4

VERTEX_GEOCODES .......................................................................................................... 25 SoftLink process................................................................................................................. 26 Building a request .............................................................................................................. 26 Executing the SoftLink process .......................................................................................... 26 Calculating tax or retrieving GeoCodes ............................................................................. 27 Passing data back to the PeopleSoft application .............................................................. 27 Closing STQ databases ....................................................................................................... 27

Chapter 2 Installing SoftLink .............................................................................. 28 SoftLink files ............................................................................................................................ 28

Files for UNIX platforms .................................................................................................... 28 Files for Windows platforms ............................................................................................. 29

Procedure for installing SoftLink ............................................................................................. 29 Installing SoftLink on a UNIX platform .............................................................................. 30 Installing SoftLink on a Windows platform ....................................................................... 30

Editing the Vertex Configuration file ....................................................................................... 31 UNIX platforms .................................................................................................................. 32 Windows platforms ........................................................................................................... 32 Required database entries for ISAM databases ................................................................ 34 Required database entries for relational databases ......................................................... 34 Debug, statistics, and debug log flags ............................................................................... 35 Tax specific flags ................................................................................................................ 36

Chapter 3 Troubleshooting SoftLink .................................................................. 38 Troubleshooting the PeopleSoft-to-SoftLink interface ........................................................... 38

Error indications ................................................................................................................ 38 Variable setting errors ....................................................................................................... 38 Not Able to Open the STQ databases ............................................................................... 39 Cannot Load Business Interlink Plug-in or Cannot Load Plug-in ....................................... 39 Server connection error .................................................................................................... 40

Error codes and associated messages ..................................................................................... 40 GetGeoCode ...................................................................................................................... 40 OpenDb ............................................................................................................................. 41 Close Db ............................................................................................................................. 41 CalcTax ............................................................................................................................... 42

Page 5: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

August 2015 Page 5

Preface This preface contains the following information:

• Contacting Vertex®, which includes how to contact Vertex about services and products

• About Vertex® Sales Tax Q Series® products, which includes the list of guides that Vertex provides

• About this guide, which includes its purpose, scope, audience, and procedure formatting

Contacting Vertex Use this information to ask questions, purchase products or services, or contact corporate offices.

Technical questions If you have technical questions or comments, contact Product Support (use product code 4720 for fastest response):

Phone: 800.281.1900 (Monday through Friday, 8:15 A.M. to 8:00 P.M. United States Eastern Time)

Web: https://my.vertexinc.com/

You can help Product Support resolve your issue promptly by having your Vertex product and release numbers as well as information about your platform, databases, and vendor package ready before you call.

Also, be sure you have access to the appropriate internal personnel (technical staff, database administrator, system administrator) if you need their assistance during your call.

Page 6: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface ContactingVertex

 

August2015 Page6

ProductsandservicesIf you would like information about obtaining a new license file, contact the Account Services department: 

Phone: 800.355.3500 Fax: 610.640.5892 If you would like information about purchasing Vertex products and services, contact the Sales department.   

VertexGlobalheadquartersPhone: 800.355.3500 or 610.640.4200 Fax: 610.640.5892 Web: http://www.vertexinc.com/ 

VertexEuropeanheadquartersPhone: +44 (0) 20 8622 3053 Fax: +44 (0) 20 8622 3200 

TaxReferences

Vertex offers a variety of references for tax compliance information as well as jurisdiction and postal code information. To learn more, refer to the Indirect Tax Solutions/Tax Reference section of the Web site at www.vertexinc.com/Solutions/indirect/tax‐reference.asp. 

VertexConsulting

Vertex® Consulting provides specialized knowledge and experience to help you configure your Vertex software and ensure that it's integrated correctly with your host system. We tailor the consulting service to complement your company's internal resources and skills to address your unique needs. For more information about the service options available, refer to the Solutions/Vertex Consulting section of our Web site at www.vertexinc.com/solutions/consulting/. 

Page 7: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface ContactingVertex

 

August2015 Page7

TrainingSolutions

Vertex offers regional classroom training, Web classroom training, and training at your facility. Vertex Training helps you understand not just how to use the product, but how to apply it in practical ways that benefit your company's tax compliance efforts. Vertex courses are CPE accredited and are led by Certified Technical Trainers. Customers who attend training classes typically reduce their implementation time by about 50 percent. For more information on Vertex Training Solutions, refer to the Support/Training Solutions section of our Web site at   www.vertexinc.com/training/. 

Commentsaboutthisdocumentation

If you have questions or comments about this guide or other Vertex product documentation, send an email to [email protected]. We are always eager to improve your documentation and we welcome your feedback. 

Page 8: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface ContactingVertex

 

August2015 Page8

Vertexcorporateoffices

Vertex is a privately held company with offices in these locations:   

Globalheadquarters

1041 Old Cassatt Road Berwyn, PA 19312 

USA Phone: 610.640.4200 

Toll‐free (United States only): 800.355.3500 Fax: 610.640.2761 

www.vertexinc.com/   

 

Sarasotaoffice

TaxReturnsprocessingcenter

101 Paramount Drive Suite 340 Sarasota, FL 34232 USA Phone: 866.829.8324 

40 Shuman Blvd. Suite 160 Naperville, IL 60563 USA Phone: 630.328.2600 

 

LatinAmericanheadquarters

Europeanheadquarters

Vertex Global Tax Solutions Brasil Ltda. Av. Dr. Chucri Zaidan, 940 16th floor ‐ Market Place Tower II   São Paulo ‐ SP 04583‐906 Brazil   Phone: +55 11 5095.3433 / 3442 

Vertex Global Tax Solutions, LTD 1 Furzeground Way, Stockley Park Uxbridge, UB11 1EZ   United Kingdom Phone: +44 (0)20 8622 3053 Fax:+44 (0)20 8622 3200 

 

 

Page 9: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface AboutSalesTaxQSeries

 

August2015 Page9

AboutSalesTaxQSeriesVertex® Sales Tax Q Series® (STQ) assists your company in the tax compliance process by maintaining tax rates, rules, and regulations and enabling you to enter special tax considerations for customers, products, and jurisdictions where you are registered.   

STQ simplifies the tax compliance process by: 

Interfacing with your host system (using industry standards such as C, OLE, UNIX, Windows, and client servers) 

Using an extensive tax rate database (Rate database) 

Using an extensive jurisdiction database (GeoCoder database) 

SalesTaxQSeriesThe C version of Vertex® Sales Tax Q Series® (STQ) can interface to any operating system that supports ANSI C functions, including UNIX and Windows. Windows users have the option of interfacing to STQ using OLE (Object Linking and Embedding) functions.   

STQ supports Indexed Sequential Access Method (ISAM) databases and Relational Database Management Systems (RDBMS).   

SalesTaxQSeriesECThe EC version of Vertex® Sales Tax Q Series® (STQ‐EC) calculates sales and use tax for electronic commerce transactions. 

STQ‐EC interfaces with your Internet application using both Java and Extensible Markup Language (XML). The object‐oriented STQ‐EC interface accepts data from your electronic commerce application using Java objects or XML documents and then passes the data into the calculation engine to provide the sales tax for an online customer.   

STQ‐EC is available in Java and XML versions. Both versions work with the C version and the PL/SQL version of STQ calculation engine.   

Page 10: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface AboutSalesTaxQSeries

 

August2015 Page10

SalesTaxQSeriesPL/SQLThe PL/SQL version of Vertex® Sales Tax Q Series® (STQ‐PL/SQL) runs in a networking computing architecture with STQ‐PL/SQL Tax Calculation that resides on the database server.     

Vertex supplies installation media for UNIX environments to install the Utility kit and installation media for Windows environments to install the Tax Professional kit. 

The Tax Calculation package is designed to run on an Oracle database. 

Page 11: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface Findingtheinformationyouneed

 

August2015 Page11

FindingtheinformationyouneedTo help you install your STQ software, integrate STQ with your financial host system, and use Vertex® Tax Decision Maker or Vertex® Taxability Mapping Tool user interfaces to customize STQ to your business, Vertex provides documentation. Select one of the following documents based on your needs and version of the STQ software: 

 

Forthistask Usethisdocumentation

Installing the software Install and configure STQ to communicate with databases.   

C Administrator's Guide 

EC Administrator's Guide 

PL/SQL Programmer's Guide 

PL/SQL Installation Guide for Oracle eBusiness Suite 

Building an interface Create interface between components of STQ and your host system. 

C Programmer's Guide 

PL/SQL Programmer's Guide 

EC Programmer's Guide 

Setting up taxability information  Set up the Tax Decision Maker (TDM) and Taxability Mapping 

Tool (TMT) 

Use and maintain these components   

Generate TDM reports and definitions of report codes 

User's Guide 

Tax Decision Maker Help 

Looking up GeoCodes View and verify GeoCodes, address, and tax rate information.   

Note: Lookup only displays the standard rates. It does not display tax overrides or tier tax logic. 

User's Guide 

Lookup Help 

Converting data Convert your existing Vertex® Sales Tax L Series® COBOL or RPG III TDM database records into a format that can be imported into an STQ TDM database. 

C Programmer's Guide 

Sales Tax Conversion Help 

Importing or exporting data Import or export exception information into an STQ TDM database 

C Programmer's Guide 

TDM Import‐Export Help 

Managing databases  Create, migrate, and re‐index ISAM databases 

Connect to databases 

Populate to update the Rate, GeoCoder, and TDM databases 

C Administrator's Guide 

EC Administrator's Guide 

Sales Tax Utilities Help 

Maintaining the Register database   Transfer, consolidate, export, and purge information 

Set up the Register control card 

Generate reports 

C Programmer's Guide 

EC Programmer's Guide 

Sales Tax Utilities Help 

 

Page 12: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface Aboutthissupplement

 

August2015 Page12

Forthistask Usethisdocumentation

Testing tax calculation Verify that tax can be calculated on sample invoices 

C Administrator's Guide 

EC Administrator's Guide 

Sales Tax Utilities Help 

Viewing database table changes Use the Administration Table Viewer to track changes to your database. 

C Administrator's Guide 

EC Administrator's Guide 

Sales Tax Utilities Help 

Working with SAP TransLink How TransLink integration works with SAP R/3, ECC, and Customer Relationship Management (CRM) applications to provide access to STQ programs and databases for tax calculation and GeoCode retrieval.   

SAP TransLink Supplement 

Working with SoftLink  How SoftLink integration works with PeopleSoft application to provide access to STQ programs and databases for tax calculation and GeoCode retrieval. 

SoftLink Supplement 

 

Note: The latest product documentation updates are available online on myVertex (https://my.vertexinc.com/). You can also use myVertex to access the online Knowledge Center, submit a Service Request, or visit the Message Board where you can communicate with other Vertex users about tips, tricks, and best practices. 

AboutthissupplementThe SoftLink Supplement explains how SoftLink operates with the PeopleSoft application to access the Vertex Sales Tax Q Series (STQ) programs and databases for tax calculation and GeoCode retrieval. 

This supplement applies only to SoftLink version 2.2 for PeopleTools versions 8.4 and 8.5, when used with STQ. 

Page 13: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface Aboutthissupplement

 

August2015 Page13

ScopeThe SoftLink Supplement tells you what you need to know to: 

Understand SoftLink, its components, and the flow of information between the PeopleSoft application, the tax calculation, and GeoCode retrieval functions of Vertex Sales Tax Q Series. 

Install SoftLink and interface it with your PeopleSoft application. 

Troubleshoot the PeopleSoft‐to‐SoftLink interface. 

ProcedureformattingVertex documentation follows some standard conventions in its descriptions of step‐by‐step instructions. These conventions make it easy to see what actions you must take and what you see on the screen. 

DataentryfieldsandcommandbuttonsText that you see on the screen, such as data entry fields and the names of command buttons, look like this: 

Click OK to save the data in the Address field. 

KeysThe names of keys you press look like this: 

Press F4 and Enter. 

MenuselectionsSelections you make from cascading menus look like this: 

Select File > Save. 

InformationyoutypeInformation you type looks like this: 

Type setup at the C:\ prompt. 

VariabletextVariable text you type looks like this: 

Type myfile at the C:\ prompt. 

Page 14: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface References

August2015 Page14

SystemmessagesMessages from the system look like this: 

setup

ReferencesThis section lists the references that will help you use STQ more effectively. 

VertexSalesTaxQSerieslibraryThis library includes: 

User'sGuide

This guide tells the tax professional how to use and maintain the Tax Decision Maker (TDM) and the Taxability Mapping Tool, and how to set up both tools. 

OnlineHelp

Screen‐specific online help is an integral part of your STQ system. 

Administrator'sGuide

This guide provides information for system implementors or C language programmers who must install STQ. 

CProgrammer'sGuide

This guide tells the C‐language programmer how to build the interfaces necessary to access the databases and programs. It also provides information about creating an interface between the components of STQ and your host system. 

Vertex offers integration software that allows you to access STQ for tax calculation without requiring a C language interface to the APIs. Vertex documents these integrations in these supplements to the C Programmer's Guide: 

Page 15: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface References

August2015 Page15

SoftLinkforPeopleTools8Supplement

This supplement explains how the SoftLink integration works with the PeopleSoft applications supported by PeopleTools 8 to provide access to STQ programs and databases for tax calculation and GeoCode retrieval. 

CReferenceManual

This manual provides the C‐language programmer with detailed information on the use and syntax of the GeoCoder and Sales and Use Tax API functions needed to build an interface to your host system when writing a C language interface to the APIs is required. 

VertexSalesTaxQSeriesEClibraryThis library includes: 

Administrator'sGuide

This guide provides information for programmers or system implementors who must install Sales Tax Q Series EC (STQ‐EC). 

JavaandXMLProgrammer'sGuide

This guide tells the Java or XML programmer how to build the interfaces necessary to access the databases and programs. It also provides information about creating an interface between the components of STQ‐EC and your host system. 

Vertex offers integration software that allows you to access STQ‐EC for tax calculation without requiring a Java or XML interface to the APIs. Vertex documents these integrations in the supplements to the Java and XML Programmer's Guide. 

VertexSalesTaxQSeriesPL/SQLlibraryThis library includes: 

InstallationGuide

This guide gives the PL/SQL programmer or system implementor information about the installation process and procedures for Sales Tax Q Series PL/SQL (STQ‐PL/SQL) for Oracle E‐Business Suite, version 11.5.9. 

Page 16: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Preface What'snewinthissupplement?

 

August2015 Page16

Programmer'sGuide

This guide tells the PL/SQL programmer how to build the interfaces necessary to access the databases and programs. It also provides information about creating an interface between the components of STQ‐PL/SQL and your host system. 

What'snewinthissupplement?The SoftLink supplement contains the following changes: 

September2015STQ 6.0 contains the following changes. 

Individualdistrictrates

Beginning with this release, you can apply different district rates for different tax types. STQ supports different district rates for Use, Rental, Lease, and Service transactions. 

Note: The functionality of the district overrides that are set up in the TDM will not change. If a district rate override is present, it takes precedence over rates in the database regardless of the transaction type. 

DatafilesforSTQ6.0

For STQ 6.0, the version number of the jurisdiction data files has not changed. Only the version number of the rate files has changed. The data file names are as follows: 

geomast5.vdf 

taxzip5.vdf 

seqmast6.vdf 

tmtmast6.vdf 

 

Page 17: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

 

August2015 Page17

C h a p t e r 1

OverviewThis overview briefly describes Vertex SoftLink and explains how it processes PeopleSoft client application requests for tax calculation and GeoCode retrieval. This chapter introduces you to SoftLink concepts so you understand how SoftLink functions before you install it. 

Inthischapter

About SoftLink functions ............................................................... 17 How SoftLink handles PeopleSoft billing ....................................... 24 How SoftLink processes requests from PeopleSoft ...................... 25 

 

AboutSoftLinkfunctionsSoftLink is a shared object or dynamic link library (dll) designed to simplify transactions between a PeopleSoft application and Vertex's Sales Tax Q Series products. 

The primary function of SoftLink is to take the parameters passed to it by the PeopleSoft calling application, translate them, if necessary, for processing by the appropriate Vertex tax calculation or GeoCode retrieval functions, and return the results to the PeopleSoft application. 

Note: Users have no requirement or provision to call directly any of the C language functions of the STQ or GeoCoder APIs. 

Page 18: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview AboutSoftLinkfunctions

 

August2015 Page18

WhatdoesSoftLinkdo?The SoftLink interfaces enable PeopleSoft applications to access Vertex Sales Tax Q Series (STQ) without using the Vertex Sales Tax Q Series Application Programmer's Interfaces (APIs). 

The PeopleSoft billing, order management, accounts payable, and purchasing processes use SoftLink to: 

Retrieve and assign GeoCodes to precisely identify tax jurisdiction codes. 

Retrieve and apply proper tax to sales or purchase transactions. 

SoftLink calculates tax for all possible sales tax situations. The PeopleSoft‐to‐SoftLink interface is designed to process documents one line item at a time in an interactive or batch environment. 

PeopleSoftArchitecture

BusinessInterlink

PeopleSoft includes the Business Interlink (BI), which is an integrated framework that allows PeopleSoft applications to access, update, and invoke procedures in an external system (for example, Vertex Sales Tax Q Series) in a real‐time synchronous mode. Each Business Interlink Definition represents a business transaction associated with an integration point (for example, calculating sales tax). Each Interlink Definition is associated with an Interlink plug‐in. 

Run‐timeplug‐in

The Interlink Object containing the transaction name and inputs is passed to the Business Interlink run‐time plug‐in (for example, the Softlink Interlink Plug‐In created by Vertex). For UNIX versions, the plug‐in is located on the PeopleSoft application server. For the Windows version, the plug‐in can be located on the PeopleSoft application server or a Web server. Note that when the plug‐in is on a Web server, a distributed business interlink is in use. 

The run‐time plug‐in provides the implementation of the transactions and/or data operations. It calls the external software system through its API, passing the input values from the Business Interlink Object. The run‐time plug‐in also receives output from the external system and assigns these values to the Business Interlink Object. 

Page 19: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview AboutSoftLinkfunctions

 

August2015 Page19

PeopleSoftInternetArchitecture

PeopleSoft includes the PeopleSoft Internet Architecture (PIA). With this architecture, the Web browser is the primary means by which end users access PeopleSoft applications. A Java‐enabled Web server supports browser transaction requests by sending these on to an application server. The application server is the core of the PeopleSoft Internet Architecture; it executes business logic and issues SQL commands to the PeopleSoft database server. Application developers and system administrators who need access to PeopleTools should use a Windows workstation. Application Designer and various other PeopleTools are not accessible through a browser. In this development environment you can connect directly to the database (two‐tier), or you can connect through an application server (three‐tier). 

Batchprocessing

Batch processing is done through the batch server where you have the Process Scheduler installed and configured; it is the location where many of your PeopleSoft batch programs run. 

Page 20: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview AboutSoftLinkfunctions

 

August2015 Page20

AccessingSoftLink

The call to SoftLink to perform GeoCode lookups and tax calculation is done on either the application server or process scheduler. 

Note: For more information on Business Interlink and PeopleSoft Internet Architecture, refer to People Tools PeopleBooks. 

The following figure is a conceptual view of the architecture, showing how it interfaces with SoftLink and Vertex Sales Tax Q Series. 

 

Figure 1: Accessing SoftLink 

Page 21: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview AboutSoftLinkfunctions

 

August2015 Page21

TheBIDesignTimePlug‐inXMLfilePeopleSoft Business Interlink Definitions are defined and saved in PeopleTools Application Designer through an XML design‐time plug‐in. The design‐time plug‐in can also be used to test the Business Interlink Definition by simulating the execution of the corresponding Business Interlink Objects. 

The BI Design Time Plug‐in XML file contains all the information needed to create an Interlink Definition, specifically: 

The names of all transactions and classes that are part of the Business Interlink plug‐in 

The input/output parameters of the transactions 

The members of the classes 

Note:   The pathname for the SoftLink plug‐in shared library/DLL, psbivrtx.dll, namely <URL>file://psbivrtx.dll</URL> implies that the plug‐in shared library/DLL resides in the interfacedrivers directory. If the plug‐in shared library/DLL file is in a different directory, you must provide the full pathname for the plug‐in shared library/DLL file. For UNIX versions, the PeopleSoft software translates the shared library name, psbivrtx.dll, to the appropriate library name, depending on the operating system where SoftLink is installed. For example, the translated shared library name on the Solaris platform is libpsbivrtx.so. 

Page 22: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview AboutSoftLinkfunctions

 

August2015 Page22

SampleBIDesignTimePlug‐inXMLfileThe following is a sample of the BI Design Time Plug‐in XML file: 

<?xml version="1.0" ?> <interface_driver> <general_info> <description>Vertex Interface Driver</description> <version>1.1</version> <author>Jose H</author> <lastupdate>04/19/2000</lastupdate> <updatedby>Joe C</updatedby> <comments>Vertex Interface Driver</comments> </general_info> <driver_settings> <option type="static_catalog" supported="true"/> <option type="transaction" supported="true"/> <relational_op> </relational_op> <logical_op> </logical_op> </driver_settings> <config_parameters> <URL>file://psbivrtx.dll</URL> </config_parameters> <class_catalog> <category> </category> </class_catalog> <trans_catalog> <category name="Tax Processing"><transaction name="geocode"> <input_list> <input name="postal_in" type="string" required="true"/> <input name="state_in" type="string" required="true"/> <input name="country_in" type="string" required="true"/> <!-- FUTURE FUNCTIONALIITY --><!-- <input name="city_in" type="string" required="false"/> <input name="county_in" type="string" required="false"/> <input name="stateprefix" type="string" required="false"/> <input name="countyprefix" type="string" required="false"/> <input name="cityprefix" type="string" required="false"/> <input name="zipprefix" type="string" required="false"/> <input name="citycompress" type="string" required="false"/> <input name="maxlocations" type="string" required="false"/> <input name="namelevel" type="string" required="false"/> <input name="geocode_in" type="string" required="false"/> --> </input_list> <output_list> <output name="state" type="string" default="NA"/> <output name="county" type="string" default="NA"/>

Page 23: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview AboutSoftLinkfunctions

 

August2015 Page23

<output name="city" type="string" default="NA"/> <output name="geocode" type="string" default="000000000"/> <output name="incitylimit" type="string" default="N"/> </output_list> </transaction> . . . . </category> </trans_catalog> </interface_driver>

HowSoftLinkinterfaceswithPeopleSoftSoftLink interfaces with PeopleSoft through PeopleSoft's Business Interlink architecture. SoftLink is created as a Business Interlink run‐time plug‐in, which is a shared library on UNIX platforms or a dynamic link library (DLL) on Windows platforms. The plug‐in can be located on the same server as the PeopleSoft Application Server or it can also be located on an Internet Web server (Windows version only). 

PeopleSoft provides two Interlink Objects to interact with SoftLink: 

VERTEX_CALCTAX for tax calculation. 

VERTEX_GEOCODES for jurisdiction data retrieval. 

DirectorystructureforSTQandSoftLinkonUNIXsystemsOn UNIX systems, avoid installing STQ and SoftLink in multiple directories. STQ and SoftLink files should be installed in specific directories to enable PeopleSoft to locate them at run time: 

The SoftLink plug‐in shared library must be installed in the <PS_HOME>/ bin/interfacedrivers directory. 

The STQ shared libraries should be installed in their own directory. The STQ libraries should not be installed in the <PS_HOME>/bin or <PS_HOME>/bin/interfacedrivers directory. 

The environment variable for the shared library should be modified to include the directory where STQ libraries are installed. 

In the production environment, the Application Server and the Process Scheduler Server use the information in these two directories to access SoftLink and STQ. 

Note: Refer to PeopleSoft documentation for specific information on directories for installation. 

Page 24: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview HowSoftLinkhandlesPeopleSoftbilling

 

August2015 Page24

DirectorystructureforSTQandSoftLinkonWindowssystemsFor Windows, the directory structure is as follows: 

The STQ DLLs must be placed in the <PS_HOME>\ bin\server\winx86 directory (for the Application Server and the Process Scheduler Server). 

The SoftLink plug‐in DLL, psbivrtx.dll, must be placed in the <PS_HOME>\bin\server\winx86\interfacedrivers directory. 

In the production environment, the Application Server and the Process Scheduler Server use the information in these two directories to access SoftLink and STQ. 

For two‐tier client testing, the directory structure is similar, except that server is replaced by client. The resulting structure is as follows: 

The STQ DLLs are placed in the <PS_HOME>\bin\client\winx86 directory. 

The SoftLink plug‐in DLL, psbivrtx.dll, is placed in the <PS_HOME>\bin\client\winx86\interfacedrivers directory. 

Note: Refer to PeopleSoft documentation for specific information on directories for installation. 

HowSoftLinkhandlesPeopleSoftbillingFor PeopleSoft Billing, interaction with the SoftLink plug‐in occurs in three ways: 

During GeoCode lookups 

During online tax calculations 

During batch tax calculations 

Note: PeopleSoft 8.8 users have AP/PO functionality. 

GeoCodelookupsGeoCode lookups occur when you change a ZIP Code in any address page that is linked to perform GeoCode lookups. This includes the locations page, the address override page, and most of the customer address pages. This call is controlled through the Installation Options setup flag. 

When Vertex is selected, the GeoCode lookup is triggered by any ZIP Code change. This setting does not control any tax calculations ‐‐ only GeoCode lookups. 

Page 25: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview HowSoftLinkprocessesrequestsfromPeopleSoft

 

August2015 Page25

OnlinetaxcalculationsOnline tax calculations are initiated from the Bill Summary page for bills created for Billing Business Units with Vertex selected. 

BatchtaxcalculationsBatch tax calculations are initiated from the Application Engine program BITAX000. This program is called from BIIVC000, the Preprocess/ Finalization Application Engine process, and BIIVC100, the single‐bill Proforma Application Engine process. The calls to Vertex are for bills that were created for Billing Business Units with Vertex selected. 

OtherPeopleSoftapplicationsOther PeopleSoft applications can perform GeoCode lookups and online tax calculations using SoftLink. Please refer to PeopleSoft documentation for specific information on how these other PeopleSoft applications interface with STQ. 

HowSoftLinkprocessesrequestsfromPeopleSoftThis section describes how SoftLink processes requests from the PeopleSoft application. 

PeopleSoft provides the following Interlink Objects to interact with the SoftLink plug‐in and STQ interfaces: 

VERTEX_CALCTAX Calculates tax 

Called by the PeopleSoft application for online and batch tax calculation 

VERTEX_GEOCODES Retrieves jurisdiction data 

Used by batch and online processes 

Automatically opens the STQ GeoCoder database, if it is not already open 

Closes the GeoCoder database when finished retrieving GeoCodes 

Page 26: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview HowSoftLinkprocessesrequestsfromPeopleSoft

 

August2015 Page26

SoftLinkprocessSoftLink processes requests from the PeopleSoft application through the following steps: 

Building a request 

Executing the SoftLink process 

Calculating tax or retrieving GeoCodes 

Passing data back to PeopleSoft 

Closing STQ databases 

BuildingarequestAfter the user completes the entry of a line item of sales order data, the PeopleSoft application process builds a request for a tax calculation or for GeoCodes by passing the information (parameters) that Vertex requires to calculate taxes or retrieve GeoCodes to Business Interlink. The parameters are retrieved from the order header (date and customer code); from the line item (quantity, extended amount, and product code); and from customer, material, and cost center or plant tables. 

Currently, PeopleSoft requests tax calculations for its orders, inquiries, quotations, and invoices. PeopleSoft also requests GeoCodes by providing a state and ZIP Code combination. 

ExecutingtheSoftLinkprocessTo retrieve a GeoCode, the PeopleSoft Business Interlink calls VERTEX_GEOCODES, which automatically opens the STQ GeoCoder database, if it is not already open, and closes the GeoCoder database when finished. 

To calculate tax, either online or in a batch, the PeopleSoft Business Interlink calls VERTEX_CALCTAX to perform the tax calculation. 

If SoftLink fails to respond to a PeopleSoft request, the user should use troubleshooting routines, as detailed in Troubleshooting SoftLink (see page 38) in this supplement, to resolve the problem and, if necessary, to help Vertex or PeopleSoft Customer Service identify the problem. 

Page 27: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter1.Overview HowSoftLinkprocessesrequestsfromPeopleSoft

 

August2015 Page27

CalculatingtaxorretrievingGeoCodesWhen the request is for tax calculation, the STQ tax calculation component performs taxability determination in accordance with state and local statutes, as well as any exceptions your tax department has established in the STQ Tax Decision Maker. Based on the taxability determined, STQ calculates tax, exempts the transaction, or indicates that the transaction is not taxable. 

When the request is for GeoCode retrieval, the GeoCoder component of STQ, using address information provided, retrieves one or more GeoCodes. 

PassingdatabacktothePeopleSoftapplicationSoftLink passes the results of the function calls back to the PeopleSoft Business Interlink, which retrieves specific tax rates and dollar amounts or GeoCodes, as relevant, for each jurisdiction. 

ClosingSTQdatabasesSTQ databases are closed when all transactions are compiled. 

 

Page 28: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

 

August2015 Page28

C h a p t e r 2

InstallingSoftLinkThis chapter describes the process for installing SoftLink: loading the software package from a CD‐ROM and setting up the Configuration file. 

Inthischapter

SoftLink files .................................................................................. 28 Procedure for installing SoftLink ................................................... 29 Editing the Vertex Configuration file ............................................. 31 

 

SoftLinkfilesThis section describes the files that constitute the SoftLink software package. Files are available for UNIX platforms and for Windows platforms. 

FilesforUNIXplatformsVertex delivers SoftLink files for UNIX on CD‐ROM. The following files are provided as required for your application: 

SOFTLINK.txt

This ASCII text README file contains notes and any information not available at the time of documentation printing. 

libpsbivrtx.a,libpsbivrtx.so,orlibpsbivrtx.sl

This is the SoftLink shared library that handles tax calculation and GeoCode lookups. Use libpsbivrtx.a for AIX platforms, libpsbivrtx.so for Solaris and libpsbivrtx.sl for HP platforms. 

Note: Since different versions of the shared library and configuration files are required for different database platforms, these files cannot be interchanged between platforms. 

Page 29: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter2.InstallingSoftLink ProcedureforinstallingSoftLink

 

August2015 Page29

psvtxcfg

This ASCII text file contains STQ database connection information and configuration switches for tax calculation and GeoCode lookup. The SoftLink shared library file uses data in this file to connect to the STQ databases and set static parameters. 

FilesforWindowsplatformsVertex delivers the Windows SoftLink files on CD‐ROM. The following files are provided as required by your application: 

SOFTLINK.txt

This ASCII text README file contains notes and any information not available at the time of documentation printing. 

psbivrtx.dll

This is the SoftLink dynamic link library that handles tax calculation and GeoCode lookups. 

psconfig.reg

This sub‐tree of the Windows Registry contains STQ database connection information and configuration switches for tax calculation and GeoCode lookup. The file psbivrtx.dll uses data in the psconfig.reg file to connect to the STQ databases and set static parameters. 

ProcedureforinstallingSoftLinkBefore you install SoftLink, you must have Vertex Sales Tax Q Series installed. Procedures for installing STQ and building databases are contained in the Vertex Sales Tax Q Series Administrator's Guide. 

Note: The STQ libraries and the SoftLink shared libraries must both be installed in the directories specified by PeopleSoft. 

Page 30: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter2.InstallingSoftLink ProcedureforinstallingSoftLink

 

August2015 Page30

InstallingSoftLinkonaUNIXplatformTo install the SoftLink software on a UNIX platform, complete the following steps, using either a PeopleSoft account or a privileged account: 

1. Go to the interfacedrivers directory under the directory where the PeopleSoft libraries have been installed.   Command: cd<PS_HOME>/bin/interfacedrivers. 

2. Mount the CD‐ROM as described in your system documentation. 

3. Extract data from the media. CD‐ROM_path is the directory entry for the CD_ROM mount (example: /mnt/cdrom). OS is the operating system on which the software is being installed (example: Solaris2.6). Database is the database platform (example: Oracle8.1). Command: tar -xvf CD-ROM_path/OS/ Database/softlink.tar. 

4. Change the owner of the interfacedrivers directory to the specified owner. It should be the same as the one used by the PeopleSoft application. Command: chown -R owner directory. 

5. Change the group of the interfacedrivers directory to the specified group. It should be the same as the one used by the PeopleSoft application. Command: chown -R group directory. 

6. Change the access mode of the interfacedrivers directory to the specified permissions. Owner must have full read, write, and execute permissions. Command: chmod -R 755 directory. 

InstallingSoftLinkonaWindowsplatformSoftLink must be installed in specific directories: 

The STQ DLLs must be placed in the <PS_HOME>\bin\server\winx86 directory for the Application Server and the Process Scheduler Server. 

The SoftLink plug‐in DLL, must be placed in the <PS_HOME>\bin\server\winx86\interfacedrivers directory. 

Complete the following steps to load the SoftLink software: 

1. Load the CD‐ROM into the CD‐ROM drive. 

2. Log on as the PeopleSoft user who will run the application. 

3. Navigate to locate softlink.exe in the following path: D:\SoftLink_version\OS\database\softlink.exe 

where:   

D is your CD‐ROM drive 

SoftLink_version is the version of SoftLink you are using 

Page 31: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter2.InstallingSoftLink EditingtheVertexConfigurationfile

 

August2015 Page31

OS is the operating system on which the software is being installed 

database is your database platform 

4. Use the Run command in the Start menu or through the Explorer. 

5. Install the SoftLink plug‐in dynamic linked library, psbivrtx.dll in the PeopleSoft directories <PS_HOME>\bin\client\winx86\interfacedrivers and <PS_HOME>\bin\server\winx86\interfacedrivers to overlay the PeopleSoft‐provided stub libraries. Please see your PeopleSoft documentation for specific directory requirements. 

6. Place the STQ DLLs in the <PS_HOME>\bin\client\winx86 and <PS_HOME>\bin\server\winx86 directories. See your PeopleSoft documentation for more information. 

7. Edit the Vertex Configuration file (psconfig.reg). 

8. Test the installation by following the procedure described in your PeopleSoft documentation. 

9. Reboot the computer. 

Note: Any subsequent maintenance point releases by PeopleSoft will overlay the SoftLink DLLs with a stub library and will therefore require reinstallation of the SoftLink DLLs. 

EditingtheVertexConfigurationfileThe Vertex configuration file psvtxcfg for UNIX platforms is a plain‐text file containing a series of entries that define site‐specific information that SoftLink needs. 

For Windows platforms, the Vertex configuration file (psconfig.reg) information is held in a Windows Registry. 

You must edit the configuration file to meet your needs. Text editor requirements differ by platform, as described below. 

Note: Set the configuration file for every instance of SoftLink installed. 

Page 32: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter2.InstallingSoftLink EditingtheVertexConfigurationfile

 

August2015 Page32

UNIXplatformsFor UNIX platforms, use a text editor such as vi or emacs to edit the psvtxcfg file to reflect the environment into which it is being installed. 

The following is an example of an edited Oracle configuration file: 

[SOFTWARE\Vertex\PeopleSoft\Integ] "DebugLog"="/logpath” "DebugOn"="FALSE" "UseTDM"="Y" "VVersion"=" " "RateDBDataSrc"="" "RateDBServer"="mserver" "RateDBPassword"="qsuuser" "RateDBUser"="qsuuser" "GeoDBDataSrc"="" "GeoDBServer"="mserver" "GeoDBUser"="qsuuser" "GeoDBPassword"="qsuuser" "RegDBDataSrc"="" "RegDBServer"="mserver" "RegDBUser"="qsuuser" "RegDBPassword"="qsuuser" "TDMDBDataSrc"="" "TDMDBServer"="mserver" "TDMDBUser"="qsuuser" "TDMDBPassword"="qsuuser" "JurisNames"="" "TDMCacheSize"="16" "TDMCacheAgeLimit"="3600" "TDMCaseSense"="FALSE" "StatsOn"="FALSE”

WindowsplatformsFor Windows platforms, the Vertex Configuration file (psconfig.reg) information is held in a Windows Registry. 

The .reg file is automatically placed in the Windows Registry during installation. Once installed in the Registry, the entries from the .reg file must be edited to reflect the current environment. Enter Regedit in the Run menu and find the entries at: 

[SOFTWARE\Vertex\PeopleSoft\Integ] 

Page 33: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter2.InstallingSoftLink EditingtheVertexConfigurationfile

 

August2015 Page33

ExampleofanEditedRegistryObject

The following is an example of an edited registry file: 

"DebugLog"="c:\\debug" /* Directory for log files */ "DebugOn"="FALSE" /* Debug logging on or off */ "UseTDM"="Y" "VVersion"="" "RateDBDataSrc"="c:\\db" /* Data source is only necessary for ISAM */ "RateDBServer"="" "RateDBPassword"="" "RateDBUser"="" "GeoDBDataSrc"="c:\\db" /* Data source is only necessary for ISAM */ "GeoDBServer"="" "GeoDBUser"="" "GeoDBPassword"="" "RegDBDataSrc"="c:\\db" /* Data source is only necessary for ISAM */ "RegDBServer"="" "RegDBUser"="" "RegDBPassword"="" "TDMDBDataSrc"="c:\\db" /* Data source is only necessary for ISAM */ "TDMDBServer"="" "TDMDBUser"="" "TDMDBPassword"="" "JurisNames"="" "VstRateCacheSize"="16" "TDMCacheSize"="16" "TDMCacheAgeLimit"="3600" "TDMCaseSense"="FALSE" "StatsOn"="FALSE" /* Statistics logging on or off */ "ErrorHandling"="0" /* Error handling parameters */

Note: An optional key/value pair, called ErrorHandling, was added to the configuration file for SoftLink version 2.0.20. The defined values are 0 and 1. When the value is set to 0 or the key/value pair is missing, SoftLink error handling works as in previous releases.    When the value is set to 1, SoftLink will not return an error in cases where no tax rates are defined for any of the jurisdiction levels. 

 

Page 34: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter2.InstallingSoftLink EditingtheVertexConfigurationfile

 

August2015 Page34

RequireddatabaseentriesforISAMdatabasesIf you are using ISAM databases, you must change the data source fields of these entries to match the directory paths of the Vertex Rate, GeoCoder, Register, and TDM databases. Leave other database fields empty. 

For ISAM databases the required entries are: 

RateDBDataSrc GeoDBDataSrc RegDBDataSrc TDMDBDataSrc

Refer to the Vertex Sales Tax Q Series Programmer's Guide for information on connecting to databases. 

Requireddatabaseentriesforrelationaldatabases

MSSQLserverdatabases

If you are using an MS SQL Server database (Windows version only), you must set the server name fields to the appropriate ODBC data source on the client. Then set the user ID and password fields to the appropriate MS SQL server login ID and password. 

Oracledatabases

If you are using an Oracle database, set the server name fields to the Oracle server name. Then set the user ID and password fields to the appropriate Oracle user ID and password. 

Requiredentries

For both MS SQL (Windows version only) and Oracle databases the required entries are: 

RateDBServer RateDBPassword RateDBUser GeoDBServer GeoDBUser GeoDBPassword RegDBServer RegDBUser RegDBPassword TDMDBServer TDMDBUser TDMDBPassword

Page 35: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter2.InstallingSoftLink EditingtheVertexConfigurationfile

 

August2015 Page35

Debug,statistics,anddebuglogflagsThe DebugOn and StatsOn flags in the configuration file are used to independently turn on the debug and statistics feature. The DebugLog sets the directory for both of these features. Details are given in the following table: 

Flag Description

DebugOn  Enables SoftLink to write to a debug file. Possible values are: 

FALSE= Off (for normal operation) 

TRUE= On (write debug file) 

The debug file name is in the form pid.psver.log where pid represents the process ID. 

 

StatsOn  Enables SoftLink to write to a statistics file. Possible values are: 

FALSE= Off (for normal operation) 

TRUE= On (write statistics file) 

The statistics file name is in the form pid.psver.sta where pid represents the process ID. 

DebugLog  Sets directory in which the debug and statistics files are written. Entry must end in a forward slash (/) for UNIX and in a backslash (\) for Windows. 

 

Page 36: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter2.InstallingSoftLink EditingtheVertexConfigurationfile

 

August2015 Page36

TaxspecificflagsSeveral flags specific to the tax calculation function must be set. The following table lists the possible values for each flag: 

Flag Description

UseTDM  Dictates whether the TDM Database is used to determine taxability. Possible values are: 

Y = Let TDM determine taxability (Default) 

N = Do not let TDM determine taxability 

Note: SoftLink has two ways of setting the UseTDM parameter: using the API or using the registry (softlink.reg) file. 

Note: SoftLink first uses the API setting. Then, if an OpenDb() call is issued, SoftLink reads the UseTDM setting from the registry, which overrides the API. 

JurisNames  Retained only for backward compatibility; leave blank. 

TDMCacheSize  Dictates the number of records to be stored in the TDM Database record cache. Default is 16. 

TDMCacheAge‐Limit  Dictates, in seconds, how long a TDM exception record can remain in the cache. Default is 3600. 

TDMCase‐Sensitive  Enables or disables case sensitivity. For Oracle database users, case sensitivity provides more efficient access to TDM Customer and Product basic tables in large TDM databases. Users of other databases should disable this feature. Possible values are: 

TRUE = Enabled 

FALSE = Disabled (Default) 

Note: If case sensitivity is enabled, it is critical that company codes, division codes, customer codes, and product codes in the TDM be in uppercase. If these codes are in mixed case or lower‐case, run the Oracle script tdmupd2.sql against the TDM Database to convert the codes to uppercase. 

Page 37: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter2.InstallingSoftLink EditingtheVertexConfigurationfile

 

August2015 Page37

Flag Description

UseFiveDigitZIPOnly  An optional registry key called UseFiveDigitZIPOnly is now available to enable or disable jurisdiction identification using US Postal Service nine‐digit ZIP Codes (ZIP+4).   

STQ 4.0 can provide more precise GeoCodes when you provide a nine‐digit ZIP Code instead of a five‐digit ZIP Code. To support this new capability, approximately 1,100 new district‐level GeoCodes were added to the appropriate data files. STQ 4.0 continues to assign GeoCodes using five‐digit ZIP Codes as well as nine‐digit ZIP code information, so this new functionality is optional. 

To set the UseFiveDigitZIPOnly registry key, select one of the following values: 

0 = SoftLink uses nine‐digit ZIP Codes (ZIP+4) if they are provided for GeoCode retrieval. This is the default value.   

1 = SoftLink uses five‐digit ZIP Codes for GeoCode retrieval even if a nine‐digit ZIP Code is provided. 

VVersion  Retained only for backward compatibility; leave blank. 

An optional key/value pair controls error handling. 

Flag Description

ErrorHandling  Controls error handling for jurisdictions with no tax rates and foreign jurisdictions. Possible values are: 

0 = SoftLink error handling works as in previous releases. This is also the behavior in the case where the flag "ErrorHandling" is not defined. 

1 = SoftLink does not return an error in cases where no tax rates are defined for any of the jurisdiction levels. 

2 = SoftLink does not return an error in cases where an error occurs during jurisdiction lookup, such as foreign jurisdictions with GeoCode 79‐000‐0000. 

3 = SoftLink combines the logic of values 1 and 2, and does not return errors in cases where no tax rates are defined for any of the jurisdiction levels, or when an error occurs during jurisdiction lookup. 

 

 

Page 38: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

 

August2015 Page38

C h a p t e r 3

TroubleshootingSoftLinkThis chapter describes troubleshooting of the PeopleSoft‐to‐SoftLink interface. 

Inthischapter

Troubleshooting the PeopleSoft‐to‐SoftLink interface ................. 38 Error codes and associated messages ........................................... 40 

 

TroubleshootingthePeopleSoft‐to‐SoftLinkinterfaceThis section describes a general approach to troubleshooting the PeopleSoft‐to‐SoftLink interface and identifies several likely error causes. 

ErrorindicationsIf an error occurs in transmitting a request from PeopleSoft to STQ or in receiving a response, set the DebugOn flag to TRUE, to produce a debug log file and provide a path to where the log file should be created on the debug log field. The section Error codes and associated messages (see page 40) lists possible error indications. 

VariablesettingerrorsSeveral errors can result from incorrect setting of environment and database variables, including: 

NotAbletoAccesstheConfigurationFile/Registry

In a UNIX environment, ensure the PSVTXCFG environment variable is set. 

In a Windows environment, make sure the Windows Registry contains the [HKEY_LOCAL_MACHINE\SOFTWARE\Vertex\PeopleSoft\Integ] key. 

Page 39: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter3.TroubleshootingSoftLink TroubleshootingthePeopleSoft‐to‐SoftLinkinterface

 

August2015 Page39

NoResponsefromSoftLinkorSharedObjectorDLLNotFound

In a UNIX environment, ensure the appropriate environment variable is set: 

LD_LIBRARY_PATH for Solaris and HP‐UX. 

LIBPATH for AIX 

Ensure the PeopleSoft‐provided stubs have been overwritten. Make sure that SoftLink and STQ shared libraries are installed in appropriate directories and the environment variables are set correctly, as explained in the Procedure for Installing SoftLink (see page 29). 

In a Windows environment, make sure the directory in which psbivrtx.dll is installed is in the path. Ensure the PeopleSoft‐provided stubs have been overwritten. Ensure that SoftLink and STQ DLLs are installed in appropriate directories, as explained in the Procedure for Installing SoftLink (see page 29). 

NotAbletoOpentheSTQdatabasesWith the debug log enabled, the message OpenDb( ) failed. Could not open databases is returned. 

Make sure all of the connection parameters are correct for each database. If you are connecting to an ISAM database, ensure that only the data source field is filled, the database files actually exist in the specified path, and the PeopleSoft application has read/write permissions to ISAM files. 

If you are working with a relational database (Oracle or MS SQL), be sure the data server, user name, and password are correctly entered. 

Also, check that you can reach your databases and calculate tax through vsttest.exe. Refer to the Vertex Sales Tax Q Series Administrator's Guide for details on this program. 

CannotLoadBusinessInterlinkPlug‐inorCannotLoadPlug‐inEnsure that the SoftLink plug‐in shared library/DLL and STQ shared libraries/DLLs are installed in appropriate directories as described in the Procedure for installing SoftLink (see page 29) section. 

Ensure that the pathname for the SoftLink plug‐in shared library/DLL is specified correctly in the Business Interlink Design Time Plug‐in XML file, psbivrtx.xml. 

Page 40: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter3.TroubleshootingSoftLink Errorcodesandassociatedmessages

 

August2015 Page40

ServerconnectionerrorThis error message may be caused by invalid database connection parameters. Ensure that debugging is turned on, then retry and check the SoftLink debug file to determine the error. 

ErrorcodesandassociatedmessagesThis section describes the error codes and associated messages recorded in the debug log when the debug feature is activated by setting the DebugOn flag to TRUE. The additional error messages printed in the log file provide more detailed information about the associated error code. The error codes and messages are organized by function. 

Note: Upon completion of troubleshooting, reset the DebugOn flag to FALSE. If this flag remains set to TRUE, log files will be generated for all transactions processed. 

GetGeoCodeCodeReturned MessageReturned

‐1  GetGeoCode() failed. Could not open databases. 

‐2  Error creating context handle. 

0  GetGeoCode() returns a NoMatch or NoMoreLocations. 

‐9  Using PeopleSoft stub.  

Page 41: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter3.TroubleshootingSoftLink Errorcodesandassociatedmessages

 

August2015 Page41

OpenDbCodeReturned MessageReturned

0  OpenDb() succeeded. 

1  Memory error while opening one of the databases. 

2  Error opening Rate database. 

3  Error opening GeoCode database. 

4  Error opening TDM database. 

5  Error opening Register database. 

6  Error creating connection handle. 

8  Installation parameters not set up. 

9  Using PeopleSoft stub.  

CloseDbCodeReturned MessageReturned

0  CloseDb() succeeded. 

1  Memory error while closing one of the Vertex databases. 

7  Error during the closing of a Vertex database. 

7  Error releasing connection handle. 

9  Using PeopleSoft stub. 

 

Page 42: SoftLink 2.2 for PeopleTools 8.4 and 8 - downloads.vgtsi.com Supplement_3.pdf · host system, and use Vertex® Tax Decision Maker or Vertex® Taxability ...

SoftLink2.2forPeopleTools8.4and8.5Chapter3.TroubleshootingSoftLink Errorcodesandassociatedmessages

 

August2015 Page42

CalcTaxCodeReturned MessageReturned

0  CalcTax() succeeded. 

6  Error creating Vertex tax handle. 

6  Error returned from one of the VstSet Vertex functions. 

6  Error returned from one of the VstGetTrans Vertex functions. 

6  Error returned from VstCalcTax Vertex function.