Getting Started with Deployment Parameters

Introduction

In an organization where multiple users are involved in building, testing, and deploying FME workflows across various environments, manual transfer of workflows can be a time-consuming and error-prone process. To address this challenge, FME Flow offers the Deployment Parameter Store—a centralized location for establishing standardized workflow configuration settings Deployment Parameters can be created for database connections, web connections, and text-based values.

By using Deployment Parameters in FME Flow workflows, users no longer need to manage individually managed connections or hard-coded values between environments. These often represent the most unreliable points in a workflow, introducing risk and instability during a migration. Instead, workflows dynamically retrieve the appropriate configuration values from the Deployment Parameter Store. Users can trust deployment parameters to produce consistent, scalable, and reliable results in any environment. 

Deployment Parameters simplify connection management, enhance collaboration, and streamline the workflow development and deployment cycles within your organization. The result is simplified workflow management and seamless data integration. Review the FAQ for a quick overview, or follow the tutorial to dive into an example workflow for using deployment parameters in your own FME environment. 
 

Deployment Parameters FAQ

What kind of values can be used as deployment parameters?

• Web and database connections 
• Text-based values like usernames, table names, API keys, or file paths

Where can I use deployment parameters?
Deployment parameters are created and managed from the Deployment Parameter Store on FME Flow. Once configured, deployment parameters can be referenced from both FME Form and FME Flow workflows. 

Who can use deployment parameters?
Any FME users or clients they’re shared with. 

Why should I use deployment parameters?

• Improved maintenance. The Deployment Parameter Store provides a centralized management hub. Rather than per user, configurations  can  be managed at the team or project level—defined once,  used by everyone.
• Fewer mistakes.  Deployment parameters offer a robust solution for running workflows in different environments. Instead of relying on the user to update workflows between migrations, deployment parameters ensure that configurations are standardized. Additionally, restricting access to the deployment parameters themselves ensure that items will not be overwritten or deleted accidentally.   
• More secure. Separating configurations from the workflow allows for better control over ownership and access. Allow users to design and deploy production-ready workflows, while still restricting access to the production environment.  
• More reliable. Enhance collaboration by standardizing configurations so that multiple users and teams can trust that results will be accurate and consistent, no matter where the workspace is built or run from. 

Requirements

• FME Form 2023.0+
• (2) FME Flow 2023.0+, e.g. staging and production
• PostgreSQL database, or a similar. 
• pgAdmin (optional) 
• An email account (optional) 

NOTE: This tutorial assumes users have access to multiple FME Flow environments (e.g. staging and production) in order to complete a migration example in full. However, some sections may be followed to demonstrate using deployment parameters in a single FME Flow environment. Simply omit the steps that are repeated for the second environment. 

Step-by-Step Instructions

In this scenario, we explore using deployment parameters for a workflow migration. You’re a technician responsible for building a workflow that updates an employee database. There are two different FME Flow environments used in this process: staging and production. 

The workflow is first developed in a staging FME Flow. In this environment, the results are always written to a testing database. When that workflow is ready to deploy, it is migrated to a production FME Flow. In this environment, the results are sent to a live database that is used by the public. Therefore, it is critical that the workspace’s database connection parameters are always changed from testing to production.

But manually updating the individual workspace parameters before deployment invites the risk of unpredictable results and error. Instead, you’ll leverage the FME Flow Deployment Parameter Store to configure the database connections required for each environment. With deployment parameters, the workflow is easily migrated from staging to production without manual intervention. You can trust that the appropriate workflow requirements for that environment will be automatically picked up and applied at runtime. 

This multi-part example demonstrates the creating, managing, authoring and sharing of deployment parameters throughout an FME workflow migration.
 

Part 1: Creating Deployment Parameters in FME Flow

The process for creating and managing deployment parameters occurs on both FME Form and Flow. The FME Flow Deployment Parameter Store is the centralized configuration hub for configuring, managing, and sharing deployment parameters. However, FME Form is where we can create and publish the underlying web and database connections that can then be used as deployment parameters. 

Our start-to-end workflow requires two different database connections: staging and production. This section creates the PostgreSQL database connection in FME Form and publishes it to FME Flow. Lastly, we’ll create a deployment parameter from the database connections on FME Flow. 

1. Create the Database Connection in FME Form
A deployment parameter can only be created for a web or database connection if it already has been published to FME Flow. The process of uploading/creating a connection on FME Flow slightly differs between the two types: 

For most users, it’s easiest to create the connection in FME Form and upload it to FME Flow alongside a workspace. That’s what we will do in the following steps. 

From PgAdmin 4, create two PostgreSQL databases: Staging and Production

