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
feederLoadAnalysis	Object that holds the feeder-load-analysis related configuration Refer container-feeder-load-analysis config 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
ewbAdmin	Object that holds the EWB Admin Service related configuration Refer ewb admin 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
primaryEwbService	Object that holds the Primary EWB config. Refer Primary EWB config options below	No
temporal	Object that holds the Temporal service config. Refer Temporal config options below	No
openDssModel	Object that holds the OpenDSS Model Service config. Refer opendss model 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
maxConnectionLifetimeMs	The maximum lifetime of a connection in the connection pool before being replaced. Will not interfere with in use connections.	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
verifyCertificates	Verify server certificates when fetching JWKS keys from each issuer in the trustedIssuers list	No	true

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",
    "issuer": "https://dev.test-dev-env.example.com:7654"
  }
}

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
networkOpportunityAnalysisEnabled	Whether to fetch and show network opportunities on the map.	No	false
networkStateControlEnabled	Whether to allow the user to swap between viewing normal and current network state on the map.	No	false
workPackageBrowserEnabled	Whether the Work Packages Module is enabled in the UI.	No	false
hostingCapacityConfigurationEnabled	Whether to enable the Hosting Capacity admin page in the Network Explorer, available at /admin/hosting-capacity-configuration.	No	false
connectedEquipmentNavigationEnabled	Whether to enable navigation between connected equipment within the terminal.	No	false
customerLisDrawerEnabled	Whether to display the customer list drawer in the UI.	No	false
networkMapSearch2Enabled	Whether to enable the Network Map Search Component Version 2.	No	false
sincalExporterTimeseriesEnabled	Whether to Sincal Exporter timerseries options, also requires sincalExporterEnabled to be true	No	false
sincalExporterForecastEnabled	Whether to Sincal Exporter forecast options, also requires sincalExporterEnabled to be true	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

Type	Description	Required
execution	Configures the execution runtime to use for exporting the model	Yes

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	Yes

Feeder Load Analysis Config

Type	Description	Required
execution	Configures the execution runtime to use for running the feeder load analysis. Refer Feeder Load Analysis execution config	Yes

Feeder Load Analysis Execution Config Types

Type	Description	Required
container	Configures the FeederLoadAnalysis Service to execute the FeederLoadAnalysis jobs via a container platform (e.g. Docker). Refer Feeder Load Analysis Container Execution Config below	Yes

Feeder Load Analysis Container Execution Config

Option	Description	Required	Default
userConfigEnv	Name of the environment variable to pass through the user configuration blob	Yes
additionalConfigEnvPrefix	Prefix to append when configuring additional environment variables	Yes
command	The command (CMD) to use when creating the container.	Yes
template	Specifies the runtime where the container should be executed. Refer Container Execution Options	Yes
easUrl	The address of EAS to use for callback URLs in the Sincal Exporter container. If left unspecified, the URL will be built from the server config.	Yes

Example FeederLoadAnalysis configuration:

{
 "feederLoadAnalysis": {
   "execution": {
     "type": "container",
     "userConfigEnv": "ZC_FLA_USER_CONFIG",
     "additionalConfigEnvPrefix": "FLA",
     "template": {
       "type": "docker",
       "url": "unix:///run/docker.sock",
       "image": "feeder-load-analysis:latest",
       "network": "host",
       "defaultEnvs": {
         "ZC_FLA_CONFIG": "env-blob://ZC_FLA_BASE,env-blob://ZC_FLA_USER_CONFIG,env-prefix://FLA",
         "ZC_FLA_BASE": "stuff=="
       }
     },
     "easUrl": "http://host.containers.internal:7654"
   }
 }
}

Container PowerFactoryModel Execution Config

