Writing to Cartegraph

Introduction

FME can be used to write to the Cartegraph! Writing to Cartegraph can be very simple if the features contain no geometry. However, it gets more complicated if you are sending geometry to Cartegraph, as you would need to recreate the JSON format 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 also be used to update records. 

Since the attributes submitted by Cartegraph vary by class, most attributes will need to be submitted via JSON. Some examples include:

Example 1:

"IDField":"Sign-50", "AddressNumberField":1765

"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 the workspace and view the bookmark named "Simple JSON Example."

In this example, the JSON submitted to Cartegraph is very simple, so the JSONTemplater is not needed to generate the JSON body.

The CartegraphConnector is used to obtain an authentication cookie, which is then passed to 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. 

Finally, the other fields parameter is used to submit the bulk 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

This bookmark demonstrates how FME can extract coordinates from geometry and generate JSON in the format required by the Cartegraph API. This process relies on JSONTemplater to generate the required JSON. 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. 

{
   "CgShape":{
      "Points":[
         {
            "Lat":41.569919018000064,
            "Lng":-93.722765304
         },
         {
            "Lat":42.569918015,
            "Lng":-93.722739823
         },
         {
            "Lat":41.569908985,
            "Lng":-93.722198017
         },
         {
            "Lat":41.569907982000075,
            "Lng":-93.722173877
         }
      ],
      "Breaks":[
         
      ],
      "ShapeType":2,
      "Center":{
         "Lat":42.069912998500058,
         "Lng":-93.722469590499969
      }
   }
}

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.

6. Creating the Center Point 

The goal of this bookmark is to create a center point. In Cartegraph JSON notation, a center point is expected for each multipoint object. To create this in FME, a BoundingBoxAccumulator is used first. The BoundingBoxAccumulator creates a bounding box, and the CenterPointReplacer is then used to place a point at the center 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. 

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

7. Using the Deaggregator to separate the points

Attached to the AttributeCreator is a Deaggregator. The Deaggregator splits the multipoint feature into points.  This allows us to use each point in the JSONTemplater. 

8. Review the JSONTemplater

The JSONTemplater is used to generate the JSON to feed the CartegraphCreateOrUpdate transformer. 

Let’s start by looking at the Root port. The Root template: 

  {
         "CgShape" : {
            "Points" : [
           fme:process-features("SUB")
            ],
            "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.

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.

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.

{
    "Lat":geom:get-y-coord(),
    "Lng":geom:get-x-coord()
}

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.

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 generated by the JSONTemplater.

Summary

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