Define File/Field Map

This page describes how to map incoming data to Appx files/Fields.

Overview:

This option allows you to maintain existing File/Field maps. You can also use this to add new mappings, but it's usually easier to define a new map using Define File/Field map from Source File.

Usage

When you click 'Define File/Field Map', you will see a display similar to the following:

The usual options for adding/changing/deleting are available. From here you can maintain the Component Files, Component Fields, Ignorable Segments and Replaceable Segments.

Component Files

The 'Component Files' button allows you to specify what identifiers indicate the beginning of a new record in the source file:

You can also click the 'Populate Field Map' button to populate the 'Component Fields' file with all the fields in the currently selected file. This might be easier than manually entering the fields later. However, if the Appx file has many fields and you are only importing a few of them, it might be easier to manage if you just manually add the fields.

Component Fields

The 'Component Fields' button allows you to specify what fields the imported data should be moved to:

The 'Details' button will allow you to change the specifics of a field mapping:

The valid source types are:

1. XML Data Field. When we choose this type, the XML Identifier, Application Id and Proces Name fields will become available for input. The Application Id and Process Name allow us to specify a subroutine that we want to run when this field is imported (optional). The subroutine will be invoked DETACHED and will be passed 4 fields. You should RECEIVE three type 'FIELD' and one type 'RECORD'. The first field is the data extracted from the XML file, the second field is the XML identifier, the third field is the Element Type (TEXT, ELEMENT, END ELEMENT, etc) and the last field is the contents of the record buffer. This allows you to refer to other fields in the record if you need them. Remember that only the fields that have been processed will have a value. You can change the first field, and the resulting data will be written to the Appx file. You can also change fields in the record buffer, however if a subsequent mapping assigns a value to a field you changed, your change will be lost.
2. Parent APPX File. We use this when we want the Appx field to be filled in from another (Parent) Appx File. For example, when importing the Contacts, we want the CONTACT PROSPECT NO field to be filled in from PROSPECT NO. When we choose this type the Parent File Id and Parent File Field fields will become available for input.
3. Sequence Number. Use this to automatically assign a sequential sequence number to the Appx field. Note that the sequence number starts at zero every time you run the import step, so normally you would not use this to generate unique keys in an existing Appx file that uses a sequence number key.
4. Date/Time Stamp. The current date/time will be set in the field.

The XML Type indicates which tag type this mapping is applicable to. Most data will be in the TEXT tag type, however, if your incoming data contains something like <phone> </phone>, the whitespace will not trigger a TEXT record in XVALUE. In this case, you might want to add another mapping triggered by the END ELEMENT tag. You can then use a subroutine to check values, etc, as required.

Ignorable Segments

Ignorable Segments are segments we want removed from the identifiers. For example, most XML files have a top level segment, such as 'ProspectData', and all identifiers are subordinate to that (ie, /ProspectData/Prospect No, /ProspectData/ProspectName, etc). To simplify our mapping, we might want the 'ProspectData' portion removed so that we have /ProspectNo, /ProspectName, etc. In that case, we would enter 'ProspectData' as one of the Ignorable Segments.

Replaceable Segments

Replaceable Segments are used for a very particular situation. Consider the following XML fragment:

Notice that the Segments all have the same name (j2:feature), and the identifier is really encoded in the attribute (name="..."). In this case, we can use the Replaceable Segments to move the attribute to the segment, which will allow us to map the segment to an Appx field:

Now our segment names will become "SourceName", "FileSystemProperties", "Path", "LastModified" instead of "j2:feature"

Comments:

Read what other users have said about this page or add your own comments.

-- JeanNeron - 2013-10-01