Environmental Information e/change N Ct W Qfk Chesapeake Bay Program A Watershed Partnership NATIONAL ENVIRONMENTAL INFORMATION EXCHANGE NETWORK Chesapeake Node Functional Specification Version 1.1 Final Draft March 13, 2006 ------- Chesapeake Node Functional Specification v. 1.1 FINAL PURPOSE of this Document The purpose of this document is to broadly define the Chesapeake Bay Program Office Non Point Source (NPS) Best Management Practices (BMPs) functional specifications. APPROVAL OF THE Functional Specifications Document: Signatory- Nancie Imler, Information Management Subcommittee, Chair Signatory- Brian Burch, Chesapeake Bay Program Office, Data Center Manager Signatory- Jennifer Gumert, PA Department of Environmental Protection, Network Node Manager Signatory- Karl Huber, VA Department of Conservation and Recreation, GIS/Data Center Manager Signatory- Ming Jiang, MD Department of Environment, Network Node Manager 11 ------- Chesapeake Node Functional Specification v. 1.1 FINAL Amendment Record: Version Date Amended By Change Version .1 August 30, 2005 B. Burch Original Document Version 1.0 November 30, 2005 Technical Team (Walkthrough) Final Draft Version 1.1 March 13, 2006 J Gumert Added signature page Changed from 'Final Draft' to 'Final' Updated version to 1.1 111 ------- Chesapeake Node Functional Specification v. 1.1 FINAL Table of Contents 1 INTRODUCTION 1 2 BUSINESS REQUIREMENTS 2 3 FUNCTIONAL REQUIREMENTS 2 3.1 N ODE W EB METHODS 2 3.1.1 Authenticate 3 3.1.2 Submit. 4 3.1.3 Query 4 3.1.4 GetStatus 5 3.1.5 Notify. 5 3.1.6 Solicit 6 3.1.7 Download 6 3.1.8 NodePing. 7 3.1.9 GetServices. 7 4 AUTHENTICATION MODEL 8 5 AUDITING 9 6 TECHNICAL SPECIFICATION 9 APPENDICES 10 A. NPS BMP Data References Documentation 10 Figure 1 Authentication Model 9 iv ------- Chesapeake Node Functional Specification v. 1.1 FINAL 1 Introduction The National Environmental Information Exchange Network (Network) is an innovative approach for the exchange of data between the EPA, states, and partner organizations. The Network provides the framework for the exchange of quality environmental information. The framework is built on Internet-based standards, technologies, and protocols. This is critically important for the long-term success of the Network. To participate in the Network, each exchange partner requires a Network node (Node). The Node hosts a suite of standard web services that facilitate the authentication and exchange of data between partners. The messaging between partners is handled through standard extensible markup language (XML). In federal fiscal year 2004, the Pennsylvania Department of Environmental Protection (PADEP) was awarded a Network Challenge Grant to facilitate the exchange of non- point source best management practice (BMP) data between the Chesapeake region states of Pennsylvania, Maryland and Virginia; and the Chesapeake Bay Program Office (CBPO). The grant called for the establishment of a new Node at the Chesapeake Bay Program Office in Annapolis, Maryland (Chesapeake node). The Chesapeake node is required to support exchanges between the state nodes and Chesapeake node, and the EPA node (CDX) and the Chesapeake node. The technology of choice for the Chesapeake node is the Microsoft .NET framework with Microsoft's SQL Server as the backend data store. Existing node configuration and requirements will serve as the blueprint for the Chesapeake node. In particular, the development team will follow the guidelines established in the Network Node Functional Specification (v. 1.1, September 2003); the Exchange Network Node Implementation Guide (v. 1.0, April 2003); and the Developing and Implementing an Exchange Network Node, 30 Minute Guide (v. 1.1, March 2005). Further, the development team plans on leveraging existing demonstrated node configuration documents. The Washington State Department of Ecology, Demonstrated Node Configuration (v. 1.0, November 2003), the Mississippi Demonstrated Node Configuration (v. 1.1, December 2003), and the demonstrated node configuration server side code for Microsoft C#.NET and Microsoft VB.NET will all be considered prior to the development of the Chesapeake node. 1 ------- Chesapeake Node Functional Specification v. 1.1 FINAL 2 Business Requirements • The Chesapeake Bay Program requires rapid access to high-quality, timely environmental information from the states to support management activity • The Chesapeake Bay Program requires consistent and comparable data across jurisdictions to inform management activity • The states require a removal of the burden of submitting uniquely formatted data to both the Chesapeake Bay Program and the EPA 3 Functional Requirements To support the business requirements, the Chesapeake Bay Program requires a fully functional network node supporting timely, consistent exchanges across the partnership. The core, functional requirement is described in detail in the Network Node Functional | Specification (vl.l, September 2003). The following details are an excerpt from the-this Specification document. 3.1 Node Web Methodsi The Network Node Functional Specification vl.l describes the behavior and interfaces of the service provider component. One of the design goals of this document is to create a framework of Web services such that data exchanges of any type between Nodes can be conducted seamlessly and automatically. The Web interface layer of the framework will create fully programmable environments on which clients can build automated tools, in any programming language, to send documents into the Network or to track previous submissions. A Node is a service provider. Thus, the key interfaces that must be implemented in a Node include the following Web methods: • Authenticate • Submit • Query • GetStatus • Notify • Solicit • Download • NodePing • GetServices • Execute (Optional method) This basic set of functions will be applicable for each given type of dataflow that will be exchanged through the Node, considering that each Node may be able to handle many kinds and types of data. 2 ------- Chesapeake Node Functional Specification v. 1.1 FINAL The following subsections define behaviors of each Web method, and give detailed descriptions of inbound/outbound messages. 3.1.1 Authenticate The Authenticate method authenticates a user using a supplied credential. It returns a securityToken when successful. The securityToken must be included in all other method invocations, except NodePing, as a proof of identity. A securityToken is an opaque string that is meaningful only to the issuer or trusted peers. It may include, but is not limited to, the following information: • The user ID or profile name. • A session ID for state management. • A timestamp for aging, expiration. Service providers must implement an aging strategy to prevent replay attack. An expired token should be discarded immediately. A suggested token life span is about ten (10) minutes. Authenticate messages must be sent through a secure transport such as secure socket layer (SSL). Note that although SSL is very good in securing communication channels, its usage, as an authentication system, is problematic; mutual verification of certificates in a large-scale distributed system is proven to be very expensive (public key infrastructure [PKI] required) and difficult to implement. The securityToken scheme presented here offers a simple yet effective way of identification and authentication. Note also that the specification itself does not define exactly how users are authenticated. Each Node implementer is free to choose any available authentication process in the underlying operating system. However, due to the Network connectivity, a security breach at one Node may have a grave impact to the overall operation. It is the responsibility of the Node operator to choose a secure authentication process. Network Security Guidelines and Recommendations, describing security practices for Network services, were provided in a separate document dated February 28, 2003. As described in the accompanying Network Exchange Protocol vl.l document delivered on March 14, 2003, and the Network Security Guidelines document, initial implementations will rely on an Environmental Protection Agency (EPA) hosted Network Authentication and Authorization Services (NAAS), supplemented as needed by local security services. Detailed information, including definition, argument description, return information and an example is available in the Network Node Functional Specification (vl.l, September 2003). 3 ------- Chesapeake Node Functional Specification v. 1.1 FINAL 3.1.2 Submit The Submit method provides a generic way of sending one or more payloads to a service provider. Payloads other than the message body are encapsulated in an array of nodeDocuments. A payload can be embedded into a nodeDocument structure as a base64 encoded value, or as a separate attachment referenced by the nodeDocument. A dataflow is a logical collection of certain kinds of data, understandable to the sender and the ultimate receiver. A dataflow can carry other information as well, such as Network events or asynchronous database requests. Such dataflows will be identified by special URLs. A Submit message can only target to one (1) dataflow at a time. Network Nodes are required to process the SOAP main body of request messages, but are not required to understand the contents of attachments unless the Node is the target Node (ultimate receiver). For instance, a missing telephone number in a submitted document is not a SOAP error, but rather a process related error that should be dealt with differently. Detailed information, including definition, argument description, return information and an example is available in the Network Node Functional Specification (vl.l, September 2003). 3.1.3 Query The Query method is a function in the Database interface. The method is intended to run a series of predefined information requests that return data in an XML instance document that conforms to a predefined standard schema. Many predefined information requests will be standard across the Network and some maybe unique to a particular Node. How the information requests are implemented is Node specific. Node implementers may choose different ways to implement the standard requests as long as the returned results conform to the XML schema. For Network efficiency, the service provider is highly recommended, but not required, to support positioned-fetches where the requester can ask for a subset of the records within the overall result set. This feature is especially useful for interactive applications with graphical user interfaces where only a limited number of records can be displayed at a time. Another case where positioned-fetch may be important is when the result set is so large that the Network connection between the requester and the provider will likely timeout. Positioned-fetch allows requesters to partition the whole result set into smaller chunks and thus avoid possible Network problems. 4 ------- Chesapeake Node Functional Specification v. 1.1 FINAL Unlike other methods, the response message of this method uses document remote procedure call (RPC) encoding style because the format of result sets varies widely from query to query. Detailed information, including definition, argument description, return information and an example is available in the Network Node Functional Specification (vl.l, September 2003). 3.1.4 GetStatus GetStatus is a method for transaction tracking. Once submitted, a transaction enters into different processing stages. The GetStatus method offers the client a way of querying the current state of the transaction. For Nodes that do not support staged transactions, the status of a submission degrades to a Boolean value: Failed or Completed. Detailed information, including definition, argument description, return information and an example is available in the Network Node Functional Specification (vl.l, September 2003). 3.1.5 Notify The Notify method has three (3) intended uses: document notification, event notification, and status notification described as follows: • Document notification: A Node or client notifies a service provider about availability of some documents (soliciting). The service provider can retrieve the documents anytime. • Event notification: A Node sends, or possibly broadcasts, an event that is of interest to other parties. Event messages can be security alerts, shutdown notices, and other Network management notes. • Status notification: A service provider sends a message to a requester to provide the current status of a submission or service request. In document notification, locations of the documents are provided in the nodeDocument structure. The service provider will use the same structure to download the available documents, so it is very important for requesters to include sufficient information so that the documents can be easily located. This specification does not define the semantics of events, as they are operation specific. Service providers are free to state the specific meaning of Network events. The event URI, however, must be unique and have a prefix of: http ://www. exchangenetwork.net/node/event 5 ------- Chesapeake Node Functional Specification v. 1.1 FINAL Detailed information, including definition, argument description, return information and an example is available in the Network Node Functional Specification (vl.l, September 2003). 3.1.6 Solicit The Solicit method performs the requested operation in the background or sometimes offline. It is designed especially for queries that may take a long time. In most situations, the Solicit method is used to ask for a Query operation. The service provider may kick off the Query operation immediately when the request is received, thus avoiding management of a transaction queue. The service provider decides whether to process the transaction immediately or later. It may spawn a separate thread to process the request in a relatively low priority mode, or save the request in a transaction queue, that will be processed sequentially sometime later. However, it must return a transaction ID immediately to the requester, thereby acknowledging the acceptance of the transaction. The service provider must return a SOAP fault message if the requested operation could not be honored. Once the requested operation is processed successfully, the service provider should update the status of the transaction to Complete. If the operation failed for some reasons, the status of the transaction should be set to Failed. The requester may optionally ask the service provider to submit the result to a Network Node location by specifying a returnURL. The location must contain a Network Node address that has an implementation of the Submit method. It is the requester's responsibility to download the result if the returnURL is empty. Detailed information, including definition, argument description, return information and an example is available in the Network Node Functional Specification (vl.l, September 2003). 3.1.7 Download The Download method is a function in the Retrieve Interface. It is different from the Submit method in two (2) ways: 1. Document flows from callee to caller (document retrieval). 2. The Download operation is usually initiated by a service provider. 6 ------- Chesapeake Node Functional Specification v. 1.1 FINAL The Download method is often used to fulfill a requested operation For instance, after being notified by a submitter, a Node invokes the Download method to retrieve available documents. If there is a pre-established contract between the two parties, e.g., names of the documents and their availability are predetermined, then a Node can actively retrieve the documents at fixed time periods without prior notification. The transactionld parameter may be empty in such cases. The ability to download documents makes mutual data exchange possible. Any Node in the Exchange Network can be a service provider and, at the same time, a service consumer. From the caller's point of view, submitting is an operation of sending documents to a remote Node, while downloading is an operation of receiving documents from a remote Node. Unlike the Submit method, however, the Download method gives access to some documents to the requester. The directory where the document resides should be limited to only those who have access rights. It is recommended that each user have a separate folder so that a document for one user cannot be accessed by another user. Detailed information, including definition, argument description, return information and an example is available in the Network Node Functional Specification (vl.l, September 2003). 3.1.8 NodePing The NodePing method is a function in the Admin interface. It is a utility method for determining whether a Node is accessible. A positive response from the Node indicates that it is live and well. A Network error (no response) or SOAP Fault (not ready) means that the service is not available at this time. NodePing is the only operation that does not require authentication. Detailed information, including definition, argument description, return information and an example is available in the Network Node Functional Specification (vl.l, September 2003). 3.1.9 GetServices The GetServices method is a function in the Admin interface. It allows requesters to query services provided by a Network Node. The type of services that can be queried includes, but is not limited to: • Interfaces: The Web service interfaces supported by the Node. 7 ------- Chesapeake Node Functional Specification v. 1.1 FINAL • Query: Predefined information requests that can be used in the Query method. • Solicit: Predefined information requests that can be used in the Solicit method. • Execute: Predefined procedures that can be used in the Execute method. A Node may choose to support additional types (meta-data) when needed. To get a complete list of all service types, a requester can pass ServiceType as the value of the ServiceType element. Using GetServices, a requester can determine the capability of a Node at runtime and proceed accordingly. On the other hand, it allows the service provider to extend the services provided, (e.g., add a new database report), without changing the infrastructure. The smart invocation and easy extensibility can greatly enhance the overall usability, stability and capability of the Exchange Network. See the Network Exchange Protocol VI.0 document for further discussion. Detailed information, including definition, argument description, return information and an example is available in the Network Node Functional Specification (vl.l, September 2003). While the CBP plans on developing the full range of node web services, only the authenticate, solicit, and getstatus methods will be employed in the production environment. The objective is to develop core node functionality to support anticipated future exchanges. 4 Authentication Model The Chesapeake node will use the Network's Network Authentication and Authorization Service (NAAS) to handle all authentication functions. The CBP will manage privilege to the Chesapeake node within the NAAS using a web-based user interface provided by the Network. As detailed in figure 1, the Chesapeake node will obtain a security token from the NAAS using the authentication service. The security token will be passed to send or retrieve data from a partner node. The partner node will validate the security token prior to responding to the request. 8 ------- Chesapeake Node Functional Specification v. 1.1 FINAL request Partner Chesapeake Node response Node 4 ) Validate 3 token true/false Network Authentication & Authorization Service (NAAS) Figure 1 Authentication Model 5 Auditing Pertinent node activity_will be logged to a Microsoft SQL Server database. This includes the date and time of outbound requests submitted to partner nodes, the date and time of inbound requests from partner nodes, and the status of those requests. Additional information about the requests may be captured in the future, which may include the request parameters and request response times. 6 Technical Specification The following specifications will be used for the initial installation of the Chesapeake node: Microsoft Server 2003, Enterprise Edition Microsoft Internet Information Server (IIS) 6.0 Microsoft SQL Server 2003 Microsoft .NET Framework 1.1 Web Services Enhancements 1.0 (WSE) 9 ------- Chesapeake Node Functional Specification v. 1.1 FINAL Appendices A. BMPNPS BMP PE^Data References Documentation 1. Network Node Functional Specification, v. 1.1, September, 2003 2. Network Exchange Protocol, v. 1.1, September, 2003 3. Exchange Network Node Implementation Guide, vl .0, April, 2003 4. Washington State Department of Ecology, Demonstrated Network Node Configuration, vl.0, November 2003 5. Developing and Implementing an Exchange Network Node, vl .1, March, 2005 6. Mississippi Demonstrated Node Configuration, vl. 1, December 2003 10 ------- |