| Exercise | Workspace Webhook |
| Overall Goal | To show how FME Server can be used to create a web service |
| Demonstrates | Creating a web hook and associated security token to serve a web service and then calling this service from a third party application. |
1) Open FME Server
Our first step will be to visit FME Server. We can do this by going to:
http://localhost/fmeserver
If you are using a training computer login as the admin using these credentials or those supplied by your trainer.
Username: admin
Password: admin
2) Open Workspace
Having opened FME Server navigate to and select the Run Workspace menu option from the top left of the FME Server interface.
From the Run Workspace screen select the Repository drop down and choose Samples.
Select the austinDownload.fmw from the Workspace drop down.
From the Service drop down choose Data Download.
Expand the Advanced Tab at the bottom of the page.
3) Create the Webhook
From this section scroll down to the Other Ways to Run this Workspace section and select Create a Webhook.
This will open the Webhook preview page. From here you can provide information on the Webhook that is being created and choose which parameters are required.
It also allows you to name the token so that you can identify it in the future. It is best practise to give this a sensible name and it can also be useful to store the token value in the name. This means if you find a token in an application you can link it easily back to FME Server. FME will also not display the token value anywhere else so unless a record is kept of it this method is the only way to view the value. It is not recommend however if the token is protecting data that is sensitive or of high value.
Set the Token Name to a suitable memorable name.
You can also include some information in the Description field describing why the token/webhook is being used. This is again best practise as it provides some documentation as to the purpose. Lastly you can change the Expiration if required though we will accept the default value.
Click OK.
4) Review and Store Credentials
Have created the webhook/token FME Server will display a summary screen that shows two different methods of using the Token. The token can either be used inline as a Query String parameter or used within the Authorisation Header. Either is valid but using it within the Header is considered better practise.
There is also the option to Download Webhook which allows you too download a text file containing a summary of the information presented.
This file can only be downloaded once so it recommended to store it safely especially if the token value is not stored with the token name.
Download the text file and keep it safe as we will use it in the next part of the exercise.
5) Call Webhook from External Source
Having created the webhook and token we can test the new web service using PostMan to mimic an external application calling the service.
Open PostMan.
Then create a new request by selecting the orange Plus (new) icon in the tabs menu towards the top of the application to create a new request page.
Set the Request Method to GET and in the Enter Request URL section enter the following
http://localhost/fmedatadownload/Samples/austinDownload.fmw?
This it the base URL of our new API that we will call. We now need to configure the query string parameters we wish to pass in.
The query string parameters are defined by the FME Workspace's published parameters and inherit their names from this. We can also see these within the URL string within the webhook text file we downloaded and the webhook configuration pages above.
The query strings are a series of Key Value pairs that we can set in the Query Params part of the PostMan page. As we are only testing the request we can use a sample set of values given below to mimic what a real request might look like.
In the Params window enter the following values.
| Key | Value |
|---|---|
| THEMES | cenart |
| FORMAT_GENERIC | PDF2D |
| MINX | -97.5 |
| MINY | 30.1 |
| MAXX | -98 |
| MAXY | 30.5 |
| COORDSYS | LL84 |
The resulting configuration should look like the below.
Click on the Send option and review the response displayed at the bottom of the panel.
You will noticed two things first that the authorisation has failed and secondly that the response is in HTML. Whilst the HTML response is fine for a browser if we want another application to call this service it would make sense to return the response in a machine readable format.
6) Set Header and Response Format
In order to securely access the web service we need to pass in the security token we generated to do this select the Headers section from the list below the URL menu to bring up the Header parameters.
Under the Key menu if you start typing a list of the available Header options will appear. Start typing Authorization and then select it from the drop down list.
Then under the Value column enter the following
fmetoken token=12345
We will replace the value 12345 with the token value shortly but this value will act as a placeholder for our initial test.
In order to get the response back in a machine readable format we can leverage a special parameter that the FME Server service supports, this is opt_reponseformat and the value of this determines if the response comes back as HTML as before, or in machine friendly JSON or XML.
Go back to the Params tab and add the following Key Value pair
| Key | Value |
|---|---|
| opt_responseformat | json |
This can be added at the bottom of the existing list as per the example below.
Send the Query again and you should now see the unauthenticated message in JSON.
7) Add the Token
We can now replace our token value with the token that we created. To do this go back to the Headers page and replace 12345 with the value of the token you created.
The token will be shown in the Text Document you downloaded.
8) Send the Query
Having replaced the token send the request again, and this time you will notice that the response takes longer to arrive as FME is now run the Workspace and preparing to return the response.
You will now get a JSON response back containing all of the information about the processed job along with a download URL.
An application can parse this response and make the download link available to the user or process the returned file its self.
If a streaming service is used the web service can return JSON or XML etc directly to the requesting client enabling it to process directly without needing to parse a job response to access the data.
9) Simplify the response
Whilst the returned response contains a lot of information that might be useful it is verbose and a consuming application would not normally need all the information shown.
The response can be simplified using another FME Server service parameter value called opt_showresult. This controls if a summary response is sent or the full response.
Under the Params Key Value pair add opt_showresult with a value of false and rerun the request.
The response returned will contain just the job number, status and the URL to the file to be downloaded.
| CONGRATULATIONS |
|
The tasks above demonstrate how you can create web services using FME Server and how you can call this from an external application. These web services can be called by web sites, other business applications or even other FME processes as required. You have also learnt how you can change the response format to make it more readily useable in a programming environment to quickly parse the returned response. |
| Advanced Task |
|
The web service above supports everything that the Workspace supports so what you can request from the Workspace running on FME Server can be selected from the API by changing the parameter values used. Try some of the values below to see how this effects the output returned. Available Themes:
The above example uses the data download service, try creating a webhook for the data streaming service and seeing how to download the workspace response directly. In order to do this you'll need to update the services the workspace is registered with. In FME 2020.1 there is now an option to change the registered services directly in FME Server under the Actions menu when you select a workspace under the Manage Workspace's menu. |