Postgres ‘Staging’ and ‘Production’ databases pictured in PgAdmin 4

Open DatabaseConfiguration.fmwt in FME Workbench. This workspace will allow us to establish the PostgreSQL database connections and create the employee data.

The DatabaseConfiguration.fmwt canvas

From FME Form's main menu, navigate to Tools > FME Options > Database Connections. Use the “+” button and select PostgreSQL as the connection type. Name the connection “Staging Employee Database” and fill out the connection parameters for your own PostgreSQL “Staging” database. 

The Database Connection settings in FME Options. Your connection information may differ.

Once the database connection is created, repeat the steps to create a “Production Employee Database” connection. Exit the FME Options window and review two valid database connections in the Navigator. 


Run the workspace to write the SQLite tables to your PostgreSQL databases. This step tests the connections and creates the example data for the remainder of the exercise.

A successful translation log and the database tables as viewed in pgAdmin 4. 

2. Establish an FME Flow Connection
To upload a database connection to FME Flow, we must publish it with a workspace. 

From the FME Form ribbon menu, find the FME Flow Connection*. Select “Connect to FME Flow…”. Create a connection to your “Staging FME Flow”. A green icon reflects a successful connection. 

Repeat the steps to create a connection to your “Production FME Flow”. When complete, the two FME Flow environments are available as connections. 



*The FME Flow Connection item on the ribbon menu is new for FME 2023.0. It may not be visible if you have customized this ribbon in previous FME installations. Click the >> button at the end of the ribbon to expose additional options, or right-click on the ribbon and select Customize Toolbar. Expand File then click and drag the FME Flow Connection option to the desired position in the ribbon. Click Apply, then OK to close. 

3. Publish the Database Connection to FME Flow
While connected to the “Staging FME Flow”, select Publish to open the publishing wizard. Create a new repository named “DeploymentParameters”. 


In the Upload Connections dialog, select only the “Staging Employee Database” database connection. 


Recall, in this organization, staging workflows are not meant to write data to the production database. Therefore, we do not have any reason to upload the “Production Employee Database” connection to our “Staging FME Flow”. 

Click through the remaining default settings to publish the workspace.

Now, toggle the FME Flow Connection to “Production FME Flow”. Repeat the steps in the publishing wizard to upload only the “Production Employee Database” database connection. 


4. Create a Deployment Parameter from a Database Connection
In FME Workbench, ensure you are connected to your Staging FME Flow Connection.


From the Navigator Window, right-click on Deployment Parameters and select ‘Create Deployment Parameter’. 


Configure the new Deployment Parameter as follows:

Upon clicking OK, the Database Connection will be uploaded to your FME Flow instance, if it doesn’t already exist, and the Deployment Parameter is created. 
 
5. Create a Deployment Parameter from a Text Value 
In addition to web and database connections, text values can be made into deployment parameters. This lends itself to many different workflow possibilities, like usernames, API keys, file paths, URLs, storage buckets, email addresses, and scripting values, among many others. Conveniently, text-based deployment parameters can be created directly from the Deployment Parameter Store. 

In our example, our PostgreSQL staging and production databases have different table names for storing employee data. From the Navigator Window, right-click on Deployment Parameters and select "Create Deployment Parmeter" again to create a deployment parameter for our database table names. 

Select OK. 

Our Staging FME Flow now has two deployment parameters: "EmployeeDatabase" and "EmployeeTable". To see the Deployment Parameters that you just created, go to your FME Flow instance in a web browser. Expand the Connections & Parameters section and then go to Deployment Parameters.
Here you should see the two Deployment parameters you created.


6. Configure Deployment Parameters in the Production Environment
Deployment parameters must be specifically configured for each FME Flow environment they will be used in. Therefore, we must recreate EmployeeDatabase and EmployeeTable in the Production FME Flow. However, this time, their values will reflect the production workflow requirements. 

From a browser, navigate to your Production FME Flow. In the “Database Connections” page, ensure that the “Production Employee Database” was successfully uploaded. 


From the Production FME Flow’s Deployment Parameter Store, repeat Step 4 to create the “EmployeeDatabase” deployment parameter. This time, using the “Production Employee Database” database connection. 

Next, repeat Step 5 to recreate the “EmployeeTable” deployment parameter. This time, the table name is “Employees”. 

The Production FME Flow Deployment Parameter Store now has “EmployeeDatabase” and “EmployeeTable”.

The Staging FME Flow and the Production FME Flow now each share two deployment parameters with the same name: “EmployeeDatabase” and “EmployeeTable”. However, the values for each of those deployment parameters differ. This allows workflows that reference these deployment parameters to pick up the right values for the environment automatically.

