Ordering Data Through ECHO

After identifying data of interest through catalog queries, you may place an order for that data if the data provider(s) allow it. To create an order, it is critical that you understand the parts that make up an order. 
An order is a collection of order items. Each order item consists of:

• The GUID for the catalog item you wish to order
• The quantity of the item you wish to order

Other options associated with the item 
Many catalog items belonging to many different providers may comprise a single order. Each provider may have its own validation scheme and rules for creating, validating, and submitting their particular catalog items. To ensure appropriate validation – as well as to demarcate a larger order for sending to each provider – orders are split up into smaller provider orders, sometimes called sub-orders. Each provider order includes all the order items in a particular order that belong to a specific provider. Each provider order has its own provider order GUID, a unique identifier comprised of the GUID of the provider and the GUID of the order that contains the catalog items for this provider. The following figure shows the structure of an order.

ECHO Order Structure 

ECHO is designed to support a variety of providers and their various ordering needs, which brings some complexity to the process of order creation. The following figure illustrates the most commonly used and direct approach for creating and submitting an order.

The most common way to obtain the catalog items needed for creating an order is through the ExecuteQuery operation found in the Catalog Service. You can also specify how the results should be displayed. When doing so, ensure that the CatalogItemID tag is returned. The string value under this tag is the actual catalog item GUID that you can use to order items from ECHO.

Order Options 

