ClaimsXten BOIP Creation Tool

A Windows PowerShell + WPF wizard that clones and updates Business/Operational Implementation Plan (BOIP) documents for a new change number and release. The tool lets you start from an existing change’s BOIP folder (or from a template), validates new inputs, and auto‑updates Microsoft Word files with new release numbers and deployment dates (Prod/QA/Dev) according to simple business rules.

---

Table of contents

• What this tool does
• How it works (architecture)
• Prerequisites
• Folder layout & required files
• Running the app
• Wizard flow
• Key functions and responsibilities
• Configuration knobs
• Logging & troubleshooting
• Known limitations / future improvements
• License

---

What this tool does

• Guided wizard (WPF) to capture:
  • Previous Change Number (to reuse its BOIP folder),
  • New Change Number,
  • Previous & New Release Number (e.g., R23.1),
  • Deployment dates for Prod, QA, and Dev.
• Clones the previous change’s BOIP folder into a new one for the new change number.
• Renames BOIP Word files to match the new change number.
• Opens each Word document and performs find/replace to update:
  • Previous → New release number,
  • Previous → New deployment dates (Prod/QA/Dev),
  • Adjusts Prod start text when deployment is on Friday or Sunday (e.g., “Starting at 18:30” for Fri; “Ready for Business” handling for Sun).
• Color‑coded progress log in the UI (Info/Update/Warning/Verbose).

---

How it works (architecture)

• Entry point: Main.ps1
  • Wires up the WPF wizard by loading XAML (via Get-XamlObject).
  • Declares event handlers for text boxes, date pickers, and buttons.
  • Validates input and spins up a background runspace to keep the UI responsive during file operations and Word automation.
• Functions library: Functions.ps1
  • Get-XamlObject – Loads XAML and required WPF assemblies (MaterialDesign in XAML).
  • Format-Date – Normalizes selected dates to the expected string format (e.g., Wed 7/24/24), and centralizes day‑of‑week abbreviations.
  • Create-Boip-Dir – Creates the new BOIP directory from the previous change (or template) and renames Word files.
  • Update-Boips – Opens Word (COM automation) and updates dates / release numbers in each BOIP.
  • Temp-Boip-Updates – Same idea as above for the template workflow.
  • Message-Log – Appends colored, timestamp‑free log lines to the UI (RichTextBox).
  • Runspace-Cleanup – Disposes the runspace when work completes/fails and triggers GC.
• UI technologies:
  • WPF/XAML views (loaded at runtime),
  • MaterialDesignInXaml assemblies (MaterialDesignThemes.Wpf.dll, MaterialDesignColors.dll).

---

Prerequisites

• Windows with PowerShell 5.1 (or newer Desktop PowerShell).
• .NET Framework (WPF) – present on most Windows desktops.
• Microsoft Word (Desktop) – for COM‑automation of .docx files.
• Execution Policy that allows running local scripts, e.g.:

  Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

• Modules / Assemblies
  • PSExcel module (some environments use it for Excel I/O). If missing, install beforehand:

    Install-Module PSExcel -Scope CurrentUser

  • assembly\MaterialDesignThemes.Wpf.dll and assembly\MaterialDesignColors.dll beside the scripts.

Note: The script attempts to install/import PSExcel if unavailable; pre‑installing it avoids prompts/permission issues.

---

Folder layout & required files

repo-root/
├─ Main.ps1                # entry point (wizard + orchestration)
├─ Functions.ps1           # helper functions and business logic
├─ assembly/
│  ├─ MaterialDesignThemes.Wpf.dll
│  └─ MaterialDesignColors.dll
└─ ui/                     # your XAML views referenced by the wizard
   ├─ *.xaml
   └─ (optional) utils/

You also need access to your BOIP root path (network or local) that contains previous change folders. The tool uses your inputs to find the previous change folder, clone it, and generate a new change folder with updated documents.

---

Running the app

From a PowerShell prompt in the repo root:

# Launch the WPF wizard
powershell -ExecutionPolicy Bypass -File .\Main.ps1

