Writing to Cartegraph

Sienna Emery
Sienna Emery
  • Updated

FME Version

  • FME 2021.2


FME can be used to write to the Cartegraph! Writing to Cartegraph can be very simple if the features contain no geometry. However, it does get more complicated if you are sending geometry to Cartegraph as you would have to recreate the JSON format that Cartegraph uses. Typically, web services will use GeoJSON, which FME can easily create. However, since Cartegraph uses a different format, we need to use our JSON transformers to recreate it. 

Data is written to Cartegraph using the CartegraphCreateOrUpdateObject transformer. However, the same transformer can be used to update records as well. 

Since the attributes submitted by Cartegraph are different based on each class, most attributes will have to be submitted through JSON. Some examples include:

Example 1:

"IDField":"Sign-50", "AddressNumberField":1765
Example 2:
"ConditionCategoryField": "Appearance", "WeightField": 1,
              "cgBridgeConditionCategories_cgImpactsClass": [

                      "ActivityField": "Clean",
                      "ImpactField": {

                        "Amount": 35,

                        "Unit": "Relative"

} ]

The following workspace demonstrates how the JSONTemplater can be used to submit JSON to the CartegraphCreateOrUpdateObject.


Step-by-Step Instructions

1. Download the Workspace 
Download the workspace (CartegraphArticlesCreateExamples.fmw) found in the files section of this article.

2. Open the Workspace in FME Workbench
In FME Workbench, open up the workspace and view the bookmark named Simple JSON Example.

Simple JSON Example

In this example, the JSON submitted to Cartegraph is very simple and therefore, the JSONTemplater is not needed to create the JSON body which is submitted.

The CartegraphConnector is used to get a cookie for authentication, which is passed into the CartegraphCreateOrUpdateObject. 

3. Review the CartegraphCreateOrUpdateObject transformer
Now, click the cogwheel, to open up the CartegraphCreateOrUpdateObject parameters.


Here, the Action is set to Create, however, this could be set to Update as well if you wish to Update Objects.
Next, the className is set to cgMarkingsClass. This will create a new Markings object in Cartegraph. 

Other Fields

Finally, the other fields parameter is used to submit the bulk on the request. The following is an example of what can be submitted. Please see the Cartegraph API documentation for more examples. 

4. View the Transforming Geometry to JSON bookmark

Complex JSON

This bookmark shows how FME can extract coordinates from geometry and create JSON in the format needed for the Cartgegraph API. This process relies on the JSONTemplater to create the JSON needed. If you’re looking for more examples of how to use the JSONTemplater, see the Writing JSON with the JSON Templater.

This bookmark shows how to transform multipoint features into the Cartegraph JSON notation. This is an example of what the workspace creates. 



5. Review the AttributeCreator
Here, an AttributeCreator is used to create an Object ID (Oid in the workspace). Typically features would already have an object id. The object id is used throughout the workflow to ensure that features with the same object id are processed together in Group-Based Transformers.

Oid Creation

6. Creating the Center Point 

Center point

The goal of this bookmark is to create a center point. In the Cartegraph JSON notation, a center point is expected per multipoint object. To create this in FME, a BoundingBoxAccumulator is used first. The BoundingBoxAccumulator creates a bounding box, then the CenterPointReplacer is used to place a point in the middle of the bounding box.

Please note that the bounding box is not needed here. The CenterPointReplacer could work without it, using the Center of Gravity Point mode. However, in my experience, using the bounding box mode had better results.

In the BoundingBoxAccumulator, a bounding box is created from all the points that share an object id. 
Bounding box replacer

From there the CenterPointReplacer is used the get the center point of the bounding box. Ensure that the Mode is set to Center Point of Bounding Box.

Center point replacer

7. Using the Deaggregator to separate the points
Attached to the AttributeCreator is a Deaggregator. The Deaggregator is used to split the multipoint feature into points.  This allows us to use each point in the JSONTemplater. 

8. Review the JSONTemplater
The JSONTemplater is used to create the JSON to feed it into the CartegraphCreateOrUpdate transformer. 
Let’s start by looking at the Root port. The Root template: 

         "CgShape" : {
            "Points" : [
            "Breaks" : [],
            "ShapeType" : 2,
            "Center" : {
               "Lat" : geom:get-y-coord(),
               "Lng" : geom:get-x-coord()
         "ActBeforeField": fme:get-attribute("ActBeforeField"),
         "ApplicationMethodField": fme:get-attribute("ApplicationMethodField"),
         "CityField": fme:get-attribute("CityField"),
         "ColorField": fme:get-attribute("ColorField"),
         "EnteredByField": fme:get-attribute("EnteredByField"),
         "EntryDateField": fme:get-attribute("EntryDateField")

This section contains most of the information needed to create the object in Cartegraph. 

However, the Points section will be an array created by the multipoints split by the deaggregator. 

 "Points" : [ fme:process-features("SUB") ]

From there the center point is written using the X and Y coordinates from the center point created in the CenterPointReplacer.

 "Breaks" : [],
            "ShapeType" : 2,
            "Center" : {
               "Lat" : geom:get-y-coord(),
               "Lng" : geom:get-x-coord()

These fields use the XQuery functions built into the JSONTemplater. These functions allow the JSON templater to use geometry in the features and access the Sub Template as seen below.
Root Templater

After the CgShape object, any additional attributes can be added to the JSON. In this case, we are adding the ActBeforeField, ApplicationMethodField, CityField, ColorField, EnteredByField and EntryDateField.

Next, we can take a look at the SUB Template.

Group processing

The Group Sub-Features By, allows us to ensure that only features from the same object are grouped together in the array.
Finally, the SUB Template is used to list each x and y coordinate per point.


9. Run with Feature Caching Enabled
Run the workspace up to the JSON templater to view the results. Select the magnifying glass on the Output. The _results attribute will contain the JSON, double click to open it. Click the ABCXYZ icon and then select JSON which will format it nicely for visualization.

Feature caching

10. Review the SubstringExtractor_2 transformer
Here the SubstringExtractor is used to remove the starting and ending curly brackets. This is needed to use it in the CartegraphCreateOrUpdateObject. 

11. Review the Cartegraph Transformers
Finally, the CartegraphConnector is used to get the Session Cookie. Then, the CartegraphCreateOrUpdateObject is used to create the object with the features from the JSON created in the JSONTemplater.



After completing this tutorial, you should now be able to successfully create records in your Cartegraph instance via the Cartegraph REST API. 

Was this article helpful?



Please sign in to leave a comment.