Skip to main content
Cartegraph Campus

Business Objects for REST API

This feature may not be available in every package. Not sure if you have this feature or you want to learn more about it? Send us a message at support@cartegraph.com.

Cartegraph's API is a licensed product that requires a purchase and verified ownership before production use.

The main purpose of the REST API is to allow a RESTful service interface for Cartegraph recordsets. Currently, the API does not handle non-metadata-driven business objects, shared recordsets (with POST, PUT, and DELETE), etc.

Every record in the Cartegraph system has a property Oid that acts as the "object ID". This is the key used by the REST API to GET/PUT/DELETE a particular record. When specifying the Oid property, case matters. Also, the Oid property value cannot be updated once the record has been saved.

Calls completing successfully will return a 200-level status code, as well as the appropriate payload in the response. Calls returning a 400- or 500-level error code will return an ApiError object to the caller.


Retrieve a record (GET)

  • Purpose: Retrieve a list of one or more records of a recordset.
  • HTTP Method: GET
  • URL:
    • https://yourserver.com/cartegraph/api/v1/classes/{className}
    • https://yourserver.com/cartegraph/api/v1/classes/{className}/{id}
    • https://yourserver.com/cartegraph/api/v1/classes/{className}/{id}/{childClassName}
  • URL Parameters:
    • className - required - Cartegraph class name (for example, cgSignsClass)
    • id - Oid of the record
    • childClassName - Cartegraph class name (for example, cgSigns_cgInspectionsClass)
  • Optional Parameters:
    • fields - Comma separated list of fields to return
      • The value for CgProximity is always returned in meters from the currentLocationLatitude and currentLocationLongitude passed in.
      • Exceptions:
        • Can only request CgProximity if currentLocationLatitude and currentLocationLongitude are specified and the class has a non-zero GeoType
      • Example: IDField,NotesField,CgProximity,MUTCDCodeField,DescriptionField
    • filter - Filter to apply to the select
      • Use when selecting a list of items rather than an individual record
      • Exceptions:
        • Cannot filter on CgShape or CgProximity field
      • Example: ([MUTCDCode\Classification] is equal to "Regulatory")
    • sort - Sort to be applied to the returned list of records
      • Default sort is Oid ascending
      • Sorting by CgProximity Ascending will return records with no location at the bottom of the list with a null value for CgProximity.
      • Exceptions:
        • Cannot sort on CgShape field
        • Can only sort by CgProximity if currentLocationLatitude and currentLocationLongitude are specified and the class has a non-zero GeoType
      • Example: IDField:asc,MUTCDCodeField:dsc,CgProximity:asc
  • limit - Number of records to return. The default number of records returned is 1000, unless otherwise specified.
  • offset - Number of records to skip
  • currentLocationLatitude - Current latitude position of the client
    • Used for calculating and/or sorting by the CgProximity field
    • Must be used with currentLocationLongitude
    • Example: 42.54
  • currentLocationLongitude - Current longitude position of the client
    • Used for calculating and/or sorting by the CgProximity field
    • Must be used with currentLocationLatitude
    • Example: -90.7654

  • bypassRoleBasedFiltering - Indicate that recordset filters configured for the logged on user's role should be bypassed.
    • The default value is false, meaning that recordset filters will be applied unless otherwise specified.
    • Example: bypassRoleBasedFiltering:true

  • ignoreNullFields -  When set to true, any fields with a value of null or "" will not be returned.

    • Records returned may not include all fields

    • Minimizes response payload size

    • Defaults to false if not specified

Example Requests

Get Sign record with Oid 435560664 with fields filter set to Oid, Address Number, and ID:

GET https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass/435560664?fields=Oid,AddressNumberField,IDField

Get Multiple Sign records excluding null fields and fields filter set to Oid, Address Number, and ID, having a limit of 3 and offset of 0:

GET https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass?fields=Oid,AddressNumberField,IDField&limit=3&offset=0&ignoreNullFields=true

Get Sign Inspection with Oid 1714378640 with all fields included:

GET https://yourserver.com/cartegraph/api/v1/classes/cgSigns_cgInspectionsClass/1714378640

Get all Inspections ordered by Inspection Date for Sign with Oid 1298381004 with fields filter set to Inspection Date, Inspected OCI, and Ra State:

GET https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass/1298381004/cgSigns_cgInspectionsClass?fields=InspectionDateField,InspectedOCIField,RaStateField&sort=InspectionDateField:asc

Get Multiple Sign records with fields filter set to Oid, CgProximity, and ID, sorting by CgProximity, having a currentLocation of (42.5, -90.7):

GET https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass?fields=Oid,CgProximity,IDField&sort=CgProximity:asc&currentLocationLatitude=42.5&currentLocationLongitude=-90.7

Example Responses

For GET calls, we always return an array of objects, even when requesting a single object. This applies to both top-level and child recordsets.

A Single Sign record with Oid 435560664 with fields filter set to Oid, Address Number, and ID:

{
    "cgSignsClass": [
    {
        "Oid": 435560664,
        "AddressNumberField": null,
        "IDField": "104"
    }
    ]
    "_metadata": {
        "totalCount": 1,
        "limit": null,
        "offset": null
    }
}

Get Multiple Sign records excluding null fields and fields filter set to Oid, ID, and Address Number, having a limit of 3 and offset of 0:

{
    "cgSignsClass": [
        {
            "Oid": 282682861,
            "AddressNumberField": 123,
            "IDField": "1"
        },
        {
            "Oid": 1588324354,
            "AddressNumberField": 456,
            "IDField": "10"
        },
        {
            "Oid": 1963899943,
            "IDField": "100"
        }
    ],
    "_metadata": {
        "totalCount": 218,
        "limit": 3,
        "offset": 0
    }
}

Sign Inspection record with Oid 1714378640 with all fields included:

{
  "cgSigns_cgInspectionsClass": [
    {
      "ParentOid": 1298381004,
      "Oid": 1714378640,
      "AssessmentMethodField": "",
      "BackgroundRaField": 40.2,
      "cgLastModifiedField": "2016-04-06T17:59:20-05:00",
      "ContrastRatioField": 3.27,
      "EnteredByField": "BackgroundDataExchanger",
      "EntryDateField": "2016-04-06T17:38:21-05:00",
      "IDField": "1009",
      "InactiveField": false,
      "InspectedByField": "",
      "InspectedOCIField": 33.09,
      "InspectedOCRField": "Fair",
      "InspectionDateField": "2005-06-06T00:00:00-05:00",
      "LastModifiedByField": "BackgroundDataExchanger",
      "LegendRaField": 12.3,
      "NotesField": "",
      "PatIntegerGreaterThan10Field": null,
      "PatIntFieldField": null,
      "PatRequiredDateTimeField": null,
      "PatRequiredLookupFieldField": "",
      "PatRequiredTextField": "",
      "RaStateField": "Fail",
      "StatusField": "Complete",
      "TaskIDField": "328",
      "cgSigns_cgInspections_cgAttachmentsClass": [],
      "cgSigns_cgInspections_cgConditionCategoriesClass": [
        {
          "ParentOid": 1714378640,
          "Oid": 1942269938,
          "cgLastModifiedField": "2016-04-06T17:38:21-05:00",
          "ConditionCategoryField": "Background Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:21-05:00",
          "InactiveField": false,
          "IndexField": 63.81,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "3.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1714378640,
          "Oid": 26696928,
          "cgLastModifiedField": "2016-04-06T17:38:21-05:00",
          "ConditionCategoryField": "Legend Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:21-05:00",
          "InactiveField": false,
          "IndexField": 3.07,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "0.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1714378640,
          "Oid": 1696597266,
          "cgLastModifiedField": "2016-04-06T17:59:20-05:00",
          "ConditionCategoryField": "Sign",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:21-05:00",
          "InactiveField": false,
          "IndexField": 32.4,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "2",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        }
      ]
    }
    ],
    "_metadata": {
        "totalCount": 1,
        "limit": null,
        "offset": null
    }
  }
}

