Add endpoint to send test progress alerts for department goals in OpenAPI documentation

2026-01-27 09:12:58 +01:00
parent 28357df51d
commit be37edaa15
1 changed files with 92 additions and 0 deletions
@@ -2682,6 +2682,98 @@ paths:
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
+
+  /goals/department/progress-alert/test:
+    post:
+      tags:
+        - Goals
+      summary: Send a test progress alert for a department goal
+      description: |
+        Sends a progress alert for a department goal to the destination defined in the goal's criteria.
+
+        Permission required: `goals_department_progress_alert_test`.
+
+        Access control:
+        - The caller must be a superuser or belong to all departments targeted by the goal.
+
+        Behavior:
+        - Looks up the goal by `id`.
+        - Rebuilds the criteria from stored JSON and attaches the goal's departments.
+        - Renders the alert using the server-side renderer (respecting progress type/style/format and destination limits).
+        - Sends the alert to Slack, Email, or SMS depending on `progress_alert_destination`, unless overridden.
+      operationId: sendDepartmentGoalProgressAlertTest
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - id
+              properties:
+                id:
+                  type: integer
+                  description: The department goal id
+                  example: 42
+                overrideDestination:
+                  type: string
+                  description: Override the destination for this test
+                  enum: [SLACK, EMAIL, SMS, NONE]
+                  example: SLACK
+                email_to:
+                  type: string
+                  format: email
+                  description: Email recipient when destination is EMAIL
+                  example: tester@example.com
+                subject:
+                  type: string
+                  description: Optional email subject when destination is EMAIL
+                  example: Dept Goal Progress Test
+                sms_to:
+                  description: One or more MSISDN recipients when destination is SMS
+                  oneOf:
+                    - type: string
+                      description: Comma or semicolon separated list
+                      example: "+4512345678, +4598765432"
+                    - type: array
+                      items:
+                        type: string
+                      example: ["+4512345678", "+4598765432"]
+                slack_webhook:
+                  type: string
+                  description: Slack webhook URL when destination is SLACK
+                  example: https://hooks.slack.com/services/T000/B000/XXX
+                department_id:
+                  type: integer
+                  description: Department id to use that department's Slack webhook when destination is SLACK
+                  example: 3
+      responses:
+        '200':
+          description: Alert sent successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: integer
+                    description: Goal id
+                  destination:
+                    type: string
+                    description: Final destination used
+                    enum: [SLACK, EMAIL, SMS, NONE]
+                  target:
+                    description: The target used for delivery (email address, phone numbers, department id, or webhook)
+                  message_preview:
+                    type: string
+                    description: Rendered message preview
+                  provider_response:
+                    description: Provider-specific response or status message
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '500': { $ref: '#/components/responses/InternalServerError' }
    delete:
      tags:
        - Goals