Skip to main content
Cartegraph Campus

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

Status Object 

  • Purpose: The status object contains data about the status of a Scenario run.
  • Properties:
    • JobId - Unique ID that references the Scenario run
    • UserName - Name of the user who started the Scenario run
    • Performance - Object with properties that contain performance data
      • Elapsed Properties - Time that a status step took to complete
        • GettingScenarioAndAssetDataElapsed
        • CalculatingCurvesElapsed
        • RunningScenarioElapsed
        • SavingScenarioResultsElapsed
      • Start/Finished Properties - Timestamps of when a status step started, and a timestamp of when the last step completed
        • GettingScenarioAndAssetDataStart
        • CalculatingCurvesStart
        • RunningScenarioStart
        • SavingScenarioResultsStart
        • Finished
    • ScenarioOid - OID of the Scenario record
    • Scenario Run Status Steps
      • GettingScenarioAndAssetData - Step to get Scenario and Asset-related data
      • CalculatingCurves - Step to calculate Asset performance curves
      • RunningScenario - Step to process the Plan Years of a Scenario
      • SavingScenarioResults - Step to save the Scenario run results
      • Properties
        • Status - Status of the step
          • 0 - Waiting
          • 1 - In progress
          • 2 - Completed
          • 3 - Error
          • 4 - Canceling
          • 5 - Canceled
        • NumberOfRecords - Number of records that pertain to the step
        • Message - Status message pertaining to the step

Start Job

  • Purpose: Start a Scenario run and get a JobId back that references the Scenario run.
  • Introduced: v8Summer 2015
  • HTTP Method: POST
  • URL:
    • https://yourserver.com/cartegraph/api/v1/commands/scenarios/runscenarioasync
  • Request Body:
    • ScenarioOid - OID of the Scenario record to start a Scenario run for
  • Response Body:
    • JobId - Unique ID that references the Scenario run. Used in other requests to get the status of the Scenario run

Example Requests

Start a Scenario run for a specific Scenario:

POST https://yourserver.com/cartegraph/api/v1/commands/scenarios/runscenarioasync

    "ScenarioOid": 245733717
}

Example Responses

Started a Scenario run for a specific Scenario:

{
    "JobId": 1248707860
}

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object containing a JobId property. The JobId references the Scenario run and is used in other requests to get the status of the Scenario run
  • 400 Bad Request
    • A request body is required for this request.
      • There was not a JSON body provided with the request
  • 403 Forbidden
    • Access is denied.
      • Your Role does not have Scenario Builder permission in OMS.
  • 500 Internal Server Error
    • [user] is currently running a scenario. Run your scenario after [user]'s scenario completes running.
    • Another scenario is currently running. Try running your scenario later.
      • Only one Scenario can run in the system at a time
    • Request body is missing the ScenarioOid property.
      • The ScenarioOid property was not in the JSON body provided with the request
    • ScenarioOid has an invalid value: {ScenarioOid}
      • Invalid value for ScenarioOid; was unable to parse it into an integer value
    • Cannot find a Scenario record with an oid of {ScenarioOid}.
      • Could not find an existing Scenario record with the specified OID

Get Status For Jobs

  • Purpose: Get Scenario run status for one or more Scenario runs.
  • Introduced: v8 - Summer 2015
  • HTTP Method: GET
  • URL:
    • https://yourserver.com/cartegraph/api/v1/commands/scenarios/runscenarioasync/jobs
  • Optional Parameters:
    • runningOnly - If set to true, will filter Scenario runs to include only those that are running
    • scenarioOid - If provided, will filter Scenario runs to include only those for a particular Scenario record
    • Note: If both runningOnly (set to true) and scenarioOid are provided, they will effectively be "ANDed," meaning that both criteria must be met in order for the Scenario runs to be included in the response
  • Response Body:

Notes on Scenario runs: The Scenario run status objects exist only in memory on the server and are not stored in persistent data storage. This means that, for instance, as the server's memory recycles, the Scenario run status objects will be cleared and no longer available.

Example Requests

Get Scenario run status for all Scenario runs:

GET https://yourserver.com/cartegraph/api/v1/commands/scenarios/runscenarioasync/jobs

Get Scenario run status for Scenario runs filtered down to include only those that are running AND that are for a particular Scenario record:

GET https://yourserver.com/cartegraph/api/v1/commands/scenarios/runscenarioasync/jobs?runningOnly=true&scenarioOid=2036840341

Example Responses

Get Scenario run status for all Scenario runs:

{
    "Jobs": [
        {
            "JobID": 1528519845,
            "UserName": "Charles",
            "Performance": {
                "GettingScenarioAndAssetDataElapsed": "0.1 seconds",
                "CalculatingCurvesElapsed": "0.0 seconds",
                "RunningScenarioElapsed": "3.0 seconds",
                "SavingScenarioResultsElapsed": "0.1 seconds",
                "GettingScenarioAndAssetDataStart": "4:33:29 PM",
                "CalculatingCurvesStart": "4:33:29 PM",
                "RunningScenarioStart": "4:33:29 PM",
                "SavingScenarioResultsStart": "4:33:32 PM",
                "Finished": "4:33:32 PM"
            },
            "ScenarioOid": 1616281285,
            "GettingScenarioAndAssetData": {
                "Status": 2,
                "NumberOfRecords": 101,
                "Message": "Gathered 101 assets."
            },
            "CalculatingCurves": {
                "Status": 2,
                "NumberOfRecords": 1,
                "Message": "Generated 1 asset performance curve."
            },
            "RunningScenario": {
                "Status": 2,
                "NumberOfRecords": 5,
                "Message": "Processed 5 plan years."
            },
            "SavingScenarioResults": {
                "Status": 2,
                "NumberOfRecords": 166,
                "Message": "Saved 166 activities."
            }
        },
        {
            "JobID": 237573488,
            "UserName": "Bob",
            "Performance": {
                "GettingScenarioAndAssetDataElapsed": null,
                "CalculatingCurvesElapsed": null,
                "RunningScenarioElapsed": null,
                "SavingScenarioResultsElapsed": null,
                "GettingScenarioAndAssetDataStart": "4:33:44 PM",
                "CalculatingCurvesStart": null,
                "RunningScenarioStart": null,
                "SavingScenarioResultsStart": null,
                "Finished": null
            },
            "ScenarioOid": 2036840341,
            "GettingScenarioAndAssetData": {
                "Status": 3,
                "NumberOfRecords": null,
                "Message": "An error has occurred. See the Error Log for details."
            },
            "CalculatingCurves": {
                "Status": 0,
                "NumberOfRecords": null,
                "Message": "Stopped."
            },
            "RunningScenario": {
                "Status": 0,
                "NumberOfRecords": null,
                "Message": "Stopped."
            },
            "SavingScenarioResults": {
                "Status": 0,
                "NumberOfRecords": null,
                "Message": "Stopped."
            }
        },
        {
            "JobID": 39202159,
            "UserName": "Bob",
            "Performance": {
                "GettingScenarioAndAssetDataElapsed": "0.0 seconds",
                "CalculatingCurvesElapsed": "0.0 seconds",
                "RunningScenarioElapsed": null,
                "SavingScenarioResultsElapsed": null,
                "GettingScenarioAndAssetDataStart": "4:35:31 PM",
                "CalculatingCurvesStart": "4:35:31 PM",
                "RunningScenarioStart": "4:35:31 PM",
                "SavingScenarioResultsStart": null,
                "Finished": null
            },
            "ScenarioOid": 2036840341,
            "GettingScenarioAndAssetData": {
                "Status": 2,
                "NumberOfRecords": 101,
                "Message": "Gathered 101 assets."
            },
            "CalculatingCurves": {
                "Status": 2,
                "NumberOfRecords": 1,
                "Message": "Generated 1 asset performance curve."
            },
            "RunningScenario": {
                "Status": 1,
                "NumberOfRecords": 5,
                "Message": "Processing 5 plan years."
            },
            "SavingScenarioResults": {
                "Status": 0,
                "NumberOfRecords": null,
                "Message": "Waiting..."
            }
        }
    ]
}

