Skip to content

Control Changes (Admin)

Policy

Overview

A Control Change Policy sets the default execution behavior for the Control Changes sent to a single Asset / Data Stream pair. Platform Administrators use it to decide how Control Changes on that pair are retried, queued and confirmed, without relying on each Application or user to set those values.

Note

To understand the concept of a Control Change, you can read the full description on the Control Change concept page.

A Control Change Policy can set:

  • How many times a Control Change is retried
  • The time between retries
  • How a new Control Change is queued against others on the same Asset / Data Stream pair
  • The completion checks that must pass before a Control Change is marked as applied

Policies are managed with the Kelvin API and the Kelvin API Client (Python). There is no Kelvin UI for Control Change Policies.

How a Policy Is Applied

Each policy field is resolved separately when a Control Change runs. The first value found in this order is used:

  1. The value set in the Control Change request
  2. The value set in the Control Change Policy of the Asset / Data Stream pair
  3. The platform default

A field that is not set in the Control Change request or in the policy uses the platform default.

A Control Change Policy does not include the expiration_date of a Control Change or any Guardrail settings. The expiration_date is always set in the Control Change request, and Guardrails are configured separately.

Policies apply to Control Changes regardless of whether they come from an Application, a Recommendation, or another origin.

Policy Synchronization

When a policy is created, updated, or deleted, the Control Change Manager (CCM) receives a notification and synchronizes the policy definitions to the Cluster. After synchronization, the change applies to new Control Changes only; it does not change Control Changes that have already been submitted, whether queued or executing.

Policy Fields

Field Type Description
resource KRN The Asset / Data Stream pair the policy applies to, in the format krn:ad:<asset_name>/<data_stream_name>. Required. Maximum 256 characters.
policy.retries Integer, 0 or more The number of retry attempts after the initial delivery. Corresponds to the Control Change request's retries field. Can be set without retry_interval.
policy.retry_interval Integer, 1 or more The time in seconds between retry attempts. Corresponds to the Control Change request's timeout field, the older, deprecated name for the interval. The policy API uses retry_interval. Can be set without retries.
policy.queueing.mode enqueue, next or immediate How a new Control Change is queued when it is submitted for the same Asset / Data Stream pair. When queueing is set, mode is required. See Queueing Mode.
policy.resource_value_check List The completion checks that must all pass before a Control Change is marked as applied.
policy.resource_value_check[].resource KRN The Asset / Data Stream pair that is observed to evaluate completion. Required for each check.
policy.resource_value_check[].tolerance Number, 0 or more The allowed deviation (±) from the requested value. Required for each check.

Policies returned by the Kelvin API also include these fields:

Field Description
created UTC time when the policy was created, in RFC 3339 format.
created_by KRN of the user or process that created the policy.
updated UTC time when the policy was last updated, in RFC 3339 format.
updated_by KRN of the user or process that last updated the policy.

Queueing Mode

The queueing.mode field determines how the new Control Change is handled in relation to other Control Changes for the same Asset / Data Stream pair:

  • enqueue: adds the Control Change to the queue for sequential execution. This is the default when no mode is set in either the Control Change request or policy, and is the behavior used before queueing modes were introduced.
  • next: moves the Control Change ahead of queued Control Changes, discarding the other queued Control Changes. A Control Change that is already executing is not discarded.
  • immediate: moves the Control Change ahead of all other Control Changes, including one that is executing. The executing Control Change is marked as Failed. If it has already been sent to an external system, the write itself cannot be interrupted.

Resource Value Check

The resource_value_check list defines the readings that must confirm a Control Change before it is marked as applied. Each check compares the value read from its specified Asset / Data Stream pair with the requested value, within that check's tolerance. All checks must match within their specified tolerances for the Control Change to be marked as applied.

The checks are evaluated as part of Control Change completion when updated readings arrive. For the evaluation flow, see the Control Change completion evaluation diagram.

Validation Rules

The Kelvin API rejects a policy that breaks these rules with a 400 error:

  • The policy resource and every resource_value_check[].resource must belong to the same Asset.
  • The Data Streams used by the policy resource and every resource_value_check[].resource must have the same data type.

The Kelvin API returns a 404 error if an Asset or a Data Stream used by the policy does not exist. Creating a policy for an Asset / Data Stream pair that already has one returns a 409 error. Use the update guide to change an existing policy.

Permissions

Action Permission
Create a policy kelvin.permission.control_change.create
View or list policies kelvin.permission.control_change.read
Update a policy kelvin.permission.control_change.update
Delete a policy kelvin.permission.control_change.delete

Policy Guides