CircuitManager | References | ArcGIS Maps SDK for JavaScript

import CircuitManager from "@arcgis/core/networks/CircuitManager.js";

const CircuitManager = await $arcgis.import("@arcgis/core/networks/CircuitManager.js");

Inheritance: CircuitManager→Accessor

Since: ArcGIS Maps SDK for JavaScript 4.34

A CircuitManager provides access to circuit management capabilities for a telecom domain network in a utility network.

See also

Example

const utilityNetwork = new UtilityNetwork({
  layerUrl: "https://host.com/arcgis/rest/services/Test/FeatureServer/0",
});

await utilityNetwork.load();

const domainNetworks = utilityNetwork.dataElement?.domainNetworks;
const telecomDomainNetwork = domainNetworks.find((dn) => dn.isTelecomNetwork);

const circuitManager = await utilityNetwork.getCircuitManager(telecomDomainNetwork.domainNetworkName);

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	CircuitManagerProperties

See the properties table for a list of all the properties that may be passed into the constructor.

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

Property	Type	Class
circuitSectionTable readonly	FeatureLayer
circuitTable readonly	FeatureLayer
declaredClass readonly inherited	string	Accessor
featureServiceUrl readonly	string
gdbVersion readonly	string \| null \| undefined
historicMoment readonly	Date \| null \| undefined
networkServiceUrl readonly	string
subcircuitTable readonly	FeatureLayer
telecomDomainNetwork readonly	DomainNetworkJSON
telecomDomainNetworkName readonly	string
utilityNetwork readonly	UtilityNetwork

circuitSectionTable

readonly Property

Type: FeatureLayer

A FeatureLayer for the telecom domain network's circuit section table.

circuitTable

readonly Property

Type: FeatureLayer

A FeatureLayer for the telecom domain network's circuit table.

declaredClass

readonlyinherited Property

Type: string

Inherited from: Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

featureServiceUrl

readonly Property

Type: string

Returns the root feature service URL which the utility network is part of.

Example

`https://utilitynetwork.esri.com/server/rest/services/NapervilleElectric/FeatureServer/`

gdbVersion

readonly Property

Type: string | null | undefined

The version of the geodatabase of the feature service data used by the utility network. Read the Overview of versioning topic for more details about this capability.

historicMoment

readonly Property

Type: Date | null | undefined

The utility network's historic moment to query. If this property is not specified, queries will apply to the current features.

networkServiceUrl

readonly Property

Type: string

The URL of the network server.

Example

`https://utilitynetwork.esri.com/server/rest/services/NapervilleElectric/UtilityNetworkServer/`

subcircuitTable

readonly Property

Type: FeatureLayer

A FeatureLayer for the telecom domain network's subcircuit table.

telecomDomainNetwork

readonly Property

Type: DomainNetworkJSON

An object representing the telecom domain network in the utility network data element.

telecomDomainNetworkName

readonly Property

Type: string

The name of the telecom domain network.

utilityNetwork

readonly Property

Type: UtilityNetwork

The UtilityNetwork that contains the telecom domain network being managed.

Methods

Method	Signature	Class
fromJSON inherited static	fromJSON(json: any): any	JSONSupportMixin
alter	alter(circuit: Circuit): Promise<void>
create	create(circuit: Circuit): Promise<void>
delete	delete(circuitNames: string[]): Promise<void>
export	export(props: CircuitExportProperties): Promise<CircuitExportResult[]>
getCircuit	getCircuit(circuitName: string, isSectioned?: boolean): Circuit
loadCircuitSectionTable	loadCircuitSectionTable(): Promise<FeatureLayer>
loadCircuitTable	loadCircuitTable(): Promise<FeatureLayer>
loadSubcircuitTable	loadSubcircuitTable(): Promise<FeatureLayer>
queryCircuitNames	queryCircuitNames(query: QueryCircuitByLocationsProperties \| QueryCircuitByIdsProperties): Promise<string[]>
queryCircuits	queryCircuits(query: QueryCircuitByNamesProperties \| QueryCircuitByLocationsProperties \| QueryCircuitByIdsProperties): Promise<Circuit[]>
submitExportJob	submitExportJob(props: CircuitExportProperties, options?: RequestOptions \| null \| undefined): Promise<CircuitExportJobInfo>
submitVerifyJob	submitVerifyJob(props: CircuitVerifyProperties, options?: RequestOptions \| null \| undefined): Promise<CircuitVerifyJobInfo>
toJSON inherited	toJSON(): any	JSONSupportMixin
verify	verify(props: CircuitVerifyProperties): Promise<CircuitVerifyResult[]>

