FME Form Troubleshooting: Web Services and Connections

Introduction

Many FME users are unfamiliar with web services and may find editing or creating web services in FME a more advanced task. Additionally, it is not always easy to discern the cause of a failed web service authentication in FME Form (formerly FME Desktop). Oftentimes the web service provider returns an HTTP response and error code which can be useful in creating a successful web service, and subsequent web connection.
This troubleshooting guide will go through common errors or mistakes that are seen when users are creating web service definitions and troubleshooting steps that we often go through to find the cause of failure.

This article is specific to FME Form. For troubleshooting on FME Flow (formerly FME Server) see the article FME Flow Troubleshooting: Web Connections
 

Checklist

Are you using the right type of web service?

FME supports OAuth 2.0, token and HTTP. Your web service provider documentation should state what type of connection is used. See Web Connections and FME.

Have you correctly entered all of the information for the web service?

The web service documentation should show how the web service definition should be set up, for how the auth URL is formatted, whether you need to send a client secret, if it has a refresh token URL, etc.

Have you tested the web service in a separate HTTP client?

Many web services show examples using Postman. If you can successfully get it working in another HTTP client (like Postman) then there is a high likelihood it should work in FME.

Have you cleared the cache?

Sometimes when signing in to a web service to authenticate you may be prompted to save credentials, or FME may cache settings like the auth URL. If you're expecting a different behaviour or outcome it can be useful to clear the cache. To do this on the FME Toolbar, choose Tools > Purge Temporary Files. This will clear the cache for FME Form and allow you to re-test your web service.

Do a web search for any web service provider errors.

If you see an error in the pop-up browser FME launches for authentication that comes from the service provider, a web search will likely return results that explain what caused the error. Web service provider documentation or sites like Stack Overflow will often return helpful results for error codes and error messages, allowing you to fix the issue.

Have you searched the FME Community?

For popular web services you may find tutorial articles or forum questions that may help you resolve your issue.
 

Additional Troubleshooting

If you are still unable to identify the cause of an incorrect web service definition, here are some advanced troubleshooting steps you can take to analyze web traffic to and from the web service.

As FME uses QT (an application manager), QT is interpreting the responses from the web service that is being authenticated with. It is unlikely that you will see logs in the FME Form log window.
When you authenticate with an OAuth service, FME (QT) opens a browser window so that you can enter your credentials.
As FME does not log the requests or responses made to web service, you may need to use another method to analyze the traffic. Seeing the response from the web service can be very helpful in debugging an unsuccessful web service.

QT debug

This option is good for checking that the authorization URL has been formed correctly based on how the web service definition has been set up, or if you are having issues with the browser window that FME opens.
If you wish to use the browser's developer tools to help troubleshoot, you can open FME with a remote debugging port. Any embedded browser windows will be accessible through your browser.

To do this, open FME Workbench with the --webEngineArgs and --remote-debugging-port flags.  The --webEngineArgs flag is optional for FME 2022 and older but is required for FME 2023 and newer. You will need to open a command line tool and navigate to the location of the FME executable:

$ ./FME fmeworkbench --webEngineArgs --remote-debugging-port=8091 

DevTools listening on ws://127.0.0.1:8091/devtools/browser/2598870a-f0b9-471a-8194-9789b6a80ead

Navigate to http://127.0.0.1:8091 in your browser and refresh the page once an embedded browser is opened in FME. Here you can verify that the authorization URL has been formatted correctly, by comparing it to documentation for that web service or an HTTP client, like Postman. 



Clicking on the URL will open a developer tools window where you can inspect the network traffic. Click on the >> to view the Network tab.

If FME opened the authentication window in a normal browser window you can open developer tools and inspect the network traffic.


When inspecting the network traffic it may be useful to check the request (to check it is formatted correctly) and response (for any errors).

Fiddler

Fiddler is a web debugging proxy tool that makes it easy to inspect web requests that FME is sending to a web service and analyze the response. 

If web service authentication or authorization fails when testing in FME, oftentimes the response that is displayed is not very informative and won’t tell you why it failed. Web services should return an error code and a message, which you can look at using Fiddler.

An example of a response in FME Form:


Setting up Fiddler
Note: These screenshots are from Fiddler Everywhere. If you are on Windows, you may be able to use Fiddler Classic. The functionality should be the same, although the UI will be different.

Once Fiddler is installed and running, open the settings to see which port it is running on:


Configure FME to use a system proxy and make sure that it’s using the same port that Fiddler is listening on.


Use Fiddler to analyze FME web traffic
You can filter Processes in Fiddler to only show traffic coming from FME:


If you now test your web service, you should see requests to that service appear in Fiddler.


The error in FME shows that the web service was unauthorized, but doesn’t say why.
Clicking on that request in Fiddler (to login.microsoftonline.com) and then inspecting the response body confirms that this is due to a missing client secret. With this information you can now correct your web service definition in FME and try again.

Additional Resources

Please consider posting to the FME Community Q&A if you are still experiencing issues that are not addressed in this article. There are also different support channels available.

Make sure to include as much information as possible:

• What web service are you connecting to? Include relevant documentation from that web service.
• What troubleshooting methods have you tried so far?
• Include any error messages.
• Screenshots of web service definition and any set up on the web service provider end that may help identify any issues.