Tip: To download an xsd file, right-click and select "Save Link As..."
The ECHO system acts as an order brokering service between end users and Data Partners. Users may submit orders for collections and granules that have been ingested into ECHO and marked as 'orderable.' ECHO will keep basic metrics and information regarding the order including the orderer's information, order contents, and historical order updates.
For a more detailed description of order fulfillment, please refer to:
- Sections 6 & 7 of the ECHO Data Partner User's Guide - (PDF)
The information provided is broken up into the following topic areas:
- 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 Data Partners when creating an order option definition..
- Order Fulfillment API - Ordering service which each Data Partner provides to fulfill orders submitted through ECHO.
- Special Considerations - Highlighted topics regarding order fulfillment of which Data Providers should be aware.
To access the Provider User Management Program (PUMP) for order policy configuration and order tracking, visit the following links:
* Operations - http://api.echo.nasa.gov/pump/
* Partner Test - http://api-test.echo.nasa.gov/pump/
* Testbed - http://testbed.echo.nasa.gov/pump/
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.
Order Option Assignments
Within ECHO, an option assignment must be created between an option definition and collection in order to signifiy that order options exist during the ordering process. Multiple definitions may be assigned to a single collection, and a definition can be assigned to multiple collections. An option assigment may also include an Xpath statement which will filter on a granule's metadata to determine whether the granule should use the assigned option definition, or not.
ECHO Forms Specification
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)
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) (JPG) - 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) (JPG) - 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) (JPG) - 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) (JPG) - 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)
Order Fulfillment API
Data Partners who wish to support receiving orders from ECHO must provide an Order Fulfillment Service at their data center which interfaces directly with their Earth Science data system. ECHO will then transmit order submissions, quotations, and cancellations to the provider. The provider's Order Fulfillment Service fulfills the requested orders and communicates with the the ECHO API as the status of the order moves to completion. These status updates are used by the ECHO Operations team and the Data Partner's User Services group to provide user support to the science community.
The following links provide the necessary information to utilize the Order Fulfillment capabilities of the ECHO system. Also provided is a sample implementation of an Order Fulfillment Service which can be run by a Data Partner to receive orders from ECHO.
- Order Fulfillment API Documentation - (HTML)
- Order Fulfillment Types XML Schema - (XSD)
- Order Fulfillment Service WSDL - (WSDL)
- Sample Order Fulfillment Service - (ZIP)
The following items outline some common areas which Data Partners should be aware of while fulfilling orders in ECHO..
SSL Secure Connections
Data Partners are encouraged to configure their Order Fulfillment Service endpoint to utilize the SSL protocol. In order to request ECHO to use the SSL protocol, a Data Partner can use PUMP to update their order policies with the public portion of the SSL certificate. The ECHO Operations team will review the certificate and activate the policy. The policy will be immediately in affect.
Provider Tracking ID
The Order Fulfillment API allows Data Partners to update the order status in ECHO with a field called 'provider tracking ID.' This field is the unique tracking ID which is assigned within the Data Partner's ordering service. In order to facilitate order tracking from ECHO, Data Partners should update the corresponding order in ECHO with their unique ID as soon as it is assigned.
A Data Partner can acknowledge an order submission with the following two update mechanisms:
- Automatic - Indicates that the order has been completed by the provider and ECHO should consider the order closed.
- Manual - Indicates that the provider will notify ECHO as the order is fulfilled.
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 Data 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.