fromJSON

inheritedstatic Method

Signature: fromJSON (json: any): any

Inherited from: JSONSupportMixin

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameters

Parameter	Type	Description	Required
json	any	A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns: any
Returns a new instance of this class.

alter

Method

Signature: alter (circuit: Circuit): Promise<void>

Modifies circuit information for an existing circuit in a telecom domain network. This method replaces the existing circuit definition with the provided circuit. If any properties are excluded from the provided circuit definition, it is removed from the circuit.

To alter an existing circuit, the provided Circuit must have a valid globalId property, else this method will throw an exception.

Parameters

Parameter	Type	Description	Required
circuit	Circuit	The circuit to be altered.

Returns: Promise<void>
Resolves when the circuit is successfully altered.

Example

const circuits = await circuitManager.queryCircuits(["FIRSTCIRCUIT"]);
circuits[0].name = "NewCircuitName";
await circuitManager.alter(circuits[0]);

create

Method

Signature: create (circuit: Circuit): Promise<void>

Creates a circuit in a telecom domain network.

Circuits created during an active edit session will not be returned by a query until the session has been ended with stopEditing.

Parameters

Parameter	Type	Description	Required
circuit	Circuit	The circuit to create.

Returns: Promise<void>
Resolves when the circuit is successfully created.

Examples

// Create a non-sectioned circuit with user-defined attributes.
const startingLocation = new CircuitLocation({
  sourceId: 20,
  globalId: "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
  firstUnit: 1,
  lastUnit: 1,
});

const stoppingLocation = new CircuitLocation({
  sourceId: 20,
  globalId: "{F081B917-499E-43FC-AEC9-7C1B313BF128}",
  firstUnit: 1,
  lastUnit: 1,
});

const attributes = {
  attributeOne: 1,
  attributeTwo: "Two",
  attributeThree: new Date().getTime(),
  attributeFour: null,
};

const circuit = new Circuit({
  name: "FIRSTCIRCUIT",
  circuitType: "physical",
  startLocation: startingLocation,
  stopLocation: stoppingLocation,
  attributes: attributes,
});

await circuitManager.create(circuit);

To create a sectioned circuit, provide a Map to represent the logical connectivity between sections in a circuit. This map should represent a directed adjacency list where each key is a CircuitSection that connects to other CircuitSection instances indicated by the key's value. The map type is Map<CircuitSection, CircuitSection[]>.

In this example, section 1 connects to 2 and 3 (where sections 2 and 3 are in parallel), 2 connects to 4, 3 connects to 4, and 4 connects to nothing (it is the end of the circuit).

// Create a sectioned circuit.
const sectionOne = new CircuitSection({
  sectionId: 1,
  sectionType: "physical",
  startLocation: new CircuitLocation({
    sourceId: 20,
    globalId: "{6B0A0E4E-80EF-4688-B463-253063A5B4B2}",
    firstUnit: 1,
    lastUnit: 4,
  }),
  stopLocation: new CircuitLocation({
    sourceId: 20,
    globalId: "{3A557124-4243-4615-96DF-51991E6B9766}",
    firstUnit: 1,
    lastUnit: 4,
  }),
});

const sectionTwo = new CircuitSection({
  sectionId: 2,
  sectionType: "physical",
  subcircuit: new Subcircuit({ name: "SUBCIRCUITVALUE2" }),
});

