Add Mailbox Out of Office step + template docs with dynamic user attributes

[blindzero]

Problem Statement

Users want to configure Exchange Online automatic replies (Out of Office / OOF) as part of Leaver and handover workflows. While IdLE already exposes a mailbox OOF step (IdLE.Step.Mailbox.OutOfOffice.Ensure) and the ExchangeOnline provider advertises the corresponding capability, the current documentation/examples do not clearly show:

• How to use template variables ({{...}}) in OOF messages.
• How to include dynamic attributes (e.g., the user’s manager) in OOF text in a safe way (i.e., without live directory lookups inside the step).
• A naming option that follows the alternative “EnsureX” convention (IdLE.Step.Mailbox.EnsureOutOfOffice) for better discoverability/consistency for some users.

Proposed Solution

A) Documentation + Examples: Template usage + dynamic manager attributes (host enrichment)

1. Add/update docs for the OOF step to explicitly state that template expansion happens against the request object, and show an end-to-end example:
   • Host reads manager details (AD/Entra) and enriches request.
   • Workflow step uses {{Request.DesiredState.Manager.*}} to render message.

Host enrichment example (AD → DesiredState.Manager):

$user = Get-ADUser -Identity 'max.power' -Properties Manager
$mgr = $null
if ($user.Manager) {
  $mgr = Get-ADUser -Identity $user.Manager -Properties DisplayName, Mail
}

$req = New-IdleLifecycleRequest -LifecycleEvent 'Leaver' -Actor $env:USERNAME -DesiredState @{
  Manager = @{
    DisplayName = $mgr.DisplayName
    Mail        = $mgr.Mail
  }
}

Workflow step example:

@{
  Name = 'Set Exchange OOO'
  Type = 'IdLE.Step.Mailbox.OutOfOffice.Ensure'
  With = @{
    Provider = 'ExchangeOnline'
    IdentityKey = 'max.power@contoso.com'
    State = 'Enabled'
    InternalMessage = "This mailbox is no longer monitored. Please contact {{Request.DesiredState.Manager.DisplayName}} ({{Request.DesiredState.Manager.Mail}})."
    ExternalMessage = "This mailbox is no longer monitored. Please contact {{Request.DesiredState.Manager.Mail}}."
    ExternalAudience = 'All'
  }
}

2. Ensure the example explicitly says: manager lookup is performed host-side, not inside the step (security boundary).

B) Step type alias (optional, non-breaking)

Add a step type alias that maps to the existing handler:

• Canonical: IdLE.Step.Mailbox.OutOfOffice.Ensure
• Alias: IdLE.Step.Mailbox.EnsureOutOfOffice

Alias should resolve to the same handler currently used for OOF:

• Invoke-IdleStepMailboxOutOfOfficeEnsure

Implementation outline:

• Step registry: add alias → handler mapping
• Step metadata catalog: add alias key with identical RequiredCapabilities

C) Validation / Idempotency verification

Verify or add step validation rules (if missing):

• State must be Disabled|Enabled|Scheduled
• When Scheduled: StartTime and EndTime required and StartTime < EndTime
• Reject ScriptBlocks in AuthSessionOptions (existing security rule)

Ensure idempotent behavior:

• If current OOF config matches desired config, return Changed = $false.

D) Deliverables (docs/tests/examples)

• Docs:
  • Update provider page for ExchangeOnline to include OOF example using templates + dynamic manager attributes
  • Update step reference page for OOF step to include “Templates” section and (if implemented) an “Aliases” section
• Examples:
  • Add a runnable leaver example workflow and a companion host snippet showing request enrichment
• Tests:
  • Step unit tests: template strings applied to InternalMessage / ExternalMessage
  • Step unit tests: scheduled validation rules
  • (If alias implemented) plan building resolves alias to same handler/capabilities

Alternatives Considered

1. Do directory lookups inside the OOF step (e.g., resolve manager automatically)
   • Rejected for now because it couples the step to a specific directory provider and breaks the “request-driven template” boundary.
2. Rename the canonical step type
   • Rejected to avoid breaking existing workflows. Alias provides the ergonomics without breaking changes.

Impact

• Does this affect existing workflows?
  • No breaking changes if implemented as docs + examples + optional alias.
• Any backward compatibility concerns?
  • Alias is additive; canonical remains stable.