Get Scenario run status for Scenario runs filtered down to include only those that are running AND that are for a particular Scenario record:

{
    "Jobs": [
        {
            "JobID": 39202159,
            "UserName": "Bob",
            "Performance": {
                "GettingScenarioAndAssetDataElapsed": "0.0 seconds",
                "CalculatingCurvesElapsed": "0.0 seconds",
                "RunningScenarioElapsed": null,
                "SavingScenarioResultsElapsed": null,
                "GettingScenarioAndAssetDataStart": "4:35:31 PM",
                "CalculatingCurvesStart": "4:35:31 PM",
                "RunningScenarioStart": "4:35:31 PM",
                "SavingScenarioResultsStart": null,
                "Finished": null
            },
            "ScenarioOid": 2036840341,
            "GettingScenarioAndAssetData": {
                "Status": 2,
                "NumberOfRecords": 101,
                "Message": "Gathered 101 assets."
            },
            "CalculatingCurves": {
                "Status": 2,
                "NumberOfRecords": 1,
                "Message": "Generated 1 asset performance curve."
            },
            "RunningScenario": {
                "Status": 1,
                "NumberOfRecords": 5,
                "Message": "Processing 5 plan years."
            },
            "SavingScenarioResults": {
                "Status": 0,
                "NumberOfRecords": null,
                "Message": "Waiting..."
            }
        }
    ]
}

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object containing a Jobs property. The value of this property is an array that contains Scenario run status objects (if there were objects to return; otherwise the array is empty)
  • 400 Bad Request
    • runningOnly has an invalid value: {runningOnly}
      • Invalid value for {runningOnly}; was unable to parse it into a boolean value
  • scenarioOid has an invalid value: {scenarioOid}
    • Invalid value for {scenarioOid}; was unable to parse it into an integer value
  • 403 Forbidden
    • Access is denied.
      • Your Role does not have Scenario Builder permission in OMS.

Get Status For Job

  • Purpose: Get Scenario run status for a specific Scenario run.
  • Introduced: v8 - Summer 2015
  • HTTP Method: GET
  • URL:
    • https://yourserver.com/cartegraph/api/v1/commands/scenarios/runscenarioasync/jobs/{jobId}
  • URL Parameters:
    • jobId - Unique ID that references the Scenario run
  • Response Body:

Notes on Scenario runs: The Scenario run status objects exist only in memory on the server and are not stored in persistent data storage. This means that, for instance, as the server's memory recycles, the Scenario run status objects will be cleared and no longer available.

Example Requests

Get Scenario run status for a specific Scenario run:

GET https://yourserver.com/cartegraph/api/v1/commands/scenarios/runscenarioasync/jobs/39202159

Example Responses

Get Scenario run status for a specific Scenario run:

{
    "Jobs": [
        {
            "JobID": 39202159,
            "UserName": "Bob",
            "Performance": {
                "GettingScenarioAndAssetDataElapsed": "0.0 seconds",
                "CalculatingCurvesElapsed": "0.0 seconds",
                "RunningScenarioElapsed": null,
                "SavingScenarioResultsElapsed": null,
                "GettingScenarioAndAssetDataStart": "4:35:31 PM",
                "CalculatingCurvesStart": "4:35:31 PM",
                "RunningScenarioStart": "4:35:31 PM",
                "SavingScenarioResultsStart": null,
                "Finished": null
            },
            "ScenarioOid": 2036840341,
            "GettingScenarioAndAssetData": {
                "Status": 2,
                "NumberOfRecords": 101,
                "Message": "Gathered 101 assets."
            },
            "CalculatingCurves": {
                "Status": 2,
                "NumberOfRecords": 1,
                "Message": "Generated 1 asset performance curve."
            },
            "RunningScenario": {
                "Status": 1,
                "NumberOfRecords": 5,
                "Message": "Processing 5 plan years."
            },
            "SavingScenarioResults": {
                "Status": 0,
                "NumberOfRecords": null,
                "Message": "Waiting..."
            }
        }
    ]
}


Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object containing a Jobs property. The value of this property is an array that contains one Scenario run status object
  • 400 Bad Request
    • {jobId} is not a valid job id
      • Invalid value for {jobId}; a Scenario run status object does not exist with the provided {jobId}
  • 403 Forbidden
    • Access is denied.
      • Your Role does not have Scenario Builder permission in OMS.

