+----------------------+-----------------------------------------------+
| ![](media/           | ![](me                                        |
| image1.wmf){width="2 | dia/image3.jpeg){width="1.4583333333333333in" |
| .2083333333333335in" | hei                                           |
| height="1            | ght="0.7916666666666666in"}**SDWIS/LabToState |
| .229861111111111in"} | 1.0**                                         |
|                      |                                               |
| United States        | **Installation Guide**                        |
| Environmental        |                                               |
| Protection Agency    |                                               |
|                      |                                               |
| Office of Ground     |                                               |
| Water and Drinking   |                                               |
| Water                |                                               |
|                      |                                               |
| SDWIS Project        |                                               |
|                      |                                               |
| Product Control No.  |                                               |
|                      |                                               |
| Sys                  |                                               |
| talex-SDWIS-01-6.d3a |                                               |
|                      |                                               |
| Deliverable No.      |                                               |
| 6.d3a                |                                               |
|                      |                                               |
| December 20, 2006    |                                               |
+----------------------+-----------------------------------------------+

**SDWIS/LABTOSTATE 1.0 INSTALLATION GUIDE**

[]{.mark}

**SDWIS PROJECT**

**Prepared for:**

**United States Environmental Protection Agency**

**Office of Ground Water and Drinking Water**

**Drinking Water Protection Division**

**1200 Pennsylvania Ave., NW**

**Washington, DC 20460**

**Contracting Officer Representative**

**Edward Cottrill**

**Prepared by:**

**SAIC Solutions Delivery Center**

**Science Applications International Corporation**

**6565 Arlington Boulevard**

**Falls Church, VA 22042**

**CONTENTS**

[1.0 Introduction 1](#introduction)

[1.1 Document Overview 1](#document-overview)

[1.2 Software and Hardware Test Environment
1](#software-and-hardware-test-environment)

[1.3 User Support 2](#user-support)

[2.0 Installation Procedures 3](#installation-procedures)

[2.1 Stand alone Client Application Installation
3](#stand-alone-client-application-installation)

[2.1.1 Upgrade Installation‑Stand Alone Client Application
3](#upgrade-installationstand-alone-client-application)

[2.1.2 First Time Installation‑Stand Alone Client Application
5](#first-time-installationstand-alone-client-application)

[2.2 Web based Application Installation
7](#web-based-application-installation)

[2.2.1 Upgrade Installation‑Web Based Application
8](#upgrade-installationweb-based-application)

[2.2.2 First Time Installation‑Web Based Application
14](#first-time-installationweb-based-application)

[3.0 Support Software Installation Procedures
21](#support-software-installation-procedures)

[3.1 Application Server Upgrade Installation
21](#application-server-upgrade-installation)

[3.1.1 Archive SDWIS/LabToState Files
22](#archive-sdwislabtostate-files-2)

[3.1.2 Remove Current Tomcat Release 23](#remove-current-tomcat-release)

[3.1.3 Remove Java SDK 24](#remove-java-sdk)

[3.1.4 Install Supporting Software 25](#install-supporting-software)

[3.2 Application Server First Time Installation
25](#application-server-first-time-installation)

[3.2.1 Download the Java SDK 26](#download-the-java-sdk)

[3.2.2 Install the Java SDK 28](#install-the-java-sdk)

[3.2.3 Download Tomcat 28](#download-tomcat)

[3.2.4 Install Tomcat 30](#install-tomcat)

[3.2.5 Increase Tomcat's Memory Allocation
31](#increase-tomcats-memory-allocation)

[3.2.6 Complete Support Software Installation
32](#complete-support-software-installation)

[4.0 Site Customization Procedures 33](#site-customization-procedures)

[4.1 Site Customization Files 33](#site-customization-files)

[4.1.1 Site Properties File 33](#site-properties-file)

[4.1.2 User Identification XML Document
33](#user-identification-xml-document)

[4.1.3 Release Statement File 34](#release-statement-file)

[4.2 Data File Content Configuration
34](#data-file-content-configuration)

[4.3 Data Source Registration File 37](#data-source-registration-file)

**APPENDIX A** System Property File Name Descriptions

**APPENDIX B** Object and Element Configuration Files

**APPENDIX C** Element Names by Object

**APPENDIX D** Interface Specifications

**EXHIBITS**

[**Exhibit 1.** Hardware and Software Test Environment
2](#__RefHeading___Toc154364567)

[**Exhibit 2.** SDWIS/LabToState Upgrade Installation Checklist
4](#__RefHeading___Toc154364568)

[**Exhibit 3.** SDWIS/LabToState Files To Archive
4](#__RefHeading___Toc154364569)

[**Exhibit 4.** Install SDWIS/LabToState
5](#__RefHeading___Toc154364570)

[**Exhibit 5.** Install SDWIS/LabToState
6](#__RefHeading___Toc154364571)

[**Exhibit 6.** Stand alone Client Application DOS Window
7](#__RefHeading___Toc154364572)

[**Exhibit 7.** SDWIS/LabToState Upgrade Installation Checklist
8](#__RefHeading___Toc154364573)

[**Exhibit 8.** SDWIS/LabToState Files To Archive
9](#__RefHeading___Toc154364574)

[**Exhibit 9.** Tomcat Administration Home Page
10](#__RefHeading___Toc154364575)

[**Exhibit 10.** Tomcat Web Application Manager Page
12](#__RefHeading___Toc154364576)

[**Exhibit 11.** Tomcat Web Application Manager Page
13](#__RefHeading___Toc154364577)

[**Exhibit 12.** SDWIS/LabToState First Time Installation Checklist
14](#__RefHeading___Toc154364578)

[**Exhibit 13.** Tomcat Home Page 16](#__RefHeading___Toc154364579)

[**Exhibit 14.** User ID and Password for Tomcat Manager
17](#__RefHeading___Toc154364580)

[**Exhibit 15.** Tomcat Web Application Manager --- Before Deployment
18](#__RefHeading___Toc154364581)

[**Exhibit 16.** Tomcat Web Application Manager Page --- After
Deployment 19](#__RefHeading___Toc154364582)

[**Exhibit 17.** SDWIS/LabToState System Environment Variables
20](#__RefHeading___Toc154364583)

[**Exhibit 18.** Supporting Software Upgrade Installation Checklist
22](#__RefHeading___Toc154364584)

[**Exhibit 19.** SDWIS/LabToState Files To Archive
22](#__RefHeading___Toc154364585)

[**Exhibit 20.** Remove Tomcat --- Add or Remove Program Window
24](#__RefHeading___Toc154364586)

[**Exhibit 21.** Remove Java SDK --- Add or Remove Program Window
25](#__RefHeading___Toc154364587)

[**Exhibit 22.** Supporting Software First Time Installation Checklist
26](#__RefHeading___Toc154364588)

[**Exhibit 23.** Java SDK Download Page
27](#__RefHeading___Toc154364589)

[**Exhibit 24.** Download Tomcat from Apache Web Site
28](#__RefHeading___Toc154364590)

[**Exhibit 25.** Download Tomcat from Apache Web Site
29](#__RefHeading___Toc154364591)

[**Exhibit 26.** Download Tomcat from Apache Web Site
29](#__RefHeading___Toc154364592)

[**Exhibit 27.** Download Tomcat from Apache Web Site
30](#__RefHeading___Toc154364593)

[**Exhibit 28.** Apache Icon in the Desktop's System Tray
31](#__RefHeading___Toc154364594)

[**Exhibit 29.** Tomcat Properties Window
32](#__RefHeading___Toc154364595)

[**Exhibit 30.** User Authentication XML Document
34](#__RefHeading___Toc154364596)

[**Exhibit 31.** Object Configuration File
35](#__RefHeading___Toc154364597)

[**Exhibit 32.** Element Configuration Files
36](#__RefHeading___Toc154364598)

[**Exhibit 33.** SDWIS/XML Sampling Structure Sets
36](#__RefHeading___Toc154364599)

[**Exhibit 34.** Example of CSV File 37](#__RefHeading___Toc154364600)

[**Exhibit 35.** Data‑Source Plug‑In Registration File
37](#__RefHeading___Toc154364601)

# Introduction

The *SDWIS/LabToState 1.0 Installation Guide* contains instructions for
installing SDWIS/LabToState 1.0. SDWIS/LabToState may be deployed as a
web based, platform‑independent application or as a stand alone client
application. It allows laboratories and other entities to format sample
data into XML documents, which are transferred to SDWIS/XML Sampling for
additional processing. The software is designed for use by and is
available to all laboratories, primacy agencies, and other entities that
format sample data for submission to primacy agencies using SDWIS/XML
Sampling.

## Document Overview

This document contains instructions for installing and administering
SDWIS/LabToState 1.0. It comprises the following sections:

-   Section 1.0, Introduction, describes the content of the document,
    the software and hardware test environment, and user support
    procedures.

-   Section 2.0, Installation Procedures, describes the steps required
    to install SDWIS/LabToState 1.0 as a stand alone client application
    and as a web based application using a J2EE application server.

-   Section 3.0, Support Software Installation Procedures, describes the
    steps required to install the support software used by
    SDWIS/LabToState 1.0 when it is installed as a web based
    application.

-   Section 4.0, Site Customization Procedures, describes the steps
    required to customize SDWIS/LabToState 1.0 at your site.

## Software and Hardware Test Environment

SDWIS/LabToState 1.0 was tested using the hardware and supporting
software versions listed in Exhibit 1. More recent versions of the
supporting software may be available; the application, however, has not
been tested with these newer versions.

As a web based application, the SDWIS/LabToState software may reside on
an application server or on a network‑connected workstation configured
as a stand alone server. As a stand alone client application, the
SDWIS/LabToState software may be installed on any windows based PC.

SDWIS/LabToState may interface with the site's local e-mail server.
Additionally, for sites using the SQL PlugIn to retrieve sample data,
SDWIS/LabToState must have access to the database server from which it
is to retrieve data. The SDWIS/LabToState SQL PlugIn was developed and
tested using databases deployed on Oracle and Microsoft Access.

+---------+---------+-----------------------+------------------------+
| **Pla   | **Op    | **Software**          | **Hardware**           |
| tform** | erating |                       |                        |
|         | S       |                       |                        |
|         | ystem** |                       |                        |
+=========+=========+=======================+========================+
| Appl    | WINDOWS | WINDOWS NT Server     | Dell OptiPlex GX400\   |
| ication | NT 4.0  | Software with Service | (Pentium 4 -- 1.4 GHz  |
| Server  | Server  | Pack 6                | Processor)             |
| / Web   |         |                       |                        |
| Server  |         | Internet Explorer     | 1 GB RAM               |
|         |         | v6.0 with Service     |                        |
|         |         | Pack 1                | Screen Resolution:     |
|         |         |                       | 1024 x 768 and Small   |
|         |         | Java 2 SDK, Standard  | Fonts                  |
|         |         | Edition (J2SE), v     |                        |
|         |         | 1.4.2                 |                        |
|         |         |                       |                        |
|         |         | Tomcat 5.0.28         |                        |
|         |         |                       |                        |
|         |         | SDWIS/XML Sampling    |                        |
|         |         | v1.0.3                |                        |
+---------+---------+-----------------------+------------------------+
| D       | Windows | WINDOWS NT Server     | Compaq Proliant DL380, |
| atabase | NT 4 .0 | Software with Service | Pentium III, 933 MHz   |
| Server  |         | Pack 6                | CPU, 4 GB Hard Disk    |
|         |         |                       |                        |
|         |         | Oracle 9i Release 2   |                        |
+---------+---------+-----------------------+------------------------+
| E-Mail  | Windows | MS Exchange 2000      | Compaq Proliant ML370  |
| Server  | 2000    |                       | G2, two 1.3 MHz CPU, 2 |
|         | Server  |                       | MB of memory           |
+---------+---------+-----------------------+------------------------+
| Client  | Windows | Internet Explorer     | Dell OptiPlex GX400\   |
| Work    | 2000    | v6.0 with Service     | (Pentium 4 -- 1.4 GHz  |
| station |         | Pack 1                | Processor)             |
|         |         |                       |                        |
|         |         |                       | 1 GB RAM               |
|         |         |                       |                        |
|         |         |                       | Screen Resolution:     |
|         |         |                       | 1024 x 768 and Small   |
|         |         |                       | Fonts                  |
+---------+---------+-----------------------+------------------------+

[]{#__RefHeading___Toc154364567 .anchor}**Exhibit 1.** Hardware and
Software Test Environment

## User Support

As a representative of a primacy agency, you may call the SDWIS User
Support Hotline at (703) 292‑6298 or e‑mail SDWIS User Support at
<sdwis@saic-solutions.com>. If you represent a laboratory using the
SDWIS/LabToState product, you are encouraged to contact the primacy
agency to which you are reporting sample data. The primacy agency will
in turn contact the SDWIS User Support Hotline on your behalf. The
hotline/e-mail account is intended as a technical support tool for the
operation and functionality of SDWIS products such as SDWIS/LabToState.
A SDWIS team member answers calls to the hotline between 8 a.m. and 5
p.m., Eastern Standard Time (EST), on weekdays (except federal holidays)
and offers immediate user support when possible. During evenings,
weekends, or those times when the support personnel are temporarily not
available, callers may leave a detailed message. Questions requiring the
expertise of other team members, such as developers or subject matter
experts, are documented in the Events Tracking System, forwarded to
those individuals, and answered as soon as possible.

# Installation Procedures

SDWIS/LabToState may be deployed as a stand alone client application
hosted on a windows‑based operating system or as a web based application
accessed through a browser‑based client. If you are installing it as a
stand alone client application, proceed to Section 2.1, Stand alone
Client Application Installation. To install it as a web based
application, proceed to Section 2.2, Web based Application Installation.

## Stand alone Client Application Installation

This section describes procedures for installing SDWIS/LabToState as a
stand alone-client application. The SDWIS/LabToState software interfaces
with the site's e‑mail server. Therefore, a System Administrator
familiar with the e‑mail server must be available to you (as the person
installing the SDWIS/LabToState application) throughout the installation
process. For primacy agencies using the SQL PlugIn, SDWIS/LabToState
interfaces with your database and the Database Administrator (DBA) must
also be available.

If you are installing SDWIS/LabToState and need to upgrade your current
installation, you may proceed to Section 2.1.1, Upgrade
Installation-Stand Alone Client Application. If you have never installed
it at your site, you should proceed to Section 2.1.2, First Time
Installation-Stand Alone Client Application.

### Upgrade Installation‑Stand Alone Client Application

Exhibit 2 is a checklist of the steps required to upgrade to a new
release of SDWIS/LabToState. The remainder of this section further
describes each step in the upgrade installation procedures.

  ----------------------------------------------------------------------------------
  **SDWIS/LabToState                              
  Upgrade Installation                            
  Checklist**                                     
  -------------------- -------------------------- ----------------------------------
  **Installation       **Installation Activity    **Installation Guide Reference**
  Step**               Description**              

  1                    Archive SDWIS/LabToState   Section 2.1.1.1, Archive
                       Files                      SDWIS/LabToState Files

  2                    Remove the                 Section 2.1.1.2, Remove the
                       SDWIS/LabToState Software  SDWIS/LabToState Software

  3                    Install SDWIS/LabToState   Section 2.1.1.3, Install
                       Software                   SDWIS/LabToState Software
  ----------------------------------------------------------------------------------

[]{#__RefHeading___Toc154364568 .anchor}**Exhibit 2.** SDWIS/LabToState
Upgrade Installation Checklist

#### Archive SDWIS/LabToState Files

The first step to upgrading SDWIS/LabToState is to move the files and
directories containing SDWIS/LabToState processing information.
Otherwise, those files and directories will be deleted during the
installation of the new release. The SDWIS/LabToState processing files
and directories you need to move are listed in Exhibit 3.

  -------------- ----------------------------------------------------------------- -----------------------------
  **File or      **Name**                                                          **Description**
  Directory**                                                                      

  Directory      \[InstalledDirectory\]\\Tomcat\\webapps\\LabToState\\JobFolders   Contains the uploaded sample
                                                                                   data, output reports, and
                                                                                   generated XML documents for
                                                                                   each job processed by
                                                                                   SDWIS/LabToState.

  Directory      \[InstalledDirectory\]\\Tomcat                                    Contains site-specific values
                 \\webapps\\LabToState\\WEB-INF\\classes\\properties               used to configure the
                                                                                   SDWIS/LabToState software.
  -------------- ----------------------------------------------------------------- -----------------------------

[]{#__RefHeading___Toc154364569 .anchor}**Exhibit 3.** SDWIS/LabToState
Files To Archive

The Job Folders directory is archived to maintain a history of the
sample data processed by SDWIS/LabToState at your site. The properties
directory is archived so that it may be used as a reference to set the
values of the site configuration files during the SDWIS/LabToState
installation.

**Note:** Since the Site Configuration files may have changed since the
last installation of SDWIS/LabToState, use the current values as a
reference to update values when you install the application again.

#### Remove the SDWIS/LabToState Software

In Step 2, you remove the SDWIS/LabToState software by deleting the
folder in which you originally installed the software.

#### Install SDWIS/LabToState Software

After the existing release of SDWIS/LabToState is removed, you should
install the SDWIS/LabToState software using the installation procedures
described in Section 2.1.2, First Time Installation-Stand Alone Client
Application.

### First Time Installation‑Stand Alone Client Application

This section describes procedures to install SDWIS/LabToState as a stand
alone-client application for the first time. Exhibit 4 is a checklist of
the steps required to install SDWIS/LabToState. The remainder of this
section further describes each step in the installation procedures.

  ----------------------------------------------------------------------------------
  **SDWIS/LabToState                                  
  Installation Check                                  
  List**                                              
  -------------------- ------------------------------ ------------------------------
  **Installation       **Installation Activity        **Installation Guide
  Step**               Description**                  Reference**

  1                    Download SDWIS/LabToState      Section 2.1.2.1, Remove the
                       Installation Package and       SDWIS/LabToState Software
                       documentation                  

  2                    Install the SDWIS/LabToState   Section 2.1.2.2, Install the
                       software                       SDWIS/LabToState Software

  3                    Start SDWIS/LabToState         Section 2.1.2.3,
                                                      SDWIS/LabToState Startup

  4                    Shut down SDWIS/LabToState     Section 2.1.2.4,
                                                      SDWIS/LabToState Shut Down

  5                    Configure SDWIS/LabToState     Section 2.1.2.5, Configure
                                                      SDWIS/LabToState
  ----------------------------------------------------------------------------------

[]{#__RefHeading___Toc154364570 .anchor}**Exhibit 4.** Install
SDWIS/LabToState

#### Download SDWIS/LabToState Installation Package

The first step is to download the SDWIS/LabToState 1.0 Installation
Package from the SDWIS web site
(<http://www.epa.gov/safewater/sdwisfed/sdwismod.htm>). You should also
download the *SDWIS/LabToState 1.0 User Guide* (Systalex-SDWIS-01-6.d3b,
December 20, 2006) and the *SDWIS/LabToState 1.0 Release Notes*
(Systalex-SDWIS-01-6.d1b, December 28, 2006).

#### Install the SDWIS/LabToState Software

In Step 2, you unzip the installation package to a directory of your
choice. To simplify the installation of the stand alone client
application, the installation package bundles the required supporting
software (e.g., Java SDK and Tomcat server). Exhibit 5 provides an
annotated list of the directory structure after unzipping the
installation package.

![](media/image4.jpeg){width="5.197916666666667in" height="1.96875in"}

[]{#__RefHeading___Toc154364571 .anchor}**Exhibit 5.** Install
SDWIS/LabToState

#### SDWIS/LabToState Startup

In Step 3, you start the application by double clicking on the
startup.bat located in the folder in which you installed the
application. As depicted in Exhibit 6, this procedure opens a DOS window
for the application process. It also opens the default browser pointing
to the URL of the application.

**Note:** You may see warning as depicted in Exhibit 6 -- please ignore.

The default hostname is set to "localhost" and the default port is set
to "8090". The URL to the application with these settings is
<http://localhost:8090/labtostate/jsp/index.jsp>. You may change the
host name and port number of the embedded Tomcat by changing the
tomcat.properties file found in the top folder of the application
installation directory.

![](media/image5.png){width="6.5in" height="3.2708333333333335in"}

[]{#__RefHeading___Toc154364572 .anchor}**Exhibit 6.** Stand alone
Client Application DOS Window

#### SDWIS/LabToState Shut Down

In Step 4, you shut down the application by closing the DOS window. To
close the DOS window click the "X" in the upper right corner of the DOS
window.

#### Configure SDWIS/LabToState 

After completing the above steps, the installation of SDWIS/LabToState
software is complete. You should continue to Section 4.0, Site
Customization Procedures of this document to configure the
SDWIS/LabToState software for your site.

## Web based Application Installation

This section describes procedures for installing SDWIS/LabToState as a
web based application. The SDWIS/LabToState software is installed on a
web server and interfaces with the e‑mail server. Therefore, a System
Administrator familiar with the web server, application server, and
e‑mail server must be available to you (as the person installing the
SDWIS/LabToState application) throughout the installation process. For
primacy agencies using SQL PlugIn, SDWIS/LabToState interfaces with your
database and the Database Administrator (DBA) must also be available.

The installation procedures described in this section include a step for
installing the support software required by SDWIS/LabToState. That step
refers to Section 3.0, Support Software Installation Procedures, which
contains the detailed procedures for installing and upgrading the
supporting software.

If you are installing SDWIS/LabToState as a web based application and
need to upgrade your current installation, you may proceed to Section
2.2.1, Upgrade Installation-Web Based Application. If you have never
installed it at your site, you should proceed to Section 2.2.2, First
Time Installation-Web Based Application.

### Upgrade Installation‑Web Based Application

Exhibit 7 is a checklist of the steps required to upgrade to a new
release of SDWIS/LabToState. The remainder of this section further
describes each step in the upgrade installation procedures.

  ----------------------------------------------------------------------------------
  **SDWIS/LabToState                              
  Upgrade Installation                            
  Checklist**                                     
  -------------------- -------------------------- ----------------------------------
  **Installation       **Installation Activity    **Installation Guide Reference**
  Step**               Description**              

  1                    Archive SDWIS/LabToState   Section 2.2.1.1, Archive
                       Files                      SDWIS/LabToState Files

  2                    Remove the                 Section 2.2.1.2, Remove the
                       SDWIS/LabToState Software  SDWIS/LabToState Software

  3                    Install SDWIS/LabToState   Section 2.2.1.3, Install
                       Software                   SDWIS/LabToState Software
  ----------------------------------------------------------------------------------

[]{#__RefHeading___Toc154364573 .anchor}**Exhibit 7.** SDWIS/LabToState
Upgrade Installation Checklist

#### Archive SDWIS/LabToState Files

The first step to upgrading SDWIS/LabToState is to move the files and
directories containing SDWIS/LabToState processing information.
Otherwise, those files and directories will be deleted during the
installation of the new release. The SDWIS/LabToState processing files
and directories you need to move are listed in Exhibit 8.

  ------------- ------------------------------------------------------------------------------ -----------------------------
  **File or     **Name**                                                                       **Description**
  Directory**                                                                                  

  Directory     c:\\jakarta-tomcat-5.0.28\\webapps\\LabToState\\JobFolders                     Contains the uploaded sample
                                                                                               data, output reports, and
                                                                                               generated XML documents for
                                                                                               each job processed by
                                                                                               SDWIS/LabToState.

  Directory     c:\\jakarta-tomcat-5.0.28\\webapps\\LabToState\\WEB-INF\\classes\\properties   Contains site-specific values
                                                                                               used to configure the
                                                                                               SDWIS/LabToState software.
  ------------- ------------------------------------------------------------------------------ -----------------------------

[]{#__RefHeading___Toc154364574 .anchor}**Exhibit 8.** SDWIS/LabToState
Files To Archive

The Job Folders directory is archived to maintain a history of the XML
documents validated and prepared by SDWIS/LabToState at your site. The
properties directory is archived so that it may be used as a reference
to set the values of the site configuration files during the
SDWIS/LabToState installation.

**Note:** Since the Site Configuration files may have changed since the
last release, use the current values as a reference to update values
when the new release of the application is installed.

#### Remove the SDWIS/LabToState Software

In Step 2, you remove the SDWIS/LabToState software from the application
server. The following list itemizes the tasks required to remove this
software:

1.  Double-click the startup.bat file in the
    c:\\jakarta-tomcat-5.0.28\\bin directory to start Tomcat (assumes
    Tomcat is running in a DOS window).

2.  Open a web browser and type **http://localhost:8080** in the address
    bar. The Tomcat home page will be displayed as illustrated in
    Exhibit 9.

![](media/image6.png){width="6.510416666666667in"
height="5.604166666666667in"}

[]{#__RefHeading___Toc154364575 .anchor}**Exhibit 9.** Tomcat
Administration Home Page

3.  Click on the Tomcat Manager link, located on the left side of the
    page in the box titled Administration. You will be prompted for a
    User ID and Password. Enter the User ID and Password created to
    manage the Tomcat application server (i.e., the User ID assigned to
    the role of "admin, manager"). To find the User ID and password,
    complete the following tasks:

-   Open the file tomcat-users.xml, located in the directory
    c:\\jakarta-tomcat-5.0.28\\conf\\ using a standard text editor.

-   Find the User ID and Password assigned to the "admin,manager" roles.
    If a User ID and Password is not assigned to these roles, enter the
    following lines in the file before the line "\</tomcat-users\>"
    (note the preceding backslash). Replace the italicized words with
    the desired User ID and Password. Save the file and restart the
    Tomcat application.

> \<user username= "*AdministratorUser*" Password=
> "*AdministratorPassword*" roles= "admin,manager" /\>

4.  The Tomcat Web Application Manager page is displayed as depicted in
    Exhibit 10. Click on the **Undeploy** button in the applications
    list next to the SDWIS/LabToState application. The arrow in Exhibit
    10 illustrates the location of this button on the page.

![](media/image7.png){width="6.510416666666667in" height="7.28125in"}

[]{#__RefHeading___Toc154364576 .anchor}**Exhibit 10.** Tomcat Web
Application Manager Page

5.  Exhibit 11 depicts the page that is presented after the application
    is "Undeployed." The message "OK - Undeployed application at context
    path /LabToState" is presented in the Message section, which is
    located directly below the page title of "Tomcat Web Application
    Manager." The arrow in Exhibit 11 illustrates the location of this
    message. Additionally, SDWIS/LabToState is removed from the list of
    applications in the Applications section of the page.

![](media/image8.png){width="6.510416666666667in"
height="6.958333333333333in"}

[]{#__RefHeading___Toc154364577 .anchor}**Exhibit 11.** Tomcat Web
Application Manager Page

#### Install SDWIS/LabToState Software

After the existing release of SDWIS/LabToState is removed from the
application server, you should install the SDWIS/LabToState software
using the installation procedures described in Section 2.2.2, First Time
Installation-Web Based Application.

### First Time Installation‑Web Based Application

Exhibit 12 is a checklist of the steps required to install
SDWIS/LabToState for the first time. The remainder of this section
further describes each step in the first time installation procedures.

  ----------------------------------------------------------------------------------
  **SDWIS/LabToState                                  
  First Time                                          
  Installation Check                                  
  List**                                              
  -------------------- ------------------------------ ------------------------------
  **Installation       **Installation Activity        **Installation Guide
  Step**               Description**                  Reference**

  1                    Download SDWIS/LabToState      2.2.2.1 Download
                       Installation Package and       SDWIS/LabToState Installation
                       documentation                  Package

  2                    Install support software       2.2.2.2 Install Support
                       (i.e., Java SDK and Tomcat     Software Used by
                       application server) used by    SDWIS/LabToState
                       SDWIS/LabToState               

  3                    Assign User ID and Password on 2.2.2.3 Assign User
                       the application server         Identification and Passwords

  4                    Install the SDWIS/LabToState   2.2.2.4 Install the
                       software                       SDWIS/LabToState Software

  5                    Set Java environment variable  2.2.2.5 Set Environment
                                                      Variables

  6                    Configure SDWIS/LabToState for 2.2.2.6 Configure and Start Up
                       deployment at your site        SDWIS/LabToState
  ----------------------------------------------------------------------------------

[]{#__RefHeading___Toc154364578 .anchor}**Exhibit 12.** SDWIS/LabToState
First Time Installation Checklist

#### Download SDWIS/LabToState Installation Package

The first step is to download the SDWIS/LabToState 1.0 Installation
Package from the SDWIS web site
(<http://www.epa.gov/safewater/sdwisfed/sdwismod.htm>). You should also
download the *SDWIS/LabToState 1.0 User Guide* and the *SDWIS/LabToState
1.0 Release Notes*.

#### Install Support Software Used by SDWIS/LabToState

In Step 2, you load the Java 2 Platform Standard Edition, Software
Development Kit (SDK), and Tomcat on the application server. If both the
Java SDK and Tomcat are already installed on the application server,
this step may be skipped. To install or upgrade those components, you
should proceed to Section 3.0, Support Software Installation Procedures,
which contains detailed instructions for loading these software
components. Although the SDWIS/LabToState application may be deployed in
any Java 2 Enterprise Edition (J2EE) compliant application server, the
installation procedures assume Tomcat is the application server on which
SDWIS/LabToState is deployed.

#### Assign User Identification and Passwords

In this step, you define the User ID and Password that administers the
Tomcat server. The administration capability is required to install
SDWIS/LabToState.

**Note:** User IDs and Passwords are case-sensitive.

The following list describes the tasks required to create a User ID and
Password to the roles named "admin" and "manager," which allow the
administration of the Tomcat application server.

1.  Open the file tomcat-users.xml, located in the directory
    c:\\jakarta-tomcat-5.0.28\\conf\\ using a standard text editor.

2.  Enter the following line in the file before the line
    "\</tomcat-users\>" (note the preceding backslash). Replace the
    italicized words with the desired User ID and Password.

> \<user username= "*AdministratorUser*" Password=
> "*AdministratorPassword*" roles= "admin,manager" /\>
>
> **Note:** If Tomcat is installed as a service, the User ID and
> Password for the admin and manager roles were assigned during the
> installation of the Tomcat service.

3.  Remember to save the file.

4.  The next time the Tomcat application is initiated, the User IDs and
    Passwords are activated.

> **Note:** If Tomcat is running in a DOS window, double-click the
> startup.bat file in the C:\\jakarta-tomcat-5.0.28\\bin directory to
> initiate Tomcat. To shut down Tomcat, double-click the shutdown.bat
> file in the C:\\jakarta-tomcat-5.0.28\\bin directory. If Tomcat is
> running as a service, the Tomcat service is shut down and initiated
> using the operating systems service administration utilities.

#### Install the SDWIS/LabToState Software

In Step 4, you load the SDWIS/LabToState software on the Tomcat
application server. The installation package delivers the
SDWIS/LabToState software as a single packed file format known as a Web
Archive (WAR) file. This format is generally used to distribute
applications before installation. By completing the following tasks, the
WAR file is unpacked into the appropriate file structure.

1.  Start the Tomcat server. Double-click the startup.bat file in the
    c:\\jakarta-tomcat-5.0.28\\bin directory to initiate Tomcat (assumes
    Tomcat is running in a DOS window).

2.  Open a web browser and type **http://localhost:8080** in the address
    bar. The Tomcat home page will be displayed as illustrated in
    Exhibit 13.

![](media/image6.png){width="6.510416666666667in"
height="5.604166666666667in"}

[]{#__RefHeading___Toc154364579 .anchor}**Exhibit 13.** Tomcat Home Page

3.  Click on the Tomcat Manager link, located on the left side of the
    page in the box titled Administration. You will be prompted for a
    User Name and Password, as depicted in Exhibit 14. Enter the User
    Name and Password created for the admin and manager roles in Section
    2.1.3, Assign User Identification and Passwords.

![](media/image9.png){width="4.1875in" height="2.78125in"}

[]{#__RefHeading___Toc154364580 .anchor}**Exhibit 14.** User ID and
Password for Tomcat Manager

4.  The Tomcat Web Application Manager page is displayed. In the Deploy
    section of the page in the text box labeled "Select WAR file to
    upload," enter the SDWIS/LabToState WAR file as depicted in
    Exhibit 15. Use the **Browse** button to assist with locating the
    file. The arrow in Exhibit 15 illustrates the location of this link
    on the page. After the SDWIS/LabToState War file is displayed in the
    text box, click on the **Deploy** button.

![](media/image10.png){width="6.510416666666667in"
height="6.791666666666667in"}

[]{#__RefHeading___Toc154364581 .anchor}**Exhibit 15.** Tomcat Web
Application Manager --- Before Deployment

5.  Exhibit 16 shows the page that is presented after the application is
    deployed. The message "OK - Deployed application at context path
    /LabToState" is presented in the Message section, which is located
    directly below the page title of "Tomcat Web Application Manager."
    Additionally, the SDWIS/LabToState application is listed in the
    Applications section of the page.

6.  Shut down the Tomcat server by double-clicking the shutdown.bat file
    in the c:\\jakarta-tomcat-5.0.28\\bin directory (assumes Tomcat is
    running in a DOS window).

![](media/image11.png){width="6.510416666666667in"
height="7.020833333333333in"}

[]{#__RefHeading___Toc154364582 .anchor}**Exhibit 16.** Tomcat Web
Application Manager Page --- After Deployment

#### Set Environment Variables

In Step 5, you set the environment variable used by the Apache Tomcat.
The "JAVA_HOME" variable is set to the location of the java compiler
software and is used by the Apache Tomcat server. By completing the
following tasks, you set these environment variables:

1.  From the Window's Control Panel, click on the System icon.

2.  Select the Advanced tab.

3.  Click on **Environment Variables** button.

4.  In the Environment Variables window (Exhibit 17), add a system
    variable named JAVA_HOME with the value of the variable set to the
    location of the java compiler software (e.g., c:\\j2sdk1.4.2_08).

5.  Restart the Tomcat server by double-clicking the startup.bat file in
    the c:\\jakarta-tomcat-5.0.28\\bin directory (assuming Tomcat is
    running in a DOS window).

![](media/image12.png){width="4.051388888888889in"
height="4.447222222222222in"}

[]{#__RefHeading___Toc154364583 .anchor}**Exhibit 17.** SDWIS/LabToState
System Environment Variables

#### Configure and Start Up SDWIS/LabToState 

After completing Steps 1 through 5, the installation of SDWIS/LabToState
is complete. You should continue to Section 4.0, Site Customization
Procedures of this document to configure the SDWIS/LabToState software
for your site.

After configuring SDWIS/LabToState, you need to complete the following
activities:

-   Start the application server.

-   Enter URL of the application (e.g.,
    http://localhost:8080/labtoState/jsp)

# Support Software Installation Procedures

Prior to installing the SDWIS/LabToState application, you should
configure the application server hosting the SDWIS/LabToState
application to include the following support software:

-   Java 2 Platform Standard Edition, Software Development Kit (SDK).
    The SDK provides the libraries, Java virtual machine, and other
    components necessary to run applications written in the Java
    programming

-   Application Server/Web Server. SDWIS/LabToState may be hosted on any
    J2EE compliant application server. All development and testing was
    conducted using the Tomcat application server provided by Apache
    Software Foundation. Tomcat serves as both the application and web
    server.

SDWIS/LabToState uses Sun Microsystems SDK Version 1.4.2.Tomcat. To
upgrade your current releases of the Java SDK and language, proceed to
Section 3.1, Application Server Upgrade Installation. If these
components are not installed on your server, proceed to Section 3.2,
Application Server First Time Installation, which defines procedures for
installing the Java SDK and Tomcat software for the first time.

**Note:** For both a first time and an upgrade installation of the Java
SDK and the Tomcat software, SDWIS/LabToState must be re-installed.
Therefore, SDWIS/LabToState installation package must be available to
you as the application installer.

**Note:** The Java SDK must be installed before the installation of the
Tomcat application server.

## Application Server Upgrade Installation

Exhibit 18 is a checklist of the steps required to upgrade to new
releases of Java SDK and Tomcat if this software is already installed on
your application server. The remainder of this section further describes
each step in the installation procedures.

  ------------------------------------------------------------------------------
  **Supporting                                
  Software Upgrade                            
  Installation                                
  Checklist**                                 
  ---------------- -------------------------- ----------------------------------
  **Installation   **Installation Activity    **Installation Guide Reference**
  Step**           Description**              

  1                Archive SDWIS/LabToState   3.1.1 Archive SDWIS/LabToState
                   Files                      Files

  2                Remove Current Tomcat      3.1.2 Remove Current Tomcat
                   Release                    Release

  3                Remove Current Java SDK    3.1.3 Remove Java SDK

  4                Install Supporting         3.1.4 Install Supporting Software
                   Software                   
  ------------------------------------------------------------------------------

[]{#__RefHeading___Toc154364584 .anchor}**Exhibit 18.** Supporting
Software Upgrade Installation Checklist

### Archive SDWIS/LabToState Files

The first step to upgrading the supporting software is to move the files
and directories containing SDWIS/LabToState processing information.
Otherwise, those files and directories will be deleted during the
installation of the new release. The SDWIS/LabToState processing files
and directories that must be moved are listed in Exhibit 19. If these
files have already been moved, proceed to Section 3.1.2, Remove Current
Tomcat Release.

  ------------- ------------------------------------------------------------------------------ -----------------------------
  **File or     **Name**                                                                       **Description**
  Directory**                                                                                  

  Directory     C:\\jakarta-tomcat-5.0.28\\webapps\\LabToState\\JobFolders                     Contains the XML documents
                                                                                               generated by each job
                                                                                               processed by
                                                                                               SDWIS/LabToState.

  Directory     C:\\jakarta-tomcat-5.0.28\\webapps\\LabToState\\WEB-INF\\classes\\properties   Contains site-specific values
                                                                                               used to configure the
                                                                                               SDWIS/LabToState processing.
  ------------- ------------------------------------------------------------------------------ -----------------------------

[]{#__RefHeading___Toc154364585 .anchor}**Exhibit 19.** SDWIS/LabToState
Files To Archive

The Job Folders directory is archived to maintain a history of the XML
documents validated and prepared by SDWIS/LabToState at your site. The
properties directory is archived so that it may be used as a reference
to set the values during the configuration of SDWIS/LabToState.

**Note:** Since the values in the files contained in the properties
directory may have changed since the last release, use the current
values as a reference to update the values when the new release of the
application is installed.

### Remove Current Tomcat Release

Before installing the new release of Tomcat, the current release must be
removed from the application server. The following list describes the
tasks required to remove Tomcat from the application server:

1.  If Tomcat is installed as a batch job, you delete the file
    containing the Tomcat software. For a default installation of
    Tomcat, the default directory is c:\\jakarta-tomcat-5.0.28.

2.  If Tomcat is installed as a service, you should remove Tomcat by
    using Windows standard Add/Remove Programs utility, as described
    below:

```{=html}
<!-- -->
```
a.  From the Windows Start menu, select Settings/Control Panel/Add or
    Remove Programs. Exhibit 20 depicts the window displayed.

b.  Click on the Apache Tomcat program as illustrated in Exhibit 20 and
    click the **Change/Remove** button. Follow the prompts from Window's
    Add or Remove Programs utility.

![](media/image13.png){width="6.489583333333333in" height="4.71875in"}

[]{#__RefHeading___Toc154364586 .anchor}**Exhibit 20.** Remove Tomcat
--- Add or Remove Program Window

### Remove Java SDK

Before installing the new release of Java SDK, the current release must
be removed from the application server. The following list describes the
tasks required to remove Java SDK from the application server:

1.  From the Windows Start menu, select Settings/Control Panel/Add or
    Remove Programs. Exhibit 21 depicts the window displayed.

2.  Click on the Java 2 SDK program as illustrated in Exhibit 21 and
    click the **Remove** button. Follow the prompts from Window's Add or
    Remove Programs utility.

![](media/image14.png){width="6.489583333333333in"
height="4.697916666666667in"}

[]{#__RefHeading___Toc154364587 .anchor}**Exhibit 21.** Remove Java SDK
--- Add or Remove Program Window

### Install Supporting Software

After the existing versions Java SDK and Tomcat are removed from the
application server, the new releases of that software must be installed
using the installation procedures described in Section 3.2, Application
Server First Time Installation.

## Application Server First Time Installation

Exhibit 22 is a checklist of the steps required to install and configure
Java SDK and Tomcat for the first time. The remainder of this section
further describes each step in the installation procedures.

  ------------------------------------------------------------------------------
  **Supporting                                    
  Software First                                  
  Time                                            
  Installation                                    
  Checklist**                                     
  ---------------- ------------------------------ ------------------------------
  **Installation   **Installation Activity        **Installation Guide
  Step**           Description**                  Reference**

  1                Download the Java SDK          3.2.1 Download the Java SDK

  2                Install the Java SDK           3.2.2 Install the Java SDK

  3                Download Tomcat                3.2.3 Download Tomcat

  4                Install Tomcat                 3.2.4 Install Tomcat

  5                Increase Tomcat's Memory       3.2.5 Increase Tomcat's Memory
                   Allocation                     Allocation

  6                Complete Support Software      3.2.6 Complete Support
                   Installation                   Software Installation
  ------------------------------------------------------------------------------

[]{#__RefHeading___Toc154364588 .anchor}**Exhibit 22.** Supporting
Software First Time Installation Checklist

### Download the Java SDK

In first step of the installation procedures, download the Java 2 SDK,
Standard Edition (J2SE) 1.4.*x*, from Sun Microsystems web site (i.e.,
http://java.sun.com/j2se/1.4.2/download.html). Exhibit 23 depicts the
page that is presented. To download the Java SDK, click on the link that
is labeled "Download Windows J2SE SDK." The arrow in Exhibit 23
illustrates the location of this link on the page.

**Note:** The page format and navigation may change after publication of
this document.

![](media/image15.png){width="5.777777777777778in" height="7.24375in"}

[]{#__RefHeading___Toc154364589 .anchor}**Exhibit 23.** Java SDK
Download Page

### Install the Java SDK

To install the Java SDK, double-click on the installation package
downloaded in Step 1. Follow the instructions displayed in the
installation package and accept the default options. This installation
may take several minutes.

**Note:** The Java SDK must be installed in file folders that **DO NOT**
contain spaces. Spaces in the file folder or file name will cause errors
when calling the software from a DOS prompt.

### Download Tomcat

Download a release build of Tomcat 5.0.28 from Apache Software
Foundation's web site

( <http://jakarta.apache.org/>). The following task list describes the
page layout and navigation required to download the Tomcat Release
build; this layout and navigation, however, may change after publication
of this document:

Click on the link <http://jakarta.apache.org/site/binindex.cgi> to
display the Apache download page as depicted in Exhibit 24.

1.  Click on the Tomcat link; the location is noted with the arrow in
    Exhibit 24. Exhibit 25 depicts the page presented.

![](media/image16.png){width="6.489583333333333in"
height="4.074305555555555in"}

[]{#__RefHeading___Toc154364590 .anchor}**Exhibit 24.** Download Tomcat
from Apache Web Site

2.  In Exhibit 24, the Tomcat link is noted with the arrow. Click that
    link and follow the links labeled Tomcat 5 in the pages presented
    until the page depicted in Exhibit 26 is presented.

![](media/image17.png){width="6.489583333333333in"
height="3.0409722222222224in"}

[]{#__RefHeading___Toc154364591 .anchor}**Exhibit 25.** Download Tomcat
from Apache Web Site

3.  Click on the link labeled "Tomcat 5.x" located on the left side of
    the page under the label Download. Exhibit 26 depicts the page
    presented.

![](media/image18.png){width="6.489583333333333in"
height="2.6555555555555554in"}

[]{#__RefHeading___Toc154364592 .anchor}**Exhibit 26.** Download Tomcat
from Apache Web Site

4.  Click on the link labeled "5.0.28" located under the Quick
    Navigation section of the page. Exhibit 27 depicts the page
    presented.

![](media/image19.png){width="6.489583333333333in"
height="3.0541666666666667in"}

[]{#__RefHeading___Toc154364593 .anchor}**Exhibit 27.** Download Tomcat
from Apache Web Site

5.  Click on the link labeled "Windows Executable (pgp md5)" or "zip
    (pgp md5)" based on whether you want to run Tomcat as a service or
    in a DOS window. The link labeled "Windows Executable (pgp md5)"
    downloads a file that installs Tomcat to run as a service. The link
    labeled "zip (pgp md5)" downloads a file that installs Tomcat to run
    in a DOS window.

> **Note:** Tomcat may be installed to run as service or as a batch job.
> If Tomcat is installed as a service, it runs as a background task and
> must be started and shut down using service utilities. If Tomcat is
> installed as a batch job, it runs in a DOS window and must be started
> and stopped using batch files.

### Install Tomcat

To install Tomcat to run in a DOS window, double-click on the zip file
(downloaded in Step 3) to extract all files to the c drive. Make sure to
set the "Use Folder Names" checkbox on the WinZip Extraction window.
Failure to select this checkbox results in improper installation.

To install Tomcat as a service, double-click on the exe file (downloaded
in Step 3) and follow the installation instructions.

**Note:** Tomcat MUST be installed in file folders that **DO NOT**
contain spaces. Spaces in the file folder or file name will cause errors
when calling the software from a DOS prompt.

**Note:** The default directory for a Tomcat installation using the exe
file **MUST** be changed to a different directory structure (e.g.,
c:\\Tomcat5_0). Tomcat does not allow a path name sufficiently long
enough to support the default path in the Tomcat variables set during
SDWIS/LabToState installation.

### Increase Tomcat's Memory Allocation

If Tomcat is running in a DOS window, you increase its memory pool using
the Tomcat Monitoring Tool. To increase the memory allocation, complete
the following steps:

1.  From the Windows Start Menu, click Programs, Apache Tomcat, Monitor
    Tomcat. These actions insert an Apache icon in the System Tray as
    indicated by the arrow in Exhibit 28.

![](media/image20.png){width="2.4479166666666665in"
height="0.3645833333333333in"}

[]{#__RefHeading___Toc154364594 .anchor}**Exhibit 28.** Apache Icon in
the Desktop's System Tray

2.  Right click the Apache icon and select Configure, which displays the
    Apache Tomcat Properties window as depicted in Exhibit 29.

![](media/image21.png){width="4.354166666666667in"
height="4.208333333333333in"}

[]{#__RefHeading___Toc154364595 .anchor}**Exhibit 29.** Tomcat
Properties Window

3.  Enter 128 for the initial memory pool. Enter 512 for the maximum
    memory pool. Click **OK**, which sets the memory allocation
    parameters.

4.  Restart Tomcat, which allows the memory parameters to be
    established.

If Tomcat is running in a DOS window, you increase its memory pool by
assigning the following System Environment Variable:

1.  In the Environment Variables window, add a system variable named
    JAVA_OPTS with the value of the variable set to -Xms128m -Xmx512m.
    This variable assigns additional memory to the SDWIS/LabToState java
    application.

2.  Restart Tomcat, which allows the memory parameters to be
    established.

### Complete Support Software Installation

After completing the activities described in the above sections, the
installation of Java SDK and Tomcat is completed. You should return to
Step 3 of the SDWIS/LabToState first time installation procedures in
Section [2.2.2.3]{.mark}, Assign User Identification and Passwords.

# Site Customization Procedures

This section describes how to configure SDWIS/LabToState at your site.
It describes the text files used to assign various installation and
run-time parameters. It also describes procedures for constructing the
data files for submission to SDWIS/LabToState.

## Site Customization Files

To customize its deployment, SDWIS/LabToState uses several text files
and XML documents. SDWIS/LabToState does not offer any tools to
administer these files. You may use any standard text editor to modify
or change the content. All of the various configuration files are
located in the following directory:

Stand alone Client Application: *\[Unzipped
Folder\]*\\docBase\\web‑inf\\classes\\properties

Web Based Application:
*\[AppServerHome\]*\\webapps\\labtostate\\web‑inf\\classes\\properties

The following sections describe each configuration file.

### Site Properties File

The Site Properties File is a text file formatted as name/value pairs.
The System Administrator changes values in this file to reflect the
operational environment at a particular site. Appendix A lists the name,
description, and initial setting of each name/value pair. Column 2 (Set
By) of Appendix A indicates whether the value of the element is "Set By"
the software, system administrator, or through delivery (the file is
delivered with a value that should not be changed).

**Physical File Name:** siteProperties.txt

### User Identification XML Document

SDWIS/LabToState provides a default implementation of user
authentication. It is, however, anticipated that most states will
implement their own authentication utility. The default implementation
is provided to deliver an "out of the box" solution for initial start up
and testing. That default implementation uses an XML document to
identify each User ID and assign to it a password, role, PIN number, and
laboratory. Exhibit 30 lists the contents of the XML document delivered
with SDWIS/LabToState.

Each user is assigned one of two roles. A user assigned to the Lab role
is granted access to the sample data submitted by that laboratory. A
user assigned to the State role is granted access to all submissions
regardless of the laboratory.

To authorize a new user add the User ID, Password, PIN Number, and role
to the XML document as depicted in Exhibit 30. A PIN Number and
laboratory are not required if the user is assigned to the "State" role.

**Physical XML Document File Name:** userList.xml

![](media/image22.png){width="3.4791666666666665in"
height="3.8958333333333335in"}

[]{#__RefHeading___Toc154364596 .anchor}**Exhibit 30.** User
Authentication XML Document

### Release Statement File

The Release Statement File is a text file containing the text presented
to the user as he/she releases the XML document to SDWIS/XML Sampling.
This text will be presented on the Certification page.

**Physical File Name:** certificationStatement.txt

## Data File Content Configuration

SDWIS/LabToState provides a Data‑Source Plug‑In to receive sample data
formatted as comma separated values (CSV). The site configures the
content and order of the sample data contained in the CSV file. First,
the site identifies logical groupings of sample data referred to as
logical objects. Each logical object is based on one of the following
SDWIS/XML Sampling structure sets:

-   Sample

-   Sample Measure

-   Result

-   Sample Result Measure

-   Sample Summary

-   Sample Summary Result

-   MDBP Summary

The Object Configuration File is a text file that maps logical objects
to one and only one structure set. Each structure set, however, may be
mapped to multiple logical objects. For example, the site may identify a
logical object called TCRSample and map it to the Sample structure set.
The site may also identify a logical object called GeneralSample and map
it to the same Sample structure set. Even though both logical objects
(TCRSample and GeneralSample) map to the same Sample structure set, they
may contain different data in a different order. Exhibit 31 lists the
content of the Object Configuration File delivered with
SDWIS/LabToState.

**Physical File Name**: master.txt**.**

![](media/image23.png){width="6.520833333333333in" height="1.65625in"}

[]{#__RefHeading___Toc154364597 .anchor}**Exhibit 31.** Object
Configuration File

For each logical object identified in the Object Configuration File, the
Element Configuration File lists the elements and their order in the CSV
file. The element names are listed in the order in which they are
submitted in the CSV file. The name of the element is the Staging Table
Column Name as specified in the structure set documentation included in
the *SDWIS/XML Sampling Mapping Document and Accompanying Schemas*
*Document* (GSA‑SDWIS‑01‑8.d4d, December 30, 2005). The Element
Configuration File is a text file and the site creates a separate
Element Configuration File for each logical object. Using the above
example in which the site configured both a TCRSample and a
GeneralSample logical object, the site must also configure two Element
Configuration Files named TCRSample.txt and GeneralSample.txt. Exhibit
32 lists the Element Configuration Files delivered with
SDWIS/LabToState. Appendix B contains a list of the content of each
Object and Element Configuration file delivered with SDWIS/LabToState.
The physical name of the Element Configuration File is *\[logical
object\]*.txt.

  -----------------------------------------------------------------------
  **Element Configuration Files**

  mdbpSummary.txt

  result.txt

  sample.txt

  sampleMeasure.txt

  sampleResultMeasure.txt

  sampleSummary.txt

  sampleSummaryResult.txt
  -----------------------------------------------------------------------

[]{#__RefHeading___Toc154364598 .anchor}**Exhibit 32.** Element
Configuration Files

**Physical File Name:** *\[logicalobject\]*.txt

To configure your own CSV file content and order, you assign a logical
name, such as TCRSample, to the data you want to submit. You register
the logical name by adding it to the Object Configuration file and
assigning it to one of the SDWIS/XML Sampling Structure Sets, listed in
Exhibit 33. Then, you create a text file containing the list of elements
names representing the data to be submitted with that logical object.
Appendix C contains an Microsoft Excel spreadsheet that lists the
element names by business object. When you create the CSV file, the
first column of the line of text is the name of the object followed by
the data values for each of the elements named in the Element
Configuration file.

  -----------------------------------------------------------------------
  **SDWIS/XML Sampling Structure Sets**

  Sample

  SampleResult

  MDBPSummary

  SampleSummary

  SampleSummaryResult

  SampleMeasure

  SampleResultMeasure
  -----------------------------------------------------------------------

[]{#__RefHeading___Toc154364599 .anchor}**Exhibit 33.** SDWIS/XML
Sampling Structure Sets

Exhibit 34 depicts an example of a CSV file that conforms to the default
configuration delivered with SDWIS/LabToState. The first column in the
CSV file is always the name of the logical object being submitted. The
remainder of the line is the sample data in the order specified in the
Element Configuration File for that logical object. Also, if any
alphanumeric data contains spaces, the alphanumeric data must be
enclosed in quotation marks as depicted in the first line of Exhibit 34.
If the alphanumeric data does not contain spaces, the quotation marks
are optional as depicted in the remaining lines of Exhibit 34.

[]{#__RefHeading___Toc154364600
.anchor}![](media/image24.png){width="6.427083333333333in"
height="0.8541666666666666in"}**Exhibit 34.** Example of CSV File

## Data Source Registration File

The Data Registration File is a text file that maps the logical name of
each Data‑Source Plug‑In to the name of the Java class implementing the
functionality. The file is formatted as name value pairs. The name is
the logical name of the Data‑Source Plug‑In and is the value listed in
the drop‑down list on the Upload And Validate Page from which the user
selects the data format being uploaded. The logical name is mapped to
the Java class implementing the data source specification.

To register your own data source specifications, you must identify a
logical name and the Java class implementing your specification. The
example depicted in Exhibit 35 registers a new Data‑Source Plug‑In with
a logical name of "NewUserPlugIn." If this data source is selected from
the Upload and Validate page, SDWIS/LabToState invokes the
"com.sdwis.labtostate.generator.NewUserPlugIn". The registered Java
class must be copied to the appropriate library in the hierarchy
structure. For this example, that directory is
\[AppServerHome\]\\webapps\\labtostate\\web‑inf\\classes.

The Data‑Source Plug‑Ins delivered with SDWIS/LabToState and those
developed by the site must adhere to the interface specifications
documented in Appendix B.

**Physical File Name:** plugins.txt

![](media/image25.png){width="6.510416666666667in" height="1.96875in"}

[]{#__RefHeading___Toc154364601 .anchor}**Exhibit 35.** Data‑Source
Plug‑In Registration File

This page is intentionally left blank

**APPENDIX A**

Site Property File Name Descriptions

This page is intentionally left blank.

+----------------+---------------------------+-----------+------------+
| **SD           |                           |           |            |
| WIS/LabToState |                           |           |            |
| Site Property  |                           |           |            |
| Names and      |                           |           |            |
| Description**  |                           |           |            |
+================+===========================+===========+============+
| **Name**       | **Description**           | **Initial | **Set By** |
|                |                           | Setting** |            |
+----------------+---------------------------+-----------+------------+
| TurnOnEmail    | Contains an indicator     | true      | Email      |
|                | allowing a site to        |           | Adm        |
|                | eliminate the delivery of |           | inistrator |
|                | e‑mail messages after     |           |            |
|                | upload and validation.    |           |            |
|                | The permitted values for  |           |            |
|                | this property are "true"  |           |            |
|                | and "false."              |           |            |
+----------------+---------------------------+-----------+------------+
| EmailHost      | Contains the IP Address   | sdc-ex2   | Email      |
|                | of the SMTP (Simple Mail  |           | Adm        |
|                | Transfer Protocol) Mail   |           | inistrator |
|                | Server.  This value is    |           |            |
|                | used to connect to the    |           |            |
|                | mail server in automate   |           |            |
|                | the delivery of e‑mails.  |           |            |
|                | This value must be set    |           |            |
|                | during installation.      |           |            |
+----------------+---------------------------+-----------+------------+
| EmailPort      | Contains the port number  | 25        | Email      |
|                | of the e‑mail server.     |           | Admi       |
|                | The default value of 25   |           | nisttrator |
|                | is used for a standard    |           |            |
|                | e-mail server             |           |            |
|                | installation.  For        |           |            |
|                | non-standard e-mail       |           |            |
|                | server installations,     |           |            |
|                | this value should be      |           |            |
|                | changed to the port       |           |            |
|                | number of the e-mail      |           |            |
|                | server.  This value is    |           |            |
|                | set during installation   |           |            |
|                | and can be changed by the |           |            |
|                | System Administrator.     |           |            |
+----------------+---------------------------+-----------+------------+
| EmailAuthenti  | Contains an indicator     | false     | Email      |
| cationRequired | allowing a site to        |           | Adm        |
|                | require e‑mail            |           | inistrator |
|                | authentication.  The      |           |            |
|                | permitted values for this |           |            |
|                | property are "true" and   |           |            |
|                | "false."  This value is   |           |            |
|                | set during installation   |           |            |
|                | and can be changed by the |           |            |
|                | System Administrator.     |           |            |
+----------------+---------------------------+-----------+------------+
| EmailUserid    | Contains the user name    | \<no      | Email      |
|                | that must be supplied if  | value\>   | Adm        |
|                | the e‑mail server         |           | inistrator |
|                | requires authentication.  |           |            |
|                | If e‑mail server does not |           |            |
|                | require authentication,   |           |            |
|                | the value is set to       |           |            |
|                | null.  This value is set  |           |            |
|                | during installation and   |           |            |
|                | can be changed by the     |           |            |
|                | System Administrator.     |           |            |
+----------------+---------------------------+-----------+------------+
| EmailPassword  | Contains the Password     | \<no      | Email      |
|                | that must be supplied if  | value\>   | Adm        |
|                | the e‑mail server         |           | inistrator |
|                | requires authentication.  |           |            |
|                | If e‑mail server does not |           |            |
|                | require authentication,   |           |            |
|                | the value is set to       |           |            |
|                | null.  This value is set  |           |            |
|                | during installation and   |           |            |
|                | can be changed by the     |           |            |
|                | System Administrator.     |           |            |
+----------------+---------------------------+-----------+------------+
| Em             | Contains the e‑mail       | L         | Email      |
| ailFromAddress | address for the           | abToState | Adm        |
|                | SDWIS/LabToState          |           | inistrator |
|                | administrator.  This      |           |            |
|                | e‑mail address is used to |           |            |
|                | send e‑mails.             |           |            |
+----------------+---------------------------+-----------+------------+
| DateFormat     | Contains a mask           | M         | System     |
|                | indicating the format in  | M/dd/yyyy | Adm        |
|                | which date values are     |           | inistrator |
|                | submitted.  The default   |           |            |
|                | mask is MM/dd/yyyy.       |           |            |
+----------------+---------------------------+-----------+------------+
| TimeFormat     | Contains a mask           | HHmmss    | System     |
|                | indicating the format in  |           | Adm        |
|                | which time values are     |           | inistrator |
|                | submitted.  The default   |           |            |
|                | mask is hhmmss.           |           |            |
+----------------+---------------------------+-----------+------------+
| DatabaseD      | Contains the JDBC-ODBC    | s         | This value |
| riverClassName | bridge class name, which  | un.jdbc.o | can be     |
|                | connects to the client's  | dbc.JdbcO | overriden  |
|                | database using the ODBC   | dbcDriver | by the     |
|                | data source.  This value  |           | Database   |
|                | must not be changed. If   |           | Adm        |
|                | the site is running on    |           | inistrator |
|                | UNIX, this value can be   |           |            |
|                | changed to the jdbc       |           |            |
|                | driver class name (Refer  |           |            |
|                | to your local database    |           |            |
|                | manual for "connecting    |           |            |
|                | using jdbc").             |           |            |
|                |                           |           |            |
|                |                           |           |            |
|                |                           |           |            |
|                | sun                       |           |            |
|                | .jdbc.odbc.JdbcOdbcDriver |           |            |
+----------------+---------------------------+-----------+------------+
| Databas        | Contains the string used  | jdbc:o    | This value |
| eConnectionURL | to establish a database   | dbc:SDWIS | can be     |
|                | connection The default    |           | overriden  |
|                | DSN name is set to SDWIS. |           | by the     |
|                | If the site is using a    |           | Database   |
|                | different DSN then this   |           | Adm        |
|                | value must be changed. If |           | inistrator |
|                | the site is running on    |           |            |
|                | UNIX, this value can be   |           |            |
|                | changed to the jdbc       |           |            |
|                | connection url (Refer to  |           |            |
|                | your local database       |           |            |
|                | manual for "connecting    |           |            |
|                | using jdbc").             |           |            |
|                |                           |           |            |
|                |                           |           |            |
|                |                           |           |            |
|                | jdbc:odbc:SDWIS           |           |            |
+----------------+---------------------------+-----------+------------+
| DatabaseUserID | Contains the User ID used | XML       | Database   |
|                | to connect to the         | SAMPLER10 | Adm        |
|                | client's database schema. |           | inistrator |
|                | This value must be set    |           |            |
|                | during installation if    |           |            |
|                | the site is using the SQL |           |            |
|                | Plug-in.                  |           |            |
+----------------+---------------------------+-----------+------------+
| Da             | Contains the Password     | XML       | Database   |
| tabasePassword | used to connect to the    | SAMPLER10 | Adm        |
|                | client's database schema. |           | inistrator |
|                | This value must be set    |           |            |
|                | during installation if    |           |            |
|                | the site is using the SQL |           |            |
|                | Plug-in.                  |           |            |
+----------------+---------------------------+-----------+------------+
| PasswordAuth   | Contains the name of the  | com       | This value |
| enticatorClass | Java class used to        | .sdwis.la | can be     |
|                | authenticate User IDs and | btostate. | overriden  |
|                | Passwords.  If the site   | utility.D | by the     |
|                | implements its own        | efaultPas | System     |
|                | authentication utilities, | swordAuth | Adm        |
|                | the implementation must   | enticator | inistrator |
|                | follow the interface      |           |            |
|                | specifications documented |           |            |
|                | in the SDWIS/LabToState   |           |            |
|                | Installation Guide.       |           |            |
|                | SDWIS/LabToState includes |           |            |
|                | a default implementation  |           |            |
|                | of user authentication in |           |            |
|                | the Java class            |           |            |
|                | com.sdwi                  |           |            |
|                | s.labtostate.utility.Defa |           |            |
|                | ultPasswordAuthenticator. |           |            |
+----------------+---------------------------+-----------+------------+
| PINAuth        | Contains the name of the  | com.sdw   | This value |
| enticatorClass | Java class used to verify | is.labtos | can be     |
|                | a User's PIN Number.  If  | tate.util | overriden  |
|                | the site implements its   | ity.Defau | by the     |
|                | own PIN Number            | ltPINAuth | System     |
|                | verification utilities,   | enticator | Adm        |
|                | the implementation must   |           | inistrator |
|                | follow the interface      |           |            |
|                | specifications documented |           |            |
|                | in the SDWIS/LabToState   |           |            |
|                | Installation Guide.       |           |            |
|                | SDWIS/LabToState includes |           |            |
|                | a default implementation  |           |            |
|                | of user PIN Number        |           |            |
|                | verification in the Java  |           |            |
|                | class                     |           |            |
|                | com                       |           |            |
|                | .sdwis.labtostate.utility |           |            |
|                | .DefaultPINAuthenticator. |           |            |
+----------------+---------------------------+-----------+------------+
| NodeURL        | Contains the URL to the   | [         | Node       |
|                | State Node offering the   | [http://l | Adm        |
|                | web services defined by   | ocalhost: | inistrator |
|                | the WSDL document.  This  | 10000/DNC |            |
|                | parameter must be used    | /services |            |
|                | when using the State Node | /NetworkN |            |
|                | for integrating with      | odePortTy |            |
|                | SDWIS/XMLSampling.        | pe_V10]{. |            |
|                |                           | underline |            |
|                |                           | }](http:/ |            |
|                |                           | /localhos |            |
|                |                           | t:10000/D |            |
|                |                           | NC/servic |            |
|                |                           | es/Networ |            |
|                |                           | kNodePort |            |
|                |                           | Type_V10) |            |
+----------------+---------------------------+-----------+------------+
| NodeUserId     | Contains the UserID       | \<no      | Node       |
|                | required to connect to    | value\>   | Adm        |
|                | the State Node.  This     |           | inistrator |
|                | parameter must be used    |           |            |
|                | when using the State Node |           |            |
|                | for integrating with      |           |            |
|                | SDWIS/XMLSampling.        |           |            |
+----------------+---------------------------+-----------+------------+
| NodePassword   | Contains the password     | \<no      | Node       |
|                | used to connect to the    | value\>   | Adm        |
|                | State Node.  This         |           | inistrator |
|                | parameter must be used    |           |            |
|                | when using the State Node |           |            |
|                | for integrating with      |           |            |
|                | SDWIS/XMLSampling.        |           |            |
+----------------+---------------------------+-----------+------------+
| DataFlowNam    | This value will be used   | XM        | Node       |
| eForWebService | as the dataflow name when | LSampling | Adm        |
|                | invoking the web          |           | inistrator |
|                | service.  This parameter  |           |            |
|                | must be used when using   |           |            |
|                | the State Node for        |           |            |
|                | integrating with          |           |            |
|                | SDWIS/XMLSampling.        |           |            |
+----------------+---------------------------+-----------+------------+
| XMLSamplingI   | Contains the name of the  | com.sd    | System     |
| ntegratorClass | Java class that delivers  | wis.labto | Adm        |
|                | the XML documents to the  | state.uti | inistrator |
|                | State Node, which in turn | lity.XMLS |            |
|                | delivers the XML document | amplingFi |            |
|                | to SDWIS/XMLSampling.     | leSystemI |            |
|                | This name/value pair and  | ntegrator |            |
|                | the name/value pairs that |           |            |
|                | identify the SDWIS/XML    |           |            |
|                | Sampling Inbox are        |           |            |
|                | mutually exclusive.       |           |            |
|                | Therefore, for delivery,  |           |            |
|                | this name/value pair is   |           |            |
|                | commented.  To implement  |           |            |
|                | this feature, you remove  |           |            |
|                | the comment from this     |           |            |
|                | line and comment the      |           |            |
|                | lines associated with the |           |            |
|                | SDWIS/XML Sampling Inbox  |           |            |
|                | (SDWIS_EDWR_Inbox,        |           |            |
|                | Sample_Summary_Inbox,     |           |            |
|                | Sam                       |           |            |
|                | ple_Summary_Result_Inbox, |           |            |
|                | and MDBP_Summary_Inbox).  |           |            |
+----------------+---------------------------+-----------+------------+
| SD             | Contains the full path    | C:\\\\    | System     |
| WIS_EDWR_Inbox | and folder name of the    | jakarta-t | Adm        |
|                | SDWIS eDWR XML Document   | omcat-5.0 | inistrator |
|                | Inbox used by SDWIS/XML   | .28\\\\we |            |
|                | Sampling.  This           | bapps\\\\ |            |
|                | name/value pair and the   | XMLSampli |            |
|                | name/value pair           | ng\\\\Sam |            |
|                | (XM                       | pleFolder |            |
|                | LSamplingIntegratorClass) |           |            |
|                | that identifies the Java  |           |            |
|                | Class for the State Node  |           |            |
|                | submission are mutually   |           |            |
|                | exclusive.  Therefore, if |           |            |
|                | you implement the State   |           |            |
|                | Node approach to          |           |            |
|                | SDWIS/XML Sampling        |           |            |
|                | integration, you must     |           |            |
|                | comment this line and     |           |            |
|                | remove the comment from   |           |            |
|                | the                       |           |            |
|                | X                         |           |            |
|                | MLSamplingIntegratorClass |           |            |
|                | line.                     |           |            |
+----------------+---------------------------+-----------+------------+
| Sample         | Contains the full path    | C:\\\\j   | System     |
| _Summary_Inbox | and folder name of the    | akarta-to | Adm        |
|                | SDWIS Sample Summary XML  | mcat-5.0. | inistrator |
|                | Document Inbox used by    | 28\\\\web |            |
|                | SDWIS/XML Sampling.  This | apps\\\\X |            |
|                | name/value pair and the   | MLSamplin |            |
|                | name/value pair           | g\\\\Summ |            |
|                | (XM                       | aryFolder |            |
|                | LSamplingIntegratorClass) |           |            |
|                | that identifies the Java  |           |            |
|                | Class for the State Node  |           |            |
|                | submission are mutually   |           |            |
|                | exclusive.  Therefore, if |           |            |
|                | you implement the State   |           |            |
|                | Node approach to          |           |            |
|                | SDWIS/XML Sampling        |           |            |
|                | integration, you must     |           |            |
|                | comment this line and     |           |            |
|                | remove the comment from   |           |            |
|                | the                       |           |            |
|                | X                         |           |            |
|                | MLSamplingIntegratorClass |           |            |
|                | line.                     |           |            |
+----------------+---------------------------+-----------+------------+
| Sample_Summar  | Contains the full path    | C:\\      | System     |
| y_Result_Inbox | and folder name of the    | \\jakarta | Adm        |
|                | SDWIS Summary Result XML  | -tomcat-5 | inistrator |
|                | Document Inbox used by    | .0.28\\\\ |            |
|                | SDWIS/XML Sampling.  This | webapps\\ |            |
|                | name/value pair and the   | \\XMLSamp |            |
|                | name/value pair           | ling\\\\S |            |
|                | (XM                       | ummaryRes |            |
|                | LSamplingIntegratorClass) | ultFolder |            |
|                | that identifies the Java  |           |            |
|                | Class for the State Node  |           |            |
|                | submission are mutually   |           |            |
|                | exclusive.  Therefore, if |           |            |
|                | you implement the State   |           |            |
|                | Node approach to          |           |            |
|                | SDWIS/XML Sampling        |           |            |
|                | integration, you must     |           |            |
|                | comment this line and     |           |            |
|                | remove the comment from   |           |            |
|                | the                       |           |            |
|                | X                         |           |            |
|                | MLSamplingIntegratorClass |           |            |
|                | line.                     |           |            |
+----------------+---------------------------+-----------+------------+
| DMBP           | Contains the full path    | C:        | System     |
| _Summary_Inbox | and folder name of the    | \\\\jakar | Adm        |
|                | SDWIS MDBP Summary XML    | ta-tomcat | inistrator |
|                | Document Inbox used by    | -5.0.28\\ |            |
|                | SDWIS/XML Sampling.  This | \\webapps |            |
|                | name/value pair and the   | \\\\XMLSa |            |
|                | name/value pair           | mpling\\\ |            |
|                | (XM                       | \MDBPSumm |            |
|                | LSamplingIntegratorClass) | aryFolder |            |
|                | that identifies the Java  |           |            |
|                | Class for the State Node  |           |            |
|                | submission are mutually   |           |            |
|                | exclusive.  Therefore, if |           |            |
|                | you implement the State   |           |            |
|                | Node approach to          |           |            |
|                | SDWIS/XML Sampling        |           |            |
|                | integration, you must     |           |            |
|                | comment this line and     |           |            |
|                | remove the comment from   |           |            |
|                | the                       |           |            |
|                | X                         |           |            |
|                | MLSamplingIntegratorClass |           |            |
|                | line.                     |           |            |
+----------------+---------------------------+-----------+------------+

**APPENDIX B**

Object and Element Configuration Files

This page is intentionally left blank.

**Sample Object**

![](media/image26.png){width="6.5in" height="5.875in"}

**Sample Measure Object**

![](media/image27.png){width="6.5in" height="1.9895833333333333in"}

**Result Object**

![](media/image28.png){width="6.5in" height="5.177083333333333in"}

**Sample Result Measure Object**

![](media/image29.png){width="6.5in" height="2.4375in"}

**Sample Summary Object**

![](media/image30.png){width="6.5in" height="2.6041666666666665in"}

**Sample Summary Result Object**

![](media/image31.png){width="6.5in" height="2.34375in"}

**MDBP Summary Object**

![](media/image32.png){width="6.5in" height="5.177083333333333in"}

This page is intentionally left blank.

**APPENDIX C**

Element Names by Object

This page is intentionally left blank.

**Click on the icon below to use viewing the electronic file for
Appendix C**

![](media/image33.wmf)

This page is intentionally left blank.

**APPENDIX D**

Interface Specifications

This page is intentionally left blank.

**Data‑Source Plug‑Ins Interface Specifications**

To implement a Data‑Source Plug‑In, the implementer will complete the
following steps to create, register, and integrate it with
SDWIS/LabToState.

**STEP 1:** **Develop a site-specific Data‑Source Plug‑in**

The Java class that implements the site-specific Data‑Source Plug‑In
extends an abstract class delivered with the standard SDWIS/LabToState
software. The abstract class is com.sdwis.labtostate.generator.Plugin.
The new Java class implements one method with the following signature:

public abstract void execute(UIStructure structure) throws Exception;

The argument passed to this method is the UIStructure class, which
contains all the data entered by the user in the upload and validate
page. It is the responsibility of the concrete data source plugin class
to create the DataObject class for each logical business object for
which it is receiving data. The DataObject class contains an attribute
command which holds the name of the logical business object and a string
array containing the data values in the order specified by the Element
Configuration File. The abstract class provides a pointer to the
handler, which the custom class uses to invoke the XML Generation tool
of the SDWIS/LabToState application. After the new Java class creates
the DataObject, it invoked the handler's processObject method denoted by
the following method signature:

abstract public void processObject(DataObject object) throws Exception;

After creating and processing all the DataObjects, the new Java class
creates a special DataObject containing the "Marshall" command. This
command notifies the handlers to create the XML documents from the
in-memory representation of the DataObjects and to invoke the XML
Validation tool to check the XML documents against the XML Schemas.

**STEP 2: Copy the site-specific Data‑Source Plug‑in**

The user copies the compiled java classes under the WEB-INF/classes
folder or creates a jar file from the compiled classes and copies the
jar file to the WEB-INF/lib folder. This step makes the site-specific
Data‑Source Plug‑In available to the SDWIS/LabToState application
allowing it to dynamically invoke site-specific implementations.

**STEP 3: Register the site‑specific Data‑Source Plug‑In**

To register the Data‑Source Plug‑In with SDWIS/LabToState, add a new
entry to the plugins.txt file in the properties folder. The new entry
contains a user-friendly logical name and the fully qualified java class
name of the custom data source implementation. The user‑friendly name is
listed as a new option under the file format in the upload and validate
page.

**User Authentication Interface Specifications**

To implement a site-specific User Authentication routine, the
implementer will complete the following steps to create, register, and
integrate it with SDWIS/LabToState.

**STEP 1:** **Create the site‑specific User Authentication
implementation**

The custom user authentication implementation class implements the
com.sdwis.labtostate.utility.PasswordAuthenticator interface class. The
concrete class implements one method with the following signature:

public boolean authenticate(String userName, String password) throws
Exception;

The arguments passed to this method contain the username and password
entered by the user in the login page. The implementation class can
validate this information using its own logic by accessing the local
user repository (eg., Windows NT, LDAP etc). The return type from this
method is a boolean indicating whether the user was successfully
authenticated.

**STEP 2: Copy the site‑specific User Authentication implementation**

The user copies the compiled java classes under the WEB-INF/classes
folder or creates a jar file from the compiled classes and copies the
jar file to the WEB-INF/lib folder. This step makes the site-specific
User Authentication implementation available to the SDWIS/LabToState
application allowing it to dynamically invoke site-specific
implementations.

**STEP 3: Register the site‑specific User Authentication
implementation**

The user updates the siteProperties.txt file in the properties folder to
change the value of the PasswordAuthenticatorClass property to contain
the name of the newly created custom class. The value must be the fully
qualified java class name of the custom implementation class.

The user changes the value of the PasswordAuthenticatorClass property in
the siteProperties.txt file in the properties folder. The value contains
the name of the newly created custom class. The value must be the fully
qualified java class name of the custom implementation class.

**PIN Authentication Interface Specifications**

To implement a site-specific PIN Authentication routine, the implementer
will complete the following steps to create, register, and integrate it
with SDWIS/LabToState.

**STEP 1:** **Create the site-specific PIN authentication
implementation**

The custom PIN authentication implementation class implements the
com.sdwis.labtostate.utility.PasswordAuthenticator interface class. The
concrete class implements one method with the following signature:

public boolean validatePIN(String userName, String laboratory, String
PIN) throws Exception;

The arguments passed to this method contain the username, laboratory,
and the PIN entered by the user on the certification page. The
implementation class validates this information using its own logic to
verify the PIN number for a specific user. The return type from this
method is a boolean indicating whether the PIN was successfully
verified.

**STEP 2: Copy the site‑specific PIN Authentication implementation**

The user copies the compiled java classes under the WEB-INF/classes
folder or creates a jar file from the compiled classes and copies the
jar file to the WEB-INF/lib folder. This step will make the site
specific PIN Authentication available to SDWIS/LabToState application
allowing it to dynamically invoke site-specific implementation.

**STEP 3: Register the custom PIN authentication class to the LabToState
application**

The user changes the value of the PINAuthenticatorClass property in the
siteProperties.txt file in the properties folder. The value contains the
name of the newly created custom class. The value must be the fully
qualified java class name of the custom implementation class.