Water Quality Exchange
Flow Configuration Document
Version 3.0
October 1, 2019
Developed for:
United States Environmental Protection Agency
Office of Environmental Information
1200 Pennsylvania Avenue, NW
Washington, DC 20460
Developed by:
Gold Systems, I no
2121 S. McClelland St., #204
Salt Lake City, Utah 84106
Environmental Information
exchange
^-Network
-------
Water Quality Exchange - Flow Configuration Document
Table of Contents
1.0 INTRODUCTION 1
1.1 Background 1
1.2 Document Purpose 1
1.3 How TO USE THIS FCD 1
2.0 COMPONENT ALIGNMENT AND CHANGE HISTORY 3
2.1 Flow Component Version History 3
2.2 Flow Component Versions Currently Supported 5
2.3 Business Rule Change History 6
3.0 IMPLEMENTING THE HEADER DOCUMENT 8
3.1 Overview 8
3.2 Header Document Structure 8
3.3 Submission File Structure 10
3.4 Payload 10
4.0 DATA PROCESSING 12
4.1 Update-Insert (WQX) 12
4.2 Update-Insert (WQX Update Identifiers) 20
4.3 Delete 21
5.0 SUBMISSION PROCESSING AND FEEDBACK 23
6.0 QUERY PROCESSING AND FEEDBACK 25
6.1 Query Process 25
6.2 Solicit Process 25
7.0 WEB SERVICE METHODS AT CDX 26
7.1 Endpoints 26
7.2 Authenticate 26
7.3 Submit 26
7.4 GetStatus 27
7.5 Download 27
7.6 Query 28
7.7 Solicit 28
8.0 DATA SERVICES (QUERY/SOLICIT) 28
11
-------
Water Quality Exchange - Flow Configuration Document
111
-------
Water Quality Exchange - Flow Configuration Document
1.0 Introduction
1.1 Background
The U.S. Environmental Protection Agency (EPA) Office of Information Collection (OIC), Office of Wetlands, Oceans and
Watersheds (OWOW), and Office of Water (OW) are committed to implementing Central Data Exchange (CDX) services and
establishing the EPA infrastructure to support an ambient water quality monitoring data exchange. The Water Quality
Exchange project is the product of a collaborative effort between OIC, OW, and the Environmental Council of States (ECOS).
The project was identified during the development of the Environmental Sampling Analysis and Results (ESAR) data
standard for water monitoring.
The project goal is to provide EPA state partners with a means of exchanging water quality monitoring data via CDX, utilizing
the ESAR data standard as much as possible. The Office of Water, in partnership with the states, establishes water quality
monitoring data exchange elements, business rules for exchanging these elements, and valid domain lists for elements not
covered by an existing or proposed standard.
The WQX System includes the following types of data:
• The physical conditions in the environment at the time of a site visit.
• The chemical and bacteriological make-up of the water sampled.
• Chemical analyses offish tissue collected.
• Biological Taxon Abundance data, including population census, frequency class, group summaries, and individual
results
• Toxicity data.
• Habitat Assesment scores and their related metric scores.
• Biological Index scores and their related metric scores.
The WQX data flow utilizes two mechanisms for exchanging water quality monitoring information:
• Web services-based solution for automated submission utilizing Exchange Network standards.
• Web-based solution for manual submissions (WQX Web).
1.2 Document Purpose
This Flow Configuration Document (FCD) is intended to define the supported data services, the approaches and processes
that are used to exchange information over the Exchange Network via web services technology. In addition, the FCD serves
as a guide for trading partners in understanding the details and challenges associated with a data flow.
The purpose of this FCD is to describe the operation of the Water Quality Monitoring Network Exchange using XML-based
data submissions through Node-to-Node or Client-to-Node transfers. This document does not consider use of the alternative
ESAR formats or transfer mechanisms. The focus of the document is the core WQX data flow between the state, local, and
tribal agencies and EPA.
The Office of Water is separately committed to providing outbound services from the WQP (Water Quality Portal), which
combines WQX (Water Quality Exchange), United States Geological Survey (USGS), and National Water Quality Monitoring
Council (NWQMC) data. These data services are outside the scope of this document.
1.3 How to use this FCD
This FCD provides guidance to implement an XML/web-service based model for data submission. For the WQX project,
there are two types of submissions, Update-Insert and Delete. This FCD expands upon the usage of the WQX Schema and
introduces the implementation of the Document Header.
This document includes the following main sections:
Implementing the Header Document
This section describes how the WQX Network Exchange makes use of the Exchange Network Header Document to
describe the payload content of a Network message. This submission structure is used for both Node-to-Node and
Client-to-Node submissions as well as the web submission (WQX Web).
Data Processing
This section describes the data processing rules in effect in the WQX System.
l
-------
Water Quality Exchange - Flow Configuration Document
Submission Processing and Feedback
This section describes the processing steps and status changes that occur as your submission flows through CDX and
the WQX System.
Web Service Methods at CDX
This section describes the Web Service Methods at CDX used by the WQX Data Flow.
2
-------
Water Quality Exchange - Flow Configuration Document
2.0 Component Alignment and Change History
2.1 Flow Component Version History
Component
Version
Date
Changed
By
Description of
Change
Flow Configuration Document (FCD)
1.0
11/15/2006
Ryan
Jorgensen
Original Version
Schema
1.0
1/19/2007
Doug
Timms
Original Version
Data Exchange Template (DET)
1.0
1/19/2007
Doug
Timms
Original Version
GetActivityByParameters data service
1.0
2/1/2007
Ryan
Jorgensen
Original Version
GetActivityGroupByParameters data
service
1.0
2/1/2007
Ryan
Jorgensen
Original Version
GetMonitoringLocationByParameters
data service
1.0
2/1/2007
Ryan
Jorgensen
Original Version
GetProjectByParameters data service
1.0
2/1/2007
Ryan
Jorgensen
Original Version
GetResultByParameters data service
1.0
2/1/2007
Ryan
Jorgensen
Original Version
GetDomainValueByElementName data
service
1.0
2/1/2007
Ryan
Jorgensen
Original Version
GetTransactionHistoryByParameters
data service
1.0
2/1/2007
Ryan
Jorgensen
Original Version
FCD
2.0
06/20/2008
Ryan
Jorgensen
Major revision for
WQX 2.0
Schema
2.0
06/04/2008
Doug
Timms
Major revision for
WQX 2.0
DET
2.0
06/04/2008
Doug
Timms
Major revision for
WQX 2.0
GetActivityByParameters data service
2.0
07/10/2008
Ryan
Jorgensen
Added support for
new WQX 2.0
elements
GetActivityGroupByParameters data
service
2.0
07/10/2008
Ryan
Jorgensen
Changed schema
reference to wqx/2.
No other changes.
GetBiologicalHabitatlndexByParameters
data service
2.0
07/10/2008
Ryan
Jorgensen
New data service for
WQX 2.0
GetMonitoringLocationByParameters
data service
2.0
07/10/2008
Ryan
Jorgensen
Added support for
new WQX 2.0
elements
GetProjectByParameters data service
2.0
07/10/2008
Ryan
Jorgensen
Added support for
new WQX 2.0
3
-------
Water Quality Exchange - Flow Configuration Document
elements
GetResultByParameters data service
2.0
07/10/2008
Ryan
Jorgensen
Added support for
new WQX 2.0
elements
GetDomainValueByElementName data
service
2.0
07/10/2008
Ryan
Jorgensen
Changed schema
reference to wqx/2
and added new 2.0
domain value lists.
GetTransactionHistoryByParameters
data service
2.0
07/10/2008
Ryan
Jorgensen
Changed schema
reference to wqx/2.
No other changes.
FCD
2.1
11/11/2009
Ryan
Jorgensen
Minor revision for
WQX 2.1
Schema
2.1
11/11/2009
Ryan
Jorgensen
Increased max
length on some
elements
DET
2.1
11/11/2009
Ryan
Jorgensen
Increased max
length on some
elements
GetActivityByParameters data service
2.1
11/11/2009
Ryan
Jorgensen
Increased max
length on some
elements
GetActivityGroupByParameters data
service
2.1
11/11/2009
Ryan
Jorgensen
No Change
GetBiologicalHabitatlndexByParameters
data service
2.1
11/11/2009
Ryan
Jorgensen
Increased max
length on some
elements
GetMonitoringLocationByParameters
data service
2.1
11/11/2009
Ryan
Jorgensen
Increased max
length on some
elements
GetProjectByParameters data service
2.1
11/11/2009
Ryan
Jorgensen
Increased max
length on some
elements
GetResultByParameters data service
2.1
11/11/2009
Ryan
Jorgensen
Increased max
length on some
elements
GetDomainValueByElementName data
service
2.1
11/11/2009
Ryan
Jorgensen
No Change
GetTransactionHistoryByParameters
data service
2.1
11/11/2009
Ryan
Jorgensen
No Change
FCD
2.1b
06/12/2012
Ryan
Jorgensen
Changed max
submission file size
to 350MB
(unzipped).
Changed rule #15.
Corrected parameter
spelling
organizationldentifer
4
-------
Water Quality Exchange - Flow Configuration Document
to
organizationldentifier
FCD
2.1c
10/15/2015
Ryan
Jorgensen
Revised section 4 to
clarify WQX
behavior with
respect to updating
existing data
FCD
2.2
10/01/2019
Rick
Cooke
Major revision for
WQX 3 .0
Schema
2.2
10/01/2019
Rick
Cooke
Added new
elements.
Rearranged elements
within schema.
DET
2.2
10/01/2019
Rick
Cooke
Added new elements
FCD
2.2
10/01/2019
Rick
Cooke
Replaced STORET
data warehouse
references to the
Water Quality Portal
(WQP)
2.2 Flow Component Versions Currently Supported
Component
Version(s)
Supported
Explanation (optional)
FCD
3.0
Schema
1.0, 2.0, 2.1, 2.2,
and 3.0
1.0,2.0,2.1,2.2, and 3.0
supported for data submissions.
Most data services (i.e.
query/solicit) only support
WQX 2.0, 2.1, 2.2, and 3.0
DET
1.0, 2.0, 2.1, 2.2,
3.0
GetActivityByParameters data service
2.0,2.1,2.2,3.0
GetActivityGroupByParameters data
service
2.0,2.1,2.2,3.0
GetBiologicalHabitatlndexByParameters
data service
2.0,2.1,2.2,3.0
GetMonitoringLocationByParameters
data service
2.0,2.1,2.2,3.0
GetProjectByParameters data service
2.0,2.1,2.2, 3.0
GetResultByParameters data service
2.0,2.1,2.2,3.0
GetDomainValueByElementName data
service
1.0, 2.0, 2.1, 2.2,
3.0
GetTransactionHistoryByParameters
1.0, 2.0, 2.1, 2.2,
5
-------
Water Quality Exchange - Flow Configuration Document
data service
3.0
2.3 Business Rule Change History
Business Rule Change
Date of Change
Explanation (optional)
When SampleTissueTaxonomicName or
SampleTissueAnatomyName is reported,
both must be reported.
WQX 2.0 (July
2008)
Rule dropped
When ResultDetectionConditionText is 'Not
Detected',
DetectionQuantitationLimitTypeName and
DetectionQuantitationLimitMeasure must
be reported
WQX 2.0 (July
2008)
Expanded to include 'Present
Above Quantification Limit' and
'Present Below Quantification
Limit'
Element name for
"SampleTissueT axonomicName" was
changed to "SubjectTaxonomicName" in
WQX 2.0.
WQX 2.0 (July
2008)
SampleTissueTaxonomicName
and
SampleTissueAnatomyName
moved from being part of an
Activity in WQX 1.0 to part of a
Result in WQX 2.0. Taxonomic
Name is no longer only used
for tissue samples so the name
was changed to
SubjectTaxonomicName
Additional Business Rules have been
created that relate to new elements in
WQX 2.0.
WQX 2.0 (July
2008)
See section 4.1.1 for a
complete list of rules.
Rule #15 changed to "CharacteristicName
and ResultStatusldentifier must be
reported"
WQX 2.1 (June
2012)
Rule #31 added: "Biological Intent Name
and Subject Taxonomic Name must be
reported when Activity Media Name is
'Biological' or 'Tissue'"
WQX 2.0 (July
2008)
Rule has been in place, since
WQX Web 2.0, but was not
documented until FCD 2.1 d
Rule #25 dropped: If Net Information is
reported then the NetSurfaceAreaMeasure
or NetMeshSizeMeasure are required.
WQX 3.0
(December 2016)
Rule dropped
Rule #22 dropped: If Sample Preparation
block is reported, then either
ChemicalPreservativeUsedName or
ThermalPreservativeUsedName must be
reported.
WQX 2.2 (January
2017)
Rule dropped
Rule #9 dropped: When ActivityTypeCode
contains the word 'Sample',
SampleCollectionMethod must be
reported.
WQX 2.2 (January
2017)
Rule dropped
Rule #14 dropped: Either ResultMeasure's
ResultMeasureValue or
ResultDetectionConditionText must be
reported, but not both.
WQX 2.2 (January
2017)
Rule dropped
Dropped Domain Value:
WQX 2.2 (January
Domain Value Dropped
6
-------
Water Quality Exchange - Flow Configuration Document
METRICTYPECONTEXT from
GetDomainValueByElementName data
service
2017)
Rule#26 modified: If BiologicallntentName
is "Group Summary" then
GroupSummaryCount or
GroupSummaryWeightMeasure must be
reported
WQX 2.2 (October
2019)
Rule description modified
Either Result Measure Value and/or Result
Detection Condition Text must be reported
WQX 2.2 (October
2019)
Rule added
Measure Unit is required when Measure
Value is supplied
WQX 2.2 (October
2019)
Rule Noted
Measure Value is required when
Measurement Unit is supplied
WQX 2.2 (October
2019)
Rule Noted
Result MeasureQualifierCode will support
new WQX 3.0 measure qualifiers as
independent child elements
in parent
with a maximum number
of 6 codes.
WQX 3.0 (October
2019)
Rule added
Habitat Selection Method is required when
Activity Assemblage is "Benthic
Macroinvertebrates"
WQX 3.0 (October
2019)
Rule added
Target Count is required when the Activity
Assemblage is "Benthic
Macroinvertebrates"
WQX 3.0 (October
2019)
Rule added
Proportion Sample Processed Numeric is
required when the Activity Assemblage is
"Benthic Macroinvertebrates"
WQX 3.0 (October
2019)
Rule added
Proportion Sample Processed Numeric
must be a positive number between 0 and
1"
WQX 3.0 (October
2019)
Rule added
Statistical N-Value Numeric must be a
positive whole number
WQX 3.0 (October
2019)
Rule added
7
-------
Water Quality Exchange - Flow Configuration Document
3.0 Implementing the Header Document
3.1 Overview
The Exchange Network Header Document provides additional information about the contents of a message payload. It is
developed to further automate the data exchange process so that data can be more readily identified during transport and
managed at its processing destination. The Header Document can describe what a data payload contains, who submitted it,
when it was submitted, as well as instructions on processing the payload contents, such as whether the contents are inserts
and updates or deletions.
Essentially, the Header Document is an XML wrapper, placed around an XML payload before transmission to CDX. A
Header Document toolkit is available in the Tool Box section of the Exchange Network Web site
(http://www.exchanqenetwork.net'). containing additional background about the Header Document, as well as Java and .NET
implementation tools.
3.2 Header Document Structure
Any network exchange for WQX must use the Header Document structure in order to meet EPA CDX and WQX processing
requirements and prior Exchange Network agreements.
The Header Document begins with a "Document" tag and contains two sections: "Header" and "Payload". The Header
section contains information about the submission. The Payload contains the WQX data. Although some data flows allow for
multiple payloads in one document, the WQX data flow allows only a single payload. The Payload must conform to one of
the two WQX standard schemas for data submissions.
The following table describes the Header Document elements and attributes and how they are utilized for the purpose of a
WQX submission.
Document
Attribute
Description
Example Value
Required
Notes
Id
Allows a submitter
to provide a unique
ID for each
submission.
"ABC 12345"
Yes
It is not mandatory
that this value be
unique.
Header Section
Element
Description
Example Value
Required
Notes
Author
First and Last
Name of individual
generating the XML
document
Joe Smith
Yes
Reference only
Organization
Name of company,
environmental
agency or individual
that created the
XML document
State X Department of
Environmental Quality
Yes
This identifies the
author's
organization,
which may be
different from the
organization who
owns the data
(identified in the
WQX payload)
Title
Identifies the target
data flow for a
submission
"WQX"
Yes
Creation Time
Date/Time when the
document was
generated
2003-01-01T12:12:12
(where date is a valid XML date
format string)
Yes
Comment
Free text
No
8
-------
Water Quality Exchange - Flow Configuration Document
description of the
message contents.
Data Service
Unused
N/A
No
Element is not
used. If a value is
included it will be
ignored.
Contact Info
Name, mailing
address, city, state,
zip, telephone
number, and email
address of person
who may be
contacted with
questions
concerning the
submission.
Joe Smith
123 Main St.
Portland, OR 97226
503 123 4567
Joec/deq .statex.gov
Yes
Notification
This element is
used only by the
CDX Node
(internally).
N/A
No
Element is not
used. If a value is
included it will be
ignored.
Sensitivity
Unused
N/A
No
Element is not
used. If a value is
included it will be
ignored.
Property
Unused
N/A
No
Element is not
used. If a value is
included it will be
ignored.
Payload
Attribute
Description
Example Value
Required
Notes
Operation
This describes the
operation to be
performed on the
payload. Multiple
values are not
allowed
Must be either "Update-Insert"
or "Delete"
Yes
WQX
XML Namespace
(xmlns)
WQX approved
namespace for
submission files
Must be either:
"http://www.exchangenetwork.net/schema/wqx/1"
or
"http://www.exchangenetwork.net/schema/wqx/2"
or
"http://www.exchangenetwork.net/schem a/wqx/3"
Yes
To take
advantage of the
elements in the
WQX 3.0 Schema
you must
reference the
wqx/3
namespace.
The following excerpt from a WQX XML Submission File demonstrates the use of the header document:
Ryan Jorgensen
Gold Systems, Inc.
WQX
2008-04-05T0 9:30:47-05:00
This is a test file
2121 S. McClelland St., #204, SLC, UT 84106, 801-456-6105, ryanj@goldsystems.com
9
-------
Water Quality Exchange - Flow Configuration Document
3.3 Submission File Structure
In addition to the XML Header Document (containing the Header and Payload), a submission can also include binary objects
(such as images or documents). These binary objects are referenced (by unique name) in the WQX Document, but are
provided as individual, external documents. In order to group all related documents for a submission, each WQX submission
should be provided to CDX in a single compressed file in '.zip' format. This also improves transmission efficiency due to the
significantly smaller size of compressed files. Even if a submission does not contain any external binary objects, it is still
strongly recommended that it be provided in '.zip' format (although single '.xml' documents will be allowed).
Additionally, the Header Document within the submission is the only file allowed to have an '.xml' extension. This allows
CDX to differentiate between the Header Document and any other binary object files included in the submission.
It is also recommended that submission files be keep files under 350 MB (before they are zipped) or about 350,000 Results.
The following diagram describes the structure of a Submission Zip File for WQX:
Submission File (.zip)
Header Document (.xml)
Header
Payload
WQX Data
Attached Binary Object 1 (.pdf - for example)
Attached Binary Object 2 (.jpg - for example)
3.4 Payload
The Payload Section of the Header Document contains an attribute named "Operation". This is used to denote the type of
processing for a submission. There are two acceptable values: "Update-Insert" or "Delete". Use of these operators triggers
the processing outlined in the Data Processing section of this document. For example, a Payload Operation of "Update-
Insert" informs the back-end application that the submission contains new data (to be added to WQX) or existing data (to be
updated in WQX). An Operation of "Delete" denotes that the submission contains identifiers for data to be deleted from
WQX.
The Payload section of the document contains the WQX data, which must conform to one of the three standard WQX XML
Schema Definitions (XSD) for data submissions:
1. If the "Operation" attribute is "Update-Insert" and the namespace is "WQX" then the Payload must conform to the
Update-Insert Schema ("WQX_WQX_v3.0.xsd").
10
-------
Water Quality Exchange - Flow Configuration Document
a. For backward compatibility WQX will continue to support submissions that comply with the WQX 1.0 schema
("WQX_WQX_v1.0.xsd"), WQX 2.0 schema ("WQX_WQX_v2.0.xsd"), WQX 2.1 schema
("WQX_WQX_v2.1 .xsd"), and WQX 2.2 schema ("WQX_WQX_v2.2.xsd").
2. If the "Operation" attribute is "Update-Insert" and the namespace is "WQXUpdateldentifiers" then the Payload must
conform to the Update-Insert Schema ("WQX_WQX_Update_ldentifiers_v3.0.xsd").
3. If the "Operation" attribute is "Delete" then the Payload must conform to the Delete Schema
(" WQX_WQX_Delete_v3.0 .xsd").
a. For backward compatibility WQX will continue to support submissions that comply with the WQX 1.0 schema
("WQX_WQX_Delete_v1.0.xsd"), WQX 2.0 schema ("WQX_WQX_Delete_v2.0.xsd"), WQX 2.1 schema
("WQX_WQX_Delete_v2.1 .xsd"), and WQX 2.2 schema ("WQX_WQX_Delete_v2.2.xsd").
11
-------
Water Quality Exchange - Flow Configuration Document
4.0 Data Processing
Each data submission to WQX includes an "Organizationldentifier" element. This is a unique identifier for the organization
whose data is to be modified (by the data submission).
Before processing a data submission, the WQX system will confirm that the Organizationldentifier is valid and that the user
(identified by a NAAS ID) has been authorized to modify data for this organization.
As long as this is true, the WQX System will proceed with processing the data submission. Sections 4.1 and 4.2 provide an
overview of the structure and processing related to the two types of payloads for WQX: "Update-Insert" and "Delete", as well
as provide a list of the data rules enforced by the WQX System (which are not described by the respective XSDs).
4.1 Update-Insert (WQX)
The WQX "Update-Insert" Schema (WQX_WQX_v3.0.xsd) is modeled in Exhibit 1. Note: it may be helpful to print the
schema/model (in Exhibit 1) while reading this section. As the name implies, this schema defines the structure of a
submission file which can be used to "Update" or "Insert" (i.e. add) data to the WQX System.
The elements in this schema are grouped into 8 components. The list of components and their general hierarchy is provided
here (spaces have been added to component names for readability).
• Organization
o Project
o Monitoring Location
o Biological/Habitat Index
o Activity Group
o Activity
¦ Activity Metric
¦ Result
The schema defines one root component for the entire hierarchy: Organization. Each submission file must contain one, and
only one, Organization (uniquely identified with an Organizationldentifier).
Under the Organization, five primary components exist (bolded in the list above and designated with a heavier border on the
boxes in the model in Exhibit 1): Project, Monitoring Location, Activity, Biological/Habitat Index and Activity Group. Two
secondary components also exist (Activity Metric, and Result), which fall below an Activity.
A valid WQX submission file should include one Organization and one or more of the primary components. Consider the
following examples of the types of data that might be included in a valid submission:
• 1 Organization and 3 Projects
• 1 Organization, 5 Projects, and 37 Monitoring Locations
• 1 Organization, 250 Biological/Habitat Indexes, 1320 Activites, and 5400 Activity Metrics
Each primary component in the schema includes an identifier (e.g. Projectldentifier, MonitoringLocationldentifier,
Activityldentifier, etc.). Each must be unique within the parent Organization. For example: no two Monitoring Locations can
have the same identifier and no two Activities can have the same Identifier (within a single submission to WQX). Likewise,
it's important to understand the implications of using an identifier in one submission that has been used in a previous
submission.
When an identifier (for one of the five primary components) is encountered in a submission, the database will be queried to
determine if a component with that identifier can be found (indicating that that identifier has been used in a previous
submission). If the identifier is found, then an "Update" is performed, overwriting all of the component details in the database
with the component details in the current data submission. If the identifier is not found, an "Insert" is performed, creating an
entirely new component record in the database.
Secondary components (i.e. Activity Metric or Result) do not have unique identifiers, and therefore cannot be updated
individually. All secondary components in the schema must be updated along with their respective parent. For example: in
order to update a Result that has been previously submitted to the WQX System, you must resubmit the parent Activity and
all Results that fall below it. To further clarify, suppose you submit an Activity with three Results to WQX. Then you wish to
12
-------
Water Quality Exchange - Flow Configuration Document
add one new Result to that original Activity. You must submit a file with the one original Activity, the three original Results,
plus the one new Result (making four total Results) to WQX.
When a primary component (in the database) is updated (with a component from a new submission), it's important to
understand that it is a comprehensive replacement of all the component details (or elements) and any secondary component
details that fall below it. There is no way to update just part of the component details. Likewise, there is no way to add
additional information to an existing component (just by submitting the new information). You must completely replace all of
the details. For example:
• Although a Monitoring Location can have multiple "AlternateMonitoringLocationldentity" values, you cannot start with
a Monitoring Location with one AlternateMonitoringLocationldentity value, then submit an update to that Monitoring
Location with one new AlternateMonitoringLocationldentity value, and then be left with two
AlternateMonitoringLocationldentity values for that Monitoring Location. Instead, your update to the original
Monitoring Location must include two AlternateMonitoringLocationldentity values: the original one and the new one.
• Likewise, an Activity can have mulitiple Projectldentifiers, but you cannot add an additional Projectldentifier to an
existing Activity. You must resubmit the Activity (to WQX) with two Projectldentifies: the original one and the new
one.
As the WQX System processes a submission, it saves each primary component once it has passed all validation rules. If
there are any errors encountered with the primary component (or any related secondary component), then the primary
component and all related secondary components will not be saved. For example: if an Activity with five Results is being
processed, and one Result (among the five) has a validation error, then the Activity and the five Results will be discarded and
will not be saved.
If any validation error was found while loading the data submission into the WQX System, the status for that submission will
be set to "Failed" at CDX. This does not mean that there were zero components that were saved. It only means that there
was at least one component that was not saved because of a validation error. The Processing Report will include an
itemized list of any primary components that failed to be saved. See Appendix A for an example Processing Report.
If a submission fails to process successfully, there are two approaches to correcting it.
1) Correct the validation errors in the original submission and then resubmit the entire submission. In this case,
components that were valid in the first submission will be updated by the second submission (with the exact same values
as before). Components that failed in the first submission (which were never saved) will now be "Inserted" (i.e. added) by
the second submission.
2) Or you can just resubmit the components that failed in the original submission (since that's all that's needed).
13
-------
Water Quality Exchange - Flow Configuration Document
OrganlattanictaitHlar*
OrganfiBtlMiFonnalNMM
OrfanteaUtsfiDesofiplionTM
TrtbatGMte*
ElectfOfllcAddnss {0 m more)
ElectronfcMtfressText
EleclTQatAadressTypsMafae"
releplioeic {0 or more)
Teiepheaeffcimb&Tect
TelephofleMumbaTypeNafne"
Tetepho»eMensli»nNi»iTili«rTsKt
OrganteaUoiUMJelrass fO m more)
AddfMsTypeName"
AdtlreasTart
SupplemenUriMdressText
LacalltyName
StsteDxte*
PestaCofie"
OawntfyOode*
CeufflyCode*
-04
Project
PrejeaDescrlJfionTexl
Sampling Dasig nTypeCode*
QAPPAipprovedlrwKeator
QAPPApprovalAgeocyName
•ttadNdBNryO&fKt (0 or mom)
¦InaryQIiJadtFBeName
rail *K»t»#sas *
ProjectM®nl!ariefla£atto«WelghOi,i} (0 or mm)
i^€iiiiortwe«pworigrflcso'rpi«asiire
»!««
StaUstfcslStralumTatt
UeaBonCategoryltanie
LocaUonStalusllaiise
RetereneeLoeatloo'TVpeCiotfe*
ReteMa-eLacatHM^Iafmate
RerefsmUicatloiiCndDale
Refef6fK»LaciitieaClt3Hc«i
tawmlttcKMn
RejicwrceCreatortlame
RfisflureeSutjeetrert
HasouroePublisherMame
Commenrrext
AcllwllfDeiKfiptloJi
AedvllyUcnlffiar
Activlt/ldefSUnerUsefSuppiled
AcM«tefT»peCfiae*
aF Efe/g' ¦ «w**MS
*€tMlyM«IIaS«ihd]MsiQHlNan*e»
JtctMtySta rtDate
ActlvltyStarCTime
Time
Aetl¥flf?Ensl'Tliiie
TlfW®ZofifsCio/Coi»il>ittIn50rganteatlanTe!i4 <0 of iw»»)
M.sniliifiBflQCiJtiQBlilenBI'Ier
ActMtyGammenfrext
AetMtyUieatten
LatHudeMMMtre
SourceMapScale
HoftzentaUccuracyMeBsure
MeaaureValue
WeasateUnllCttie"
HarlzantalCatlaeliaiiMattmdNBiiM *
tellvityLQca-ltoaDeiCfiptisnTest
l£NS; fethltyGmupRaiir*
AeUwftfSroiipTfpeCis**
teHwItfMeiiHiar |lormare)
14
-------
Water Quality Exchange - Flow Configuration Document
J £
NonltoringLscaliwi
Monitof i nylouibof tlrfwrttty
UonllorliUljBeattalitethWer
NaaltoringLiKBtlaAMaiite
Huai>U»ln^UM.dtionTvfHiNBflM*
BanftoftiiflMttefiOeiefieuonTe*!
HLiCElflfttDi§itCo(le
HUCTwei*eOig ItCoile
TrkbalLandlnoHeator
TrtiaiLanaName
.«ta'aiteM®nll©finfLocs1:IafiHeiitily (0 or mow)
Me«tl»Qrti»flJK;aBo*fl*imiter
ManH»rtn0ljaaitlf BvC 4 y JjMC"k»'tjp4a*fi
15
-------
Water Quality Exchange - Flow Configuration Document
I I
8 fo iogicalHabiiail n da*
IniBMldieiiMllif
tnie*Tfpe
IisdiBKTfpel'iBiiitlflef
iBdeMTfpelieBiltapCoolieit
lrxteflypeataHttn
nmrnttMCmmammm
ResourceSubjerfnwt
tesouKePubilsherfJam*
iMtoCIVMScafeT est
n0L»
-tttftar
ActtvttytMMcrype
MctricTvptbMntmer»*
Mea-fcrfpelAsBiUBerContest*
MettftrypeName
MetrttTypeCllatton
SfCrVfc« V.1*— I iSsKFIISllSC-
ReseiiwcsCfeatarltain*!
lemwoStifleemwi
ResauwePiibllshefWame
MetrttTypeScateText
FwrmjIaDescrlptiorfText
NetrtCValiMsMeasure
MaMurcUnltCoile*
MetrieScwe
MeftrteCommemTe*!
tndexldentlfler (0- m mm)
6
*
Hamuli Oeseriplsn
DataUiggefLJneltame
ResultDetectiBnCondlt)onT€Bft*
CharafJefisticNarneUSefSupplfed
MettoilSpectallenMame*
ResultSBmpleFracdonText*
ResultMe&sitre
ResaitMeasu revalue* *
MeasureUnflCode*
MeasiufetJaiiBflafCkiiile" (D to 6)
TargetCount
f*3portioiiSamp»foc£ssedHiiBi«l£
ResuJElalusitUwitMSer*
StaBillcalBaseCiiite*
SlallstScaWVatePiiiinerii-
ResultValueTypeName*
Sesulttt'eij-hlBasisText'
Resu!tTii*«BaslsText*
ResuJITefTipefatia-eBitslsText*
SestiltParticteSiiieBatslsText
DataQuBllly
Precfelonvalue
BlaiiVitoe
Cofit
-------
Water Quality Exchange - Flow Configuration Document
JShx;
* Constrained by a lis! of domain values
' * Conjftionallf consliained
Bo(d = Required Dement (if parent tag tncfuded)
TaxwvomidDetBlls
CeBFofmName*
CettShapeHarne*
tmrnmim* {o to 3>
Voltln&mHame*
TasatnoialtRiliullonTsla-ance
TaiJciittBiilcPotlulsriTDlefaricaScalBTejct
TfoplicLewelHame
FunctleiiaiFeedlngGraupSiime p to 3}
TaisciaeBtlcCietallsCIIaBini
RamiitclRtaHuM
ResourceCnsstorKBine
ResaureeSubjecrrext
RssoufcsPu blMhsrflaBis
KcMtureeOial*
KawMarealdenHllar
FresineficvClasslfffftrmaOsii (0 to 3)
— —T . . |^, « fn'Ti IB' ilfli - - - *- Igng-fr. ag
p*r eq y cfl£^c..:wa s^eas*. n pwriMmsi' *
FrequencyOaasDcscripEarUnHCode*
LowerCtassBoundValue
UpperOastBoundValue
AttiehedBfoaryOblect (0 or more)
¦tnaryCNgeclMteTyiMCods
ReMrttAnalyticalMethod
McfthadlttMiNIerCaittegt*
HethodName
MetftadquaHfteriypeNafne
MettiodEtescrtpHsnTed:
CeitiparaliteAnaljtlfalWfttoa
MethodUianllfl«rCantait*
WethodMndHlcaBanTeif
ResullLablntofmatten
LabataXoryName
AnatysisStaftDate
Analys&StartTlme
Time
JtnafpisErKlDate
AnatysteEntfTliTie
Time
rimeZomaCode*
Laterals ryCfcmmentTew
Resy»DgtseltonQuanHtaB«nLImit (0 or mere)
(teasureiWafme
DeteettenQijanliralienLlfiilll'QffiifiMiCreK!
l.ateratei'j'SampIeSpBt.RKlci
UBxmrtoryAiCcredltatlonlndlcator
LaborataivAcQiedllaUonAutiMkrityKame
Ta*#)*fTi«s»ccfedltattonIr»d»eatof
TaxonarfiMttccfedilailciiiAuliliofltyNaine
LabSamptaPreparatton (0 or men)
LabSamflePrepaifaBsfiMethad
M€ifeMtTdontlficr
MattKKtNama
MettodQ^HAerrypeName
MethodDescrlpHonT ext
Preparations tart Date
PrepsralJonStartTtti#
PveparaQonEndDate
PreparaHonEndTlme
Time
TinieZoneCodte*
SuftstaimDiMtosifacter
Exhibit 1 - Update-Insert Schema
17
-------
Water Quality Exchange - Flow Configuration Document
4.1.1 Data Rules
The following is a summary of the data validation rules enforced on an "Insert-Update" submission to WQX. These are in
addition to the rules enforced by the WQX XSD.
1. When ElectronicAddressText or ElectronicAddressTypeName is reported, both must be reported.
2. When TelephoneNumberText orTelephoneNumberTypeName is reported, both must be reported.
3. When AddressText or AddressTypeName is reported, both must be reported.
4. When HorizonitalCollectionMethodName is "Interpolation-Map", SourceMapScale must be reported.
5. When VerticalMeasure's MeasureValue is reported, the following also must be reported:
VerticalMeasure's MeasureUnitCode,
VerticalCollectionMethodName,
VerticalCoordinateReferenceSystemDatumName.
6. Either ProjectDescriptionText or Project's AttachedBinaryObject must be reported.
7. Activity Depth/Height can be reported in only one of the following two ways (but not both):
a. Specific depth using ActivityDepthHeightMeasure's MeasureValue.
b. Depth Range using ActivityTopDepthHeightMeasure's MeasureValue and
ActivityBottomDepthHeightMeasure's MeasureValue.
i. This method must be used when ActivityTypeCode is "Sample-Integrated Vertical Profile".
8. When ActivityTypeCode contains the word 'Logger', DataLoggerLineName must be reported.
9. When ActivityMediaName is "Tissue" then BiologicallntentName must also be "Tissue" (and visa-versa)
10. When ActivityMediaName (or BiologicallntentName) is "Tissue", then SampleTissueAnatomyName must be reported.
11. When ActivityMediaName is "Biological" then AssemblageSampledName must be reported
12. When ResultDetectionConditionText is 'Not Detected', 'Present Above Quantification Limit' or 'Present Below
Quantification Limit', then DetectionQuantitationLimitTypeName and DetectionQuantitationLimitMeasure must be
reported.
13. CharacteristicName and ResultStatusldentifier must be reported.
14. When DetectionQuantitationLimit's MeasureValue is reported, DetectionQuantitationLimit's MeasureUnitCode must
be reported.
15. ActivityDescription's MonitoringLocationldentifier may be required depending on the value provided for
ActivityTypeCode. See the domain value list for ActivityTypeCode for more information.
16. ResultAnalyticalMethod may be required depending on the value provided for ActivityTypeCode. See the domain
value list for ActivityTypeCode for more information.
a. However, ResultAnalyticalMethod is never required if BiologicallntentName is "Individual", "Population
Census", "Frequency Class", or "Group Summary"
17. ResultSampleFractionText may be required depending on the value provided for CharacteristicName. See the
domain value list for CharacteristicName for more information.
18. ResultAnalyticalMethod's MethodldentifierContext must either match a value from the AnalyticalMethodContext
domain list or it must be the same as the value for the Organizationldentifier provided in the submission file.
a. If the MethodldentifierContext matches a value from the domain list, then the Methodldentifier must also
match a value from the AnalyticalMethod domain list (for that Context). Furthermore, MethodName,
MethodQualifierTypeName, and MethodDescriptionText are not required and will be ignored (since only the
Identifier and IdentifierContext are needed to uniquely identify the Analytical Method).
b. If the MethodldentifierContext matches your Organizationldentifier (indicating your own method), then
Methodldentifier and MethodName are both required, but do not need to match a value from the domain list
18
-------
Water Quality Exchange - Flow Configuration Document
(since they are your own). Additionally, MethodQualifierTypeName and MethodDescriptionText can be
provided, but are optional, to further describe the Analytical Method used.
19. Projectldentifier, MonitoringLocationldentifier, Activityldentifier, Indexldentifier and ActivityGroupldentifier must be
unique within an Organization. The value for each of these identifiers may occur only once in a submission file.
a. Unique identifiers are treated as case-insensitive by WQX. For example, the following three identifiers would
be treated as identical: "Mx571", "mx571", "MX571".
20. ResultMeasure's ResultMeasureValue may be constrained to a list of domain values depending on the value
provided for CharacteristicName. See the domain value list for CharacteristicName for more information.
21. If a numeric value is reported for ResultMeasureValue, then ResultMeasure's MeasureUnitCode and
ResultValueTypeName are required.
a. The exception to this is when the ResultMeasureValue is a Characteristic Pick List Value. These do not
have units.
22. If a CountyCode is reported then a StateCode must also be reported.
23. If NetTypeName = "Net/Horizontal Tow" then BoatSpeedMeasure is required.
24. If NetTypeName is reported then the SampleCollectionEquipmentName must be one that relates to that type of
equipment.
25. ActivityMetric's MetricTypeldentifierContext must either match a value from the MetricTypeContext domain list or it
must be the same as the value for the Organizationldentifier provided in the submission file.
a. If the MetricTypeldentifierContext matches a value from the domain list, then the MetricTypeldentifier must
also match a value from the MetricType domain list (for that Context). Furthermore, MetricTypeName,
MetricTypeCitation, MetricTypeScaleText, and FormulaDescriptionText are not required and will be ignored
(since only the Identifier and IdentifierContext are needed to uniquely identify the MetricType).
b. If the MetricTypeldentifierContext matches your Organizationldentifier (indicating your own metric), then
MetricTypeldentifier and MetricTypeName are both required, but do not need to match a value from the
domain list (since they are your own). Additionally, MetricTypeCitation, MetricTypeScaleText, and
FormulaDescriptionText can be provided, but are optional, to further describe the MetricType used.
26. If BiologicallntentName is "Group Summary" then GroupSummaryCount or GroupSummaryWeightMeasure must be
reported
27. If BiologicallntentName is "Frequency Class" then Result's CharacteristicName must be "Count"
28. If BiologicallntentName is "Population Census" then Result's CharacteristicName must be "Count" or "Total Sample
Weight"
29. FrequencyClassDescriptorUnitCode may be required depending on the value provided for
FrequencyClassDescriptorCode. See the domain value list for FrequencyClassType for more information.
30. FrequencyClasslnformation's LowerClassBoundValue and UpperClassBoundValue may be required depending on
the value provided for FrequencyClassDescriptorCode. See the domain value list for FrequencyClassType for more
information
31. Biological Intent Name and Subject Taxonomic Name must be reported when Activity Media Name is "Biological" or
"Tissue"
32. Either Result Measure Value and/or Result Detection Condition Text must be reported
33. Measure Unit is required when Measure Value is supplied
34. Measure Value is required when Measurement Unit is supplied
35. ResultMeasureQualifierCode will support new WQX 3.0 measure qualifiers as independent child elements
in parent with a maximum number of 6 codes.
36. Habitat Selection Method is required when Activity Assemblage is "Benthic Macroinvertebrates"
37. Target Count is required when the Activity Assemblage is "Benthic Macroinvertebrates"
38. Proportion Sample Processed Numeric is required when the Activity Assemblage is "Benthic Macroinvertebrates"
39. Proportion Sample Processed Numeric will be set to NULL when value is equal to 0.000000001 and the Activity
Assemblage is "Benthic Macroinvertebrates"
19
-------
Water Quality Exchange - Flow Configuration Document
40. Proportion Sample Processed Numeric must be a positive number between 0 and 1"
41. Removed (v3.0) Sample Collection Method is required when Activity Type Code contains the word "Sample"
42. Statistical N-Value Numeric must be a positive whole number
43. Analytical Method is required when submitting a Comparable Analytical Method
44. Comparable Analytical Method Identifier Context must match a national value from the domain list
45. If ResultDetectionQuantitationLimit is reported, then DetectionQuantitationLimitTypeName and
DetectionQuantitationLimitMeasure are required
46. ResultAnalyticalMethod may be required depending on the value provided for CharacteristicName. See the domain
value list for CharacteristicName for more information
47. MethodSpeciation may be required depending on the value provided for CharacteristicName. See the domain value
list for CharacteristicName for more information
4.2 Update-Insert (WQX Update Identifiers)
The WQXUpdateldentifiers "Update-Insert" Schema (WQX_WQX_Update_ldentifiers_v3.0.xsd ) is modeled in Exhibit 2. This
schema defines the structure of a submission file which can be used to "Update" existing identifiers of major entities in the
WQX System.
The elements in this schema are grouped into 5 components. The list of components and their general hierarchy is provided
here (spaces have been added to component names for readability).
• Organizationldentifier
o ProjectldentifierUpdate
¦ Oldldentifier
¦ Newldentifier
o MonitoringLocationldentifierUpdate
¦ Oldldentifier
¦ Newldentifier
o IndexIdentifierUpdate
¦ Oldldentifier
¦ Newldentifier
o ActivityldentifierUpdate
¦ Oldldentifier
¦ Newldentifier
o ActivityGroupldentifierUpdate
¦ Oldldentifier
¦ Newldentifier
The schema defines one root component for the entire hierarchy: Organization. Each submission file must contain one, and
only one, Organization (uniquely identified with an Organizationldentifier).
In addition to the Organizationldentifier, at least one of the other identifiers (in the list above): ProjectldentifierUpdate,
MonitoringLocationldentifierUpdate, IndexIdentifierUpdate, ActivityldentifierUpdate, and ActivityGroupldentifierUpdate must
be provided. The identifiers can be repeated as many times as necessary to identify all of the records to be updated in the
WQX Database.
The following procedure defines the update process:
The unique identifier (Oldldentifier) for each Project, Monitoring Location, Biological/Habitat Index, Activity, and Activity Group
in the payload is compared with the identifiers for these respective items in the WQX Database for the given organization
20
-------
Water Quality Exchange - Flow Configuration Document
(Organizationldentifier). If the identifier is not found, a warning is added to the Processing Report, and the identifier is
ignored. If the identifier is found, then the matching record in the database is updated with the new identifier (Newldentifier).
WQX XML Schema Model
for Update Identifiers
Updatelclentifiers
Organizationldentifier
ProjectEdentifierUpdate
oidldentifier
Newldentifier
Monitoring Locati onldenti fierU pdate
Oidldentifier
Newldentifier
Ind exldentifier Upd ate
Oidldentifier
Newldentifier
ActivityldentifierUpdate
Oidldentifier
Newldentifier
Acti v ityGrou pldersti fi e r J pdate
Oidldentifier
Newldentifier
Exhibit 2 - Update Identifiers Schema
4.3 Delete
The XML Schema for the "Delete" operation is very simple (See Exhibit 3):
• Organizationldentifier
o Projectldentifier
o MonitoringLocationldentifier
o Indexldentifier
o Activityldentifier
o ActivityGroupldentifier
Organizationldentifier is required (and must be provided only once). The Organizationldentifier is required for context only.
Organizations cannot be deleted.
In addition to the Organizationldentifier, at least one of the other identifiers (e.g. Projectldentifier, MonitoringLocationldentifer,
Activityldentifier, ActivityGroupldentifier, or Indexldentifier) must be provided and can be repeated as many times as
necessary to identify all of the records to be deleted from the WQX Database.
The following procedure defines the delete process:
The unique identifier for each Project, Monitoring Location, Activity, Biological/Habitat Index and Activity Group in the payload
is compared with the identifiers for these respective items in the WQX Database. If the identifier is not found, a warning is
added to the Processing Report, and the identifier is ignored. If the identifier is found, then the matching record in the
database is deleted.
Legend j
Bold = required Element j
21
-------
Water Quality Exchange - Flow Configuration Document
When one of these primary components is deleted from the system, all child data is deleted as well.
For example:
• AttachedBinaryObjects are deleted whenever the parent Project, MonitoringLocation, Activity or Result is deleted;
• Results are deleted whenever their parent Activity is deleted;
• Activites are deleted whenever their parent Project or MonitoringLocation is deleted.
The following exceptions exist:
1. Activities can relate to more than one Project.
a. When a project is deleted and a related Activity has more than one project relationship, the Activity will not be
deleted. Only the relationship between the Project and the Activity will be deleted.
b. When an Activity relates to only one Project, the Activity will be deleted when its parent Project is deleted.
2. Activities may or may not relate to a Monitoring Location.
a. When an Activity relates to a Monitoring Location it will be deleted when its parent Monitoring Location is deleted.
b. When it does not relate to a Monitoring Location (such as for certain Quality Control Samples) it will be
unaffected by any Monitoring Location deletes.
3. Deleting a Biological/Habitat Index or Activity Group does not delete the Activities that relate to them.
WQX XML Schema Model
for Delete
ucycfwt
AclwilyiGrcitipIfleiifiiw
Exhibit 3 - Delete Schema
22
-------
Water Quality Exchange - Flow Configuration Document
5.0 Submission Processing and Feedback
Before a WQX submission is made to CDX, a Node User must register with Network Authentication Authorization (NAAS)
and obtain a user account. Furthermore, a NAAS policy is established that allows the account to invoke specific methods on
the CDX Node for the WQX exchange.
Submission of Exchange Network Documents to the WQX System via the CDX Node follows these processing steps:
Authenticati
Submit-
Submit-
Notify-
GetStatus-
Download-
2. Submit file to CDX
1. Authenticate to CDX
10. Get Status from CDX
11. Download Processing
Report
Originating Node
(or Node Client)
3. Archive file
a. Set Status = "Received'
4. Validate XML
a. Schema Validation
b. Set Status = "Pending'
or
c. Set Status = "Failed"
Jump to step 9
5. Submit file to WQX System
8. Archive Processing Report
9. Send notification email to
submitter.
CDX
6. Process file
7. Notify CDX and return the
Processing Report
a. Set Status = "Completed'
or
b. Set Status = "Failed"
WQX
1. The Originating Node/Node Client calls the Authenticate method to initiate a session with CDX.
a. If authentication is successful, a Security Token will be returned.
2. The Submit method is called to submit a WQX file for processing.
a. A Transaction ID is returned, indicating that the file transfer was successful.
3. The submission file (.zip or .xml) is archived at CDX.
a. The status of the submission is set to "Received".
4. The XML submission file is validated at CDX:
a. The file is compared with the Header Schema and the relevant WQX Schema to confirm that it complies with
the required structure.
b. If the XML file passes validation, the submission status is set to "Pending".
c. Otherwise, a Processing Report is generated and the submission status is set to "Failed". No further
processing occurs (skip to step 9).
5. CDX submits the file to the WQX System (by calling its Submit method).
6. The WQX System processes the submission file (i.e. performs database inserts, updates, and deletes as indicated in
the file) and loads any attached binary objects.
7. The WQX System calls the Notify method at CDX to update the submission status and return a Processing Report.
a. If the file was processed without errors, then the status is set to "Completed".
b. If there were errors, then the status is set to "Failed".
8. The Processing Report is archived at CDX.
9. An email is sent to the submitter notifying him/her of the final status of the submission ("Failed" or "Completed").
10. The Originating Node/Node Client calls the GetStatus method to determine the status of the submission. If the
Originating Node is manually controlled and the submitter is already aware of the status (from the email in step 9),
then this step could be skipped.
11. Once the status is either "Completed" or "Failed", the Download method is called to retrieve the Processing Report
from CDX.
23
-------
Water Quality Exchange - Flow Configuration Document
a. The Processing Report is an XML-based summary of the processing that occurred on the WQX System
(including processing time, insert/update/delete counts and any error or warning messages). See Appendix
A for an example Processing Report.
24
-------
Water Quality Exchange - Flow Configuration Document
6.0 Query Processing and Feedback
A query allows a State/Regional/Tribal node to request data back from the WQX system. There are two methods for
retrieving this data: the Query method, which returns the results immediately, and the Solicit method which creates a data
file (offline) which can be downloaded (or submitted back to the requestor's node) at a later time. The Query method is ideal
for smaller requests and may have restrictions on the size of the results returned. The Solicit method can accommodate
larger requests.
6.1 Query Process
The Query process follows these processing steps:
Authenticati
Query-
Query-
4. Process the request and
return the results
WQX
3. Call WQX Query method
5. Return the results
CDX
2. Submit a request to CDX (via
Query method)
1. Authenticate to CDX
Originating Node
(or Node Client)
1. The Originating Node/Node Client calls the Authenticate method to initiate a session with CDX.
a. If authentication is successful, a Security Token will be returned.
2. The Query method is called to request data from CDX.
*3. CDX forwards the request on to the WQX System (via the Query method).
*4. The WQX System processes the request and returns the results to CDX.
*5. CDX returns the results to the Originating Node/Node Client.
* Steps 3, 4, and 5 are all transparent to the Originating Node. The Query method call (in step 2) returns the results
(mentioned in step 5).
6.2 Solicit Process
The Solicit process follows these processing steps:
Authenticati
Solicit-
Solicit-
Submit-
GetStatus-
Notify-
Download-
3. Set Status = "Pending'
4. Call WQX Solicit method
8. Send notification email to
requestor.
7. Set Status to "Completed" or
"Failed"
CDX
5. Process the request
6. Submit results to CDX (if
successful)
or
Notify CDX of error (if
unsuccessful)
WQX
2. Submit a request to CDX (via
Solicit method)
9. Get Status from CDX
1. Authenticate to CDX
10. Download results file from CDX
Originating Node
(or Node Client)
1. The Originating Node/Node Client calls the Authenticate method to initiate a session with CDX.
a. If authentication is successful, a Security Token will be returned.
2. The Solicit method is called to request data from CDX.
a. A Transaction ID is returned.
3. The Transaction Status is set to "Pending".
4. CDX calls the Solicit method on the WQX System.
5. The WQX System processes the request and creates a results file corresponding to the criteria it was passed.
6. If the request is successful, then the WQX System calls the Submit method to return the results file to CDX.
25
-------
Water Quality Exchange - Flow Configuration Document
If the request fails, then the WQX System calls the Notify method to return the error message.
7. CDX sets the Transaction Status to "Completed" if the request was successful or "Failed" if not successful.
8. An email is sent to the requestor notifying him/her of the final status of the solicit request ("Failed" or
"Completed").
9. The Originating Node/Node Client calls the GetStatus method to determine the status of the transaction. If the
Originating Node is manually controlled and the requestor is already aware of the status (from the email in step
8), then this step could be skipped.
10. Once the status is either "Completed" or "Failed", the Download method is called to retrieve the results file (or
error message).
7.0 Web Service Methods at CDX
The following sections discuss the web service methods available at CDX for the WQX data flow. This reference can be
used by the developers of a State/Regional/Tribal Node in implementing the interface between their node and CDX. For
more information, see the Network Node Functional Specification document available on the Exchange Network web site
(www. exch a n a e n etwo rk. n et):
7.1 Endpoints
The WQX endpoints for Submitting/Querying data are:
Production:
• https://cdxnodengn.epa.gov/ngn-enws20/services/NetworkNode2ServiceConditionalMTOM
Test:
• https://testngn.epacdxnode.net/ngn-enws20/services/NetworkNode2ServiceConditionalMTOM
7.2 Authenticate
The authenticate method is used to obtain a security token from the Network Authentication Authorization Service (NAAS).
This token will be passed in all subsequent method calls in the exchange between your node and CDX. Please note that
security tokens will expire 20 minutes after the token is issued.
Parameters:
• userld: the User ID identifying your node.
• credential: the password you were issued along with the User ID.
• authenticationMethod: the method used to authenticate. Currently only "password" is allowed
Returns: a securityToken used to identify your session with CDX.
7.3 Submit
The Submit method is used to send your WQX submission file to CDX.
Parameters:
• securityToken: A security token issued by the NAAS and returned from the Authenticate method.
• transactionld: unused.
• dataflow: The name of target dataflow: "WQX"
• documents: An array of type nodeDocument. Each nodeDocument structure contains a single submission
document/file. For WQX, only a single instance of nodeDocument is submitted. The nodeDocument's
"documentName" property must have a file extension of .xml or .zip (e.g. "TestSubmision.xml"). Any documents with
other extensions in the documentName property will not be processed.
Returns: a transactionld which identifies your submission. This can be used in the GetStatus and Download methods
(described below).
26
-------
Water Quality Exchange - Flow Configuration Document
7.4 GetStatus
The GetStatus method is used to check on the current status of a submission file being processed or a solicitation for WQX
data. Generally this is used to followup on a previous call to the Submit or Solicit method.
Parameters:
• securityToken: A security token issued by the NAAS and returned from the Authenticate method.
• transactionld: A Transaction ID returned by the Submit or Solicit method.
Returns: the status of the specified transaction: Received, Pending, Completed, or Failed.
7.5 Download
The Download method is used to download documents from the CDX node relating to a specific transactionld. Generally,
this method is used after the GetStatus returns either "Completed" or "Failed".
There are two purposes for the Download method:
1. Retrieve the Processing Report after a submission file has been processed.
a. This report describes the processing that occurred on your submission and any errors or warnings that
arose.
2. Retrieve the results of a request for WQX data using the Solicit method.
Parameters:
• securityToken: A security token issued by the NAAS and returned from the Authenticate method.
• transactionld: A transaction ID returned by the Submit or Solicit method.
• dataflow: The name of the dataflow: "WQX".
• documents: (optional).
If this parameter is left blank, then all documents relating to this transaction will be returned. This parameter is useful
to avoid downloading things you don't need. For example: pass in the Processing Report name to download just the
processing report, and avoid downloading your original submission file along with it.
The documents parameter is made up of the following three fields:
o name: the name of the document you wish to download,
o type: the file type (XML, ZIP, OTHER),
o content: not used.
Returns: a set of documents.
The following documents are available for download:
For a Submit transaction:
1. The original submission document.
2a. The Schema Validation Error Report (this will only exist in cases where CDX found a problem with
the format of your XML submission file).
(name = "Validation Results", type = "XML")
or
2b. The Processing Report from the WQX System.
(name = "DocumentStatus_ +[original document name]", type = "XML")
For a Solicit transaction:
1. The results file.
27
-------
Water Quality Exchange - Flow Configuration Document
(name = "Results.zip", type = "ZIP").
7.6 Query
The Query method is used to query the WQX system and retrieve data from it. Queries have restrictions to keep the size of
the output reasonably small. For requests that may return a larger set of data, please use the Solicit method. Section 6.6.1
describes the Query and Solicit Requests that are currently support by the WQX system.
Note: The WQX.GetWqxldentifiers_v3.0 query service will return a zipped file (name = "Results.zip", type = "ZIP").
Parameters:
• securityToken: A security token issued by the NAAS and returned from the Authenticate method.
• request: The name of the query to be performed (see section 6.6.1 for more details).
• rowld: not used.
• maxRow: not used.
• parameters: An array of parameter values for the query to be performed. Parameters are specific to the request that
is made (see section 6.6.1 for details).
Returns: a set of data in an XML instance document. The returned data set is dependant on the request made.
Note: The WQX.GetWqxldentifiers_v3.0 service is not constrained by any size limitations.
7.7 Solicit
The Solicit method is used to query the WQX system and retrieve data from it. Unlike the Query method, which returns the
results immediately, the Solicit method processes the request offline and creates a zipped XML document that can be
downloaded (or submitted back to the requestor's node) at a later time. The Solicit method is also able to handle requests for
a larger volume of data than the Query method. Section 6.6.1 describes the requests that are currently support by the WQX
system.
Parameters:
• securityToken: A security token issued by the NAAS and returned from the Authenticate method.
• returnURL: Not supported at CDX (leave blank).
• request: The name of the query to be performed (see section 6.6.1 for more details).
• parameters: An array of parameter values for the query to be performed. Parameters are specific to the request that
is made (see section 6.6.1 for details).
Returns: a transaction Id which identifies your request. This can be used with the GetStatus and Download methods to
retrieve your results.
8.0 Data Services (Query/Solicit)
WQX will support the following Requests available via the Query or Solicit Web Service Methods:
• WQX.GetActivityByParameters_v3.0
o Description: Returns a collection of Activities and a count of the number of Results on each Activity.
o
o
Available via: Query or Solicit
¦ Query requests are limited to 500 Activities.
Parameters:
Pos
Name
Tvoe
Reauired
Notes
1
organizationldentifier
String
Required
2
monitoringLocationldentifier
String
Optional
3
projectldentifier
String
Optional
28
-------
Water Quality Exchange - Flow Configuration Document
4
activityStartDateBegin
DateTime
Optional
Example format:
2005-10-16T14:00:00-06:00
or 2005-10-16
5
activityStartDateEnd
DateTime
Optional
Example format:
2005-10-16T14:00:00-06:00
or 2005-10-16
6
activityldentifier
String
Optional
o Return Schema: WQX_WQX_v3.0.xsd (Organization & Activity Sections only).
• WQX.GetActivityByParameters_v2.0, WQX.GetActivityByParameters_v2.1, or
WQX.GetActivityByParameters_v2.2
o Parameters: identical to the 3.0 version described above.
o Return Schema: WQX_WQX_v2.2.xsd (Organization & Activity Sections only)
• WQX.GetActivityGroupByParameters_v3.0
o Description: Returns a collection of Activity Groups,
o Available via: Query or Solicit,
o Parameters:
Pos
Name
Tvoe
Reauired
Notes
1
organizationldentifier
String
Required
2
activityGroupTypeCode
String
Optional
3
activityGroupldentifier
String
Optional
o Return Schema: WQX_WQX_v3.0.xsd (Organization & ActivityGroup Sections only).
• WQX. GetActivityGroupByParameters _v2.0, WQX. GetActivityGroupByParameters _v2.1, or WQX.
GetActivityGroupByParameters _v2.2
o Parameters: identical to the 3.0 version described above.
o Return Schema: WQX_WQX_v2.2.xsd (Organization & ActivityGroup Sections only)
• WQX.GetBiologicalHabitatlndexByParameters_v3.0
o Description: Returns a collection of Biological or Habitat Indices,
o Available via: Query or Solicit
o Parameters:
Pos
Name
Tvoe
Reauired
Notes
1
organizationldentifier
String
Required
2
monitoringLocationldentifier
String
Optional
3
indexCalculatedDateBegin
DateTime
Optional
Example format:
2005-10-16T14:00:00-06:00
or 2005-10-16
29
-------
Water Quality Exchange - Flow Configuration Document
4
indexCalculatedDateEnd
DateTime
Optional
Example format:
2005-10-16T14:00:00-06:00
or 2005-10-16
5
indexldentifier
String
Optional
o Return Schema: WQX_WQX_v3.0.xsd (Organization & BiologicalHabitatlndex Sections only).
• WQX. GetBiologicalHabitatlndexByParameters _v2.0, WQX. GetBiologicalHabitatlndexByParameters _v2.1,
or WQX. GetBiologicalHabitatlndexByParameters _v2.2
o Parameters: identical to the 3.0 version described above.
o Return Schema: WQX_WQX_v2.2.xsd (Organization & BiologicalHabitatlndex Sections only)
• WQX.GetDomainValueByElementName_v3.0
o Description: Returns a list of domain values for the elementName passed in.
o Available via: Query or Solicit
¦ Query requests are limited to one Domain List (i.e. elementName is required).
o Parameters:
Pos
Name
Tvoe
Reauired
Notes
1
elementName
String
Required
for Query
Optional for
Solicit
If the elementName is null, then all domain
value lists are returned. Otherwise,
elementName must be one of the following:
ActivityGroupType
ActivityMedia
ActivityMediaSubdivision
ActivityRelativeDepth
ActivityType
AddressType
AnalyticalMethod
AnalyticalMethodContext
Assemblage
Biologicallntent
CellForm
CellShape
Characteristic
Country
County
DetectionQuantitationLimitType
ElectronicAddressType
FrequencyClassDescriptor
Habit
HorizontalCollectionMethod
HorizontalCoordinateReferenceSystemDatum
MeasureUnit
MethodSpeciation
MetricType
MetricTypeContext
MonitoringLocationType
NetType
ReferenceLocationType
ResultDetectionCondition
ResultLaboratoryComment
30
-------
Water Quality Exchange - Flow Configuration Document
ResultMeasureQualifier
ResultMeasureValuePickList
ResultSampleFraction
ResultStatus
ResultTemperature Basis
ResultTime Basis
ResultValueType
ResultWeightBasis
SampleCollectionEquipment
SampleContainerColor
SampleContainerType
SampleTissueAnatomy
SamplingDesignType
State
StatisticalBase
Taxon
TelephoneNumberType
TimeZone
ThermalPreservativeUsed
ToxicityTestType
Tribe
VerticalCollectionMethod
VerticalCoordinateReferenceSystemDatum
Voltinism
WellFormationType
WellType
o Return Schema: WQX_DomainValues_v3.0.xsd.
• WQX.GetDomainValueByElementName_v2.0, WQX.GetDomainValueByElementName_v2.1, or
WQX.GetDomainValueByElementName_v2.2
o Parameters: identical to the 3.0 version described above.
o Return Schema: WQX_DomainValues_v2.2.xsd
• WQX.GetDomainValueByElementName_v1.0
o Description: For backward compatibility with WQX 1.0, the version 1.0 name is still supported,
o Parameters: identical to the 2.0 version described above,
o Return Schema: WQX_DomainValues_v1.0.xsd
• WQX.GetMonitoringl_ocationByParameters_v3.0
o Description: Returns a collection of Monitoring Locations,
o Available via: Query or Solicit
¦ Query requests are limited to 1000 Monitoring Locations.
o Parameters:
Pos
Name
Tvoe
Reauired
Notes
1
organizationldentifier
String
Required
2
monitoringLocationldentifier
String
Optional
o Return Schema: WQX_WQX_v3.0.xsd (Organization & MonitoringLocation Sections only).
31
-------
Water Quality Exchange - Flow Configuration Document
• WQX.GetMonitoringl_ocationByParameters_v2.0, WQX.GetMonitoringl_ocationByParameters_v2.1, or
WQX.GetMonitoringl_ocationByParameters_v2.2
o Parameters: identical to the 3.0 version described above.
o Return Schema: WQX_WQX_v2.2.xsd (Organization & MonitoringLocation Sections only)
• WQX.GetProjectByParameters_v3.0
o Description: Returns a collection of Projects for the organization passed in.
o Available via: Query or Solicit
¦ Query requests are limited to 1000 Projects,
o Parameters:
Pos
Name
Tvoe
Reauired
Notes
1
organizationldentifier
String
Required
2
projectldentifier
String
Optional
o Return Schema: WQX_WQX_v3.0.xsd (Organization & Project Sections only).
• WQX. GetProjectByParameters_v2.0, WQX.GetProjectByParameters_v2.1, or
WQX.GetProjectByParameters_v2.2
o Parameters: identical to the 3.0 version described above.
o Return Schema: WQX_WQX_v2.2.xsd (Organization & Project Sections only)
• WQX.GetResultByParameters_v3.0
o Description: Returns a collection of Activities and Results,
o Available via: Query or Solicit.
¦ Query requests are limited to 500 Results,
o Parameters:
Pos
Name
Tvoe
Reauired
Notes
1
organizationldentifier
String
Required
2
monitoringLocationldentifier
String
Optional
3
projectldentifier
String
Optional
4
activityStartDateBegin
DateTime
Optional
Example format:
2005-10-16T14:00:00-06:00
or 2005-10-16
5
activityStartDateEnd
DateTime
Optional
Example format:
2005-10-16T14:00:00-06:00
or 2005-10-16
6
activityldentifier
String
Optional
o Return Schema: WQX_WQX_v3.0.xsd (Organization, Activity & Results Sections only).
• WQX.GetResultByParameters_v2.0, WQX.GetResultByParameters_v2.1, or
WQX.GetResultByParameters_v2.2
o Parameters: identical to the 3.0 version described above.
32
-------
Water Quality Exchange - Flow Configuration Document
o Return Schema: WQX_WQX_v2.2.xsd (Organization, Activity & Results Sections only)
• WQX.GetTransactionHistoryByParameters_v3.0
o Description: Returns a summary of the transactions processed by the WQX System,
o Available via: Query or Solicit,
o Parameters:
Pos
Name
Tvoe
Reauired
Notes
1
organizationldentifier
String
Conditionally
Required
One of these three parameters must
have a non-null value
2
userldentifier
String
Conditionally
Required
3
transactionldentifier
String
Conditionally
Required
4
transactionDateBegin
DateTime
Optional
Example format:
2005-10-16T14:00:00-06:00
or 2005-10-16
5
transactionDateEnd
DateTime
Optional
Example format:
2005-10-06T14:00:00-06:00
or 2005-10-16
o Return Schema: WQX_TransactionHistory_v3.0.xsd
• WQX.GetTransactionHistoryByParameters_v2.0, WQX.GetTransactionHistoryByParameters_v2.1, or
WQX.GetTransactionHistoryByParameters_v2.2
o Parameters: identical to the 3.0 version described above.
o Return Schema: WQX_ TransactionHistory _v2.2.xsd
• WQX.GetTransactionHistoryByParameters_v1.0
o Description: For backward compatibility with WQX 1.0, the version 1.0 name is still supported,
o Parameters: identical to the 2.0 version described above,
o Return Schema: WQX_TransactionHistory_v1.0.xsd
• WQX.GetWqxldentifiers_v3.0
o Description: Returns a collection of Projects, Monitoring Locations, Activities, Indexes, Activity Groups,
o Available via: Query or Solicit
¦ Note: Query request is not limited to maximum value,
o Parameters:
Pos
Name
Tvoe
Reauired
Notes
1
organizationldentifier
String
Required
2
entity
String
Optional
Valid Values: PROJECTS,
MONITORING LOCATIONS,
ACTIVITIES, INDEXES, ACTIVITY
33
-------
Water Quality Exchange - Flow Configuration Document
GROUPS
o Return Schema: WQX_WQX_ldentifiers_v3.0.xsd as a zipped file.
34
-------
Water Quality Exchange - Flow Configuration Document
Appendix A. - Example Processing Report
6ede652a-6fbc-4af4-9972-37eld8316ba4
Failed
WQX Node
WQX Database
l
l
l
0
0
83
0
0
1718
10
0
7
l
0
32021
0
0
2l
0
0
Message
Parse and Load started at 01/24/2006 03:29:37 PM
Warning
Activity could not be deleted. Activity ID "25792446" not found.
MonitoringLocationDelete/Line 22, Activity ID = 25792446
Error
35
-------
Water Quality Exchange - Flow Configuration Document
File "Station_CBC050.jpg" cannot be found.
AttachedBinaryObject/Line 274
Message
Parse and Load completed at 01/24/2006 03:45:40 PM
982
678
2 88 892A
2 9384 8X
192 8389822
3823239822
1922 8
1922 8
32 8
367
36
------- |