Overview

The EWB Server is the primary server that supplies APIs to access network and time series data, as well as provides web apps that provide visualisations and other high level functionality related to the data from the APIs.

This document describes how to configure and run the energy workbench server.

---

Configuration

Configuration for the energy workbench server is specified in a JSON file.

Key	Description	Required
http	Object that holds http related config. Refer http config options below.	Yes
ewbData	Object that holds the ewb data related config. Refer ewb data config options below.	Yes
auth	Object that holds the auth related config. Refer auth config options below.	No
syslog	Object that holds system log related config for Nix based systems Refer system log options below.	No
geoView	Object that holds map tile related config Refer geo view options below.	No
publicGeoView	Object that holds map tile related config for the public map tile endpoint Refer geo view options below.	No
debug	Object that holds results cache related config Refer debug options below.	No
scada	Object that holds SCADA related config Refer SCADA options below.	No
currentState	Object that holds current state processing related config Refer current state processing options below.	No
voltageLevel	Object that holds voltage level related config Refer voltage level options below.	No
graphQl	Object that holds GraphQL related config Refer GraphQL options below.	No

HTTP Config

Option	Description	Required	Default
port	The port for the server to listen on for REST/GraphQL requests.	Yes
grpcPort	The port for the server to listen on for gRPC requests.	Yes
webroot	The path to the directory holding the application website.	No	webroot
mapSymbolsPath	The path to the directory holding the map symbol SVG's.	No	webroot/images/map-symbols
staticAssetCaching	Flag to indicate whether static caching is enabled.	No	true
cors	Allows you to specify hosts to add to the CORS (cross origin resource sharing) white list.	No	None
compression	The type of compression to use for gRPC.	No	identity
isTlsEnabled	Enable HTTPS on the web server.	No	false
keyPath	The path to the PEM private key file.	No
certPath	The path to the PEM certificate for the provided private key.	No
caPath	The path to a PEM CA chain for client authentication.	No
clientAuth	Whether client authentication should be enabled. One of request, required, or none, meaning client auth is optional (client can request), required (client must present a signed certificate by a CA in caPath), or no client auth is available respectively.	No	none

EWB Data Config

Option	Description	Required	Default
path	The path to the ewb data directory. When AWS related keys are specified, this is the path where EWB downloads the files from S3.	Yes
timezone	The timezone which the data belongs to.	Yes
loadDatabase	Configures connection to the database holding load data for customers. Refer DB config options below.	Yes, if inputDatabase is defined
inputDatabase	Configures connection to the database holding, among other things, PV/EV/BESS profiles. Refer DB config options below.	No
loadIntervalLengthMinutes	The length of a load interval in minutes. This should match the interval length used in the loadDatabase. Supported values: 15, 30	No	30M
previousDaysToSearchForNetwork	Number of days to search the network back from the current date.	No	0
previousDaysToSearchForDiagram	Number of days number of days prior to the date of the network-model database being loaded to search for a diagrams database, if an exact match did not exist.	No	0
previousDaysToSearchForCustomer	Number of days number of days prior to the date of the network-model database being loaded to search for a customer database, if an exact match did not exist.	No	0
cachePeriod	Limits the amount of load data available in the server. Specified in days unless a units character is appended. Valid unit characters: 'd' (days), 'm' (months), 'y' (years).	No	All
resultsCacheTtlSeconds	The time to live for the results cache.	No	0
connectionPointIdentifier	The name of the identifier used for connection points.	String	NMI
excludeCustomers	Indicates that customers should be excluded from the EWB database load. Must be set to true if you do not have a customer database.	Boolean	false
networkDate	When set EWB will only attempt to load a network-model database of this date.	No
awsRegion	When set EWB will use this value as part of the AWS S3 URI of database files.	Yes, if awsBucket is defined
awsBucket	When set EWB will use this value as part of the AWS S3 URI of database files.	Yes, if awsRegion is defined
azureStorageAccountName	When set EWB will use this value as part of the Azure Blob Storage URI of database files.	Yes, if azureStorageContainerName is defined
azureStorageContainerName	When set EWB will use this value as part of the Azure Blob Storage URI of database files.	Yes, if azureStorageAccountName is defined
shouldInferPhases	Indicates if de-energised phases should be inferred when possible.	No	false
changeSets	Configures the loading and applying of change sets. Refer Change Set Config below.	No

tip

• To use AWS S3, see default credentials provider chain to set up authentication.
• To use Azure Blob Storage, see Default credentials provider chain to set up authentication.

DB Config

The following options can be used to configure a connection to a PostgreSQL database:

Option	Description	Required	Default
host	The hostname of the PostgreSQL server.	Yes
port	The port of the PostgreSQL server.	No	5432
name	The name of the PostgreSQL database.	Yes
username	The username to use to connect to the PostgreSQL server.	Yes
password	The password to use to connect to the PostgreSQL server.	Yes

Change Set Config

Option	Description	Required	Default
enabled	Controls if change set processing is enabled or not. When disabled, no change set processing will be performed even if configured.	No	false
applyToBase	A list of change set names that should be applied to the base model.	No	none
failOnMissing	Indicates if the server should fail to start if a specified change set can't be found, rather than ignoring it.	No	true

