Creating KML Folders Through KML IDs

Introduction

In the previous example, we learned how to create folders using a fanout feature type. In this example, we will focus on creating folders using KML IDs and KML parent attributes. This approach is best when you want direct control over folder naming and parent-child relationships for as many levels deep as you want. In other words, this approach is for creating a custom folder hierarchy.

Not sure what folders are? No problem! KML folders are what define the nested tree structure in the Google Earth Places pane. Check out the article Creating KML Folders by Feature Type Fanout for a full definition.

KML IDs Approach (kml_parent and kml_id)

Similar to the feature type fanout approach, these methods of creating folders are intended for use in KML rather than the KMZ (which is the zipped KML file).

We can create KML folders through KML IDs in two steps: first, by creating the folder structure, and then by creating folder elements and associating all our features with their appropriate folders using the kml_parent attribute.

For this example, we will be using a CSV file of Vancouver’s rapid transit stations. Rather than having a big list of stations in the KML Places legend in Google Earth, we want to organize it into a folder hierarchy. We can do this by separating stations by train lines, and then separating the downtown stops for the Canada Line, like the structure below:

The KML ID approach to folder setup uses three levels of folders. This is the file structure that we will use in our example. The parent level is Train Route. It has three children: Connection, Expo, and CanadaLine. The Canada Line has its own child folder, Downtown.

Step-by-step Instructions

Part 1: Create an Empty Folder Structure

1. Set up Workspace

Open FME Workbench and start a blank workspace. Add a Creator to the canvas, then attach five AttributeCreator transformers to it. Open the Creator parameters and delete the Creation Instance Attribute. 

If you are using FME 2025.2 and newer, you can start your workflow with the AttributeCreator only. 

As of FME 2025.2, many transformers have been updated to not require input from the creator transformer. For a list of all the transformers with this improvement, please see Transformers with an Optional Input Port

We will be using one AttributeCreator to create each folder. So in other words, if we want five folders, we’ll need five AttributeCreators. Referring to the image of the file structure above, let’s create the  Parent folder first. 

2. Create Parent Folder

Open the first AttributeCreator parameters and create the following attributes:

This is our parent folder, which we named Train Route (kml_name). Notice that the kml_id does not have any spaces. We are doing this to reduce the chance of error later when we need to associate our data with this folder. We will place data into these folders by associating it with the kml_id of the desired folder. We need to be aware of spaces and case sensitivity because our data won’t be placed in the correct folder if we have the wrong ID.
The last thing to point out here is the kml_document. Normally, the kml_document would be set to the fme_basename (the source data file name) by default when reading from a dataset. 

However, when using a Creator, we need to set the kml_document. It’s crucial here that we set all our subsequent AttributeCreators to the same kml_document name if we want to write them out into the same KML file. The name of the kml_document must also be the same name as the file that you are writing out. Folders and data tagged with a different document name than the file name will not be written out into that file.

Note for advanced users: This means that by controlling what you name your kml_document, you can write out different KML files using the same workspace. For example, if I want an offshoot KML file called potatoes, I would name the kml_document ‘potatoes’ in the AttributeCreator, and I would get an empty folder called potatoes.kml in addition to what I’m writing out in my workspace. Just be sure that your data is also being written to the desired folder and the kml_document name.

3. Create Children Folders of the TrainRoute Parent

We are now creating our next level of folders using another three AttributeCreators. We want to create the folders: Connection, Expo, and Canada Line. Alright, you got me! For those familiar with Vancouver, there is no line called Connection. It’s just a category I’ve separated for Waterfront Station, which connects the two train lines in this dataset.

In the next AttributeCreator, create the following attributes:

Notice that we have a new attribute here called kml_parent. This method of assigning parent folders is what creates the hierarchy. 

In the next AttributeCreator, create the following attributes:

Finally, in the fourth AttributeCreator, create the following attributes:

4. Create the Child Folder of Canada (Line)

The final AttributeCreator will be our subfolder to the folder Canada (Line), open the parameters, and create the following attributes:

5. Write Out Folder Structure

Now we can write out the empty folder structure to confirm that it was set up correctly. Add an OGC/Google KML writer to the canvas, and browse to a location to save the file. Name the file transportation.kml (which is the same as the kml_document we used in the AttributeCreators). Set the Feature Type Definition to Automatic, then click OK. 

In the Feature Type dialog, change the Feature Type Name to Folder, then click OK. This feature type must be named Folder for Google Earth to recognize your folder structure. 

6. Run Workspace and View Output in Google Earth

