Attach Agreements to Collectives

[alanna]

User story

As an admin I want to associate documents and notes with a particular Collective, so that I can keep everything together in the system. Examples are grant contracts, contracts for services, grant reporting obligations, etc.

Best solution for this problem

• An 'info' section under about
• It can be set to be visible publicly or not, but it's always visible to Collective and Host admins
• Functions like an Expense comments thread
• Host and Collective admins can post comments
• They can also upload attachments

MVP

A feature only for Host admins, which doesn't need to be polished, and is never public. Maybe accessed through the Hosted Collectives tab in Host dashboard, and host Admins could add text and attachments there?

We currently manage this kind of thing through a messy system of Google drive folders and it's quite easy to miss things. t would be super handy to be able to directly link people like auditors to associated files.

P2 low frequency, high impact

[natehn]

This would be helpful for OCF's grantmaking process and other situations where we need to pay someone based on a contract. Being able to attach the contract would make the process much smoother for the admin team.

[alinamanko]

I would love to see it happening. The only thing to consider from my perspective if going by the option of having the ability to add/review attachments through the hosted collectives tab is whether there would be a way to specify and categorize documents easily to avoid clutter. One example that comes to mind in relation to the grantmaking example is to ensure we could easily pick up those and associate them to the relevant expenses submitted. Would like to ensure that not all documents just live in one place without an easy way to sort through them.

[emberwry]

I love the idea of storing this stuff on the platform. could be interesting for cash policy and volunteer w9s. maybe we could tag the attachments and come up with a naming convention so it's easily searchable, like to look at all of the grants at once and also the full names associated with it. seconding Alina's idea to be able to associate expenses with uploaded documents, this could all fold together nicely in some kind of notification system, like what pops up when the user needs to submit their tax form, but for things that we as hosts are supposed to look out for, like, can i tell at a glance that a collective already has an approved cash application when i go to pay a cash expense? or if the payee is based in India, it can pop up to be sure that the account is payable. lots of possibilities here that take the burden off the host to remember all the nitpicky things. the mvp sounds like a great place to start.

[natehn]

I think #3433 could be a good starting point, or an alternative that could meet some of the more immediate needs

[katieOCF]

We need a way to manage documents and notes associated with collectives. Not having this function is a barrier to scalability. It also makes me nervous as a lawyer--the paper trail is so important to keep the organization healthy. Google docs is great for collaboration, but it's easy for someone to accidentally drag an item to the wrong folder or edit something that was supposed to remain untouched. Whenever possible, human error should be engineered out of the key document retention processes we need to be a responsible fiscal sponsor.

[dawnmatlak]

I'd love to see a notes feature that's visible to host admins only on Collective page. We have nuances regarding certain types of expenses that are complex to keep track of, and currently no great system for them. Having the ability to click on the collective page & view/add to private notes would be incredibly helpful.

[iamronen]

1. There are a few asks on this thread that need to be unpacked and addressed
2. We've done preparatory work #3753 in order to be ready to move in this direction.
3. This is a good example of a project that belongs in the workspace and not in the public profile page. The solution outlined above was based on trying to fit this into the public profile page and is therefore obsolete.
4. When scoping out the pending contributions project we recognized the "conversational" ux pattern in expenses as something we wanted to recreate for pending contributions (and in the future perhaps for other information entities). This did not fit in the initial scope of the pending contributions effort.
5. That "conversational pattern" can benefit from a few improvements including file attachments and leaving comments that are internal notes only visible for the fiscal host admins (similar to the capability that is available in Freshdesk).
6. I don't think that this conversational pattern is going to be sufficient for storing collective-related documents. I believe it will quickly overflow and become an unmanageable mess. I think there is room for thinking and shaping what a collective document repository can look like. In a way it already implicitly exists due to existing documents that are attached to expenses (and in the future, potentially to pending contributions).

However in terms of priorities all this is contingent on:

1. Creating the workplace - which we are doing now #6385
2. Research (ongoing) into a prioritized list of needed tools that can then gradually be added into the workplace.
3. Already it seems that a prime candidate is handling expenses with in-app notifications.
4. Then, it seems that tools for easing our support loads are needed.

