Skip to main content

Add a New Parameter

This guide walks through adding a new application parameter to the Core Service. It assumes you're familiar with the parameter model described in Configuration: Parameters — Cloud vs. OnPrem resolution and tenant/store overrides — and focuses on the steps to add one.

1. Confirm this belongs in Parameters, not CCC​

Parameters are for settings that should not be customer-controlled. If the setting you're adding is something a retailer or store manager should be able to change themselves, it doesn't belong here — use Customer Controlled Configuration instead (see Configuration: Tenant Configuration / Store Configuration, and Configure a New Store for how store-level CCC values get set). The rest of this guide assumes the setting genuinely shouldn't be customer-editable.

2. Decide the scope​

  • Environment(s) — Cloud, OnPrem, or both. The two are configured independently (see below), so add the parameter to each environment it should exist in.
  • Value scope — does every tenant/store need the same value (add only a default), or does a specific tenant/store need something different (add an override too)?

3. Add it for Cloud​

Add the key to DEFAULT_SETTINGS in appsettings.Cloud.json, using the Cloud naming convention (ALL_CAPS_WITH_UNDERSCORES):

{
  "DEFAULT_SETTINGS": {
    "YOUR_NEW_PARAMETER": "default-value"
  }
}

If a specific tenant or store needs a different value, add an override under TENANT_SETTINGS for that tenant (and its BUSINESS_UNITS entry, if store-specific) — see Configuration: Configuring for specific tenants and stores for the exact shape.

Cloud parameters are bound directly from appsettings.Cloud.json at build time — there's no live API to set them, so a new or changed value requires a rebuild and redeploy of the Core Service. Cloud has no program-ID concept (see step 4) — it's just a flat key.

4. Add it for OnPrem​

OnPrem parameters are keyed by Program ID — decide whether this parameter belongs under MyScan (shared with the client application) or MyScan.Core.Service (background-service-only); see Configuration: Parameters for the distinction. Program ID is an OnPrem-only concept and doesn't apply to the Cloud step above. See also the PROGRAMNAMES table all program IDs.

Add the parameter to the PROGRAMPARAMETERS table (via the ParameterService) under that program ID, using the OnPrem naming convention — the same name, case-insensitive, no underscores (e.g. YourNewParameter).

If a specific store needs a different value, add a row to PROGRAMSTOREPARAMETERS instead, scoped to that store's number — this takes precedence over the PROGRAMPARAMETERS value when both are defined.

OnPrem parameter reads go through the ParameterService's distributed cache (Redis or in-memory) — a change may not be visible immediately if a cached response hasn't expired yet.

5. Verify​

  • GET v3/parameters — confirm the new parameter appears for your own tenant/business unit.
  • GET v3/business-units/{businessUnitId}/parameters — confirm a store-level override, if you added one, takes effect for that specific store.

Reference​