Option	Description	Required	Default
userConfigEnv	Name of the environment variable to pass through the user configuration blob	Yes
additionalConfigEnvPrefix	Prefix to append when configuring additional environment variables	Yes
command	The command (CMD) to use when creating the container.	Yes
template	Specifies the runtime where the container should be executed. Refer Container Execution Options	Yes
easUrl	The address of EAS to use for callback URLs in the Sincal Exporter container. If left unspecified, the URL will be built from the server config.	Yes
outputStorage	The storage where the resulting PowerFactory models will be placed Refer Storage Backend Options	Yes

Example PowerFactoryModel configuration:

{
 "powerFactoryModel": {
   "execution": {
     "type": "container",
     "template": {
       "envRef": [
         {
           "name": "powerfactory-exporter-configmap",
           "type": "CONFIG_MAP"
         }
       ],
       "image": "ghcr.io/zepben/powerfactory-model-service:test",
       "imagePullSecretName": "github-registry",
       "jobPrefix": "powerfactory-exporter",
       "namespace": "endeavour-fg",
       "type": "kubernetes"
     },
     "eas": "http://host.containers.internal:7654",
     "userConfigEnv": "PF_USER",
     "additionalConfigEnvPrefix": "PF",
     "outputStorage": {
       "type": "azure",
       "storageAccountName": "test",
       "storageContainerName": "output",
       "prefix": "models-eas/"
     }
   }
 }
}

OpenDSS Model Config

Type	Description	Required
execution	Configures the execution runtime to use for exporting the model. Refer OpenDSS Model execution config	Yes
timezone	The timezone to use for passing the load datetime to the Open DSS processor.	Yes

OpenDSS Model Execution Config Types

Type	Description	Required
container	Configures the OpenDSS Model Service to execute the OpenDSS Model Processor jobs via a container platform (e.g. Docker). Refer OpenDSS Model Container Execution Config below	Yes

OpenDSS Model Container Execution Config

Option	Description	Required	Default
userConfigEnv	Name of the environment variable to pass through the user configuration blob	Yes
additionalConfigEnvPrefix	Prefix to append when configuring additional environment variables	Yes
command	The command (CMD) to use when creating the container.	Yes
template	Specifies the runtime where the container should be executed. Refer Container Execution Options	Yes
easUrl	The address of EAS to use for callback URLs in the OpenDSS exporter container. If left unspecified, the URL will be built from the server config.	Yes
outputStorage	The storage where the resulting OpenDSS models will be placed Refer Storage Backend Options	Yes

Example FeederLoadAnalysis configuration:

{
 "openDssModel": {
   "execution": {
     "type": "container",
     "userConfigEnv": "OD_USER_CONFIG",
     "template": {
       "type": "docker",
       "url": "unix:///run/docker.sock",
       "image": "ghcr.io/zepben/opendss-model-processor:latest",
       "network": "host",
       "defaultEnvs": {
         "OD_CONFIG": "env-blob://OD_BASE,env-blob://OD_USER_CONFIG,env-prefix://OD",
         "OD_BASE": "stuff=="
       }
     }
   }
 }
}

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
inputDatabase	Object that holds configuration related to connecting to a hosting capacity input database. Refer to Hosting Capacity Input Database Config	No
storage	Storage location for the input databases and configuration files Storage Backend Options	No
calibration	Object that holds configuration related to performing calibration runs for distribution transformers Hosting Capacity Calibration 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
schema	The database schema to use.	No
maxConnectionLifetimeMs	The maximum lifetime of a connection in the connection pool before being replaced. Will not interfere with in use connections.	No

Example Hosting Capacity Results Database configuration:

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

Hosting Capacity Input Database Config

Option	Description	Required	Default
url	The JDBC URL to use to connect to the input database	Yes
driver	The database driver to use. If left unspecified, HikariCP will infer the driver from the JDBC URL.	No
schema	The database schema to use. By default it will use the "input" schema.	No	"input"
maxConnectionLifetimeMs	The maximum lifetime of a connection in the connection pool before being replaced. Will not interfere with in use connections.	No

Example Hosting Capacity Input Database configuration:

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

