Connecting to Cartegraph

Introduction

Cartegraph is an asset and operations management system used to manage assets and track work. 

FME can connect to Cartegraph using the suite of Cartegraph Transformers available on the FME Hub. These transformers do require access to the Cartegraph API to be used. The Cartegraph transformers can be used to create, delete and modify business objects. If you need to use any other functionality from the Cartegraph API, you can use the HTTPCaller to access the API. 

Authorizing Cartegraph

Cartegraph is authorized through the CartegraphConnector transformer. The CartegraphConnector makes a call to the Cartegraph API and returns a cookie. This cookie can be used with the other Cartegraph transformers to connect to Cartegraph.

Step-by-Step Instructions 

Getting data from Cartegraph is easy. To authorize any Cartegraph transformer or API call, first, use the CartegraphConnector transformer. The output of the CartegraphConnector is a cookie that can be used to authorize the other Cartegraph transformers.  

1. Open FME Workbench 
Open FME Workbench and click New to create a blank workspace.

2. Add a Creator
Add a Creator to the canvas. The Creator will initiate the workspace.

3. Add a CartegraphConnector
Add the CartegraphConnector to the workspace and attach it to the Creator. Fill in your instance, username, and password in the CartegraphConnector. 



4. Run the workspace with Feature Caching enabled
Click the drop-down menu by the Run button and ensure that Feature Caching is enabled. 



Then, run the workspace. 
Click on the Cookie output port to view the results. You should see an attribute called session_cookie which should contain a value from Cartegraph. This is the cookie that will be used in all other Cartegraph transformers.




5. Add the CartegraphObjectFetcher 
Add the CartegraphObjectFetcher and connect it to the CartegraphConnector. First, we will start with a basic query to get all the data stored within a class in Cartegraph. 
Open up the CartegraphObjectFetcher to configure the parameters.
Add your instance URL to the Instance. Next, set up the Session Cookie. This should be set to the session_cookie attribute. 
Finally, select the cgMarkingsClass and select OK.



6. Run the workspace with Feature Caching enabled


Run the CartegraphObjectFetcher, to get the results. If you inspect the results, you’ll find that the data from the CartegraphObjectFetcher is stored in the _response_body attribute. 



7. Parse the JSON stored in the _response_body 
Add a JSONFlattener to the canvas and connect it to the Output port of the CartegraphObjectFetcher. 
Open the JSONFlattener, and under JSON Document select the drop-down menu, then find Attribute Value and select the _response_body attribute. 

 Add the following under attributes to expose:

• Oid
• ActBeforeField
• CgShape{}
• ApplicationMethodField
• CityField
• ColorField
• EnteredByField
• EntryDateField
• cgGeoSyncDateField

Click OK to exit the Attributes to Expose dialogue and OK again to exit the JSONFlattener.

8. Expose the point attributes
Add an AttributeExposer and attach it to the JSONFlattener. 
Open the AttributeExposer and add the following attributes to expose:

• CgShape.Points{}.Lng
• CgShape.Points{}.Lat

9. Explode the list
Add a ListExploder and attach it to the AttributeExposer.
Set the List Attribute to CgShape.Points{} and select OK.  This will expose all the points contained in the feature. 

 10. Create points
Add a VertexCreator and attach it to the ListExploder. 
The VertexCreator will take the text data and create geometry from it. 
Open up the VertexCreator and set the X Value to Lng and the Y Value to Lat. 



11. Set the coordinate system
Add a CoordinateSystemSetter and attach it to the VertexCreator.
The CoordinateSystemSetter is used to define the coordinate system used.
The coordinate system should be set to LL84.

12. Aggregate the points
Finally, we need to aggregate the points together. To do this we need to add an Aggregator. 
Attach the Aggregator to the CoordinateSystemSetter. 
In the Aggregator, check the Group Processing box and under Group By select the Oid attribute. 
This will group all attributes with the same Object ID. Which will aggregate all the points together with the same object id.

13. Add an AttributeRemover
Add an AttributeRemover to the canvas and attach it to the Aggregator. 
The AttributeRemover will remove attributes that we do not want to write out to the destination data.
Open up the AttributeRemover and select the following attributes:

• _creation_instance
• _element_index
• _Instance
• _reponse_body
• _SESSION_COOKIE
• Limit
• Offset
• session_cookie

Then, select all the items in Lists to Remove and then select OK and OK again to exit the dialogue. 


14. Add a Geodatabase Writer
Finally, add an Esri Geodatabase (File Geodb Open API) writer to the canvas. 
Set up the dataset to write out to a geodatabase on your Desktop. Click OK to exit the dialogue.



In the next dialogue, set the Table Name to Markings. Then, set the geometry to geodb_multipoint. Click OK.
Connect the writer to AttributeRemover. 

15. Run the Workspace and inspect the output
Run the workspace and inspect the output in FME. 

Summary

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