Configuration

Configuration for the Evolve App Server is specified in a JSON file. The server requires a configuration file to start. The config file can contain the following JSON object:

Key	Description	Required
server	Object that holds http related config. Refer server config options below	Yes
ewb	Object that holds the ewb server related config. Refer ewb config options below	Yes
database	Object that holds the database config. Refer database config options below	Yes
auth	Object that holds the config for the client authentication method Refer auth_config options below	Yes
ui	Object that holds the config provided to the UI Refer ui config options below	No
powerFactoryModel	Object that holds the power-factory-model related configuration Refer power-factory-model options below	No
hostingCapacity	Object that holds the hosting capacity related configuration Refer hosting capacity options below	No
airflow	Object that holds the Airflow related configuration for use by the Admin Service Refer airflow options below	No
metricsDatabase	Object that holds the metrics database config. Refer database config options below	No
sincalModel	Object that holds the Sincal Model Service config. Refer sincal model config options below	No
jwks	Object that holds the JWKS config. Refer jwks config options below	No
ingestor	Object that holds the Ingestor Service config. Refer ingestor config options below	No

Server Config

Option	Description	Required	Default
host	The host for the server.	No	"localhost"
port	The port for the server to listen on.	No	433 if useTLS is true, otherwise 80
useTls	Enable HTTPS on the server	No	false
keyStorePath	Path to a Java Key Store that contains credentials for TLS	No	Will disable TLS if missing
keyStorePassword	Password to access the Java Key Store above	No
privateKeyAlias	The alias to the private key to use for TLS, contained within the Java Key Store above	No
privateKeyPassword	The password to the private key to use for TLS, contained within the Java Key Store above	No
webClientHost	The host for the Web Client	No	host
webRoot	Path to a directory that contains the static assets for the web client	Yes	"static"
logFile	Path to a file to write log output to	No

Example Server Config:

{
  "server": {
    "host": "0.0.0.0",
    "useTls": true,
    "keyStorePath": "keystore.jks",
    "privateKeyAlias": "ewb.local",
    "keyStorePassword": "zepben",
    "privateKeyPassword": "zepben",
    "webClientHost": "*",
    "port": 7654,
    "webRoot": "static",
    "logLevels": {
      "ROOT": "INFO",
      "Server": "DEBUG"
    }
  }
}

EWB Config

Option	Description	Required	Default
host	The host for EWB server	No	"localhost"
port	The port on which to find the EWB server	No	9000
protocol	The protocol to use when making requests to the EWB server - HTTP or HTTPS	No	"HTTP"
auth	The property that specifies m2m authentication parameters for an authenticated EWB server. Refer to ClientCredentialsAuth options below	No
verifyCertificate	The verification for the SSL cert when connecting to the services over TLS	No	"true"
connectionPointIdentifier	Specify the NameType name used by EWB to store the connection point identifier	No	"NMI"

Client Credentials Auth Config

NOTE: To configure no authentication between EAS and EWB, omit the ewb.auth block completely.

Option	Description	Required	Default
method	The auth method to use for authentication with EWB (AUTH0, ENTRAID)	Yes
issuer	The issuer domain for authentication using a client_credentials Oauth2 flow	Yes, unless using Managed Identity tokens with EntraID
audience	The audience for authentication with auth0	Yes, unless using Managed Identity tokens with EntraID
clientId	The clientId which is used by the client in order to authenticate	Yes
clientSecret	The clientSecret which is used by the client in order to authenticate	Yes, for regular auth. For Managed Identity should be skipped

NOTE: to use Managed Identity tokens with EntraID, do not provide clientSecret in the configuration (only the clientId).

Example EntraID EWB Config:

{
  "ewb": {
    "host": "localhost",
    "port": 9000,
    "protocol": "HTTP",
    "auth": {
      "method": "entraid",
      "audience": "12341234-1234-4321-1234-123412341234",
      "issuer": "https://login.microsoftonline.com/12345678-2222-3333-4444-1234546781234/v2.0",
      "clientId": "s8df79as7d9f87a9sd7f7",
      "clientSecret": "laksjdflkjasdlfk"
    }
  }
}

Database Config

Option	Description	Required	Default
url	The url to use to connect to the database	No	"jdbc:h2:mem:mem;DB_CLOSE_DELAY=-1;DATABASE_TO_LOWER=TRUE;"
driver	The database driver to use	No	"org.h2.Driver"
updateSchemaOnStart	If set to true, the app server will attempt to initialise and/or update the database schema and default data (including roles and permissions) on startup.	No	true
sqlDirs	A list of paths to directories containing ".sql" files. On startup, every ".sql" file will be executed against the database	No

