List of Supported Formats

Search the Online Transformer Gallery

You are here: Popular FormatsXML (Extensible Markup Language) Reader/WriterMapping File ReferenceReader OverviewReader Mapping File Directives

Reader Directives

The following directives are processed by the XML reader. The suffixes listed are prefixed by the current <ReaderKeyword> in a mapping file. By default, the <ReaderKeyword> for the XML reader is XML.

DATASET

Required/Optional: Required

This keyword specifies the location of the input XML document. The XML Reader is capable of reading XML documents that are gzipped.

Workbench Parameter

Source XML File(s)

Example:

XML_DATASET http://www.safe.com/data/points1.xml

or

XML_DATASET C:\tmp\data\points1.gz

SYSTEM_ENCODING

This directive specifies the system’s encoding. Its default value is the system encoding.

Required/Optional

Optional

Mapping File Syntax

XML_SYSTEM_ENCODING ISO-8859-3

Workbench Parameter

System Encoding

XFMAP

This directive specifies the location of the xfMap document.

Multiple XFMAP keywords may be specified within a mapping file. Each xfMap will map features from the same input dataset. Alternatively, multiple xfMaps may be specified in a single value quoted XFMAP directive by separating each xfMap path with a semicolon.

Required/Optional

Optional

Mapping File Syntax

XML_XFMAP C:\tmp\data\features.xmp

or

XML_XFMAP “C:\tmp\drainages.xmp;C:\tmp\pits_pipes.xmp”

or

XML_XFMAP C:\tmp\drainages.xmp
XML_XFMAP C:\tmp\pits_pipes.xmp

Workbench Parameter

XML Map File

XFMAP_BYPASS_GEOM_BUILDERS

This directive specifies whether geometries should be built fully in xfMap mapping rules.

Ideally, this directive can be set to yes to speed up a process where XML reader is used to generate schema features that do not require any information from the geometries. If set to yes, only null geometries are created.

Required/Optional

Optional

Mapping File Syntax

XFMAP_BYPASS_GEOM_BUILDERS yes

XFMAP_FEATURE_PATHS, XFMAP_FEATURE_PATHS_EXCEPT

This directive specifies whitespace separated xfMap match or except expressions.

The match expressions specify which XML elements in the dataset should be extracted into features containing XML Fragments. The except expressions specify which XML elements in the match expressions should be excluded, and this is especially useful if the match expressions contains wildcard character.The fragments will be held in non-geometrical FME features under their xml_fragment attribute.

Three additional attributes are added to the feature. One records the element that was matched (the xml_matched_element attribute); the other holds an ID for that element (the xml_id attribute); and the last one holds an ID for the parent ID of that element (the xml_parent_id attribute).

  • The xml_matched_element may be used to identify which element matched the expression in the case that the last component of the matched expression is a wildcard, “*”. Note the value for the xml_matched_element is also set as the feature type for the features.
  • The xml_id attribute is not globally unique but is guarantee to be unique only in the context of the dataset.
  • The xml_parent_id attribute is empty if the parent of the element is not matched or it does not have any parent.

  • The xml_parent_child_pos contains the position of the element in relation to its parent. If the parent of the element is not matched or it doesn’t have any parent, then this attribute is empty.

The XFMAP_FEATURE_PATHS directive is useful for decomposing large XML documents into parts, where these parts may be further operated on via downstream XML, XQuery, XSLT or text processing Workbench Transformers.

See the “Match and Except Expression” section in the xfMap documentation for details regarding the match expression.

Required/Optional

Optional

Mapping File Syntax

This example extracts the children of <dc:SearchResults> element from the dataset into XML fragment features except for <csw: metadata> children:

