Replace IdLE.Step.EnsureAttribute with IdLE.Step.EnsureAttributes - multi-attribute capability

[Copilot]

Complete Removal of Deprecated Step Type

Removed all deprecated/legacy IdLE.Step.EnsureAttribute references and updated entire codebase to use IdLE.Step.EnsureAttributes with the new Attributes hashtable syntax.

Changes Made

Removed Files:

• ❌ src/IdLE.Steps.Common/Public/Invoke-IdleStepEnsureAttribute.ps1 - deprecated wrapper
• ❌ tests/Steps/Invoke-IdleStepEnsureAttribute.Tests.ps1 - compatibility tests
• ❌ docs/reference/steps/step-ensure-attribute.md - deprecated documentation
• ❌ examples/workflows/mock/joiner-minimal-ensureattribute.psd1 - legacy example workflow

Module Updates:

• ✅ Removed Invoke-IdleStepEnsureAttribute from module exports (.psd1 and .psm1)
• ✅ Removed IdLE.Step.EnsureAttribute from step registry
• ✅ Removed deprecated entry from step metadata catalog

Workflow Examples Updated (17 files):

• ✅ All mock workflows converted to use Attributes hashtable syntax
• ✅ All template workflows updated (AD, EntraID, complete scenarios)
• ✅ Consolidated multiple single-attribute steps where appropriate (e.g., EntraID leaver workflow now batches Manager + DisplayName)
• ✅ Removed legacy workflow file with old naming

Documentation Updated:

• ✅ Regenerated step reference (now shows only EnsureAttributes)
• ✅ Updated capabilities.md
• ✅ Updated provider documentation (provider-ad.md, provider-entraID.md, provider-mock.md)
• ✅ Updated installation.md
• ✅ Updated quickstart.md to reference EnsureAttributes
• ✅ Updated examples README.md (removed legacy file references)
• ✅ Fixed website sidebars.js to reference new step documentation
• ✅ Fixed provider-ad.md installation section - simplified to name-based import only (PSModulePath extended by IdLE)
• ✅ Simplified provider-ad.md auth examples (removed AdminCount example per review feedback)
• ✅ Clarified per-attribute result handling when provider doesn't return detailed results

Tests Updated:

• ✅ ModuleSurface.Tests.ps1 - expects EnsureAttributes instead of EnsureAttribute
• ✅ Auth session tests - updated to use Attributes hashtable and new function name
• ✅ All 486 tests pass (0 failures)

Code Quality Improvements

• ✅ Added clearer comments in Invoke-IdleStepEnsureAttributes about per-attribute change tracking limitations
• ✅ Improved mock provider documentation to explain step-to-provider method mapping
• ✅ Corrected provider installation documentation to accurately reflect standalone module architecture
• ✅ Simplified import instructions to use name-based imports (leveraging PSModulePath extension)

Result

✅ Zero references to deprecated IdLE.Step.EnsureAttribute remain in documentation
✅ All examples and documentation use the new plural step type
✅ All tests passing (486 passed, 0 failed, 5 skipped)
✅ PSScriptAnalyzer: No issues
✅ Website builds successfully (fixed sidebars.js reference)
✅ Provider documentation accurate (corrected and simplified installation instructions)
✅ Pre-1.0 breaking change implemented cleanly

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Replace IdLE.Step.EnsureAttribute with IdLE.Step.EnsureAttributes - multi-attribute-capability</issue_title>
<issue_description>## Problem Statement

IdLE.Step.EnsureAttribute currently supports exactly one attribute (With.Name + With.Value) per step.

In real-world workflows we often need to converge many attributes for the same identity. This forces authors to add multiple EnsureAttribute steps, which creates:

• unnecessary workflow verbosity and maintenance overhead,
• larger plans (harder to review / export / troubleshoot),
• repeated provider/session resolution overhead in the engine.

The current limitation is visible in the implementation: Invoke-IdleStepEnsureAttribute enforces With.IdentityKey, With.Name, With.Value and calls provider method EnsureAttribute(IdentityKey, Name, Value). The built-in step registry only maps IdLE.Step.EnsureAttribute to Invoke-IdleStepEnsureAttribute.

Proposed Solution

Introduce a plural step type that can ensure multiple attributes in one step:

• New step type: IdLE.Step.EnsureAttributes
• New handler: Invoke-IdleStepEnsureAttributes
• New schema (example):