const sectionThree = new CircuitSection({
  sectionId: 3,
  sectionType: "physical",
  startLocation: new CircuitLocation({
    sourceId: 20,
    globalId: "{7C874691-D659-4311-B19C-D33027B6F48A}",
    firstUnit: 1,
    lastUnit: 4,
  }),
  stopLocation: new CircuitLocation({
    sourceId: 20,
    globalId: "{BF34887C-359E-4E00-A695-8D92BF41FE37}",
    firstUnit: 1,
    lastUnit: 4,
  }),
});

const sectionFour = new CircuitSection({
  sectionId: 4,
  sectionType: "physical",
  startLocation: new CircuitLocation({
    sourceId: 20,
    globalId: "{E4ECA4B4-F9F7-4AB2-B2FD-6CDAB1A9506B}",
    firstUnit: 1,
    lastUnit: 4,
  }),
  stopLocation: new CircuitLocation({
    sourceId: 20,
    globalId: "{18DE7259-FDC6-4788-B13B-3F6210CCCB56}",
    firstUnit: 1,
    lastUnit: 4,
  }),
});

const sections = new Map([
  [sectionOne, [sectionTwo, sectionThree]],
  [sectionTwo, [sectionFour]],
  [sectionThree, [sectionFour]],
  [sectionFour, []],
]);

const sectionedCircuit = new Circuit({
  name: "CIRCUIT - 1749681983401",
  circuitType: "physical",
  sections: sections,
});

await circuitManager.create(sectionedCircuit);

delete

Method

Signature: delete (circuitNames: string[]): Promise<void>

Logically deletes one or more circuits in a telecom domain network.

Parameters

Parameter	Type	Description	Required
circuitNames	string[]	The names of the circuit or circuits to be deleted.

Returns: Promise<void>
Resolves when the specified circuits are successfully deleted.

Example

const circuitNames = ["FIRSTCIRCUIT"];
await circuitManager.delete(circuitNames);

export

Method

Signature: export (props: CircuitExportProperties): Promise<CircuitExportResult[]>

Exports feature and connectivity information about provided circuits in a telecom domain network into JSON files for consumption by external systems. Each circuit exported is output to a separate JSON file.

Parameters

Parameter	Type	Description	Required
props	CircuitExportProperties	An object specifying configuration settings for the export.

Returns: Promise<CircuitExportResult[]>
Resolves to an object specifying the export location and status for each circuit.

Example

const circuits = await circuitManager.export({
  circuitNames: ["FIRSTCIRCUIT"],
  exportAcknowledgement: true,
  outSpatialReference: {
    wkid: 4326
  },
  resultTypes: [
    {
      type: "features",
      includeGeometry: true,
      includeDomainDescriptions: true,
      networkAttributeNames: ["Asset group", "Asset type"],
      diagramTemplateName: "",
      resultTypeFields: [
        { networkSourceId: 20, fieldName: "FIRSTUNIT" },
        { networkSourceId: 20, fieldName: "LASTUNIT" },
      ],
    },
  ],
});

getCircuit

Method

Signature: getCircuit (circuitName: string, isSectioned?: boolean): Circuit

Returns a Circuit instance with its circuitManager property set to the current CircuitManager instance.

Parameters

Parameter	Type	Description	Required
circuitName	string	The name of the `Circuit` instance to create.
isSectioned	boolean	= false - Whether the `Circuit` instance is sectioned.

Returns: Circuit
A Circuit instance with its circuitManager property set to the current CircuitManager instance.

loadCircuitSectionTable

Method

Signature: loadCircuitSectionTable (): Promise<FeatureLayer>

Loads the telecom domain network's circuit section table.

Returns: Promise<FeatureLayer>
Resolves to a loaded FeatureLayer for the circuit section table.

loadCircuitTable

Method

Signature: loadCircuitTable (): Promise<FeatureLayer>

Loads the telecom domain network's circuit table.

Returns: Promise<FeatureLayer>
Resolves to a loaded FeatureLayer for the circuit table.

loadSubcircuitTable

Method

Signature: loadSubcircuitTable (): Promise<FeatureLayer>

Loads the telecom domain network's subcircuit table.

Returns: Promise<FeatureLayer>
Resolves to a loaded FeatureLayer for the subcircuit table.

queryCircuitNames

Method

