User's Guide

Vertex® Indirect Tax O Series® 9.0

Vertex® O Series® Client Utilities
August 2019
Copyright and legal notices
Copyright © 2019 Vertex, Inc. 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, Inc. 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.
Contents

What's New in This Guide? ............................................................................................ 5

What's New in this guide for 9.0 (August 2019) .................................................................. 5

Preface ........................................................................................................................... 6
About Vertex and our services ........................................................................................... 6
About Vertex O Series ........................................................................................................ 8
Finding information about Vertex Indirect Tax O Series ..................................................... 9
About this guide ............................................................................................................... 13

Chapter 1. O Series Client Utilities Overview ............................................................ 14

O Series Client Utilities command line overview .............................................................. 15
O Series Client Utilities web services overview................................................................. 21
Before you begin using the O Series Client Utilities .......................................................... 23
Best practice: Create a custom role with a password that does not expire for your
O Series Client Utilities activities ............................................................................... 23
How to configure the O Series Client Utilities in an On-Premise environment (server-
side Vertex O Series) .................................................................................................. 24
The oseries-client.zip file ................................................................................................. 29
Requirement: Vertex Retail users must create a Data Management filter ...................... 30
Requirement: Data Extract users must create a Data Extract definition.......................... 30

Chapter 2. O Series Client Utilities Through the Command Line ............................. 31

Data Management command line utilities ....................................................................... 31
The runBatchClientInterface utility.................................................................................. 32
The runTaxDataImport utility .......................................................................................... 38
The runTaxDataExport utility ........................................................................................... 40
The runTaxEngineExtract utility ....................................................................................... 43
The runRetailTaxExtract utility......................................................................................... 45
The runEUMossExtract utility .......................................................................................... 47
Data Extract command line utilities.................................................................................. 50
The runDataExtract utility................................................................................................ 51
File Transfer command line utilities ................................................................................. 53
The putFile utility ............................................................................................................. 53
The getFile utility ............................................................................................................. 55

Chapter 3. O Series Client Utilities Through Web Services ....................................... 59

Connecting to the WSDL endpoint.................................................................................... 59
Where to find annotated schema documentation ............................................................ 60
Data Management web services ...................................................................................... 61

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 3
 Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide

Can I access a local Batch Client Interface database using the Batch Client Interface
web service? .............................................................................................................. 61
Data Extract web services ................................................................................................ 62
File Transfer web services ................................................................................................ 62
How uploading status files from a Vertex Retail Local Indirect Tax Engine (LITE)
deployment to a Vertex Central deployment works .................................................. 62
How retrieving files from Batch Client Interface processing works ................................. 63
Security Services web services ......................................................................................... 65

Chapter 4. Troubleshooting the Vertex O Series Client Utilities Run Through web
services ........................................................................................................................ 66
Troubleshooting a client fault .......................................................................................... 66
Troubleshooting a server fault ......................................................................................... 67

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 4
What's New in This Guide?
This section describes the new features for the latest major release and all service releases.

What's New in this Guide for O Series 9.0

(August 2019)
Additional details about delete transactions are added to this version of the guide.
If you are upgrading to Vertex O Series 9.0, you need to be aware of the O Series schema
changes and additions that may impact your integration. For details, refer to the chapter, "If You
Are Upgrading to Vertex O Series 9.0," in the XML Integration Guide.
Review the annotated HTML files for the Vertex O Series 9.0 schema. These HTML files are
included in the Vertex OSeries v9 Client Utilities.zip file that contains this guide.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 5
Preface
This preface contains information about Vertex services, Vertex® Indirect Tax O Series®, and its
documentation.

About Vertex and our services

Vertex Inc. is a leading tax software and services provider that empowers global commerce.
Vertex connects customers and partners across all industries to deliver the world’s most trusted
tax solutions for businesses to grow with confidence. Vertex provides cloud-based and on-
premise solutions that can be tailored to specific industries for every major line of indirect tax,
including sales and consumer use, value added, and payroll. Headquartered in Pennsylvania and
with offices worldwide, Vertex is a privately held company that employs over 1,000
professionals and serves companies across the globe.

Vertex has offices in King of Prussia, Pennsylvania; Sarasota, Florida; Naperville, Illinois; London,
United Kingdom; and São Paulo, Brazil. For office addresses and telephone numbers, go to
https://www.vertexinc.com/contact.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 6
 Preface

Vertex services
Vertex provides the following services:
D

For... Go to...

Technical questions Vertex Customer Support

about your products Phone: 800.281.1900 (Monday through Friday, 8:15 A.M. to
8:00 P.M. United States Eastern Time)
Web: https://vertexinc.custhelp.com/
Documentation, The myVertex customer portal
downloads, forums, Web: https://vertexinc.custhelp.com/
service requests, and
up-to-the-minute
information about tax
rates, tax rules, and
jurisdictions
Questions about your Vertex Account Services
licensing agreement, Phone: 800.355.3500 or 610.640.4200
license renewal, and
Web: www.vertexinc.com/contact
invoicing
arrangements for your
products
Regional training Vertex Training
classes, web-based Phone: 877.455.2645 (Monday through Friday, 8:15 A.M. to
training classes, or on- 8:00 P.M. United States Eastern Time) option #2
site training at your
Web: www.vertexinc.com/training
facility

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 7
 Preface

About Vertex O Series

The Vertex O Series platform provides an advanced architecture for integrating a broad range of
tax compliance features into a single, seamless application suite.
By using object-oriented techniques and web technologies, such as XML, HTML, SOAP, and Java,
Vertex O Series efficiently combines functionality for data maintenance, tax calculation, system
administration, and external interface to a financial host system that can be shared by multiple
applications. Vertex O Series also provides easy, flexible deployment in a variety of operating
environments.
The Vertex O Series suite offers the following products:
• Vertex® Indirect Tax O Series® for calculating tax on business transactions. To help you
achieve tax compliance, it calculates tax based on Vertex-supplied research and your
customizations of jurisdiction rates, rules, and exceptions.
• Vertex® Indirect Tax Reporting & Analysis, a web-based reporting and analytics application
that works with IBM Cognos technology to turn your transaction and taxability data into
valuable information. You can create custom tables, pivot tables, charts, and reports that
contain the information that you need in the format that you require.
• Vertex® Indirect Tax for Retail (Vertex Retail), which coordinates the exchange and
maintenance of tax data for Point-of-Sale (POS) systems between a central headquarters
and multiple POS locations.
• Vertex® Indirect Tax for Leasing (Vertex Leasing), a tax calculation solution for major leasing
software vendors and their enterprise customers within the equipment and vehicle leasing
industries.
• Address Cleansing to improve the granularity of TaxGIS database searches for United States
address data and provide better jurisdiction assignments. This service assigns nine-digit ZIP
Codes, converts addresses to a standard format, and corrects address errors. You can
purchase this service separately as an add-on feature.
Vertex provides On-Demand deployment options for all of the above products. These software-
as-a-service, hosted models accelerate implementation and reduce hardware, database, and
other support requirements.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 8
 Preface

Finding information about Vertex

