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 time series related config Refer geo view options below	No
debug	Object that holds results cache related config Refer debug options below	No

HTTP Config

Option	Description	Required	Default
port	The port for the server to listen on.	Yes
webroot	The path to the directory holding the application website.	No	webroot
staticCachingEnabled	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
tlsEnabled	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.	Yes
timezone	The timezone which the data belongs to.	Yes
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

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
issuer	Domain url for token issuer	Yes, if type is not NONE	""
audience	API audience for the server	Yes, if type is not NONE	""
permissionKey	The permissions key in the token that has the permissions for audience. It's permissions for Auth0 and roles for EntraId.	No	"permissions"
defaultApiClaim	Default API claim	No	"read:ewb"
allowAllPermissions	Boolean flag to disable Authorisation - all claims will be accepted when authorising. Not recommended for production use cases.	No	false

For instance, for EntraId, use the following example (the url have to be used the way as in the example, or it won't work):

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

For an Auth0 config:

"auth": {
    "authType": "auth0",
    "issuer": "zepben-dev.au.auth0.com",
    "audience": "https://some-audience/",
    "defaultApiClaim": "read:ewb"
}

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

caution

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

The following is a sample configuration file:

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"
  }
}

---

Run

Command Line Arguments

Flag	Valid Values	Required	Default
-c, --conf	Path to the configuration file	No	energy-workbench-server-conf.json
-s0, --suppress-zero-length	Suppress the logging of zero length energy profile warnings	No	Log warnings

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.