Skip to main content

CONFIG VALUE

Config Value

{
    "value": 123 // any JSON type
}

Configuration values are the actual data that is stored and retrieved from the CCC.

Values have kinds and are set on specific targets.

Config value can be a string or an object or any other JSON type.

All types of values are treated in the same way, there is no special handling for object's properties or array items. If you are not sure whether you need one kind with an object type or multiple kinds storing its fields, see Gotchas when defining config kinds

Defining a new config value​

Before reading this section make sure you are familiar with the inheritance concept in CCC.

CCC API provides two ways that you can mutate the values on a specific target:

PUT /v1/config/{kind}/{target}​

This is the simplest way to set a value on a specific target. When the value is set, it is stored on the target and is passed down to all its children as-is. If the value already exists on the target, it is overwritten. Note, that this operation will override the value from the higher levels as seen in the example below.

put("tenants/self", 123)
get("tenants/self") // 123
get("business-units/b1") // 123, inheritedFrom: tenants/self
get("business-units/b1/workstations/w1") // inheritedFrom: tenants/self

put("business-units/b1", 456)
get("tenants/self") // 123
get("business-units/b1") // 456
get("business-units/b1/workstations/w1") // 456, inheritedFrom: business-units/b1

PATCH /v1/config/{kind}/{target}​

This is another way you can manipulate the values on the target. CCC does not use the json-patch format, but rather a version that accepts a value and merges it with the existing one. The operation also respects the inheritance tree, so when you request a value from a target, you will get the inherited value from the tree, and will have all the patches applied on top of it.

Notable features:

  • each target can only have one patch value, so when you patch again you override the previous patch
  • if target has a value defined on its level, you can not patch it, you can only override it with PUT
  • when you PUT a value on a target, the patch on it is removed
  • objects are merged be property names, arrays are just concatenated
  • as a special case, if array items are objects, they are merged by their id property
  • if one of the values is primitive, it is replaced by the patch value
  • if types for value and patch are not equal, the patch value is used
put("tenants/self", { a: 1, b: 2 })
get("tenants/self") // { a: 1, b: 2 }

patch("tenants/self", { a: 3 }) // can not patch on the level that has a value
patch("business-units/b1", { a: 3 })

get("business-units/b1") // { a: 3, b: 2 }, inheritedFrom: tenants/self, patchedOn: [business-units/b1]
get("business-units/b1/workstations/w1") // { a: 3, b: 2 }, inheritedFrom: tenants/self, patchedOn: [business-units/b1]

patch("tenants/self", [])
get("tenants/self") // [], types are different - object and array, so the patch value is used

patch("tenants/self", '123')
get("tenants/self") // '123', types are different - primitive and array, so the patch value is used

If you are interested in the exact patch value on a certain level you can GET it by passing a special query parameter:

get("business-units/b1?getPatchValue=true") // { a: 3 }

Removing a value​

You can easily remove a value on any target except the GLOBAL by calling a DELETE endpoint. The operation will remove any value present on the target be it a regular value or a patch.