Implement invoice back-end
Setup
- Copy
.environ/.env.dev
to.env
(if you already have an.env
, do a merge with the new variables). - Need JIRA credentials for a service account. Check our keypass DB for them, and assign them to
JIRA_SERVICE_USER_USERNAME
andJIRA_SERVICE_USER_PASSWORD
properly. Make sureJIRA_SERVER_URL
points to the proper JIRA domain (i.e.https://tasks.opencraft.com
). - Need a wkhtmltopdf binary, to do HTML-to-PDF conversion. See https://wkhtmltopdf.org/downloads.html.
- Need a PKCS12 file for Google Auth. This can be downloaded from the credentials page at Google Console, or from our secret accounting keypass DB (see our secrets repo; in there is the private key, and you can turn it into a PKCS12 file using the instructions). Name it .p12 (by default) and put it at the root of this repo. Or, change the
GOOGLE_AUTH_PKCS12_FILE_PATH
variable name in your environment accordingly if you've other plans. (FYI -- the password for the.p12
files should benotasecret
by default; yes, it's really not a secret, as this is what Google automatically puts on all new PKCS12 files you download, and also what thePyDrive
library expects to have to enter.) - Set
GOOGLE_AUTH_CLIENT_SERVICE_EMAIL
to the service account email present in the accounting keypass DB. - Need to set the proper
GOOGLE_DRIVE_ROOT
for file uploads -- see the accounting keypass DB. - Make sure
ENABLE_JIRA
andENABLE_GOOGLE
are set toTrue
. It's turned off by default in an open source setting like this, to prevent awkward behavior for those without the proper creds. - Remove any docker DB you may have from before by checking
docker volume ls
. If you see something likeaccounting_postgres_data
, dodocker volume rm accounting_postgres_data
. - Do
make dev.build
to freshen the container. - Do
make dev.up
and thenmake dev.web.logs
to see that the service's container is running properly. - Do
make migrate
. - It may be convenient to have fake data lying around: do
touch private.mk
and enter these details:users: ## Make all the users we need for testing. $(HONCHO_MANAGE) createsuperuser --username me --email me@email.com $(HONCHO_MANAGE) createsuperuser --username opencraft --email billing@opencraft.com $(HONCHO_MANAGE) generate_account_data --accounts-num 100
make users
. You can do this again later in case you want to delete your DB to start from scratch. Or just use thegenerate_account_data
command directly to make more fake data. - Go in the shell (
make shell
) and doSite.objects.get_current().update(domain='http://localhost:1786')
- Go to
http://localhost:1786/admin
and login using the first user you created from above. - Go to
http://localhost:1786/admin/authentication/user/
and update your user to use your proper full name. This displays on invoices. - Go to
http://localhost:1786/admin/account/account/
and add an account for both your user, and for theopencraft
user. Up to you if you want it to reflect reality; note though that business names are given priority over full names for display on invoices. - Go to
http://localhost:1786/admin/account/hourlyrate/
to make an hourly rate connecting you and theopencraft
user, withopencraft
being the client. - Go to
http://localhost:1786/admin/bank/bankaccount
and make a fake bank account. Note that theIdentification
field is aJSONField
-- just enter any arbitrary strings that you'd like to show up on the invoice. Only non-empty strings will actually show. Note also that the invoice only shows the provider's bank account details -- so you can skip doing this for theopencraft
user. - Go to
http://localhost:1786/admin/invoice/invoice
and make a new invoice.- Make sure the date-related defaults all make sense: given todays date, the billing start and end are based off of last month, since this is how we assume invoice processing works -- invoices created this month are meant to bill last month's work.
- Make the provider and client equal to you and OpenCraft, respectively.
- Upload a signature image (or any image) in the
Signature
section. - Leave checkboxes unchecked.
- After saving the invoice, check your repository's
media
folder and see that the 'signature' you uploaded is present.
JIRA Worklogs Download
- Go back to the invoice object you made.
- Check the 'Auto download jira worklogs on save' button.
- Save! This part can be a bit slow -- there's usually a lot of data being downloaded and processed, and your comptuer's fan might speed up ;p
- If you did everything correctly, your system will have correctly downloaded all worklogs for your user from JIRA. Go to
http://localhost:1786/admin/invoice/lineitem/
to see that all your worklogs are present. - For some worklog that you have in the past month that's present in the line item list, change the description slightly on JIRA itself.
- Re-save the invoice to re-download JIRA worklogs.
- Go check the same line item in the admin to ensure that no new item was created, but rather, the existing line item was updated.
- You can do the same action with changing the worklog's actual time spent on JIRA, and even if you change the ticket's name! In fact, you can delete, add, update the worklogs as much as you want and the system will ensure you have a perfect sync between the JIRA worklogs for the billing date range and the DB. For example: change the billing end date to many different dates, and re-save. Each time, you'll always have the proper line items in the DB that correspond only to that billing date range, even if you modify the worklogs. Cool!
PDF Generation
- Go back to the invoice obejct you made.
- Uncheck the 'Auto download jira worklogs on save' button.
- Check the 'Auto pdf on save' button.
- Save! (This part gets faster the 2nd time around because of heavy DB caching. Actually, that's problematic at some level because the caching may end up giving you false information in the next generated PDF -- for example, if you change the hourly rate right now and re-generate, it would catch the currency change but not the price change.)
- Check your
media
folder to see that an invoice exists. - Inspect the PDF to see that the information all makes sense, including totals and what not. (Ok, you don't have to pull out a calculator, just compare it to your actual invoice from the past month! (that's if your billing start/end dates were for November)).
Google Drive
- Go back to the invoice obejct you made.
- Do not uncheck the 'Auto pdf on save' button. Google Drive uploading only happens if a PDF is generated first -- the system doesn't go searching in the
media
folder for candidate PDFs, it gets it directly from the generation code. - Check the 'Auto upload google drive on save'.
- Save! (will take however long it takes for the Google Drive API to work)
- Go to the
11
folder (for the month of November) in the Accounting Drive'sinvoice-in
folder for2017
. See that your invoice is present and created bycrafty
.
Play Around
- Freebie: play around with this system to see if any normal use cases are broken. I know I didn't implement error handling for basically anything between JIRA worklog downloads / PDF generation / Google Drive uploads -- but see if anything that should work isn't.