XML_XFMAP_FEATURE_PATHS “csw:SearchResults/*”
XML_XFMAP_FEATURE_PATHS_EXCEPT "csw:SearchResults/csw:metadata"

Workbench Parameter

Elements to Match and Elements to Exclude

XFMAP_FEATURE_PATHS_SUB_FRAGMENTS

This directive is to be used in conjunction with XFMAP_FEATURE_PATHS and allows children of the matched elements to be extracted as xml fragment attributes.

Required/Optional

Optional

Mapping File Syntax

This example extracts each child of <cswSearchResults> into an XML fragment:

XML_XFMAP_FEATURE_PATHS “csw:SearchResults”

XML_XFMAP_FEATURE_PATHS_SUB_FRAGMENTS “csw:SearchResults/*”

XFMAP_FEATURE_PATHS_STRUCTURE

This directive is to be used in conjunction with XFMAP_FEATURE_PATHS and allows children of the matched elements to be exposed as attributes on FME Features.

See the “Structure Element” section in the xfMap documentation for details regarding the options available and more examples.

Required/Optional

Optional

Mapping File Syntax

This example extracts the children of the elements into attributes on FME Features:

XML_XFMAP_FEATURE_PATHS_STRUCTURE <structure/>

Workbench Parameter

Flatten Options

CONTINUE_ON_GEOM_ERROR

Rather than halting the reader, this optional directive allows the reader to continue reading and extracting features from the input XML document stream upon encountering a geometrical error. The valid values of this directive are YES and NO, its default value is YES.

Required/Optional

Optional

Mapping File Syntax

XML_CONTINUE_ON_GEOM_ERROR YES

Workbench Parameter

Continue on Geometry Error

FEATURE_TYPES_SCHEMA_MODE

This directive specifies whether only feature types that exist in the dataset will be generated for the schema.

The default value is XML_SCHEMA in which the XML reader will generate all the feature types that exist in the application schema(s), including all the possible feature attributes that come from XML property elements.

If the value is set to DATASET, then only feature types and attributes that are in the dataset will be generated. If attributes from both the dataset and XML Schema are desired, then set the value to DATASET_MERGE_XML_SCHEMA.

Required/Optional

Optional

Values

XML_SCHEMA (default) | DATASET | DATASET_MERGE_XML_SCHEMA

Mapping File Syntax

This example extracts the children of the elements into attributes on FME Features:

XML_FEATURE_TYPES_SCHEMA_MODE DATASET

VALIDATE_XFMAP

This directive specifies whether the input xfMap document should be validated against its Document Type Definition (DTD).

Required/Optional

Optional

Values

auto | yes | no (default)

Mapping File Syntax

XML_VALIDATE_XFMAP yes

Workbench Parameter

Validate XML Map File

VALIDATE_DATASET

This directive specifies whether the input XML document should be validated against a DTD or an XML schema.

Required/Optional

Optional

Values

auto | yes | no (default)

Mapping File Syntax

XML_VALIDATE_DATASET yes

Workbench Parameter

Validate XML Dataset File

FEATURE_ENCODING

This directive specifies which encoding the mapped FME features should be in.

Required/Optional

Optional

Values

The default value is the system encoding.

Mapping File Syntax

XML_FEATURE_ENCODING Shift-JIS

MAPPING_FILE_ENCODING

This directive specifies which encoding the FME mapping file is in.

Required/Optional

Optional

Values

When not specified, the FME mapping file is assumed to be encoded in the system encoding.

Mapping File Syntax

XML_MAPPING_FILE_ENCODING ISO-8859-3

DOCUMENT_STREAM

This directive specifies as its value the input XML document to parse; that is, the XML document is specified inline in the FME mapping file.

Note: If present, this directive overrides the DATASET directive.

Required/Optional

Optional

XFMAP_STREAM

This directive specifies as its value an inline xfMap document in the FME mapping file.

Note: If present, it overrides the XFMAP directive.

Required/Optional

Optional

XFMAP_SCHEMA

This directive specifies the xfMap(s) that are to be used when reading schema features. Multiple XFMAP_SCHEMA directives may also be specified as per the XFMAP directive.

Required/Optional

Optional

Mapping File Syntax

XML_XFMAP_SCHEMA C:\tmp\data\schema_features.xmp

or

XML_XFMAP_SCHEMA “C:s_drainages.xmp;C:s_pits_pipes.xmp”

or

XML_XFMAP_SCHEMA C:\tmp\schema_drainages.xmp
XML_XFMAP_SCHEMA C:\tmp\schema_pits_pipes.xmp

XRS

This directive specifies the path for an XRS document. An XRS (XML Reader Switch) document allows the XML Reader to automatically configure itself to read “known” XML datasets without the need to specify in advance the appropriate xfMaps.

The directive only applies when both the XFMAP and XFMAP_STREAM directives are absent or empty. A default XRS document is also provided, so the XRS directive is optional even when it is applicable.

The default XRS document is named xrs.xml, and it is located in the xml/xrs subfolder of the FME installation folder.

The documentation for the XRS can be found in the xml/xrs/xrs_doc.txt file.

Required/Optional

Optional

Mapping File Syntax

XML_XRS C:\tmp\my_xrs.xml

Workbench Parameter

XRS File

XR_PIPELINE

The XML reader allows several xfMaps to be specified on the same document stream. Each xfMap may construct its own feature representations for the input stream, for example by deconstructing the hierarchy of the input stream into a flattened structure. The XR_PIPELINE directive allows an FME factory pipeline to be applied on features constructed across xfMaps.

For example, an XML format may define their areas in a hierarchy such that XML representation of an area element contains, either directly or by reference, line children, and each line contains, either directly or by reference, point elements. An xfMap can only construct one feature at a time, so if an xfMap is mapping the area elements to construct area features, then additional xfMaps are required to map line and point elements to construct line and point features, respectively. The XR_PIPELINE directive can then be used to apply a factory pipeline on the areas, lines, and point features for further processing before these are output to FME, say to assemble their topology, if the XML format was topologically based.

Required/Optional

Optional

Mapping File Syntax

XML_XR_PIPELINE C:\tmp\my_topology_assembler.fmi

XFMAP_KEYWORD

This directive allows the specification for name-value pairs that become accessible in an xfMap with the <keyword> expression wherever expression sequences are allowed. See the xfMap <keyword> expression section documentation for more information about its usage.

This directive may occur a multiple number of times in the FME mapping file for multiple name-value pairs.

Required/Optional

Optional

Mapping File Syntax

XML_XFMAP_KEYWORD key0 value0
XML_XFMAP_KEYWORD key1 “my other value”

XFMAP_KEYWORD_FILE

This directive is similar to XFMAP_KEYWORD, but it allows name-value pairs to be specified in an external file.

The XFMAP_KEYWORD_FILE is an XML document. Each keyword name-value pair in the document is specified with a <keyword> element:

<keyword name=”...” value=”...”/>

Each keyword may in addition belong to a named group, thereby allowing keyword names to repeat when these belong to different groups. A keyword belongs to a named group if it is a child of the <group> element:

<group name=”...”>
		<keyword .../>
		<keyword .../>
		...
		<keyword .../>
</group>

Keywords that are not specified as children of a group are in the default group. Keywords that belong to the default group must be children of the root element. The root element for a XFMAP_KEYWORD_FILE document is the <keywords> element.

Note that the keywords defined in the FME mapping file with XFMAP_KEYWORD are also in the default group, and they will take precedence over keywords defined in the XFMAP_KEYWORD_FILE document if a keyword clash occurs.

Required/Optional

Optional

Mapping File Syntax

sample_keyword_file.xml:

<?xml version=”1.0” encoding=”UTF-8”?>
<keywords>
		<group name=”MyGroup”>
			<keyword name=”key1” value=”val-1”/>
			<keyword name=”key2” value=”val-2”/>
		</group>
</keywords>

XML_XR_PIPELINE C:\tmp\sample_keyword_file.xml

MAX_SCHEMA_SCAN_FEATURES

Required/Optional

Optional

Mapping File Syntax

XML_MAX_SCHEMA_SCAN_FEATURES 10000

Values

Any positive number

SEARCH_ENVELOPE

Using the minimum and maximum x and y parameters, define a bounding box that will be used to filter the input features. Only features that interact with the bounding box are returned.

If all four coordinates of the search envelope are specified as 0, the search envelope will be disabled.

Mapping File Syntax

<ReaderKeyword>_SEARCH_ENVELOPE <minX> <minY> <maxX> <maxY>

Note: If all four coordinates of the search envelope are specified as zero, the search envelope will be disabled.

Required/Optional

Optional

Workbench Parameter

Minimum X, Minimum Y, Maximum X, Maximum Y

SEARCH_ENVELOPE_COORDINATE_SYSTEM

This directive specifies the coordinate system of the search envelope if it is different than the coordinate system of the data.

The COORDINATE_SYSTEM directive, which specifies the coordinate system associated with the data to be read, must always be set if the SEARCH_ENVELOPE_COORDINATE_SYSTEM directive is set.

If this directive is set, the minimum and maximum points of the search envelope are reprojected from the SEARCH_ENVELOPE_COORDINATE_SYSTEM to the reader COORDINATE_SYSTEM prior to applying the envelope.

Required/Optional

Optional

Mapping File Syntax

<ReaderKeyword>_SEARCH_ENVELOPE_COORDINATE_SYSTEM <coordinate system>

Workbench Parameter

Search Envelope Coordinate System

CLIP_TO_ENVELOPE

This directive specifies whether or not FME should clip features to the envelope specified in the SEARCH_ENVELOPE directive.

Values

YES | NO (default)

Mapping File Syntax

<ReaderKeyword>_CLIP_TO_ENVELOPE [yes | no]

Workbench Parameter

Clip To Envelope

EXPOSED_ATTRS

This directive allows the selection of format attributes to be explicitly added to the reader feature type.

This is similar to exposing format attributes on a reader feature type once it has been generated; however, it is even more powerful because it enables schema-driven applications other than Workbench to access and leverage these attributes as if they were explicitly on the schema as user attributes.

The result of picking a list of attributes is a comma-separated list of attribute names and types that will be added to the schema features. Currently all reader feature types will receive the same set of additional schema attributes for a given instance of the reader.

Required/Optional

Optional

Mapping File Syntax

Not applicable.

While it is possible for FME Objects applications to invoke this directive, the required format is not documented.

This directive is intended for use in our GUI applications (for example, Workbench) only.

Workbench Parameter

Additional Attributes to Expose

HTTP_AUTH_USER

Required/Optional

Optional

Specifies the username to use when accessing a password-protected HTTP server.

Mapping File Syntax

<ReaderKeyword>_HTTP_AUTH_USER someusername

Workbench Parameter

Http Username

HTTP_AUTH_PASSWORD

Required/Optional

Optional

Specifies the password to use when accessing a password-protected HTTP server.

Mapping File Syntax

<ReaderKeyword>_HTTP_AUTH_PASSWORD password1234

Workbench Parameter

HTTP Password

HTTP_AUTH_METHOD

Required/Optional

Optional

Specifies the authentication method (Basic, Digest, or NTLM) to use when accessing a password-protected HTTP server.

Mapping File Syntax

<ReaderKeyword>_HTTP_AUTH_METHOD Digest

Workbench Parameter

HTTP Authentication