Version: 2.11.0

Input Files

Required Input Files

The following files are required for the GIS Network Extractor to run:

File(s)	Data type	Default location
Processor Config	Single .json file	./processor-config.json
Cable Types	Single .json file	./cable-types.json
Network Hierarchy	Single .json file	./network-hierarchy.json
Nodes Config	Single .json file	./nodes-config.json
Poles	Single .json file	./poles.json
GIS Network files	Single or multiple .json/.geojson files	./gis

Optional Files

The following files may be provided as input for the GIS Network Extractor, however they are not required:

File(s)	Data type	Default location
Meter Mapping	Single or multiple.csv files	./meter_mappings

Meter Mapping File

The GIS Network Extractor takes meter mapping files to provide a mapping of meters and supply points to transformers. These files use CSV format and contain the following columns: company, nmi,meter_id, supply_point_id, meter_no, transformer_id, transformer_desc, feeder, service_addr, cust_class, cust_tariff. Each file is required to have its date in the file name so the appropriate mapping file can be used.

Sample content:

company,nmi,meter_id,supply_point_id,meter_no,transformer_id,transformer_desc,feeder,service_addr,cust_class,cust_tariff
"ACME","FOOH1234567",123456789,11929433,"1234",,,"LP001","140 THISSON STREET,SPRINGFIELD,SPF,12345A","C","T1"
"ACME","FOOH1234567",123456789,11929433,"1234",,,"LP002","140 OTHERSON STREET,SPRINGFIELD,SPF,12345A","R","T1"
"ACME","FOOH1234567",123456789,11929533,"1234",,,"LP003","LEVEL44,76 WOOP WOOP STREET,SPRINGFIELD,SPF,12345A","I","T2"
"ACME","FOOH1234567",123456789,11929538,"1234",,,"LP004","WEST TOWER,76 WOOP WOOP STREET,SPRINGFIELD,SPF,12345A","I","T1"
"ACME","FOOH1234567",123456789,11929538,"1234",,,"LP006","WEST TOWER,76 WOOP WOOP STREET,SPRINGFIELD,SPF,12345A","C","T1"
"ACME","FOOH1234567",123456789,11929538,"1234",,,"LP007","TENANCY2,OPP 76 WOOP WOOP STREET,SPRINGFIELD,SPF,12345A","I","T3"
"ACME","FOOH1234567",123456789,11929538,"1234",,,"LP008","TENANCY1,OPP 76 WOOP WOOP STREET,SPRINGFIELD,SPF,12345A","R","T3"

Processor Config File

The processor configuration allows specifying whether some of the processing steps will be executed, as well as allows filtering of what data will be ingested and saved to the resulting database. If a config file is not specified or present, defaults will be as per below.

Structure:

{
  # Whether meter data should be processed (if true a meter mappings file must be provided)
  # Default: true
  "processMeters": boolean,
  
  # Whether the Sub-transmission network should be ingested (must be in a file name like SUB_TRANS_NETWORK.*.json
  # Default: true
  "includeSubtrans": boolean,
  
  # HV filters (see below). 
  # Default: null
  "hv": null | {  # Exactly one of the following fields must be set
        "include": ["<feeder_name_1>", "<feeder_name_2>", ...]
        "exclude": ["<feeder_name_1>", "<feeder_name_2>", ...]
  },
  
  # Whether LV should be saved to the database. 
  # Default: true
  "includeLV": boolean
  
}

####### Filters and includeLV

Filters allow specifying which feeders get processed and stored in the result, however there are file name requirements that must be met for filters to work as intended. For the most efficient handling of data, separate files should exist for HV and LV network, and they must be named accordingly in the form below:

HV Files: <feeder_name>_mv.[geo]json
LV Files: <feeder_name>_lv.[geo]json

includeLV: false will only work efficiently if LV files are named in this form, as they will be excluded from the ingest process.

You can filter only at the HV level, and you can specify only one of the include/exclude filters. For HV filters the filter is based on the feeder name, and the feeder name must be at the start of the filename.

An include filter will include only feeders with filenames that start with any of the given strings, and conversely an exclude filter will exclude any feeders with filenames that start with any of the given strings in the same way.

Note the strings are not pattern matches and no regex is supported.

Sample content:

Include 2 HV feeders and their LV but without meter processing or subtrans network.

{
    "processMeters": false,

    "includeSubtrans": false,

    "hv": { 
        "include": ["FNA001", "FNA002"]
    },

    "includeLV": true
}

Include 2 HV feeders, plus sub-trans with meter processing, but no LV.

