User notifications on invoice transition in finance flow

[sks444]

Summary

OTF needs to inform the users involved in the process of invoice transition through the webapp. This is so they can be kept up-to-date of the invoice status, and be notified if they are required to do anything.

Users involved

• Contractor: they submit the invoice.

• Programme Manager Staff: they are the contractor's point of contact within OTF. They review the invoice to make sure the deliverables have been met correctly. They review the invoice, communicate with the contractor if changes are made.

• Finance 1: they are the finance staff that review the invoice to check it has the required information and all numbers are correct.

• Finance 2: they are the finance staff that review the invoice, cross-check the work carried out by the finance 1 user. They also send the invoice to the payment system if all looks OK.

Notification method

It's been decided that 1) OTF Staff will receive notifications via Slack, and 2) contractors will receive notifications via the email address defined in their account.

Communication style

The current OTF-to-contractor communication style is to provide the minimum level of detail in the email and to require them to log-in to read the full message.

Invoice states and who needs to be notified

The first sequence diagram below outlines the possible invoice states (states 1-17 below).

It also defines which user needs to be notified at each change of status (Yellow boxes a-to-s below).

(If it's hard to read, you can see the original)

If an invoice is rejected

These sequence diagram outline if an invoice is rejected.

PM declines invoice

Finance 1 declines invoice

Finance 2 declines invoice

Notification message content

Draft notification messages are ready for review.

Feedback

• get feedback on notification message content from @fourthletter
• get feedback from @frjo, @sks444 focused on difficulties to implementation
• get feedback on notification message content from users (contractors, PMs, finance)
• get final agreement/sign-off

Open questions

• For Finance how long can it take for a payment to leave the OTF banking system and reach a contractors account? (Take into account the different global locations bank accounts can be. Some will take longer or short periods of time)
• For finance & PMs: If Finance 2 declines an invoice should the PM be notified?

[sks444]

We need a way to notify(either via slack or email) to respective users whenever an invoice is getting transitioned into different states. Above are the few notifications that I collected from different finance issues. We can discuss here and decide something final. I believe we also need to send notification to applicant on final approval of invoice(finance 2 approval)?

For now, I will go-ahead and complete the finance flow in hypha without these notifications. And come back to this afterwards.

cc: @frjo @ei8fdb @fourthletter

[fourthletter]

On Feb 3 during standup we discussed the content that should be embedded into emails.

• Default settings for emails and slack; different porks for different forks: staff gets slack while contractors get emails
• Emails will contain links that go directly to the projects page, invoice, communication/message, etc.
• Bernard has ideas for additional email notifications
• Fredrik propose we keep similar email templates used in Submissions
• OTF creates new slack channel for project related notifications (not directly pertinent to this GH issue)
• Messages/Notifications the SAME for Slack?
• Fredrik is probably already thinking about this, but we may need to build something in the WagTail admin.

How does staff receive slack notifications for specific funds/labs? Image of the lab/fund form:

How does each staff member sign up for slack notifications generally? Image of the profile page:

[ei8fdb]

These are correct

Thanks for that, and also the other changes to the contractor notifications. 👍

For example, what if finance 2 has questions or requests modifications that are specifically for finance 1?

Can you give me some more info on what those modifications could be? Just so I understand.

Are finance users to be able to modify an invoice submitted from a contractor?

[sks444]

@ei8fdb, thanks for the beautiful design!

Can you also add a notification flow for when Invoices gets declined?

All three users(PM Staff, Finance 1 and Finance 2) have the ability to decline invoices. I believe we are sending notification directly to contractor in all three cases?

cc: @fourthletter

[fourthletter]

@ei8fdb

All three users(PM Staff, Finance 1 and Finance 2) have the ability to decline invoices. I believe we are sending notification directly to contractor in all three cases?

• PM declines invoice - notifies Contractor

• Finance 1 declines invoice - notifies PM; does NOT notify Contractor

• Finance 2 declines invoice - notifies Finance 1; notifies PM? ; does NOT notify Contractor

• It's unclear to me if a decline from Finance 2 should notify PM because the issue may not be pertinent to the PM. For example, Finance 1 didn't complete a SAM check. Notifying the PM when they do not have agency to rectify the issue will only produce 'noise.'

Contractors do not need notifications until the PM has a grasp of the issue because:

Example: Invoice is for a 'partial' 20% of one deliverable. Finance 1 declined the invoice, and the PM needs to discuss this with either Finance OR the Contractor to resolve this issue.

1. PM has a direct line of communication with the Contractor, PM's has the relationship and knows how to best communicate with the Contractor, e.g., via signal or a meeting.
2. Not every scenario requires the Contractor's attention. A Contractor does not need to be notified if the PM and Finance 1 could resolve the issue internally.

[sks444]

Just to point to out that, in case where any changes are needed to an invoice we are using changes requested flow.

Declining an invoice makes the invoice invalid, that means it should not be processed further.

Invalid is something similar to deleting an invoice but still keeping the record in our system.

[sks444]

@ei8fdb, we continued this discussion on standup Feb 9.

We decided to only let PM/Staff to decline invoices.

PM has direct communication with both contractor and finance they can put up a valid reason to decline invoices. And also can communicate further with contractor.

There is very less possibility that an invoice get invalid once the PM has approved it. But even if that case occur finance can request changes. And PM can make it invalid.

[ei8fdb]

The UX work is paused for the moment. I've asked for review from finance staff and devs.

From discussion with Di yesterday, no design work is needed for the moment.

[fourthletter]

@sandeepsajan0 Could you please take a look at notifications for the finance workflow this month? We're planning to test with end-users, and it would be helpful for us to start drafting appropriate slack and email messages soon. Thanks.

[sandeepsajan0]

@fourthletter Yeah, sure. I picked this task and see that notifications are already implemented. So, I tested it properly for every user type (contractors, lead/staff, finance1, and finance2) and for all statuses (Submitted to Paid including decline) and its notifications work fine.

If you want to check or update those notification messages from one place(here) I can paste the notification message here. Let me know how you want to proceed.

[fourthletter]

Thank you @sandeepsajan0 -- I will test it as well and document if the messages need to be updated for OTF.