If you run into policy or dependency issues, see Prerequisites and Troubleshooting below.

---

Wizard flow

1. Choose a source:
   • From Previous Change – enter Previous Change Number and New Change Number.
   • From Template – you’ll point the wizard to the template location instead.
2. Enter releases:
   • Previous Release and New Release (validated; e.g., R23.1).
3. Pick dates:
   • Prod, QA, Dev – select from the date pickers.
   • The tool formats them via Format-Date and applies rules (Fri/Sun behaviors) for Prod.
4. Generate:
   • The wizard:
     • Clones the previous folder → new folder,
     • Renames Word files to the new change number,
     • Find/Replaces old → new release and dates across BOIP docs,
     • Shows a color‑coded log as it works.
5. Finish: review the new folder and BOIP docs.

---

Key functions and responsibilities

Get-XamlObject

Loads XAML files at runtime and injects WPF objects into PowerShell. Also loads MaterialDesignInXaml assemblies from the local assembly folder.

Format-Date ([ref]$deployDate)

Takes a date string (from the date pickers) and ensures a uniform output the rest of the code expects (e.g., Wed 7/24/24).

Create-Boip-Dir ($prevBoipPath, $currentBoipPath, $prevChange, $newChange, ...)

• Validates and creates the destination folder.
• Copies files from previous change (or template) to the new folder.
• Renames BOIP documents for the new change number.

Update-Boips ($currentBoipPath, $prevRelease, $newRelease, $prodDate, $qaDate, $devDate)

• Iterates all Word files in the BOIP.
• Uses Word COM automation to update content:
  • release numbers,
  • deployment dates,
  • special Friday/Sunday handling for Prod start lines.
• Saves and closes each document.

Temp-Boip-Updates (...)

Processing equivalent when you choose the template workflow rather than previous change.

Message-Log ($message)

Adds a line to the wizard’s log area. Messages prefixed with Info, Update, Warning, Verbose are styled differently.

Runspace-Cleanup

Disposes of the background runspace after completion/failure and forces a GC to free resources.

---

Configuration knobs

A few values you may want to adjust in the scripts:

• Regex formats for Change Number and Release inputs (see the text‑changed handlers in Main.ps1). Tune these to your org’s naming if the wizard flags “Incorrect Format.”
• Prod start rules (Friday @ 18:30, Sunday “Ready for Business”): adjust in Update-Boips if your policy differs.
• Root paths for BOIP directories: ensure Main.ps1 sets/receives the correct root (often supplied via the wizard UI).

---

Logging & troubleshooting

• The wizard log shows progress live; errors are red, updates green.
• Common issues
  • Execution Policy blocked – run with -ExecutionPolicy Bypass or relax policy for CurrentUser.
  • Missing assemblies – ensure both MaterialDesign*.dll files exist in the assembly folder.
  • Word not installed – install Microsoft Word Desktop; the automation requires it.
  • Leftover WINWORD.exe – if Word remains open after failures, end the process and re‑run.
  • Regex validation fails – adapt the patterns in Main.ps1 to match your change/release conventions.
  • PSExcel install prompt – pre‑install the module to avoid elevation prompts.

---

Known limitations / future improvements

• COM cleanup: consider explicitly releasing COM objects:

  [void][Runtime.InteropServices.Marshal]::FinalReleaseComObject($objDoc)
  [void][Runtime.InteropServices.Marshal]::FinalReleaseComObject($objWord)
  [gc]::Collect(); [gc]::WaitForPendingFinalizers()

• Error handling: wrap Word automation with try { ... } finally {} to guarantee close/quit even on errors.
• Centralize regex: keep all input patterns in one place (easier to maintain and test).
• Config file: move hard‑coded paths/policies into a JSON/YAML settings file.
• Unit tests: add Pester tests for Format-Date and renaming logic.
• Packaging: create a Start-BoipWizard.ps1 runner or a packaged EXE via PS2EXE for non‑PowerShell users.

---

License

Internal / private—fill in the license that applies to your environment.