NOTE: Additional steps are required to share deployment parameters with other FME users and roles. See Part 5 for more information about permissions. 

Part 2: Authoring Workspaces with Deployment Parameters

Once deployment parameters are configured on FME Flow, they may be used to author and run workspaces in FME Form. Users still must maintain a local connection, using the same name, to successfully run the translation. However, this simplifies the process of uploading to FME Flow and subsequent migration. 

Although this tutorial example has an emphasis on workflow migration, the benefits of configuration management are not limited to multiple FME Flow environments. FME administrators can leverage the Deployment Parameter Store to standardize and manage parameters and connections with a single FME Flow environment. 
The following section uses deployment parameters for workspace authoring in FME Form. 

1. Synchronize Deployment Parameters in FME Form
In FME Form, open EmployeeDatabaseWorkflow.fmw. The first bookmark represents the main objective of the workspace: writing an update to the employee table. In the second bookmark, the table contents is written to an HTML page.


Workspaces can be synchronized with the Deployment Parameter Store at any time.
Toggle the FME Flow Connection to the “Staging FME Flow”. From the drop-down menu, select Sync to retrieve any new or updated deployment parameters. This step is especially important if your workspace is open in FME Form while changes are being applied to the Deployment Parameter Store in FME Flow. 


In the Translation Log window, you might spot a new message: “Retrieved 2 deployment parameters from the FME Flow Connection ‘Staging FME Flow’”


The workspace FeatureReader and FeatureWriter currently connect to PostgreSQL using standard database connections, listed as the “Staging Employee Database” database connection in the Navigator. Above it, notice an empty Deployment Parameters section. This section will remain empty until we use deployment parameters in the workspace. 


2. Use a Deployment Parameter in a Transformer
Similar to attribute values and user parameters, deployment parameters can be used as parameter values in transformers, readers, and writers. 
From the canvas, open the FeatureWriter. The PostgreSQL Connection parameter is currently using the standard “Staging Database Database” database connection. 


By default, a standard database connection references a locally stored configuration (as we created in Part 1.1). But if the workspace was published to an FME Flow where the connection was not also uploaded or maintained, it would fail to find that configuration.

Deployment parameters are more robust because they allow workspaces to reference the same parameter in FME Form and FME Flow environments. In each environment, the underlying values must still be configured and maintained. But it allows the user to move that workspace between environments and trust that the appropriate parameter values will be referenced.  

From the dropdown menu next to Connection, select User Parameters > FME Deployment Parameters > EmployeeDatabase. 

Deployment parameters are distinguished by a green cogwheel icon. 

In this example, our database table names differ in each environment. We can account for that with our text deployment parameter, "EmployeeTable". In Parameters > Table Name, use the drop-down menu to select User Parameters > FME Deployment Parameters > EmployeeTable. 

The FeatureWriter should now employ our two deployment parameters. 

FeatureWriter configured with deployment parameters

Select OK to return to the canvas. 

Next, open the FeatureReader. Repeat the steps to replace the standard “Staging Employee Database” connection with “EmployeeDatabase”. Use the drop-down menu next to Connection, and select User Parameters > FME Deployment Parameters > EmployeeDatabase. 

Apply the EmployeeTable deployment parameter as a value for Constaints > Feature Types to Read. This completes the configuration.  

FeatureReader configured with deployment parameters


Lastly, this workflow produces HTML so that we can quickly confirm the workflow results. Open the HTMLReportGenerator to review. In the Page Contents, there are two Headers with the values: 

HTMLReportGenerator Headers

The final HTML will report the runtime values: the fme_dataset value will write the database name and the fme_feature_type will write the table name. Should our deployment parameters have been configured correctly, these values will be different when running the workspace on testing or production environments.  

Close the HTMLReportGenerator. 

In the Navigator, notice the Deployment Parameters section has now been populated with their Staging FME Flow values. 


3. Run an FME Form Workflow with Deployment Parameters
Workflows can be run in FME Form using deployment parameters. 
Select Run from the ribbon menu. You’ll be prompted to enter four user parameters. Example data for an update: 

Once the translation is complete, select the folder icon to locate the HTML file. 


Open the DatabaseVisual.html file in a browser.  

In the report, you should see the values for the “Staging” database and “EmployeesTesting” table at the top of the page. Below it, a new or updated employee record should be found in the table. 


Feel free to also use pgAdmin to view the results in PostgreSQL. Query the EmployeesTesting table.


NOTE: deployment parameters allow users to test their workflows for different environments from FME Form. For example, if you toggled your FME Flow Connection to “Production FME Flow”, the workspace would reference that environment’s deployment parameter values instead. 


