EQuIS Format Files

<< Click to Display Table of Contents >>

EQuIS Format Files

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.

 

Data providers may submit data to EQuIS using one of the standard format files (e.g., EFWEDD, EQEDD, EZEDD, etc.) or a custom format file. EQuIS formats can be customized to add or change requirements and logic, to add additional fields, change mapping and look-ups, or include conditional checks. EarthSoft strongly recommends that any format to be edited is renamed to distinguish between the original and customized format.

 

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. The EQuIS format file always includes the Format Definition File, but may also include other files. The following files may be included in the format file set:

Format Definition file (.xsd or .xse)

Custom Handler file (.vb or .vbe)

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 (.xsd or .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.)

 

Custom Handler File

 

More extensive checking, such as comparing the value of one field against the value of another, is in the Custom Handler (.vb or .vbe) file. The Custom Handler file 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 the Custom Handler file rules, please contact support@earthsoft.com to obtain an unencrypted version of the format. Learn about writing custom handlers here.

 

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 exist in the same directory as the Format Definition file 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.

 

 

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