Parameter files

Your application's configuration (mail server, web server start, history retention, licence, redirections) lives in files placed in Resources/json and merged into Storage at startup. APP_PARAMETERS is the base; the other files override it depending on the machine.

The files

• No extension: the names are exact (APP_PARAMETERS, not APP_PARAMETERS.json).
• Encrypted on disk: edit them with the JSON object editor, never with a text editor.
• The suffix of DEV_PARAMETERS_<suffix> is only a convention (a developer's name, for instance): nothing picks a file by machine or user, every one that exists is loaded.
• The installation copies templates of APP_PARAMETERS, DEV_PARAMETERS, PREPROD_PARAMETERS and WEB_PARAMETERS into your project, unless they are already there.

These files belong to each machine: do not commit them and do not ship them. They hold secrets (the mail server password, the licence…), and carrying a file over would overwrite the configuration on the other side. The build removes them from the delivered application (except WEB_PARAMETERS): each server keeps its own.

Load order and merge

At startup the application begins in PROD mode, then reads, in this order:

APP_PARAMETERS → WEB_PARAMETERS → PREPROD_PARAMETERS → DEV_PARAMETERS → the DEV_PARAMETERS_*

A file read later wins over a file read earlier, with these rules:

"One level deep" means: inside vo_Param, a simple value is replaced by the next file's, but a nested object is replaced as a whole. A DEV_PARAMETERS that only wants to change the mail server must therefore carry the whole vo_Mail, not just vt_Host: otherwise the port, user and password disappear.

A parameter therefore goes inside a root object, almost always vo_Param:

{
  "vo_Param": {
    "vt_RedirectMail": "me@example.com",
    "vo_Mail": { "vt_Host": "smtp.example.com", "vl_Port": 587, "vt_User": "…", "vt_Password": "…", "vt_Forwarder": "…" }
  }
}

The application mode

Storage.vo_Param.vt_applicationMode is PROD, PREPROD or DEV (and COMPONENT when the component is opened on its own). DEV wins over PREPROD. DEV_PARAMETERS_* files do not change the mode.

A fresh installation starts in DEV mode, since the installation copies a DEV_PARAMETERS template. Delete it, and PREPROD_PARAMETERS, on a production server.

A few tools (the content exchange snapshot, history archiving, the startup confirmation dialog) rely only on the presence of a file whose name starts with DEV_PARAMETERS. With a single DEV_PARAMETERS_<suffix>, they treat the machine as a development machine while the mode stays PROD.

Main keys

All under vo_Param:

Reading a parameter

• In your project: Storage.vo_Param.<key>. Your project has its own Storage; the Use (Storage) block the installation adds to On Startup copies vo_Param into it at startup (see The launcher, startup and the toolbar). Other root objects are not copied.
• In the component: Storage.vo_Param.<key> or Storage.<root object>.<key>.

Changing a parameter

With the JSON object editor, then restart: saving the file reloads nothing, and the Storage refresh (BSPK_REFRESH_STORAGE) does not re-read these files.

A new key that a new version of your application needs is added by an update method: read the file (BSPK_FILE_Get_JSON_Content), add the key only if it is missing, write the file back (BSPK_FILE_SET_JSON_CONTENT). Never by shipping the file.

At a server's first start

If your project has no Resources/json/APP_PARAMETERS, startup opens a "Select APP_PARAMETERS files" dialog (APP_PARAMETERS, PREPROD_PARAMETERS and DEV_PARAMETERS are accepted), copies the chosen files, and quits 4D if the dialog is cancelled or nobody is there to answer it. A delivered application carries no parameter file, so every new server installation goes through it.

Good to know

• A simple value placed at the root of the file never reaches Storage, with no error and no trace.
• A date stored as ISO text comes back as a 4D date: see The 4D language.
• A key removed from a file stays in Storage until the next restart.

See also

• The JSON object editor
• The Mail class
• The launcher, startup and the toolbar