322ad21f8b
Payment requests are basically always "in progress" until they're rejected or the requestor receives payment. Use a name that better reflects what's going on.
232 lines
11 KiB
Markdown
232 lines
11 KiB
Markdown
# Requirements for the Reimbursement and Outgoing Payment Request System
|
|
|
|
## Overview
|
|
|
|
One short-term goal of the Non-Profit Accounting Project is to create a
|
|
system that allows (a) members of an organization, and external parties, to
|
|
submit requests for reimbursement or request for payment like invoices,
|
|
and (b) the organization's bookkeepers, accountants, and managerial approvers
|
|
to review those requests, add them to the organization's books, and prepare
|
|
payment. The primary motivation for this project is to save time both groups
|
|
spend on handling reimbursement requests and outgoing payments, and reduce
|
|
turnaround time for these requests, and to help members file complete
|
|
requests that are easy for bookkeepers to review and accept.
|
|
|
|
Members of the organization could be employees, members of projects
|
|
represented by the organization, or others doing work to advance the
|
|
organization's mission—anyone who the organization might want to reimburse or
|
|
pay.
|
|
|
|
The system should not make assumptions about specific reimbursement policies
|
|
or invoicing requirements. Instead, it should be possible for a bookkeeper
|
|
or administrator to define follow-up questions and what responses are and are
|
|
not eligible for reimbursement or payment. Early versions may require
|
|
sysadmin-level technical expertise to do this, but ultimately it should be
|
|
doable by a bookkeeper with appropriate privileges.
|
|
|
|
## Requirements for first release
|
|
|
|
### Defining the request form
|
|
|
|
Requests for payment have four states: Draft, Submitted,
|
|
Accepted, and Rejected.
|
|
|
|
Administrators can define questions to ask the requestor about the entire
|
|
request, and about each expense in the request. The system can display
|
|
forms, validate answers, and record answers for questions with the following
|
|
types of answers:
|
|
|
|
* Text
|
|
* Selection (from a list of values)
|
|
* Number
|
|
* Currency (We may not need strict validation, but the system must at least
|
|
understand that different currencies exist, and be able to validate that a
|
|
currency is specified when needed. Using a plain Number for currency is
|
|
not sufficient.)
|
|
* File upload
|
|
|
|
Other types like boolean and date would be nice, but I think they could be
|
|
expressed with the types above.
|
|
|
|
It is expected that one question about expenses will be the type of expense
|
|
(e.g., airfare, accommodations, meals, office supplies). The administrator
|
|
must be able to define follow-up questions that are asked based on the
|
|
expense type, to request additional information as required by policy. For
|
|
example, Conservancy requires airfare search results to be attached to
|
|
airfare reimbursement requests. Requestors should be prompted for this
|
|
documentation when submitting reimbursements for flights, and not for other
|
|
expenses.
|
|
|
|
### Requestor workflow
|
|
|
|
Requestors can log in and see the status of all their requests. They can also
|
|
create a new request, which starts in the Draft
|
|
state.
|
|
|
|
When they view a report, it shows the questions and answers about the entire
|
|
report, and a list of associated expenses. Viewing a specific expense
|
|
similarly shows all the questions and answers about it.
|
|
|
|
When a report is Draft state, the requestor can edit any answer in the
|
|
report or an associated expense. They can also add an expense, which begins
|
|
by asking them questions common to all expenses, and then
|
|
follow-up questions as necessary based on those answers.
|
|
|
|
When an Draft report has at least one expense associated with it, and
|
|
all questions have been answered, the requestor may submit the request for
|
|
approval, along with optional notes about the request.
|
|
Once the request is submitted, it moves to the Submitted state.
|
|
Bookkeepers receive an e-mail notification that the request is ready for
|
|
review, including the notes written by the requestor.
|
|
|
|
### Bookkeeper workflow
|
|
|
|
Bookkeepers can log into the system and see all requests.
|
|
|
|
When bookkeepers review a Submitted report, they can change the report's
|
|
state, and include a note explaining why the report was moved to that state
|
|
(for example, the bookkeeper moved the request back to Draft because a
|
|
specific receipt was insufficient documentation). When they do this, the
|
|
system sends email to the requestor letting them know about the change,
|
|
including the rationale provided by the bookkeeper.
|
|
|
|
The bookkeeper can export any request to the books. The first release of the
|
|
software will simply provide an archive that includes all of the request's
|
|
supporting documentation, plus a `.ledger` file with entries for each
|
|
expense. However, note that when building this feature in the code and UI,
|
|
it should be relatively generic. Exporting should remain abstract enough
|
|
that integration with other accounting systems remains simple and
|
|
straightforward. Note that even the mechanics could be different; for
|
|
example, an SQLedger exporter may add entries to the system directly, rather
|
|
than providing the bookkeeper with a file download.
|
|
|
|
## Requirements potentially for first release
|
|
|
|
These are features that we would like the system to have, and it may make
|
|
sense to make them requirements of the first release depending on how it's
|
|
built.
|
|
|
|
* CiviCRM integration: Many NPOs are already using CiviCRM. CiviCRM
|
|
integration would provide a familiar interface to users, and simplify
|
|
system administration for the organization. It may be possible to build
|
|
the system as a CiviCRM extension. If so, we would get this feature for
|
|
"free."
|
|
|
|
* Usable without JavaScript: For consistent mission advocacy, it's important
|
|
that some organizations not require requestors to use JavaScript. For
|
|
example, Tor browsers typically have JavaScript disabled because it can
|
|
undermine Tor's anonymity guarantees; organiziations supporting Tor must
|
|
support these users.
|
|
It should be possible to submit payment
|
|
requests without JavaScript. The interface can be enhanced when JavaScript
|
|
is available.
|
|
|
|
Whether or not we do this in the first release probably depends on what
|
|
framework we decide to build on. If the framework itself requires
|
|
JavaScript out of the box, it may make sense to have the first release go
|
|
with the flow, then work to add JavaScript-free functionality in a later
|
|
release.
|
|
|
|
In any case, Javascript used will respect software freedom of users and, *if
|
|
possible*, will adhere to LibreJS protocols.
|
|
|
|
## Requirements for later releases
|
|
|
|
These are features that we would ultimately like the system to have. We
|
|
would also like to release a first version as early as possible, to start
|
|
getting feedback from users and generating more development interest. It's
|
|
good to keep these in mind when architecting—in particular, we may choose an
|
|
existing system to use, or framework to build on, based on its ability to
|
|
support these features. However, they needn't be a focus of development
|
|
effort for the first release.
|
|
|
|
* Administrator-defined policy validations
|
|
|
|
Some validations we would like to have:
|
|
|
|
* A value from a selection is in a specific subset of values
|
|
|
|
* A date is within N days before and/or after today or a date in another answer
|
|
|
|
* A currency amount is over or under a limit, with automatic conversion as needed
|
|
|
|
* The limit on a currency amount is defined by an outside source - The
|
|
main case for this is per diem, where many organizations use rates that
|
|
are determined by another party like the US GSA and updated periodically.
|
|
|
|
These may need to be compounded. For example, an administrator may want
|
|
to define a policy, "If an employee did not use a preferred airline, and
|
|
did not travel internationally, it does not meet policy."
|
|
|
|
* Flag non-reimburseable expenses based on policy validations
|
|
|
|
When the requestor answers questions that are outside the policy
|
|
validations, the system should flag the answer and explain how it falls
|
|
outside policy. The requestor should still be able to submit the request,
|
|
but they should be prompted to explain why the request should be fulfilled
|
|
despite policy problems.
|
|
|
|
* Ask additional questions based on policy validations
|
|
|
|
For example, "If the expense type is office supplies, and the cost is over
|
|
$50, prompt for a receipt."
|
|
|
|
* Allow optional questions
|
|
|
|
Along with this, policy validations probably need to
|
|
be extended to address the case of "other question isn't answered"
|
|
|
|
* Additional exporters
|
|
|
|
* Export to SQLedger
|
|
|
|
* [Certainly many more, feel free to add them here]
|
|
|
|
* Richer lifecycle management
|
|
|
|
* Support requests for pre-approval, probably with two states
|
|
"Pre-Approval Draft" and "Pre-Approval Submitted." In the
|
|
Pre-Approval state, the requestor is submitting not receipts or
|
|
invoices, but documents regarding potential expenses that have not yet
|
|
been incurred, but for which organization policies require preapproval
|
|
by organizational management ahead of time. The appropriate management
|
|
representatives are duly notified by the system of pending Pre-Approval
|
|
requests, and their approval moves the request into the Draft
|
|
state. Their rejection moves the request to the Rejected sate.
|
|
|
|
* Support more review: a leader (such as a manager or program
|
|
director) may need to review and approve a request along with, or
|
|
instead of, the bookkeeper
|
|
|
|
* Support automatically determining the appropriate leader for a
|
|
payment request based on information in the request, like a
|
|
"What project is this for?" selection
|
|
|
|
* A new state after Approved, Filled, which means that the
|
|
organization has arranged for payment to go out. The requestor
|
|
should receive a notification when their request moves to the
|
|
Filled state.
|
|
|
|
* A new state after Filled, Received, which means the requestor
|
|
received payment. Bookkeepers should receive a notification when
|
|
the request moves to this state.
|
|
|
|
* Show currency amounts in the requestor's reimbursement currency
|
|
|
|
For example, the requestor can submit a reimbursement with expenses in
|
|
USD, EUR, and CHR, but wants payment in INR. Unclear what
|
|
interface for this would look like, but real-time data about past currency
|
|
rates might be available via an API somewhere, and we can use that to have
|
|
the requestor give us "preferred currency for payment" so all changes
|
|
happen in real time in the interface (even allowing the requestor to be
|
|
able to decide *while filling out the report*: "ugh, these exchange rates
|
|
to INR are horrible; I'll have them pay my USD account instead").
|
|
|
|
* Data import
|
|
|
|
* Apps like [Tricky Tripper](http://trickytripper.blogspot.de/) let users
|
|
track expenses for a trip as they go. The system could import this data
|
|
to prepopulate answers to questions about the request and expenses in
|
|
it. Probably there would be an import API that can map different import
|
|
formats to a common format, and then administrators can define how
|
|
questions in their system can be answered based on imported data.
|