Example Database configuration:

{
  "database": {
    "url": "jdbc:postgresql://<hostname>/<database-name>?user=<user>&password=<password>",
    "driver": "org.postgresql.Driver",
    "updateSchemaOnStart": true,
    "sqlDirs": [
      "./scripts/sql"
    ]
  }
}

Auth Config

Method	Description	Required
auth0	Configures authentication through Auth0. Refer auth0 options below	No, mutually exclusive with others
entraId	Configures authentication through EntraID. Refer entraID options below	No, mutually exclusive with others
none	It allows for unauthenticated access to the server Refer auth none options below	No, mutually exclusive with others

Auth0/EntraID Config

Option	Description	Required	Default
method	The method to use to authenticate (auth0, entraid)	Yes
trustedIssuers	The list of issuers to accept tokens from	Yes
audience	The audience for authentication	Yes
publicAccess	Object that holds the configuration to allow limited access to unauthenticated users Refer public access options	No	Disabled if no present

Example Auth0 configuration:

{
  "auth": {
    "method": "auth0",
    "trustedIssuers": ["https://zepben-dev.au.auth0.com"],
    "audience": "https://evolve-ewb/"
  }
}

Public Access Config

Option	Description	Required	Default
enabled	Allow requests from un-authenticated users that inherit limited permissions.	No	false
permissions	The list of permissions(not roles) to provide to un-authenticated users when public access in enabled. Note: Unauthenticated users' map tile requests will always directed to EWB's public tile endpoint.	No	[]

Example Public Access configuration:

{
  "auth": {
    "method": "auth0",
    "trustedIssuers": ["https://zepben-dev.au.auth0.com"],
    "audience": "https://evolve-ewb/",
    "publicAccess": {
      "enabled": true,
      "permissions": [
        "OPPORTUNITIES:READ",
        "LOCATION_SERVICE:READ"
      ]
    }
  }
}

Auth None Config

Option	Description	Required	Default
defaultUsername	The id for the default user	Yes
defaultUserEmail	The email for the default user	Yes
defaultUserRoles	The roles that will be inherited by the default/unauthenticated user	Yes

Jwks Config

Option	Description	Required	Default
currentUserSigningKey	The key name to use for generating jwks for users.	No	"current-user"
currentMachineSigningKey	The key name to use for generating jwks for machines.	No	"current-machine"
issuer	The issuer url of the jwks.	No	"https://localhost:7654"

Example Jwks configuration:

{
  "jwks": {
    "currentUserSigningKey": "current-User-Signing-Key",
    "currentMachineSigningKey": "current-Machine-Signing-Key"
    }
}

UI Config

Option	Description	Required	Default
defaultScreen	The default screen to open when the UI is opened. "map" for the network map or "fault_location" for the fault location overlay	No	map
studiesEnabled	Whether studies are enabled in the UI. true for enabled, false for disabled.	No	true
profilesTrendDisplayEnabled	Whether the Trend Display module under Profiles is enabled in the UI. true for enabled, false for disabled.	No	false
profilesSubstationLoadAnalysisEnabled	Whether the Substation Load Analysis module under Profiles is enabled in the UI. true for enabled, false for disabled.	No	false
defaultMapLayerColors	Define default map layer colors to be rendered for all themes. Refer Map layer colors below.	No
themes	An array of objects to define the styling and colors of the map. Refer Themes below	No
defaultTheme	Specifies the default theme from themes to display by default.	No
powerFactoryExporterEnabled	Whether the Power Factory Exporter Module is enabled in the UI. It requires powerFactoryExporterOptions as well.	No
powerFactoryExporterOptions	Specifies the Exporter Options to be enabled if powerFactoryExporterEnabled is true. Refer Exporter Options below.	No
sincalExporterEnabled	Whether the Sincal Exporter Module is enabled in the UI. It requires sincalExporterOptions as well.	No
sincalExporterOptions	Specifies the Exporter Options to be enabled if sincalExporterEnabled is true. Refer Exporter Options below.	No
workPackageBrowserEnabled	Whether the Work Packages Module is enabled in the UI.	No	false

Exporter Options

Option	Description	Required	Default
enableInternalNodes	This allows user to add the Internal Substation Nodes in the "Network Hierarchy Explorer"	Yes	false
enableLVFeeders	This enables the Show LV Feeders switch in the UI which a user can use to interact with the LV section of the network.	Yes	true

Themes

