|Exercise 3||Grounds Maintenance Project|
|Data||Parks (MapInfo TAB)|
|Overall Goal||Parameterize and implement a translation log|
|Demonstrates||Creation and use of complex User Parameters|
In a previous project (in the FME Basic Desktop training) you created a project to transform parks data by calculating the size and average size of each park.
The team who are using this now want to implement it on FME Server. At the same time they want to improve some of the functionality and implement a custom translation log.
As you created the original workspace, you are assigned to carry out these upgrades to your former work.
- Set the output to write to a folder for that user
- Ask whether to filter out dog parks
- Ask which attribute to create labels of
- Create a translation log in CSV format
1) Start Workbench
Start Workbench and open the workspace C:\FMEData2016\Workspaces\DesktopAdvanced\Parameters-Ex3-Begin.fmw
You can see that the workspace reads some MapInfo parks data, filters out dog parks, calculates park area and average area, creates labels, and writes out the data back to MapInfo.
There are two existing published parameters - one for the source dataset and one for the destination. The source dataset will never change, and we are going to create a new parameter for the destination, so delete these two parameters.
2) Add User Parameter
If we are going to write the output to a folder specific to the current user, we need to know who that user is.
So, next create a text format user parameter to ask for the user's name:
Ensure that the optional checkbox is unchecked; we want users to have to enter a value in here.
3) Add User Parameter
There are various ways we can implement the requirements here; we'll do the version that involves sharing user parameters.
So, create a new user parameter of type Folder (Existing). Uncheck BOTH of the Published and Optional fields; i.e. it will be a private parameter for us to use (not the end user) and it will be required.
Set the Name field to something like OutputFolder and for the Value browse to C:\FMEData2016\Output\Training
|Dr Workbench says...|
|Technically, we could use a text-type parameter. The only benefit of a folder parameter is it lets us browse to the location. But since it's a private parameter, that the user will never see, it doesn't really matter. Anyway, both methods will cure our problem.|
4) Set Output Location
Now let's use the two parameters we've created.
*NB: First ensure you deleted the two existing source/destination user parameters in step 1, else this step won't work!*
Locate the FME parameter for Destination MapInfo Folder in the Navigator window and double-click it to open the editing dialog.
In that dialog manually enter:
Alternatively, use the text editor where you can add these by double-clicking, to reduce the chance of error.
You've basically concatenated/embedded the two user parameters into the FME parameter.
When you run the workspace you will be prompted to enter your name and then the output data will now be written to C:\FMEData2016\Output\Training\<username>
|Dr Workbench says...|
|There are various ways we could have done this. We could have set the OutputFolder parameter to C:\FMEData2016\Output\Training\$(username) and then linked it to the FME Destination MapInfo parameter. You'll see in a moment why we didn't do that!|
5) Add User Parameter
The next task is to check whether dog parks are required in the output. The Tester transformer in the workspace shows that an attribute (DogParks) will have a value of Y or N to denote its status. We need to ask the user and add their decision to the Tester.
So create a new user parameter. It will be a Choice type parameter that is not optional:
Set it up to be a simple Yes/No question of whether to include dog parks in the output.
6) Update Tester
To use the DogParks parameter open up the Tester parameters dialog. Add a second test clause:
$(DogParks) = Yes
Now when the workspace runs, if you choose not to keep dog parks they will be filtered out from the workspace. This concept - of directing features depending on the value of a user parameter - is a very useful one to be aware of.
7) Add User Parameter
OK. Next task is to allow the user to pick which attribute to use for a label.
As noted in the previous section of training, if we just publish the label parameter in the LabelPointReplacer the user will be able to enter text as well as select an attribute. We want them to have to select an attribute and not to be able to enter text.
So, create a new user parameter of type Attribute Name. This one can be optional, as the user failing to select an attribute is equivalent to saying "no labels required":
|Dr Workbench says...|
Click the run button and see what appears in the list of prompts; you should see a parameter to Select the Label Attribute. But look! The parameter shows "No Attributes Available". Why is this?
This is because the list of available attributes depends on where the parameter is used. Since we have not used the parameter yet, no attributes are available!
Similarly, if we used the parameter in a location where we have attributes A and B, and also in a different location with attributes B and C, the only attribute available to the parameter is B. That's because a parameter of this type will only show attributes that exist in all places that it is used.
8) Update LabelPointReplacer
To use the LabelAttribute parameter open up the LabelPointReplacer parameters dialog.
Remember (again from the previous section) that we can't just apply this user parameter to the Label FME parameter. That would just return the name of the attribute; we want the attribute value.
So in the Label parameter manually enter (or open the text editor and enter):
Now when the workspace runs you are also prompted to select an attribute to label the parks with. If you choose no attribute, no labels are created (just point features).
9) Add Log Writer
The final task is to create a CSV format translation log. That is not too difficult to do.
Use Writer > Add Writer to add a new CSV format Writer with the following setup:
|Writer Format||CSV (Comma Separated Value)|
|Writer Parameters||Append to File: Yes (Checked)
Output Field Names on First Line: No (Unchecked)
|Add Feature Type(s)||CSV File Definition: Manual|
When you click OK the dialog will open for you to define the table schema.
On the General tab set the CSV File Name as TranslationLog:
In the User Attributes tab, define the attributes User and Date:
Click OK to close the dialog.
10) Connect Feature Type
We need a single record to trigger this feature type; but just one feature else we will get multiple records.
Place a Creator transformer down and connect it to the TranslationLog feature type:
11) Set Output Folder
We should set the output location for the log to be relative to where the user files are being written.
So, locate the destination dataset parameter for the CSV Writer, right-click on it and choose Link to User Parameter:
When prompted select the OutputFolder (private) parameter that we created earlier.
|Dr Workbench says...|
You might be wondering what the point of that last part was. Why did we link the parameter when both were pointing to the same folder already?
The point is that now the MapInfo and CSV Writers share a parameter defining their output folder. If we wish to change where they are being written to (say when the path changes from FMEData2016 to FMEData2017) we only need to edit the private parameter to fix both Writers.
If you don't believe me, try it and find out for yourself!
12) Set User Attribute
The very last step here is to provide values for the User and Date fields of the translation log (CSV Writer).
Right-click on the attribute called User on the feature type and choose the option to Edit Value:
In the dialog that pops up enter $(username) (you'll be prompted for it shortly after you start to type):
This is another example of sharing user parameters. This parameter is now used here and in the MapInfo Writer name.
13) Set Date Attribute
Now add a TimeStamper transformer to provide a value to the Date attribute:
We are done! Save the workspace and then run it!
You should find your choice of data (with or without labels) written to a folder under your name, and a record of the translation added to the CSV file in the parent folder.
By completing this exercise you have learned how to: