Skip to content

Transformer Execution Instructions (Mapping File)

Everything in the Execution Instructions is what is actually inserted into the mapping file. The transformer name can be inserted using the tag $(XFORMER_NAME) and you'll need it, as almost everything is prefixed with it, or with $(FME_UUID), for namespacing.

Input tags can be specified using $(INPUT_<type>_LINES) to insert tags of a given <type>, or $(INPUT_LINES) to put all input lines at once.

Output tags can be specified using $(OUTPUT_<type>_FTYPE) to insert output tags for the feature type <type>. Output functions can be inserted by specifying $(OUTPUT_<type>_FUNCS)

Parameters can be substituted into the template by encasing it in $() For example $(MYPARM), to substitute the parameter named MYPARM. The following parameters are built in:

  • XFORMER_NAME_ENCODED && XFORMER_NAME the transformer name input by the user
  • XFORMER_VERSION the version number of the transformer
  • FME_BRACED_PARM_VAL_LIST parameters and their values written in key { value } form assuming {*} syntax is used on the factory definition
  • FME_PARM_VAL_LIST parameters and their values written in key value form. This can be useful to add all parameters to a factory definition without individually specifying each parameter
  • FME_PARM_LIST list of parameter names separated by ','. No values included

Use the {*} rather than * in the template start. This indicates that { } will be the indicator of the keyword value rather than space. Otherwise, if the user publishes the parameter and leaves it blank, the parser will fail because the keyword has no value.

FACTORY_DEF {*} MyFactory
  ....
  KEYWORD { $(MYPARM) }

You can write all parameters and their values using the $(FME_BRACED_PARM_VAL_LIST) keyword (formerly FME_PARM_VAL_LIST). This is handy if you have a factory whose keywords exactly match all the parameters in your GUI. In this case, the data is written as: 

parm1 { val1 } 
parm2 { val2 } 
...etc...

Similarly, you can get a list of all parameters using the FME_PARM_LIST keyword. This will give a comma-delimited list of all parameter names in the form: parm1, parm2, etc.

The execution instructions are a list of factories that work with each other to process the features coming from the ports specified in INPUT_TAGS and finally output features to the ports specified in OUTPUT_TAGS (there is a default output tag of OUTPUT). Some common factories are TeeFactory (used to route output) and TestFactory(used to route output based upon some test). Functions can be applied on features by using the @Function syntax either upon input (on the INPUT FEATURE_TYPE line) or upon output(on the OUTPUT FEATURE_TYPE line). For example, to output BOUNDING_LINE features after applying the Coordinate(REMOVE, ...) function on them 3 times:

OUTPUT FEATURE_TYPE BOUNDING_LINE
    @Coordinate(REMOVE,4)
    @Coordinate(REMOVE,3)
    @Coordinate(REMOVE,1)

To execute a function from tcl, you will need to use FME_Execute. For example: FME_Execute Geometry GET_CONVEXITY_CLASS

A more involved example that sets a global variable:

Tcl2 proc $(XFORMER_NAME)_setFeatType {} {
    global FME_FeatureType;
    set ft {$(XFORMER_NAME)_};
    append ft [FME_Execute Geometry GET_CONVEXITY_CLASS];
    set FME_FeatureType $ft;
}

Then we can use this function like this: @Tcl2($(XFORMER_NAME)_setFeatType)

To dynamically change the output feature type, you need to modify the tcl global variable FME_FeatureType. You can easily do that using the function @FeatureType. Here is an example from the ConvexityFilter transformer. This transformer routes features to different ports bydepending on what the result of applying @Geometry(GET_CONVEXITY_CLASS) is:

FACTORY_DEF * TeeFactory
   FACTORY_NAME $(XFORMER_NAME)
   $(INPUT_LINES)
   OUTPUT FEATURE_TYPE * @FeatureType(@Concatenate($(XFORMER_NAME)_,@Geometry(GET_CONVEXITY_CLASS)))

Here is a listing of factories/functions available in the most current FME release.

Best Practices

  • If a parameter value can contain spaces, its reference should be in quotes in the mapping file "$(myParam)". String values that contains spaces and are not quoted will have the spaces removed by the parser.
  • Note that any parameter that supports expressions may contain spaces, as the conditional syntax uses space as a delimiter.
  • If writing TCL that access macros directly, ensure that special characters are handled. The FME parser can do strange things. Test with a string like: "PARAN (and spaces)". Alternatively, ensure your parameter is fmeTextEncoded (ie. "valueType": "stringEncoded") and decode the value in the tcl
  • only use the $(XFORMER_NAME) macro if you really need a transformer name. If the user does not see the value, use the FME_UUID macro instead (e.g. for Tcl function names)

Good Luck!