Cancel Job

  • Purpose: Cancel a specific Scenario run.
  • Introduced: v8 - Summer 2015
  • HTTP Method: DELETE
  • URL:
    • https://yourserver.com/cartegraph/api/v1/commands/scenarios/runscenarioasync/jobs/{jobId}
  • URL Parameters:
    • jobId - Unique ID that references the Scenario run

Notes on Scenario runs: The Scenario run status objects exist only in memory on the server and are not stored in persistent data storage. This means that, for instance, as the server's memory recycles, the Scenario run status objects will be cleared and no longer available.

Example Requests

Cancel a specific Scenario run:

DELETE https://yourserver.com/cartegraph/api/v1/commands/scenarios/runscenarioasync/jobs/1217763244

Example Responses

Cancel a specific Scenario run:

{}

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains an empty JSON object
  • 400 Bad Request
    • {jobId} is not a valid job id
      • Invalid value for {jobId}; a Scenario run status object does not exist with the provided {jobId}
  • 403 Forbidden
    • Access is denied.
      • Your Role does not have Scenario Builder permission in OMS.

Asset Swap

  • Purpose: To Perform a "Swap" of two Container/Component assets.
  • Introduced: v10 - Spring 2016
  • HTTP Method: POST
  • URL:
    • https://yourserver.com/cartegraph/api/v1/commands/assets/swap
  • Required Parameters:
    • className - the class name of the assets you want to swap.
    • outgoingAssetOid - the Oid of the asset being replaced.
    • outgoingAssetTaskActivity - the Activity for the task on the asset being replaced that will be created as part of the swap process.
    • outgoingAssetTaskLaborer - the ID of the Labor record to assign to the task on the asset being replaced.
    • incomingAssetOid - the Oid of the replacement asset.
    • incomingAssetTaskActivity - the Activity for the task on the replacement asset that will be created as part of the swap process.

Example Request

POST https://yourserver.com/cartegraph/api/v1/commands/assets/swap
{
    "ClassName": "cgFacilityLightingClass",
    "OutgoingAssetOid": 1234343,
    "OutgoingAssetTaskActivity": "Install",
    "OutgoingAssetTaskLaborer": "123",
    "IncomingAssetOid": 5678456,
    "IncomingAssetTaskActivity": "Repair"
}

Success Response

Returns the oids of the two tasks created.

{
     "IncomingAssetTaskOid": 1623649981,
     "OutgoingAssetTaskOid": 145296453
}

Status Codes Returned and Common Error Messages

  • 200 OK
    • Simple success object returned.
  • 400 Bad Request
    • Cannot find a {assetType} record with an oid of {Oid}.
      • The incomingAssetOid or outgoingAssetOid are invalid.
    • {activityName} is not a valid activity.
    • The specified activity could not be found.
    • Cannot swap in an asset that has components.
      • The asset specifed by incomingAssetOid is already part of a container/component relationship.
    • Cannot use an asset that already has a container
      • The asset specifed by incomingAssetOid is already part of a container/component relationship.
    • Please provide a valid Container or Component class
      • The className provided must specify an asset in a container/component relationship.
    • Incoming asset must not have any open tasks associated.
      • The asset specified by incomingAssetOid must have no open tasks associated to it.