Signature: queryCircuitNames (query: QueryCircuitByLocationsProperties | QueryCircuitByIdsProperties): Promise<string[]>

Returns the names of circuits from a telecom domain network that satisfy a specified query.

Parameters

Parameter	Type	Description	Required
query	QueryCircuitByLocationsProperties \| QueryCircuitByIdsProperties	The query specifying the criteria for the circuits to return.

Returns: Promise<string[]>
The queried circuit names.

Examples

const props: QueryCircuitByLocationsProperties = {
  locations: [
    new CircuitLocation({
      sourceId: 20,
      globalId: "{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}",
      firstUnit: 1,
      lastUnit: 1,
    }),
  ],
  locationType: "all",
};

const circuitNames = await circuitManager.queryCircuitNames(props);

const props: QueryCircuitByIdsProperties = {
  globalIds: ["{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}"],
};

const circuitNames = await circuitManager.queryCircuitNames(props);

queryCircuits

Method

Signature: queryCircuits (query: QueryCircuitByNamesProperties | QueryCircuitByLocationsProperties | QueryCircuitByIdsProperties): Promise<Circuit[]>

Returns circuits from a telecom domain network that satisfy a specified query. The query can specify circuit names, globalIds, or start/stop locations, along with additional options such as circuit hierarchy and status.

Parameters

Parameter	Type	Description	Required
query	QueryCircuitByNamesProperties \| QueryCircuitByLocationsProperties \| QueryCircuitByIdsProperties	The names, globalIds, or start/stop locations of the circuits to query.

Returns: Promise<Circuit[]>
The queried circuits.

Examples

// Query circuits by locations.
const circuits = await circuitManager?.queryCircuits({
  hierarchy: "consumers-and-providers",
  locations: [
    new CircuitLocation({
      firstUnit: 1,
      globalId: "{B8E64696-E9C5-4349-ADC8-E72BBF2797D1}",
      lastUnit: 1,
      sourceId: 20,
    }),
  ],
});

// Query circuits by name.
const circuits = await circuitManager.queryCircuits({ names: ["MULTISECTIONCIRCUIT"] });

// Query circuits by globalIds.
const circuits = await circuitManager.queryCircuits({ globalIds: ["{8A1B5A33-3EBA-42CC-9085-31B22DAFE5DC}"] });

submitExportJob

Method

Signature: submitExportJob (props: CircuitExportProperties, options?: RequestOptions | null | undefined): Promise<CircuitExportJobInfo>

Since: ArcGIS Maps SDK for JavaScript 5.1

Asynchronously exports feature and connectivity information about provided circuits in a telecom domain network.

Parameters

Parameter	Type	Description	Required
props	CircuitExportProperties	An object specifying configuration settings for the export job.
options	RequestOptions \| null \| undefined	The request options specified by the user in the data request.

Returns: Promise<CircuitExportJobInfo>
Resolves to a CircuitExportJobInfo object with the results of the export job.

Example

const exportJob = await circuitManager.submitExportJob({
  circuitNames: ["MULTISECTIONCIRCUIT"],
  exportAcknowledgement: true,
  outSpatialReference: {
    wkid: 4326,
  },
  resultTypes: [
    {
      type: "features",
      includeGeometry: true,
      includeDomainDescriptions: true,
      networkAttributeNames: ["Asset group", "Asset type"],
      diagramTemplateName: "",
      resultTypeFields: [
        { networkSourceId: 20, fieldName: "FIRSTUNIT" },
        { networkSourceId: 20, fieldName: "LASTUNIT" },
      ],
    },
  ],
});

await exportJob.waitForJobCompletion();

submitVerifyJob

Method

Signature: submitVerifyJob (props: CircuitVerifyProperties, options?: RequestOptions | null | undefined): Promise<CircuitVerifyJobInfo>

Since: ArcGIS Maps SDK for JavaScript 5.1

Asynchronously checks the validity of circuits in a telecom domain network.

Parameters

Parameter	Type	Description	Required
props	CircuitVerifyProperties	An object specifying configuration settings for the verify job.
options	RequestOptions \| null \| undefined	The request options specified by the user in the data request.