Hosting Capacity Calibration Config

Option	Description	Required	Default
timestamp	The date and time of the load data to run calibration on. This is the local time of the model without a timezone, in the format of YYYY-MM-ddTHH:mm:ss	Yes
calibrationWorkPackageConfig	An object containing configuration for the work package used in calibration. Refer Calibration work package options below	No

Example Hosting Capacity Service configuration:

{
 "hostingCapacity": {
   "calibration": {
     "timestamp": "2023-05-10T04:00:00"
   }
 }
}

Calibration work package config

Type	Description	Required
generatorConfig	A GeneratorConfig object.	No
scenario	The senario to be used for the calibration work package.	No

EWB Admin Config

Type	Description	Required
airflow	Configures Airflow client for use by the EWB admin service. Refer EWB airflow options below	No, mutually exclusive with kubernetes
kubernetes	Configures Kubernetes client for use by the EWB admin service Refer EWB kubernetes options below	No, mutually exclusive with airflow

Airflow EWB Admin Config

Option	Description	Required	Default
type	Type of platform the EWB service is administered by	Yes	Must be airflow
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 EWB Admin configuration:

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

Kubernetes EWB Admin Config

NOTE: A Kubernetes primaryEwbService must be configured when using Kubernetes to administer EWB from EAS.

Option	Description	Required	Default
type	Type of platform the EWB service is administered by	Yes	Must be "kubernetes"
namespace	The kubernetes namespace the EWB ConfigMap is in.	Yes	"default"
name	The name of the EWB ConfigMap.	Yes	"ewb-network-switcher"

Example Kubernetes EWB Admin configuration:

{
 "ewbAdmin": {
   "type": "kubernetes",
   "namespace": "hosting-capacity",
   "name": "ewb-main-config"
 }
}

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
schema	The database schema to use. By default it will use the "metrics" schema.	No	"metrics"
maxConnectionLifetimeMs	The maximum lifetime of a connection in the connection pool before being replaced. Will not interfere with in use connections.	No

Only Postgres is currently supported for the metrics database. As such, url must start with jdbc:postgresql and driver must be either unspecified or org.postgresql.Driver. 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
inputStorage	Storage location for the input databases and configuration files Storage Backend Options
outputStorage	Storage location for the output files Storage Backend Options
execution	Object specifying the method of executing the Sincal Exporter. Refer sincal model execution options below.	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 Execution 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
easUrl	The address of EAS to use for callback URLs in the Sincal Exporter container. If left unspecified, the URL will be built from the server config.	No
trustCallbackUrl	Whether the Sincal Exporter trusts the callback URL without verifying its SSL/TLS certificate. This should only be set to true for development purposes, when running EAS with a self-signed certificate.	Yes	false

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 EWB Auth Client Config

Option	Description	Required	Default
method	The auth method to use for authentication with EWB (ENTRAID, NONE)	Yes
issuer	The issuer domain for authentication using a client_credentials Oauth2 flow	Yes
audience	The audience for authentication with auth0	Yes
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": {
    "inputStorage": {
      "type": "azure",
      "storageAccountName": "replacewithstorageaccountname",
      "storageContainerName": "sincal-input",
      "localStore": "local_tmp"
    },
    "outputStorage": {
      "type": "azure",
      "storageAccountName": "replacewithstorageaccountname",
      "storageContainerName": "sincal-output",
      "localStore": "local_tmp"
    },
    "execution": {
      "type": "container",
      "template": {
        "type": "docker",
        "url": "tcp://localhost:2375",
        "image": "sincal-exporter-console-debug",
        "network": "host"
      },
      "ewbUrl": "http://host.docker.internal:9000",
      "easUrl": "http://host.docker.internal:7654",
      "trustCallbackUrl": false
    },
    "ewbAuthClient": {
      "method": "entraid",
      "audience": "audience",
      "issuer": "https://login.microsoftonline.com/some-id/v2.0",
      "clientId": "1234567890",
      "clientSecret": "swordfish"
    }
  }
}