@{
  Name = 'Ensure core user attributes'
  Type = 'IdLE.Step.EnsureAttributes'
  With = @{
    Provider    = 'AD'               # optional, default: Identity
    IdentityKey = '{{Request.IdentityKeys.SamAccountName}}'
    Attributes  = @{
      GivenName         = 'Max'
      Surname           = 'Power'
      UserPrincipalName = 'max.power@contoso.com'
    }
    # AuthSessionName / AuthSessionOptions like other steps (optional)
  }
}

Provider interaction / performance

To keep providers stable while still allowing optimizations:

1. Preferred (optional) fast path: If the provider implements a batch method EnsureAttributes, call it.

   • Proposed signature: EnsureAttributes(IdentityKey, AttributesHashtable)
   • Optional AuthSession parameter support (same discovery behavior as Invoke-IdleProviderMethod already uses).

2. Fallback (no provider change required): If EnsureAttributes is not available, iterate keys and call the existing EnsureAttribute(IdentityKey, Name, Value) for each attribute.

Result shape

• StepResult.Changed should be true if any attribute was changed.
• Additionally, return per-attribute details in a structured way (e.g. StepResult.Data.Attributes), without leaking secrets:
  • AttributeName
  • Changed (bool)
  • Error (null/string)
  • (Optional) Before/After only if engine already allows it safely (default should not emit values).

Backward compatibility / migration

We should switch the primary documentation and examples to EnsureAttributes.

For compatibility we have two viable options (choose one during implementation; default recommendation: A):

• Option A (recommended, non-breaking for existing workflows):

  • Keep IdLE.Step.EnsureAttribute working.
  • Implement it as a thin wrapper that internally calls the plural handler with a single entry.
  • Mark IdLE.Step.EnsureAttribute as deprecated in docs and changelog; schedule removal for a future major (1.0+) if desired.

• Option B (breaking, pre-1.0 acceptable):

  • Remove IdLE.Step.EnsureAttribute from the built-in registry and docs.
  • Workflows using it must be updated to IdLE.Step.EnsureAttributes.

Given the user goal is mainly workflow overhead, Option A achieves that immediately (new workflows use plural), while existing workflows keep running.

Alternatives Considered

1. Keep step singular but enhance workflow syntax with loops/macros
   → rejected: IdLE workflows are intentionally data-only; adding looping constructs increases complexity and undermines simplicity/security.

2. Add With.Names/With.Values arrays
   → rejected: risk of mismatched lengths and unclear semantics; a hashtable is clearer.

3. Only implement plural by calling provider EnsureAttribute in a loop
   → acceptable baseline; however the optional provider EnsureAttributes fast-path provides a clean performance upgrade path.

Impact

Engine / Core / Steps

• Step registry must register the new type:
  • IdLE.Core/Private/Get-IdleStepRegistry.ps1: add mapping for IdLE.Step.EnsureAttributes.
  • Keep (Option A) or remove (Option B) mapping for IdLE.Step.EnsureAttribute.

Step metadata catalog

• IdLE.Steps.Common/Public/Get-IdleStepMetadataCatalog.ps1: add IdLE.Step.EnsureAttributes with the same capability:
  • RequiredCapabilities = @('IdLE.Identity.Attribute.Ensure')

Provider contracts

• No breaking provider change is required if we implement the fallback loop.
• Providers may implement EnsureAttributes for efficiency.

Workflows / docs / examples

• Update docs and examples to use IdLE.Step.EnsureAttributes to reduce workflow verbosity.

Additional Context