Option	Description	Required	Default
name	Name of the theme (for display purposes only).	yes
sourceUrl	mapbox-gl URL to fetch theme from.	yes
thumbnailUrl	File path for EAS thumbnail image. See the sample configuration for examples - paths must be present in network-map.	yes
layerColors	Define layer specific colours for this theme. Properties not set will use values from defaultMapLayerColors. Refer Map layer colors below	No

Note that for layerColors any top-level property that is not set the default will be used from defaultMapLayerColors. This means that if you do not specify voltage within layerColors you will get the default voltage coloring. It's important to note that this will only apply to top-level properties listed in Map layer colors below. For example, if you override phases you should set colours for all possible phases in your network, otherwise unmatched phases will default to black.

Map Layer Colors

If not configured defaults will be determined by the network map configuration.

Option	Description	Required	Default
phases	An object mapping phase codes to hex color codes. Refer phase below.	No
pen	A list of hex color codes to be cycled through when coloring arbitrary groupings of lines.	No
voltage	An array of objects with keys of range and colors to define voltage ranges and their hex color codes. Refer voltage below.	No
offSupply	A list of hex color codes to be used to denote off-supply lines.	No
highlight	A default hex color code to be used when highlighting lines.	No
missingVoltage	Color for lines with voltages that are not covered in any range under voltage.	No
partiallyOffSupply	A list of hex color codes to be used to denote partially off-supply lines.	No
containerColors	An object mapping EquipmentContainer mRIDs to hex color codes. Refer container colors below.	No
enableColorOverrides	A boolean type field to disable picking the color from local storage. Refer enable color overrides below.	No

Phase

Possible phase codes: A, B, C, AB, AC, BC, ABC, AN, BN, CN, ABN, ACN, BCN, ABCN, X, Y, YX, XN, YN, YXN, NONE

Example color configuration:

{
  "phases": {
    "A": "#FF0000",
    "B": "#00FF00",
    "C": "#0000FF",
    "AB": "#FF8800",
    "AC": "#7c4cad",
    "BC": "#00BB00",
    "ABC": "#000000",
    "AN": "#BB0000",
    "BN": "#BBBB00",
    "CN": "#0000BB",
    "ABN": "#BB6600",
    "ACN": "#73479b",
    "BCN": "#008800",
    "ABCN": "#444444",
    "X": "#bb6666",
    "Y": "#444488",
    "YX": "#AAAAAA",
    "XN": "#AAAAAA",
    "YN": "#AAAAAA",
    "YXN": "#AAAAAA",
    "NONE": "#CCCCCC"
  }
}

If a PhaseCode is omitted it will default to black.

Pen

Pen colors will be used when coloring lines by "Container" if the containerColors option is not specified.

Voltage

To define voltage colors you must define a range and color which should be used for that range. Note that for any voltage missing a color code and range will default to the missingVoltage color or black if none is set.

{
  "voltage": [
    {
      "range": [
        0,
        240
      ],
      "color": "#1FF0EA"
    },
    {
      "range": [
        400,
        4000
      ],
      "color": "#00CCFF"
    }
  ]
}

Container Colors

A mapping of EquipmentContainer mRIDs to a hex color code. Note that for any containers missing a color code they will default to black.

Example color configuration:

{
 "containerColors":  [
   {
     "mRID": "feeder#1",
     "color": "#FF0077"
   },
   {
     "mRID": "feeder#2",
     "color": "#99FF99"
   }
 ]
}

Enable Color Overrides

This will enable override of map layer colors from server config. If it is not required and developer want to use colors from localStorage, this can be set false or unset. Example:

{
  "enableColorOverrides": true
}

PowerFactoryModel Config Types

Type	Description	Required
http	Configures the power-factory-model functionality to use an external http server for the creation of power-factory-models. Refer power-factory-model http options below	No, mutually exclusive with mock
mock	Configures the power-factory-model functionality use a provided mock file as the result of any power-factory-model creation request. This is meant for testing purposes only Refer power-factory-model mock options below	No, mutually exclusive with http

Http PowerFactoryModel Config

Option	Description	Required	Default
host	The host for the network model creation service	Yes
port	The port for the network model creation service	Yes
modelsDir	Path to directory where all generated power-factory-models will be stored	Yes

Example PowerFactoryModel configuration:

{
 "powerFactoryModel": {
   "type": "http",
   "host": "localhost",
   "port": 8089,
   "modelsDir": "modelsDir"
 }
}

Mock PowerFactoryModel Config

Option	Description	Required	Default
mockModelPath	Path to the file to be used as a mock for all power-factory-model creation requests	Yes
modelsDir	Path to directory where all generated power-factory-models will be stored	Yes

Hosting Capacity Config