All this to say, I think it will take us time to get to address this need but that the work we are doing is creating the conditions to solve it well (better then hacking yet another piece into the public collective profile page).

[alanna]

This is becoming a critical need for OCF and we would like it to be prioritised.

[alanna]

To be clear, the critical need for OCF is specifically the host-admin only version, for us to track important details about Collectives. It would be important that this info is only viewable to host admins and private from everyone else. For MVP we'd take just a text field notes section - we can paste in links to files in Google drive, etc if we can't have direct attachments. If we can't get this feature we're going to have to set up a whole CRM system outside the platform to track Collective notes. Maybe we should just do that, but I think it would be better to keep things all together on the platform.

[BenJam]

:wave: @alanna @katieOCF @dawnmatlak how is this managed currently and how much of an improvement would implementing this make objectively (i.e. it would save me searching for the collective's folder in gdocs)?

I ask as; I worry too about the possibility for this to be a complete mess with multiple documents attached to a collective that are not presented in the correct flows.

I too feel that having a note to the effect of 'this collective contracts the person on a monthly basis' and I do have that in mind when processing expenses for, say, PHPFoundation. Having notes attached to the collective would, in my opinion, not speed up the process for paying that expense without having the information presented at that point.

The reason I ask how this is done currently is that, the click, from expense to collective, could easily be a quick click into a separate document store. Either way I am just looking for the quickest flow from expense approved to payment with the necessary checks.

[katieOCF]

Thanks for asking! The need here includes but is not limited to expense workflows. Expense documentation and notes are an essential part of what we do, but we also have legal obligations across a variety of areas of law in many jurisdictions that require us to be able to locate records and notes about necessary context quickly, and we must be able to identify key facts quickly when we are alerted to any collective activity that could jeopardize our 501(c)(3) status.

Any activity that could jeopardize our 501(c)(3) status is an existential threat to OCF that must be handled swiftly and effectively. Here's a helpful summary https://nonprofitrisk.org/resources/articles/how-to-lose-your-501c3-tax-exempt-status-without-really-trying/ of ways to lose 501(c)(3) status.

Other areas of law where we have obligations that we can't meet without timely access to records and notes include but are not limited to employment law (varies by state, employment contracts/termination/etc must comply, these are not uniform standards across the US) and contract law (funder agreements, grant agreements--these vary by funder/collective, again, not uniform). It may be possible to use Justworks for employment contracts, which would be better than a G drive folder, imo.

To answer your question directly, when a time-sensitive issue with potential legal implications comes across my desk, I need to gather the relevant information asap to get legal advice and act accordingly before the matter escalates further. I don't only have to look through G drive for contracts or other legal documents (sometimes needing to request access along the way), I also have to comb through slack, freshdesk, OC, emails forwarded to me by the team, notes from team meetings in Around...anywhere we work is potentially a place I'll need to check back later because there is no centralized place to track key information. I also have live conversations with team members who know context that may not be captured in any of these places, and then I have to reconcile the different accounts from different team members, figuring out myself who has the most recent intel. I don't think manually tracking this information in individual docs is a viable solution at our current scale. Law firms use case management software for this purpose, sales firms use CRM software, and we need a solution, too.

On Thu, Mar 16, 2023 at 8:58 AM Benjamin Nickolls @.***> wrote:

👋 @alanna https://github.com/alanna @katieOCF https://github.com/katieOCF @dawnmatlak https://github.com/dawnmatlak how is this managed currently and how much of an improvement would implementing this make objectively (i.e. it would save me searching for the collective's folder in gdocs)?

I ask as; I worry too about the possibility for this to be a complete mess with multiple documents attached to a collective that are not presented in the correct flows.

I too feel that having a note to the effect of 'this collective contracts the person on a monthly basis' and I do have that in mind when processing expenses for, say, PHPFoundation. Having notes attached to the collective would, in my opinion, not speed up the process for paying that expense without having the information presented at that point.

The reason I ask how this is done currently is that, the click, from expense to collective, could easily be a quick click into a separate document store. Either way I am just looking for the quickest flow from expense approved to payment with the necessary checks.

— Reply to this email directly, view it on GitHub https://github.com/opencollective/opencollective/issues/4894#issuecomment-1471908247, or unsubscribe https://github.com/notifications/unsubscribe-auth/A6GBNYLFNLKK7FSAM72AQK3W4ME6PANCNFSM5HFP7XEQ . You are receiving this because you were mentioned.Message ID: @.***>

-- Katie Adamides (she/they) Operations Director Open Collective Foundation https://opencollective.foundation

[dawnmatlak]

from an expense POV, we are often trying to figure out specific details that live in the brains of one or two people (who may or may not be on the team right now). for example, if a collective has a lease on file for the rent expense they're submitting for, we can have a note on the platform that says "lease on file, dates active are x-x" (and then we'll know to find them in google docs if need be. we also can keep notes about collectives when we know we see the same issue repeating, ie: "if this collective has their client submit a hardship expense, please remind them to use our cash assistance or grant process". these types of notes will be invaluable for onboarding new finance staff & creating better sustainability on an internal organization level. right now, so many of our systems are built around what individual staff know (and the nuances they've mentally been tracking).

also note: i don't think it's necessarily as useful to attach files to this type of text box, as long as we can link to where the files live - as katie noted: we typically have to comb through many different platforms to seek out information

[BenJam]

there is no centralized place to track key information

so my argument is that, maybe, this is the actual problem. And that making a finance platform into a structured content management system isn't the right route to go here.

as long as we can link to where the files live

yeah I'm thinking that this might be best. Let's run a quick sync process to establish what might work here. INCOMING

[dawnmatlak]

i agree that turning the platform into an extensive CRM makes my eyes spin. mainly just wanted something rather simple (from a user standpoint).

[alanna]

I agree we should not try to replicate a fully featured CRM system. Maybe we should consider an integration with one?

But this issue seems more urgent to us than the timescale it will take to figure out the whole workspace idea, a third party CRM integration, etc. We're on the verge of hacking slack into a makeshift CRM at OCF and it's so messy.

Here's my MVP design:

All the other (valid!) questions, like should there be file attachments, how does someone know there are notes when processing an expense, should Collective admins have access to some version of this, should it show up in the Host Dashboard/workspace, etc, can be considered later.

[BenJam]

okay cool, just had a chat with @dawnmatlak and my concern is that without something in the main expense flow that prompts the person processing an expense, this will probably continue to slow things down.

So.

how about a way to series of notes, each with an optional link that describes things like:

• this collective has a lease on this building at $3,000 until Dec 2024 (link to lease)
• this collective has a contract with Bob to pay $6,000/month until April 2025 (link to agreement)

and that these notes are visible from a prompt on the host's expense processing page, with a dialogue that allows you to view the notes in the expense dashboard flow a la the attachment dialogue.

we'll take a look at what we can do Monday, otherwise, we'll get this started in 2 weeks.

[alanna]

Why the emphasis on expense flow? While OCF does have a need to reference notes and files in relation to expenses, it's really not exclusive to that. We need a way to reference notes outside the expense flow too, hence my idea to associate it with the main Collective page. @BenJam with you design, how will a host admin reference the notes when no expenses are involved? I don't really mind if it's a series or just one box we can update or whatever, for MVP. We just need a way to associate updateable text with a Collective somehow, which Host admins can reference.

[iamronen]

@BenJam both of the examples you gave seem very closely aligned with the need for something like "agreements" which I've expanded on in this Loomio thread. This information lives at the level of a collective and can be associated to expenses (and I would argue that eventually SHOULD be associated to expenses).

Also, in the research work I've been doing around the expense approval process, I have learned about OCF's need to track collectives who are approved for "cash assistance" - yet another form of agreement which is tracked in a dedicated spreadsheet, but is really information that is needed in correlation to expenses (and fiscal host admins either memorize which collectives are approved and/or have to reference the spreadsheet).

[Betree]

From the engineering perspective, I would like to argue against implementing such a feature on the collective page. The collective page is our funnel for most newcomers on the platform, and we're working hard to keep it as simple and lightweight as possible. Introducing this additional complexity could have a negative impact on performance and UX. From a conceptual point of view, it also doesn't match the patterns and primary purpose of the collective page, which is by no means a place to administrate an account.

We're currently starting an experiment with the new workspace (https://github.com/opencollective/opencollective/issues/6385). If we can find an easy way to include it in there and match both projects' release dates, great!

Otherwise, I'll suggest implementing this as a new/separate page (e.g. /:collective/admin-documents) that we could eventually link from the navbar:

The main benefit of this approach would be isolating the implementation, which will make it easier to transfer the feature to whatever place we think it should live in (i.e., the admin workspace) when it is ready.

[iamronen]

Feedback from @katieOCF after conversation with @Memo-Es and me https://docs.google.com/document/d/195C7oEmrDTiVRubAfBplvGjacd_91YOdWMj0lblKWIQ/edit

[iamronen]

I don't feel good about the implementation model we went with during the kickoff for this project. I've recorded this loom in order to try and communicate why: https://www.loom.com/share/2b893952cf234fc9a438f731457e9579

The MVP in the pitch opened the door to a lot of potential that may, over time transform how expenses are paid (and submitted). The implementation model that we chose shut the door on most of that potential:

I think we need to reconsider before moving forward.

[iamronen]

I had a brief async interaction with @katieOCF asking her for feedback about this junction, posting her reply here on her behalf:

I believe that the engineering team solution in the bottom right will create more work for host admins and lead to confusion. It will require core staff to have more training and confidence in reviewing legal agreements and understanding their purpose and interpretation. That's typically not expected of staff performing routine tasks. It may still be better than nothing. I agree that the base unit of our work is agreements--literally, the fiscal sponsorship agreement is what each host is built on. Hosting is a relationship based on a contract. That's entirely what it is. If an expense comes along that isn't contemplated by the original agreement, a new agreement needs to be made for that expense to be legitimately approved. This is very basic, foundational, to the concept of fiscal sponsorship/hosting.

[BenJam]

• [ ] Design are looking at the notes section on a collective's page (only aviaible to host admins). Something like this:

• [ ] Eng are looking at implementing the infrastrcuture

[iamronen]

Initial scoping with @gustavlrsn @hdiniz and @Memo-Es

• [ ] Entity structure
  • [ ] Core
    • [ ] Title
    • [ ] Attachment
    • [ ] Expiration date
    • [ ] Agreement are related to a collective
    • [ ] Agreements are related to a HostCollectiveID
    • [ ] API Implementation: only allow creation of agreements by fiscal hosts
• [ ] showing agreements within an expense
  • [ ] Modal for displaying agreements from the expense block
  • [ ] Integrating in the "expense block" in list of expenses (design review - where/how to show this effectively, how does this relate to the "sidebar full expense view")
  • [ ] full expense details
    • [ ] managing agreements - adding a page for "agreements" in the fiscal host workspace
  • [ ] Filtering agreements per collective
  • [ ] Review agreements
  • [ ] Add/Edit agreements
  • [ ] Archive agreements (? do not delete agreements that are related to expenses)

Questions

• What happens to agreements when a collective leaves - currently belongs to a host
• future: agreements between collectives (eg: supporting dependencies)

Things that surfaced that we don't want to touch

• Not adding a maximum amount to the agreement
• Not adding agreement categories

[Memo-Es]

@hdiniz @iamronen @BenJam @gustavlrsn

https://www.loom.com/share/3310f5112d7e469db5100825325d8df7

[iamronen]

@Betree once explained to me that we create all tables with a set of default metadata fields that includes createdby / createDAte ... so just want to flag that and make sure it is considered/applied here.

[hdiniz]

@iamronen Yes, it will have these default date fields, but they do not always apply cleanly to the entity concepts, if we want to reflect data about the agreement like agreementStartDate or agreementExpiresAt, etc. we can add these fields.

In some cases the default metadata can match with the represented entity, for example a Comment. In the Agreement case, the createdAt field would indicate when the Agreement database record was inserted but not necessarily the effective start date of the agreement. Same for updatedAt and deletedAt.

I am interested in the agreement start and end dates to figure out how we display that information when attached to expenses. I believe we want to show only agreements that where in place when the expense was created, right?

[iamronen]

thank you for the clarification @hdiniz

1. I do think think that these generic metadata fields are needed. I think it is important to capture when an agreement record was created on the platform and by who.
2. I realize that. in this case, these generic metadata fields do not correlate to the contents of the agreement itself.
3. For now, I think that for the actual agreement end-date is more important than start-date because the end-date informs expense decision making.
4. The consideration for how information is displayed depends on the context in which you are showing it.
5. In the context the expense payment flow I think:
   • It is an interesting proposal to show only agreements that were in place when the expense was created (thank you for calling attention to this) but I think that is NOT a good idea because there may be cases (especially in these very early days of agreements) where agreements will in fact be created AFTER expenses in response to expenses that are missing agreements.
     • the end-date may be a distraction because the date that matters is the end-date (and in the future we may be able to auto-validate this, which why it is useful to have it as part of the MVP so that we start accumulating quality information).
     • It may be useful to provide a visually indicator for an agreement which has expired.
       6. In the context of the list of agreements (fiscal host workspace) you have both more space and more attention, so end-date may be useful but not distracting.

tagging @Memo-Es for design considerations

[iamronen]

Just a heads up: when adding the agreements to the full expense details page make sure that it only shows up for fiscal host admins (because the expense details page exists in the public domain).

[znarf]

This week

• API in progress, PR ready
• Attachment upload

[iamronen]

• PR for API awaiting review and merging
• Completing the attachment upload
• This week, if possible. start the front-end

[iamronen]

I was taking this for granted, but I want to make sure that agreements will have URL's that can be used to reference them elsewhere.

I also want to emphasize that this needs to be permission based. In this seed phase of the project, URL's should only work for Fiscal host admins of the host to which these agreements belong. This is likely to change as the Agreements campaign unfolds.

[iamronen]

Capturing here a summary of a conversation I had with @gustavlrsn about collecting additional metadata for agreements.

In the current implementation we are providing minimal information for agreements. We have already been able to hypothesize about additional fields but decided against expanding the model at this point. We prefer to discover real-world needs instead of speculating about theoretical needs.

However, if OCF users are going to seriously adopt this feature (I am in conversation with @katieOCF about creating the conditions for this) then having to review all the agreements again in the future to add additional information can be an expensive and cumbersome ask.

With that in mind I approached Gustav to consult about the feasibility of a zero-cost-to-engineering hack:

1. Invite OCF users to create agreements with encoded data in the agreement title.
2. For example, by adding max2000 to an agreement title they can indicate that this agreement covers expenses of up to $2000.
3. OCF could then use a self-determined protocol to declare, as agreements are created, additional information about them.

This would:

1. Support a discovery of what additional information they wish to store.
2. Enable them to enter at least some of the obvious data-fields already at the moment of creating the agreements.
3. Do so in such a way that in a future cycle engineering could do a cleanup&convert operation: transforming this data into properly structured data (and remove it from the titles).

In the conversation with Gustav we discussed two additional implementation strategies for this.

1. Doing this in a notes field (which may be something we need anyway) so as to allow more space to do this without contaminating the title.
2. Creating a user interface enabling users to enter key-value pairs which are a better information structure and user experience which we can then also study and at a later time convert into structured data.

We agreed that if time allows, we would like to aim for the latter (a basic and most likely temporary interface for entering key-value pairs).

attn @BenJam @znarf @Memo-Es

[BenJam]

Thanks for the ping, i read through the expanded scope of this like 😳 and this is the approach that i like to take:

We prefer to discover real-world needs instead of speculating about theoretical needs.

I seem to recall that the last time we spoke we were at this point https://github.com/opencollective/opencollective/issues/4894#issuecomment-1519948799 and we wanted to ensure that, when we do want to add more meta-data, that option is open to us. It seems like a good problem to have if Open Collective Foundation are asking us to expand the functionality because they're using it 🙃

[znarf]

I generally like the idea of key-value pairs. When reviewing the pending contributions project, I thought it could have been an interesting approach here.

[iamronen]

@BenJam to clarify: Considering the larger potential of the Agreements campaign I am confident that more meta-data about agreements will be needed. I think that adding this capability to somehow capture the meta-data is a low cost effort (checked with @gustavlrsn ) that achieves:

1. It enables us to discover what meta-data is needed.
2. It enables us to capture some of it already in the first wave of agreements data-entry. This, in turn, positions us well to rapidly transforming it into structured data in a future iteration.
3. It reduces the need to manually revise all the agreements in a later iteration (which will likely cost more than the effort to capture it early days.
4. It, I believe, increases the confidence that OCF can have in this capability and so biases the entire experiment towards better results.

Also, after seeing the demo @aerugo created for expenses in Coda, I believe that doing this in Coda may be a fourth option (which may even be more appealing in terms of user experience). I'll be having a conversation about this next week with Katie & Hugi.

[gustavlrsn]

This week

• [ ] Get started on frontend to display agreements from an expense #6705

[hdiniz]

This week

• [ ] Finalize Agreement GraphQL schema on https://github.com/opencollective/opencollective-api/pull/8864

[gustavlrsn]

This week

• [ ] Review & merge https://github.com/opencollective/opencollective-api/pull/8864
• [ ] Get started on frontend to display agreements from an expense https://github.com/opencollective/opencollective/issues/6705

[iamronen]

After conversations with @katieOCF and @aerugo we've decided to continue the prototyping research for additional agreement metadata with OCF on Coda:

• Hugi will build an interface in Coda for agreements so that as agreements are created on the platform they will appear in Coda.
• Katie will (together with Hugi) discover and add additional agreement-related meta-data (with an eye on the goal of, in the future, reaching a capability to indicate a related agreement when submitting an expense). This will provide a rapid and flexible interface for this research into agreement data (and processes).
• @iamronen will be following along this process in order to determine next steps for the platform implementation of agreements

[Betree]

Last week:

• [x] Take over @gustavlrsn's PR and finish it

This week:

• [x] Merge base frontend PR (dev & staging only)
• [x] https://github.com/opencollective/opencollective-frontend/pull/8998
• [x] https://github.com/opencollective/opencollective-frontend/pull/9020
• [x] https://github.com/opencollective/opencollective/issues/6836
• [x] https://github.com/opencollective/opencollective/issues/6705
• [x] https://github.com/opencollective/opencollective-frontend/pull/9019
• [x] https://github.com/opencollective/opencollective/issues/6832

[Betree]

For next week:

• [x] Merge & deploy latest changes
• [x] https://github.com/opencollective/opencollective/issues/6840
• [x] Define release strategy

[iamronen]

Given the nature of this new "Agreements" capability (it lays foundations for future potential, has limited immediate impact and needs context and guidance to be implemented effectively) we have decided to release it initially only to our 1st party fiscal hosts (OSC, OCF, OCE).

[Betree]

Adapting the panel to make sure accountants can view (but not edit, delete or create) agreements in https://github.com/opencollective/opencollective-frontend/pull/9059 + https://github.com/opencollective/opencollective-api/pull/9139

[Betree]

The agreements feature is now live for all internal fiscal hosts :rocket:

Demo: https://www.loom.com/share/d207c961835a4cef9672ce15f7204511 Feedback issue: https://github.com/opencollective/opencollective/issues/6846

[Betree]

For this week: we're ready to iterate on Feedback if needed, but there's nothing more planned at this point.

[iamronen]

Thank you @Betree I'll signal the OCF team that they can start an adoption process we discussed a few weeks ago.

[Betree]

All done and released. We'll track Feedback in https://github.com/opencollective/opencollective/issues/6846

[BenJam]

@Betree cna i just check whether this is released for all hosts, or just first party?

[Betree]

Only 1st party + OCNZ for now (with an opt-in flag). I'm open for a public release but we need to work on docs