diff --git a/openapi.yaml b/openapi.yaml index 6fc8a70b..089d685e 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -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