Indirect Tax O Series
Vertex provides documentation for the tasks that you must complete to use O Series
successfully. Most documentation is available on the myVertex customer portal
(https://vertexinc.custhelp.com).
Note: You can also use myVertex to access the online Knowledge Base, submit a Service
Request, or visit the Communities where you can communicate with other Vertex users
about tips, tricks, and best practices.

Preparing your O Series instance

For this task Use this documentation

Planning your implementation for Planning Guide

technology and tax compliance.

Installing and deploying the O Series Installation Guide

platform and loading O Series.
Configuring O Series. Configuration Parameters Reference Guide
Performing administrative tasks, such as Administration Guide
defining user access and roles, applying
data updates, moving data, and
monitoring performance.

Integrating O Series with your host system

For this task Use this documentation
Using XML messages to integrate O Series XML Integration Guide
and your host system.

Using the Java interface to integrate O Java Integration Guide

Series and your host system.

Managing O Series tax data that is used in Vertex Central Web Services Integration
a calling application. Guide

Using the Batch Client Interface to process Batch Client Interface Integration Guide
groups of transactions without writing an
interface between O Series and your host
system.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 9
 Preface

Maintaining O Series
For this task Use this documentation

Managing O Series data, customized data, Administration Guide

and Tax Journal data. Vertex Central Help
User's Guide
Performing monthly updates. Administration Guide
Upgrading to the latest major version of Upgrade Guide
O Series.

Using O Series for indirect tax

For this task Use this documentation
Setting up taxability information and your Vertex Central Help
structure, such as the following: User's Guide
• Taxpayers, customers, and vendors
• Certificates
• Taxability categories
• Taxability drivers
• Tax rules
Generating standard reports and Data Vertex Central Help
Extract reports. User's Guide

Using the command line or web services O Series Client Utilities User's Guide
to perform activities for Data
Management, Data Extract, and file
transfer.
Using required data file formats to move Tax Data File Formats Handbook
data between O Series and your host
system.
Reviewing formats in which you can view Reporting Database Views Tipsheet
the Reporting database data.
Exemption Certificate Manager Vertex Central Help
ECM Administration Guide
ECM Configuration Guide
Exemption Certificate Portal Exemption Certificate Portal User’s Guide
Exemption Certificate Wizard ECW Integration Guide
ECW Portal Help

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 10
 Preface

Using O Series with Vertex Returns

For this task Use this documentation
Exporting data for returns. Vertex Central Help
User's Guide

Using the required header and export file Returns Export Data File Format Handbook
formats to move data between O Series
and Vertex Returns to create ready-to-file
returns.
Using the required header and export file VAT Returns Export Data File Format
formats to move data between O Series Handbook
and Vertex Returns to create ready-to-file
VAT returns.
Setting up data transfers and Returns Reconciliation Guide
understanding data discrepancies
between O Series and Vertex Returns.

Using O Series with Vertex Reporting & Analysis

For this task Use this documentation

Generating reports and adhoc queries. Vertex Reporting & Analysis User’s Guide
Learning more about Cognos. IBM Cognos Business Intelligence
Installation and Configuration Guide
IBM Cognos Query Studio User Guide
IBM Cognos Connection User Guide

Using O Series On-Demand

For this task Use this documentation

Understanding your responsibilities for On-Demand Getting Started Guide

setting up and for implementing your
hosted O Series environment.
Using O Series in your hosted Vertex Central Help
environment.
Supporting your decision-making during On-Demand Implementation Guide
the onboarding process, reviewing
configuration settings, and managing your
Vertex O Series On-Demand instance.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 11
 Preface

Using O Series with industry-specific and jurisdiction-specific data

For this product Use this documentation
Vertex Indirect Tax for Retail Retail Getting Started Guide
Retail Installation and Administration
Guide
Retail Tax Extract Integration Guide
Vertex Indirect Tax for Leasing Vertex Indirect Tax for Leasing Planning
Guide
Administration Guide
Vertex Central Help
Vertex Indirect Tax for Hospitality Vertex Indirect Tax for Hospitality Planning
Guide
Vertex Central Help
Vertex Indirect Tax for Brazil Brazil Guide

Vertex® Indirect Tax for Communications Vertex® Indirect Tax for Communications
Guide

Using the O Series Tax Data Management Plug-in

For this task Use this documentation
Moving O Series data into a tax data Tax Data Management Plug-In Quick
repository Reference Guide
Reviewing the format of the Wide Tax Tax Data Management Plug-In Wide Tax
Journal File Journal File Format Handbook

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 12
 Preface

About this guide

The following table shows the audience for this guide:
How this audience uses
Type of audience Required skills for this audience
Client Utilities
IT professional. This Through the command • Implementing new hardware
professional is line and software
generally assigned the • Network management
Vertex-defined role of • Databases
Partition System
• Security
Administrator.
Software developer Through the web • Web services, including
services accessing, deploying, and
troubleshooting
• Standalone XML or browser-
based editors
• Simple Object Access
Protocol (SOAP) toolkits for
the relevant development
environment

This guide describes what you need to know to do the following:

• Perform configuration tasks in an On-Premise environment (server-side Vertex O Series).
• Locate, download, and unzip the oseries-client.zip file that contains the command line
scripts, configuration file, and supporting files.
• Perform Data Management, Data Extract, and File Transfer activities via the O Series Client
Utilities that are available through the command line in Windows or UNIX.
• Connect to the Web Service Description Language (WSDL) endpoint for each O Series Client
Utilities web service.
• Perform Data Management, Data Extract, File Transfer, and Security Services activities via
the O Series Client Utilities that are available through the web services.
• Retrieve the status of a Data Management activity. This activity can be run only through a
web service.
• Retrieve the status of a Data Extract activity. This activity can be run only through a web
service.
Vertex product documentation covers only the software functionality and usage. For
information about scenarios outside the documented functionality, visit myVertex
(https://vertexinc.custhelp.com/).
To provide questions and/or feedback, email documentation@vertexinc.com.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 13
Chapter 1. O Series Client Utilities
Overview
The Vertex® Indirect Tax O Series® Client Utilities (O Series Client Utilities) consist of the
command line utilities and web services that enable you to perform specific Data Management,
Data Extract, File Transfer, and Security Services activities. You can perform these activities in
both an On-Demand environment (client-side using hosted Vertex O Series) and an On-Premise
environment (server-side Vertex O Series).
This chapter provides a summary of these utilities and describes how to access them.

In this chapter
O Series Client Utilities command line overview ..........................15
O Series Client Utilities web services overview ............................21
Before you begin using the O Series Client Utilities......................23

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 14
 Chapter 1. O Series Client Utilities Overview

O Series Client Utilities command line

overview
Use the command line when you want to schedule activities to run at a specific time.
The tables below provide an overview of the Data Management, Data Extract, and File Transfer
functions that are available through the command line:
Note: You can use the File Transfer utilities independently of the Data Management utilities.

Windows
These O Series Client
Enable you to... With this command line...
Utilities...
Batch Client Interface Perform Batch Client runBatchClientInterface.bat
Interface processing.
This includes uploading
the associated CSV file
or database for
processing, downloading
the results file and, if
applicable, an errors file.
Batch Client Interface Use a delete transaction runBatchClientInterface.bat
file to mark transactions
as deleted in the Tax
Journal.
The delete transaction
file is a CSV file with the
Delete message type
and either document
numbers or transaction
IDs. Refer to the Batch
Client Interface
Integration Guide for
more information.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 15
 Chapter 1. O Series Client Utilities Overview

These O Series Client

Enable you to... With this command line...
Utilities...
Tax Data Import Perform a Tax Data runTaxDataImport.bat
Import.
This includes uploading
the import file to the
Vertex O Series server
from the local machine.
Tax Data Export Perform a Tax Data runTaxDataExport.bat
Export.
This includes
downloading the export
file to the local machine
from the Vertex O Series
server.
Tax Engine Extract in a Perform a Tax Engine runTaxEngineExtract.bat
Vertex® Indirect Tax for Extract.
Retail - This includes
Local Indirect Tax downloading the extract
Engine (LITE) file to the local machine
deployment from the Vertex O Series
server.
Retail Tax Extract in a Perform a Retail Tax runRetailTaxExtract.bat
Vertex Retail - Extract.
Retail Tax Extract This includes
deployment downloading the extract
file to the local machine
from the Vertex O Series
server.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 16
 Chapter 1. O Series Client Utilities Overview

These O Series Client

Enable you to... With this command line...
Utilities...
EU MOSS Extract Perform an EU MOSS runEUMossExtract.bat
Extract. For more details
about EU MOSS, refer to
the EU Mini One Stop
Shop in O Series Guide.
This includes uploading
the exchange rates file
from the local machine
to the Vertex O Series
server.
This includes
downloading the extract
file to the local machine
from the Vertex O Series
server.
Data Extract Perform a Data Extract. runDataExtract.bat
This includes
downloading the extract
file to the local machine
from the Vertex O Series
server.
File Transfer - Download a file from the getFile.bat
Download Vertex O Series server to
the local machine.

File Transfer - Upload Upload a file from the putFile.bat

local machine to the
Vertex O Series server.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 17
 Chapter 1. O Series Client Utilities Overview

UNIX
These O Series Client
Enable you to... With this command line...
Utilities...
Batch Client Interface Perform Batch Client runBatchClientInterface.sh
Interface processing.
This includes uploading
the associated CSV file
or database for
processing, downloading
the results file and, if
applicable, an errors file.
Batch Client Interface Use a delete transaction runBatchClientInterface.sh
file to mark transactions
as deleted in the Tax
Journal.
The delete transaction
file is a CSV file with the
Delete message type
and either document
numbers or transaction
IDs. Refer to the Batch
Client Interface
Integration Guide for
more information.
Tax Data Import Perform a Tax Data runTaxDataImport.sh
Import.
This includes uploading
the import file to the
Vertex O Series server
from the local machine.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 18
 Chapter 1. O Series Client Utilities Overview

These O Series Client

Enable you to... With this command line...
Utilities...
Tax Data Export Perform a Tax Data runTaxDataExport.sh
Export.
This includes
downloading the export
file to the local machine
from the Vertex O Series
server.
Tax Engine Extract in a Perform a Tax Engine runTaxEngineExtract.sh
Vertex® Indirect Tax for Extract.
Retail - This includes
Local Indirect Tax downloading the extract
Engine (LITE) file to the local machine
deployment from the Vertex O Series
server.
Retail Tax Extract in a Perform a Retail Tax runRetailTaxExtract.sh
Vertex Retail - Extract.
Retail Tax Extract This includes
deployment downloading the extract
file to the local machine
from the Vertex O Series
server.
EU MOSS Extract Perform an EU MOSS runEUMossExtract.sh
Extract. For more details
about EU MOSS, refer to
the EU Mini One Stop
Shop in O Series Guide.
This includes uploading
the exchange rates file
from the local machine
to the Vertex O Series
server.
This includes
downloading the extract
file to the local machine
from the Vertex O Series
server.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 19
 Chapter 1. O Series Client Utilities Overview

These O Series Client

Enable you to... With this command line...
Utilities...
Data Extract Perform a Data Extract. runDataExtract.sh
This includes
downloading the extract
file to the local machine
from the Vertex O Series
server.
File Transfer - Download a file from the getFile.sh
Download Vertex O Series server to
the local machine.
File Transfer - Upload Upload a file from the putFile.sh
local machine to the
Vertex O Series server.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 20
 Chapter 1. O Series Client Utilities Overview

O Series Client Utilities web services

overview
Connect to the Web Service Description Language (WSDL) endpoint for the O Series Client
Utilities web services at:
http://server:port/vertex-remote-services/listVertexServices.jsp

where:
server is the name of the server for the Vertex O Series web services page.

port is the name of the connection port that directs you to the Vertex O Series web services
page.
This WSDL enables you to access Data Management, Data Extract, File Transfer, and Security
Services web services.
The table below provides an overview of the Data Management, Data Extract, File Transfer, and
Security Services functions that are available through the web services:
These O Series Client
Enable you to ...
Utilities...
Data Management web services

Batch Client Interface Perform Batch Client Interface processing.

This does not include uploading or downloading a file. Create
a PutFile Request message to upload a file and a GetFile
Request message to download a file.
Tax Journal Export Perform a Tax Journal Export.
This does not include downloading a file. Create a GetFile
Request message to download the export file.
Tax Data Import Perform a Tax Data Import.
This does not include uploading a file. Create a PutFile Request
message to upload the import file.
Tax Data Export Perform a Tax Data Export.
This does not include downloading a file. Create a GetFile
Request message to download the export file.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 21
 Chapter 1. O Series Client Utilities Overview

These O Series Client

Enable you to ...
Utilities...
Tax Engine Extract in a Perform a Tax Engine Extract.
Vertex Retail - This does not include downloading a file. Create a GetFile
Local Indirect Tax Request message to download the export file.
Engine (LITE)
deployment
Retail Tax Extract in a Perform a Retail Tax Extract.
Vertex Retail - This does not include downloading a file. Create a GetFile
Retail Tax Extract Request message to download the export file.
deployment
EU MOSS Extract Perform an EU MOSS Extract.
This does not include either of the following:
• Uploading the exchange rates file. Create a PutFile
Request message to upload the exchange rates file.
• Downloading a file. Create a GetFile Request message to
download the extract file.
Get Activity Status Retrieve the current status of a Data Management Activity.

Data Extract web services

Data Extract Perform a Data Extract.

This does not include downloading a file. Create a GetFile
Request message to download the export file.
Get Extract Status Retrieve the current status of an extract activity.

File Transfer web services

GetFile Download a file from the Vertex O Series server to the local
machine.
PutFile Upload a file from the local machine to the Vertex O Series
server.
Security Services web services

CreatePartition Create a new partition on the Vertex O Series server.

CreateUser Create a new user on the Vertex O Series server.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 22
 Chapter 1. O Series Client Utilities Overview

Before you begin using the O Series

Client Utilities
To ensure that the O Series Client Utilities function properly, you must perform the following
tasks before you begin using these utilities:
1. If you have an On-Premise environment (server-side Vertex O Series), perform configuration
tasks (see page 24).
2. Locate, download, and unzip the oseries-client.zip file (see page 29).
3. If you use the Vertex Retail utilities, create a Data Management filter (see page 30).
4. If you use the Data Extract utilities, create a Data Extract definition (see page 30).

Best practice: Create a custom role with a password that

does not expire for your O Series Client Utilities activities
If you perform regularly scheduled activities through the Vertex O Series Client Utilities in either
an Vertex O Series On-Demand or a Vertex O Series on premise environment, Vertex
recommends that you create a password that does not expire. This will enable you to perform
your scheduled Data Management, Data Extract, or File Transfer activities without interruption.
To prevent any potential security issues that may occur by using a password that does not
expire, Vertex also recommends that you create a custom role that is dedicated to performing
the scheduled O Series Client Utilities activities. Vertex recommends that this role have
permissions only for the Vertex O Series features that you use in your scheduled activities.
Assign the password that does not expire to this custom role.
For more details about creating a password that does not expire, refer to the Vertex Central
Help.
For details about Vertex Indirect Tax O Series On-Demand, refer to the Vertex O Series On-
Demand Getting Started Guide.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 23
 Chapter 1. O Series Client Utilities Overview

How to configure the O Series Client Utilities in an On-Premise

environment (server-side Vertex O Series)
If you have an On-Premise environment (server-side Vertex O Series), complete the following
configuration process:
1. Set permissions in Vertex Central related to O Series Client Utilities (see page 25).
2. If needed, set O Series Client Utilities-related configuration parameters (see page 26).
3. Set the oseries-client.properties file configuration parameters (see page 27).
Optionally, you may choose to configure log4j functions to create an O Series Client Utilities log
file (see page 28).

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 24
 Chapter 1. O Series Client Utilities Overview

How the Vertex Retail license and permissions in Vertex Central relate
to O Series Client Utilities
Before you can use the O Series Client Utilities in an On-Premise environment (server-side
Vertex O Series), you must have obtained the appropriate Vertex O Series license and set the
appropriate Vertex O Series permissions. You must have a Vertex® Indirect Tax for Retail license
to use the retail features in the O Series Client Utilities.
To use the O Series Client utilities for Data Management activities, you must have enabled
permissions for:
• Batch Client Interface
• Tax Engine Extract and Import Service
• Retail Tax Extract
• Tax Journal Export
• Tax Data Import
• Tax Data Export
• Task Log features
• Data Extract
Set the permissions for O Series Client Utilities in Vertex Central through System > Roles.
Note: The Import Service feature is available to only a Vertex O Series user with a Master
Administrator role.
When you set the permissions for Batch Client Interface, Tax Engine Extract, and Retail Tax
Extract, the associated file transfer activities are also enabled.
Refer to Data Management permissions in the Vertex Central Online Help for more details on
the permissions related to:
• Batch Client Interface
• Tax Engine Extract
• Import Service
• Retail Tax Extract
• Tax Journal Export
• Tax Data Import
• Tax Data Export
• Task Log
For more details on the permissions related to Data Extract, refer to Data Extract Permissions in
the Vertex Central Online Help.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 25
 Chapter 1. O Series Client Utilities Overview

Vertex O Series configuration parameters you may need to set for

the O Series Client Utilities
If your Vertex O Series deployment uses multiple application servers and these servers do not
share the Vertex Home directory you specified during Vertex O Series installation, set the
following parameters in the vertex.cfg file to point to a shared file directory:
• common.reports.dir.batch.client.output.dir. For more details on this parameter, refer to the
Configuration File Parameters Reference Guide.
• retail.taxjournal.dir. For more details on this parameter, refer to the Vertex® Indirect Tax for
Retail Installation and Administration Guide.
• retail.taxdata.dir. For more details on this parameter, refer to the Vertex® Indirect Tax for
Retail Installation and Administration Guide.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 26
 Chapter 1. O Series Client Utilities Overview

Configuration parameters in the O Series Client Utilities oseries-

client.properties file
The oseries-client.properties file enables you to configure the O Series Client Utilities. The
oseries-client.properties file resides in the /config subdirectory where you unzipped the oseries-
client.zip file on your local machine.

Web services-related parameters

The oseries-client.properties file contains the following web-services-related parameters:
Parameter Definition Default value Additional information
WebServiceURL The URL for the http://<server>:<port Specify the location of
Vertex O Series >/ the server and port
web services. vertex-remote-services information for the O
Series web services at
your site.
PollingFrequency The frequency in 10 seconds. This value must be a
seconds in which positive integer.
the command
line scripts poll
the O Series
Client Utilities
web service to
determine if any
activity has been
completed.
TransferBufferSize The maximum 64KB. N/A.
number of bytes
that the O Series
Client Utilities
can transfer at a
given time.
Timeout The time limit in 60 minutes. If the activity does not
minutes for the complete within this
completion of an time limit, the
O Series Client associated command
Utilities activity. line scripts time out.
This value must be a
positive integer.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 27
 Chapter 1. O Series Client Utilities Overview

Batch Client Interface-related parameters

If you want to use a local Batch Client Interface database as input for Batch Client Interface
processing, you must set the following parameters in the oseries-client.properties file. There are
no default values for these parameters:
Parameter Definition References
BciDriverName The database driver Refer to the comments in this file for
name for the local Batch examples of JDBC driver names.
Client Interface
database.
BciUrl The database URL for Refer to the comments in this file for
the local Batch Client examples of connection URLs.
Interface database.
BciUserName The database user name N/A.
for the local Batch Client
Interface database.
BciPassword The database password N/A.
for the local Batch Client
Interface database.

Configuring log4j to create an O Series Client Utilities log file

The O Series Client Utilities display the error and status messages below on the command line
console as it processes transactions.
If you want to save these error and status messages to a log file in addition to viewing them on
the command line console, complete the following steps:
1. Locate the log4j.properties file in the Vertex Home/config directory.
2. Open the log4j.properties file with a text editor.
3. Comment out the following text by adding a # sign:
# Define the root logger with appender file
log4j.rootLogger=INFO, ConsoleAppender
4. Uncomment the following lines by removing the # sign:
# log4j.rootLogger = INFO, ConsoleAppender, FileAppender
# log4j.appender.FileAppender=org.apache.log4j.FileAppender
# log4j.appender.FileAppender.File=./on_demand_client.log
# log4j.appender.FileAppender.layout=org.apache.log4j.PatternLayout
# log4j.appender.FileAppender.layout.conversionPattern=%d{HH:mm:ss} [%p] %m%n
5. Save your changes in the text editor.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 28
 Chapter 1. O Series Client Utilities Overview

The oseries-client.zip file

The oseries-client.zip file contains the command line scripts, configuration file, and supporting
files for the O Series Client Utilities.

Locate the oseries-client.zip file

The location of the oseries-client.zip file depends on what type of Vertex O Series environment
you have:
• If you have an On-Demand environment (client-side using hosted Vertex O Series), a link to
this file is located in the Client Tools section that is on the O Series landing page.
• If you have an On-Premise environment (server-side Vertex O Series), this file is located on
the myVertex customer portal.

Download and unzip the oseries-client.zip file

Download and unzip the oseries-client.zip file to a directory on your local machine.

Where can I find the components of the oseries-client.zip file?

This oseries-client.zip file contains the following directory structure:
This O Series
Client Utilities Contains these files ...
directory...
bin Command Line script files (.bat and .sh)
config Configuration file
lib Supporting JAR files
sql SQL scripts for the Retail Tax Extract database
Note: If you are licensed for Vertex Retail and have a
Retail Tax Extract deployment, use these SQL
scripts to manipulate the Retail Tax Extract data on
your local machine. For details, refer to
Manipulating Retail Tax Extract data using the O
Series Client Utilities (see page 47).

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 29
 Chapter 1. O Series Client Utilities Overview

Requirement: Vertex Retail users must create a Data

Management filter
If you are licensed for Vertex Retail, create a Data Management filter before you use the Vertex
Retail utilities in the O Series Client. You can create a new Data Management filter through
Vertex Central.
For details on creating a Data Management filter, refer to the Vertex Central Online Help.

Requirement: Data Extract users must create a Data Extract

definition
If you are a Data Extract user, create a Data Extract definition before you use the Data Extract
utilities in the O Series Client. You can create a new data extract definition through Vertex
Central.
For details on creating a Data Extract definition, refer to the Vertex Central Online Help.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 30
Chapter 2. O Series Client Utilities
Through the Command Line
The O Series Client Utilities that are available through the command line include the Data
Management, Data Extract, and File Transfer utilities. This chapter includes the procedures and
parameters associated with each utility.

In this chapter
Data Management command line utilities ...................................31
Data Extract command line utilities..............................................50
File Transfer command line utilities .............................................53

Data Management command line

utilities
The Data Management utilities that are available through the command line enable you to
perform the following activities in Windows or UNIX:
• The runBatchClientInterface utility (see page 32)
• The runTaxDataImport utility (see page 38)
• The runTaxDataExport utility (see page 40)
• The runTaxEngineExtract utility (see page 43) for the Local Indirect Tax Engine (LITE)
deployment of Vertex Retail
• The runRetailTaxExtract utility (see page 45) for the Retail Tax Extract deployment of Vertex
Retail
• The runEUMossExtract utility (see page 47)
Before you use the Vertex Retail utilities, you need to create a Data Management filter. For
details about creating a filter, refer to the Vertex Central Online Help.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 31
 Chapter 2. O Series Client Utilities Through the Command Line

The runBatchClientInterface utility

This section tells you:
• The parameters that are associated with the runBatchClientInterface utility (see page 32)
• How to run the runBatchClientInterface utility from the command line (see page 34)
• How to manage errors when using a local database as input (see page 37)
• The limitations of Batch Client Interface processing using a local database (see page 38)

Command line parameters for the runBatchClientInterface utility

The runBatchClientInterface command line utility has both required and optional parameters.
Both short and long parameter options are provided.

User authentication parameters

The following parameters are required:
• -u <userName> or --userName <userName>
userName: This parameter is the O Series user name for authentication purposes.
• -p <password> or --password <password>
password: This parameter is the O Series user password for authentication purposes.

Input parameters
You must set one of these parameters:
• -f <inputFileName> or --inputFileName <inputFileName>
inputFileName: This parameter enables you to specify the name of the CSV file to process.
This file name must be the absolute path of the file on the client machine.
Note: Any value that you specify in this parameter overrides the value in the
transactionTableName parameter.
• -x <transactionTableName> or --transactionTableName <transactionTableName>
transactionTableName: This parameter enables you to specify the name of the database to
process.
Valid values are A-Z (uppercase alphabetic letters), a-z (lowercase alphabetic letters), 0-9
(numbers), and _ (underscores). Before performing any queries, the Batch Client Interface
utility confirms that the values in the transactionTableName are valid.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 32
 Chapter 2. O Series Client Utilities Through the Command Line

When you specify this parameter, the Batch Client Interface utility does the following:
− Processes transactionTableName.csv in the inputFileName parameter.
− Ignores the fieldDelimiter and textQualifier parameters during processing. The Batch
Client Interface uses the default values for the fieldDelimiter (COMMA) and textQualifier
(DOUBLE_QUOTE) parameters.

Transaction parameters
The following parameters are optional:
• -d <fieldDelimiter> or --fieldDelimiter <fieldDelimiter>
fieldDelimiter: This parameter enables you to define the character that you use as a
delimiter in your CSV file. For example, -d ASTERISK sets the delimiter value to an asterisk.
Valid values are COMMA (,), FORWARD_SLASH (/), ASTERISK (*), TILDE (~), SEMICOLON (;),
PIPE (|), AND CARET (^). The default value is a COMMA (,).
• -e <skipExistingDocuments> or --skipExistingDocuments <skipExistingDocuments>
skipExistingDocuments: This parameter directs the runBatchClientInterface utility to skip
transactions that have already been processed. Any transactions that already reside in the
Tax Journal are not processed.
Note: Vertex recommends that you use this -e parameter if you are processing a failed batch.
This will prevent a transaction from being processed twice.
• -l <lineItemLevelProcessing> or --lineItemLevelProcessing
<lineItemLevelProcessing>
lineItemLevelProcessing: This parameter indicates whether the runBatchClientInterface
utility should process each row as a separate transaction. The default value is false, that is,
each row is processed as a separate transaction.
• -q <quotationOnly> or --quotationOnly <quotationOnly>
quotationOnly: This parameter directs the runBatchClientInterface utility to process each
transaction as a quotation without writing the results to the Tax Journal. You can use this
parameter with any type of message. If you do not specify this parameter, the default value
is false.
• -s <startRow> or --startRow <startRow>
startRow: This parameter directs the runBatchClientInterface utility to begin processing the
data input file at a specified line. Entering a value causes processing to begin at the line
numbered one more than the specified number. For example, if you specify 16 in this
parameter, the runBatchClientInterface utility begins processing the data input file at row
17.
If you do not specify this parameter, the default value is 0 and processing begins at line 1.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 33
 Chapter 2. O Series Client Utilities Through the Command Line

• -t <textQualifier> or --textQualifier <textQualifier>

textQualifier: This parameter enables you to define the quote character that is used to
encapsulate text fields. For example, -t SINGLE_QUOTE sets the quote character to single
quote (').
Valid values are NONE, DOUBLE_QUOTE, and SINGLE_QUOTE. The default value is a
DOUBLE_QUOTE.

Testing or troubleshooting diagnostic parameters

The following parameter is optional:
• -n <documentNumberPrefix> or --documentNumberPrefix <documentNumberPrefix>
documentNumberPrefix: This parameter adds a specified string to the beginning of each
document number. This numeric prefix enables you to generate distinct transactions from
the same CSV data input file.

Running the runBatchClientInterface utility from the command line

You can run the runBatchClientInterface utility through the command line in Windows or UNIX.
The runBatchClientInterface utility performs tax calculations. This processing includes the
upload of the input CSV file or database from the client location, the tax calculation activity
itself, the download of the generated results file and, if applicable, a generated errors file to the
client location.
Complete the following steps to run the runBatchClientInterface utility from the command line:
1. Access the command line.
2. Access the directory that contains the unzipped oseries-client file.
3. Run the runBatchClientInterface script by doing one of the following:
• For Windows systems, enter runBatchClientInterface.bat -u userName -p password -f
inputFileName or -x transactionTableName
• For UNIX systems, enter runBatchClientInterface.sh -u userName -p password -f
inputFileName or -x transactionTableName
where:
userName is your Vertex O Series user name.
password is your Vertex O Series password.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 34
 Chapter 2. O Series Client Utilities Through the Command Line

Depending on the type of input you want the Batch Client Interface utility to process, specify
one of the following parameters:
inputFileName is the name of the saved CSV file to process.
or
transactionTableName is the name of the database to process.
Press Enter.
The following messages display as the Batch Client Interface utility uploads and processes the
input file or database, then downloads the results file, and, if applicable, generates the errors
file.
Depending on the type of input you are using, the Batch Client Interface utility displays one of
the following messages:
Running batch client interface for file <inputFileName>

or
Running batch client interface for file <transactionTableName>

If you are using a database as input, the Batch Client Interface utility displays an additional
message:
Exporting transaction data from table <transactionTableName> to
<inputFileName>...

The Batch Client Interface utility displays the following messages as it uploads and processes
your input and downloads the tax calculation results:
Uploading <inputFileName>
Upload complete.
Running batch client interface...
Batch Client Interface activity completed with status <message>.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 35
 Chapter 2. O Series Client Utilities Through the Command Line

Valid status messages include the following:

• RUNNING
• COMPLETED SUCCESSFULLY
• COMPLETED WITH WARNING
• COMPLETED WITH FAILURE
Downloading results file to <resultsFileName>
Download complete.
Downloading errors file to <errorsFileName>
Download complete.

When the Batch Client Interface utility updates the database with the calculated results, the
following message displays:
Updating table <transactionTableName> with transaction results.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 36
 Chapter 2. O Series Client Utilities Through the Command Line

Managing errors for Batch Client Interface processing when using a

local database as input
When using a local database as input, Batch Client Interface processing errors may occur. For
details on types of errors and how to address them, review the table below:
If a Batch Client
Interface processing O Series... To correct this error,
error occurs...
While the Batch Client Does not write Re‐run the Batch Client Interface
Interface exports information to the O command line utility.
transaction data from Series database.
the local database.
While the Batch Client Does not write Re‐run the Batch Client Interface
Interface transfers the information to the O command line utility.
CSV file from local Series database.
database to the remote
server.
While the Batch Client May record some Re‐run the Batch Client Interface
Interface processes transactions in Vertex input file using the
transactions. O Series Tax Journal. ‐e skipExistingDocuments
parameter. Also, run the Tax
Journal Data Extract template to
determine the transactions that
were recorded in the Vertex O
Series Tax Journal.
And the Batch Client May record some Re‐run the Batch Client Interface
Interface cannot transfer transactions in Vertex input file using the
calculation results back O Series Tax Journal. ‐e skipExistingDocument
to the local client. parameter. Also, run the Tax
Journal Data Extract template to
determine the transactions that
were recorded in the Vertex O
Series Tax Journal.
While the Batch Client May have irregular Synchronize your local database
Interface uploads the results. with the results of the
local database with downloaded Batch Client
transaction results. Interface file.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 37
 Chapter 2. O Series Client Utilities Through the Command Line

Limitation of Batch Client Interface processing using a local

database
In On-Premise Vertex O Series, you can perform batch processing when the Batch Client
Interface utility uses a local database as input.
In On-Demand Vertex O Series, you cannot perform batch processing when the Batch Client
Interface utility uses a local database as input.

The runTaxDataImport utility

This section tells you:
• The parameters that are associated with the runTaxDataImport utility (see page 38)
• How to run the runTaxDataImport utility from the command line (see page 39)

Command line parameters for the runTaxDataImport utility

The runTaxDataImport command line utility has both required and optional parameters. Both
short and long parameter options are provided.

User authentication parameters

The following parameters are required:
• -u <userName> or --userName <userName>
userName: This parameter is the O Series user name for authentication purposes.
• -p <password> or --password <password>
password: This parameter is the O Series user password for authentication purposes.

Input file parameter

The following parameter is required:
• -l <importFileName> or --importFileName <importFileName>
importFileName: This parameter enables you to specify the local file name for the tax data
import file that is uploaded to the remote O Series server. This file name must be the
absolute path of the file on the client machine.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 38
 Chapter 2. O Series Client Utilities Through the Command Line

Transaction parameters
The following parameter is required:
• -d <fieldDelimiter> or --fieldDelimiter <fieldDelimiter>
fieldDelimiter: This parameter enables you to define the character that you use as a
delimiter in your tax data import file. For example, -d ASTERISK sets the delimiter value to
an asterisk. Valid values are COMMA (,), FORWARD_SLASH (/), ASTERISK (*), TILDE (~),
SEMICOLON (;), PIPE (|), AND CARET (^). The default value is a COMMA (,).
The following parameter is optional:
• -c <importIntoCurrentPartition> or --importIntoCurrentPartition
<importIntoCurrentPartition>
importIntoCurrentPartition: This parameter enables you to determine whether the tax data
import file is imported into the partition that is associated with the O Series user running the
Tax Data Import utility, instead of the partition specified in the tax data import file. If you do
not specify a value for this parameter, Vertex O Series imports the tax data import file into
the partition specified in the tax data import file.

Running the runTaxDataImport utility from the command line

You can run the runTaxDataImport utility through the command line in Windows or UNIX. The
runTaxDataImport utility performs a Tax Data import activity and uploads the import file to the
remote Vertex O Series server.
Complete the following steps to run the runTaxDataImport utility from the command line:
1. Access the command line.
2. Access the directory that contains the unzipped oseries-client file.
3. Run the runTaxDataImport script by doing one of the following:
• For Windows systems, enter runTaxDataImport.bat -u userName -p password -l
importFileName -d fieldDelimiter
• For UNIX systems, enter runTaxDataImport.sh -u userName -p password -l
importFileName -d fieldDelimiter
where:
userName is your Vertex O Series user name.
password is your Vertex O Series password.
importFileName is the name of the local tax data import file.
fieldDelimiter is the value that separates each field.
Press Enter.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 39
 Chapter 2. O Series Client Utilities Through the Command Line

The following messages display as the utility imports the tax data file and uploads the import file
to the remote Vertex O Series server:
Running tax data import for file <importFileName>
Uploading <importFileName>
Upload complete.
Running tax data import ...
Tax data import activity submitted with activity id <id>.
Tax data import activity completed with status <statusName>.

Valid status messages include the following:

• RUNNING
• COMPLETED SUCCESSFULLY
• COMPLETED WITH WARNING
• COMPLETED WITH FAILURE

The runTaxDataExport utility

This section tells you:
• The parameters that are associated with the runTaxDataExport utility (see page 40)
• How to run the runTaxDataExport utility from the command line (see page 42)

Command line parameters for the runTaxDataExport utility

The runTaxDataExport command line utility has both required and optional parameters. Both
short and long parameter options are provided.

User authentication parameters

The following parameters are required:
• -u <userName> or --userName <userName>
userName: This parameter is the O Series user name for authentication purposes.
• -p <password> or --password <password>
password: This parameter is the O Series user password for authentication purposes.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 40
 Chapter 2. O Series Client Utilities Through the Command Line

Input file parameter

The following parameter is required:
• -l <exportFileName> or --exportFileName <exportFileName>
exportFileName: This parameter enables you to specify the local file name to assign to the
tax data export file that is downloaded from the remote O Series server. This file name must
be the absolute path of the file on the client machine.

Transaction parameters
The following parameters are optional:
• -c <taxpayerCompanyCode> or --taxpayerCompanyCode <taxpayerCompanyCode>
taxpayerCompanyCode: This parameter enables you to define the company-level taxpayer
code.
• -d <fieldDelimiter> or --fieldDelimiter <fieldDelimiter>
fieldDelimiter: This parameter enables you to define the character that you use as a
delimiter in your tax data export file. For example, -d ASTERISK sets the delimiter value to
an asterisk. Valid values are COMMA (,), FORWARD_SLASH (/), ASTERISK (*), TILDE (~),
SEMICOLON (;), PIPE (|), AND CARET (^). The default value is a COMMA (,).
• -e <endDate> or --endDate <endDate>
endDate: This parameter enables you to define the end date of the effective date range for
the tax data being exported.
• -i <taxpayerDivisionCode> or --taxpayerDivisionCode <taxpayerDivisionCode>
taxpayerDivisionCode: This parameter enables you to define the division-level taxpayer
code.
• -n <targetPartitionName> or --targetPartitionName <targetPartitionName>
targetPartitionName: This parameter enables you to specify the name of the partition in
which to export tax data.
• -r <recordType> or --recordType <recordType>
recordType: This parameter enables you to specify the type of data that you want to export.
Valid values are CERTIFICATE, CUSTOMER, FLEX_FIELDS_DEFINITIONS, FORM,
SITUS_TREATMENT_RULE, TAX_ASSIST_ALLOCATION_TABLE, TAX_ASSIST_LOOKUP_TABLE,
TAX_ASSIST_RULE, TAX_RULE, TAXABILITY_CATEGORY, TAXABILITY_CATEGORY_MAPPING,
TAXABILITY_DRIVER, TAXABILITY_MAPPING, TAXPAYER, and VENDOR. If you do not specify a
value for this parameter, Vertex O Series defaults to include all values.
• -s <startDate> or --startDate <startDate>
startDate: This parameter enables you to define the start date of the effective date range for
the tax data being exported.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 41
 Chapter 2. O Series Client Utilities Through the Command Line

• -t <taxpayerDepartmentCode> or --taxpayerDepartmentCode
<taxpayerDepartmentCode>
taxpayerDepartmentCode: This parameter enables you to define the department-level
taxpayer code.

Running the runTaxDataExport utility from the command line

You can run the runTaxDataExport utility through the command line in Windows or UNIX. The
runTaxDataExport utility performs a Tax Data export activity and downloads the export file to
your local machine.
Complete the following steps to run the runTaxDataExport utility from the command line:
1. Access the command line.
2. Access the directory that contains the unzipped oseries-client file.
3. Run the runTaxDataExport script by doing one of the following:
• For Windows systems, enter runTaxDataExport.bat -u userName -p password -l
exportFileName
• For UNIX systems, enter runTaxDataExport.sh -u userName -p password -l
exportFileName
where:
userName is your Vertex O Series user name.
password is your Vertex O Series password.
exportFileName is the name of the local file to assign to the downloaded tax data export
file.
Press Enter.
The following messages display as the utility exports the tax data file and downloads the export
file to your local machine:
Running tax data export...
Tax data export activity submitted with activity id <id>.
Tax data export activity completed with status <statusName>.

Valid status messages include the following:

• RUNNING
• COMPLETED SUCCESSFULLY
• COMPLETED WITH WARNING
• COMPLETED WITH FAILURE
Downloading export file to <exportFileName>.
Download completed.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 42
 Chapter 2. O Series Client Utilities Through the Command Line

The runTaxEngineExtract utility

This section tells you:
• The parameters that are associated with the runTaxEngineExtract utility (see page 43)
• How to run the runTaxEngineExtract utility from the command line (see page 44)

Command line parameters for the runTaxEngineExtract utility

The following runTaxEngineExtract command line parameters are required. Both short and long
parameter options are provided.

User authentication parameters

The following parameters are required:
• -u <userName> or --userName <userName>
userName: This parameter is the O Series user name for authentication purposes.
• -p <password> or --password <password>
password: This parameter is the O Series user password for authentication purposes.

Input file parameters

The following parameters are required:
• -f <filterName> or --filterName <filterName>
filterName: This parameter enables you to specify the name of the Tax Engine Extract filter
to be run.
• -l <localUpdateFileName> or --localUpdateFileName <localUpdateFileName>
localUpdateFileName: This parameter enables you to specify the local file name to assign to
the downloaded Tax Engine Extract update file.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 43
 Chapter 2. O Series Client Utilities Through the Command Line

Running the runTaxEngineExtract utility from the command line

You can run the runTaxEngineExtract utility through the command line in Windows or UNIX. Use
this utility to perform a Tax Engine Extract if you have a Local Indirect Tax Engine (LITE)
deployment of Vertex Retail. Make sure you have created a Data Management filter through
System > Data Management in Vertex Central before you run the runTaxEngineExtract.

Complete the following steps to run the runTaxEngineExtract utility from the command line:
1. Access the command line.
2. Access the directory that contains the unzipped oseries-client file.
3. Run the runTaxEngineExtract script by doing one of the following:
• For Windows systems, enter runTaxEngineExtract.bat -u userName -p password -f
filterName -l localUpdateFileName
• For UNIX systems, enter runTaxEngineExtract.sh -u userName -p password -f
filterName -l localUpdateFileName
where:
userName is your Vertex O Series user name.
password is your Vertex O Series password.
filterName is the name of the saved Data Management activity filter you created.
localUpdateFileName is the local file name to assign to the downloaded Tax Engine Extract
update file.
Press Enter.
The following messages display as the utility performs the extract and then downloads the
update file to your local machine:
Running tax engine extract for filter <filterName>
Tax Engine Extract activity completed with status <message>.

Valid status messages include:

• RUNNING
• COMPLETED SUCCESSFULLY
• COMPLETED WITH WARNING
• COMPLETED WITH FAILURE
If the Tax Engine Extract fails, the utility does not download a file and the following error
message displays:
Issues running Tax Engine Extract activity, stopping...
Otherwise, the following messages display:
Downloading update file to <localUpdateFileName>
Download complete.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 44
 Chapter 2. O Series Client Utilities Through the Command Line

The runRetailTaxExtract utility

This section tells you:
• The parameters that are associated with the runRetailTaxExtract utility (see page 45)
• How to run the runRetailTaxExtract utility from the command line (see page 46)
• How to manipulate Retail Tax Extract data (see page 47)
• How to retrieve the Retail XML Schema file (see page 47)

Command line parameters for the runRetailTaxExtract utility

The following runRetailTaxExtract command line parameters are required. Both short and long
parameter options are provided.

User authentication parameters

The following parameters are required:
• -u <userName> or --userName <userName>
userName: This parameter is the O Series user name for authentication purposes.
• -p <password> or --password <password>
password: This parameter is the O Series user password for authentication purposes.

Input file parameters

The following parameters are required:
• -f <filterName> or --filterName <filterName>
filterName: This parameter enables you to specify the name of the Retail Tax Extract filter to
be run.
• -l <localExtractFileName> or --localExtractFileName <localExtractFileName>
localExtractFileName: This parameter enables you to specify the local file name to assign
to the downloaded Retail Tax Extract file.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 45
 Chapter 2. O Series Client Utilities Through the Command Line

Running the runRetailTaxExtract utility from the command line

You can perform the runRetailTaxExtract utility through the command line in Windows or UNIX.
Use this utility to perform a Retail Tax Extract if you have a Retail Tax Extract deployment of
Vertex Retail. Make sure that you have created a Data Management filter through System >
Data Management in Vertex Central before you run the runRetailTaxExtract.

Complete the following steps to run the runRetailTaxExtract utility from the command line:
1. Access the command line.
2. Access the directory that contains the unzipped oseries-client file.
3. Run the runRetailTaxExtract script by doing one of the following:
• For Windows systems, enter runRetailTaxExtract.bat -u userName -p password -f
filterName -l localExtractFileName
• For UNIX systems, enter runRetailTaxExtract.sh -u userName -p password -f
filterName -l localExtractFileName
where:
userName is your Vertex O Series user name.
password is your Vertex O Series password.
filterName is the name of the saved Data Management activity filter you created.
localExtractFileName is the local file name to assign to the downloaded Retail Tax Extract
file.
Press Enter.
The following messages display as the utility performs the extract activity and then downloads
the extract file to your local machine:
Running Retail Tax Extract for filter <filterName>
Retail Tax Extract activity completed with status <message>.

Valid status messages include:

• RUNNING
• COMPLETED SUCCESSFULLY
• COMPLETED WITH WARNING
• COMPLETED WITH FAILURE
Note: If the Retail Tax Engine Extract fails, the utility does not download a file and the following
error message displays:
Issues running Retail Tax Extract activity, stopping...

Otherwise, the following messages display:

Downloading extract file to <localExtractFileName>
Download complete.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 46
 Chapter 2. O Series Client Utilities Through the Command Line

Manipulating Retail Tax Extract data by using the O Series Client

Utilities
If you want to manipulate the Retail Tax Extract data on your local machine, select the Generate
Database Export check box when you create a Retail Tax Extract filter through System > Data
Management in Vertex Central.

The Generate Database Export check box enables you to export the data in the Retail Tax
Extract database as a ZIP file. This file contains tilde (~)-delimited files for each database table.
You can then load this file into another database, such as Oracle or SQL, to manipulate and
extract the appropriate data as needed.
Select Include Date Time Stamp to automatically append a date and time stamp to the file name.

Retrieve the Retail XML Schema file

If you selected both the Generate Retail XML Schema check box and Generate Database Export
check box when you created a filter for a Retail Tax Extract, you need to perform an additional
step to retrieve the generated Retail XML Schema file.
To retrieve the generated Retail XML Schema file, use the getFile utility (see page 57) to
download the file from the server to your local machine.
You do not have to do anything special to retrieve the generated database ZIP file. This file is
downloaded from the O Series remote server to your local machine as part of the
runRetailTaxExtract utility.

The runEUMossExtract utility

This section tells you the following:
• The parameters that are associated with the runEUMossExtract utility (see page 47)
• How to run the runEUMossExtract utility from the command line (see page 49)
For more details about EU MOSS, refer to the EU Mini One Stop Shop in O Series Guide.

Command line parameters for the runEUMossExtract utility

The runEUMossExtract command line utility has both required and optional parameters. Both
short and long parameter options are provided.

User authentication parameters

The following parameters are required:
• -u <userName> or --userName <userName>
userName: This parameter is the O Series user name for authentication purposes.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 47
 Chapter 2. O Series Client Utilities Through the Command Line

• -p <password> or --password <password>

password: This parameter is the O Series user password for authentication purposes.

Transaction parameters
The following parameters are required:
• -d <exchangeRateDate> or --exchangeRateDate <exchangeRateDate>
exchangeRateDate: This parameter enables you to set the date for currency conversion
(yyyy-MM-dd).
• -e <endDate> or --endDate <endDate>
endDate: This parameter enables you to set the posting end date of the data to be extracted
(yyyy-MM-dd).
• -r <exchangeRatesFileName> or --exchangeRatesFileName <exchangeRatesFileName>
exchangeRatesFileName: This parameter enables you to identify the name of the exchange
rates file. This file is in .csv format.
• -s <startDate> or --startDate <startDate>
startDate: This parameter enables you to set the posting start date of the data to be
extracted (yyyy-MM-dd).
• -x <extractFileName> or --extractFileName <extractFileName>
extractFileName: This parameter enables you to identify the name of the EU MOSS extract
file. This file is in .csv format.
The following parameter is optional:
• -t <taxpayers> or --taxpayers <taxpayers>
taxpayers: This parameter enables you to identify the taxpayers for which the data is
extracted. Taxpayers are delimited by commas (,). Company Code, Division Code, and
Department Code are delimited by a colon (:).
Example: -t ABCCorporation::,DEFCorporation:LosAngeles:Department12

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 48
 Chapter 2. O Series Client Utilities Through the Command Line

Running the runEUMossExtract utility from the command line

You can run the runEUMossExtract utility through the command line in Windows or UNIX. The
runEUMossExtract utility uploads the Exchange Rates File, performs an EU MOSS Extract
activity, and downloads the extract file and extract detail file from the remote Vertex O Series
server.
Complete the following steps to perform an EU MOSS Extract:
1. Access the command line.
2. Access the directory that contains the unzipped oseries-client file.
3. Run the runEUMossExtract script by doing one of the following:
• For Windows systems, enter runEUMossExtract.bat -u userName -p password -s
startDate -e endDate -d exchangeRateDate -r exchangeRatesFileName -x
extractFileName
• For UNIX systems, enter runEUMossExtract.sh -u userName -p password -s startDate -
e endDate -d exchangeRateDate -r exchangeRatesFileName -x exchangeFileName
where:
userName is your Vertex O Series user name.
password is your Vertex O Series password.
startDate is the posting start date of the data to be extracted (yyyy-MM-dd).
endDate is the posting end date of the data to be extracted (yyyy-MM-dd).
exchangeRateDate is the date for currency conversion (yyyy-MM-dd).
exchangeRatesFileName is the name of the exchange rates file.
extractFileName is the name of the extract file.
Press Enter.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 49
 Chapter 2. O Series Client Utilities Through the Command Line

The runEUMossExtract utility displays the following messages as it uploads the Exchange Rates
file:
Uploading exchange rates file <exchangeRatesFileName>
Upload complete.

The runEUMossExtract utility displays the following messages as it submits, processes, and
completes the extract. It also displays the status of the completed extract activity.
Running EU MOSS extract...
EU MOSS extract activity submitted with activity id <id>.
EU MOSS extract activity status:<status>
EU Moss extract activity completed with status <statusName>

Valid status messages include the following:

• RUNNING
• COMPLETED SUCCESSFULLY
• COMPLETED WITH WARNING
• COMPLETED WITH FAILURE
The runEUMossExtract utility displays the following messages as it downloads the extract file:
Downloading extract file to <extractFileName>
Download complete.

The runEUMossExtract utility displays the following messages as it downloads the extract detail
file:
Downloading extract detail file to <extractDetailFileName>
Download complete.

Data Extract command line utilities

The Data Extract utilities available through the command line enable you to perform a Data
Extract in Windows or UNIX:
Before you use these utilities, you must create a Data Extract definition. For details on creating a
definition, refer to the Vertex Central Online Help.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 50
 Chapter 2. O Series Client Utilities Through the Command Line

The runDataExtract utility

This section tells you:
• The parameters that are associated with the runDataExtract utility (see page 51)
• How to run the runDataExtract utility from the command line (see page 52)

Command line parameters for the runDataExtract utility

The runDataExtract command line utility has both required and optional parameters. Both short
and long parameter options are provided.

User authentication parameters

The following parameters are required:
• -u <userName> or --userName <userName>
userName: This parameter is the O Series user name for authentication purposes.
• -p <password> or --password <password>
password: This parameter is the O Series user password for authentication purposes.

Input parameters
The following parameter is required:
• -n <extractName> or --extractName <extractName>
extractName: This parameter enables you to specify the name of the data extract to run.

Transaction parameters
The following parameters are optional:
• -l <localFileName> or --localFileName <localFileName>
localFileName: This parameter enables you to specify the local file name to assign to the
downloaded Data Extract results file. This file can be in any format that is supported by Data
Extract in Vertex O Series. This parameter can include an absolute path. If you do not specify
an absolute path for this parameter, this utility downloads this file, by default, to the
oseries-client-utilities/bin directory on your local machine.

• <filterValue1...N>
filterValue1...N: These parameters enable you to specify values for the filters that you
defined when creating the Data Extract definition. The filter values that you enter on the
command line override the values that you entered when creating the Data Extract
definition. The number of filter values that you specify on the command line must be less
than or equal to the number of filter values that you defined in the Data Extract definition.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 51
 Chapter 2. O Series Client Utilities Through the Command Line

Running the runDataExtract utility from the command line

You can run the runDataExtract utility through the command line in Windows or UNIX. The
runDataExtract utility performs a data extract and downloads the data extract results file to the
client location.
Complete the following steps to run the runDataExtract utility from the command line:
1. Access the command line.
2. Access the directory that contains the unzipped oseries-client file.
3. Run the runDataExtract script by doing one of the following:
• For Windows systems, enter runDataExtract.bat -u userName -p password -n
extractName
[-l localFileName][filterValue1][filterValue2]…[filterValueN]
• For UNIX systems, enter runDataExtract.sh -u userName -p password -n extractName
[-l localFileName][filterValue1][filterValue2]…[filterValueN]
where:
userName is your Vertex O Series user name.
password is your Vertex O Series password.
extractName is the name of the data extract to run.
[localFileName] is the local file name to assign to the downloaded Data Extract results
file.
[filterValue1][filterValue2]...[filterValueN] are the values for the filters that you
defined when creating the Data Extract definition.
Press Enter.
The following messages display as the utility performs a data extract and then downloads the
results file:
Running data extract for filter <extractName>
Data extract completed with status <message>.

Valid status messages include the following:

• RUNNING
• COMPLETED SUCCESSFULLY
• COMPLETED WITH WARNING
• COMPLETED WITH FAILURE
Downloading results file to <extractName>
Download complete.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 52
 Chapter 2. O Series Client Utilities Through the Command Line

File Transfer command line utilities

The File Transfer utilities available through the command line enable you to perform file
transfer activities in Windows or UNIX. These activities include moving files between the O
Series server and your local client.
Note: When you perform Data Management activities through the command line, the File
Transfer steps are performed as part of the Data Management processing, so you do not
need to perform the File Transfer steps separately.
If you want to perform a file transfer unrelated to Data Management activities, you can run
these file transfer utilities separately:
• putFile (see page 53) utility (File upload)
• getFile (see page 55) utility(File download)

The putFile utility

This section tells you:
• The parameters that are associated with the putFile utility (see page 53)
• How to run the putFile utility through the command line (see page 54)

Command line parameters for the putFile utility

The putFile command line utility has both required and optional parameters. Both short and
long parameter options are provided.

User authentication parameters

The following putFile command line parameters are required:
• -u <userName> or --userName <userName>
userName: This parameter is the O Series user name for authentication purposes.
• -p <password> or --password <password>
password: This parameter is the O Series user password for authentication purposes.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 53
 Chapter 2. O Series Client Utilities Through the Command Line

Input file parameters

The following putFile command line parameters are required:
• -l <localFileName> or --localFileName <localFileName>
localFileName: This parameter enables you to specify the name of the file to upload.
• -d <remoteDirectoryName> or --remoteDirectoryName <remoteDirectoryName>
remoteDirectoryName: This parameter enables you to specify the logical directory on the
remote O Series server in which to upload the file.
Valid values are BATCH_CLIENT_INTERFACE, EU_MOSS_EXTRACT, RETAIL_JOURNAL,
RETAIL_STATUS, and TAX_DATA_IMPORT.

Other putFile parameters

The following putFile command line parameters are optional:
• -r <remoteFileName> or --remoteFileName <remoteFileName>
remoteFileName: This parameter enables you to specify the name of the file to create on
the remote O Series server. If you do not specify this parameter, the default value is the
same as the localFileName.
• -z <zip> or --zip <zip>
zip: This parameter enables you to zip your local file before Vertex O Series uploads it to the
Vertex O Series server. The file on your local computer, by default, is not a zipped file. If you
specify this parameter but do not specify a remoteFileName, Vertex O Series appends a
.zip extension to the uploaded file name. If you specify this parameter and a
remoteFileName, Vertex O Series provides a .zip extension to remoteFileName.

Running the putFile utility through the command line

You can run the putFile utility through the command line in Windows or UNIX. Use this utility to
perform a file upload from a local computer to the O Series server.
Note: When you perform Data Management activities through the command line, the File
Transfer steps are performed as part of the Data Management processing. You do not
need to perform the File Transfer separately for a Data Management activity.
Complete the following steps to run the putFile utility from the command line:
1. Access the command line.
2. Access the directory that contains the unzipped oseries-client file.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 54
 Chapter 2. O Series Client Utilities Through the Command Line

3. Run the putFile script by doing one of the following:

• For Windows systems, enter putFile.bat -u userName -p password -l localFileName
-d remoteDirectoryName -r remoteFileName

• For UNIX systems, enter putFile.sh -u userName -p password -l localFileName -d

remoteDirectoryName -r remoteFileName
where:
userName is your Vertex O Series user name.
password is your Vertex O Series password.
localFileName is the name of the file to upload.
remoteDirectoryName is the name of the directory where the file should be created on the
remote O Series server.
remoteFileName is the name of the file to create on the remote O Series server.
Press Enter.
The following initial message displays as the utility uploads the remote file to the O Series
server:
Uploading file <localFileName> to <remoteFileName>

While the file is uploading, the following message displays:

Uploaded <totalBytesTransferred> of <fileSize> bytes (<percentComplete>%
complete).

After the entire file has been uploaded, the following message displays:
Upload complete.

The getFile utility

This section tells you:
• The parameters that are associated with the getFile utility (see page 56)
• How to run the getFile utility through the command line (see page 57)

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 55
 Chapter 2. O Series Client Utilities Through the Command Line

Command line parameters for the getFile utility

The getFile command line utility has both required and optional parameters. Both short and
long parameter options are provided.

User authentication parameters

The following getFile command line parameters are required:
• -u <userName> or --userName <userName>
userName: This parameter is the O Series user name for authentication purposes.
• -p <password> or --password <password>
password: This parameter is the O Series user password for authentication purposes.

Remote file parameters

The following getFile command line parameters are required:
• -d <remoteDirectoryName> or --remoteDirectoryName <remoteDirectoryName>
remoteDirectoryName: This parameter enables you to specify the logical directory on the
remote O Series server where the file to be downloaded resides.
Valid values are BATCH_CLIENT_INTERFACE, DATA_EXTRACT, EU_MOSS_EXTRACT,
RETAIL_TAX_EXTRACT, RETURNS_EXPORT, TAX_DATA_EXPORT, TAX_ENGINE_EXTRACT,
STANDARD_AUDIT_FILE, and VAT_RETURNS_EXPORT.
• -r <remoteFileName> or --remoteFileName <remoteFileName>
remoteFileName: This parameter enables you to specify the name of the remote file to
download.

Other getFile parameters

The following getFile command line parameters are optional:
• -l <localFileName> or --localFileName <localFileName>
localFileName: This parameter enables you to specify the local file name to assign to the
downloaded file. If you do not specify this parameter, the default value is the same as the
remoteFileName.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 56
 Chapter 2. O Series Client Utilities Through the Command Line

Note: You can specify the complete local directory path for this file or only a file name. If you
specify only a file name, the getFile utility downloads the file into the current directory
where the utility resides.
• -z <zip> or --zip <zip>
zip: This parameter enables you to zip your remote file before Vertex O Series downloads it
to your local computer. The file on your Vertex O Series server, by default, is not a zipped
file. If you specify this parameter but do not specify a localFileName, Vertex O Series
appends a .zip extension to the downloaded localFileName. If you specify this parameter
and a localFileName, Vertex O Series provides a .zip extension to localFileName.

Running the getFile utility from the command line

You can run the getFile utility through the command line in Windows or UNIX. Use this utility to
perform a file download from the remote O Series server.
Note: When you perform Data Management activities through the command line, the File
Transfer steps are performed as part of the Data Management processing. As a result,
you do not need to perform the File Transfer separately for a Data Management activity.
Complete the following steps to run the getFile utility from the command line:
1. Access the command line.
2. Access the directory that contains the unzipped oseries-client file.
3. Run the getFile script by doing one of the following:
• For Windows systems, enter getFile.bat -u userName -p password -d
remoteDirectoryName -r remoteFileName
• For UNIX systems, enter getFile.sh -u userName -p password -d remoteDirectoryName
-r remoteFileName
where:
userName is your Vertex O Series user name.
password is your Vertex O Series password.
remoteDirectoryName is the name of the directory where the file to download resides on
the remote O Series server.
remoteFileName is the name of the file to download from the remote O Series server.
Press Enter.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 57
 Chapter 2. O Series Client Utilities Through the Command Line

The following initial message displays as the utility downloads the remote file to your local
machine:
Downloading file <remoteFileName> to <localFileName>

While the file is downloading, the following message displays:

Downloaded <totalBytesTransferred> of <fileSize> bytes (<percentComplete>%
complete).

After the entire file has been downloaded, the following message displays:
Download complete.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 58
Chapter 3. O Series Client Utilities
Through Web Services
The O Series Client Utilities web services include Data Management, Data Extract, File Transfer,
and Security Services. These services enable you to do the following:
• Generate XML messages that are used to perform Data Management and Data Extract
activities and the associated file transfer tasks.
• Remotely create users and partitions.
This chapter includes a procedure to connect to the WSDL endpoint, information about each
web service, and where to find annotated schema documentation. This documentation can help
you understand the required data elements in the web service request and response messages.

In this chapter
Connecting to the WSDL endpoint ...............................................59
Where to find annotated schema documentation .......................60
Data Management web services ..................................................61
Data Extract web services.............................................................62
File Transfer web services ............................................................62
Security Services web services .....................................................65

Connecting to the WSDL endpoint

Complete the following steps to access the WSDL endpoint for each O Series Client Utilities web
service:
1. Type http://<server>:<port>/vertex-remote-services/ in your Internet browser:
where:
server is the name of the server that directs you to the Vertex O Series web services page.
port is the name of the connection port for the Vertex O Series web services page.
Type the server and port names that you specified in the WebServiceURL parameter in the
oseries-client.properties file. For details, refer to the oseries-client.properties file for
configuration parameters (see page 27).
2. Press Enter.
The Vertex O Series web services page displays.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 59
 Chapter 3. O Series Client Utilities Through Web Services

3. Click View the list of deployed Vertex O Series web services and their Endpoints.
A list of Vertex O Series web services displays, with a brief description and the WSDL
endpoint for each web service.
4. Select the O Series Client web service you want to use:
• Data Management web services (see page 61)
• Data Extract web services (see page 62)
• File Transfer web services (see page 62)
• Security Services web services (see page 65)
5. Point the SOAP toolkit to the WSDL endpoint for the web service you selected to create a
SOAP Request message for the host application.

Where to find annotated schema

documentation
Vertex provides annotated schema documentation in HTML format for your reference. This
schema documentation can help you understand the required data elements in the web service
request and response messages.
The annotated schema documentation is included in the Vertex Oseries ClientUtilities.zip file:
• If you have an On-Demand environment (client-side using hosted Vertex O Series), you can
access a link to the Vertex Oseries v9 ClientUtilities.zip file in the Client Tools section that is
on the O Series landing page.
• If you have an On-Premise environment (server-side Vertex O Series), you can access the
Vertex Oseries v9 ClientUtilities.zip file on the myVertex customer portal
(https://vertexinc.custhelp.com).

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 60
 Chapter 3. O Series Client Utilities Through Web Services

Data Management web services

The Data Management web services enable you to perform Data Management activities
remotely. These web services include the following:
• RunBatchClientInterface
Note: You cannot run the Batch Client Interface utility when using a database as input through
web services.
• RunEUMossExtract
• RunRetailTaxExtract for the Retail Tax Extract deployment of Vertex Retail
• RunTaxDataExport
• RunTaxDataImport
• RunTaxEngineExtract for the Local Indirect Tax Engine (LITE) deployment of Vertex Retail
• RunTaxJournalExport (can be run only through a web service)
Note: The RunTaxJournalExport Request message may create one or multiple Tax Journal
Export files, depending on how you seqment the export file size.
• GetActivityStatus to retrieve the status of a Data Management activity
Before you use the Vertex Retail web services, you must create a Data Management filter. You
can create a new Data Management filter through Vertex Central. For details about creating a
filter, refer to the Vertex Central Online Help.
For details about these web services, refer to the annotated schema documentation (see page
60).

Can I access a local Batch Client Interface database using

the Batch Client Interface web service?
The O Series Client Utilities cannot access a local Batch Client Interface database through a web
service. You can run Batch Client Interface processing using a local database as input through
the command line only. For details, refer to Running the runBatchClientInterface utility from the
command line (see page 34).

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 61
 Chapter 3. O Series Client Utilities Through Web Services

Data Extract web services

The Data Extract web services enable you to perform Data Extract activities remotely. These
web services include the following:
• RunDataExtract
• GetExtractStatus to retrieve the current status of a Data Extract
Before you use the RunDataExtract web service, you must create a Data Extract definition for
your Data Extract. You can create a new data extract definition through Vertex Central. For
details about creating a Data Extract definition, refer to the Vertex Central Online Help.
For details about these web services, refer to the annotated schema documentation (see page
60).

File Transfer web services

The File Transfer web services enable you to perform file transfer activities between the O
Series server and your local client. These web services include the following:
• GetFile (file download)
• PutFile (file upload)
Note: To limit the access to the directories that are under the vertexroot/data folder, you
cannot use relative path characters (., /, \) in the directories that you specify when
using the GetFile and PutFile web services.
For details about these web services, refer to the annotated schema documentation (see page
60).

How uploading status files from a Vertex Retail Local Indirect

Tax Engine (LITE) deployment to a Vertex Central
deployment works
If you have a Vertex Retail LITE deployment and want to upload the status files from your
location to a Vertex Central location, use the putFile utility with the <remoteDirectoryName>
parameter (see page 53). The RETAIL_STATUS value for this parameter enables you to upload
these status files to a Vertex Central location. After you upload these status files, you can
successfully run the Data Extract Retail Location Status report.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 62
 Chapter 3. O Series Client Utilities Through Web Services

How retrieving files from Batch Client Interface processing

works
If you are writing your own client by calling the web services directly, use the GetFile utility to
download the Batch Client Interface processing results file and errors file from the Vertex O
Series server to your local machine. Before you can do this, you need to understand the
following:
1. How the Batch Client Interface directory structure (see page 63) impacts file retrieval
2. How file movement during Batch Client Interface processing (see page 64) impacts file
retrieval
3. How to specify the ResultsFileName and ErrorsFileName values that are returned by the
RunBatchClientInterfaceResponse XML message as input in the GetFile utility (see page 64)

Directories for generated Batch Client Interface files

Vertex O Series identifies each Data Management activity by a unique numeric identifier
(Activity Log Id). The Activity Log Id identifies each Data Management job.
The files that Vertex O Series generates during a Batch Client Interface activity are located in the
Vertex Home/data/bci directory, in a sub-directory identified by the Activity Log Id. For
example:
Vertex Home/data/bci/<Activity Log Id>

where:
<Activity Log Id> is the directory that contains the results and errors files from the
processing that is associated with that specific Batch Client Interface job.
The Activity Log Id is returned by the RunBatchClientInterfaceResponse XML message.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 63
 Chapter 3. O Series Client Utilities Through Web Services

Stages of file movement during Batch Client Interface processing

and file retrieval activities
To retrieve the results and errors files from Batch Client Interface processing, you must
understand the exchange of files between the client location and the O Series server. You need
to know the specific file names from Batch Client Interface processing to use in the GetFile
utility.
Review the following stages of file movement:
1. Use the PutFile utility to upload the input CSV file from your local computer to the O Series
server.
2. Use the RunBatchClientInterface utility to use the uploaded CSV file as input for Batch Client
Interface processing. Batch Client Interface processing calculates tax and generates a results
file and, if applicable, an errors file.
3. Use the GetFile Utility to retrieve the files that were generated by Batch Client Interface
processing. For details, refer to Guideline: Use the ResultsFileName and ErrorsFileName
values returned by the RunBatchClientInterfaceResponse XML message as input in the
GetFile utility (see page 64).

Guideline: Use the ResultsFileName and ErrorsFileName values

returned by the RunBatchClientInterfaceResponse XML message as
input in the GetFile utility
Use the ResultsFileName and ErrorsFileName values returned by the
RunBatchClientInterfaceResponse XML message as input in the GetFile utility.

How the Batch Client Interface ResultsFileName relates to the GetFile utility
To retrieve the results file from Batch Client Interface processing, use the value from the
ResultsFileName data element as the value for the RemoteFileName in the GetFile utility. This
file name must be prefaced by Activity Log Id directory, such as
<Activity Log Id>/ResultsFileName
where:
<Activity Log Id> is the unique identifier for each Data Management activity.
ResultsFileName is the results file returned in the RunBatchClientInterfaceResponse XML
message.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 64
 Chapter 3. O Series Client Utilities Through Web Services

How the Batch Client Interface ErrorsFileName relates to the GetFile utility
To retrieve the errors file from Batch Client Interface processing, use the value from the
ErrorsFileName data element as the value for the RemoteFileName in the GetFile utility. This file
name must be prefaced by Activity Log Id directory, such as
<Activity Log Id>/ErrorsFileName
where:
<Activity Log Id> is the unique identifier for each Data Management activity.
ErrorsFileName is the errors file that was returned in the
RunBatchClientInterfaceResponse XML message.

Security Services web services

The Security Services enable you to remotely create partitions and users. These web services
include the following:
• CreatePartition
• CreateUser
Note: For users that are created via web services, a cache refresh must occur before those
users can log in to Vertex Central. With default settings, this refresh can take up to
5 minutes.
For details about these web services, refer to the annotated schema documentation (see page
60).

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 65
Chapter 4. Troubleshooting the Vertex O
Series Client Utilities Run Through web
services
You may get Simple Object Access Protocol (SOAP) errors while Vertex O Series processes XML
messages. The cause of the error determines the type of SOAP fault message that you receive.
For more details on the SOAP portion of the W3C standard, go to
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.

In this chapter
Troubleshooting a client fault.......................................................66
Troubleshooting a server fault .....................................................67

Troubleshooting a client fault

A client fault indicates that the SOAP message was incorrectly formed or did not include a
required element.
Troubleshooting a client fault involves:
1. Reviewing the message against the SOAP standard and correcting any omissions. Then,
resend the message.
2. If you still receive a client fault, have your IT Department review the Vertex O Series Log files
to determine the type of error. If necessary, contact Vertex Product Support.
For more details about SOAP faults, go to http://www.w3.org/TR/2000/NOTE-SOAP-
20000508/#_Toc478383510.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 66
 Chapter 4. Troubleshooting the Vertex O Series Client Utilities Run Through web services

Troubleshooting a server fault

A server fault indicates that a SOAP message could not be processed for reasons unrelated to
the contents of the message. This message indicates that the processing server may be
unresponsive or not available for processing.
Troubleshooting a server fault involves:
1. Vertex addressing and resolving the server issue.
2. Resending your message at a later date when the processing server is available.
For more details on SOAP faults, go to http://www.w3.org/TR/2000/NOTE-SOAP-
20000508/#_Toc478383510.

Vertex® Indirect Tax O Series® 9.0 O Series Client Utilities User's Guide | 67