Auth Config

Option	Description	Required	Default
authType	Auth method to be used Valid values: AUTH0, EntraID,NONE AUTH0 and EntraId use Auth0 or EntraId OAuth2 implementation respectively. NONE to disable auth.	Yes, if auth defined	NONE
trustedIssuers	List of domain URL's for token issuers to be trusted by EWB.	Yes, if type is not NONE	""
audience	API audience for the server.	Yes, if type is not NONE	""
allowAllPermissions	Boolean flag to disable Authorisation - all claims will be accepted when authorising. Not recommended for production use cases.	No	false
verifyCertificates	Verify server certificates when fetching JWKS keys from each issuer in the trustedIssuers list.	No	true
grpcScopes	Object that holds the gRPC scopes. Refer gRPC scopes config options below.	No

Note: Auth claims must have the read:ewb role/permission when authentication is enabled

EntraID

{
  "auth": {
    "authType": "entraid",
    "trustedIssuers": [
      "https://login.microsoftonline.com/<tenant>/v2.0"
    ],
    "audience": "982374979-23492837492-23423874987289asjdf"
  }
}

info

For EntraId, you must use the URL as shown in the example; otherwise, it won’t function correctly.

Auth0

{
  "auth": {
    "authType": "auth0",
    "trustedIssuers": [
      "zepben-dev.au.auth0.com"
    ],
    "audience": "https://some-audience/"
  }
}

gRPC Scopes Config

When using any of the token based authentication methods, the following options configure the scopes that must be found in the token in order to access the service. These should be configured to match the scopes you have defined in the external auth workflow (i.e. Auth0 or EntraID).

Option	Description	Required	Default
zepben.protobuf.nc.NetworkConsumer	The scope required to access the network consumer service.	No	read:ewb
zepben.protobuf.dc.DiagramConsumer	The scope required to access the diagram consumer service.	No	read:diagram
zepben.protobuf.cc.CustomerConsumer	The scope required to access the customer consumer service.	No	read:customer
zepben.protobuf.ns.UpdateNetworkStateService	The scope required to access the update network state service.	No	write:ewb

Example:

{
  "auth": {
    ...
    "grpcScopes": {
      "zepben.protobuf.nc.NetworkConsumer": "my-network-read-access",
      "zepben.protobuf.dc.DiagramConsumer": "my-diagram-read-access",
      "zepben.protobuf.cc.CustomerConsumer": "my-customer-read-access",
      "zepben.protobuf.ns.UpdateNetworkStateService": "my-network-write-access"
    }
  }
}

System Log Config

Option	Description	Required	Default
facility	The facility code to specify the type of program logging the message. Valid Values : SYSLOG, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7	No
tag	The tag for the log message.	With facility

Geographic View Config

Option	Description	Required	Default
tileSize	The size of the tiles to produce.	No	4096
maxZoom	The maximum supported zoom level.	No	20
mapboxApiToken	The API token required to render MapBox tiles.	No	invalid token
keepLevelSpec	The keep level specification to be used for vector tiles.	No	null
maxCacheSize	The maximum size in MB for tiles in the memory tile cache.	No	512
cacheWritePeriod	The time period in seconds between batch writes of the MVTs in memory to be written to disk. A value of 0 will disable disk writes.	No	10
minPointsToWrite	The minimum number of points on a tile for it to be written to the disk cache.	No	1000
switchNamePattern	A regex pattern with a maximum of one group to extract switch names for visualisation on the map. If a single regex grouping is provided the group will be returned as the switch name. If the pattern doesn't match the switch name will not be included. Default is no switch names in the map tiles.	No	null

Debug Config

Option	Description	Required	Default
logRoutes	Indicates if the server should print all registered routes on start-up	No	false
logExceptions	Enable stacktrace loggin when the server response with a 500	No	true
logRequests	Indicates if the server should print all requests received	No	true
logRequestBodyToFile	Specifies a file to save the last received request body	No
suppressZeroLength	Suppress the logging of zero length energy profile warnings	No	false

caution

If any paths in the configuration are given as relative paths, they will be relative to the working directory of the JVM.

SCADA Config

Option	Description	Required	Default
host	The host name of the server hosting the SCADA GetPowerData service.	Yes
port	The port number of the server hosting the SCADA GetPowerData service.	Yes
basePath	Any base path being used to proxy the SCADA GetPowerData service. Must include any leading /.	Yes

Current State Processing Config

The following options can be used to customise the current state processing:

Option	Description	Required	Default
fromSystemTag	The system tag used to identify the id's passed to the current state processor. To use the mRID of the network objects set this to "EWB".	No	GIS
backlog	Optional configuration to enable pulling of a backlog of current state events at start-up. If not specified, backlog processing is disabled. Refer Backlog Configuration below.	No	null
debug	Whether to enable extra debug logging on current state events. Will add reporting for number of EnergyConsumers possibly impacted by changes to the dynamic state. There is a small performance impact to state changes by enabling this setting.	No	false

Example:

