ECHO Client Partners

Overview

An ECHO Client Partner works within the ECHO Community by developing a software application that communicates with web services available through the ECHO API. The ECHO API allows for various client types including user-interactive, metadata harvesting and other batch processing for scientists and other clients. Most ECHO clients provide access to ECHO's Earth Science metadata and browse catalog and order broker, while other client objectives exist to facilitate Data Partner data management and metrics collection.

The information contained within the Client Partners section of this website is organized to support the efforts of new and current ECHO Client Partners. View a complete list of current ECHO Client Partners.

Client Partner Responsibilities

Client partners are responsible for:

  • Providing an interface which facilitates the discovery of Earth Science data through ECHO's querying services

Getting Started

Getting Started

Application and Operations Agreement

ECHO encourages the development of external clients that take advantage of the services offered ECHO. In order to create an open relationship between ECHO and its client partners, the ECHO team requests that potential client partners begin by completing the Client Partner Application found below. The application will be reviewed by the ECHO team in conjunction with Project Managers to determine compatibility with the ECHO scope and goals set forth by the ECHO Technical Committee (ETC). Please read the Client Partner Operations Agreement (OA) before submitting your application to fully understand all that is required by ECHO Client Partners. By submitting the application, you agree to comply with the terms specified in the OA.

After the submitted application is reviewed and approved, the ECHO team will work with the new Client Partner to complete the Client Partner Operations Agreement. This agreement covers the Client Partner roles and responsibilities in the operational ECHO system and the corresponding roles and responsibilities of the ECHO team.

Please address any questions you have with becoming an ECHO Client Partner by emailing the ECHO team at echo @ echo.nasa.gov. The Client Partner Application and Client Partner Operations Agreement can also be mailed to this address as well.

  • Client Partner Operations Agreement - (PDF) (DOC)

Using the ECHO System

The ECHO API exposes Web Services to allow Client Partners to discover and submit orders for science data contained within the ECHO holdings. Additional services allow for the management of user profiles and groups, event notification subscriptions, service invocations, data access management, and more. For a full view of the ECHO API Web Services, view the API documentation found here: http://api.echo.nasa.gov/echo/ws/v10/index.html.

The information referenced in the Client Partners section of this website will describe in greater detail the functionality available for use by ECHO Client Partners. The Client Partner User's Guide found below has also been created as a consolidated reference for ECHO Client Partners.

  • Client Partner User's Guide - (PDF)

New ECHO Client Partners should also review the Systems section of this website to gain a clear understanding of the different ECHO instances and their specific use. In brief, Client Partners should direct their testing to the ECHO Alpha Testbed or Partner Test systems. The Operational system should only be used for testing in coordination with the ECHO Operations group. The ECHO Team will work with Client Partners wishing to become an Operational Client Partner and perform queries against the Operational system.

Utilized Technology

ECHO utilizes the Web Service Definition Language (WSDL) to expose the web services that are offered by the ECHO API and is compliant with the WS-I Basic Profile 1.0. The WSDL document can be interpreted by programming tools and environments that generate code to expose the functionality natively (e.g., in Java, C/C++, etc.). The actual details of the transport protocol used are handled internally by the code. The ECHO System uses the Simple Object Access Protocol (SOAP) as its transport protocol.

All communication with the ECHO API must be performed utilizing a secure connection. ECHO uses the Secure Sockets Layer (SSL) connection protocol to communicate securely with client applications. All unsecure communication will be denied by the ECHO System.

In conjunction with the available Web Services, ECHO uses the Extensible Markup Language (XML) to represent science data queries and query results. These XML documents are validated by the Document Type Definition (DTD) and XML Schema specifications.

Developers will also want to become familiar with the ECHO Data Model.

  • Facilitating the creation of orders for data represented within ECHO's data holdings through ECHO's order brokerage serices

Discovering Data

Discovering Data

Overview

The topics covered on this page include information regarding the disovery of Earth Science data contained within ECHO's holdings. It is the responsiblity of the Client Partner to expose the ECHO discovery capabilities through the usage of the ECHO API..

The information provided is broken up into the following topic areas:

  • Query Workflow - An overview of how ECHO processes metadata queries.
  • Query Structure - An overview of the ECHO query and results structure.
  • Special Considerations - Highlighted topics regarding metadata discovery of which Client Providers should be aware.

Query Workflow

The ECHO kernel facilitates both synchronous and asynchronous data discovery mechanisms. Both the discovery queries and results may be saved within ECHO for future use by an ECHO end user. If an asynchronous query is performed, the user will be provided with a unique query identifier which may be used to poll for query results. The image referenced below shows the ECHO query workflow.

  • Query Workflow - (PNG)

When initially submitting a query, a maximum result size and iterator size are provided. These values are used to limit the total amount of items which will be returned, and how many will be returned at one time. After a query has returned, the query results may be further accessed through the usage of a 'cursor.' The following list contains the type of results which may be gathered through data queries.

  • Results - Returns the detailed metadata for items that match the query directly in the response.
  • Item Guids - Returns the catalog item guids which match the specified query.
  • Result Set Guid - Returns the result set guid of the results that are stored on the server. The results are not returned and must be retrieved with separate calls to get query results using the Catalog operations.
  • Number of Results - Returns the number of hits (matches) to the query.
  • Hits - Returns the number of hits (matches) to the query and a result set guid for the results stored on the server.