Code references (...

• Fixes Replace IdLE.Step.EnsureAttribute with IdLE.Step.EnsureAttributes - multi-attribute-capability #169

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[blindzero]

@copilot remove all deprecated / legacy documentation, comments, aliases and so on. just make sure all existing documentation and examples are updated to the new one as we are pre-1.0

[Copilot]

@copilot remove all deprecated / legacy documentation, comments, aliases and so on. just make sure all existing documentation and examples are updated to the new one as we are pre-1.0

Done. Removed all deprecated/legacy references to IdLE.Step.EnsureAttribute and updated entire codebase to use IdLE.Step.EnsureAttributes.

Removed:

• Deprecated wrapper function and tests
• All deprecated documentation
• Registry and metadata entries for old step type

Updated (30 files):

• All 17 workflow examples converted to Attributes hashtable syntax
• All provider documentation
• All tests

✅ Zero deprecated references remain
✅ All 486 tests pass

Commits: 3fb6085, 7614ee4, 06b3b3a

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Pull request overview

This PR completes the migration away from the deprecated singular IdLE.Step.EnsureAttribute step type by removing its implementation and updating the engine registry, step metadata, tests, examples, and documentation to use the plural IdLE.Step.EnsureAttributes step with an Attributes hashtable.

Changes:

• Added Invoke-IdleStepEnsureAttributes step handler (with provider fast-path + fallback to per-attribute calls).
• Removed Invoke-IdleStepEnsureAttribute and updated step registry/metadata/module exports to only expose EnsureAttributes.
• Updated tests, docs, and workflow examples to use IdLE.Step.EnsureAttributes + With.Attributes.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/Steps/Invoke-IdleStepEnsureAttributes.Tests.ps1	Adds coverage for new built-in step handler, including fast-path and fallback behavior.
tests/Steps/Invoke-IdleStepAuthSession.Tests.ps1	Updates auth-session routing tests to call Invoke-IdleStepEnsureAttributes and use With.Attributes.
tests/Packaging/ModuleSurface.Tests.ps1	Updates module surface expectations to export/register EnsureAttributes.
tests/Core/New-IdlePlan.Tests.ps1	Adjusts planning tests to account for EnsureAttributes capability requirements.
tests/Core/Invoke-IdlePlan.Tests.ps1	Adjusts execution tests to account for EnsureAttributes capability requirements.
src/IdLE.Steps.Common/Public/Invoke-IdleStepEnsureAttributes.ps1	Introduces the new plural step implementation.
src/IdLE.Steps.Common/Public/Invoke-IdleStepEnsureAttribute.ps1	Removes deprecated singular step implementation.
src/IdLE.Steps.Common/Public/Get-IdleStepMetadataCatalog.ps1	Updates step metadata catalog entry to IdLE.Step.EnsureAttributes.
src/IdLE.Steps.Common/IdLE.Steps.Common.psm1	Updates exports to expose Invoke-IdleStepEnsureAttributes.
src/IdLE.Steps.Common/IdLE.Steps.Common.psd1	Updates manifest exports to expose Invoke-IdleStepEnsureAttributes.
src/IdLE.Core/Private/Get-IdleStepRegistry.ps1	Updates built-in step registry mapping to IdLE.Step.EnsureAttributes.
examples/workflows/templates/entraid-mover-department-change.psd1	Updates template workflow steps to plural step + hashtable syntax.
examples/workflows/templates/entraid-leaver-offboarding.psd1	Consolidates multiple single-attribute steps into one multi-attribute step.
examples/workflows/templates/entraid-joiner-complete.psd1	Updates template workflow step to plural step + hashtable syntax.
examples/workflows/templates/complete-leaver-entraid-exo.psd1	Updates template workflow step to plural step + hashtable syntax.
examples/workflows/templates/ad-mover-department-change.psd1	Consolidates attribute updates into a single multi-attribute step.
examples/workflows/templates/ad-leaver-offboarding.psd1	Updates template workflow step to plural step + hashtable syntax.
examples/workflows/templates/ad-joiner-complete.psd1	Consolidates attribute updates into a single multi-attribute step.
examples/workflows/mock/joiner-with-onfailure.psd1	Updates mock workflow step to plural step + hashtable syntax.
examples/workflows/mock/joiner-minimal-ensureattributes.psd1	Adds a new minimal example that demonstrates EnsureAttributes.
examples/workflows/mock/joiner-minimal-ensureattribute.psd1	Renames/updates the minimal example to use EnsureAttributes.
examples/workflows/mock/joiner-ensureentitlement.psd1	Updates mock workflow step to plural step + hashtable syntax.
examples/workflows/joiner-with-retry-profiles.psd1	Updates retry-profile example to plural step + hashtable syntax.
docs/use/installation.md	Updates step examples in installation docs to reference EnsureAttributes.
docs/reference/steps/step-ensure-attributes.md	Updates generated step reference for plural step type and new schema.
docs/reference/steps.md	Updates generated steps index to list IdLE.Step.EnsureAttributes.
docs/reference/providers/provider-mock.md	Updates provider docs examples/mentions to plural step type.
docs/reference/providers/provider-entraID.md	Updates provider docs to reference EnsureAttributes step type.
docs/reference/providers/provider-ad.md	Updates provider docs examples/mentions to plural step type and schema.
docs/reference/capabilities.md	Updates examples to reference IdLE.Step.EnsureAttributes.