Alter (Circuits) | ArcGIS REST APIs

URL:: https://<root>/<serviceName>/UtilityNetworkServer/circuits/alter
Methods:: GETPOST
Version Introduced:: 11.5

The alter operation on the circuits resource allows you to modify circuit information for an existing circuit in a telecom domain network. The alter operation replaces the existing circuit definition with that provided in the circuits parameter. If any properties or information is excluded from the circuit definition in the parameter, it is removed from the circuit.

When the operation is successful, the editor tracking fields for the circuit in the circuit management tables are updated.

Request parameters

Parameter Details

Parameter	Details
`f`	Specifies the output format of the response. The default response format is `html`. Values: `html` \| `json` \| `pjson`
`gdbVersion` (Optional)	Specifies the name of the geodatabase version. The default is 'sde.DEFAULT'. Syntax: Use dark colors for code blocksCopy `1 gdbVersion=<version>`
`sessionId` (Optional)	Specifies the token (guid) used to lock the version. If a client has previously started an edit session and holds an exclusive lock on the version specified, the request will fail if the sessionId is not provided. If the specified version is currently locked by any other session, the request will fail if the sessionId is not provided or does not match the sessionId that holds the exclusive lock. Syntax: Use dark colors for code blocksCopy `1 sessionId=<guid>`
`domainNetworkName` (Required)	Specifies the name of the telecom domain network containing the circuit to be altered. Syntax: Use dark colors for code blocksCopy `1 domainNetworkName=<string>` Example: Use dark colors for code blocksCopy `1 domainNetworkName=Telco`
`circuit` (Required)	The circuit or circuit information to be altered. Syntax: Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 { "circuits":[ { "name": <string>, "globalId": <guid>, "isSectioned": <boolean>, "sectionOrder": <string>, "circuitType": "Physical" \| "Virtual", // Default is Physical "startLocation" : // Only if isSectioned is false { "sourceId" : <short>, "globalId" : <guid>, "terminalId" : <short>, "firstUnit" : <short>, "lastUnit" : <short> }, "stopLocation" : // Only if isSectioned is false { "sourceId" : <short>, "globalId" : <guid>, "terminalId" : <short>, "firstUnit" : <short>, "lastUnit" : <short> }, "sections": [ { "sectionId": <long>, "role": "Start and end"\| "Start" \| "End" \| "Midspan", // Default is Start and end "sectionType": "Physical" \| "Virtual", // Default is Physical "startLocation": { "sourceId" : <short>, "globalId" : <guid>, "terminalId" : <short>, "firstUnit" : <short>, "lastUnit" : <short> }, "stopLocation": { "sourceId" : <short>, "globalId" : <guid>, "terminalId" : <short>, "firstUnit" : <short>, "lastUnit" : <short> }, } ], "subcircuits": [ { "name": <string>, "globalId": <guid>, "providerID": <guid>, "consumerId": <guid>, "isReserved": "true" \| "false", // Default is false "attributes": { // Optional, used when user-defined attributes are configured for the Subcircuit "subCircuitUserField1": <value>, "subCircuitUserField2": <value> } } ], "attributes": { // Optional, used when user-defined attributes are configured for the Circuit "circuitUserField1": <value>, "circuitUserField2": <value> } }

f

Specifies the output format of the response. The default response format is html.

Values: html | json | pjson

gdbVersion

(Optional)

Specifies the name of the geodatabase version. The default is 'sde.DEFAULT'.

Syntax:

Use dark colors for code blocksCopy
gdbVersion=<version>

sessionId

(Optional)

Specifies the token (guid) used to lock the version. If a client has previously started an edit session and holds an exclusive lock on the version specified, the request will fail if the sessionId is not provided. If the specified version is currently locked by any other session, the request will fail if the sessionId is not provided or does not match the sessionId that holds the exclusive lock.

Syntax:

Use dark colors for code blocksCopy
sessionId=<guid>

domainNetworkName

(Required)

Specifies the name of the telecom domain network containing the circuit to be altered.

Syntax:

Use dark colors for code blocksCopy
domainNetworkName=<string>

Example:

Use dark colors for code blocksCopy
domainNetworkName=Telco

circuit

(Required)

The circuit or circuit information to be altered.

Syntax:

Use dark colors for code blocksCopy
{
"circuits":[
  {
    "name": <string>,
    "globalId": <guid>,
    "isSectioned": <boolean>,
    "sectionOrder": <string>,
    "circuitType": "Physical" | "Virtual",               // Default is Physical
    "startLocation" :              // Only if isSectioned is false
      {
        "sourceId"   : <short>,
        "globalId"   : <guid>,
        "terminalId" : <short>,
        "firstUnit"  : <short>,
        "lastUnit"   : <short>
      },
    "stopLocation" :              // Only if isSectioned is false
      {
        "sourceId"   : <short>,
        "globalId"   : <guid>,
        "terminalId" : <short>,
        "firstUnit"  : <short>,
        "lastUnit"   : <short>
      },
   "sections": [
      {
        "sectionId": <long>,
        "role": "Start and end"| "Start" | "End" | "Midspan",               // Default is Start and end
        "sectionType": "Physical" | "Virtual",               // Default is Physical
        "startLocation": {
          "sourceId"   : <short>,
          "globalId"   : <guid>,
          "terminalId" : <short>,
          "firstUnit"  : <short>,
          "lastUnit"   : <short>
          },
        "stopLocation": {
          "sourceId"   : <short>,
          "globalId"   : <guid>,
          "terminalId" : <short>,
          "firstUnit"  : <short>,
          "lastUnit"   : <short>
          },
        }
      ],
    "subcircuits": [
      {
          "name": <string>,
          "globalId": <guid>,
          "providerID": <guid>,
          "consumerId": <guid>,
          "isReserved": "true" | "false",               // Default is false
          "attributes": {               // Optional, used when user-defined attributes are configured for the Subcircuit
            "subCircuitUserField1": <value>,
            "subCircuitUserField2": <value>
          }
        }
      ],
    "attributes": {               // Optional, used when user-defined attributes are configured for the Circuit
      "circuitUserField1": <value>,
      "circuitUserField2": <value>
    }
}

JSON Response syntax

Use dark colors for code blocksCopy
{
  "moment": <epochtime>,
  "exceededTransferLimit": <true | false>,
  "serviceEdits": [
    {
      "id": <layerId>,
      "editedFeatures": {
        "updates": [<currentFeature1>, <currentFeature2>]
      }
    }
  ],
  "success": <boolean>,
  "error" : {                   // only if success is false
    "extendedCode" : <HRESULT>,
    "message" : <string>,
    "details" : [ <string> ]
  }
}

Example usage

Request URL and parameters:

Use dark colors for code blocksCopy

https://myserver.esri.com/server/rest/services/Telco/UtilityNetworkServer/circuits/alter

Use the alter operation to make modifications to a sectioned circuit named A48/T3U/89032834/89253420. The circuit was created with a single section using the create operation on the circuits resource as follows:

Use dark colors for code blocksCopy

f=json
gdbVersion=sde.Default
domainNetworkName=Telco
circuit={
  "name": "A48/T3U/89032834/89253420",
  "globalId": "{D592806A-4EDD-458A-92C2-7A653556C131}",
  "circuitType": "Physical",
  "isSectioned": true,
  "sectionOrder": {},
  "sections": [
    {
      "sectionId": 1,
      "role": "Start and end",
      "sectionType": "Physical",
      "startLocation": {
        "sourceId": 20,
        "globalId": "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
        "terminalId": 1,
        "firstUnit": 1,
        "lastUnit": 1
      },
      "stopLocation": {
        "sourceId": 20,
        "globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
        "terminalId": 1,
        "firstUnit": 1,
        "lastUnit": 1
      }
    }
  ],
  "subcircuits": []
}

Add a second section and subcircuit to the circuit created above using the alter operation, specifying the section order and role for each section:

Use dark colors for code blocksCopy

f=json
gdbVersion=sde.Default
domainNetworkName=Telco
circuit={
  "name": "A48/T3U/89032834/89253420",
  "globalId": "{4477F01F-A6EB-4FB0-970A-41E6F26363B6}",
  "circuitType": "Physical",
  "isSectioned": true,
  "sectionOrder": {
    "1": [2],
    "2": []
    },
  "sections": [
    {
      "sectionId": 1,
      "role": "Start",
      "sectionType": "Physical",
      "startLocation": {
        "sourceId": 20,
        "globalId": "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
        "terminalId": 1,
        "firstUnit": 1,
        "lastUnit": 1
      },
      "stopLocation": {
        "sourceId": 20,
        "globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
        "terminalId": 1,
        "firstUnit": 1,
        "lastUnit": 1
      }
    },
    {
      "sectionID": 2,
      "role": "End",
      "sectionType": "Physical",
      "startLocation": {
        "sourceId": 20,
        "globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
        "terminalId": 1,
        "firstUnit": 1,
        "lastUnit": 1
      },
      "stopLocation": {
        "sourceId": 20,
        "globalId": "{A8ADC6B0-B7DB-4999-ADB3-D7958F10D4A8}",
        "terminalId": 1,
        "firstUnit": 1,
        "lastUnit": 1
      }
    }
  ],
  "subcircuits": [
    {
      "name": "S1A48/T3U/89032834/89253420",
      "providerId": "{661614F5-4A19-404A-B4F2-F3D7F1D2362B}",
      "consumerId": "{FFBA459C-28A6-4978-88F8-3C0A34C81BF4}",
      "isReserved": false
    }
  ]
}

Remove the first section and subcircuit from the circuit using the alter operation and update the value of a user-defined attribute added to the circuit:

Use dark colors for code blocksCopy

f=json
gdbVersion=sde.Default
domainNetworkName=Telco
circuit={
  "name": "A48/T3U/89032834/89253420",
  "globalId": "{D592806A-4EDD-458A-92C2-7A653556C131}",
  "circuitType": "Physical",
  "isSectioned": true,
  "sectionOrder": {},
  "sections": [
    {
      "sectionID": 2,
      "role": "Start and end",
      "sectionType": "Physical",
      "startLocation": {
        "sourceId": 20,
        "globalId": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
        "terminalId": 1,
        "firstUnit": 1,
        "lastUnit": 1
      },
      "stopLocation": {
        "sourceId": 20,
        "globalId": "{A8ADC6B0-B7DB-4999-ADB3-D7958F10D4A8}",
        "terminalId": 1,
        "firstUnit": 1,
        "lastUnit": 1
      }
    }
  ],
  "subcircuits": [],
  "attributes": {
    "Private": "Yes"
  }
}

JSON response:

Use dark colors for code blocksCopy
{
  "moment": 1751471421276,
  "exceededTransferLimit": false,
  "serviceEdits": [
    {
      "id": 22,
      "editedFeatures": {
        "updates": [
          [
            {
              "attributes": {
                "objectid": 446,
                "name": "A48/T3U/89032834/89253420",
                "sectionorder": "{\"1\":[]}",
                "status": 1,
                "isdeleted": 0,
                "lastverified": null,
                "lastexported": null,
                "startlocationsourceid": null,
                "startlocationid": null,
                "startlocationterminalid": null,
                "startlocationfirstunit": null,
                "startlocationlastunit": null,
                "stoplocationsourceid": null,
                "stoplocationid": null,
                "stoplocationterminalid": null,
                "stoplocationfirstunit": null,
                "stoplocationlastunit": null,
                "issectioned": 1,
                "circuittype": 0,
                "conflictcontainerstate": null,
                "globalid": "{4477F01F-A6EB-4FB0-970A-41E6F26363B6}",
                "created_user": "unadmin",
                "created_date": 1751471183000,
                "last_edited_user": "unadmin",
                "last_edited_date": 1751471183000
              }
            },
            {
              "attributes": {
                "objectid": 446,
                "name": "A48/T3U/89032834/89253420",
                "sectionorder": "{\"2\":[]}",
                "status": 1,
                "isdeleted": 0,
                "lastverified": null,
                "lastexported": null,
                "startlocationsourceid": null,
                "startlocationid": null,
                "startlocationterminalid": null,
                "startlocationfirstunit": null,
                "startlocationlastunit": null,
                "stoplocationsourceid": null,
                "stoplocationid": null,
                "stoplocationterminalid": null,
                "stoplocationfirstunit": null,
                "stoplocationlastunit": null,
                "issectioned": 1,
                "circuittype": 0,
                "conflictcontainerstate": null,
                "globalid": "{4477F01F-A6EB-4FB0-970A-41E6F26363B6}",
                "created_user": "unadmin",
                "created_date": 1751471183000,
                "last_edited_user": "unadmin",
                "last_edited_date": 1751471421000
              }
            }
          ]
        ]
      }
    },
    {
      "id": 23,
      "editedFeatures": {
        "adds": [
          {
            "attributes": {
              "objectid": 437,
              "circuitid": "{4477F01F-A6EB-4FB0-970A-41E6F26363B6}",
              "sectionid": 2,
              "startlocationsourceid": 20,
              "startlocationid": "{332A2863-0CE0-41BC-847B-C0F1980C9E4C}",
              "startlocationterminalid": 1,
              "startlocationfirstunit": 1,
              "startlocationlastunit": 1,
              "stoplocationsourceid": 20,
              "stoplocationid": "{6C59BEF8-A74C-49E7-9A9C-144FA5CB3C3A}",
              "stoplocationterminalid": 1,
              "stoplocationfirstunit": 1,
              "stoplocationlastunit": 1,
              "role": 0,
              "sectiontype": 0,
              "globalid": "{1838DAA4-17E7-412A-914C-E9EB74BA6D23}",
              "created_user": "unadmin",
              "created_date": 1751471421000,
              "last_edited_user": "unadmin",
              "last_edited_date": 1751471421000
            }
          }
        ],
        "deletes": [
          {
            "attributes": {
              "objectid": 832,
              "circuitid": "{4477F01F-A6EB-4FB0-970A-41E6F26363B6}",
              "sectionid": 1,
              "startlocationsourceid": 20,
              "startlocationid": "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
              "startlocationterminalid": 1,
              "startlocationfirstunit": 1,
              "startlocationlastunit": 1,
              "stoplocationsourceid": 20,
              "stoplocationid": "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
              "stoplocationterminalid": 1,
              "stoplocationfirstunit": 1,
              "stoplocationlastunit": 1,
              "role": 0,
              "sectiontype": 0,
              "globalid": "{90DE7F50-0638-4F47-B582-732524E20C40}",
              "created_user": "unadmin",
              "created_date": 1751471183000,
              "last_edited_user": "unadmin",
              "last_edited_date": 1751471183000
            }
          }
        ]
      }
    }
  ],
  "success": true
}