Returns: Promise<CircuitVerifyJobInfo>
Resolves to a CircuitVerifyJobInfo object with the results of the verify job.

Example

const props: VerifyCircuitsProperties = {
  circuitNames: ["FIRSTCIRCUIT"],
  forceVerify: true,
  synthesizeGeometries: true,
};

const verifyCircuitsResult = await circuitManager.submitVerifyJob(props);

toJSON

inherited Method

Signature: toJSON (): any

Inherited from: JSONSupportMixin

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.

Returns: any
The ArcGIS portal JSON representation of an instance of this class.

verify

Method

Signature: verify (props: CircuitVerifyProperties): Promise<CircuitVerifyResult[]>

Checks the validity of circuits in a telecom domain network. The operation confirms that a circuit can be traced from the starting location to the stopping location and ensures that circuit sections and subcircuits are properly configured.

Parameters

Parameter	Type	Description	Required
props	CircuitVerifyProperties	An object specifying configuration settings for the verify operation.

Returns: Promise<CircuitVerifyResult[]>
Resolves to an array of objects specifying the verification status for each circuit.

Example

const props: VerifyCircuitsProperties = {
  circuitNames: ["FIRSTCIRCUIT"],
  outSpatialReference: {
    wkid: 4326,
  },
  forceVerify: true,
  synthesizeGeometries: true,
};

const verifyCircuitsResult = await circuitManager.verify(props);

Type definitions

CommonCircuitQueryProperties

Type definition

hierarchy

Property

Type: CircuitHierarchy | undefined

Specifies whether to return the associated consumer and provider circuits with the queried circuit. The default is none.

status

Property

Type: CircuitStatus | undefined

Specifies whether to filter the result of the query to return only circuits of a certain status. This filter also applies to any circuits returned using the hierarchy parameter. status is empty by default with no filter applied.

QueryCircuitByNamesProperties

Type definition

Parameters for querying circuits by name.

Supertypes: CommonCircuitQueryProperties

names

Property

Type: string[]

The names of the circuit or circuits to be returned.

globalIds

Property

Type: null | undefined

The global ID of the circuit or circuits to be returned.

locations

Property

Type: null | undefined

Specifies the location information for the feature associated with a circuit's starting or stopping point. The results can be filtered further when used with the locationType parameter.

locationType

Property

Type: null | undefined

The type of trace location in the circuit to query (start location, stop location, or both). The default is all. This can be used to filter the results when using locations to return circuit information.

QueryCircuitByIdsProperties

Type definition

Parameters for querying circuits by global IDs.

Supertypes: CommonCircuitQueryProperties

names

Property

Type: null | undefined

The names of the circuit or circuits to be returned.

globalIds

Property

Type: string[]

The global ID of the circuit or circuits to be returned.

locations

Property

Type: null | undefined

Specifies the location information for the feature associated with a circuit's starting or stopping point. The results can be filtered further when used with the locationType parameter.

locationType

Property

Type: null | undefined

QueryCircuitByLocationsProperties

Type definition

Parameters for querying circuits by circuit start or stop locations.

Supertypes: CommonCircuitQueryProperties

names

Property

Type: null | undefined

The names of the circuit or circuits to be returned.

globalIds

Property

Type: null | undefined

The global ID of the circuit or circuits to be returned.

locations

Property

Type: CircuitLocation[]

Specifies the location information for the feature associated with a circuit's starting or stopping point. The results can be filtered further when used with the locationType parameter.

locationType

Property

Type: "start" | "stop" | "all" | null | undefined

CircuitExportProperties

Type definition

Parameters for exporting circuits with export() or submitExportJob().

Supertypes: Pick<ExportCircuitsParametersProperties‚ "circuitNames" | "exportAcknowledgement" | "resultTypes" | "outSpatialReference">

CircuitVerifyProperties

Type definition

Parameters for verifying circuits with verify() or submitVerifyJob().

Supertypes: Pick<VerifyCircuitsParametersProperties‚ "circuitNames" | "forceVerify" | "synthesizeGeometries" | "outSpatialReference">