{
    "currentState": {
        "fromSystemTag": "GIS",
        "backlog": {
            "grpcChannelMode": "Insecure",
            "host": "ewb.zepben.com",
            "port": 50051,
            "sinceDays": 30,
            "verifyCertificates": false
        },
        "debug": true
    },
}

Current State Backlog Config

Option	Description	Required	Default
host	The host name of the service used to retrieve the backlog of current state events.	Yes
port	The port of the service used to retrieve the backlog of current state events. Must be between 1 and 65535.	Yes
sinceDays	The amount of days before the until date to be considered as backlog events.	No	30
until	The final time point to be considered as backlog events.	No	Current Time
grpcChannelMode	The gRPC channel mode specifying how the connection to the service is secured or authenticated. One of Insecure, Tls, SecretAuthorIdentityAuth`.	No	Insecure
clientId	The client ID used for authentication when grpcChannelMode is set to SecretAuth.	For SecretAuth	""
clientSecret	The client secret used for authentication when grpcChannelMode is set to SecretAuth.	For SecretAuth	""
audience	The audience used for authentication when grpcChannelMode is set to SecretAuth.	For SecretAuth	""
issuer	The issuer URL used for authentication when grpcChannelMode is set to SecretAuth.	For SecretAuth	""
authMethod	The authentication method used for securing the connection. One of NONE, OAUTH, or ENTRAID.	For SecretAuth	NONE
identityUrl	The identity provider URL required when grpcChannelMode is set to IdentityAuth.	For IdentityAuth	""
authCAFilename	The filename of the certificate authority file for authentication. If provided, the file must exist.	No	null
caFilename	The filename of the certificate authority file used to validate the server's certificate. If provided, the file must exist.	No	null
verifyCertificates	Enable (true) or disable (false) certificate verification in the backlog client connection.	No	true

Voltage Level Config

The following options can be used to customise the network voltage level assignment in the mapbox vector tiles:

Option	Description	Required	Default
unknownLevelLvLimit	The upper voltage (in volts) of items to assign to the LV voltage level if the level can't be determined by the containers of the item. Items above this voltage will be processed with [unknownLevelHvLimit].	No	1000
unknownLevelHvLimit	The upper voltage (in volts) of items to assign to the HV voltage level if the level can't be determined by the containers of the item. Items above this voltage will be assigned to the EHV level.	No	22000
ehvPoleClassification	A set of classifications that indicate a pole carries equipment at the EHV level.	No	[]
hvPoleClassification	A set of classifications that indicate a pole carries equipment at the HV level.	No	[]
lvPoleClassification	A set of classifications that indicate a pole carries equipment at the LV level.	No	[]

GraphQL Config

The following options can be used to customise the GraphQL processing:

Option	Description	Required	Default
maxIdentifiedObjects	The maximum number of identified objects that can be returned by the getIdentifiedObjects GraphQL query.	No	100
numWorkerThreads	The number of GraphQL worker threads to add to the pool for handling GraphQL requests.	No	4

Sample Configuration File

The following is a sample configuration file:

{
  "http": {
    "port": 9000,
    "webroot": "/Users/zepben/Desktop/Zepben/Client/web-client/dist",
    "staticCachingEnabled": false,
    "cors": ".*"
  },
  "ewbData": {
    "path": "/Users/zepben/Desktop/Zepben/Server/EnergyWorkbench/ewb",
    "previousDaysToSearchForNetwork": 365,
    "timezone": "Australia/Melbourne",
    "cachePeriod": "1m",
    "resultsCacheTtlSeconds": 90000
  },
  "syslog": {
    "facility": "SYSLOG",
    "tag": "EWB"
  },
  "graphQl": {
    "maxIdentifiedObjects": 1000,
    "numWorkerThreads": 10
  }
}

---

Run

Command Line Arguments

Flag	Valid Values	Required	Default
-c, --conf	Path to the configuration file	No	energy-workbench-server-conf.json

To run the server, execute the following command at a terminal where <heap size> is the desired size of the heap (e.g. 16g):

java -Xmx<heap size> -Xms<heap size> -jar <path to energy-workbench-server-jar> --conf <path to config file>

Heap Size Estimation

Because you are running up a server with large network models and a lot of load profiles, you will need to increase the heap size for the JVM instance

using the appropriate JVM flags:

A network with 500,000 HV assets requires around 8GB.
Load points for around 100,000 distribution transformers require 20GB/year.
Weather Data from 100 weather stations would require around 512MB/year.
Depending on the API usage the JVM would require more than 8GB.

ewb_server.sh

As the server runs as a server (that is generally as a background process but at the very least as a process that does not just finish after a task is done) a script is provided to more easily start and stop the server. The script will make sure if there is a EWB server instance already running it will not start a second instance.

The script can be found at EWB_RELEASE_DIR/bin/ewb_server.sh.

The underlying java command that starts the server can be configured in the ewb.conf configuration file. See the deployment documentation for more information on ewb.conf.

To start the EWB server using this script:

EWB_RELEASE_DIR/bin/ewb_server.sh start

To stop the EWB server using this script:

EWB_RELEASE_DIR/bin/ewb_server.sh stop

note

The ewb_daily.sh script relies on the ewb_server.sh script to stop and start the server.