Order Options use ECHO Forms (refer to  http://www.echo.nasa.gov/data_partners/data_tools10.shtml for more information) for providers to indicate additional information required from users in order to fulfill their orders, such as the media to put the ordered data on and the specific subset of the data to order. Providers assign Order Option definitions to catalog items. When you add an order item to an order that has required order options, it must contain an option selection that corresponds to one of the assigned option definitions for the catalog item you are ordering. See section 1.3 of the ECHO Forms Specification for more details. 
To list the possible options for each catalog item, use the GetCatalogItemOrderInfomation operation on the 
OrderManagementService. The operation returns one object called CatalogItemOrderInformation. This contains a list of catalog items and a list of option definitions. Not every option definition in the list applies to every catalog item returned. Each catalog item is associated with zero or more option definition GUIDs, which will be included in the list returned in CatalogItemOrderInformation. Use only one selection from one of the definitions when you add a catalog item to the order. Use your discretion when choosing the definition to use for the order and the selection from within that definition.

The code listing below shows an example of getting the order options for two granules. 

String token = "[token obtained from login]"; 
// The items we're interested in 
String[] catalogItemGuids = new String[] { "G12345-PROV1", "G23456-PROV1" };
Get the service OrderManagementServiceLocator locator = new


OrderManagementServiceLocator(); OrderManagementServicePort orderService = 
locator.getOrderManagementServicePort();
Get the order information CatalogItemOrderInformation itemInfo =


orderService.getCatalogItemOrderInformation(token, catalogItemGuids); 

Creating an Order

Once you have collected the catalog item GUIDs and associated options, you can create an order by calling the CreateOrder operation on the OrderManagementService. Simply pass an array of item IDs to add to the order. 
Common Selection 
If you are adding one or more items to an order at the same time, and their selections are the same, you can choose a common selection for the CreateOrder, AddOrderItems, CreateAndSubmitOrder, and UpdateOrderItems operations that will be applied to all order items passed in without an option selection. This reduces the amount of data transmitted to ECHO and is less resource-intensive because ECHO will need to validate the common selection only once. 
For each item in the array, you should set the following parameters:

Parameters on a Catalog Item

The other attributes of Order Item should be empty when creating an order; ECHO will populate them automatically. ECHO will process the request and return a GUID identifying the newly created order. The code listing below shows an example of creating a simple order. 

OrderItem[] orderItems = new OrderItem[2]; orderItems[0] =
new OrderItem(null, null, "G12345-PROV1", null, (short) 2, null); orderItems[1] =
new OrderItem(null, null, "G23456-PROV1", null, (short) 2, null); String orderGuid = orderService.createOrder(token, orderItems,null);

Adding Order Items 
Once you have created an order, you may add other items to it using the AddOrderItems operation. This operation uses the GUID of the target order and a list of items to add. As with CreateOrder, the options other than those listed in the table above should be empty; ECHO will process the additions and return a list of GUIDs identifying these additions. The code listing below shows an example of adding items to an existing order. 

orderItems[0] = new OrderItem(null, null, "G34567-PROV1", null, (short) 2, null); 
orderItems[1] = new OrderItem(null, null, "G45678-PROV1", null, (short) 2, null); 
orderService.addOrderItems(token, orderGuid, orderItems,null); 

Updating Order Items
Once you have added an item to an order, you can modify the options or quantity by calling UpdateOrderItems and passing in the modified items. In this case, you must fill in the GUID of each item since ECHO needs to findthe original item in your order to update it. To ensure you are updating the appropriate item with the correct information, follow these steps:

• Call GetOrderItems to populate the data.
• Modify the desired order items.
• Pass the results to UpdateOrderItems.
  

The code listing below shows an example of updating an existing item.

NameGuid[] itemNames = orderService.getOrderItemNamesByOrder(token, orderGuid); 
String[] orderItemGuids = new String[] { itemNames[0].getGuid() }; 
OrderItem[] items = orderService.getOrderItems(token, orderItemGuids); items[0].setQuantityOrdered((short) 22); 
orderService.updateOrderItems(token, items,null);

Removing Order Items 

You may remove items from an order using the RemoveOrderItems operation as shown below: 

itemNames = orderService.getOrderItemNamesByOrder(token, orderGuid); 
orderItemGuids = new String[] { itemNames[0].getGuid() }; 
orderService.removeOrderItems(token, orderItemGuids);

Removing Orders and Canceling Orders

To delete a specific provider order(s), use the RemoveProviderOrders operation. You cannot delete orders that you have already submitted. For post-submittal orders, a registered user can use the CancelOrder operation on the OrderManagementService to cancel an open order. 
Guest orders cannot be deleted in the post-submittal phase; the CancelOrder operation will delete the entire order, including all associated orders.

Setting User Information for an Order

Every order must have its own user-specific information attached to it so that a data provider can process the order. Contact information, billing, and shipping addresses are all required as well as user domain and region. Each order is independent of other orders, so user information must be set up for each order created. 
You may set up user information at any point in the order process prior to submission. User information is not required until you validate, quote, or submit the order. If the required information is not present at that time, you will receive an error. You can set up user information for an order by calling the SetUserInformationForOrder operation on the OrderManagementService.

Validating an Order

To ensure that an order is complete, with all the required options and user-associated information for that order filled out, ECHO validates all orders when submitted or quoted. If you attempt to submit an invalid order, you will receive an error message. Currently, the message reflects only the first validation error encountered; you need to fix the reported error and revalidate until the order is error-free. At this point, if you change any aspect of the validated order before finally submitting it, then the order will again require validation. To validate orders, call SubmitOrder or QuoteOrder. You can manually validate orders with the ValidateOrder operation in the 
OrderManagementService.

Keep in mind that running the ValidateOrder operation may return a validation error related to one of the many provider-specific validation rules, which may change over time. You should find the error messages complete enough to help you determine what aspects of the order you need to correct. 

Note that validation errors can occur if the order specified does not exist, or does not belong to you.

Requesting a Quote for an Order

Requesting a quote is an optional step that not all providers support. A quoted order provides a binding price for the order as a whole. The binding quote response from each of the necessary providers may take a day or more to receive. You cannot make changes to an order while it is in the quoting process. If you make changes to the order subsequent to the receipt of a quote, the changes may invalidate the quoted price. You may request a quote from a provider by calling QuoteOrder.

Submitting an Order

Once you have fully validated an order and have made no subsequent changes to the order, submit the order to the system using the SubmitOrder operation in the OrderManagementService. 
Specify your preference for receiving order status information using one of the NotificationLevel choices shown in Table 10: ECHO Order Notification Levels

ECHO Order Notification Levels

If you do not specify any notification level for a registered user's order, ECHO will use your preference value. If you, as a registered user, have not set a preference value, the default value is INFO. The notification for all guests' orders is also INFO. 
Once an order transmits to the system using the SubmitOrder operation, ECHO sends each provider order contained within your order to the appropriate provider. Each provider will decide whether to accept your provider order and how to process it. 

Tracking and Canceling Orders 
From this point on, you can track the status of an order using the GetOrders operation in the OrderManagementService. At any point before the order actually ships, you may request cancellation of the order through the CancelOrder operation. You can then use the GetOrders operation again to track whether you successfully cancelled the order. 
When ECHO sends a request to a provider to quote, submit or cancel a particular order, both ECHO and that provider must have the same ID for that order. ECHO identifies the specific provider order by the ProviderOrderGUID (which is the combination of the provider GUID and the order GUID). However, the provider may also have its own ID system for tracking a particular provider order. As a solution, the provider order in ECHO also contains a provider-tracking ID. When the provider receives the request from ECHO, the provider has the option to accept the order GUID that ECHO has assigned to that provider order, or to provide ECHO with its own unique ID. If the provider does pass back its own unique ID as the provider-tracking ID, then ECHO will use that ID in addition to the normal ECHO ProviderOrderGUID to refer to this provider order. If the provider does not specify a tracking ID, then the provider order will be referenced using only the ECHO ProviderOrderGUID.

Order States

An order consists of zero or many provider orders. An order state is calculated based on the state of the individual provider orders that make up the order. The table below shows the order states for orders made up of zero or one provider order or of multiple provider orders having the same provider order state. 

Order States with 0 or 1 Provider Order

Restricted or Deleted Order Items 
Some catalog items you may order only with permission. Each provider sets the restrictions and permissions on catalog item ordering. Providers may also delete catalog items at any time. Restrictions can apply to individual users, groups of users or all users. If a catalog item is not available to you, executing the 
CreateAndSubmitOrder, GetCatalogItemOrderInformation, CreateOrder, or AddOrderItems operation with this catalog item will return an error message indicating that it is not an orderable item. If an item becomes unavailable after you have created an order, you will receive an error message when you invoke the 
UpdateOrderItems, ValidateOrder, QuoteOrder, or SubmitOrder operation on that order.