Type	Description	Required	Default
service	Object that holds configuration related to connecting to a hosting capacity service. Refer to Hosting Capacity Service Config Type	No
resultDatabase	Object that holds configuration related to connecting to a hosting capacity results database. Refer to Hosting Capacity Results Database Config	No

Hosting Capacity Service Config Type

Type	Description	Required
http	Configures the hosting capacity functionality to use an external http server for running hosting capacity work packages. Refer hosting capacity http options below	No, mutually exclusive with mock
mock	Configures the hosting capacity functionality to use a mocked backend that will not actually run any hosting capacity work packages. This is meant for testing purposes only Refer hosting capacity mock options below	No, mutually exclusive with http

Http Hosting Capacity Service Config

Option	Description	Required	Default
host	The host for the hosting capacity service	Yes
port	The port for the hosting capacity service	Yes

Example Hosting Capacity Service configuration:

{
 "hostingCapacity": {
   "service": {
     "type": "http",
     "host": "localhost",
     "port": 9191
   }
 }
}

Mock Hosting Capacity Service Config

Option	Description	Required	Default
succeed	If true all hosting capacity calls will result in a successful response. If false all will result in a failure	Yes

Hosting Capacity Results Database Config

Option	Description	Required	Default
url	The JDBC URL to use to connect to the results database	Yes
driver	The database driver to use. If left unspecified, HikariCP will infer the driver from the JDBC URL.	No

Example Hosting Capacity Results Database configuration:

{
  "hostingCapacity": {
    "resultDatabase": {
      "url": "jdbc:postgresql://<hostname>/<database-name>?user=<user>&password=<password>",
      "driver": "org.postgresql.Driver"
    }
  }
}

Airflow Config

Option	Description	Required	Default
host	The host for the Airflow service	No	"localhost"
port	The port for the Airflow service	No	8080
protocol	The protocol to use when making requests to the Airflow server - HTTP or HTTPS	No	"HTTP"
verifyCertificate	The verification for the SSL cert when connecting to the Airflow service over TLS	No	"true"
username	The username to use when making requests to the Airflow service	Yes
password	The password to use when making requests to the Airflow service	Yes

Example Airflow configuration:

{
 "airflow": {
   "host": "localhost",
   "port": 8080,
   "protocol": "HTTP",
   "verifyCertificate": false,
   "username": "airflow_user",
   "password": "airflow_password123"
 }
}

Metrics Database Config

Option	Description	Required	Default
url	The JDBC URL to use to connect to the metrics database	Yes
driver	The database driver to use. If left unspecified, HikariCP will infer the driver from the JDBC URL.	No

Example Metrics Database configuration:

{
  "metricsDatabase": {
    "url": "jdbc:postgresql://<hostname>/<database-name>?user=<user>&password=<password>",
    "driver": "org.postgresql.Driver"
  }
}

Sincal Model Config

Option	Description	Required	Default
frontendExporterConfigDefaultsPath	Path of the JSON file used to constrain and provide defaults for frontend options for the Sincal Exporter.	Yes
backendExporterConfigPath	Path of the JSON file used to provide backend options for the Sincal Exporter.	Yes
execution	Object specifying the method of executing the Sincal Exporter. Refer sincal model execution options below.	Yes
storage	Object specifying the method of storing input and output files for the Sincal Model Service.	Yes
ewbAuthClient	Object specifying the OAuth client used by the Sincal Exporter. Refer sincal model EWB auth client options below.	No

Sincal Model Execution Config Types

Type	Description	Required
container	Configures the Sincal Model Service to execute the Sincal Exporter via a container platform (e.g. Docker). Refer sincal model container execution config below	No, mutually exclusive with mock
mock	Configures the Sincal Model Service to automatically fail or succeed in model creation rather than actually run the Sincal Exporter. This should only be used for testing purposes. Refer sincal model mock execution config below	No, mutually exclusive with container

Container Sincal Model Execution Config

Option	Description	Required	Default
template	Specifies how the container should be created. This includes the image and platform to run the container on. Refer container template options below	Yes
command	The command (CMD) to use when creating the container.	Yes	[]
ewbUrl	The address of EWB to use in the Sincal Exporter container. If left unspecified, the URL will be built from the EWB config.	No

Container Execution Options

Type	Description	Required
docker	Configuration for launching Docker containers. Refer docker container template config below	No, mutually exclusive other types
azure	Configuration for launching Azure container app jobs. Refer azure container template config below	No, mutually exclusive other types
ecs	Configuration for launching AWS Elastic Container Service tasks. Refer ecs container template config below	No, mutually exclusive other types

Docker Container Template Config