{
    "hv": { 
        "include": ["FNA001", "FNA002"]
    },

    "includeLV": false
}

Two HV feeders and their LV, plus sub-trans with meter processing.

{
    "hv": { 
        "include": ["FNA001", "FNA002"]
    }
}

Cable Types File

The GIS Network Extractor derives cable type information from a json file structured as follows:

{
    "cableTypes": [{
            "id": string,
            "resistance": double,
            "reactance": double,
            "zeroSeqResistance": double,
            "zeroSeqReactance": double,
            "nominalVoltage": double,
            "rating": int,
            "maxFaultCurrent": double,
            "normalRating": double,
            "springDay": double,
            "springNight": double,
            "summerDay": double,
            "summerNight": double,
            "autumnDay": double,
            "autumnNight": double,
            "winterDay": double,
            "winterNight": double,
            "neutralRating": double
        }
    ]
}

If you have a running copy of the Energy Workbench Server you can download the existing cable types.

Sample content:

{
  "cableTypes": [
    {
      "id": "Cu_0.1i_SWAS_SD_11_6",
      "resistance": 0.342,
      "reactance": 0.115,
      "zeroSeqResistance": 0.795,
      "zeroSeqReactance": 0.066,
      "nominalVoltage": 11,
      "rating": 215,
      "maxFaultCurrent": 10.1,
      "normalRating": 1,
      "springDay": 1,
      "springNight": 1,
      "summerDay": 1,
      "summerNight": 1,
      "autumnDay": 1,
      "autumnNight": 1,
      "winterDay": 1.14,
      "winterNight": 1.14,
      "neutralRating": 215
    },
    {
      "id": "Cu_0.25i_pswsb_SD_6.6_3",
      "resistance": 0.133,
      "reactance": 0.074,
      "zeroSeqResistance": 0.95,
      "zeroSeqReactance": 0.541,
      "nominalVoltage": 6.6,
      "rating": 345,
      "maxFaultCurrent": 10.1,
      "normalRating": 1,
      "springDay": 1,
      "springNight": 1,
      "summerDay": 1,
      "summerNight": 1,
      "autumnDay": 1,
      "autumnNight": 1,
      "winterDay": 1.117,
      "winterNight": 1.117,
      "neutralRating": 345
    }
  ]
}

Network Hierarchy File

The GIS Network Extractor derives network hierarchy information from a json file structured as follows:

{
    "businesses": [{
        "id": string,
        "name": string,
        "regions": [{
            "id": string,
            "name": string,
            "zones": [{
                "id": string,
                "name": string,
                "feeders": [{
                    "id": string,
                    "name": string
                }]
            }]
        }]
    }]
}

If you have a running copy of the Energy Workbench Server you can download the existing network hierarchy.

Sample content:

{
  "businesses": [
    {
      "id": "business1",
      "name": "BUSINESS1",
      "regions": [
        {
          "id": "region1",
          "name": "REGION1",
          "zones": [
            {
              "id": "zone1",
              "name": "ZONE1",
              "feeders": [
                {
                  "id": "feeder1",
                  "name": "FEEDER1"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Nodes Config File

The GIS Network Extractor derives node configuration information from a json file structured as follows:

Structure:

{
  "mappings": [
    {
      "gisClass": "<gis-node-class>",
      "cimClass": "<conducting-equipment-class>",
      "style": "<diagram-object-style>"
    },
    ...
  ],
  "switchStyles": [
    {
      "value": "<attribute-value>",
      "style": "<diagram-object-style>"
    },
    ...
  ]
}

Sample content:

{
  "mappings": [
    {
      "gisClass": "acr",
      "cimClass": "Recloser",
      "style": "RECLOSER"
    },
    {
      "gisClass": "hvSwitch",
      "cimClass": "Disconnector",
      "style": "SWITCH"
    }
  ],
  "switchStyles": [
    {
      "value": "bridge",
      "style": "BRIDGE"
    },
    {
      "value": "air-break",
      "style": "SWITCH"
    },
    {
      "value": "live line clamp",
      "style": "LIVE_LINE_CLAMP"
    }
  ]
}

Required Input Files​

Optional Files​

Meter Mapping File​

Sample content:​

Processor Config File​

Structure:​

Sample content:​

Cable Types File​

Sample content:​

Network Hierarchy File​

Sample content:​

Nodes Config File​

Structure:​

Sample content:​

Required Input Files

Optional Files

Meter Mapping File

Sample content:

Processor Config File

Structure:

Sample content:

Cable Types File

Sample content:

Network Hierarchy File

Sample content:

Nodes Config File

Structure:

Sample content: