From fa7de0cb848d651f75eb2181f15b953b844bb6bf Mon Sep 17 00:00:00 2001 From: stvnrlly Date: Wed, 5 Jul 2023 15:09:09 -0400 Subject: [PATCH 1/4] add new agreement adr --- docs/adrs/0005-agreement-data-model.md | 121 +++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 docs/adrs/0005-agreement-data-model.md diff --git a/docs/adrs/0005-agreement-data-model.md b/docs/adrs/0005-agreement-data-model.md new file mode 100644 index 000000000..964175aba --- /dev/null +++ b/docs/adrs/0005-agreement-data-model.md @@ -0,0 +1,121 @@ +# TITLE: Determine How to Handle Timezones in US Notify + + +| CREATED DATE | LAST UPDATED | STATUS | AUTHOR | STAKEHOLDERS | +| :---: | :---: | :---: | :---: | :---: | +| 06/21/2023 | 07/05/2023 | Accepted | @stvnrlly, @ccostino | @GSA/notify-contributors | + + +## CONTEXT AND PROBLEM STATEMENT + +**OPEN ISSUE(S):** https://github.com/GSA/notifications-api/issues/141, https://github.com/GSA/notifications-admin/issues/53, https://github.com/GSA/notifications-admin/issues/51 + +We will be entering into memoranda of understanding (MOU) and Interagency Agreements (IAA) with partner agencies. Data from those agreements will be important for application function. + +Unlike the UK version of the application, users will not be able to complete a self-service in-app agreement process. Our agreement process requires that documents be “signed” outside of the application and (especially in the case of an IAA) needs to happen with specific forms that have historically proven difficult to automate. + +Inside the application, we’ll want to know information about the partner as well as information necessary to avoid overspending the account. + +This information includes: +- Agreement identifier +- Agreement type (MOU or IAA) +- Agreement partner name +- Agreement status +- Agreement start datetime (known as period of performance) +- Agreement end datetime (known as period of performance) +- Agreement URL (where it is in Google Drive) +- Budget amount (*not* message limit) + + +## DECISION DRIVERS + +An implementation should address these needs: + +- The need for multiple agreements per partner over time +- The information and tools to stop sending before overspending +- The ability to connect data to organization and service models + +This is a minimal implementation of agreement data. It's quite possible that +it will change and expand over time, but those needs are note yet clear. + +Because we will continue to have the actual agreement docs safely in Google +Drive, this implementation does not need to be a source of truth and does not +need to retain history over time. + + +### SECURITY COMPLIANCE CONSIDERATIONS + +We will need to take care about permissions to change this data. Existing +permissions are fairly binary: you are a user or you are an admin. We should +consider whether that's still sufficient or if an in-between role would be +useful. + + +## CONSIDERED OPTIONS + +As a team, we've gone through the following options: + +- Add an Agreement model: a new class in `models.py` with the relevant fields. + - Pros: + - Separates agreements from the orgs, since they may change separately + - Multiple agreement-like models might be confusing, this avoids that + - Cons: + - Groups IAA and MOU together, which makes validation at the model level harder + and, in turn, makes it easier to break validation logic elsewhere in the + application + +- Add MOU and IAA models: two new classes in `models.py` with the same fields + but different configurations. + - Pros: + - Cleanest representation of the real world + - Allows SQL-level support for required/unique fields + - Cons: + - Most complex data model + +- Add agreement info to Organization model: no new classes, just a combination + of new fields and properties. + - Pros: + - No added model complexity + - Cons: + - Doesn’t directly allow for history + + +## CHOSEN OPTION: Add an Agreement model + +By adding an Agreement model, we’ll allow flexibility in the interaction between agreements and organizations but stop short of attempting to recreate the full complexity of agreements in our data model. + +If we later find that it’s necessary to separate MOU and IAA agreements, we should be able to perform a migration. + + +### Consequences + +- Positive + - We’ll gain more granular control over message limits for paid (IAA) agreements + - We can offer more agreement transparency to users. For example, identifying + agreements that will need renewal + +- Negative + - We’re adding some complexity to the data model + - We know that this implementation is an MVP and thus might have rough edges + - Manual work is necessary to keep agreements in sync with the real-world process + + +## VALIDATION AND NEXT STEPS + +This process includes adding the new model and updating the existing models to +use them. + +1. Add the new model: +- Add Agreement to models.py with the fields identified above +- Create migration to add/update table + +2. Update the Organisation model: +- Add one-to-many field linking one Organisation to multiple Agreements +- Add model property to convert budget amount into message limit +- Add model property to provide remaining budget based on sent messages +- Add model property about whether free tier or not +- Add model property for free tier usage (retrieve messages sent in a year) + +This will set up a new system, but stops short of connecting agreements to the +services actually sending the messages. This approach will be laid out in a +forthcoming ADR about managing message limits. From 22670b6ee6ecb69ba3441fa1e6565fedf2b07794 Mon Sep 17 00:00:00 2001 From: stvnrlly Date: Wed, 5 Jul 2023 15:12:41 -0400 Subject: [PATCH 2/4] adr housekeeping --- docs/adrs/0005-agreement-data-model.md | 2 +- docs/adrs/README.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/adrs/0005-agreement-data-model.md b/docs/adrs/0005-agreement-data-model.md index 964175aba..fb549800e 100644 --- a/docs/adrs/0005-agreement-data-model.md +++ b/docs/adrs/0005-agreement-data-model.md @@ -1,4 +1,4 @@ -# TITLE: Determine How to Handle Timezones in US Notify +# TITLE: Agreement info in data model | CREATED DATE | LAST UPDATED | STATUS | AUTHOR | STAKEHOLDERS | diff --git a/docs/adrs/README.md b/docs/adrs/README.md index 807236963..481f95121 100644 --- a/docs/adrs/README.md +++ b/docs/adrs/README.md @@ -172,6 +172,7 @@ top!). | ADR | TITLE | CURRENT STATUS | IMPLEMENTED | LAST MODIFIED | | :---: | :---: | :---: | :---: | :---: | +| [ADR-0005](./0005-agreement-data-model.md) | [Agreement info in data model](./0005-agreement-data-model.md) | Accepted | No | 07/05/2023 | | [ADR-0004](./0004-designing-pilot-content-visibility.md) | [Designing Pilot Content Visibility](./0004-designing-pilot-content-visibility.md) | Proposed | No | 06/20/2023 | | [ADR-0003](./0003-implementing-invite-expirations.md) | [Implementing User Invite Expirations](./0003-implementing-invite-expirations.md) | Proposed | No | 06/15/2023 | | [ADR-0002](./0002-how-to-handle-timezones.md) | [Determine How to Handle Timezones in US Notify](./0002-how-to-handle-timezones.md) | Accepted | Yes | 06/15/2023 | From f93972e9c48776e449a17c42c7bccbb187e94101 Mon Sep 17 00:00:00 2001 From: Carlo Costino Date: Wed, 5 Jul 2023 15:29:59 -0400 Subject: [PATCH 3/4] Minor doc formatting and typo fixes Signed-off-by: Carlo Costino --- docs/adrs/0005-agreement-data-model.md | 50 ++++++++++++++++---------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/docs/adrs/0005-agreement-data-model.md b/docs/adrs/0005-agreement-data-model.md index fb549800e..15fb1030c 100644 --- a/docs/adrs/0005-agreement-data-model.md +++ b/docs/adrs/0005-agreement-data-model.md @@ -10,11 +10,18 @@ **OPEN ISSUE(S):** https://github.com/GSA/notifications-api/issues/141, https://github.com/GSA/notifications-admin/issues/53, https://github.com/GSA/notifications-admin/issues/51 -We will be entering into memoranda of understanding (MOU) and Interagency Agreements (IAA) with partner agencies. Data from those agreements will be important for application function. +We will be entering into Memoranda of Understanding (MOU) and Interagency +Agreements (IAA) with partner agencies. Data from those agreements will be +important for application function. -Unlike the UK version of the application, users will not be able to complete a self-service in-app agreement process. Our agreement process requires that documents be “signed” outside of the application and (especially in the case of an IAA) needs to happen with specific forms that have historically proven difficult to automate. +Unlike the UK version of the application, users will not be able to complete a +self-service in-app agreement process. Our agreement process requires that +documents be “signed” outside of the application and (especially in the case of +an IAA) needs to happen with specific forms that have historically proven +difficult to automate. -Inside the application, we’ll want to know information about the partner as well as information necessary to avoid overspending the account. +Inside the application, we’ll want to know information about the partner as well +as information necessary to avoid overspending the account. This information includes: - Agreement identifier @@ -36,7 +43,7 @@ An implementation should address these needs: - The ability to connect data to organization and service models This is a minimal implementation of agreement data. It's quite possible that -it will change and expand over time, but those needs are note yet clear. +it will change and expand over time, but those needs are not yet clear. Because we will continue to have the actual agreement docs safely in Google Drive, this implementation does not need to be a source of truth and does not @@ -60,9 +67,9 @@ As a team, we've gone through the following options: - Separates agreements from the orgs, since they may change separately - Multiple agreement-like models might be confusing, this avoids that - Cons: - - Groups IAA and MOU together, which makes validation at the model level harder - and, in turn, makes it easier to break validation logic elsewhere in the - application + - Groups IAA and MOU together, which makes validation at the model level + harder and, in turn, makes it easier to break validation logic elsewhere + in the application - Add MOU and IAA models: two new classes in `models.py` with the same fields but different configurations. @@ -82,22 +89,27 @@ As a team, we've gone through the following options: ## CHOSEN OPTION: Add an Agreement model -By adding an Agreement model, we’ll allow flexibility in the interaction between agreements and organizations but stop short of attempting to recreate the full complexity of agreements in our data model. +By adding an Agreement model, we’ll allow flexibility in the interaction between +agreements and organizations but stop short of attempting to recreate the full +complexity of agreements in our data model. -If we later find that it’s necessary to separate MOU and IAA agreements, we should be able to perform a migration. +If we later find that it’s necessary to separate MOU and IAA agreements, we +should be able to perform a migration. ### Consequences - Positive - - We’ll gain more granular control over message limits for paid (IAA) agreements + - We’ll gain more granular control over message limits for paid (IAA) + agreements - We can offer more agreement transparency to users. For example, identifying - agreements that will need renewal + agreements that will need renewal - Negative - We’re adding some complexity to the data model - We know that this implementation is an MVP and thus might have rough edges - - Manual work is necessary to keep agreements in sync with the real-world process + - Manual work is necessary to keep agreements in sync with the real-world + process ## VALIDATION AND NEXT STEPS @@ -106,15 +118,15 @@ This process includes adding the new model and updating the existing models to use them. 1. Add the new model: -- Add Agreement to models.py with the fields identified above -- Create migration to add/update table + - Add Agreement to models.py with the fields identified above + - Create migration to add/update table 2. Update the Organisation model: -- Add one-to-many field linking one Organisation to multiple Agreements -- Add model property to convert budget amount into message limit -- Add model property to provide remaining budget based on sent messages -- Add model property about whether free tier or not -- Add model property for free tier usage (retrieve messages sent in a year) + - Add one-to-many field linking one Organisation to multiple Agreements + - Add model property to convert budget amount into message limit + - Add model property to provide remaining budget based on sent messages + - Add model property about whether free tier or not + - Add model property for free tier usage (retrieve messages sent in a year) This will set up a new system, but stops short of connecting agreements to the services actually sending the messages. This approach will be laid out in a From 34cd616cac970f11968f695ae98867a2a4ca3f5a Mon Sep 17 00:00:00 2001 From: Carlo Costino Date: Wed, 5 Jul 2023 15:34:30 -0400 Subject: [PATCH 4/4] Last bit of formatting improvements. Signed-off-by: Carlo Costino --- docs/adrs/0005-agreement-data-model.md | 43 ++++++++++++++------------ 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/docs/adrs/0005-agreement-data-model.md b/docs/adrs/0005-agreement-data-model.md index 15fb1030c..01b94533e 100644 --- a/docs/adrs/0005-agreement-data-model.md +++ b/docs/adrs/0005-agreement-data-model.md @@ -8,7 +8,10 @@ ## CONTEXT AND PROBLEM STATEMENT -**OPEN ISSUE(S):** https://github.com/GSA/notifications-api/issues/141, https://github.com/GSA/notifications-admin/issues/53, https://github.com/GSA/notifications-admin/issues/51 +**OPEN ISSUE(S):** +* https://github.com/GSA/notifications-api/issues/141 +* https://github.com/GSA/notifications-admin/issues/53 +* https://github.com/GSA/notifications-admin/issues/51 We will be entering into Memoranda of Understanding (MOU) and Interagency Agreements (IAA) with partner agencies. Data from those agreements will be @@ -42,19 +45,19 @@ An implementation should address these needs: - The information and tools to stop sending before overspending - The ability to connect data to organization and service models -This is a minimal implementation of agreement data. It's quite possible that +This is a minimal implementation of agreement data. It's quite possible that it will change and expand over time, but those needs are not yet clear. -Because we will continue to have the actual agreement docs safely in Google -Drive, this implementation does not need to be a source of truth and does not +Because we will continue to have the actual agreement docs safely in Google +Drive, this implementation does not need to be a source of truth and does not need to retain history over time. ### SECURITY COMPLIANCE CONSIDERATIONS -We will need to take care about permissions to change this data. Existing -permissions are fairly binary: you are a user or you are an admin. We should -consider whether that's still sufficient or if an in-between role would be +We will need to take care about permissions to change this data. Existing +permissions are fairly binary: you are a user or you are an admin. We should +consider whether that's still sufficient or if an in-between role would be useful. @@ -71,11 +74,11 @@ As a team, we've gone through the following options: harder and, in turn, makes it easier to break validation logic elsewhere in the application -- Add MOU and IAA models: two new classes in `models.py` with the same fields +- Add MOU and IAA models: two new classes in `models.py` with the same fields but different configurations. - Pros: - Cleanest representation of the real world - - Allows SQL-level support for required/unique fields + - Allows SQL-level support for required/unique fields - Cons: - Most complex data model @@ -102,7 +105,7 @@ should be able to perform a migration. - Positive - We’ll gain more granular control over message limits for paid (IAA) agreements - - We can offer more agreement transparency to users. For example, identifying + - We can offer more agreement transparency to users. For example, identifying agreements that will need renewal - Negative @@ -114,20 +117,20 @@ should be able to perform a migration. ## VALIDATION AND NEXT STEPS -This process includes adding the new model and updating the existing models to +This process includes adding the new model and updating the existing models to use them. 1. Add the new model: - - Add Agreement to models.py with the fields identified above - - Create migration to add/update table + - Add Agreement to models.py with the fields identified above + - Create migration to add/update table 2. Update the Organisation model: - - Add one-to-many field linking one Organisation to multiple Agreements - - Add model property to convert budget amount into message limit - - Add model property to provide remaining budget based on sent messages - - Add model property about whether free tier or not - - Add model property for free tier usage (retrieve messages sent in a year) + - Add one-to-many field linking one Organisation to multiple Agreements + - Add model property to convert budget amount into message limit + - Add model property to provide remaining budget based on sent messages + - Add model property about whether free tier or not + - Add model property for free tier usage (retrieve messages sent in a year) -This will set up a new system, but stops short of connecting agreements to the -services actually sending the messages. This approach will be laid out in a +This will set up a new system, but stops short of connecting agreements to the +services actually sending the messages. This approach will be laid out in a forthcoming ADR about managing message limits.