Products Documentation

« Back to User Guide

$Id: index.html 17879 2012-12-12 19:49:10Z jmfee $
$URL: https://ghttrac.cr.usgs.gov/websvn/ProductDistribution/tags/1.8.9/etc/documentation/userguide/products/index.html $

Known Product Types

This is a list of known products being sent via Product Distribution.

Special "admin" products

Most products provide information about one event. The existence of one of these products in an event will change the way the indexer indexes, and they are generated by administrative users who need to override the default association/processing logic.

Designing New Products

What is a Product?

A product is a specific version of any content produced in response to an earthquake, information about an earthquake, or another product.

A product usually consists of a directory of files, but may also include a stream of bytes, links to internet resources, and key/value pairs.

Product IDs

The source, type, and code uniquely identify a product and its associated content. Update times indicate different versions of the same product, and products with more recent update times supersede products with less recent update times.

source
The product creator. Usually a network code.
type
The type of product. Multiple sources may create the same type of product.
code
A unique code, for a given source and type combination.
update time
When this version of content was created. Two products with the same source, type, and code, but different update times are different versions of the same product.

Status

A brief status code. Typically UPDATE or DELETE. Any value that is not DELETE is considered an update.

When a product producer deletes a product they send an update with a status DELETE, which is distributed like any other product.

Contents

Files

Contents are optional, but are usually present when the status is not DELETE. Each content has a path, which corresponds to a filename.

Non file content

Each product may have one piece of content that is a stream of bytes. It has an empty path and isn't stored in a file. Typically this content is read from standard input, and also delivered to consumers via standard input.

Metadata

Links

A product may include links to other products and resources. Links have a relation, which specifies how the resource is related to the product. There may be multiple links for each type of relation.

Properties

Key value pairs. Each property may only have one value. These can be used to determine whether further processing is required. "Standard" properties include:

eventsource
network code of related event
eventsourcecode
network event code of related event
eventtime
time of related event
latitude
latitude of related event
longitude
longitude of related event
depth
depth of related event
magnitude
magnitude of related event
version
producer product version. This is not used for ordering products, which use update time as a versions.

All of these properties are optional, but a combination of either eventsource and eventsourcecode OR eventtime, latitude, and longitude are recommended for event-related products for association purposes.

Signature

Producers generate a signature which may be verified by both hubs and consumers. The signature consists of a hash of all product contents and attributes, which is encrypted using a private key and verified using a public key.

Production hubs require a signature, and a keypair must be registered before products are sent.

Generating a “Good” Product

The information contained in this section is a recommendation, not a requirement however recommendations can be seen as a best practice when generating new products.

Product Properties

Properties should be defined for important attributes of your product. They allow recipients to quickly determine whether they should process a product, without extensive parsing.

For example, eventsource and eventsourcecode are used by the indexer to associate a product with an event. Other examples include dyfi number of responses, losspager alert level, and shakemap maximum MMI.

Product-Specific Properties

Products may have properties that are specific to that product type. For example, the origin product has a custom azimuthal-gap property. Like all product properties, these properties are set using name/value pairs, using either command line Java parameters on a product send, or within a node of an XML file sent with the product.

These properties aren't pre-configured using INI files like config.ini, however they often need programmatic support, such as identifying which XML file and node contains a custom property. For this reason, please contact jmfee@usgs.gov in advance before creating a new product type.

Contents.xml File

It is recommended you include with your product a “contents.xml” file. This file describes all of the contents you are sending with your product. It helps the web page to better display your product and ultimately determines what content users will be able to easily download from the web site.

The contents.xml file format is defined with a contents.xsd file. You must understand how to read XML schema (XSD) files in order to properly generate a contents.xml file.

Grouping Content

When mapping products into PDL, it is important to consider how content is generated and updated when deciding what individual products should contain.

For event-related products, the group of content is everything related to that event.

For non-event-related products, the group depends more on how content is generated and updated. For example, station related content might be broken up by station. It's possible that this content would need to be further divided based on update intervals.

Product Code Conventions

A product code must be unique forever, from the same source and type. Product creators also reuse the code to update or delete the product.

For event-related products, an eventid makes a good code because it also must be unique forever. Examples include : us2011abcd and nc12345678.

For non-event-related products another ID scheme is required. Timestamps are often useful in this situation when the products are related to a time window.

An internal database key can be used.