Primary EWB Service Config

Option	Description	Required	Default
service	Container Service configuration block Container Service Options	Yes

Example Primary EWB Service configuration:

{
  "primaryEwbService": {
    "service": {
      "type": "docker",
      "url": "unix:///run/docker.sock",
      "containerName": "realEwbService",
      "network": "host"
    }
  }
}

Container Service Options

Configuration block to allow management of a service running in a container environment.

Docker

Option	Description	Required	Default
type	Type of platform the container service will be configured for	Yes	Must be docker
url	The address of the Docker daemon to run the service on.	Yes
certPath	The path of the SSL/TLS certificate store to use when connecting to the Docker daemon.	No
containerName	The name of the container the service is running in.	Yes

ECS

Option	Description	Required	Default
type	Type of platform the container service will be configured for	Yes	Must be ecs
region	The AWS region to launch the service in.	No
clusterName	The name of the cluster the service will run on.	Yes
serviceName	The name of the service to interact with.	Yes

Kubernetes

Option	Description	Required	Default
type	Type of platform the container service will be configured for	Yes	Must be kubernetes
namespace	The kubernetes namespace the service is in.	Yes
name	The name of the service.	Yes

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
additionalConfigEnvPrefix	The prefix used when passing configuration items to the ingestor container. This should match the prefix configured in the ingestor container.	Yes
restartEwbOnCompletion	Whether to restart the configured EWB service(primaryEwbService) following the successful completion of a network ingestion run(that was initiated by EAS).	No	false

Ingestor Runtime Options

Type	Description	Required
container	Configuration for launching ingestor runs directly in a container environment. Refer ingestor container runtime config below	No, mutually exclusive other types
temporal	Configuration for launching ingestor runs via Temporal. Refer ingestor temporal runtime config below	No, mutually exclusive other types

Ingestor Temporal Runtime Config

Option	Description	Required	Default
command	The command (CMD) to use when creating the container.	Yes	[]
easUrl	The address of EAS to use for callback URLs in the Ingestor container. If left unspecified, the URL will be built from the server config.	No

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	[]
easUrl	The address of EAS to use for callback URLs in the Ingestor container. If left unspecified, the URL will be built from the server config.	No

Example Ingestor Container Service configuration:

{
  "ingestor": {
    "runtime": {
      "type": "container",
      "template": {
        "type": "docker",
        "url": "unix:///run/docker.sock",
        "image": "zepben/ingestor_42342",
        "network": "host"
      },
      "easUrl": "https://ewb.local:7654"
    },
    "additionalConfigEnvPrefix": "se",
    "restartEwbOnCompletion": true
  }
}

Storage Backend Options

The configuration for storage depends on the type of storage backend used. The application supports local, AWS S3 and Azure Blob. The value of type will be used to determine the backend used.

Local Filesystem

Var	Description	Example
type	Type of storage backend	Must be local
newFileStore	Path to where new file created using this backend should be stored, defaults to current working directory	/home/bob/tmp

AWS S3

See AWS default credentials provider chain to set up authentication.

Var	Description	Example
type	Type of storage backend	Must be s3
region	The region where the bucket exists. If not set, AWS_DEFAULT_REGION will be used	us-east-1
bucketName	Name of the bucket	test-bucket
localStore	Temporary cache location where files will be cached. Defaults to OS temp directory	/tmp

Azure Blob

See Azure Default credentials provider chain to set up authentication.

Var	Description	Example
type	Type of storage backend	See below
storageAccountName	Name of the storage account	model-storage-sa
storageContainerName	Name of the storage container	models
localStore	Temporary cache location where files will be cached. Defaults to OS temp directory	/tmp

Temporal Config

Option	Description	Required	Default
host	The host for Temporal service	No	localhost
port	The port for Temporal service	No	7233
namespace	The Temporal service namespace	No	'default'