Staging FME Flow deployment parameter values


Production FME Flow deployment parameter values

5. Upload the Workspace to FME Flow
In FME Form, select the Publish button to open the wizard. Toggle the FME Flow Connection back to “Staging FME Flow”. Upload EmployeeDatabaseWorkflow.fmw file to the “DeploymentParameters” repository. 


In the Register Services options, check the box next to Data Streaming. This web service simply allows the workspace to deliver the HTML directly in the browser when we test the workspace. 


5. Run an FME Flow Workflow with Deployment Parameters
Navigate to the Staging FME Flow in a browser. Open the Run Workspace page and configure the parameters: 
 

Published Parameters:

Select Run.

An HTML page will be returned in the browser. Because we’re running the workspace from the Staging FME Flow, our deployment parameters have automatically applied the appropriate database and table information. A successful update will display that employee “555555” has been updated to “Inactive”. 

 

Part 3: Workflow Migration Using Projects

This section will use an FME Flow Project to migrate the EmployeeDatabaseUpdates.fmw workflow from the staging to the production environments. Projects are a simple way to package an FME Flow workflow so it can be shared with other users or between environments. 

However, another option would be to publish the workspace to the production environment directly from FME Form. To do this, you’d simply toggle the FME Flow connection to the “Production FME Flow” and complete the steps to publish the workspace. Some FME authors may prefer this manual migration while developing individual workflows, but projects are a more convenient solution for automated deployments or workflows with FME Flow dependencies (like Automations or Flow Apps). 

1. Create and Export an FME Flow Workflow using Projects
We will now create a project to migrate the EmployeeDatabaseWorkflow.fmw workspace from the Staging FME Flow to the Production FME Flow. 
Navigate to the Staging FME Flow in a browser. From the sidebar, open Projects > Create Project. Configure the parameters to describe the employee update workflow. 
 

In Project Contents, select Add Items to open the dialog. 

While scrolling the Item Type list, note the variety of items. These options represent items that can be shared or migrated with a project. Sensitive data, like passwords and connections, can be omitted before export. 

For our example, choose Workspace. Select “DeploymentParameters” as the repository and the “+” button next to the EmployeeDatabaseUpdates.fmw workspace. 

The Selected Items panel populates with the workspace name. Expanding the item allows us to review its dependencies, i.e. the additional items must be included in order for the workflow to run successfully in another environment. However, even though deployment parameters are listed, their values are not migrated with projects. Their values are specific to an FME Flow environment and can not be overwritten or migrated with a project. 


Select Add Items to return to the project page. The Project Contents now lists the workspace. 


Save the project. From the overview, select Actions > Export. 


Review the project export options for reference, but leave all settings as default. We’ll choose to export the project to our desktop, rather than storing it in the FME Flow Resources. 


Select Export and select a location on your local desktop to download the project file (*.fsproject) to.

2. Import an FME Flow Workflow Using Projects
Navigate to the Production FME Flow in a browser. From the sidebar menu, select Projects > Manage Projects > Import. 


With File Location set to Upload, drop the fsproject file from your desktop. 


Leave the rest of the Additional Options as default and select Import.  


3. Run a Workflow in a Different FME Flow Environment
The project has imported the DeploymentParameters repository and its contents into the Production FME Flow.
From the Run Workspace page, select the repository and workspace. For the Published Parameters, enter any sample data, e.g. 
Published Parameters 

Select Run. If our migration was successful, the workspace will return a familiar HTML page. This time, with the production environment details listed and a new row for the most recently added employee. 


The workflow returns the contents of the PostgreSQL ‘Production’ database’s ‘Employees’ table when run from the Production FME Flow 

This result confirms a successful workflow migration using FME Flow Deployment Parameters with Projects. 

In this workflow, we relied on the Deployment Parameter Store to tailor configurations and parameters for each environment. This framework allows multiple users to seamlessly collaborate, develop, and deploy workflows between environments without the need for manual intervention. Projects further simplified the migration process so that the entire workflow and its dependencies could be packaged and imported with just a few clicks. 
 

Part 4: Authoring Automations with Deployment Parameters

Deployment parameters can be used to pass values within an FME Flow Automation, just as attributes are passed in a workspace. This is a convenient strategy for storing values that are frequently used in automated workflows. The Deployment Parameter Store also allows us to easily update all of our automation’s parameters from one place, no matter which user owns them. 

The final example builds an FME Flow Automation that sends an employee spreadsheet to the HR inbox on a monthly basis. But email connections represent the kind of values that are subject to frequent change or restricted use. It is often more convenient to centrally manage these types of connections so that they can be shared with other users with reliable results. 

