Skip to content

Commit b0bccc9

Browse files
JBrenesSimpatJBrenesSimpat
authored
[DMS-865] Add year dropdown to swagger UI (#751)
* Add year selector to swagger UI * copilot suggestions * set display none for selector and update documentation
1 parent 2f77ac5 commit b0bccc9

File tree

8 files changed

+1060
-17
lines changed

8 files changed

+1060
-17
lines changed

‎eng/Dms-Management.psm1‎

Lines changed: 191 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -641,4 +641,194 @@ function Get-DmsInstances {
641641
return $response
642642
}
643643

644-
Export-ModuleMember -Function Add-CmsClient, Get-CmsToken, Add-Vendor, Add-Application, Get-DmsToken, Get-CurrentSchoolYear, Add-DmsInstance, Get-DmsInstances, Invoke-Api
644+
<#
645+
.SYNOPSIS
646+
Creates a DMS Instance Route Context by sending a POST request to the Configuration Service.
647+
648+
.DESCRIPTION
649+
Adds a route context (key-value pair) to an existing DMS Instance.
650+
651+
.PARAMETER CmsUrl
652+
The base URL of the Config server (e.g., http://localhost:8081).
653+
654+
.PARAMETER InstanceId
655+
The ID of the DMS Instance to which this route context will be added (mandatory).
656+
657+
.PARAMETER ContextKey
658+
The context key (e.g., "schoolYear", "districtId"). Mandatory.
659+
660+
.PARAMETER ContextValue
661+
The context value (e.g., "2024", "255901"). Mandatory.
662+
663+
.PARAMETER AccessToken
664+
The bearer token for authorization (mandatory).
665+
666+
.OUTPUTS
667+
[long] Returns the Route Context ID of the newly created route context.
668+
669+
.EXAMPLE
670+
# Add schoolYear route context to an instance
671+
$routeContextId = Add-DmsInstanceRouteContext -AccessToken $token -InstanceId 1 -ContextKey "schoolYear" -ContextValue "2024"
672+
#>
673+
function Add-DmsInstanceRouteContext {
674+
[CmdletBinding()]
675+
param (
676+
[ValidateNotNullOrEmpty()]
677+
[string]$CmsUrl = "http://localhost:8081",
678+
679+
[Parameter(Mandatory = $true)]
680+
[long]$InstanceId,
681+
682+
[Parameter(Mandatory = $true)]
683+
[ValidateNotNullOrEmpty()]
684+
[string]$ContextKey,
685+
686+
[Parameter(Mandatory = $true)]
687+
[ValidateNotNullOrEmpty()]
688+
[string]$ContextValue,
689+
690+
[Parameter(Mandatory = $true)]
691+
[string]$AccessToken
692+
)
693+
694+
$routeContextData = @{
695+
instanceId = $InstanceId
696+
contextKey = $ContextKey
697+
contextValue = $ContextValue
698+
}
699+
700+
$invokeParams = @{
701+
BaseUrl = $CmsUrl
702+
RelativeUrl = "v2/dmsInstanceRouteContexts"
703+
Method = "Post"
704+
ContentType = "application/json"
705+
Body = ConvertTo-Json -InputObject $routeContextData -Depth 10
706+
Headers = @{ Authorization = "Bearer $AccessToken" }
707+
}
708+
709+
$response = Invoke-Api @invokeParams
710+
711+
return $response.id
712+
}
713+
714+
<#
715+
.SYNOPSIS
716+
Creates multiple DMS Instances with school year route contexts.
717+
718+
.DESCRIPTION
719+
Creates a DMS Instance for each school year in the specified range.
720+
Each instance will have a route context with key "schoolYear" and the year as the value.
721+
722+
.PARAMETER CmsUrl
723+
The base URL of the Config server (e.g., http://localhost:8081).
724+
725+
.PARAMETER StartYear
726+
The first school year in the range (mandatory).
727+
728+
.PARAMETER EndYear
729+
The last school year in the range (mandatory).
730+
731+
.PARAMETER PostgresPassword
732+
The PostgreSQL password (mandatory).
733+
734+
.PARAMETER PostgresDbName
735+
The PostgreSQL database name. Defaults to "edfi_datamanagementservice".
736+
737+
.PARAMETER PostgresHost
738+
The PostgreSQL host. Defaults to "dms-postgresql".
739+
740+
.PARAMETER PostgresPort
741+
The PostgreSQL port. Defaults to 5432.
742+
743+
.PARAMETER PostgresUser
744+
The PostgreSQL username. Defaults to "postgres".
745+
746+
.PARAMETER AccessToken
747+
The bearer token for authorization (mandatory).
748+
749+
.OUTPUTS
750+
Array of hashtables containing InstanceId and Year for each created instance.
751+
752+
.EXAMPLE
753+
# Create instances for years 2022-2026
754+
$instances = Add-DmsSchoolYearInstances -AccessToken $token -StartYear 2022 -EndYear 2026 -PostgresPassword "secret123"
755+
#>
756+
function Add-DmsSchoolYearInstances {
757+
[CmdletBinding()]
758+
param (
759+
[ValidateNotNullOrEmpty()]
760+
[string]$CmsUrl = "http://localhost:8081",
761+
762+
[Parameter(Mandatory = $true)]
763+
[int]$StartYear,
764+
765+
[Parameter(Mandatory = $true)]
766+
[int]$EndYear,
767+
768+
[Parameter(Mandatory = $true)]
769+
[string]$PostgresPassword,
770+
771+
[ValidateNotNullOrEmpty()]
772+
[string]$PostgresDbName = "edfi_datamanagementservice",
773+
774+
[ValidateNotNullOrEmpty()]
775+
[string]$PostgresHost = "dms-postgresql",
776+
777+
[int]$PostgresPort = 5432,
778+
779+
[ValidateNotNullOrEmpty()]
780+
[string]$PostgresUser = "postgres",
781+
782+
[Parameter(Mandatory = $true)]
783+
[string]$AccessToken
784+
)
785+
786+
# Validate year range
787+
if ($StartYear -gt $EndYear) {
788+
throw "StartYear ($StartYear) cannot be greater than EndYear ($EndYear)"
789+
}
790+
791+
$createdInstances = @()
792+
793+
Write-Host "Creating DMS Instances for school years $StartYear to $EndYear..." -ForegroundColor Cyan
794+
795+
for ($year = $StartYear; $year -le $EndYear; $year++) {
796+
Write-Host " Creating instance for School Year $year..." -ForegroundColor Yellow
797+
798+
# Create DMS Instance
799+
$instanceId = Add-DmsInstance `
800+
-CmsUrl $CmsUrl `
801+
-InstanceType "SchoolYear" `
802+
-InstanceName "School Year $year" `
803+
-PostgresPassword $PostgresPassword `
804+
-PostgresDbName $PostgresDbName `
805+
-PostgresHost $PostgresHost `
806+
-PostgresPort $PostgresPort `
807+
-PostgresUser $PostgresUser `
808+
-AccessToken $AccessToken
809+
810+
Write-Host " Instance created with ID: $instanceId" -ForegroundColor Green
811+
812+
# Add route context for school year
813+
$routeContextId = Add-DmsInstanceRouteContext `
814+
-CmsUrl $CmsUrl `
815+
-InstanceId $instanceId `
816+
-ContextKey "schoolYear" `
817+
-ContextValue $year.ToString() `
818+
-AccessToken $AccessToken
819+
820+
Write-Host " Route context created with ID: $routeContextId (schoolYear=$year)" -ForegroundColor Green
821+
822+
$createdInstances += @{
823+
InstanceId = $instanceId
824+
Year = $year
825+
RouteContextId = $routeContextId
826+
}
827+
}
828+
829+
Write-Host "Successfully created $($createdInstances.Count) DMS Instances with school year route contexts" -ForegroundColor Green
830+
831+
return $createdInstances
832+
}
833+
834+
Export-ModuleMember -Function Add-CmsClient, Get-CmsToken, Add-Vendor, Add-Application, Get-DmsToken, Get-CurrentSchoolYear, Add-DmsInstance, Get-DmsInstances, Add-DmsInstanceRouteContext, Add-DmsSchoolYearInstances, Invoke-Api

‎eng/docker-compose/SCHOOL_YEAR_INSTANCES.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# School Year Instance Setup
2+
3+
This guide explains how to set up multiple DMS instances with school year routing.
4+
5+
## Overview
6+
7+
The `start-local-dms.ps1` script now supports automatic creation of multiple DMS instances, each configured with a specific school year route context. This is useful for multi-tenant scenarios where you need to separate data by school year.
8+
9+
## Quick Start
10+
11+
### Create School Year Instances
12+
13+
To create DMS instances for a range of school years, use the `-SchoolYearRange` parameter:
14+
15+
```powershell
16+
./start-local-dms.ps1 -EnableConfig -EnvironmentFile ./.env -EnableSwaggerUI -LoadSeedData -SchoolYearRange "2022-2026"
17+
```
18+
19+
This will:
20+
21+
1. Start all required services (PostgreSQL, DMS, Configuration Service)
22+
2. Create 5 DMS instances: one for each year from 2022 to 2026
23+
3. Configure route contexts for each instance with `schoolYear` as the key
24+
4. Make the instances available at URLs like:
25+
- `http://localhost:8080/2022/data`
26+
- `http://localhost:8080/2023/data`
27+
- `http://localhost:8080/2024/data`
28+
- `http://localhost:8080/2025/data`
29+
- `http://localhost:8080/2026/data`
30+
31+
### Format
32+
33+
The `SchoolYearRange` parameter uses the format: `StartYear-EndYear`
34+
35+
Examples:
36+
37+
- `"2022-2026"` - Creates instances for 2022, 2023, 2024, 2025, 2026
38+
- `"2024-2025"` - Creates instances for 2024, 2025
39+
- `"2025-2025"` - Creates a single instance for 2025
40+
41+
## What Gets Created
42+
43+
For each school year in the range, the script creates:
44+
45+
1. **DMS Instance**: A database instance with:
46+
- **Instance Type**: "SchoolYear"
47+
- **Instance Name**: "School Year {YEAR}"
48+
- **Connection String**: Configured from your environment file
49+
50+
2. **Route Context**: A routing rule with:
51+
- **Context Key**: "schoolYear"
52+
- **Context Value**: The year (e.g., "2024")
53+
54+
## Swagger UI Integration
55+
56+
When you use the `-EnableSwaggerUI` flag along with `-SchoolYearRange`, the Swagger UI will automatically:
57+
58+
1. Detect all available school years from the OpenAPI specification
59+
2. Display a school year selector dropdown
60+
3. **Set the current school year as the default** (calculated based on the current date):
61+
- If current month > June: uses next calendar year
62+
- Otherwise: uses current calendar year
63+
4. Update the API base URL when you change the selected year
64+
65+
### Example
66+
67+
If you're accessing Swagger UI in August 2025:
68+
69+
- Default selected year: **2026** (because August > June)
70+
- Available years: All years from your range
71+
72+
If you're accessing Swagger UI in March 2025:
73+
74+
- Default selected year: **2025** (because March ≤ June)
75+
- Available years: All years from your range
76+
77+
## Complete Example
78+
79+
```powershell
80+
# Start DMS with school year instances for 2022-2026
81+
./start-local-dms.ps1 `
82+
-EnableConfig `
83+
-EnvironmentFile ./.env `
84+
-EnableSwaggerUI `
85+
-LoadSeedData `
86+
-SchoolYearRange "2022-2026" `
87+
-r
88+
```
89+
90+
> [!NOTE]
91+
> If you are using .env file don't forget to uncomment ROUTE_QUALIFIER_SEGMENTS
92+
> and set the value equals to schoolYear
93+
94+
```
95+
ROUTE_QUALIFIER_SEGMENTS=schoolYear
96+
```
97+
98+
This command:
99+
100+
- Rebuilds images (`-r`)
101+
- Enables Configuration Service (`-EnableConfig`)
102+
- Loads seed data (`-LoadSeedData`)
103+
- Enables Swagger UI (`-EnableSwaggerUI`)
104+
- Creates instances for years 2022-2026
105+
106+
## Single Instance (Default Behavior)
107+
108+
If you don't specify `-SchoolYearRange`, the script will create a single default instance:
109+
110+
```powershell
111+
./start-local-dms.ps1 -EnableConfig -EnvironmentFile ./.env -EnableSwaggerUI -LoadSeedData
112+
```
113+
114+
This creates:
115+
116+
- **1 DMS Instance**: "Local Development Instance"
117+
- **No route contexts**: Accessible at `http://localhost:8080/data`
118+
119+
## Manual Route Context Creation
120+
121+
If you need more complex routing or want to add route contexts manually, you can still use the Configuration Service API. See `test-schoolyear-route.http` in `src/dms/tests/RestClient/` for examples.
122+
123+
## Troubleshooting
124+
125+
### Changes not reflected immediately
126+
127+
After creating instances with route contexts, the DMS may take a moment to refresh its cache. If you don't see the new routes immediately:
128+
129+
1. Wait 20-30 seconds for the cache to refresh
130+
2. Restart the DMS container if needed:
131+
132+
```powershell
133+
docker restart dms-local-edfi-dm-1
134+
```
135+
136+
### Invalid year range format
137+
138+
Ensure your range uses the correct format: `"YYYY-YYYY"` with a hyphen separator.
139+
140+
✅ Correct: `-SchoolYearRange "2022-2026"`
141+
❌ Incorrect: `-SchoolYearRange "2022 2026"` or `-SchoolYearRange "22-26"`
142+
143+
## See Also
144+
145+
- `Dms-Management.psm1` - PowerShell module with functions for managing DMS instances
146+
- `test-schoolyear-route.http` - REST Client examples for manual route creation
147+
- `edfi-school-year-from-spec.js` - Swagger UI plugin for school year selection

0 commit comments

Comments
 (0)