Debugging Guide for Workspaces

Introduction

If you have encountered an issue with an FME workspace and are unable to resolve it, this guide will help narrow down the problem to its simplest form. This process should help solve the issue or ensure that you receive a timely solution from technical support.

The following diagram displays the process:

Process Overview

1. Reproduce the Issue

“My workspace fails to write any data!"

Identify the exact steps that cause the issue to occur. This may be as simple as running a workspace or something more complex, such as adding a series of transformers. You will need to be able to perform this procedure again, as outlined in the steps below.

2. Narrow the Focus

“My workspace seems to fail as there are no features exiting the Clipper’s Inside port!”

Consider the problem and the various objects present in the workspace. Are you reading, writing and/or transforming data? Try to narrow down the issue to something specific.

Important clues:

• The feature count stops at a particular transformer
• The log contains an error or warning about an object
• The output dataset is unexpected or incorrect
• Data fails to be read into the workspace
• Data is not written

Helpful Tip

If you are encountering an issue when you run your workspace, use the following to help narrow down where the problem is coming from:

• Run With Data (Feature) Caching: Runs the entire workflow and then allows you to inspect the data at any point in the workspace. This option is flexible, but it may take longer, as you must process all the features first.
• Run With Breakpoints: Stops the workflow at a specific breakpoint, allowing you to visualise feature by feature within FME Workbench. This option is quick to use, as it stops at the first feature rather than running the entire workspace.
• Run With Log Debug: Log Debug provides additional information about errors to help narrow down the problem. Care should be taken to disable Log Debug before sharing a workspace or using it in production, as Log Debug may impact workspace performance or include too much detail for other users.
  
  To enable Log Debug in FME Workbench, click the settings wheel in the Translation Log window to edit log options. Or, select Tools > FME Options > Translation. Then, go to Log Settings and check Log Debug to enable it.

Once you have identified the general area where the problem exists, you can proceed to the next step.

3. Test Variables

“I’m going to try using only a single feature from the dataset”

Making small changes and testing is a great way to get to the source of an issue. For example, changing a workspace to read a smaller subset of the same data can help determine if a particular feature in that dataset is causing the issue. Below is a simple procedure to use:

Test Procedure:

• Locate a variable that can be modified
• Make a change to the variable
• Run through the reproduction steps that cause the issue to occur
• Record the outcome
• Repeat (if the outcome is not different)

The following highlights example variables that can be utilised with Step 1 of the Test Procedure:

The following highlights example changes that can be used with Step 2 of the Test Procedure:

Try anything that you think may lead to a different outcome! 

Once you have made a change that creates a different output, proceed to the next step.

Note: If you were unable to make any changes that resulted in a different outcome and have exhausted every variable, proceed to Step 6: Go Direct to Source.

4. Analyze the Outcome

“The simplified dataset was clipped! This means that a specific feature in my data is causing the problem, not the clipper!”

This step is designed to either resolve the issue or determine the next course of action. Here is a flowchart of the process:



When a specific change alters the workspace outcome, it should help you point to a possible root cause for the problem.

Root Cause Examples:

• A Specific Feature
• Geometry Type
• Incorrect Format Parameter
• Spatial Reference (mismatched coordinate systems)
• Operating System

Note: When the change seems related to a specific computer, you can Generate a System Information File for each environment to help narrow down the differences.

5. (Optional) Go Direct to the Source

In some cases, the issue may be caused by something outside of the FME software. In this test, attempt to replicate the same functionality without using FME software and see if the root cause can be identified. This is an essential step when working with components such as databases, web applications, complex formats, and Python scripts.

Direct to the Source Examples:

Issue: FME fails to read from an Esri Geodatabase.

• Test: Use the ArcGIS for Desktop product to ensure the data can be read.

Issue: Error when attempting to connect to a website using the HTTPCaller.

• Test: Try connecting through a web browser.

If the issue remains unresolved, proceed to the final step.

Next Steps

Please complete the following to ensure that you receive timely and correct technical assistance.

1. Simplify the Workflow

The goal here is to create a very simple reproduction of the issue.

Readers: 

To simplify the readers, do one of the following:

• Use 'Save As' in Data Inspector to save a small sample in the same format.
• Recreate a small sample of the data using a Creator transformer.
• Use the Recorder transformer to store your data and the Player transformer to play it back. This method is especially useful for database formats. Refer to this guide for a step-by-step explanation: Using the Recorder and Player.

If the issue requires that the specific reader format be present, then create a small subset of the data to submit with your case. To do this in FME, use the Clipper or Sampler transformer to create a new version of the data with a limited number of features.

Transformers: 

When a problem can be narrowed down to a specific transformer or series of transformers in the workflow, place a Recorder transformer directly before this area and record the data. Then replace with a Player.

Writers:

Replace writers with a Logger or Inspector transformer whenever possible.

Example of a simplified reproduction:

After each simplification step, ensure that the problem still exists. If during this process you discover that the outcome has changed, go back to step 5 above and analyse the new information.

2. Disable Unrelated Objects

Disable any components that are not related to the issue. These objects may be readers, writers and transformers within the workspace.

Run the workflow after each change to verify that the problem persists.

Examples:

a) Problem: FME errors when reading data at runtime.

• Process: Disable all transformers and writers from your workflow.

b) Problem: FME crashes within a StatisticsCalculator transformer

• Process: Disable writers and transformers located before or after the StatisticsCalculator that do not cause the issue to occur. Attach a Logger transformer to the StatisticsCalculator to ensure the data flows through.

3. Save as a Template File

Save your workspace as a template (.fmwt extension). This ensures that it can be run exactly the same way. This file contains a copy of the workspace and all the data files necessary to run. A step-by-step guide can be found here: Creating a Template File.

4. Send the Reproduction to Support

This step will create a request on the Safe Software support ticketing system.

Gather the following resources:

• The workspace template
• Log files
• System Information Report (See here for information on how to generate this report)
• Any supporting materials (Screenshots, video, documents)

Complete this form (attaching your files) in order to submit your issue to technical support.