Skip to main content
Cartegraph Campus

Layout 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.

  • Purpose: Retrieve existing Cartegraph Views (also known as screen layouts or FlexViews).
  • HTTP Method: GET
  • URL:
    • https://yourserver.com/cartegraph/api/v1/layout/{className}/{viewType}
      • This will return the View currently assigned to your OMS Role for the requested viewType.
    • https://yourserver.com/cartegraph/api/v1/layout/{className}/{viewType}/{viewName}
      • This will return the specific, named View for the requested viewType.
    • https://yourserver.com/cartegraph/api/v1/layout/?classes={csvClassNames}&viewType={viewType}
      • This will return the Views currently assigned to your OMS Role for the requested viewType for the provided csvClassNames.
  • URL Parameters:
    • className - Cartegraph class name (for example, cgSignsClass). 
    • csvClassNames - A comma-delimited list of classNames to retrieve views for. Allows for bulk retrieval of views.
    • viewType - The type of the screen layout. The name of the viewType more or less corresponds to the type of UI that the View is used for. Common values for viewType include List and Detail
    • viewName - The name of the screen layout. For a given className and viewType, the viewName identifies a specific screen layout. The name of the default Views in Cartegraph are Cartegraph Default. Retrieving a list of viewNames that, exist in the system, is currently not supported.

Cartegraph Roles

In Cartegraph OMS, Cartegraph Views are assigned to Cartegraph Roles. The OMS username used for Authentication in the API belongs to an OMS Role. Using the Layout feature of the API allows you to get the Views assigned to your OMS Role as well as Views assigned to Roles other than your own.

When requesting a View currently assigned to your OMS Role for the requested viewType:

https://yourserver.com/cartegraph/api/v1/layout/{className}/{viewType}

You would receive an error if the view name is set to <None> in OMS.

When requesting a specific, named View for the requested viewType:

https://yourserver.com/cartegraph/api/v1/layout/{className}/{viewType}/{viewName}

You would receive an error if the View is not assigned to your Role and your Role does not have Layout Manager permission in OMS.

When requesting a list of views:

https://yourserver.com/cartegraph/api/v1/layout/?classes={csvClassNames}&viewType={viewType}

You will not receive an error if requesting a View your role does not have permissions to. Instead, the returned collection will omit any Views that are not available to your role.

Example Requests

Get the Detail Layout for the Labor History recordset assigned to your OMS Role.

GET https://yourserver.com/cartegraph/api/v1/layout/cgLabor_cgHistoryClass/Detail

Get the "Cartegraph Default" List Layout for the Ponds recordset.

GET https://yourserver.com/cartegraph/api/v1/layout/PondsClass/List/Cartegraph%20Default

Get the "Cartegraph Default" Detail Layout for the Ponds recordset.

GET https://yourserver.com/cartegraph/api/v1/layout/PondsClass/Detail/Cartegraph%20Default

Get the List Layout for the Signs, Pavement, and Pavement Area recordsets.

GET https://yourserver.com/cartegraph/api/v1/layout/?classes=cgSignsClass,cgPavementClass,cgPavementAreaClass&viewType=List

Example Responses

Requested the Detail Layout for the Labor History recordset assigned to your OMS Role (in this example, "MyCustomRole"):

{
    "Oid": 1107562647,
    "ID": "cgLabor_cgHistoryClass",
    "ViewType": 2,
    "ViewName": "MyCustomView",
    "Roles": ",MyCustomRole,",
    "Sections": [
        {
            "Name": "History",
            "Items": [
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "DateField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "EventField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "NotesField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "cgLastModifiedField",
                    "Name": ""
                }
            ],
            "ID": "History1",
            "CGID": 0,
            "Type": 2,
            "IsVisible": true
        }
    ],
    "Pages": [],
    "ViewDenied": false
}

Requested the "Cartegraph Default" List Layout for the Ponds recordset:

