Introduction to FME Packages

Introduction

An FME package is a mechanism used to distribute add-on FME Engine components to the core FME Platform applications, FME Form, and FME Flow. The FME Engine components commonly included in an FME package are transformers, readers / writers, and web connections. Each FME Package is fully portable, containing all of the dependencies needed to execute successfully in FME Form or Flow.

Packages are also maintained and released fully independent from FME Form or Flow. This separation means that fixes and enhancements to FME package performance and functionality can be released as available, rather than waiting on an official FME core product release. In this way, users can take advantage of package improvements frequently, and without needing to upgrade their core FME products to capture each package release. A simple package upgrade will do!

FME Hub hosts all of the FME packages produced by Safe Software and those produced and made available by members of the FME user community. Each FME package hosted on FME Hub has its own information page, where users can download any available version of a package and view the package's minimum FME requirements, system dependencies, and usage notes.

Users are encouraged to visit the FME Hub information page for the FME package they would like to add to their core FME Platform applications before installing the FME package. These package information pages can be readily found using the search functionality and search filters available on the FME Hub homepage.

Just as a .zip file is a compressed archive containing several related files, a .fpkg file is a compressed archive containing all of the files needed for each FME package to function correctly in FME Form and FME Flow. Extracting a downloaded .fpkg file to the system location relevant for the FME product(s) in use effectively installs the package in FME Form or Flow. This action of extracting the downloaded .fpkg file is referred to as "installing" the FME package. 

Installing FME Packages to FME Form

FME packages are installed to FME Form on a per-user and per-build basis. Installing an FME package to one build of FME Form will not result in the package being available for use in all builds of FME Form already present on a user's system. Installing an FME package to one build of FME Form and subsequently installing a newer build of FME Form on the same system and under the same user will result in the FME package(s) installed to the older build being automatically installed to the newer FME Form build.

For example, User A installs FME Form 2024.1.2.1 to their system. This user then installs the SharePoint Online package, and the Emailer package to FME Form 2024.1.2.1 following one of the two install methods described below. Subsequently, User A installs FME Form 2024.2 to their system. When User A opens FME Workbench 2024.2 and accesses Tools --> FME Options --> FME Packages, the two FME packages installed to FME Form 2024.1.2.1 will be listed as installed to FME Form 2024.2.

Now let's change the scenario. Say User A installs FME Form 2024.1.2.1, and then installs the two above-mentioned FME packages to FME Form 2024.1.2.1. User A then logs out of the machine. Next, User B logs into the same machine and installs FME Form 2024.2. When User B starts up FME Workbench 2024.2 and then accesses Tools --> FME Options --> FME Packages, the packages installed to User A's FME Form 2024.1.2.1 will not be automatically installed to User B's FME Form 2024.2. FME package installs are tied to both FME Form build and the logged-in user who installed the package.

FME Package Installation Methods for FME Form

There are two primary ways to install an FME package to a build of FME Form. Method 1 uses the FME Workbench quick-add functionality, while Method 2 involves downloading the package from FME Hub and opening the downloaded .fpkg file in FME Workbench. Regardless of the install method chosen, users must ensure that an internet connection that allows access to FME Hub is available and that the ability to extract Python files on the client machine is allowable. 

Before choosing an install method, it's important to note that Method 1 of installing an FME package to a target build of FME Form will, when successful, always result in the installation of the newest version of the package available for the target FME Form build. Users can consult the FME Hub information page for the package they wish to install, to get details on the newest available package version. If the newest available package version is not desirable, users should follow Method 2 below to install their target FME package version. 

Method 1: Quick-add in FME Workbench

First, users might want to consider ensuring that the Translation Log window is visible in FME Workbench (docked or undocked) to view the messages that appear during an FME package install. These messages can be helpful if a package install is unsuccessful or as confirmation that the package was successfully installed.

To install an FME package directly from FME Workbench, use Quick Add to add the package's canvas object to a workspace. 

FME package canvas objects will appear in the left-side pane of the Quick Add dialog, denoted by the typical icon indicating its object type (reader, writer, or transformer). In addition, a second icon will appear, showing a downward-pointing arrow to indicate that the canvas object is FME Hub-hosted downloadable content.  When users highlight the canvas object, the right-side pane of the Quick Add dialog will display its key information, including an indication that the canvas object derives from a package.

Double-click on the package entry that appears in the left-side pane of the Quick Add dialog. If the package is not yet installed, users will see the following Install Prompt appear:

Once users select Install on this prompt, FME will begin installing the package, and the following installation progress bar will appear:

Once the package has successfully installed, users will see the package's canvas object appear in the workspace, and the following messaging will appear in the Translation Log window:

The Translation Log messaging lists the key package components that were installed, including any transformers, web services, web file systems, or Python packages. Notice the file path shown in the final Translation Log message; this file path shows the default install location for an FME package's Python components. Backing this file path up two levels will arrive at the default install home for all FME packages:

