Descriptor Enrichment Configuration Reference

This page documents the configuration parameters available for all Descriptor Enrichment Providers. These settings control runtime behaviour, failure handling, and performance tuning.

Configuration parameters

Each provider exposes the following configuration settings through the Administration Panel. These appear in the Provider Settings drawer when configuring a provider.

UI Label	Type	Required	Default	Description
Enabled	boolean	Yes	false	Whether the provider is active. Disabled providers are skipped entirely.
Failure Mode	enum	Yes	Fail Open	What to do if the provider fails or times out. See Failure Mode below.
Timeout (seconds)	integer	Yes	Provider-specific	Maximum time to wait for the provider to respond.
Cache TTL (seconds)	integer	Yes	Provider-specific	How long to cache provider results. See Cache TTL below.
System Types	string[]	No	Empty (all types)	If set, restricts the provider to projects matching specific Practice Shaper system types. See System Types below.

Failure Mode

The Failure Mode setting controls what happens when a provider cannot supply data — for example due to a timeout or an upstream service being unavailable.

Fail Open

The provider's contribution is skipped for that evaluation. The operation (provisioning, policy test) continues with whatever data is available from other providers. A warning is written to the platform logs.

Use Fail Open when:

• You are enabling a provider for the first time and want to validate behaviour without risk.
• The provider is informational and policies can function without it (graceful handling of missing data).
• You want to prevent provider failures from blocking provisioning operations.

Fail Closed

The operation is aborted if the provider fails. No provisioning or policy evaluation takes place until the provider recovers.

Use Fail Closed when:

• Policies require the provider's data to make a correct governance decision, and proceeding without it would be unsafe.
• You have confirmed the upstream service is reliably available in all environments.
• The cost of a failed provisioning operation is lower than the cost of proceeding with stale or missing data.

warning

Switching from Fail Open to Fail Closed in production without first validating provider reliability can cause provisioning operations to fail unexpectedly. Validate in lower environments first.

Cache TTL

The Cache TTL (seconds) setting determines how long provider results are cached in memory before being refreshed. Caching reduces latency and upstream service load.

How caching works

• The first provider call after enabling (or after cache expiry) incurs a live call to the upstream service
• Subsequent calls within the TTL window are served from the in-memory cache
• The cache is per-project — different projects have independent cache entries
• Cache entries expire after the configured TTL, triggering a fresh provider call on the next evaluation

Tuning guidance

TTL Value	Use Case	Trade-offs
0 (disabled)	Debugging or when data changes must be immediately visible	High latency, high upstream load. Only recommended for very low-traffic platforms.
30–60 seconds	Frequently changing data where freshness is critical	Moderate upstream load, good freshness guarantees. Suitable for most production use cases.
5–15 minutes	Infrequently changing data where staleness is acceptable	Low upstream load, data may be several minutes out of date. Good for reducing service load.
30+ minutes	Static or near-static data	Minimal upstream load, but data may be significantly stale. Only use if the upstream service is expensive or rate-limited.

Cache warm-up behaviour

In environments with many concurrent provisioning operations starting at the same time (e.g., after a platform restart), multiple simultaneous cache misses can cause a burst of requests to the upstream service. This is typically harmless for small environment counts (3–5), but worth being aware of at scale.

System Types

The System Types setting restricts the provider to projects matching specific Practice Shaper system types. If left empty, the provider applies to all projects regardless of type.

Example use cases:

• Only fetch deployment status for dataproduct and dataplatform system types, not for application types
• Apply a provider only to projects in a specific domain or organizational unit
• Limit provider invocation to reduce unnecessary overhead for project types that don't use the enriched data

How it works:

• Projects whose system type does not match the configured list are skipped
• The provider is not invoked for non-matching projects
• No enriched data from that provider appears in the descriptor for non-matching projects

Next steps

• To enable and configure a provider: See Enable Descriptor Enrichment Providers
• To safely rollout to production: See Rollout Descriptor Enrichment Providers
• To see available providers: See Descriptor Enrichment Providers