{
    "Oid": 1497422226,
    "ID": "PondsClass",
    "ViewType": 0,
    "ViewName": "Cartegraph Default",
    "Roles": ",Default Administrator,Default User,MyCustomRole,",
    "Sections": [
        {
            "Name": "Index",
            "Items": [
                {
                    "UID": "PondsClass",
                    "Height": "350px",
                    "GridStyle": "Standard",
                    "GridFilter": "",
                    "InfoLookup": "",
                    "Items": [
                        {
                            "ColumnWidth": "",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "IDField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "200px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "StreetField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "EstimatedOCIField",
                            "Name": ""
                        }
                    ],
                    "HideFrozenColumn": false,
                    "ID": "",
                    "Name": "Grid"
                }
            ],
            "ID": "Index1",
            "CGID": 0,
            "Type": 1,
            "IsVisible": true
        }
    ],
    "Pages": [],
    "ViewDenied": false
}

Requested the "Cartegraph Default" Detail Layout for the Ponds recordset:

{
    "Oid": 909194854,
    "ID": "PondsClass",
    "ViewType": 2,
    "ViewName": "Cartegraph Default",
    "Roles": ",Default Administrator,Default User,MyCustomRole,",
    "Sections": [
        {
            "Name": "Overview",
            "Items": [
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "AssetType",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "IDField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "Avatar",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "StreetField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "LocationDescriptionField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "InstalledField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "ReplacedField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "Empty",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "RemainingLifeFormatted",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "EstimatedOCIProgress",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "EstimatedOCRStars",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "EstimatedOCIField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "TotalCostToDateFormatted",
                    "Name": ""
                }
            ],
            "ID": "Overview1",
            "CGID": 4,
            "Type": 0,
            "IsVisible": true
        },
        {
            "Height": "400px",
            "Name": "Map",
            "Items": [],
            "ID": "Map2",
            "CGID": 1,
            "Type": 0,
            "IsVisible": true
        },
        {
            "Name": "Location",
            "Items": [
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "StreetField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "CityField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "LocationDescriptionField",
                    "Name": ""
                }
            ],
            "ID": "Location3",
            "CGID": 2,
            "Type": 1,
            "IsVisible": true
        },
        {
            "Name": "Details",
            "Items": [
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "cgSectionGroupHeader",
                    "Name": "Basic Information"
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "IDField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "NotesField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "cgSectionGroupHeader",
                    "Name": "Relevant Dates"
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "InstalledField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "ReplacedField",
                    "Name": ""
                },
                {
                    "ColumnWidth": "",
                    "AltSortField": "",
                    "AttachmentUid": "",
                    "ID": "RetiredField",
                    "Name": ""
                }
            ],
            "ID": "AssetDetail4",
            "CGID": 0,
            "Type": 2,
            "IsVisible": true
        },
        {
            "Name": "Inspections",
            "Items": [
                {
                    "UID": "Ponds_cgInspectionsClass",
                    "Height": "350px",
                    "GridStyle": "ReadOnlyView",
                    "GridFilter": "",
                    "InfoLookup": "",
                    "Items": [
                        {
                            "ColumnWidth": "110px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "InspectionDateField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "100px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "StatusField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "150px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "InspectedByField\\FullNameField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "110px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "InspectedOCIField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "110px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "InspectedOCRField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "335px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "NotesField",
                            "Name": ""
                        }
                    ],
                    "HideFrozenColumn": false,
                    "ID": "",
                    "Name": "Grid"
                }
            ],
            "ID": "Inspections5",
            "CGID": 0,
            "Type": 2,
            "IsVisible": true
        },
        {
            "Name": "Tasks",
            "Items": [
                {
                    "UID": "Ponds_cgTasksClass",
                    "Height": "350px",
                    "GridStyle": "ReadOnlyView",
                    "GridFilter": "",
                    "InfoLookup": "",
                    "Items": [
                        {
                            "ColumnWidth": "101px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "IDField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "124px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "ActivityField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "100px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "StatusField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "135px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "StartDateEstimatedField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "125px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "StartDateActualField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "125px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "StopDateActualField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "128px",
                            "AltSortField": "PriorityField\\RankField",
                            "AttachmentUid": "",
                            "ID": "PriorityField",
                            "Name": ""
                        },
                        {
                            "ColumnWidth": "115px",
                            "AltSortField": "",
                            "AttachmentUid": "",
                            "ID": "TotalCostActualField",
                            "Name": ""
                        }
                    ],
                    "HideFrozenColumn": false,
                    "ID": "",
                    "Name": "Grid"
                }
            ],
            "ID": "Tasks6",
            "CGID": 0,
            "Type": 0,
            "IsVisible": true
        },
        {
            "Name": "Linked Assets",
            "Items": [],
            "ID": "LinkedAssets7",
            "CGID": 8,
            "Type": 0,
            "IsVisible": true
        },
        {
            "Name": "Attached Files",
            "Items": [],
            "ID": "Attachments8",
            "CGID": 5,
            "Type": 0,
            "IsVisible": true
        }
    ],
    "Pages": [],
    "ViewDenied": false
}