The scenario calls for two additional deployment parameters to be created. These steps require access to an email server, (e.g. Gmail or Outlook) to be completed. The instructions also assume you’re now familiar with the process of creating deployment parameters, but use Part 1, Part 2, and Part 3 as a reference when needed. 

1. Create an Email Web Connection in FME Form
Open EmployeeQuery.fmw in FME Form. In summary, this workspace reads the PostgreSQL "Production" database’s “Employees” table, summarizes the data, writes an Excel sheet, and sends it in an email. The final destination is an HR email inbox. 

To run this translation successfully, this workspace requires four parameters. Two parameters that we created in the previous steps: 

• A PostgreSQL database connection (‘Production Employee Database’)
• The name of the production database table (‘Employees’) 

And two new parameters which we’ll create in the following steps: 

• An email Web Connection (sender)
• An email address (recipient) 

As an FME Admin, we may want to empower our employees to build workflows that leverage connections that are owned by the organization, like email accounts, without requiring them to access and maintain their credentials. 

From the main menu, open FME Options > Web Connections. Use the “+” button to create a web connection for the sender’s email service. This example uses Gmail. 


Once connected, exit and return to the canvas. 

Before publishing a workflow to FME Flow, it’s always a good idea to test the workflow if possible. Selecting Run prompts for four user parameters. At this point, they’re all using locally stored values. 


Feel free to run the workspace to ensure the Excel file is received by the recipient email (‘HR Email’).

From the FME Form ribbon menu, select Publish. Ensure you are connected to “Production FME Flow”. Upload the EmployeeSummary.fmw workspace to the DeploymentParameters repository. 


Select ‘My Organization Email’ to upload the Gmail web connection with the workspace. 


In the next dialog, select the Emailer package to upload.


Click through to publish the workspace. 

2. Create Web and Text Deployment Parameters on FME Flow
Open the Production FME Flow in a browser. Navigate to Files and Connections > Deployment Parameters.  Create a new deployment parameter for the uploaded email web connection.

Next, we’ll create a text-based deployment parameter for the recipient email address. 

The Production FME Flow now has four deployment parameters.  


3. Use Deployment Parameters in an FME Flow Automation
We’ll now employ our newly created deployment parameters in our workspace using an FME Flow automation.

Navigate to Automations > Create Automations. Double-click the Trigger and configure as follows:  

Apply. 

Add an Action to the automation and connect it to the trigger. Configure as follows: 

Published parameters become available once the workspace is selected. Beside each parameter, use the drop-down menu to access the deployment parameters. Each will be listed by the name given in FME Flow, prefixed by deployment.*


*Deployment parameters are only available if the type is compatible with the workspace user parameter. For example, connection-based deployment parameters are available for connection-based user parameters, but text-based deployment parameters are not. 

Repeat to apply each deployment parameter for all four published parameter values. 


Apply to save. 

Save the automation as “Employee Reports”. Select Start Automation. Once running, double-click the FME Flow Schedule trigger to open and select Trigger. 



A successful workflow delivers an email to the inbox specified in the published parameter, “Email Address (Recipient)”. 

To view the results of the workspace, open the Excel spreadsheet in a spreadsheet editor. As designed in the EmployeeQuery workspace, the first page summarizes the production employee data and the following pages categorize employees by length of tenure. 


An emailed spreadsheet means that we’ve successfully used deployment parameters in an FME Flow Automation. 


NOTE: The email may take a minute or two to arrive. But if you fail to receive the email, review the FME Flow Automation log (accessible from Employee Reports > Menu > View Log File) for evidence of any errors or job failures. 
 

Sharing Deployment Parameters

Sharing deployment parameters with others within our organization is key to maximizing their potential value. We can leverage user management and deployment parameters to customize configurations for different users, groups, and applications.  

Different deployment parameters can be created for different user groups. 

Different user groups can have different levels of access to deployment parameters.  

API Tokens allow other applications to securely access connections via deployment parameters.

Troubleshooting

"Why am I seeing an undefined macro error when running a workspace that uses deployment parameters on FME Flow"
Users lacking access permissions for a deployment parameter in FME Flow may encounter an error when executing a workspace that includes this deployment parameter. The error message typically reads, “Undefined macro ‘s3-skytrain-bucket-connection’ dereferenced in file <path to workspace>." This message indicates that the user needs access rights to the deployment parameter in question to successfully run the workspace. To resolve this, grant the user permissions to the deployment parameter. Please see this article for more details.

Additional Resources

Using the Parameter Manager
Getting Started with Automations
Making Database and Web Connections Public