For a complete overview of the ECHO Query workflow, please refer to:

  • Section 4 of the ECHO 10.0 Client Partner User's Guide - (PDF)

Query Structure

In order to facilitate data discovery, ECHO utilizes the Independent Information Management Subsystem (IIMS) Alternative Query Language (AQL). This is referred to commonly as the ECHO "AQL". This query language allows clients to discover data based upon a selection of metadata fields which are contained within the ECHO data holdings.

For a complete overview of the ECHO Alternative Query Language, please refer to:

  • Section 6 of the ECHO 10.0 Client Partner User's Guide - (PDF)

DTDs

The XML messages passed in and received from the ECHO API interface conform to a set of Document Type Definitions (DTDs) that correspond to the particular messages involved. A client partner must use these DTDs in creating the XML messages to query and interpret query results:

  • IIMSAQL query language - (DTD)
  • Collection Results - (DTD)
  • Granule Results - (DTD)
  • Geometry Collection - (DTD)
  • Echo Exceptions - (XSD)
  • Echo Types - (XSD)

Special Considerations

The following items outline some common areas which Client Partners should be aware of while discovering data in ECHO. For a complete overview of data discovery, please refer to:

  • Section 4 of the ECHO 10.0 Client Partner User's Guide - (PDF)

Data Visibility

ECHO Data Partners may create permissioned access to certain collections and granules within their data holdings. These restructions are applied to specific groups of ECHO users and access to permissioned data is dependent upon membership in the defined user groups. Users who are not a member of a group will not be able to access the data restricted to its members. In some circumstances, tThe Data Partner may allow access to a collection, but not to its granules. If you have a need to access specific data, please contact the Data Partner's user-services contact in order to discuss your needs.

Query Performance

In order to reduce the time required to discover data within the ECHO holdings, it is strongly encouraged for ECHO Client applications refrain from performing queries which return the total number of items that fulfill the query. The "Hits" result type will perform this type of query. Also, ECHO Client applications should encourage users to use a reasonable value for "Max Results" when generating a query.

  • Allowings users to access data services offered by ECHO and other Data and Service partners

Ordering Data

Ordering Data

Tip: To download an xsd file, right-click and select "Save Link As..."

Overview

The topics covered on this page include information regarding the creation and management of ECHO submitted through ECHO. It is the responsiblity of the Client Partner to accurately represent the ordering capabilities which ECHO and the Data Partners provide.

The information provided is broken up into the following topic areas:

  • Order Workflow - An overview of how ECHO processes metadata queries.
  • Order Options - The mechanism by which a specific information is requested from a user at the time of ordering.
  • Forms Specification - The specific syntax and features utilized by ECHO Client Partners when displaying an order option definition.
  • Special Considerations - Highlighted topics regarding metadata discovery of which Client Providers should be aware.

Order Workflow

Within ECHO, there are two types of 'orders' which are used to track the request for data from a Data Partner:

  • ECHO Order - A list of metadata items which will be, or has been, requested from one or more ECHO Data Partner. The order also includes necessary information regarding the user and any data-specific order options.
  • Provider Order - A list of metadata items requested from a single ECHO Data Partner, associated with a submitted ECHO order.

The ECHO API facilitates asynchronous creation, updating, and submission of ECHO Orders. An order created in ECHO will persist indefinetely, unless removed explicity by a user. Once an order is created, metadata items may be added, updated, or removed through the API. Some providers support the quoting activity, which allows a user to submit their order to a provider to view the final cost prior to submission. As a part of quoting and submission, an ECHO order will be validated.

Once an valid order is submitted, the appropriate ECHO Data Partners will be contacted, and the order will be fulfilled via the provider's order delivery mechanisms. As an order is processed, the Data Partners will update the order's status. An ECHO Client may choose to allow registered users to view the status of a submitted order.

ECHO Order Options

The term "order option" refers to the mechanism by which a Data Partner can request specific information from a user at the time of ordering. For example, an order option may require that users provide ftp-push information, or specific subsetting information. The ECHO Forms Specification defines the structure and content of the XML documents which are used in ECHO to specify the order options assigned to a collection within the ECHO data catalog. The term "ECHO Form" is used to refer to the XML document created using the standards in the ECHO Forms Specification.

It is the responsibility of the ECHO Data Partners to design, upload, and assign order options to their catalog items using the ECHO Forms Specification. If a provider's collection does not allow ordering, then an order option may not be assigned. It is also the responsibility of the Data Partner to verify that their order options correctly define the information needed to complete the order process.

