Description of Alternate Id Search Function

SRS-Web Service Flow Configuration Document

Doc. No.: 28-SRS-RPT-0248

Version 1.0

Table of Contents

1.Introduction

2.Node Web Methods

3.SRS-Web Service implemented Web Methods

3.1NodePing Web Method

3.2Authenticate Web Method

3.3Query Web Method

4.SRS-WS Data Flow Configuration

Appendix A – Chemical Identification and Biological Taxonomy Data Standard to SRS-WS XML Tag Cross Reference

1.Introduction

The Substance Registry System (SRS – is the Environmental Protection Agency's (EPA) central system for information about regulated and monitored substances. The system provides a common basis for identification of chemicals, biological organisms and other substances listed in EPA regulations and data systems, as well as substances of interest from other sources, such as publications. The SRS supports and conforms to EPA's Chemical Identification Data Standard and the EPA's Biological Identification Data Standard. The SRS is a part of the centralized Systems of Registries (SoR – which provides access to the Agency's core registry systems. SRS data is accessible,at the request of state clients, using custom web services technology. SRS web services (SRS-WS) are provided through a Central Data Exchange/Demonstrated Node Configuration(CDX/DNC) Network Node which exposes an interface to these services by the use of web methods.

2.Node Web Methods

The Network Node Functional Specification V1.0describes the behavior and interfaces of the service provider component. The Network Node Functional Specification V1.0 is available on the Exchange Network ( ). A Node is a service provider. In the SRS exchange, web services will allow an exchange network partner to request SRS data from the SRS Node. The key interfaces that must be implemented in a Network Node include the following Web Methods:

• Authenticate
• Submit
• Query
• GetStatus
• Notify
• Solicit
• Download
• NodePing
• GetServices
• Execute (optional)

3.SRS-Web Service implemented Web Methods

SRS-Web Service (SRS-WS) implements only the following request functionality from the above web methods for Release 1.0:

• NodePing (to establish a line of communication between client and SRS-WS).
• Authenticate (to authenticate users of the system).
• Query (to query the SRS database).

3.1NodePing Web Method

• Description:

NodePing is a utility method to determine whether a Node is accessible or not. A positive response (typically a string like “Ready”) from the Node indicates that it is listening for requests. A network error (no response) means that the service is not available at this time.

• Arguments:

NodePing method has one string argument that may contain arbitrary text (preferably a short word, like “hello”, or even an empty string).

• Return:

NodePing returns a positive response in the form of a human readable short text string (like “Ready”, “Busy”, or “Unavailable”). It may throw a fault message (an exception message) that the requester must catch and interpret its meaning.

3.2Authenticate Web Method

• Description:

Authenticate method authenticates the credentials of a user. If the user successfully passes the authentication process, a security token (securityToken) string is returned. The securityToken must be used in all method invocations (except NodePing), as a proof of identity. The securityToken may be the result of some combination of user id, session id and a timestamp to provide a reference in relation to the life span of the user session. This authentication method relies on an EPA-hosted Network Authentication and Authorization Services (NAAS).

• Arguments:

user id: the user Id of a person or system.

credentials: user credentials for accessing the services.

authentication method: currently “password” is the only method supported by the Network Node functional specification V1.0. This parameter tells how to interpret the credentials passed in the second parameter.

• Return:

Upon successful authentication, SRS-WS returns a SOAP message with a securityToken. This is an encrypted string that becomes a security ticket for all subsequent service requests. SRS-WS throws a fault message (an exception message) in the following conditions:

• The user record is unknown
• The user credential is incorrect
• An internal server fault (exception) occurred.

3.3Query Web Method

• Description:

The Query method is a function in the database interface. This web method exposes a series of predefined information request functions that return response information in XML format (conforming to a predefined XML schema); in a synchronous RPC style (the client waits for the results to be returned).

The SRS-WS Query Web Method allows the following requests to be made:

• getSubstanceByCAS
• getSubstanceByName
• getSubstanceByEPAID
• getSubstanceByICTV
• getSubstanceTSN
• getSubstanceByALTID

All of the above requests perform an “Exact Match” of the input parameters against database identifier items.

The Substance details displayed in the XML file could be:

• EPA Name (if any).
• EPA Source Name (if any).
• Systematic Name.
• Systematic Source Name.
• TSN (if applicable).
• EPA ID (if applicable).
• Classification.
• Type.
• Definition.
• Comment Text.
• CAS number.
• Molecular Formula.
• Molecular Weight.
• Other Numbers (if any) associated with the substance.
• The list of Synonyms.
• Arguments

This web method is used to submit database queries to the SRS.The following arguments are part of this method signature:

securityToken: Security string issued by SRS-WS at authentication time (see above).

request: This argument should contain the exact name of one the information requests listed above.

rowId: The start row for the result set from the query. This a zero-based integer index to the current result set. The current SRS-WS release does not use this argument (it is always set to zero).

maxRows: Maximum number of rows to be returned (integer). The current SRS-WS release does not use this value (it is always set to -1).

parameters: This is an array of parameter values to a “request” function (see list above or details below).

• Return

The web method returns the results of a query in the form of an XML message string (see below).

1. getSubstanceByCAS

Input request: Chemical Abstracts Service (CAS) Registry Number (string format). This request can be called by passing arguments such as Current CAS numbers, Former CAS numbers, Invalid CAS numbers, Unknown CAS numbers, or Used Incorrectly CAS Numbers etc.

Output response: XML string containing the details for the associated Substance.

1. getSubstanceByName

Input request: Name (string). This argument can be an EPA Name, Systematic Name or Synonym.

Output response: XML string containing the details for the associated Substance.

1. getSubstanceByEPAID

Input request: EPA Identifier (string)

Output response: XML string containing the details for the associated Substance.

1. getSubstanceByICTV

Input request: International Committee on Taxonomy of Viruses (ICTV) Database Identifier

Output response: XML file containing the details for the associated Substance.

1. getSubstanceByTSN

Input request: Taxonomic Serial Number (string)

Output request: XML string containing the details for the associated Substance.

1. getSubstanceByALTId

Input request: Alternate Identifier

Output response: XML string containing the details for the associated Substance.

Alternate Identifiers are identification numbers used in EPA program information systems (e.g., pesticide product codes) or regulations (e.g., RCRA Hazardous Waste Codes). The generated XML string for this function will contain the Substance details and the Alternate Identifiers, Related Program Information System and Name used for the Substance in the Program Information System.

4.SRS-WS Data Flow Configuration

The data flow description depicts how client requests are executed, what system components are involved in the processing of the requests, and how results are returned to the client caller as responses. The following diagram attempts to describe this data flow.

The events, flow paths and data flow are outlined below:

1. The state client or a trusted exchange partner process, located somewhere outside the local/private network, submits a “Query” request for substance information. The request gets transported via HTTPS (secure HyperText Transport Protocol) through a secure firewall to SRS-WS Network Node.
2. The client user identification is validated at the Network Authentication and Authorization System (NAAS) and a Security Token is issued to be used for all further transactions with the DNC-SRS system.
3. The Network Node validates the request before passing it on to a “Service Invoker” object.
4. The Service Invoker instantiates the appropriate Java Data Access Object (DAO) to handle this request.
5. The DAO submits a PL/SQL query using JDBC (Java Database Connectivity) API to invoke database-stored functions, which ultimately access and return the relevant data as a data collection (Java List).
6. Next, the data collections are passed and loaded onto compile-time-generated Java content objects. These Java content objects are generated using a JAXB utility and the application XML schemas.
7. An XML builder marshals (converts) the Java content objects to produce an XML string.
8. The resulting XML string is returned to the originator of the request (state or trusted partner).

Note: Only the “Query” process (the only one supported at this time) is shown here. Each “Query” request is required to carry and pass the security token, which the client process acquires through the “Authenticate” request function mentioned earlier.

Appendix A – Chemical Identification and Biological Taxonomy Data Standard to SRS-WS XML Tag Cross Reference

DCN: 28-SRS-RPT-0248 CHR 2141 of 1101/13/2006

SRS-Web Service Flow Configuration Document

DCN: 28-SRS-RPT-0248 CHR 2141 of 1101/13/2006