-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: How to add a send destination [skip pizza]
- Loading branch information
1 parent
b92d401
commit 18a51ed
Showing
1 changed file
with
75 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,75 @@ | ||
# How to Add a Send Destination (Integration) | ||
|
||
This guide outlines the steps required to add a new integration destination to PlanX. | ||
|
||
## Setup | ||
1. **Configure send destination** | ||
- Add new destination to `SEND_DESTINATIONS` const in `planx-core` | ||
|
||
## Database (Hasura) | ||
1. **Create audit table** | ||
- Name format: `new_destination_applications` | ||
- Grant necessary Hasura permissions (copy for `bops_applications`) | ||
|
||
1. **Update views** | ||
- Update `submission_services_log` view | ||
- Update `submission_services_summary` view | ||
|
||
## Frontend | ||
1. **Update Editor component** | ||
- Add new destination label and checkbox in Editor component | ||
- Location: `editor.planx.uk/src/@planx/components/Send/Editor.tsx` | ||
- Follow existing pattern for label text and styling in `options` object | ||
|
||
1. **Implement validation rules** | ||
- Add any destination-specific validation in Editor component | ||
- Consider: | ||
- Which team is sending this? | ||
- Which services are able to submit to this destination? | ||
|
||
## Metabase | ||
1. **Check Metabase** | ||
- Check any queries which rely on `submission_services_summary` | ||
- You may need to rescan the table for new columns to be picked up | ||
|
||
## Data sanitation | ||
1. **Update sanitation job** | ||
- Add table to sanitation cron job | ||
- Location: `api.planx.uk/modules/webhooks/service/sanitiseApplicationData/operations.ts` | ||
- Implement specific sanitation rules if needed | ||
- Test sanitation works as expected | ||
|
||
## Secret management | ||
1. **Configure integration secrets** | ||
- Add required secrets to `team_integrations` table | ||
- Update `planx-core` to read new columns (`TeamClient.getIntegrations()`) | ||
|
||
## API | ||
1. **Create send events** | ||
The frontend "Send" components generates a `CombinedEventsPayload` object, this needs to be parsed in the `CreateSendEventsController` to generate a Hasura event. This in turn will hit the API endpoint which parses the session into the required payload for submission. | ||
|
||
- Parse the incoming request | ||
- Generate a Hasura scheduled event for the new send destination | ||
|
||
1. **Create payment send events** | ||
Submission can also be driven by an invite to pay event (not triggered by an applicant directly hitting the public "Send" component). We need to ensure that this event can generate a submission event for the new destination. | ||
|
||
- Parse `CombinedResponse` in `createPaymentSendEvents()` (location: `api.planx.uk/modules/pay/service/inviteToPay/createPaymentSendEvents.ts`) | ||
- Generate a Hasura scheduled event for the new send destination | ||
|
||
2. **Add API Routes** | ||
- Create new route: | ||
```typescript | ||
router.post( | ||
"/new-destination/{localAuthority}", | ||
useHasuraAuth, | ||
validate(sendIntegrationSchema), | ||
sendToNewDestinationController | ||
); | ||
``` | ||
- Implement controller with: | ||
- Team integration validation (check previous validation rules configured in Editor) | ||
- Submission handling (parse session, authenticate with send destination, construct payload for submission) | ||
- Audit record creation (write to `new_destination_applications` table) | ||
- Add `service.ts` layer for business logic | ||
- Update `docs.yaml` Swagger file |