Option	Description	Required	Default
url	The address of the Docker daemon to run the container on.	Yes
certPath	The path of the SSL/TLS certificate store to use when connecting to the Docker daemon.	No
network	The name of the network to use for the container.	Yes	"bridge"
image	The name of the image to use for the container.	Yes

Azure Container Template Config

Option	Description	Required	Default
tenantId	The ID of the Azure tenant hosting the container app job.	Yes
subscriptionId	The ID of the Azure subscription for the container app job.	Yes
resourceGroup	The name of the Azure resource group for the container app job.	Yes
jobName	The name of the Azure container app job.	Yes
image	The name of the image of the to use for the container.	Yes

ECS Container Template Config

Option	Description	Required	Default
region	The AWS region to launch the container task in.	Yes
clusterName	The name of the cluster the container task will run on.	Yes
taskDefinitionArn	The ARN of the task definition to run.	Yes
containerName	The name of the container to be used.	Yes
assignPublicIp	Whether a public IP address will be assigned to the container running the task.	Yes
subnetIds	List of the subnetIds the task can be assigned. (actual subnet used depends on the Availability Zone the container is provisioned into)	Yes
securityGroupIds	List of the securityGroupIds the task will be assigned.	Yes

Mock Sincal Model Execution Config

Option	Description	Required	Default
succeed	If true all Sincal Exporter calls will result in a successful response. If false all will result in a failure.	Yes

Sincal Model Storage Config Type

Type	Description	Required
blob	Configures the Sincal Model Service to use Azure blob storage for input and output files. Refer sincal model blob storage config below	No, mutually exclusive with file
file	Configures the Sincal Model Service to use the local filesystem for input and output files. The download routes for output models do not work with this option. This should only be used for testing purposes. Refer sincal model file storage config below	No, mutually exclusive with blob

Blob Sincal Model Storage Config

Option	Description	Required	Default
blobServiceUrl	The URL of the Azure blob service endpoint.	Yes
inputBlobContainerName	The name of the container holding the input blobs.	Yes	"sincal-input"
templateBlobName	The name of the input blob for the template Sincal file.	Yes	"blank.sin"
standardDbBlobName	The name of the input blob for the standard database.	No
infeederMappingBlobName	The name of the input blob for the infeeder mapping.	No
protectionDevicesDbBlobName	The name of the input blob for the protection devices database.	No
outputBlobContainerName	The name of the container to hold the output blobs.	Yes	"sincal-output"

File Sincal Model Storage Config

Option	Description	Required	Default
templateBlobName	The path of the template Sincal file.	Yes
outputPath	The path to use for the output files. This should be a writable directory.	Yes

Sincal Model EWB Auth Client Config

Option	Description	Required	Default
clientId	The ID of the OAuth client to authenticate against.	Yes
clientSecret	The secret of the OAuth client to authenticate against.	Yes

Example Sincal Model Service configuration:

{
  "sincalModel": {
    "frontendExporterConfigDefaultsPath": "/path/to/defaultFrontendSincalConfig.json",
    "backendExporterConfigPath": "/path/to/backendSincalConfig.json",
    "storage": {
      "type": "blob",
      "blobServiceUrl": "https://replacewithstorageaccountname.blob.core.windows.net/",
      "inputBlobContainerName": "inputcontainer",
      "templateBlobName": "template.sin",
      "standardDbBlobName": "standard_db.sqlite",
      "infeederMappingBlobName": "mapping.csv",
      "protectionDevicesDbBlobName": "protection_devices.sqlite",
      "outputBlobContainerName": "outputcontainer"
    },
    "execution": {
      "type": "container",
      "template": {
        "type": "docker",
        "url": "tcp://localhost:2375",
        "image": "sincal-exporter-console-debug",
        "network": "host"
      },
      "ewbUrl": "http://host.docker.internal:9000"
    },
    "ewbAuthClient": {
      "clientId": "1234567890",
      "clientSecret": "swordfish"
    }
  }
}

Ingestor Service Config

Option	Description	Required	Default
runtime	Object specifying the method of executing the Ingestor Service. Refer ingestor container service runtime options below.	Yes

Ingestor Container Service Runtime Config

Option	Description	Required	Default
template	Specifies how the container should be created. This includes the image and platform to run the container on. Refer container execution options above	Yes
command	The command (CMD) to use when creating the container.	Yes	[]

Example Sincal Model Service configuration:

{
  "ingestor": {
    "runtime": {
      "template": {
        "type": "docker",
        "url": "unix:///run/docker.sock",
        "image": "zepben/ingestor_42342",
        "network": "host"
      }
    }
  }
}