From 5c0540afaeeef5c12968ebcc46cb0d0b0f9ef3e8 Mon Sep 17 00:00:00 2001 From: Stephanie Buadu <47737608+acn-sbuad@users.noreply.github.com> Date: Fri, 2 Feb 2024 15:27:24 +0100 Subject: [PATCH] updated notifications arch docs (#1394) * updated notifications arch docs * documented regression tests * split charts into multiple * Update _index.en.md Typo * added dependency --------- Co-authored-by: Thomas Bakken <70642698+tba76@users.noreply.github.com> --- .../notifications/architecture/_index.en.md | 15 +- ...tifications-topic-process-email.drawio.svg | 640 +++++++++++ ...tifications-topic-process-order.drawio.svg | 388 +++++++ ...notifications-topic-process-sms.drawio.svg | 277 +++++ .../notifications-topic.drawio.svg | 998 ------------------ .../architecture/notifications/_index.en.md | 26 +- .../notifications/dbmodel.drawio.svg | 651 +++++++----- .../architecture/solution.drawio.svg | 237 +++-- .../send-notifications/_index.en.md | 4 +- 9 files changed, 1898 insertions(+), 1338 deletions(-) create mode 100644 content/notifications/architecture/notifications-topic-process-email.drawio.svg create mode 100644 content/notifications/architecture/notifications-topic-process-order.drawio.svg create mode 100644 content/notifications/architecture/notifications-topic-process-sms.drawio.svg delete mode 100644 content/notifications/architecture/notifications-topic.drawio.svg diff --git a/content/notifications/architecture/_index.en.md b/content/notifications/architecture/_index.en.md index 985ebf06ea1..0c0b4112798 100644 --- a/content/notifications/architecture/_index.en.md +++ b/content/notifications/architecture/_index.en.md @@ -20,7 +20,20 @@ The following diagram illustrates the overall data flow. ## Process flow between microservices and Kafka topics -![Topics](notifications-topic.drawio.svg "Illustration of the data flow including Kafka Topics") +{{% expandlarge id="anotifications-topic-process-order.drawio.svg" header="Flow chart for order processing" %}} +![Topics](notifications-topic-process-order.drawio.svg "Flow chart including Kafka topics for order processing") +{{% /expandlarge %}} + + +{{% expandlarge id="anotifications-topic-process-email.drawio.svg" header="Flow chart for email notification processing" %}} +![Topics](notifications-topic-process-email.drawio.svg "Flow chart including Kafka topics for email notification processing") +{{% /expandlarge %}} + + +{{% expandlarge id="anotifications-topic-process-sms.drawio.svg" header="Flow chart for sms notification processing" %}} +![Topics](notifications-topic-process-sms.drawio.svg "Flow chart including Kafka topics for sms notification processing") +{{% /expandlarge %}} + ## System and service dependencies ### Internal diff --git a/content/notifications/architecture/notifications-topic-process-email.drawio.svg b/content/notifications/architecture/notifications-topic-process-email.drawio.svg new file mode 100644 index 00000000000..02d5a2164c5 --- /dev/null +++ b/content/notifications/architecture/notifications-topic-process-email.drawio.svg @@ -0,0 +1,640 @@ + + + + + + + +
+
+
+ + Altinn.Notifications.Email + +
+
+
+ + + Altinn.Notifications... + + + + + + + + + + + + + + + + +
+
+
+ Sending status set to: sending in DB & email published to topic +
+
+
+ + + Sending status set to: sen... + + + + + + + +
+
+
+ Time triggered service +
+ triggers retrieval of past due emails from db +
+
+
+ + + Time triggered service... + + + + + + + + + +
+
+
+ altinn. +
+ notification. +
+ email. +
+ queue +
+
+
+ + + altinn.... + + + + + + + + + +
+
+
+ + Send email through communication services + +
+
+
+ + + Send email through c... + + + + + + + + +
+
+
+ NO +
+
+
+ + + NO + + + + + + + + +
+
+
+ YES +
+
+
+ + + YES + + + + + + + +
+
+
+ + Operation accepted? + +
+
+
+ + + Operation accepted? + + + + + + + + + +
+
+
+ + Publish send notification operation identifier to topic + +
+
+
+ + + Publish send notific... + + + + + + + + + +
+
+
+ altinn. +
+ notification. +
+ email. +
+ sending. +
+ accepted +
+
+
+ + + altinn.... + + + + + + + + + +
+
+
+ + Get operation update from communication services + +
+
+
+ + + Get operation update... + + + + + + + + +
+
+
+ NO +
+
+
+ + + NO + + + + + + + + +
+
+
+ YES +
+
+
+ + + YES + + + + + + + +
+
+
+ + Is result still 'Sending'? + +
+
+
+ + + Is result still 'Sendi... + + + + + + + + + +
+
+
+ altinn. +
+ notification. +
+ email. +
+ status. +
+ updated +
+
+
+ + + altinn.... + + + + + + + + + +
+
+
+ + Generate send operation result + +
+
+
+ + + Generate send operat... + + + + + + + + + +
+
+
+ altinn. +
+ notification. +
+ email. +
+ queue.retry +
+
+
+ + + altinn.... + + + + + + + + +
+
+
+ No further consumer implemented +
+
+
+ + + No furth... + + + + + + + + +
+
+
+ YES +
+
+
+ + + YES + + + + + + + +
+
+
+ + Last update more than +
+ 8 secs ago? +
+ +
+
+
+ + + Last update more than... + + + + + + + + +
+
+
+ NO +
+
+
+ + + NO + + + + + + + + + +
+
+
+ + An exception is thrown +
+ +
+
+
+ + + An exception is thrown + + + + + + + + + +
+
+
+ Persist status update to DB +
+
+
+ + + Persist status updat... + + + + + + + + +
+
+
+ NO +
+
+
+ + + NO + + + + + + + + +
+
+
+ YES +
+
+
+ + + YES + + + + + + + +
+
+
+ + Successfully persisted? + +
+
+
+ + + Successfully persisted? + + + + + + + + +
+
+
+ No further actions +
+
+
+ + + No furth... + + + + + + + + +
+
+
+ NO +
+
+
+ + + NO + + + + + + + + +
+
+
+ YES +
+
+
+ + + YES + + + + + + + +
+
+
+ + is +
+ RequestFailedException +
+ +
+
+
+ + + is... + + + + + + + +
+
+
+ Altinn.Notifications +
+
+
+ + + Altinn.Notifications + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/content/notifications/architecture/notifications-topic-process-order.drawio.svg b/content/notifications/architecture/notifications-topic-process-order.drawio.svg new file mode 100644 index 00000000000..213389a4db3 --- /dev/null +++ b/content/notifications/architecture/notifications-topic-process-order.drawio.svg @@ -0,0 +1,388 @@ + + + + + + + + + +
+
+
+ altinn. +
+ notifications. +
+ orders. +
+ pastdue +
+
+
+ + + altinn.... + + + + + + + + + + + + +
+
+
+ NO +
+
+
+ + + NO + + + + + + + +
+
+
+ + Generation successful? + +
+
+
+ + + Generation successful? + + + + + + + + + +
+
+
+ Order processing status set to completed +
+
+
+ + + Order processing sta... + + + + + + + + +
+
+
+ Order processing status: completed +
+
+
+ + + Order pr... + + + + + + + + + +
+
+
+ + Generate an email + +
+ + notification for each recipient and persist in database + +
+
+
+ + + Generate an email... + + + + + + + +
+
+
+ YES +
+
+
+ + + YES + + + + + + + +
+
+
+ Order processing status set to processing in DB & order published to topic +
+
+
+ + + Order processing status se... + + + + + + + + + +
+
+
+ altinn. +
+ notifications. +
+ orders. +
+ pastdue. +
+ retry +
+
+
+ + + altinn.... + + + + + + + + + +
+
+
+ + Generate an email + +
+ + notification for each recipient not yet persisted in database + +
+
+
+ + + Generate an email... + + + + + + + + +
+
+
+ YES +
+
+
+ + + YES + + + + + + + + +
+
+
+ NO +
+
+
+ + + NO + + + + + + + +
+
+
+ + Generation successful? + +
+
+
+ + + Generation successful? + + + + + + + + + +
+
+
+ Order processing status set to completed +
+
+
+ + + Order processing sta... + + + + + + + + +
+
+
+ Order processing status: completed +
+
+
+ + + Order pr... + + + + + + + + +
+
+
+ Order processing status: processing +
+
+
+ + + Order pr... + + + + + + + +
+
+
+ Altinn.Notifications +
+
+
+ + + Altinn.Notifications + + + + + + + + +
+
+
+
+ + Time triggered service + +
+ + triggers retrieval of past due orders from db + +
+
+
+
+
+
+
+
+
+ + + Time triggered service... + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/content/notifications/architecture/notifications-topic-process-sms.drawio.svg b/content/notifications/architecture/notifications-topic-process-sms.drawio.svg new file mode 100644 index 00000000000..6668d15f35b --- /dev/null +++ b/content/notifications/architecture/notifications-topic-process-sms.drawio.svg @@ -0,0 +1,277 @@ + + + + + + + +
+
+
+ + Altinn.Notifications.Sms + +
+
+
+ + + Altinn.Notifications... + + + + + + + + + + + + + + + + +
+
+
+ Sending status set to: sending in DB & smspublished to topic +
+
+
+ + + Sending status set to: sen... + + + + + + + +
+
+
+ Time triggered service +
+ triggers retrieval of past due sms from db +
+
+
+ + + Time triggered service... + + + + + + + + + +
+
+
+ altinn. +
+ notification. +
+ sms. +
+ queue +
+
+
+ + + altinn.... + + + + + + + + + +
+
+
+ altinn. +
+ notification. +
+ sms. +
+ queue.retry +
+
+
+ + + altinn.... + + + + + + + + +
+
+
+ No further consumer implemented +
+
+
+ + + No furth... + + + + + + + + +
+
+
+ YES +
+
+
+ + + YES + + + + + + + +
+
+
+ Altinn.Notifications +
+
+
+ + + Altinn.Notifications + + + + + + + + + +
+
+
+ + Send sms via Link Mobility Gateway + +
+
+
+ + + Send sms via Link Mo... + + + + + + + + +
+
+
+ NO +
+
+
+ + + NO + + + + + + + +
+
+
+ + Did an error occur? + +
+
+
+ + + Did an error occur? + + + + + + + + + +
+
+
+ + Generate send operation result + +
+
+
+ + + Generate send operat... + + + + + + + + +
+
+
+ No further consumer implemented +
+
+
+ + + No furth... + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/content/notifications/architecture/notifications-topic.drawio.svg b/content/notifications/architecture/notifications-topic.drawio.svg deleted file mode 100644 index 482656a59d4..00000000000 --- a/content/notifications/architecture/notifications-topic.drawio.svg +++ /dev/null @@ -1,998 +0,0 @@ - - - - - - - - - -
-
-
- altinn. -
- notifications. -
- orders. -
- pastdue -
-
-
- - - altinn.... - - - - - - - - - - - - -
-
-
- NO -
-
-
- - - NO - - - - - - - -
-
-
- - Generation successful? - -
-
-
- - - Generation successful? - - - - - - - - - -
-
-
- Order processing status set to completed -
-
-
- - - Order processing sta... - - - - - - - - -
-
-
- Order processing status: completed -
-
-
- - - Order pr... - - - - - - - - - -
-
-
- - Generate an email - -
- - notification for each recipient and persist in database - -
-
-
- - - Generate an email... - - - - - - - -
-
-
- YES -
-
-
- - - YES - - - - - - - -
-
-
- Order processing status set to processing in DB & order published to topic -
-
-
- - - Order processing status se... - - - - - - - - - -
-
-
- altinn. -
- notifications. -
- orders. -
- pastdue. -
- retry -
-
-
- - - altinn.... - - - - - - - - - -
-
-
- - Generate an email - -
- - notification for each recipient not yet persisted in database - -
-
-
- - - Generate an email... - - - - - - - - -
-
-
- YES -
-
-
- - - YES - - - - - - - - -
-
-
- NO -
-
-
- - - NO - - - - - - - -
-
-
- - Generation successful? - -
-
-
- - - Generation successful? - - - - - - - - - -
-
-
- Order processing status set to completed -
-
-
- - - Order processing sta... - - - - - - - - -
-
-
- Order processing status: completed -
-
-
- - - Order pr... - - - - - - - - -
-
-
- Order processing status: processing -
-
-
- - - Order pr... - - - - - - - -
-
-
- Altinn.Notifications -
-
-
- - - Altinn.Notifications - - - - - - - -
-
-
- - Altinn.Notifications.Email - -
-
-
- - - Altinn.Notifications... - - - - - - - - -
-
-
-
- - Time triggered service - -
- - triggers retrieval of past due orders from db - -
-
-
-
-
-
-
-
-
- - - Time triggered service... - - - - - - - - - - - - - - - - - - - -
-
-
- Sending status set to: sending in DB & email published to topic -
-
-
- - - Sending status set to: sen... - - - - - - - -
-
-
- Time triggered service -
- triggers retrieval of past due emails from db -
-
-
- - - Time triggered service... - - - - - - - - - -
-
-
- altinn. -
- notification. -
- email. -
- queue -
-
-
- - - altinn.... - - - - - - - - - -
-
-
- - Send email through communication services - -
-
-
- - - Send email through c... - - - - - - - - -
-
-
- NO -
-
-
- - - NO - - - - - - - - -
-
-
- YES -
-
-
- - - YES - - - - - - - -
-
-
- - Operation accepted? - -
-
-
- - - Operation accepted? - - - - - - - - - -
-
-
- - Publish send notification operation identifier to topic - -
-
-
- - - Publish send notific... - - - - - - - - - -
-
-
- altinn. -
- notification. -
- email. -
- sending. -
- accepted -
-
-
- - - altinn.... - - - - - - - - - -
-
-
- - Get operation update from communication services - -
-
-
- - - Get operation update... - - - - - - - - -
-
-
- NO -
-
-
- - - NO - - - - - - - - -
-
-
- YES -
-
-
- - - YES - - - - - - - -
-
-
- - Is result still 'Sending'? - -
-
-
- - - Is result still 'Sendi... - - - - - - - - - -
-
-
- altinn. -
- notification. -
- email. -
- status. -
- updated -
-
-
- - - altinn.... - - - - - - - - - -
-
-
- - Generate send operation result - -
-
-
- - - Generate send operat... - - - - - - - - - -
-
-
- altinn. -
- notification. -
- email. -
- queue.retry -
-
-
- - - altinn.... - - - - - - - - -
-
-
- No further consumer implemented -
-
-
- - - No furth... - - - - - - - - -
-
-
- YES -
-
-
- - - YES - - - - - - - -
-
-
- - Last update more than -
- 8 secs ago? -
- -
-
-
- - - Last update more than... - - - - - - - - -
-
-
- NO -
-
-
- - - NO - - - - - - - - - -
-
-
- - An exception is thrown -
- -
-
-
- - - An exception is thrown - - - - - - - - - -
-
-
- Persist status update to DB -
-
-
- - - Persist status updat... - - - - - - - - -
-
-
- NO -
-
-
- - - NO - - - - - - - - -
-
-
- YES -
-
-
- - - YES - - - - - - - -
-
-
- - Successfully persisted? - -
-
-
- - - Successfully persisted? - - - - - - - - -
-
-
- No further actions -
-
-
- - - No furth... - - - - - - - - -
-
-
- NO -
-
-
- - - NO - - - - - - - - -
-
-
- YES -
-
-
- - - YES - - - - - - - -
-
-
- - is -
- RequestFailedException -
- -
-
-
- - - is... - - - - - - - - - Text is not SVG - cannot display - - - - \ No newline at end of file diff --git a/content/notifications/architecture/notifications/_index.en.md b/content/notifications/architecture/notifications/_index.en.md index b66e8d150c9..ca8d796b3cd 100644 --- a/content/notifications/architecture/notifications/_index.en.md +++ b/content/notifications/architecture/notifications/_index.en.md @@ -33,12 +33,14 @@ Data related to notification orders, notifications and receipients is persisted Each table in the _notifications_ schema is described in the table below, followed by a diagram showing the relation between the tables. -| Table | Description | -| ------------------ | ----------------------------------------------------------------------------------------------------------- | -| orders | Contains metadata for each notification order | -| emailtexts | Holds the static common texts related to a notification | -| emailnotifications | Holds metadata for each notfication along with recipient contact details | -| resourcelimitlog | Keeps track of resource limits outages for dependent systems e.g. Azure Communication services | +| Table | Description | +| ------------------ | ------------------------------------------------------------------------------------------------ | +| orders | Contains metadata for each notification order | +| emailtexts | Holds the static common texts related to an email notification | +| emailnotifications | Holds metadata for each email notfication along with recipient contact details | +| smstexts | Holds the static common texts related to an sms notification | +| smsnotifications | Holds metadata for each sms notification along with recipient contact details | +| resourcelimitlog | Keeps track of resource limits outages for dependent systems e.g. Azure Communication services | ![Diagram of Notifications Database](dbmodel.drawio.svg "Diagram of Notifications Database") @@ -127,6 +129,7 @@ Notifications microservice takes use of a range of libraries to support the prov | Confluent.Kafka | Integrate with kafka broker | [Repository](https://github.com/confluentinc/confluent-kafka-dotnet), [Documentation](https://developer.confluent.io/get-started/dotnet/) | | FluentValidation | Used to validate content of API request | [Repository](https://github.com/FluentValidation/FluentValidation), [Documentation](https://docs.fluentvalidation.net/en/latest/)| | JWTCookieAuthentication| Used to validate Altinn token (JWT) | [Repository](https://github.com/Altinn/altinn-authentication), [Documentation](../../../authentication/architecture/jwtcookie/)| +| libphonenumber-csharp | Used to validate mobile numbers | [Repository](https://github.com/caseykramer/libphonenumber-csharp), [Documentation](https://github.com/caseykramer/libphonenumber-csharp) | | Npgsql | Used to access the database server | [Repository]( https://github.com/rdagumampan/yuniql ), [Documentation](https://www.npgsql.org/)| | Yuniql | DB migration | [Repository](https://github.com/rdagumampan/yuniql), [Documentation](https://yuniql.io/)| @@ -165,14 +168,23 @@ start all Kafka-related dependencies in a Docker containers. The automated tests for this micro service are implemented through [Grafana's k6](https://k6.io/). The tool is specialized for load tests, but we do use it for automated API tests as well. +The test set is used for both use case and regression tests. -### Use case tests +#### Use case tests [All use case workflows are available on GitHub](https://github.com/Altinn/altinn-notifications/tree/main/.github/workflows) Use case tests are run every 15 minuts through GitHub Actions. The tests run during the use case tests are defined in the k6 test project. The aim of the tests is to run through central functionality of the solution to ensure that it is running and available to our end users. +#### Regression tests +[All regression test workflows are available on GitHub](https://github.com/Altinn/altinn-notifications/tree/main/.github/workflows) + +The regression tests are run once a week and 5 minutes after deploy to a given environment. +The tests run during the regression tests are defined in the k6 test project. +The aim of the regression tests is to cover as much of our functionality as possible, +to ensure that a new release does not break any existing functionality. + ## Hosting ### Web API diff --git a/content/notifications/architecture/notifications/dbmodel.drawio.svg b/content/notifications/architecture/notifications/dbmodel.drawio.svg index cadad4081e5..d8299b776db 100644 --- a/content/notifications/architecture/notifications/dbmodel.drawio.svg +++ b/content/notifications/architecture/notifications/dbmodel.drawio.svg @@ -1,129 +1,162 @@ - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + -
+
1:1 @@ -131,79 +164,79 @@
- + 1:1 - - - - + + + + - + emailtexts - - - - + + + + PK - - - + + + _id - - - - + + + + FK - - - + + + _orderid - - - - + + + + fromaddress - - - - + + + + subject - - - - + + + + body - - - - + + + + contenttype - + -
+
1:* @@ -211,257 +244,275 @@
- + + 1:* + + + + + + + + +
+
+
+ 1:* +
+
+
+ + 1:* - - - - + + + + - + orders - - - - + + + + PK - - - + + + _id - - - - + + + + alternateid - - - - + + + + creatorname - - - - + + + + sendersreference - - - - + + + + created - - - - - + + + + + requestedsendtime - - - - + + + + processed - - - - + + + + processedstatus - - - - + + + + notificationorder - - - - + + + + - + emailnotifications - - - - + + + + PK - - - + + + _id - - - - + + + + FK - - - + + + _orderid - - - - + + + + alternateid - - - - + + + + recipientid - - - - + + + + toaddress - - - - + + + + result - - - - + + + + resulttime - - - - + + + + expirytime - - - - + + + + operationid - - - - + + + + - + resourcelimitlog - - - - + + + + PK - - - + + + id - - - - + + + + emaillimittimeout - - - - + + + + - + smstexts - - - - + + + + PK - - - + + + _id - - - - + + + + FK - - - + + + _orderid - - - - + + + + sendernumber - - - - + + + + body - + -
+
1:1 @@ -469,11 +520,95 @@
- + 1:1 + + + + + + + smsnotifications + + + + + + + PK + + + + + + _id + + + + + + + FK + + + + + + _orderid + + + + + + + alternateid + + + + + + + recipientid + + + + + + + mobilenumber + + + + + + + result + + + + + + + resulttime + + + + + + + expirytime + + + + + + + gatewayreference + + diff --git a/content/notifications/architecture/solution.drawio.svg b/content/notifications/architecture/solution.drawio.svg index 1932473f791..d97c2836f9b 100644 --- a/content/notifications/architecture/solution.drawio.svg +++ b/content/notifications/architecture/solution.drawio.svg @@ -1,11 +1,11 @@ - + - + -
+
Notifications DB @@ -13,18 +13,18 @@
- + Notifi... - - - + + + -
+
Cron jobs @@ -32,14 +32,14 @@
- + Cron jobs - - - + + + @@ -93,22 +93,22 @@ - + - + Kafka - - - - - - + + + + + + -
+
Places a notification order @@ -116,7 +116,7 @@
- + Places a notification order @@ -124,7 +124,7 @@ -
+
@@ -137,17 +137,17 @@
- + POST /orders/email... - - + + -
+
Send email @@ -155,17 +155,17 @@
- + Send email - - + + -
+
Report status @@ -173,19 +173,19 @@
- + Report status - - - - + + + + -
+
Notifications API @@ -193,19 +193,19 @@
- + Notifications API - - - - + + + + -
+
Trigger processing @@ -217,18 +217,18 @@
- + Trigger processing... - - - + + + -
+
Notification Email @@ -238,15 +238,15 @@
- + Notification Email... - + -
+
Consumes status updates @@ -254,18 +254,18 @@
- + Consumes status updates - - - - + + + + -
+
Publishes notifications @@ -273,18 +273,18 @@
- + Publishes notifications - - - - + + + + -
+
Publishes status updates @@ -292,15 +292,15 @@
- + Publishes status updates - + -
+
Consumes notifications @@ -308,17 +308,17 @@
- + Consumes notifications - - + + -
+
Report status @@ -326,12 +326,105 @@
- + Report status - + + + + + + +
+
+
+ Report status +
+
+
+ + + Report status + + + + + + + + + +
+
+
+ Notification Sms +
+ service +
+
+
+ + + Notification Sms... + + + + + + + + + +
+
+
+ Consumes notifications +
+
+
+ + + Consumes notifications + + + + + + +
+
+
+ Publishes status updates +
+
+
+ + + Publishes status updates + + + + + + + + +
+
+
+ Send SMS +
+
+
+ + + Send SMS + + + + diff --git a/content/notifications/send-notifications/_index.en.md b/content/notifications/send-notifications/_index.en.md index 8590f7f537b..69d5b66caaf 100644 --- a/content/notifications/send-notifications/_index.en.md +++ b/content/notifications/send-notifications/_index.en.md @@ -14,8 +14,8 @@ toc: true ## Combining notification channels {{% notice info %}} -Per November '23 only one communication chanel is supported. -Once multiple channels are provided, it will be possible to combine notification channels for a single order request. +Per January '24 it is not possible to combine notification channels for a single order request. +This functionality can be expected in the first half of '24. {{% /notice %}} ## Registries used for recipient addresses