EQuIS Format Files

Data providers may submit an EDD (Electronic Data Deliverable) to EQuIS using one of the standard format files (e.g., EFWEDD, EQEDD, EZEDD, etc.) or a custom format file. The EQuIS format file is the essence of data checking in EDP and EQuIS. Structured in eXtensible Markup Language (XML), the EQuIS format file set contains the definitions and restrictions for each individual field in available data tables. The format files control data checks, such as range checking, reference values, formatting and enumerations.

Standard EQuIS formats are located in the EarthSoft Formats folder (e.g., \EarthSoft\EQuIS\Formats\EarthSoft). Standard formats are encrypted and are contained in a .zip file. Modifications to EarthSoft standard format files are not supported under the EarthSoft Software Maintenance Agreement (SMA). If modifications are made to these formats, it is required that the formats are renamed to include your organization name. This will also ensure that the modified formats will not be overwritten during any EQuIS updates.

EQuIS formats can be customized to add or change requirements and logic, to add additional fields, change mapping and lookups, or include conditional checks.

Structure of EQuIS Format Files

Format files may be encrypted or unencrypted. Unencrypted format files may be edited or customized, whereas encrypted files cannot be changed. Starting with the EQuIS 7.22.1 Build, plain-text EDD format files (i.e., unencrypted with *.xsd file extension) may no longer be used except in EDP Standalone or EDGE or when using Professional EDP with database-level security. See the Securing EDD Formats article for more details.

The EQuIS format file always includes the EQuIS Format Definition (EFD) file and the format .dll file, but may also include other files. Custom Handler code contains the custom business rules that apply to the format and is compiled in the format .dll file. The following files may be included in the format file set:

•Format Definition file (.xsd or .xse)

•Enumeration file

•Export file (*-export.xml)

•Reference Value file (.rvf) – Only needed when using EDP Standalone or not connected to a database.

Format Definition File

Simple checks, such as range checking, reference values, formatting and enumerations, are included in the Format Definition (.xse) file. The Format Definition file contains the mapping and definition for the sections of the format file to the data table and fields in the EQuIS database, such as:

•Required fields

•Primary keys

•Field length

•Field description

•Field type (numeric, text, etc.)

Enumeration File

Enumerations are a way to enforce vocabulary on fields that have no reference tables. Enumerations can also restrict the vocabulary of fields that do have existing reference tables. The Enumeration (or enum) file is an optional file that allows EDP to enforce a set of lookup values for specific fields that are not linked to a reference table in the EQuIS database or to a subset of values within an existing reference table. For example, elevation units would typically be linked to the RT_UNIT table, which may contain 100 or more units. Thus, the enumeration file might be used to limit the elevation units to "meters" and "feet" since those are the only valid units for this type of data.

The Enumeration file is used in EQuIS Professional EDP as well as EDP Standalone. The enum file must be in the same directory as the rest of the format files and properly named and referenced within the format file, otherwise an error will occur when opening the format. The Enumeration file is created and maintained manually using any text editor.

Export File

The Export file is used to customize EDD exports. For large or complex EDD formats, having a number of different types of exports may be useful. For example, the EFWEDD format includes one export for lab EDDs and another for field EDDs. Each of these different exports is defined within the same *-export.xml file as a "report".

For the *-export.xml file to be used by the format, the *-export.xml file must either exist in the same directory as the Format Definition file or be embedded in the assembly (see the Securing EDD Formats article), and the Format Definition file must include a <edd:export>node within the <xs:appinfo> node that indicates the name of the *-export.xml file (see the Format Export File article for more information).

Reference Value File

For each EQuIS database, reference values are defined and are required to process an EDD for errors in EDP. Professional EDP uses the values in the Reference Tables from the connected EQuIS database. Since EDP Standalone is not linked to a specific EQuIS database, the desired reference values must be loaded using a Reference Value File (RVF). The RVF is created as an export from reference tables in EQuIS Professional (see Creating a Reference Value File article).

Note: EarthSoft recommends using the RefVals Format to create analyte groups. Populate the RT_MTH_ANL_GROUP and RT_MTH_ANL_GROUP_MEMBER fields.

Custom Handler Code

More extensive checking, such as comparing the value of one field against the value of another, is handled in the Custom Handler code. The Custom Handler code contains the custom business rules that apply to the format. The following are examples of business rules:

•The analysis date cannot proceed sample date.

•REPORTABLE_RESULT field cannot be "Yes" when the LAB_QUALIFIER field is E, G, P or R.

•If a certain sample type is encountered, then another field must be populated (e.g., if a SAMPLE_TYPE field is "FD" (field duplicate), then the parent sample field must be populated to avoid an orphan quality assurance/quality control sample).

To edit Custom Handler rules, please contact support@earthsoft.com to obtain an unencrypted version of the format. Learn about writing custom handlers here.

Customizing an EQuIS Format File

When customizing a format file, start with an existing standard format. Review the different standard formats and select the format closest to the desired result. In addition to the format structure, also consider if the following attributes are present and/or desired:

•Required fields

•Custom fields

•Format variations

•Field position

•Field names and data types

•Look-up tables

To modify a standard EQuIS format, an unencrypted version of the format file (*.xsd) is needed. Unencrypted format files of standard encrypted formats can be provided to clients who have executed the Source Code License Agreement (SCLA) and maintain a current EarthSoft Software Maintenance Agreement (SMA). Please see Making Changes to Format Files for more information.

Proprietary Formats

Proprietary, custom EQuIS formats were requested and designed for a third party. An example of a proprietary EQuIS format is the EPA Region format. Proprietary EQuIS formats contain specific business rules and are encrypted. Proprietary formats and their download pages are available at https://earthsoft.com/support/edd-formats.

For more information about customizing a format or for obtaining and registering a proprietary format, please email support@earthsoft.com.