Windows OS

C:\Users\<UserName>\AppData\Roaming\Safe Software\FME\Packages\<FME_BUILD_NUMBER>

MacOS

/Users/<Username>/Library/Caches/Safe Software/FME/Packages/<FME_BUILD_NUMBER>

Linux

$HOME/.Safe Software/FME/Packages/<fme-version>-linux-x64/

If users choose to install the package via quick-add in FME Workbench, a stable internet connection will be required on the machine running FME Workbench. Further, the machine will need to establish a connection to FME Hub to download the target FME package. Users who operate behind a firewall or proxy or make use of antivirus software should consider making or requesting relevant policy adjustments to these network components such that a connection to FME Hub can be established and the downloaded package can be fully unpacked and installed without file quarantine. Please see our URLs Used by FME article and our FME and Antivirus Software article for guidance on the above.

Method 2: Download the FME Package File from FME Hub

Users may also access the FME Hub information page for a target FME package, and download a specific package version directly from this page. When users download an FME package from FME Hub, they receive a .fpkg file. The downloaded .fpkg file is a ZIP archive with the following naming convention:

[package publisher].[package name]-[package version].fpkg.

Once the .fpkg file finishes downloading, users can choose one of the following options to install the downloaded .fpkg file to a target build of FME Form:

• Right-click on the downloaded .fpkg file, choose Open With, and then choose the version and build of FME Workbench they wish to install the FME package to; 
• Open the target version of FME Workbench, and drag and drop the downloaded .fpkg file onto the canvas

The right-click option will not initiate FME Workbench, and will not provide any messaging or confirmation that the package install was successful. Users will only see an install prompt, followed by an install progress bar. The progress bar will disappear once the installation has finished. 

The drag-and-drop option will result in the same install prompts and messaging shown with Method 1, above.

Verify the FME Package Install for FME Form 

Once users receive an indication that the FME package of interest has been installed to the target build of FME Form, users can navigate to the following system location to verify the package install and see the contents of the package's .fpkg file:

C:\Users\<UserName>\AppData\Roaming\Safe Software\FME\Packages\<FME_Form_Build_Number>

FME Form relies on the installed package's contents being named and located in this default install location. It is, therefore, recommended that users avoid renaming, moving, deleting, or otherwise adjusting any of the files or folders associated with an installed FME package. 

Installing FME Packages to FME Flow

Users can readily install an FME package to their FME Flow environment by publishing a workspace that contains the package's canvas object from FME Form. Publishing a workspace from the FME Form will initiate the Publish to FME Flow wizard, where users will be presented with an option to publish any packages upon which the workspace depends and which have not already been published to the target FME Flow environment.

Once an FME package is published to FME Flow, its .fpkg file will, by default reside in the following location:

• FME Flow Web UI --> Resources --> Engine
  • local machine filepath:   <systemshare>\resources\engine

It's important to note that a package is not installed by default upon publishing to FME Flow. The published FME package's .fpkg file still needs to be fully extracted, to install the package's components to FME Flow. This package file extraction occurs when a job or workspace involving the package's canvas object is successfully run in FME Flow. To complete the package install for FME Flow, users should run a workspace or automation that makes use of the package's canvas object.

Once an FME package's .fpkg file is fully extracted to FME Flow, users will notice that several new files and folders appear in the following FME Flow System Share locations on the machine running Flow:

• <systemshare>\resources\engine\packages\<build>\PackageFiles\<PackageName>
• <systemshare>\resources\engine\Packages\<build>\Python\<PackageName>
• <systemshare>\resources\engine\Packages\<build>\Resources\<PackageName>
• <systemshare>\resources\engine\Packages\<build>\transformers\<PackageName>
• <systemshare>\resources\engine\Packages\<build>\webfilesystems\<PackageName>

In the FME Flow Web UI, users will see new files and folders appear in the following location:

• Resources --> Engine --> Packages --> <Flow_Build>

The PackageFiles, python, resources, transformers, and webfilesystems folders pictured above will contain the various extracted components for each package installed to FME Flow.

Users should not rename, move, or delete, or otherwise tamper with any of the extracted package files or folders. The correct functionality of the package's canvas object depends on the package files residing in their expected location, as-is. 

Updating an FME Package

FME packages are maintained separate from the core FME Platform applications, meaning new version releases of FME packages will not necessarily coincide with new version releases of FME Form or Flow. FME packages are released as improvements to package components are available. Users should periodically visit the FME Hub information page for their installed packages to see if a newer package version is available for their FME Form and Flow products. If a new version is available, users can read about the key improvements made to the package by accessing the History tab on the package's FME Hub information page.

Updating an FME Package in FME Form

Users can check for package updates by opening FME Workbench, and then accessing:

Tools --> FME Options --> FME Packages

