The Configuration File

Spark apps all require a config file to run.

In development mode, there's a config file at public/config that your app fetches during loading.

Production apps will check the configs directory of the jcu-webapps-config repository for a config file. You should update this repo with your app's production config before deploying your app in production.

The config file is JSON contains a single object. It looks like JSON normally does:

{
    "config_version": "1.0.0",
    "configuration": {
        "authentication": {
            "client_id": "room-viewer",
            "post_logout_redirect_uri": "/loggedout"
        },
        "appearance": {
            "theme": "jcu"
        },
        "environment": {
            "type": "test",
            "name": "UAT Environment",
            "description": "This is not a production system; information displayed in this environment should not be considered valid. Please use the [current live system](https://www.jcu.edu.au/) unless testing this application version."
        },

The tables below split the config data into functional sections. Each section's heading includes the key name, its valid values, the default value if the key isn't supplied (or if the key is required), and the SPARK versions that the key is operational in.

Top level keys in the configuration file

Key	Values	Default	Versions	Description
`config_version`	`1.0.0`	required	all	This is the version of the config data object itself, and it has always been 1.0.0
`configuration`	data object	required	all	Contains all the config

Authentication

Keys in configuration.authentication address OIDC config.

Keys	Values	Default	Versions	Description
`client_id`	string	required	all	Your app's OIDC client id, usually a kebab-case string that matches your git repo name and URL path e.g. `room-viewer`
`post_logout_redirect_uri`	URL path	none	all	`"/loggedout"`

TODO add all the other settings; in the meantime refer to (https://git.jcu.edu.au/bitbucket/projects/WEBLIB/repos/jcu-webapp/browse/src/services/AxaOidcProvider.tsx#7,71) for all the rest of the fun settings you can tweak.

Appearance

Keys in configuration.appearance control the visual appearance of the app.

Key	Values	Default	Versions	Description
`theme`	`jcu` or `sith`	`jcu`	all	The theme to apply to your app. Generally just use `jcu`; the `sith` theme is used in the profile application because it matches Forgerock's look&feel.

Environment

Keys in configuration.environment determine the environment (production or otherwise) this app is considered to be "in". Many of these fields show up in default headers as part of the JcuEnvironmentBanner.

Key	Values	Default	Versions	Description
`type`	`prod`, `test`, `uat`, or some other string	none	all	The environment type. Use `prod` for production, `test` and `uat` where they make sense; aside from `prod` == production, it's also okay to make something up if those conventions aren't useful.
`name`	string	none	all	The human-readable name for the environment. Use Title Case.
`description`	Markdown	none	all	The human-readable description of this environment and what it means to the user.

Support

Keys in configuration.support describe the mechanisms users of this application can get help.

Key	Values	Versions	Description
`name`	string	all	the human-readable name of the group or individual responsible for support. Use uncapitalised "the" in front of group names, e.g. "the IT Helpdesk".
`email`	email	all	email contact for the supporting entity
`phone`	phone number (string)	all	phone contact for the supporting entity

APIs

The array at configuration.apis includes configuration for all the API Interfaces used by the app.

Key	Values	Versions	Description
`[n].name`	string	all	The name for your API Interface, usually in kebab-case. This needs to match your ApiInterface.interfaceName
`[n].url`	URL string	all	The base URL for your API Interface
`[n].version`	string	all	API Interface version (almost always `"1"`)
`[n].options`	{object}	all	TODO

Header and Footer

The structures under configuration.header and configuration.footer determine links in the (optionally displayed) header and footer. Empty objects or missing header and footer keys will result in not including the relevant header/footer.

Key	Values	Default	Versions	Description
`header`	``		all	TODO
`footer`	``		all	TODO

Banner

The structure under configuration.banner defines content to display in an application banner. This is intended to provide important, usually time-relevant information to application users; don't use this for low value content like marketing info.

The banner content is treated as Markdown, so you can include links and text formatting. You can try Markdown using the same formatter in this markdown-to-jsx online tool.

Key	Values	Default	Versions	Description
`title`	`string`		all	title of the displayed banner
`description`	`Markdown string`		all	content for the banner, in Markdown format

Application

Keys under configuration.application configure behaviour of the application.

Key	Values	Default	Versions	Description
`open`	ISO-8601 date string	none	2.5+	Before this date, the application will display a "not open yet" page (see JcuApp's `openPage` prop) rather than the usual content
`close`	ISO-8601 date string	none	2.5+	After this date, the application will display a "closed" page (see JcuApp's `closePage` prop) rather than the usual content
`embedded`	`always`, `auto`, or `never`		3.2+	Define if and when this application should act as an "embedded" app, which mostly means most of the headers and footers get turned off. `never` is the default and means no special handling; `always` means always use an embedded layout that has minimal headers and footers; `auto` will attempt to detect if the app in loaded in a frame or iframe, and use embedded layout in those cases. Refer to the useEmbedded hook for how to adapt your own layouts to being embedded

Dates for open and close assume a +10 timezone if none is specified. For more detail about how open and close dates are handled, see the DisplayWhen docs covering date/times.