Get the List Layout for the Signs, Pavement, and Pavement Area recordsets. Remember, any views your role does not have permissions for will be omitted without warning

{
    "cgSignsClass": {
        "Oid": 909194854,
        "ID": "cgSignsClass",
        "ViewType": 2,
        "ViewName": "Cartegraph Default",
        "Roles": ",Default Administrator,Default User,MyCustomRole,",
        "Sections": [ ... ],
        "Pages": [],
        "ViewDenied": false
    },
    "cgPavementClass": {
        "Oid": 909194224,
        "ID": "cgPavementClass",
        "ViewType": 2,
        "ViewName": "Cartegraph Default",
        "Roles": ",Default Administrator,Default User,MyCustomRole,",
        "Sections": [ ... ],
        "Pages": [],
        "ViewDenied": false
    },
    "cgPavementAreaClass": {
        "Oid": 909194811,
        "ID": "cgPavementAreaClass",
        "ViewType": 2,
        "ViewName": "Cartegraph Default",
        "Roles": ",Default Administrator,Default User,MyCustomRole,",
        "Sections": [ ... ],
        "Pages": [],
        "ViewDenied": false
    }
}

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object representing a Cartegraph View record.
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name in the URL
        • Invalid URI path. {className} has less than the minimum number of URI segments required for this URI.
      • The URL contains less than the valid number of URI segments for that given URI.
      • In this document, refer to the applicable URL specification in order to view URL examples with valid numbers of segments.
      • Example: /cgSignsClass/ -- There are less than two segments (in this example, /{className}/).
        • 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, refer to the applicable URL specification in order to view URL examples with valid numbers of segments.
      • Example: /cgSignsClass/Detail/Cartegraph%20Default/blah -- There are more than three segments (in this example, /{className}/{viewType}/{viewName}/something else).
        • Class name '{className}' was not found.
      • An invalid class name was entered in the URL
      • Example: cgBlahClass/ -- cgBlahClass does not exist so it is invalid.
        • {viewType} is not a valid view type.
      • The view type specified was invalid.
        • The specified View was not found.
      • The specific, named View requested was not found--probably because it doesn't exist. Check your className and viewName.
        • A View with a view type of 'TaskInspection' is incompatible with 'cgSignsClass'.
      • The TaskInspection view type is only compatible with cgTasksClass.
  • 403 Forbidden
    • Access is denied. You do not have permission to access this view.
      • Occurs when requesting a View currently assigned to your OMS Role for the requested viewType and the view name is set to <None> in OMS.
      • Occurs when requesting a specific, named View for the requested viewType and the View is not assigned to your Role and your Role does not have Layout Manager permission in OMS.