It is the responsibility of an ECHO Client Partner which is offering the service of ordering ECHO data to implement functionality that will display the ECHO Form. It is strongly encouraged that a Client Partner implementing the ordering functionality ensure that the entire ECHO Forms Specification can be represented. ECHO Data Partners may choose to utilize any and all parts of the specification. If ordering is not a feature which is included in the scope of a Client Partner's work, then they need not implement the ECHO Forms Specification.

Provider vs System Level Forms

The ECHO Forms that are created and uploaded by Data Partner are referred to as "provider level forms." This designates the fact that they are visible only to the Data Partner who uploaded the form. There are also ECHO Forms that are created and uploaded by the ECHO Team, and they are referred to as "system level forms." These forms are visible to all providers. The purpose of system level forms is to centralize common option definition elements which can be shared by all providers in order to reduce duplication of form components.

ECHO Forms Specifcation

The ECHO Forms Specification, found below, outlines the complete set of syntax and features utilized by ECHO Data Partners when creating ECHO Forms. The specification also describes the workflow and user interface elements which are used as form controls. Also found below are links to the XML Schemas defining the ECHO Form's XML structure.

  • ECHO Forms Specification - (PDF)
  • Autopopulate XML Schema - (XSD)
  • ECHO Forms XML Schema - (XSD)

Sample Forms

In order to facilitate ECHO Forms development, some sample provider forms and the current ECHO system form are provided below. Also included is the ECHO Forms Sandbox webpage which may be used to display realtime forms processing.

  • Basic FTPPush/Pull & SCP Provider Level Form - (XML) - This form which utilizes a very simple structure where the user has three distribution methods. Only the FTPPush option is shown in the image.
  • Basic Media & Relevancy Provider Level Form - (XML) - This form which contains options for FTP Push, Pull, CD-ROM, DLT, or DVD media distributions. The provided image shows each media option resulting in different information prompted from the user. This form takes advantage of the 'relevancy' functionality of the forms to determine when or when not to display certain items.
  • Advanced FTPPush/Pull Provider Level Form - (XML) - This form is similar to the xmlFTP_Media example, however it allows a user to enter subsetting information based upon spatial or parameter subsetting. This form takes advantage of an xpath constraint to enforce that the user choose a subsetting parameter scheme. Finally, you will see that this form uses the autopopulate capabilities of the ECHO forms specification to populate the size of the granule into the subsetting options.
  • Advanced FTPPush/Pull Provider Level Form - (XML) - This form provides another example using relevancy, subsetting options, and the autopopulate capabilities.
  • System Level Order Option - (XML) - The current system level form provided by ECHO.
  • ECHO Forms Sandbox - (ZIP)
  • Working in cooperation with the ECHO Operations team to meet the needs of ECHO's expanding user community

Resources

Resources

The resources provided on this page include the following items:

  • Reference Materials - Links to documentation specific for ECHO Client Partners.
  • Reference Client - A sample client which demonstrates basic data discovery functionality.
  • Other Tools - Other tools available to Client Partners.
  • ISO-3166 Country Names - A list of recommended country names for use during ordering.

Reference Materials

The following links and documentation provide quick access to the most commonly used reference materials by ECHO Client Partners.

ECHO Reference Client

The ECHO Reference Client is a working Java-based Web application that interacts with ECHO to demonstrate an implementation of the following basic client operations:

  • Login/logout
  • Query collections and granules

The application is distributed with the source code and is intended to be used as a learning resource by anyone developing software clients for ECHO. While the software is a fully working client, it is not meant to be an operational ECHO client. The user interface is very plain and the system supports only a small subset of the full ECHO functionality.

For questions or comments concerning the ECHO Reference Client, please contact the ECHO Team (echo @ echo.nasa.gov ).

Downloads

The source code and help documents for the ECHO Reference Client are available to registered ECHO Client Partners by request to the ECHO Operations team. Developers looking to become a registered ECHO Client Partner should contact the ECHO team at echo @ echo.nasa.gov.

Other Tools

The ECHO Team also provides various other tools which are available to registered ECHO Client Partners. These tools are made available by the ECHO Operations team to Client Partners.

ECHO Forms Sandbox

The ECHO Forms Sandbox is provided by ECHO to facilitate the creation of ECHO forms. The sandbox contains a single html page which may be used to visualize how a client will likely render the form, and how the option selection should be trimmed by the client according to the form.

  • ECHO Forms Sandbox - (ZIP)

Special Considerations

The following items outline some common areas which Client Partners should be aware of while fulfilling orders in ECHO..

ISO-3166 Country Names

The ECHO system allows user to enter a freeform string to define their contact, shipping, or billing address. In cooperation with the EOSDIS User Services Working Group, ECHO has created a list of approved country names that complies with the ISO 3166 standard. This list of names will appear in the ECHO supported PUMP and WIST tools for for user registration and order creation in WIST. ECHO will support all countries on this list and additional user-entered countries. ECHO Client Partners are encouraged to use this list in their applications to provide a consistent list of countries to all ECHO users. The full list can be downloaded below.

Reference Materials

The following links and documentation provide quick access to the most commonly used reference materials by ECHO Client Partners.

Page Last Updated: May 2, 2019 at 10:33 AM EDT