All Inspections ordered by Inspection Date for Sign with Oid 1298381004 with fields filter set to Inspection Date, Inspected OCI, and Ra State:

{
  "cgSigns_cgInspectionsClass": [
    {
      "Oid": 1181961726,
      "InspectionDateField": "2002-01-06T00:00:00-06:00",
      "InspectedOCIField": 39.26,
      "RaStateField": "Fail",
      "cgSigns_cgInspections_cgAttachmentsClass": [],
      "cgSigns_cgInspections_cgConditionCategoriesClass": [
        {
          "ParentOid": 1181961726,
          "Oid": 1197795148,
          "cgLastModifiedField": "2016-04-06T17:38:19-05:00",
          "ConditionCategoryField": "Background Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:19-05:00",
          "InactiveField": false,
          "IndexField": 70.79,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "4",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1181961726,
          "Oid": 1193670932,
          "cgLastModifiedField": "2016-04-06T17:38:19-05:00",
          "ConditionCategoryField": "Legend Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:19-05:00",
          "InactiveField": false,
          "IndexField": 4.56,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "0.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1181961726,
          "Oid": 1936502546,
          "cgLastModifiedField": "2016-04-06T17:59:20-05:00",
          "ConditionCategoryField": "Sign",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:19-05:00",
          "InactiveField": false,
          "IndexField": 42.44,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "2.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        }
      ]
    },
    {
      "Oid": 1675993421,
      "InspectionDateField": "2002-06-06T00:00:00-05:00",
      "InspectedOCIField": 49.65,
      "RaStateField": "Fail",
      "cgSigns_cgInspections_cgAttachmentsClass": [],
      "cgSigns_cgInspections_cgConditionCategoriesClass": [
        {
          "ParentOid": 1675993421,
          "Oid": 1280553811,
          "cgLastModifiedField": "2016-04-06T17:38:20-05:00",
          "ConditionCategoryField": "Background Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:20-05:00",
          "InactiveField": false,
          "IndexField": 70.79,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "4",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1675993421,
          "Oid": 26292986,
          "cgLastModifiedField": "2016-04-06T17:38:20-05:00",
          "ConditionCategoryField": "Legend Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:20-05:00",
          "InactiveField": false,
          "IndexField": 4.56,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "0.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1675993421,
          "Oid": 2095403814,
          "cgLastModifiedField": "2016-04-06T17:38:20-05:00",
          "ConditionCategoryField": "Sign",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:20-05:00",
          "InactiveField": false,
          "IndexField": 73.61,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "",
          "NotesField": "",
          "NotInspectedField": true,
          "ConditionCategoryField\\SortOrderField": 0
        }
      ]
    },
    {
      "Oid": 1791416647,
      "InspectionDateField": "2004-06-06T00:00:00-05:00",
      "InspectedOCIField": 52.05,
      "RaStateField": "Fail",
      "cgSigns_cgInspections_cgAttachmentsClass": [],
      "cgSigns_cgInspections_cgConditionCategoriesClass": [
        {
          "ParentOid": 1791416647,
          "Oid": 413655705,
          "cgLastModifiedField": "2016-04-06T17:38:20-05:00",
          "ConditionCategoryField": "Background Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:20-05:00",
          "InactiveField": false,
          "IndexField": 88.1,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "4.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1791416647,
          "Oid": 1174966391,
          "cgLastModifiedField": "2016-04-06T17:38:20-05:00",
          "ConditionCategoryField": "Legend Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:20-05:00",
          "InactiveField": false,
          "IndexField": 7.55,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "0.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1791416647,
          "Oid": 101264189,
          "cgLastModifiedField": "2016-04-06T17:59:20-05:00",
          "ConditionCategoryField": "Sign",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:20-05:00",
          "InactiveField": false,
          "IndexField": 60.5,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "3.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        }
      ]
    },
    {
      "Oid": 1714378640,
      "InspectionDateField": "2005-06-06T00:00:00-05:00",
      "InspectedOCIField": 33.09,
      "RaStateField": "Fail",
      "cgSigns_cgInspections_cgAttachmentsClass": [],
      "cgSigns_cgInspections_cgConditionCategoriesClass": [
        {
          "ParentOid": 1714378640,
          "Oid": 1942269938,
          "cgLastModifiedField": "2016-04-06T17:38:21-05:00",
          "ConditionCategoryField": "Background Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:21-05:00",
          "InactiveField": false,
          "IndexField": 63.81,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "3.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1714378640,
          "Oid": 26696928,
          "cgLastModifiedField": "2016-04-06T17:38:21-05:00",
          "ConditionCategoryField": "Legend Ra",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:21-05:00",
          "InactiveField": false,
          "IndexField": 3.07,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "0.5",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        },
        {
          "ParentOid": 1714378640,
          "Oid": 1696597266,
          "cgLastModifiedField": "2016-04-06T17:59:20-05:00",
          "ConditionCategoryField": "Sign",
          "ConditionDetailsField": "",
          "EnteredByField": "BackgroundDataExchanger",
          "EntryDateField": "2016-04-06T17:38:21-05:00",
          "InactiveField": false,
          "IndexField": 32.4,
          "LastModifiedByField": "BackgroundDataExchanger",
          "MeasuredValueField": "2",
          "NotesField": "",
          "NotInspectedField": false,
          "ConditionCategoryField\\SortOrderField": 0
        }
      ]
    }
  ],
  "_metadata": {
    "totalCount": 4,
    "limit": 1000,
    "offset": 0
  }
}

Get Multiple Sign records with fields filter set to Oid, CgProximity, and ID, sorting by CgProximity, and having a currentLocation of (42.5, -90.7):

{
    "cgSignsClass": [
        {
            "CgProximity": 535.5066254371676,
            "Oid": 1485334809,
            "IDField": "21"
        },
        {
            "CgProximity": 692.241480569641,
            "Oid": 85170152,
            "IDField": "95"
        },
        {
            "CgProximity": null,
            "Oid": 2081677170,
            "IDField": "35"
        }
    ],
    "_metadata": {
        "totalCount": 218,
        "limit": null,
        "offset": null
    }
}

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object containing a className property (that corresponds to the class name in the URL). The value of this property is an array whose contents may vary depending upon the request.
      • When selecting a list of records or a single record: The array contains objects that represent records of that class name type.
      • When the result was not found: The array is empty.
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL.
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a GET, /cgSignsClass/651592699/cgSigns_cgAttachmentsClass/2131404296 —There are more than three segments (in this example, /{className}/{id}/{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was entered in the URL.
      • Example: cgBlahClass/1234—cgBlahClass does not exist in the OMS database, so it is invalid.
    • Invalid URI path. {className} is not child to {different className}
      • The URL contains a bad relationship in classes.
      • Example: /cgSignsClass/12345/cgBridges_cgInspectionsClass —Signs does not have a child recordset of Bridge Inspections.
    • Unable to convert {id} to an oid
      • An invalid value was entered for an Oid in the URL.
      • Example: /cgSignsClass/AB1234 — Oids are numbers and cannot contain letters.
  • 403 Forbidden
    • User is invalid.
    • User does not have access to the specified request.
  • 404 Not Found
    • During a file get, the specified file and or directory is not valid.
    • Record cannot be found.
      • A record with the given oid cannot be found.
      • Example: /cgSignsClass/1234 —A Sign record with an oid of 1234 does not exist in the database.
  • 500 Internal Server Error
    • An error has occurred while processing the transaction. More details can be found in the Error log within OMS.

Get New (Initial Values)

  • Purpose: Retrieve a new, uncommitted record with all initial values populated.
  • Introduced: v8 - Summer 2015
  • HTTP Method: GET
  • URL:
    • https://yourserver.com/cartegraph/api/v1/classes/{className}/new
  • URL Parameters:
    • classNamerequired—Cartegraph class name (for example, cgTreesClass or cgTrees_cgInspectionsClass)
  • Optional Parameters:
    • parentOid —Oid of the parent record. Specify this for child records to populate initial values that depend on the parent record.
    • ignoreNullFields -  When set to true, any fields with a value of null or "" will not be returned.

      • Record returned may not include all fields

      • Minimizes response payload size

      • Defaults to false if not specified

Example Requests

Get a new Tree record excluding null fields:

GET https://yourserver.com/cartegraph/api/v1/classes/cgTreesClass/new?ignoreNullFields=true

Get a new Tree Inspection record:

GET https://yourserver.com/cartegraph/api/v1/classes/cgTrees_cgInspectionsClass/new

Get a new Tree Inspection record that is child to a specific Tree record:

GET https://yourserver.com/cartegraph/api/v1/classes/cgTrees_cgInspectionsClass/new?parentOid=123456

Example Responses

A new Tree record excluding null fields:

{
    "cgTreesClass": [
        {
            "Oid": 0,
            "CriticalityFactorField": 1,
            "IDField": "(AutoNumber)"
        }
    ]
}

A new Tree Inspection record:

{
    "cgTrees_cgInspectionsClass":
    [
        {
            "Oid": 0,
            "ParentOid": 0,
            "AppraisalMethodField": "",
            "AppraisedValueField": null,
            "cgLastModifiedField": null,
            "CircumferenceField": {
                "Amount": null,
                "Unit": "in"
            },
            "ConditionRatingField": null,
            "ContributionField": null,
            "DiameterField": {
                "Amount": null,
                "Unit": "in"
            },
            "EnteredByField": "",
            "EntryDateField": null,
            "FoliageandBudHealthField": null,
            "IDField": "(AutoNumber)",
            "InactiveField": false,
            "InspectedByField": "",
            "InspectedOCIField": null,
            "InspectedOCRField": "",
            "InspectionDateField": null,
            "LastModifiedByField": "",
            "LocationRatingField": null,
            "NotesField": "",
            "PlacementField": null,
            "RemovalandCleanupCostsField": 0,
            "RootHealthField": null,
            "RootStructureField": null,
            "ScaffoldBranchHealthField": null,
            "ScaffoldBranchStructureField": null,
            "SiteField": null,
            "SmallBranchandTwigHealthField": null,
            "StatusField": "Incomplete",
            "TaskIDField": "",
            "TrunkAreaField": {
                "Amount": null,
                "Unit": "in²"
            },
            "TrunkHealthField": null,
            "TrunkStructureField": null
        }
    ]
}

Get a new Tree Inspection record that is child to a specific Tree record:

{
    "cgTrees_cgInspectionsClass":
    [
        {
            "Oid": 0,
            "ParentOid": 123456,
            "AppraisalMethodField": "",
            "AppraisedValueField": null,
            "cgLastModifiedField": null,
            "CircumferenceField": {
                "Amount": null,
                "Unit": "cm"
            },
            "ConditionRatingField": null,
            "ContributionField": null,
            "DiameterField": {
                "Amount": null,
                "Unit": "cm"
            },
            "EnteredByField": "",
            "EntryDateField": null,
            "FoliageandBudHealthField": null,
            "IDField": "(AutoNumber)",
            "InactiveField": false,
            "InspectedByField": "",
            "InspectedOCIField": null,
            "InspectedOCRField": "",
            "InspectionDateField": null,
            "LastModifiedByField": "",
            "LocationRatingField": null,
            "NotesField": "",
            "PlacementField": null,
            "RemovalandCleanupCostsField": 0,
            "RootHealthField": null,
            "RootStructureField": null,
            "ScaffoldBranchHealthField": null,
            "ScaffoldBranchStructureField": null,
            "SiteField": null,
            "SmallBranchandTwigHealthField": null,
            "StatusField": "Incomplete",
            "TaskIDField": "",
            "TrunkAreaField": {
                "Amount": null,
                "Unit": "cm²"
            },
            "TrunkHealthField": null,
            "TrunkStructureField": null
            "cgTrees_cgInspections_cgConditionCategoriesClass": [
              {
                "Oid": 0,
                "ParentOid": 0,
                "cgLastModifiedField": null,
                "ConditionCategoryField": "Foliage",
                "ConditionDetailsField": "",
                "EnteredByField": "",
                "EntryDateField": null,
                "InactiveField": false,
                "IndexField": null,
                "LastModifiedByField": "",
                "MeasuredValueField": "",
                "NotesField": "",
                "NotInspectedField": false,
                "ConditionCategoryField\\SortOrderField": 0
              },
              {
                "Oid": 0,
                "ParentOid": 0,
                "cgLastModifiedField": null,
                "ConditionCategoryField": "Trunk",
                "ConditionDetailsField": "",
                "EnteredByField": "",
                "EntryDateField": null,
                "InactiveField": false,
                "IndexField": null,
                "LastModifiedByField": "",
                "MeasuredValueField": "",
                "NotesField": "",
                "NotInspectedField": false,
                "ConditionCategoryField\\SortOrderField": 0
              }
            ]
        }
    ]
}

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object containing a className property (that corresponds to the class name in the URL). The value of this property is an array containing an object that represents a single record of that class name type.
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name in the URL.
    • {className} is not a valid class name
      • An invalid class name was entered in the URL.
      • Example: cgBlahClass/new — cgBlahClass does not exist in the OMS database, so it is invalid.
    • Parent oid cannot be specified for a top level class
      • The URL contains a top level class, but a parentOid parameter was passed up
      • Example: /cgSignsClass/new/12345 — Signs does not have a parent class.
  • 403 Forbidden
    • The user is invalid.
    • The user does not have access to the specified request.
  • 404 Not Found
    • During a file get, the specified file and or directory is not valid.
    • The specified record was not found.
  • 500 Internal Server Error
    • An error has occurred while processing the transaction. More details can be found in the Error log within OMS.

Create a Record (POST)

  • Purpose: Create one or more records for a recordset. May include child records at the same time.
  • HTTP Method: POST
  • URL:
    • https://yourserver.com/cartegraph/api/v1/classes/{className}
    • https://yourserver.com/cartegraph/api/v1/classes/{className}/{id}/{childClassName}
  • URL Parameters:
    • classNamerequired—Cartegraph class name (for example, cgSignsClass)
    • id —Oid of the record
    • childClassName —Cartegraph class name (for example, cgSigns_cgInspectionsClass)
  • Optional Parameters:
    • ignoreNullFields -  When set to true, any fields with a value of null or "" will not be returned.

      • Records returned may not include all fields

      • Minimizes response payload size

      • Defaults to false if not specified

Notes on setting System Calculated Fields: Generally, fields that are marked System and Read-Only are populated by OMS. Although it is possible to set values in these fields on PUT and POST API calls without getting an error, the system will likely overwrite the provided value with the system calculated one.

Example Requests

Create a Sign with an Address Number of 1765 and Id of Sign-50:

POST https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass
{
    "cgSignsClass":[
        {
            "IDField":"Sign-50",
            "AddressNumberField":1765
        }
    ]
}

Create two Signs and exclude null fields from the response:

POST https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass?ignoreNullFields=true
{
    "cgSignsClass":[
        {
            "IDField":"Sign-51",
            "AddressNumberField":1765
        },
        {
          "IDField":"Sign-52",
          "AddressNumberField":1766,
          "InactiveField":true
        }
    ]
}

Create a Bridge Condition Category and add an Impact (child record) to it:

POST https://yourserver.com/cartegraph/api/v1/classes/cgBridgeConditionCategoriesClass
{
    "cgBridgeConditionCategoriesClass": [
        {
            "ConditionCategoryField": "Appearance",
            "WeightField": 1,
            "cgBridgeConditionCategories_cgImpactsClass": [
                {
                    "ActivityField": "Clean",
                    "ImpactField": {
                      "Amount": 35,
                      "Unit": "Relative"
                    }
                }
            ]
        }
    ]
}

Create a Pavement Inspection without child records and without an associated Task:

POST https://yourserver.com/cartegraph/api/v1/classes/cgPavementClass/1244406749/cgPavement_cgInspectionsClass
{
    "cgPavement_cgInspectionsClass": [
        {
            "InspectedByField": "100",
            "InspectionDateField": "2014-03-01",
            "NotesField": "My Inspection notes.",
            "StatusField": "Incomplete"
        }
    ]
}

Create a completed Pavement Inspection with child records and that is associated to an existing Task:

POST https://yourserver.com/cartegraph/api/v1/classes/cgPavementClass/1244406749/cgPavement_cgInspectionsClass
{
    "cgPavement_cgInspectionsClass": [
        {
            "TaskIDField": "2219",
            "InspectedByField": "100",
            "InspectionDateField": "2014-03-01",
            "NotesField": "My Inspection notes.",
            "StatusField": "Complete",
            "cgPavement_cgInspections_cgConditionCategoriesClass": [
                {
                    "ConditionCategoryField": "PCI"
                },
                {
                    "ConditionCategoryField": "Ride",
                    "IndexField": 80
                }
            ],
            "cgPavement_cgInspections_cgSamplesClass": [
                {
                   "SampleTypeField": "Additional",
                   "SampleFromField": {
                      "Amount": 100,
                      "Unit": "ft"
                    },
                    "SampleToField": {
                      "Amount": 300,
                      "Unit": "ft"
                    },
                    "cgPavement_cgInspections_cgSamples_cgDistressesClass": [
                        {
                            "DistressField": "PCC Blowup Buckling",
                            "ExtentField": 10,
                            "SeverityField": "Low"
                        },
                        {
                            "DistressField": "PCC Corner Break",
                            "ExtentField": 5,
                            "SeverityField": "Low"
                        }
                    ]
                },
                {
                   "SampleTypeField": "Additional",
                   "SampleFromField": {
                      "Amount": 500,
                      "Unit": "ft"
                    },
                    "SampleToField": {
                      "Amount": 700,
                      "Unit": "ft"
                    },
                    "NoDistressesFoundField": true
                }
            ]
        }
    ]
}

Example Responses

One Sign with an Address Number of 1765 and Id of Sign-50 created:

{
  "cgSignsClass": [
    {
      "IDField": "Sign-50",
      "AddressNumberField": 1765,
      "Oid": 242283165,
      "CgShape": null,
      "ActBeforeField": null,
      "BackingMaterialField": "",
      "BridgeField": "",
      "cgLastModifiedField": "2014-03-06T16:42:57-06:00",
      "CityField": "",
      "ConditionGroupField": "",
      "CountyField": "",
      "CurrentInspectionIDField": "",
      "EnteredByField": "Jessica",
      "EntryDateField": "2014-03-06T16:42:57-06:00",
      "EstimatedBackgroundRaField": null,
      "EstimatedCCIField": null,
      "EstimatedCCRField": "",
      "EstimatedContrastRatioField": null,
      "EstimatedLegendRaField": null,
      "EstimatedOCIField": null,
      "EstimatedOCRField": "",
      "EstimatedRaStateField": "",
      "HeightField": {
        "Amount": null,
        "Unit": "in"
      },
      "IlluminationField": "",
      "InactiveField": false,
      "InstalledField": null,
      "JurisdictionField": "",
      "LastModifiedByField": "Jessica",
      "LocationDescriptionField": "",
      "LocatorAddressNumberField": "",
      "LocatorCityField": "",
      "LocatorStreetField": "",
      "MaintenanceMethodField": "",
      "MountingHeightField": {
        "Amount": null,
        "Unit": "in"
      },
      "MUTCDCodeField": "",
      "NotesField": "",
      "OffsetField": {
        "Amount": null,
        "Unit": "ft"
      },
      "PositionField": "",
      "PredictionGroupField": "",
      "PrimaryAttachmentField": "",
      "ReflectorizationField": "",
      "ReplacedField": null,
      "RetiredField": null,
      "SheetingMaterialField": "",
      "SignDirectionField": "",
      "SpeedZoneField": {
        "Amount": null,
        "Unit": "mph"
      },
      "StateField": "",
      "StreetField": "",
      "SupportField": "",
      "TrailField": "",
      "VariableTextField": "",
      "WidthField": {
        "Amount": null,
        "Unit": "in"
      }
    }
  ]
}

Two Signs created and excluded null fields from the response:

{
    "cgSignsClass": [
        {
          "IDField": "Sign-51",
          "AddressNumberField": 1765,
          "Oid": 114964549,
          "cgLastModifiedField": "2014-03-06T16:40:01-06:00",
          "EnteredByField": "Jessica",
          "EntryDateField": "2014-03-06T16:40:01-06:00",
          "HeightField": {
            "Amount": null,
            "Unit": "in"
          },
          "InactiveField": false,
          "LastModifiedByField": "Jessica",
          "MountingHeightField": {
            "Amount": null,
            "Unit": "in"
          },
          "OffsetField": {
            "Amount": null,
            "Unit": "ft"
          },
          "SpeedZoneField": {
            "Amount": null,
            "Unit": "mph"
          },
          "WidthField": {
            "Amount": null,
            "Unit": "in"
          }
        },
        {
          "IDField": "Sign-52",
          "AddressNumberField": 1766,
          "InactiveField": true,
          "Oid": 447575113,
          "cgLastModifiedField": "2014-03-06T16:40:01-06:00",
          "EnteredByField": "Jessica",
          "EntryDateField": "2014-03-06T16:40:01-06:00",
          "HeightField": {
            "Amount": null,
            "Unit": "in"
          },
          "LastModifiedByField": "Jessica",
          "MountingHeightField": {
            "Amount": null,
            "Unit": "in"
          },
          "OffsetField": {
            "Amount": null,
            "Unit": "ft"
          },
          "SpeedZoneField": {
            "Amount": null,
            "Unit": "mph"
          },
          "WidthField": {
            "Amount": null,
            "Unit": "in"
          }
        }
    ]
}

Bridge Condition Category and an Impact (child record) created:

{
  "cgBridgeConditionCategoriesClass": [
    {
      "ConditionCategoryField": "Appearance",
      "WeightField": 1,
      "cgBridgeConditionCategories_cgImpactsClass": [
        {
          "ActivityField": "Clean",
          "ImpactField": {
            "Amount": 35,
            "Unit": "Relative"
          },
          "ParentOid": 1463012989,
          "Oid": 461749927,
          "cgLastModifiedField": "2014-03-06T16:51:12-06:00",
          "EnteredByField": "Jessica",
          "EntryDateField": "2014-03-06T16:51:12-06:00",
          "InactiveField": false,
          "LastModifiedByField": "Jessica"
        }
      ],
      "Oid": 1463012989,
      "cgLastModifiedField": "2014-03-06T16:51:09-06:00",
      "EnteredByField": "Jessica",
      "EntryDateField": "2014-03-06T16:51:09-06:00",
      "FilterTextField": "",
      "FilterXMLField": "",
      "InactiveField": false,
      "LastModifiedByField": "Jessica"
    }
  ]
}

Pavement Inspection without child records and without an associated Task:

{
    "cgPavement_cgInspectionsClass": [
        {
            "InspectedByField": "100",
            "InspectionDateField": "2014-03-01T00:00:00-06:00",
            "NotesField": "My Inspection notes.",
            "StatusField": "Incomplete",
            "Oid": 360538339,
            "ParentOid": 1244406749,
            "cgLastModifiedField": "2014-03-25T14:55:25-05:00",
            "EnteredByField": "kevin",
            "EntryDateField": "2014-03-25T14:55:25-05:00",
            "IDField": "104",
            "InactiveField": false,
            "InspectedOCIField": null,
            "InspectedOCRField": "",
            "LastModifiedByField": "kevin",
            "TaskIDField": "2001",
            "TypeField": "Network-Level"
        }
    ]
}

Notes on Creating Inspections

  • In this example, since a TaskID wasn't provided, the system automatically created a Task (with an autonumbered TaskID) associated witho the Pavement Asset that is the parent record of the Inspection. If a TaskID is provided and a Task with that TaskID does not exist in the database, the automatically created Task will use the provided TaskID instead of autonumbering the TaskID. If the provided TaskID already exists in the database and the Task can be associated with the Inspection being created, the system will use the existing Task and not create a new Task.
  • For a Task that the system automatically creates when creating an Inspection, the Task will have its Activity field set to "Inspect" and will have either its Start Date Actual or Start Date Estimated field set to the Inspection's Inspection Date field. (If the Inspection Date is before today, Start Date Actual gets set; otherwise, Start Date Estimated gets set.) If the Inspection being created has its Status set to "Complete," the automatically created Task will have its Stop Date Actual field set to the Inspection's Inspection Date field and have its Status field set to "Completed."
  • If the Inspection being created has its Status set to "Complete" and a Condition Category does not have a value for its Index field, Rating field, and is not marked as "Not Inspected," the Condition Category will have its Not Inspected field set to true so that the Inspection can be completed. Condition Categories calculated by the system such as PCI, Background RA, and Legend RA will not be marked as NI if an index could not be calculated and the inspection can still be marked as completed.

Completed Pavement Inspection with child records and that is associated with an existing Task:

{
    "cgPavement_cgInspectionsClass": [
        {
            "TaskIDField": "2219",
            "InspectedByField": "100",
            "InspectionDateField": "2014-03-01T00:00:00-06:00",
            "NotesField": "My Inspection notes.",
            "StatusField": "Complete",
            "cgPavement_cgInspections_cgConditionCategoriesClass": [
                {
                    "ConditionCategoryField": "PCI",
                    "Oid": 809421339,
                    "ParentOid": 505062566,
                    "cgLastModifiedField": "2014-03-25T16:10:33-05:00",
                    "EnteredByField": "kevin",
                    "EntryDateField": "2014-03-25T16:10:33-05:00",
                    "InactiveField": false,
                    "IndexField": 18.9,
                    "LastModifiedByField": "kevin",
                    "NotesField": "",
                    "NotInspectedField": false
                },
                {
                    "ConditionCategoryField": "Ride",
                    "IndexField": 80,
                    "Oid": 529666470,
                    "ParentOid": 505062566,
                    "cgLastModifiedField": "2014-03-25T16:10:33-05:00",
                    "EnteredByField": "kevin",
                    "EntryDateField": "2014-03-25T16:10:33-05:00",
                    "InactiveField": false,
                    "LastModifiedByField": "kevin",
                    "NotesField": "",
                    "NotInspectedField": false
                }
            ],
            "cgPavement_cgInspections_cgSamplesClass": [
                {
                    "SampleFromField": {
                      "Amount": 100,
                      "Unit": "ft"
                    },
                    "SampleToField": {
                      "Amount": 300,
                      "Unit": "ft"
                    },
                    "cgPavement_cgInspections_cgSamples_cgDistressesClass": [
                        {
                            "DistressField": "PCC Blowup Buckling",
                            "ExtentField": 10,
                            "SeverityField": "Low",
                            "Oid": 162041537,
                            "ParentOid": 0,
                            "cgLastModifiedField": "2014-03-25T16:10:33-05:00",
                            "EnteredByField": "kevin",
                            "EntryDateField": "2014-03-25T16:10:33-05:00",
                            "IDField": "136",
                            "InactiveField": false,
                            "LastModifiedByField": "kevin"
                        },
                        {
                            "DistressField": "PCC Corner Break",
                            "ExtentField": 5,
                            "SeverityField": "Low",
                            "Oid": 775320540,
                            "ParentOid": 0,
                            "cgLastModifiedField": "2014-03-25T16:10:34-05:00",
                            "EnteredByField": "kevin",
                            "EntryDateField": "2014-03-25T16:10:34-05:00",
                            "IDField": "137",
                            "InactiveField": false,
                            "LastModifiedByField": "kevin"
                        }
                    ],
                    "Oid": 274539731,
                    "ParentOid": 0,
                    "cgLastModifiedField": "2014-03-25T16:10:33-05:00",
                    "EnteredByField": "kevin",
                    "EntryDateField": "2014-03-25T16:10:33-05:00",
                    "IDField": "136",
                    "InactiveField": false,
                    "LastModifiedByField": "kevin",
                    "NoDistressesFoundField": false,
                    "SampleTypeField": "Additional"
                },
                {
                   "SampleFromField": {
                      "Amount": 500,
                      "Unit": "ft"
                    },
                    "SampleToField": {
                      "Amount": 700,
                      "Unit": "ft"
                    },
                    "NoDistressesFoundField": true,
                    "Oid": 800245523,
                    "ParentOid": 0,
                    "cgLastModifiedField": "2014-03-25T16:10:34-05:00",
                    "EnteredByField": "kevin",
                    "EntryDateField": "2014-03-25T16:10:34-05:00",
                    "IDField": "137",
                    "InactiveField": false,
                    "LastModifiedByField": "kevin",
                    "SampleTypeField": "Additional"
                }
            ],
            "Oid": 505062566,
            "ParentOid": 1244406749,
            "cgLastModifiedField": "2014-03-25T16:10:33-05:00",
            "EnteredByField": "kevin",
            "EntryDateField": "2014-03-25T16:10:32-05:00",
            "IDField": "120",
            "InactiveField": false,
            "InspectedOCIField": 31.12,
            "InspectedOCRField": "Fair",
            "LastModifiedByField": "kevin",
            "TypeField": "Network-Level"
        }
    ]
}

Note: Refer to the Notes on Creating Inspections in the prior example. In this example, a TaskID of an existing Task was provided and therefore a new Task was not created. Although the Inspection being created has its Status set to "Complete," since the Task was an existing Task that was not automatically created, the Task does not have its Status field set to "Completed."

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object containing a className property (that corresponds to the class name in the URL). The value of this property contains the records that were sent in the message body and created.
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL.
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a POST, /cgSignsClass/651592699/cgSigns_cgAttachmentsClass/2131404296 —There are more than three segments (in this example, /{className}/{id}/{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was entered in the URL.
      • Example: cgBlahClass/1234 —cgBlahClass does not exist in the OMS database so it is invalid.
    • Invalid URI path. {className} is not child to {different className}
      • The URL contains a bad relationship in classes.
      • Example: /cgSignsClass/12345/cgBridges_cgInspectionsClass —Signs does not have a child recordset of Bridge Inspections.
    • The class names do not match '{className}'.
      • URL class name does not match the top-level class in the message body JSON.
    • Unable to convert {id} to an oid
      • An invalid value was entered for an Oid in the URL.
      • Example: /cgSignsClass/AB1234 — Oids are numbers and cannot contain letters.
    • Cannot specify the oid in the URL for a create.
      • The URL has on Oid at the end. This is not allowed for a create. It is OK to have Oid in the JSON but not at the end of the URL.
  • 403 Forbidden
    • The System Administrator prevented your access to this feature. Ask the System Administrator for help with access. Security Role assigned to the User Account does not have permissions to the Create action for {className}.
  • 500 Internal Server Error
    • An error occurred on the server while trying to create.
      • Example: ID Sign-1 already exists. Enter a unique value.
      • {className} has an invalid format.
        • In the JSON message body, the value of a className property (for example, cgSignsClass) must be an array — even if you are only working with a single record. In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the Example Requests section in order to view examples of properly formatted JSON data.
      • A parent oid is missing.
        • There is no parent oid in the URL or top-level JSON.
      • The parent oids do not match.
        • The URL's parent Oid is not equal to the JSON's parent Oid.
    • If a 500 error is thrown by a POST, none of the records in the call will save. After the issue is fixed, the entire call can be run again.

Update a record (PUT)

  • Purpose: Update one or more records for a recordset. May include child records at the same time.
  • HTTP Method: PUT
  • URL:
    • https://yourserver.com/cartegraph/api/v1/classes/{className}
    • https://yourserver.com/cartegraph/api/v1/classes/{className}/{id}
    • https://yourserver.com/cartegraph/api/v1/classes/{className}/{id}/{childClassName}
  • URL Parameters:
    • className - required - Cartegraph class name (for example, cgSignsClass)
    • id - Oid of the record
    • childClassName - Cartegraph class name (for example, cgSigns_cgInspectionsClass)
  • Optional Parameters:
    • ignoreNullFields -  When set to true, any fields with a value of null or "" will not be returned.

      • Records returned may not include all fields

      • Minimizes response payload size

      • Defaults to false if not specified

Notes on setting System Calculated Fields: Generally, fields that are marked System and Read-Only are populated by OMS. Although it is possible to set values in these fields on PUT and POST API calls without getting an error, the system will likely overwrite the provided value with the system calculated one.

Notes on Oid: When specifying the Oid property to access a specific record, case matters. In other words, do not specify the property as oid instead of Oid. Also, the Oid property value cannot be updated once the record has been saved.

Example Requests

Update Sign 242283165 setting the Address field to 4771:

PUT https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass/242283165
{
    "cgSignsClass":[
        {
            "AddressNumberField":4771
        }
    ]
}

Update multiple Signs and exclude null fields from the response:

PUT https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass?ignoreNullFields=true
{
    "cgSignsClass":[
        {
            "Oid": 114964549,
            "AddressNumberField":9999
        },
        {
            "Oid": 447575113,
            "AddressNumberField":8888
        }
    ]
}

Update a Bridge Condition Category's Weight and one of its Impacts (child record):

PUT https://yourserver.com/cartegraph/api/v1/classes/cgBridgeConditionCategoriesClass/1463012989
{
  "cgBridgeConditionCategoriesClass": [
    {
        "WeightField": 2,
        "cgBridgeConditionCategories_cgImpactsClass": [
          {
             "Oid": 461749927,
             "ImpactField": {
                "Amount": 25,
                "Unit": "Relative"
             }
          }
        ]
    }
 ]
}

Update an Incomplete Pavement Inspection to set its Status to Complete:

PUT https://yourserver.com/cartegraph/api/v1/classes/cgPavement_cgInspectionsClass/360538339
{
    "cgPavement_cgInspectionsClass": [
        {
            "StatusField": "Complete",
            "cgPavement_cgInspections_cgSamplesClass": [
                {
                   "SampleFromField": {
                      "Amount": 500,
                      "Unit": "ft"
                    },
                    "SampleToField": {
                      "Amount": 700,
                      "Unit": "ft"
                    },
                    "NoDistressesFoundField": true,
                    "SampleTypeField": "Single"
                }
            ]
        }
    ]
}

Example Responses

Updated Sign 242283165 with the Address field set to 4771:

{
    "cgSignsClass": [
    {
      "AddressNumberField": 4771,
      "Oid": 242283165,
      "CgShape": null,
      "ActBeforeField": null,
      "BackingMaterialField": "",
      "BridgeField": "",
      "cgLastModifiedField": "2014-03-07T09:11:49-06:00",
      "CityField": "",
      "ConditionGroupField": "",
      "CountyField": "",
      "CurrentInspectionIDField": "",
      "EnteredByField": "Jessica",
      "EntryDateField": "2014-03-06T16:42:57-06:00",
      "EstimatedBackgroundRaField": null,
      "EstimatedCCIField": null,
      "EstimatedCCRField": "",
      "EstimatedContrastRatioField": null,
      "EstimatedLegendRaField": null,
      "EstimatedOCIField": null,
      "EstimatedOCRField": "",
      "EstimatedRaStateField": "",
      "HeightField": {
        "Amount": null,
        "Unit": "in"
      },
      "IDField": "Sign-50",
      "IlluminationField": "",
      "InactiveField": false,
      "InstalledField": null,
      "JurisdictionField": "",
      "LastModifiedByField": "Jessica",
      "LocationDescriptionField": "",
      "LocatorAddressNumberField": "",
      "LocatorCityField": "",
      "LocatorStreetField": "",
      "MaintenanceMethodField": "",
      "MountingHeightField": {
        "Amount": null,
        "Unit": "in"
      },
      "MUTCDCodeField": "",
      "NotesField": "",
      "OffsetField": {
        "Amount": null,
        "Unit": "ft"
      },
      "PositionField": "",
      "PredictionGroupField": "",
      "PrimaryAttachmentField": "",
      "ReflectorizationField": "",
      "ReplacedField": null,
      "RetiredField": null,
      "SheetingMaterialField": "",
      "SignDirectionField": "",
      "SpeedZoneField": {
        "Amount": null,
        "Unit": "mph"
      },
      "StateField": "",
      "StreetField": "",
      "SupportField": "",
      "TrailField": "",
      "VariableTextField": "",
      "WidthField": {
        "Amount": null,
        "Unit": "in"
      }
    }
  ]
}

Updated multiple Signs and excluded null fields from the response:

{
  "cgSignsClass": [
    {
      "Oid": 114964549,
      "AddressNumberField": 9999,
      "cgLastModifiedField": "2014-03-07T09:15:21-06:00",
      "EnteredByField": "Jessica",
      "EntryDateField": "2014-03-06T16:40:01-06:00",
      "HeightField": {
        "Amount": null,
        "Unit": "in"
      },
      "IDField": "Sign-51",
      "InactiveField": false,
      "LastModifiedByField": "Jessica",
      "MountingHeightField": {
        "Amount": null,
        "Unit": "in"
      },
      "OffsetField": {
        "Amount": null,
        "Unit": "ft"
      },
      "SpeedZoneField": {
        "Amount": null,
        "Unit": "mph"
      },
      "WidthField": {
        "Amount": null,
        "Unit": "in"
      }
    },
    {
      "Oid": 447575113,
      "AddressNumberField": 8888,
      "cgLastModifiedField": "2014-03-07T09:15:21-06:00",
      "EnteredByField": "Jessica",
      "EntryDateField": "2014-03-06T16:40:01-06:00",
      "HeightField": {
        "Amount": null,
        "Unit": "in"
      },
      "IDField": "Sign-52",
      "InactiveField": true,
      "LastModifiedByField": "Jessica",
      "MountingHeightField": {
        "Amount": null,
        "Unit": "in"
      },
      "OffsetField": {
        "Amount": null,
        "Unit": "ft"
      },
      "SpeedZoneField": {
        "Amount": null,
        "Unit": "mph"
      },
      "WidthField": {
        "Amount": null,
        "Unit": "in"
      }
    }
  ]
}

Updated a Bridge Condition Category's Weight and one of its Impacts (child record):

{
  "cgBridgeConditionCategoriesClass": [
    {
      "WeightField": 2,
      "cgBridgeConditionCategories_cgImpactsClass": [
        {
          "ParentOid": 1463012989,
          "Oid": 461749927,
          "ImpactField": {
            "Amount": 25,
            "Unit": "Relative"
          },
          "ActivityField": "Clean",
          "cgLastModifiedField": "2014-03-06T17:00:16-06:00",
          "EnteredByField": "Jessica",
          "EntryDateField": "2014-03-06T16:51:12-06:00",
          "InactiveField": false,
          "LastModifiedByField": "Jessica"
        }
      ],
      "Oid": 1463012989,
      "cgLastModifiedField": "2014-03-06T17:00:15-06:00",
      "ConditionCategoryField": "Appearance",
      "EnteredByField": "Jessica",
      "EntryDateField": "2014-03-06T16:51:09-06:00",
      "FilterTextField": "",
      "FilterXMLField": "",
      "InactiveField": false,
      "LastModifiedByField": "Jessica"
    }
  ]
}

Updated Incomplete Pavement Inspection to set its Status to Complete:

{
    "cgPavement_cgInspectionsClass": [
        {
            "StatusField": "Complete",
            "cgPavement_cgInspections_cgSamplesClass": [
                {
                   "SampleFromField": {
                      "Amount": 500,
                      "Unit": "ft"
                    },
                    "SampleToField": {
                      "Amount": 700,
                      "Unit": "ft"
                    },
                    "NoDistressesFoundField": true,
                    "Oid": 1699887784,
                    "ParentOid": 0,
                    "cgLastModifiedField": "2014-03-26T11:07:18-05:00",
                    "EnteredByField": "kevin",
                    "EntryDateField": "2014-03-26T11:07:18-05:00",
                    "IDField": "152",
                    "InactiveField": false,
                    "LastModifiedByField": "kevin",
                    "SampleTypeField": "Single"
                }
            ],
            "Oid": 926528324,
            "ParentOid": 1244406749,
            "cgLastModifiedField": "2014-03-26T11:07:17-05:00",
            "EnteredByField": "kevin",
            "EntryDateField": "2014-03-26T11:06:07-05:00",
            "IDField": "130",
            "InactiveField": false,
            "InspectedByField": "100",
            "InspectedOCIField": 10,
            "InspectedOCRField": "Poor",
            "InspectionDateField": "2014-03-01T00:00:00-06:00",
            "LastModifiedByField": "kevin",
            "NotesField": "My Inspection notes.",
            "TaskIDField": "989995060",
            "TypeField": "Network-Level"
        }
    ]
}

  • Notes on Updating Inspections: If the Inspection being updated has its Status set to "Complete" and a Condition Category does not have a value for its Index field, Rating field, and is not marked as "Not Inspected," the Condition Category will have its Not Inspected field set to true so that the Inspection can be completed. However, Condition Categories calculated by the system such as PCI, Background RA, and Legend RA will not be marked as NI if an index could not be calculated and the inspection can still be marked as completed. In this example, there is sufficient Sample/Distress data to calculate the "PCI" Condition Category. Other Condition Categories (such as "Ride") will have been marked as "Not Inspected."

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object containing a className property (that corresponds to the class name in the URL). The value of this property contains the records that were sent in the message body and updated.
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL.
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a PUT, /cgSignsClass/651592699/cgSigns_cgAttachmentsClass/2131404296 —There are more than three segments (in this example, /{className}/{id}/{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was entered in the URL.
      • Example: cgBlahClass/1234 -- cgBlahClass does not exist in the OMS database so it is invalid.
    • Invalid URI path. {className} is not child to {different className}
      • The URL contains a bad relationship in classes.
      • Example: /cgSignsClass/12345/cgBridges_cgInspectionsClass —Signs does not have a child recordset of Bridge Inspections.
    • "The class names do not match {className}."
      • URL class name does not match the top-level classes in the message body JSON.
    • Unable to convert {id} to an oid
      • An invalid value was entered for an Oid in the URL.
      • Example: /cgSignsClass/AB1234 -- Oids are numbers and cannot contain letters.
  • 403 Forbidden
    • "The System Administrator prevented your access to this feature. Ask the System Administrator for help with access. Security Role assigned to the User Account does not have permissions to the Update action for {className}."
  • 500 Internal Server Error
    • An error occurred on the server while trying to update.
      • Example: "'Dubuque' is not in the list of Cities."
      • {className} has an invalid format.
        • In the JSON message body, the value of a className property (for example, cgSignsClass) must be an array—ven if you are only working with a single record. In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the Example Requests section in order to view examples of properly formatted JSON data.
      • Cannot specify the oid in the URL when updating multiple records.
        • The URL has on Oid at the end. This is not allowed when updating multiple records. Instead, specify the Oid in the JSON.
      • Oid is required for all records being updated.
        • This message is given when an Oid is missing in the URL or JSON for the top-level JSON class.
      • The oids do not match {oid}.
        • There is only one record being updating and the URL's Oid is not equal to the JSON's Oid.
    • If a 500 error is thrown by a PUT, none of the records in the call will save. After the issue is fixed, the entire call can be run again.

Delete a record (DELETE)

  • Purpose: Delete one or more records for a recordset using a filter.
  • HTTP Method: DELETE
  • URL:
    • https://yourserver.com/cartegraph/api/v1/classes/{className}
    • https://yourserver.com/cartegraph/api/v1/classes/{className}/{id}
  • URL Parameters:
    • className - required - Cartegraph class name (for example, cgSignsClass)
    • id - Oid of the record
  • Optional Parameters:
    • filter - Filter to apply to the delete
      • Use when deleting a collection of items rather than an individual record
      • Example: "([MUTCDCode\Classification] is equal to "Regulatory")"

Example Requests

Delete Sign with Oid 123:

https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass/123

Delete Attachment with an Oid of 456:

https://yourserver.com/cartegraph/api/v1/classes/cgSigns_cgAttachmentsClass/456

Delete all Regulatory Signs:

https://yourserver.com/cartegraph/api/v1/classes/cgSignsClass?filter=(([MUTCDCode\Classification] is equal to "Regulatory"))

Response

Success

A 200 OK status code is returned on any successful deletion. The object returned will contain the number of records deleted. Note that this count only includes records of the type specified in the URL; the count does not include child records that also get deleted during the process.

{
    "DeletedRecordCount": 1
}

Exclusions

Inspections and Inspection\Samples cannot be directly deleted. Attempting to do so using the REST API will result in an error. You must instead delete the associated Task if you would like to delete Inspections or Samples. However, distresses can be deleted through the REST API.

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body may contain any of the following depending on the request:
      • When a successful deletion occurs, this code will be returned.
      • When a filter is applied to a collection to be deleted but there are no records that apply to this filter, a 200 OK code will be returned with a DeletedRecordCount of 0.
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL.
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a DELETE, /cgSignsClass/651592699/cgSigns_cgAttachmentsClass/2131404296 —There are more than three segments (in this example, /{className}/{id}/{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was in the URL.
      • Example: cgBlahClass/1234 -- cgBlahClass does not exist in the OMS database so it is invalid.
    • Invalid URI path. {className} is not child to {different className}
      • The URL contains a bad relationship in classes.
      • Example: /cgSignsClass/12345/cgBridges_cgInspectionsClass —Signs does not have a child recordset of Bridge Inspections.
    • Unable to convert {id} to an oid
      • An invalid value for an Oid was in the URL.
      • Example: /cgSignsClassB1234—Oids are numbers and cannot contain letters.
  • 403 Forbidden
    • The System Administrator prevented your access to this feature. Ask the System Administrator for help with access. Security Role assigned to the User Account does not have permissions to the Delete action for {className}.
  • 500 Internal Server Error
    • An error occurred on the server while trying to delete
      • Example: "Record cannot be found. Ask your System Administrator for help. Cannot find Signs record with OID = 123"
      • An Oid or Filter is required for record deletion.
        • To prevent users from accidentally deleting all of the records for a particular recordset, we require an Oid for a single delete or a filter for a multiple record deletion in order to process the request.
      • Cannot include a filter when an individual oid is specified
        • This message is given when an Oid is specified in the URL and a filter is included. This results in an ambiguous command. Should I use the Oid or the filter? What if they are different?
      • Cannot delete the inspection. Delete the associated Task to delete the inspection.
        • To remain consistent with the OMS UI functionality, an inspection cannot be directly deleted. The user must delete the associated Task which will in turn delete the inspection.
      • Cannot delete sample. Delete the associated Inspection Task to delete the sample.
        • To remain consistent with the OMS UI functionality, an Inspection Sample cannot be directly deleted. The user must delete the associated Task which will in turn delete the inspection and its Samples.

Enhanced Error Responses for POST and PUT

Beginning with the v11 - Summer 2016 release, the Business Object Create a Record (POST) and Update a record (PUT) methods have been enhanced with improved error reporting for validating the records you're trying to create or update.

Traditional Error Responses
For example, let's say you were trying to create two Tasks that both could not be saved due to validation of the records. The first Task has a Street that does not exist. The second Task has a City that does not exist and is missing an Activity—a required field.

The request body might look like this:

{
    "cgTasksClass": [
        {
            "ActivityField": "Maintain",
            "StreetField": "Some street that does not exist"
        },
        {
            "CityField": "Some city that does not exist"
        }
    ]
}


The response body would contain only a Message property whose value was the first error encountered—the Street that does not exist in the first Task:

{
    "Message": "'Some street that does not exist' is not in the list of Streets."
}


The error response left some things to be desired.

  • It wasn't clear which field the error was associated with.
  • It wasn't clear which record the error was associated with.
  • Only one error was reported when there may have been multiple errors across multiple records.

The introduction of enhanced error responses addresses these shortcomings.

Enhanced Error Responses

You can now optionally provide the new API-specific GUID property for the records you're trying to create or update in order to uniquely identify the record in the enhanced error response. The GUID field is a string that should be unique to the request whose value or format is up to your discretion.

Revisiting our Task creation example, the request body might now look like this:

{
    "cgTasksClass": [
        {
            "GUID": "12345",
            "ActivityField": "Maintain",
            "StreetField": "Some street that does not exist"
        },
        {
            "GUID": "67890",
            "CityField": "Some city that does not exist"
        }
    ]
}

The response body might then look like this:

{
    "Message": "'Some street that does not exist' is not in the list of Streets.",
    "Errors": [
        {
            "GUID": "12345",
            "FieldName": "StreetField",
            "Message": "'Some street that does not exist' is not in the list of Streets."
        },
        {
            "GUID": "67890",
            "FieldName": "ActivityField",
            "Message": "The Activity field requires a value."
        },
        {
            "GUID": "67890",
            "FieldName": "CityField",
            "Message": "'Some city that does not exist' is not in the list of Cities."
        }
    ]
}


In addition to the Message property there is now an Errors property. Errors is an array of objects that represent errors.

The improved response allows you to:

  • Identify which field has an associated error via the FieldName property.
    • If the error message cannot be associated to a specific field, the FieldName field's value will be an empty string.
  • Identify which record has the associated error via the GUID property.
  • Get a response that includes multiple errors across multiple records.
    • Validation is performed and errors reported for all records in the request (except records child to those that have errors).

Additional Details

  • Not every possible request failure is guaranteed to have an Errors property in the response and may just include a Message property.
  • When an enhanced error response can be provided from validating records, the Message property remains in the response with the value of the first error encountered.