Each package listed in the right-side pane of the FME Packages menu may appear with (Update Available) next to the package's name. Users can also select Check for Updates, just below the list of installed packages, to refresh this list of packages with available updates.

Where a package update is available, users can simply highlight the package's name and then select Update near the bottom right of the FME Packages menu. This will update the installed package to the newest available package version, as listed on the package's FME Hub information page. If users are not sure what the newest available package contains, they should first check the package's FME Hub information page for details on the newest available package version. 

Users who do not have open internet access may not see when package updates are available in FME Options --> FME Packages and, therefore, may not be able to update their FME packages from the FME Packages menu. In this scenario, it's important to keep track of package version releases by regularly checking the package's FME Hub information page.

When users do see a new package version available on FME Hub, they can upgrade to this new version by following these steps:

1. Open FME Workbench and access Tools --> FME Options --> FME Packages
2. Highlight the package to upgrade in the list of FME Packages shown, and select Remove at bottom-right
3. Once the package is removed from the build of FME Form in use, follow FME Form package install Method 2 as described above.

Updating an FME Package in FME Flow

FME Flow does not have a method for checking for available package updates. However, if users keep installed package versions the same between their FME Form and FME Flow products, they can first check for package updates in FME Form as described above. Then, they can perform package updates for FME Form, followed by package updates for FME Flow as described below.

FME package updates for FME Flow involve the following key steps:

1. Fully uninstalling the package from the build of FME Flow in use; please see the instructions provided in the Uninstalling an FME Package from FME Flow section, below
2. Publishing the updated package version from FME Form to FME Flow
3. Extracting the newly published package in FME Flow

After fully uninstalling the FME package targeted for update from FME Flow, users will need to republish the newer package version they wish to upgrade to, from FME Workbench. This means that the package version targeted for upgrade on FME Flow should first be installed in FME Form. Then, users can simply add and configure the upgraded package's canvas object to a blank canvas in FME Workbench, test the canvas object to verify its correct functionality, and then publish this simple workspace to FME Flow. The Publish to FME Flow wizard will prompt users to publish the package; users should ensure that they choose to publish the package when prompted.

Once the workspace and package have been successfully published from FME Form to FME Flow, users must complete the FME Flow package upgrade by running a workspace or automation in FME Flow, which uses the upgraded package's canvas object. This final action will fully extract the published package, completing the package upgrade for FME Flow.

If users are not prompted to publish the package targeted for an upgrade, then they should cancel publishing and verify that the package has been fully uninstalled from FME Flow. Review Uninstalling an FME Package from FME Flow, below. 

Uninstalling an FME Package

Occasionally, users may wish to completely uninstall an FME package from their FME Platform applications. This uninstall might be necessary to troubleshoot errors encountered with an FME package, or to simply remove packages that are no longer needed. 

Uninstalling an FME Package from FME Form

FME packages can be fully uninstalled from a build of FME Form by first opening that build's FME Workbench. Next, navigate to Tools --> FME Options --> FME Packages, and select the package to uninstall from the listed package shown. Finally, select Remove at the bottom-right of the FME Packages menu to uninstall the package. 

Uninstalling an FME Package from FME Flow

Uninstalling an FME package from FME Flow requires careful attention to the steps described below; if components of an older package are left behind, upgraded packages may not function as expected in the FME Flow environment.

To fully uninstall a published, extracted FME package from FME Flow, users must first log in to the FME Flow Web UI under the Flow Admin or Superuser role. These roles contain the permissions needed to remove files and folders associated with FME packages.

Once logged in, use the left-side panel and navigate to the following FME Flow Web UI location:

Resources > Engine > Packages > [Flow_Build]

In this location, users will see several subfolders. The subfolders containing extracted FME package components include the following:

• PackageFiles
• Python
• resources
• transformers
• webfilesystems

Users should access each of the above-listed subfolders, and remove the target package's folder therein using the Actions drop-down.

Once the target package's extracted components have been removed, users should navigate to Resources > Engine and remove the target package's .fpkg file using the Actions drop-down menu.

While removing the target package's .fpkg file, users will see the following warning appear:

Select OK to acknowledge the warning and remove the .fpkg file. This final .fpkg removal will complete the full uninstall of a published, extracted FME package from FME Flow.

If the FME package to be removed from FME Flow was published, but not extracted, users should log into the FME Flow web UI as an Admin or Superuser, and navigate to the following location:

Resources > Engine

Select the .fpkg file for the FME package targeted for removal, and then select Remove from the Actions drop-down menu. This action will remove the published, unextracted FME package from FME Flow.

Additional Resources

Users are encouraged to consult the following documentation for more detailed information on FME packages and FME Hub.

FME Package Troubleshooting Guides:

FME Flow Troubleshooting: Packages

FME Form Troubleshooting: Packages

Building an FME Package with the FME Packages SDK

FME Packages SDK Guide - Introduction

Information About FME Hub

FME Hub FAQ

Publishing Items to FME Hub