.\" $Id: pta_import.1,v 1.8 2020/11/26 19:39:43 freda Exp $
.\"
.\" Copyright (c) 2020 Freda Bundchen
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: November 26 2020 $
.Dt PTA_IMPORT 1
.Os
.Sh NAME
.Nm pta_import
.Nd print pta journal entries from bank CSV file input
.Sh SYNOPSIS
.Nm pta_import
.Fl I Ar accountname
.Op Ar file
.Sh DESCRIPTION
The
.Nm
utility converts lines from a CSV
.Ar file
generated by a financial
institution into journal entries used by
.Xr pta 1 .
.Pp
If the
.Ar file
argument is omitted, standard input is read instead.
.Pp
.Ar accountname
is exactly one of
.Pp
.Bl -bullet -offset indent -compact
.It
.Cm bbva_usa
.It
.Cm capital_one_credit
.It
.Cm chase_credit
.It
.Cm optum_hsa
.It
.Cm sparkasse_camt
.It
.Cm wellsfargo
.El
.Pp
and corresponds to an existing
.Pa ./import/ Ns Ar accountname Ns Pa .txt
configuration file.
.Ss Configuration file format
Each configuration file contains rules
used to import transactions from a financial institution.
Like all
.Xr pta 1
input files, it is an
.Xr ascii 7
text file using strings of one or more space characters
as the field delimiter and using the hash character
.Pq Sq #
in the first column to mark lines as ignored.
.Pp
The rules are as follows:
.Bl -tag -width Ds
.It Ic ACCOUNT Ar csv_account_number
The number in
.Xr pta-accounts 5
of the bank or credit card account this CSV file contains entries for.
This rule is required in every configuration file.
.It Ic DELIM Ar delimiter
The character used to separate fields.
This rule is required in every configuration file.
Most financial institutions use commas but some use semicolons.
.It Ic HEADER Ar header
Skip the first line of the CSV file if it matches the
.Ar header
line verbatim, or cause parsing to fail if it does not.
.It Ic IGNORE Ar regular_expression
Skip all lines in the CSV file matching the
.Ar regular_expression .
.It Ic QUOTE Ar quote
Expects that every field starts and ends with the
.Ar quote
character.
.It Ar selector account_number booking_identifier
Lines in the CSV file that match the
.Ar selector
are associated with the contra account
.Ar account_number
and are assigned the
.Ar booking_identifier .
The selector is a string consisting of regular expressions separated
by delimiters defined in the
.Ic DELIM
rule.
.El
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa ./import/bbva_usa.txt
.It Pa ./import/capital_one_credit.txt
.It Pa ./import/chase_credit.txt
.It Pa ./import/sparkasse_camt.txt
.It Pa ./import/optum_hsa.txt
.It Pa ./import/wellsfargo.txt
.El
.Pp
These files contain the header that the financial institution uses, the
account number from
.Pa ./accounts.txt
used by this account, as well as patterns used to map transactions to
the correct account and booking identifier.
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Add journal entries to a journal file using a CSV file generated by
a financial institution:
.Pp
.Dl "$ pta_import -I chase_credit chasedownload.csv >> journal.txt"
.Ss Account numbers in the configuration file
The line
.Pp
.Dl ACCOUNT 3235
.Pp
in the configuration file corresponds to a line such as
.Pp
.Dl 3235 L Capital One credit card
.Pp
in
.Pa ./accounts.txt .
.Pp
The description
.Qq Capital One credit card
may vary, but in this example, the account numbers
.Qq 3235
match, and the account type is
.Qq L
to indicate that it is a liability account.
.Ss Patterns in the configuration file
Suppose
.Pp
.Dl ,,,Automotive,,, 1111 AUTO
.Pp
is a sample entry in the
.Pa ./import/chase_credit.txt
file which uses headers of the form
.Pp
.Dl Transaction Date,Post Date,Description,Category,Type,Amount
.Pp
Then this
.Ar selector
ignores the transaction date, post date, description, type, and amount.
It matches the
.Qq Automotive
category and maps transactions to account
.Qq 1111
defined in
.Pa ./accounts.txt
with the
.Qq Auto
booking identifier.
.Ss A sample credit card purchase
If
.Pa chasedownload.csv
file contains
.Pp
.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"
.Pp
and
.Pa ./import/chase_credit.txt
contains
.Bd -literal -offset Ds
ACCOUNT 3234
,,,Shopping,,, 9996 SHOP
.Ed
.Pp
and
.Pa ./accounts.txt
contains
.Bd -literal -offset Ds
3234 L Chase credit card
9996 X shopping
.Ed
.Pp
then the
.Qq Shopping
category defined by Chase is mapped to the user's
.Qq SHOP
booking identifier, the user's account for shopping
expenses is defined as
.Qq 9996
in their
.Pa ./accounts.txt ,
the user's account for the credit card is 3234 in their
.Pa ./accounts.txt ,
and
.Nm
prints
.Pp
.Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj"
.Ss A complete example
Suppose
.Pa ./accounts.txt
is given by
.Bd -literal
1700 A My Bank
3234 L My Chase Credit Card
5102 X Physician expenses
5103 X Dental expenses
5203 X Shopping
.Ed
.Pp
and
.Pa chasedownload.csv
is given by
.Bd -literal
Transaction Date,Post Date,Description,Category,Type,Amount,Memo
11/06/2020,11/09/2020,Dr. Joseph Schmoe,Health & Wellness,Sale,-100.00,
11/06/2020,11/09/2020,Dr. Sally Sue,Health & Wellness,Sale,-183.00,
11/08/2020,11/08/2020,example.com,Shopping,Sale,-53.83,
11/04/2020,11/04/2020,Payment Thank You - Web,,Payment,75.43,
.Ed
.Pp
and
.Pa ./import/chase_credit.txt
is given by
.Bd -literal
# Chase credit card header is
# Transaction Date,Post Date,Description,Category,Type,Amount
# The format of this file is
# selector account_number booking_identifier
# selector is a comma-separated list of regular expressions which
# matches corresponding fields in the CSV file
ACCOUNT 3234
,,,Automotive,,, 1111 AUTO
,,,Bills & Utilities,,, 2222 BILLS
,,,Fees & Adjustments,,, 3333 FEES
,,,Food & Drink,,, 4444 FOOD
,,,Gas,,, 5555 GAS
,,,Gifts & Donations,,, 6666 GIFTS
,,,Groceries,,, 7777 GROCERIES
,,Dr. Sally Sue,,,, 5103 DENTAL
,,,Health & Wellness,,, 5102 PHYSICIAN
,,,Home,,, 9999 HOME
,,,Personal,,, 9998 PERSONAL
,,,Professional Services,,, 9997 PRO
,,,Shopping,,, 5203 SHOP
,,,,Payment,, 1700 PAY
.Ed
.Pp
Then
.Pp
.Dl pta_import -I chase_credit chasedownload.csv
.Pp
outputs
.Bd -literal
20201109 PHYSICIAN 5102 3234 100.00 Dr. Joseph Schmoe
20201109 DENTAL 5103 3234 183.00 Dr. Sally Sue
20201108 SHOP 5203 3234 53.83 example.com
20201104 PAY 3234 1700 75.43 Payment Thank You - Web
.Ed
.Pp
Note that the selector for Dr\&. Sally Sue
in the example configuration file comes before the
Health & Wellness selector.
Since the first match wins, transactions for Dr\&. Sally Sue
can be classified with the DENTAL booking identifier,
even though the bank's CSV file classifies
these transactions as Health & Wellness.
.Sh SEE ALSO
.Xr pta-accounts 5 ,
.Xr pta-journal 5 ,
.Xr pta-glossary 7
.Sh BUGS
Currently,
.Nm
has the following limitations:
.Bl -dash
.It
Pattern recognition in the
.Pa import/accountname.txt
files is under continued development.
.It
Only CSV files for these account types are supported:
.Bl -bullet -offset indent -compact
.It
.Cm BBVA USA bank accounts
.It
.Cm Capital One credit cards
.It
.Cm Chase credit cards
.It
.Cm Optum HSA bank accounts
.It
.Cm Sparkasse bank accounts
.It
.Cm Wells Fargo bank accounts
.El
.El