Skip to main content

Extensibility

IdLE is designed for change through modules instead of forks.

Add a new step​

A new step typically involves:

  1. A metadata definition declaring required capabilities, the provider it uses and a typed WithSchema
  2. A handler function that receives the validated With and a provider handle and returns @{ Changed; Data }
  3. Unit tests (Pester)

The engine validates With, resolves the provider, handles authentication and builds the step result, so the handler contains only the step's domain logic. See Step metadata contract and Step handler contract.

Extension step types and capabilities use your own owner prefix: <Owner>.IdLE.Step.<Area>.<Name> and <Owner>.IdLE.<Domain>.<Verb> (e.g. Contoso.IdLE.Step.Hr.SyncManager, Contoso.IdLE.Hr.Manager.Read). IdLE.* is reserved for the IdLE project; see Step type names.

Steps can emit structured events using the execution context contract:

  • Context.EventSink.WriteEvent(Type, Message, StepName, Data[, Level]) (see Event types)

Keep steps host-agnostic: do not call UI APIs directly.

  • Use providers for system operations; do not embed authentication logic inside steps.
  • Emit events using Context.EventSink.WriteEvent(Type, Message, StepName, Data[, Level]).
  • Avoid global state. Steps should be idempotent whenever possible.

Add a new provider​

Providers are responsible for interacting with external systems (directories, cloud services, APIs, etc.).

A new provider typically involves:

  1. A contract interface (if not already present)
  2. A provider implementation module
  3. Auth session acquisition via host execution context (AuthSessionBroker)
  4. Contract tests and unit tests

Auth session acquisition​

IdLE keeps authentication out of the core engine. Providers acquire sessions through the execution context:

  • Context.AcquireAuthSession(Name, Options)

Key points:

  • Hosts provide an AuthSessionBroker via Providers.AuthSessionBroker
  • Providers request sessions by name (e.g., MicrosoftGraph, ActiveDirectory)
  • Options are data-only (ScriptBlocks rejected)
  • The broker handles caching, interactive auth policy, and secret management

Security:

  • AuthSessionBroker is a trusted extension point provided by the host
  • See Security and Trust Boundaries for the complete trust model and ScriptBlock handling rules

For detailed contract specifications and usage patterns, see:

→ Providers and Contracts — Complete provider contracts and AuthSessionBroker details

Capability Advertisement​

Providers must explicitly advertise their supported capabilities via a GetCapabilities() method. These capabilities are used by the engine during plan build to validate whether all required functionality is available.

The full contract, naming rules, and validation behavior are described in Provider Capabilities. Providers may advertise IdLE-defined capabilities (IdLE.*, as listed in the catalog) and their own extension capabilities (<Owner>.IdLE.*); anything else fails planning.

Providers should include the corresponding provider capability contract tests to ensure compliance.

Versioning strategy​

Keep workflows stable by treating step identifiers as contracts. If behavior changes incompatibly:

  • introduce a new step id or explicit handler mapping
  • keep the old step id available for older workflows

Keep the core headless​

Do not add:

  • interactive prompts
  • authentication code inside steps
  • authentication flows inside providers (use AuthSessionBroker)
  • UI or web server dependencies

Those belong in a host application.

Register step handlers​

Steps are executed via the step registry.

  • Workflows reference steps by Type (identifier).
  • Step packs register their handlers with the Handler key in their metadata catalog (see Step packs).
  • For host-defined step types only, the host maps the identifier to a function name (string) in Providers.StepRegistry. Step types defined by a step pack cannot be replaced.

ScriptBlock handlers are intentionally not supported as a secure default.

Handlers follow the step handler contract: they declare -With (and -Provider if the metadata declares a provider; -Context and -Step as needed) and return $null or @{ Changed; Data; State }. Handlers written for the pre-1.0 contract (-Context/-Step only) fail with LegacyStepHandler.

Command Contracts​

For supported commands, the following are stable contracts (breaking changes require a major version):

  • Command name
  • Parameter names and parameter sets
  • Observable semantics (mandatory/optional/default behavior)
  • Output type identity at a coarse level (PSTypeName)

The following are not contracts and may change in minor/patch versions:

  • Exact error message strings
  • Undocumented internal object properties
  • Internal module cmdlets

Data Contracts​

Workflow authoring contract (PSD1):

  • Format: PSD1 workflow definitions validated by Test-IdleWorkflow
  • Unknown keys: FAIL (strict validation)
  • Required fields (Name, LifecycleEvent, Steps[].Name, Steps[].Type): FAIL if null/empty
  • With payload values: allow null and empty strings (supports "clear attribute" scenarios)

Lifecycle request contract:

  • Required fields: LifecycleEvent, CorrelationId
  • Optional fields: Actor, IdentityKeys, Intent, Context