Skip to main content

CONFIG KIND

Config Kind

{
  "kind": "che.receipt-layout.v1",
  "name": "Receipt layout",
  "schema": "https://somewhere.com/receipt-layout-schema.json",
  "maxTreeDepth": "tenants/self"
}

Each configuration value in CCC has a kind.

Kinds are used to group values with the same schema.

Each kind has an identifier which consists of: system prefix, name and version.

Example of config kind id: che.receipt-layout-header.v1

Config schema​

Config kind's schema field is designed to point to a url which should contain a JSON schema of the config value.

Schema is used to validate values that you update.

Check Defining a new config kind for info on how to define schemas.

Gotchas when defining config kinds​

It is up to you to make good judgements when defining configuration kinds, but keep in mind the following:

Defaults are per kind, not object's field​

Default in this context means: value that was inherited from a more general target.

Example:

Option 1:

// kind: che.receipt-layout.v1
{
  "header": "...",
  "body": "...",
  "footer": "...",
}
  • 🟢 you have 1 call to get/set the value
  • 🔴 you will not have defaults on header and footer if you only set the body field, you either set the whole object or get a default for the whole object

Option 2:

{ "value": "..." } // kind: che.receipt-layout-header.v1
{ "value": "..." } // kind: che.receipt-layout-body.v1
{ "value": "..." } // kind: che.receipt-layout-footer.v1
  • 🟢 you get separate defaults on each component
  • 🔴 you have to do 3 calls to get/set values

In this example it is better to use Option 2 as having separate defaults on each components is needed.

But this does not mean that you should always create one config kind per domain object's component. There can be cases where grouping all (or some) components of domain object in a single config kind is preferable.

Config value size​

Configuration values are not files in a bucket, they are records in the database.

Do not store big amounts of data in CCC service, maximum allowed value size is 100kb.

For example: do not store an image using base64 encoding, store a link to the image.

Max caching level​

Config kind's optional max-caching-level field is used to control how much inheriting target's values will be pre-cached during the update.

Note: max-caching-level defaults to tenants/self which means pre-caching is disabled. You should keep this value unless you really need to optimize for performance.

Note: Pre-caching only affects targets that were never accessed before. Targets that were already pre-cached or directly accessed before will keep the caching logic.

Possible values for max-caching-level field are:

  • tenants/self - tenant level
  • business-unit-groups/* - business unit group level
  • business-units/* - business unit level
  • business-units/*/workstations/* - workstation level

Warning: If you will set the max-caching-level to business-units/*/workstations/* and set a value on tenant or global level you can potentially cache values for all workstations, even if the values will only be fetched on business unit level after.

Example 1. Pre-caching disabled:

max_tree_depth = "tenants/self"
updated_target = "tenants/self"
precached_values:
  - "tenants/self" # exact target

Example 2: Pre-caching for business units only:

max_tree_depth = "business-units/*"
updated_target = "tenants/self"
precached_values:
  - "tenants/self" # exact target
  - "business-unit-groups/*" # groups are still pre-cached as they are above business units in inheritence tree
  - "business-units/*" # all of the inheriting business units
max_tree_depth = "business-units/*"
updated_target = "business-units/b1/workstations/001"
precached_values:
  - "business-units/b1/workstations/001" # exact target

Example 3. Pre-caching everything:

max_tree_depth = "business-units/*/workstations/*"
updated_target = "tenants/self"
precached_values =
  - "tenants/self" # exact target
  - "business-unit-groups/*" # all of the inheriting groups
  - "business-units/*" # all of the inheriting business units
  - "business-units/*/workstations/*" # all of the inheriting workstations