Connect the Folder reader feature type to all five AttributeCreators. Once it is connected, run the workspace, then view the output in Google Earth. 

Part 2: Add Data to Folders

7. Read Source Dataset 

As of FME 2025.2, the Coordinate System parameter is now configured within the Parameters dialog of each reader/writer format. For more information, including details about the change and affected transformers, please see Coordinate System Parameter Location Change.

• Click the Add Reader icon and add a reader with the following parameters:

    • Format: CSV (Comma Separated Value)

    • Dataset: /rapid-trainsit-stations-categorized.csv

  

  Click the Parameters button to set the coordinate system:

    • Attribute Definition: Manual

  
  

    • Name: x

    • Type: x_coordinate

  
  

    • Name: y

    • Type: y_coordinate

  
  

    • Create Point Geometry from Attributes: Enabled

    • X Coordinate Attribute: x

    • Y Coordinate Attribute: y

    • Coordinate System: UTM83-10

  

  
  

  Click OK to add the reader to the workspace.

• Click the Add Reader icon and add a reader with the following parameters:

    • Format: CSV (Comma Separated Value)

    • Dataset: /rapid-trainsit-stations-categorized.csv

    • Coordinate System: UTM83-10

  

  
  

  In the Parameters dialog, confirm that the x and y attributes are set to x_coordinate and y_coordinate, respectively. If they are not, change the Attribute Definition to Manual, then manually set.

  

  
  

  Click OK to add the reader to the workspace.

8. Filter Data to Put into Folders

Next, we will use a TestFilter to filter out our data by train line, and then our last folder, Downtown stations that belong on the Canada Line. We want to filter our data in the same way that our folders are set up so that we can associate data with the correct folder. Add a TestFilter to the canvas and connect it to the rapid_train_stations reader feature type. In the parameters, create the following tests:

Except for Waterfront, which we have categorized as a Connection, there are only two other stations on the Canada Line that we consider a part of downtown: Yaletown-Roundhouse and Vancouver City Centre stations. Using that information, we filter out Downtown stations based on the condition that the station name contains parts of the stations we are looking for (keywords: Vancouver and Yaletown).

9. Set the Parent Folder for the Stations of Each Train Line

Add a new AttributeCreator to the CONNECTION output port of the TestFilter. In this step, we are setting the KML parent folder to the data and giving the station an ID name that will be displayed in Google KML by default.
We will set the kml_parent to the corresponding folder (Connection port has a kml_parent: Connection, Expo has a kml_parent: Expo, Downtown has a kml_parent: Downtown, Canada Line has a kml_parent: Canada). 

We are using the kml_id of the folder as the kml_parent. Remember that we did not use any spaces in the kml_id’s. Below are the parameters for the AttributeCreator connected to the CONNECTION output port of the TestFilter.

For the kml_id here, we are setting it to the Attribute ‘STATION’ in all four AttributeCreators. This attribute contains the train station name. Do the same for the AttributeCreators connected to Expo and CanadaLine, using their respective kml_parent IDs.


10. Style Outputs 

At this point, all our folders in the workspace now contain data. In this step, we are styling our stations by setting icons and icon colors for visualization. Add four KMLStylers to the workspace and attach one to each AttributeCreator from the previous step. 

In the KMLStyler parameters, expand the Icon section, then set the Name to gme/gx_rail and set the Color to magenta. Repeat this step for the other three train lines, choosing a different color for each one. 

11. Set Station Names to TitleCase

If we ran our workspace now, we would find that all of our stations are written in capital letters. To make this look nicer, we will connect all of our KMLStylers to a single KMLPropertySetter transformer. In the KMLPropertySetter parameters, click on the drop-down next to Name in the Navigation Tree section and open the Text Editor. 

In the Text Editor, double-click the FullTitleCase in the String Functions section, then double-click on STATION in the FME Feature Attributes section. It should look like the following (you can also paste in the following):

@FullTitleCase(@Value(STATION))

This string function will convert our STATION name to title case.

12. Write Out Stations

Finally, we can write out the data. On the top menu bar, go to Writers > Add Feature Type. In the Feature Type dialog, change the Name to Placemarks, then click OK. 

Connect the Placemarks writer feature type to the KMLPropertySetter.

13. Run Workspace and View Output in Google Earth

Run the workspace, then view the output in Google Earth. All stations should be colored and contained within their respective folders. 

Data Attribution

The data used here originates from open data made available by the City of Vancouver, British Columbia. It contains information licensed under the Open Government License - Vancouver.