NAACCR XML Utility

The supported NAACCR versions and record types are listed on the individual pages of the tool.

Data files can be compressed using the GZip (.gz) compression.

Several software can be found online to compress/uncompress a given file. For example, 7-Zip is a free standalone program that will handle the two compression methods.

The utility tool allows you to select the compression as part of the conversion options.
By default, the compression is set to the same one as the source file, but that can be changed by using the compression drop-down.

Follow the following steps to convert a flat file into the corresponding XML format:

1. In the left navigation bar, select the Flat to XML button.
2. Use the Browse button and select the source data file you would like to convert.
3. Review the target file and the compression drop-down; change the values if the default ones are not what you need.
4. Review the processing options.
5. If you need to, provide a user-defined dictionary.
6. Click the Process Source File button.
7. The file will first be analyzed, and the processing will start automatically if no issues are detected during the analysis.
8. The interface will show the created file, its size and the processing time; it might also show some warnings gathered during the processing.

Follow the following steps to convert an XML file into the corresponding flat-file format:

1. In the left navigation bar, select the XML to Flat button.
2. Use the Browse button and select the source data file you would like to convert.
3. Review the target file and the compression drop-down; change the values if the default ones are not what you need.
4. Review the processing options.
5. If you need to, provide a user-defined dictionary.
6. Click the Process Source File button.
7. The file will first be analyzed, and the processing will start automatically if no issues are detected during the analysis.
8. The interface will show the created file, its size and the processing time; it might also show some warnings gathered during the processing.

Follow the following steps to re-create an XML file using specific options (for example to add the NAACCR Item Numbers):

1. In the left navigation bar, select the XML to XML button.
2. Use the Browse button and select the source data file you would like to convert.
3. Review the target file and the compression drop-down; change the values if the default ones are not what you need.
4. Review the processing options.
5. If you need to, provide a user-defined dictionary.
6. Click the Process Source File button.
7. The file will first be analyzed, and the processing will start automatically if no issues are detected during the analysis.
8. The interface will show the created file, its size and the processing time; it might also show some warnings gathered during the processing.

Follow the following steps to validate a given NAACCR XML file:

1. In the left navigation bar, select the XML Validation button.
2. Use the Browse button and select the source data file you would like to validate.
3. Review the target file and the compression drop-down; change the values if the default ones are not what you need.
4. Review the processing options.
5. If you need to, provide a user-defined dictionary.
6. Click the Process Source File button.
7. The file will first be analyzed, and the processing will start automatically if no issues are detected during the analysis.
8. The interface will show the created file, its size and the processing time; it might also show some warnings gathered during the processing.

Follow the following steps to view one of the standard NAACCR dictionaries:

1. In the left navigation bar, select the Standard Dictionaries button.
2. Select one of the dictionaries in the drop-down.

You can also use the Extract to CSV... button to create a CSV file containing all the data items of dictionary currently selected.

To create your own user-defined dictionary, select the Dictionary Editor button in the left navigation bar.

The toolbar on the top of the page allows the following actions:

• Load: load an existing dictionary from an XML file.
• Save: save the current dictionary in the current file.
• Save As: save the current dictionary in a new file.
• Validate: validate the current dictionary.

When editing your dictionary, you may modify the following fields:

• URI: this is a sequence of characters that uniquely identifies your dictionary; by convention it looks like an online address (a URL), but the dictionary itself doesn't have to be maintained online at that address.
• Version: which NAACCR version your dictionary will be used for; leaving the value to Any implies that it can be used with several versions (this usually requires to leave the Start Columns blank in the data items since items tends to shift location in the flat file standard).
• Description: an optional description for you dictionary.
• Data Items: the data items making up your dictionary. The following properties can be modified for each item:
  • ID: a sequence of characters that uniquely identifies the data item; to minimize conflicts it is recommended to use a prefix for every data item that is relevant to your company or organization.
  • Num: a number that also uniquely identifies the data item.
  • Name: the data item name.
  • Start Col: this is only applicable for old (pre-NAACCR-21) dictionaries, but the column is still displayed for all dictionaries.
  • Length: the data item length.
  • Record Types: to which record type(s) this data item applies.
  • Parent XML Element: the parent XML tag of the data item in the NAACCR XML structure.
  • Data Type: the data type of this data item; leaving the default value of Text means that you impose no restriction on the values that the data item can have in the XML data files.
  • Padding: the padding rule to apply when writing values to a flat or XML file (this libraries doesn't apply padding rules by default but offers an option to turn that feature on).
  • Trimming: the trimming rule to apply when reading values form a flat file (most data items should be left to the all default value.
  To add or remove rows in the data item tables, use the table context menu by right-clicking on one of its rows. Not all options might be available depending which row is selected.

For more information about the NAACCR XML standard and the meaning of those attributes, check out the implementation guide on the NAACCR website.

This software uses binary code from the following projects:

• Apache Commons - Released under Apache 2.0 License
• XML Pull - Released to Public Domain
• Thoughtworks XStream (https://github.com/codehaus/xstream) - License:
  • (BSD Style License) Copyright (c) 2003-2006, Joe Walnes Copyright (c) 2006-2011, XStream Committers All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of XStream nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.