feat: Enhance deployment automation and Bicep CLI prerequisites

README.md

@@ -272,8 +272,13 @@ Follow the quick deploy steps on the deployment guide to deploy this solution to
 
 > **Note:** This solution accelerator requires **Azure Developer CLI (azd) version 1.18.0 or higher**. Please ensure you have the latest version installed before proceeding with deployment. [Download azd here](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd).
 
+> **Note:** This solution accelerator also requires **Bicep CLI version 0.33.0 or higher** for compiling infrastructure templates. [Install Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/install).
+
 [Click here to launch the deployment guide](./docs/DeploymentGuide.md)
 
+> ⚠️ **Post-Deployment Setup Required**  
+> `azd up` provisions infrastructure only. After it completes, run the post-deployment scripts to register schemas, upload sample data, and configure authentication. See [Step 5 of the Deployment Guide](./docs/DeploymentGuide.md#step-5-post-deployment-configuration) for commands and required permissions.
+
 | [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/content-processing-solution-accelerator) | [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/content-processing-solution-accelerator) | [![Open in Visual Studio Code Web](https://img.shields.io/static/v1?style=for-the-badge&label=Visual%20Studio%20Code%20(Web)&message=Open&color=blue&logo=visualstudiocode&logoColor=white)](https://vscode.dev/azure/?vscode-azure-exp=foundry&agentPayload=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvY29udGVudC1wcm9jZXNzaW5nLXNvbHV0aW9uLWFjY2VsZXJhdG9yL3JlZnMvaGVhZHMvbWFpbi9pbmZyYS92c2NvZGVfd2ViIiwgImluZGV4VXJsIjogIi9pbmRleC5qc29uIiwgInZhcmlhYmxlcyI6IHsiYWdlbnRJZCI6ICIiLCAiY29ubmVjdGlvblN0cmluZyI6ICIiLCAidGhyZWFkSWQiOiAiIiwgInVzZXJNZXNzYWdlIjogIiIsICJwbGF5Z3JvdW5kTmFtZSI6ICIiLCAibG9jYXRpb24iOiAiIiwgInN1YnNjcmlwdGlvbklkIjogIiIsICJyZXNvdXJjZUlkIjogIiIsICJwcm9qZWN0UmVzb3VyY2VJZCI6ICIiLCAiZW5kcG9pbnQiOiAiIn0sICJjb2RlUm91dGUiOiBbImFpLXByb2plY3RzLXNkayIsICJweXRob24iLCAiZGVmYXVsdC1henVyZS1hdXRoIiwgImVuZHBvaW50Il19) |
 |---|---|---|
 

azure.yaml

@@ -9,14 +9,3 @@ requiredVersions:
 metadata:
   template: content-processing@1.0
   name: content-processinge@1.0
-
-hooks:
-  postprovision:
-    posix:
-      shell: sh
-      run: sed -i 's/\r$//' ./infra/scripts/post_deployment.sh; bash ./infra/scripts/post_deployment.sh
-      interactive: true
-    windows:
-      shell: pwsh
-      run: ./infra/scripts/post_deployment.ps1
-      interactive: true

azure_custom.yaml

@@ -64,13 +64,3 @@ services:
       registry: ${AZURE_CONTAINER_REGISTRY_ENDPOINT}
       remoteBuild: true
 
-hooks:
-  postprovision:
-    posix:
-      shell: sh
-      run: sed -i 's/\r$//' ./infra/scripts/post_deployment.sh; bash ./infra/scripts/post_deployment.sh
-      interactive: true
-    windows:
-      shell: pwsh
-      run: ./infra/scripts/post_deployment.ps1
-      interactive: true

docs/AVMPostDeploymentGuide.md

@@ -11,9 +11,10 @@ This document provides guidance on post-deployment steps after deploying the Con
 After successfully deploying the Content Processing Solution Accelerator using the AVM template, you need to:
 
 1. **Register schemas** — upload schema files, create a schema set, and link them together
-2. **Configure authentication** — set up app registration for secure access
+2. **Process sample files** — upload and process sample claim bundles for verification
+3. **Configure authentication** — set up app registration for secure access
 
-> **Note:** When deploying via `azd up`, schema registration happens automatically through a post-provisioning hook. AVM deployments require the manual steps below.
+> **Note:** Post-deployment data setup and authentication are manual steps for both `azd` and AVM deployments. Run the scripts in this guide after infrastructure provisioning.
 
 ## Prerequisites
 
@@ -73,14 +74,27 @@ The script is idempotent — it skips schemas and schema sets that already exist
 
 > **Want custom schemas?** See [Customize Schema Data](./CustomizeSchemaData.md) to create your own document schemas.
 
-### Step 4: Configure Authentication (Required)
+### Step 4: Process Sample File Bundles (Optional)
+
+After schema registration, you can upload and process the included sample claim bundles to verify the deployment is working end to end. Each sample folder (`claim_date_of_loss/`, `claim_hail/`) contains a `bundle_info.json` manifest that maps files to their schema classes.
+
+The workflow for each bundle:
+1. **Create a claim batch** with the schema set ID via `PUT /claimprocessor/claims`
+2. **Upload each file** with its mapped schema ID via `POST /claimprocessor/claims/{claim_id}/files`
+3. **Submit the batch** for processing via `POST /claimprocessor/claims`
+
+You can perform these steps via the web UI or the API directly. See the [API documentation](./API.md) and [Golden Path Workflows](./GoldenPathWorkflows.md) for details.
+
+> **Note:** In `azd` and AVM flows, sample file processing runs when you execute the post-deployment script manually.
+
+### Step 5: Configure Authentication (Required)
 
 **This step is mandatory for application access:**
 
 1. Follow [App Authentication Configuration](./ConfigureAppAuthentication.md).
 2. Wait up to 10 minutes for authentication changes to take effect.
 
-### Step 5: Verify Deployment
+### Step 6: Verify Deployment
 
 1. Access your application using the Web App URL from your deployment output.
 2. Confirm the application loads successfully.

docs/ConfigureAppAuthentication.md

@@ -1,5 +1,25 @@
 # Set up Authentication in Azure Container App
 
+> ### ✅ Recommended: run the authentication script first
+>
+> `azd up` no longer runs authentication setup automatically. Run the script below after deployment:
+>
+> **Windows:**
+> ```powershell
+> ./infra/scripts/setup_auth.ps1
+> ```
+>
+> **macOS/Linux:**
+> ```bash
+> bash ./infra/scripts/setup_auth.sh
+> ```
+>
+> See [DeploymentGuide.md § 5.3](./DeploymentGuide.md#53-configure-authentication-manual-script) for step-by-step instructions.
+>
+> Follow the portal/manual steps below if:
+> - Your tenant policy prohibits programmatic app registration or secret creation
+> - The script reports a permission or policy failure that cannot be resolved in your current identity
+
 This document provides step-by-step instructions to configure Azure App Registrations for the front-end and back-end applications.
 
 > **Note:** The solution deploys four container apps. Only the **Web** and **API** container apps require Entra ID authentication provider configuration. The **Content Processor** (app) and **Content Process Workflow** (wkfl) containers are internal services that communicate via Storage Queues using managed identity — they do not expose public endpoints.

docs/CustomizeSchemaData.md

@@ -73,18 +73,18 @@ flowchart LR
 
 A new JSON Schema document needs to be created that defines the schema as a declarative description of your document type.
 
-> **Schema Folder:** [/src/ContentProcessorAPI/samples/schemas/](/src/ContentProcessorAPI/samples/schemas/) — All schema JSON files should be placed into this folder
+> **Schema Folder:** [../src/ContentProcessorAPI/samples/schemas/](../src/ContentProcessorAPI/samples/schemas/) — All schema JSON files should be placed into this folder
 
 **Sample Schemas:** The accelerator ships with 4 sample schemas — use any as a starting template:
 
-| Schema                    | File                                                                              | Class Name                      | Auto-registered |
+| Schema                    | File                                                                              | Class Name                      | Included sample |
 | ------------------------- | --------------------------------------------------------------------------------- | ------------------------------- | --------------- |
-| Auto Insurance Claim Form | [autoclaim.json](/src/ContentProcessorAPI/samples/schemas/autoclaim.json)             | `AutoInsuranceClaimForm`        | ✅               |
-| Police Report             | [policereport.json](/src/ContentProcessorAPI/samples/schemas/policereport.json)       | `PoliceReportDocument`          | ✅               |
-| Repair Estimate           | [repairestimate.json](/src/ContentProcessorAPI/samples/schemas/repairestimate.json)   | `RepairEstimateDocument`        | ✅               |
-| Damaged Vehicle Image     | [damagedcarimage.json](/src/ContentProcessorAPI/samples/schemas/damagedcarimage.json) | `DamagedVehicleImageAssessment` | ✅               |
+| Auto Insurance Claim Form | [autoclaim.json](../src/ContentProcessorAPI/samples/schemas/autoclaim.json)             | `AutoInsuranceClaimForm`        | ✅               |
+| Police Report             | [policereport.json](../src/ContentProcessorAPI/samples/schemas/policereport.json)       | `PoliceReportDocument`          | ✅               |
+| Repair Estimate           | [repairestimate.json](../src/ContentProcessorAPI/samples/schemas/repairestimate.json)   | `RepairEstimateDocument`        | ✅               |
+| Damaged Vehicle Image     | [damagedcarimage.json](../src/ContentProcessorAPI/samples/schemas/damagedcarimage.json) | `DamagedVehicleImageAssessment` | ✅               |
 
-> **Note:** All 4 schemas are automatically registered during deployment (via `azd up` or the `register_schema.py` script) and grouped into the **"Auto Claim"** schema set.
+> **Note:** These 4 schemas are included in the repository and are registered when you run the manual post-deployment schema registration step (for example, `register_schemas.ps1` / `register_schemas.sh`, or `run_post_deployment.ps1` / `run_post_deployment.sh`). They are then grouped into the **"Auto Claim"** schema set.
 
 Duplicate one of these files and update with fields that represent your document type.
 
@@ -158,22 +158,22 @@ Example using the REST Client extension:
 
 > **Note:** Install the [REST Client VSCode extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) to execute `.http` files directly in VS Code.
 
-> **Sample requests:** [/src/ContentProcessorAPI/test_http/invoke_APIs.http](/src/ContentProcessorAPI/test_http/invoke_APIs.http)
+> **Sample requests:** [../src/ContentProcessorAPI/test_http/invoke_APIs.http](../src/ContentProcessorAPI/test_http/invoke_APIs.http)
 
 The response returns a Schema `Id` — **save this** for Step 3.
 
 > ![Schema Registration REST API call with payload](./images/schema-register-api.png)
 
 ### Option B: Register via script (batch)
 
-> **Note:** The default sample schemas are registered **automatically** during `azd up` via the post-provisioning hook. You only need to run the script manually if you are adding custom schemas or if automatic registration was skipped.
+> **Note:** Default sample schemas are registered when you run the post-deployment script manually (see Deployment Guide Step 5.1). Run this script again whenever you add or update schemas.
 
 For bulk registration, use the provided script with a JSON manifest. The script performs three steps automatically:
 1. **Registers** individual schema files via `/schemavault/`
 2. **Creates** a schema set via `/schemasetvault/`
 3. **Adds** each registered schema into the schema set
 
-**Manifest file** ([schema_info.json](/src/ContentProcessorAPI/samples/schemas/schema_info.json)):
+**Manifest file** ([schema_info.json](../src/ContentProcessorAPI/samples/schemas/schema_info.json)):
 ```json
 {
   "schemas": [

docs/DeploymentGuide.md

@@ -159,6 +159,7 @@ Select one of the following options to deploy the Content Processing Solution Ac
 **Required Tools:**
 - [PowerShell 7.0+](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) 
 - [Azure Developer CLI (azd) 1.18.0+](https://aka.ms/install-azd)
+- [Bicep CLI 0.33.0+](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install)
 - [Python 3.9+](https://www.python.org/downloads/)
 - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
 - [Git](https://git-scm.com/downloads)
@@ -300,85 +301,112 @@ azd up
 
 ## Step 5: Post-Deployment Configuration
 
-### 5.1 Schema Registration (Automatic)
+### 5.1 Run Schema Registration (Manual)
 
- > Want to customize the schemas for your own documents? [Learn more about adding your own schemas here.](./CustomizeSchemaData.md)
+> Want to customize the schemas for your own documents? [Learn more about adding your own schemas here.](./CustomizeSchemaData.md)
 
-Schema registration happens **automatically** as part of the `azd up` post-provisioning hook — no manual steps required. After infrastructure is deployed, the hook:
+`azd up` now provisions infrastructure and application containers only. Post-provision data setup is split into **separate manual steps** so you can run, retry, or skip them independently.
 
-1. Waits for the API container app to be ready
-2. Registers the sample schema files (auto claim, damaged car image, police report, repair estimate)
-3. Creates an **"Auto Claim"** schema set
-4. Adds all registered schemas into the schema set
+Run schema registration first to:
 
-After successful deployment, the terminal displays container app details and schema registration output:
+1. Wait for the API container app to be ready
+2. Register the sample schema files (auto claim, damaged car image, police report, repair estimate)
+3. Create the **"Auto Claim"** schema set
+4. Add all registered schemas into the schema set
 
+**Windows (PowerShell):**
+
+```powershell
+./infra/scripts/register_schemas.ps1
+```
+
+**macOS/Linux:**
+
+```bash
+bash ./infra/scripts/register_schemas.sh
+```
+
+The script is idempotent and safe to re-run.
+
+### 5.2 Run Sample Data Upload (Manual)
+
+After schema registration completes, upload the sample bundles as a separate explicit step. This step:
+
+1. Resolves the existing **Auto Claim** schema set and registered schema IDs
+2. Creates sample claim batches for `claim_date_of_loss` and `claim_hail`
+3. Uploads each file with its mapped schema
+4. Submits each claim batch for processing
+
+**Windows (PowerShell):**
+
+```powershell
+./infra/scripts/upload_sample_data.ps1
+```
+
+**macOS/Linux:**
+
+```bash
+bash ./infra/scripts/upload_sample_data.sh
+```
+
+### 5.3 Configure Authentication (Manual Script)
+
+Run authentication setup as an explicit step after post-deployment data setup:
+
+**Windows (PowerShell):**
+
+```powershell
+./infra/scripts/setup_auth.ps1
 ```
-🧭 Web App Details:
-  ✅ Name: ca-<env>-web
-  🌐 Endpoint: ca-<env>-web.<region>.azurecontainerapps.io
-  🔗 Portal URL: https://portal.azure.com/#resource/...
-
-🧭 API App Details:
-  ✅ Name: ca-<env>-api
-  🌐 Endpoint: ca-<env>-api.<region>.azurecontainerapps.io
-  🔗 Portal URL: https://portal.azure.com/#resource/...
-
-🧭 Workflow App Details:
-  ✅ Name: ca-<env>-wkfl
-  🔗 Portal URL: https://portal.azure.com/#resource/...
-
-📦 Registering schemas and creating schema set...
-  ⏳ Waiting for API to be ready...
-  ✅ API is ready.
-============================================================
-Step 1: Register schemas
-============================================================
-✓ Successfully registered: Auto Insurance Claim Form's Schema Id - <id>
-✓ Successfully registered: Damaged Vehicle Image Assessment's Schema Id - <id>
-✓ Successfully registered: Police Report Document's Schema Id - <id>
-✓ Successfully registered: Repair Estimate Document's Schema Id - <id>
-
-============================================================
-Step 2: Create schema set
-============================================================
-✓ Created schema set 'Auto Claim' with ID: <id>
-
-============================================================
-Step 3: Add schemas to schema set
-============================================================
-  ✓ Added 'AutoInsuranceClaimForm' (<id>) to schema set
-  ✓ Added 'DamagedVehicleImageAssessment' (<id>) to schema set
-  ✓ Added 'PoliceReportDocument' (<id>) to schema set
-  ✓ Added 'RepairEstimateDocument' (<id>) to schema set
-
-============================================================
-Schema registration process completed.
-  Schema set ID: <id>
-  Schemas added: 4
-============================================================
-  ✅ Schema registration complete.
+
+**macOS/Linux:**
+
+```bash
+bash ./infra/scripts/setup_auth.sh
+```
+
+The auth script is idempotent and performs preflight validation before making changes.
+
+#### Skipping auth setup
+
+If your tenant blocks programmatic app registration, or you need to defer authentication setup, you can skip this step:
+
+```powershell
+azd env set AZURE_SKIP_AUTH_SETUP true
 ```
 
-### 5.2 Configure Authentication (Required)
+Then follow the manual instructions in [App Authentication Configuration](./ConfigureAppAuthentication.md). To re-enable later, set the value to `false` and re-run `setup_auth.ps1`.
+
+#### Required Permissions for auth setup
+
+- Create/update app registrations: **Application Administrator**, **Cloud Application Administrator**, or **Global Administrator**
+- Grant admin consent: **Cloud Application Administrator** or **Global Administrator**
+- Update Container Apps auth/secret settings: **Contributor** on the deployment resource group
 
-**This step is mandatory for application access:**
+If permissions are insufficient, the script exits early (or warns before consent) with clear remediation guidance.
 
-1. Follow [App Authentication Configuration](./ConfigureAppAuthentication.md).
-2. Wait up to 10 minutes for authentication changes to take effect.
+> **Note:** EasyAuth can take up to 10 minutes to fully propagate. If the Web app returns 500/401 immediately after setup, wait a few minutes and retry.
 
-### 5.3 Verify Deployment
+#### WAF (Well-Architected Framework) deployments
+
+Authentication script execution is fully compatible with the WAF / production profile (`main.waf.parameters.json`, which enables `enablePrivateNetworking`, `enableRedundancy`, and `enableScalability`). The Web and API container apps keep external ingress in the default WAF profile, so registered redirect URIs (`https://<fqdn>/.auth/login/aad/callback`) remain valid public entry points.
+
+> If you customize WAF to make Web or API ingress internal-only, run the auth script from an environment that can reach those private endpoints (for example, the deployed jumpbox or a VPN-connected host).
+
+### 5.4 Verify Deployment
 
 1. Access your application using the **Web App Endpoint** from the deployment output.
 2. Confirm the application loads successfully.
 3. Verify you can sign in with your authenticated account.
 
-### 5.4 Test the Application
+### 5.5 Test the Application
+
+> **Note:** If you ran [Step 5.2](#52-run-sample-data-upload-manual), two sample claim bundles (`claim_date_of_loss` and `claim_hail`) should already be processed in the web app.
 
 **Quick Test Steps:**
-1. **Download Samples**: Get sample files from the [samples directory](../src/ContentProcessorAPI/samples) — use the `claim_date_of_loss/` or `claim_hail/` folders for auto claim documents.
-2. **Upload**: In the app, select the **"Auto Claim"** schema set, choose a schema (e.g., Auto Insurance Claim Form), click Import Content, and upload a sample file.
-3. **Review**: Wait for completion (~1 min), then click the row to verify the extracted data against the source document.
+1. **Check Processed Results**: Open the web app — you should see the two sample claim batches already processed with extracted data.
+2. **Review**: Click a processed claim row to verify the extracted data against the source document.
+3. **Upload More (Optional)**: To test additional uploads, get sample files from the [samples directory](../src/ContentProcessorAPI/samples), select the **"Auto Claim"** schema set, and upload via Import Content.
 
 📖 **Detailed Instructions:** See the complete [Golden Path Workflows](./GoldenPathWorkflows.md) guide for step-by-step testing procedures.