Introduction
Custom transformers let FME authors package a piece of workspace logic into a reusable, shareable component. Like any packaged logic, custom transformers evolve over time: bugs get fixed, parameters get added, and behavior gets refined. This article walks through how to upgrade a custom transformer safely, covering linked transformers, embedded transformers, deprecated transformers, and workspaces published to FME Flow.
Types of Custom Transformers:
-
Embedded:
- Stores its definition directly inside the workspace that created it.
- Can't be shared or reused in other workspaces
- Manually upgraded, no built-in check for updates
- Shown in light green on the canvas
-
Linked:
- Stores its definition in a separate .fmx file
- Any workspace referencing it points back to that single definition
- Any change to the definition can be picked up by every workspace linking to it
- Can easily be shared or reused
- FME can detect when a newer version exists
- Shown in dark green on the canvas
See Embedding or Linking a Custom Transformer for more information.
Step-by-Step Instructions
The steps below are grouped into four parts, depending on what's being upgraded: a linked transformer in FME Workbench, an embedded transformer, a deprecated transformer, or a transformer deployed to FME Flow. Work through the part that matches the situation.
Part 1: Upgrade a Linked Custom Transformer in FME Workbench
The transformer version is independent of the FME version. Just because FME has been upgraded to a new version doesn’t mean that the transformer has been updated. There is also no automatic upgrade for transformers; the workspace author controls when to upgrade their transformer.
1. Open the Workspace in FME Workbench
Open the workspace that contains the linked custom transformer in FME Workbench. FME should automatically check for any transformer updates. However, you can refresh the Transformer Gallery at any time, which will rescan available custom transformer definitions.
Note: To refresh the Transformer Gallery, ensure it is open: View > Windows > Transformer Gallery. Then click on the arrow circle in the bottom left corner.
2. Locate the Upgradeable Transformer
If a transformer has an upgrade, it will appear under Upgradable Transformers in the Navigator. Both built-in and custom transformers will appear here.
3. View History
Before upgrading a transformer, it is recommended to view the change log. In the Navigator, right-click the transformer name, then click Show Changes to view its version history and change details before deciding whether to upgrade.
4. Start the Upgrade
Right-click the transformer instance and click Upgrade <Name of Transformer> Transformer to open the Upgrading Transformer dialog.
You will be prompted to create a backup of your workspace during the upgrade process. It is highly recommended that the workspace be backed up, so it is enabled by default.
One final step before the upgrade is complete is to review the parameters side by side for the current and new version. Before clicking OK, confirm that the parameters look ok.
Click OK to apply the change. The transformer instance now reflects the newer version's parameters and behavior. If the current FME release doesn't support the newer definition, the upgrade option won't appear at all. In that case, an FME upgrade is needed first.
Anyone maintaining the .fmx definition itself (not just an instance of it) will be prompted, on save, to choose between overwriting the existing version or creating a new version. Creating a new version doesn't create a separate file; it adds another version inside the same .fmx file, so users on older FME builds who can't use the new behavior can keep using the prior version, while others can upgrade.
Part 2: Upgrade an Embedded Custom Transformer
Embedded transformers are trickier to upgrade because there's no external definition file for FME to compare against, so they require a manual review.
Option 1: Edit the Embedded Definition Directly
Open the workspace with the embedded transformer in FME Workbench. Then, next to the Start and Main tabs, a tab will appear for any embedded custom transformers. Click on the transformer tab.
Next, upgrade the transformers as described in the Linked section. However, this time it will be individual transformers being upgraded, either built-in or linked. Some custom transformers may have additional custom transformers nested, which may also need to be upgraded.
For more information on upgrading transformers, see the documentation.
When upgrading custom transformers or built-in transformers, it is highly recommended to make a backup copy of your workspace prior to upgrading.
Option 2: Convert the Transformer to Linked, Then Upgrade
When a transformer is embedded, even if it has a maintained .fmx file, if it is not stored in the correct location, FME cannot find it. To convert the embedded transformer to linked, the .fmx must be stored in the following location:
- Windows:
C:\Users\<user>\Documents\FME\Transformers - Linux:
~/.fme/Transformers - OSX:
~/Library/Application Support/FME/Transformers
After moving the .fmx to the location above, in FME, click on the Reload Transformers button in the Transformer Gallery (View > Windows > Transformer Gallery). Once the transformers are reloaded, the embedded transformer will now appear in the Transformer Gallery as linked; however, the transformer(s) on the canvas still need to be updated.
Right-click on the embedded custom transformer and select Reload Latest Version. The embedded transformer will now be updated to the same version as the .fmx file; however, it is not yet linked. The update can be stopped here if linking is not desired.
To complete linking the embedded transformer. Right-click on it once more, and Link is now an option; click on Link.
If there is more than one instance of the embedded transformer on the canvas, a dialog will appear about linking all instances.
After clicking Yes or No for the multiple instances, the transformer will now be linked and appear as a dark green transformer with the link icon.
The linked transformer can then be upgraded as needed as detailed in the Linked section above. To re-embed the transformer, right-click on it and click Embed.
Option 3: Manually Recreate the Instance
Alternatively, remove all instances of the outdated embedded transformer from the workspace and re-add the current version fresh from the Transformer Gallery. Simply replacing instances one at a time won't work as FME retains the old embedded definition in the workspace until every instance referencing it has been removed. After removing the final instance, a dialog will appear asking to delete the embedded definition, click Yes.
With the embedded definition now removed, the custom transformer .fmx can be installed or downloaded from FME Hub.
This method will require all of the transformer connections and parameters to be reset.
Part 3: Manage a Deprecated Custom Transformer
If a custom transformer has been marked deprecated, it is recommended to keep it as embedded, not linked. A deprecated linked transformer will still attempt to contact FME Hub and pull the newest published version, which can create version conflicts with the deprecated copy that's intentionally being preserved. It is also advised to keep a separate .fmx backup of the custom transformer to truly preserve the deprecated item.
Part 4: Deploy and Upgrade a Custom Transformer on FME Flow
Workspaces published to FME Flow may depend on custom transformers that also need to exist on the server. Embedded transformers travel inside the workspace, so publishing the workspace with the updated transformer is all that's required. Linked transformers need their .fmx definition made available separately.
Embedded Custom Transformers
Publish the workspace to FME Flow as usual. No separate transformer upload is needed, since the definition travels inside the workspace.
Linked Custom Transformers
Option 1: Upload the Linked Transformer to Shared Resources
For a linked transformer, go to Resources > Engine > Transformers in the FME Flow web interface and upload the .fmx file. This makes the transformer available to every workspace on that FME Flow instance, across all repositories.
If the .fmx definition already exists on FME Flow, but there is an update. As long as the file name is exactly the same, FME will overwrite it upon upload so the workspaces can access the update.
Note: Uploading a newer .fmx file to Resources on FME Flow updates the definition available to the server, but it does not retroactively upgrade the transformer instances inside workspaces that are already published there. Open the workspace back in FME Workbench, upgrade the transformer there using Part 1, and republish the workspace to FME Flow.
Option 2: Publish the Linked Transformer from FME Workbench
As an alternative to Linked Option 1, open the .fmx file in FME Workbench and use File > Publish to FME Flow. This makes the transformer available to workspaces in the specific repository it's published to, rather than server-wide.
This method also requires the transformer to be upgraded in the workspace, then republished.
Option 3: Publish the Transformer Alongside a Workspace
As a third option, when publishing a workspace that uses a linked transformer, upload the transformer's resources at the same time — either into the same repository (available only there) or into the shared resource folder (available everywhere).
If a linked transformer of the same name exists in both a repository and the shared resource folder, FME Flow checks the shared resource location (FME_SHARED_RESOURCE_DIR) first, and only falls back to the repository-level copy if it doesn't find one there.
Troubleshooting
The Upgrade Transformer option doesn't appear. This usually means the current FME release doesn't support the newer transformer definition. Upgrade FME Form to a release compatible with the newer definition, then try again.
A workspace on FME Flow isn't using the expected transformer version. Check whether a linked transformer of the same name exists in both a repository and the shared resource folder — FME Flow checks the shared resource location first. Confirm which copy is being picked up, or remove the outdated copy from whichever location shouldn't take precedence.