Skip to content

Transformer Best Practices

The following gives a listing of practices to consider as you design and develop your transformer

Parameters

  • Parameters usually should allow both User Parameter and Expression assignment ability to allow data to be input at runtime rather than authoring time. That is have the following specification: "supportedValueTypes": [ "expression", "globalParameter" ]. Exceptions to allowing Expression assignment support is when the backend code can not handle the value changing on a per feature basis or there would be a significant performance hit to do so.
  • When setting the default values for your transformer, set them consistently to what Workbench would normally save. This probably means the default value for some dependent parameters will be . It can mean fmeTextEncoding some values

Factory/Function Code

  • Always handle verification of values in your factory/function code. If the parameter is published, the value is only known at runtime so the backend needs to do the verification
  • If at all possible do NOT look for 'gui-isms' in fmx or C++ code.
    • Do not check for ! Instead check the value of the MACRO(s) that made the parameter unused. If the parent parameter is linked to a user parameter, the GUI can NOT know the value of the choice until runtime. As a result, it will write out ALL the dependent parameters to the mapping file and will not necessarily flag them as because it does not know at mapping file generation time.
    • @Value() - instead of parsing for @Value, pass the attribute value into the tcl function as a parameter (see styler transformers like DGNStyler as examples of how to pass parameters to tcl properly).

Upgrading Transformers

Transformers should be versioned when behavior changes in a nonbackwards compatible way. We add functionality to functions/factories all the time, but we want to make sure old workspaces act exactly as they always have.

Transformers can be upgraded to their latest version in workbench using the 'Update Transformer' menu option. Here are few things transformer writers should do to help users upgrade successfully

  • Briefly describe the changes done to the transformer in 'changeLog' of the new version. Ensure text description is in 'user speak' using user facing terminology
  • If changing parameters or ports, then in the original version of the transformer, you need to specify how to upgrade to the next version. In the original version of the transformer specify:
    • If any of the input or output tags were renamed/removed then specify the old to new name mapping in the 'portMapping' dictionary. This is required so that the links can be maintained after upgrading the transformer
    • If parameters were renamed/removed then specify the old to new name mapping in the parameterMapping dictionary

The following types of changes can be made without making a new version:

  • Adding/renaming ports
  • Adding preserved or added attributes on output ports
  • Adding a new parameter when the default value doesn't change the semantics or behavior of the transformer
  • Removing a parameter (if it no longer makes sense)
  • Changing the default value of a parameter, or a parameter prompt
  • Changing the type of a parameter (as long as ALL existing values are compatible with the new type)
  • Adding a choice to a choice parameter, or changing the display name associated with a given choice
  • Changing the transformer execution template, if the change does not affect the default operation of the transformer
  • Changing the transformer's category or aliases
  • Renaming the transformer
  • Setting the transformer as replaced by a different transformer (using the replacedBy key)

The following types of changes require making a new version:

  • Removing ports
  • Removing preserved or added attributes from output ports (debatable - use judgment)
  • Changing the behavior of the transformer for a given value of a parameter
  • Changing the type of a parameter from not encoded to encoded ("valueType": "stringEncoded")
  • Removing a choice from a choice parameter, or changing the value associated with a given choice
  • Changing the transformer execution template, if the change affects the default operation of the transformer

When creating a new version and changing a parameter, you should consider if the parameter you change is backwards compatible with older presets. In the event that you do not want an older preset to be 'pulled' into this version, you need to rename the parameter. Note to support upgrading, you can map the old parameter to the new parameter name via the parameterMapping dictionary.

Refreshing transformer in Workbench (Debugging fmxj changes)

In order to see changes in your transformer in Workbench, you have to:

  1. delete the transformer from the workspace
  2. refresh the transformer list (there is a refresh button at the bottom of the Transformer Gallery or the Tools->"Reload Transformers" menu option)
  3. undo delete (Ctrl+Z) of transformer.

The delete-undo sequence is one mechanism to pick up the refresh. After the refresh, all new transformer instances added to the canvas will get the updated transformer definition. Existing instances will have the old definition. Closing and reopening a workspace also updates all transformers to the newer definition.