version 1.1, 2020/11/01 22:57:03 |
version 1.9, 2020/11/28 15:10:36 |
|
|
.Nd print pta journal entries from bank CSV file input |
.Nd print pta journal entries from bank CSV file input |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm pta_import |
.Nm pta_import |
.Ar file |
.Fl I Ar accountname |
|
.Op Ar file |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
utility converts lines from a CSV file generated by a financial |
utility converts lines from a CSV |
|
.Ar file |
|
generated by a financial |
institution into journal entries used by |
institution into journal entries used by |
.Xr pta 1 . |
.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_360 |
|
.It |
|
.Cm capital_one_credit |
|
.It |
|
.Cm chase_credit |
|
.It |
|
.Cm etrade_ira |
|
.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 |
.Sh FILES |
.Bl -tag -width import.txt |
.Bl -tag -width Ds -compact |
.It Pa ./import.txt |
.It Pa ./import/bbva_usa.txt |
file containing account numbers associated with CSV categories |
.It Pa ./import/capital_one_360.txt |
|
.It Pa ./import/capital_one_credit.txt |
|
.It Pa ./import/chase_credit.txt |
|
.It Pa ./import/etrade_ira.txt |
|
.It Pa ./import/optum_hsa.txt |
|
.It Pa ./import/sparkasse_camt.txt |
|
.It Pa ./import/wellsfargo.txt |
.El |
.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 |
.Sh EXIT STATUS |
.Ex -std |
.Ex -std |
.Sh EXAMPLES |
.Sh EXAMPLES |
Add journal entries to a journal file using a CSV file generated by |
Add journal entries to a journal file using a CSV file generated by |
a financial institution: |
a financial institution: |
.Pp |
.Pp |
.Dl "$ pta_import MyCreditCard1234.csv >> journal.txt" |
.Dl "$ pta_import -I chase_credit chasedownload.csv >> journal.txt" |
|
.Ss Account numbers in the configuration file |
|
The line |
.Pp |
.Pp |
Suppose a line in the CSV file looks like |
.Dl ACCOUNT 3235 |
.Pp |
.Pp |
.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07" |
in the configuration file corresponds to a line such as |
.Pp |
.Pp |
Then |
.Dl 3235 L Capital One credit card |
.Nm |
|
prints |
|
.Pp |
.Pp |
.Dl "20201026 SHOP 9996 1234 17.07 example.com*asldfkj" |
in |
|
.Pa ./accounts.txt . |
.Pp |
.Pp |
In this example, the user's |
The description |
.Pa ./import.txt |
.Qq Capital One credit card |
contains |
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 |
.Pp |
.Dl "SHOP Shopping 9996" |
.Dl ,,,Automotive,,, 1111 AUTO |
.Pp |
.Pp |
to reflect that their expense account for shopping is 9996 in |
is a sample entry in the |
.Pa ./accounts.txt |
.Pa ./import/chase_credit.txt |
and |
file which uses headers of the form |
.Pp |
.Pp |
.Dl "CVSACCOUNT Current Account 1234" |
.Dl Transaction Date,Post Date,Description,Category,Type,Amount |
.Pp |
.Pp |
to reflect that the account they are importing is 1234 in |
Then this |
.Pa ./accounts.txt . |
.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 |
.Pp |
Now suppose a line in the CSV file looks like |
.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07" |
.Pp |
.Pp |
.Dl "10/27/2020,10/27/2020,Payment Thank You - Web,,Payment,1653.42" |
and |
|
.Pa ./import/chase_credit.txt |
|
contains |
|
.Bd -literal -offset Ds |
|
ACCOUNT 3234 |
|
,,,Shopping,,, 9996 SHOP |
|
.Ed |
.Pp |
.Pp |
Then |
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 |
.Nm |
prints |
prints |
.Pp |
.Pp |
.Dl "20201027 DEFAULTCONTRA 1234 5678 1653.2 Payment Thank You - Web" |
.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 |
.Pp |
In this example, the user's |
and |
.Pa ./import.txt |
.Pa chasedownload.csv |
has |
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 |
.Pp |
.Dl "DEFAULTCONTRA Contra 5678" |
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 |
.Pp |
to reflect that the default account used to make payments for the |
Then |
account we are importing is 5678. |
.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 |
.Sh SEE ALSO |
.Xr pta-accounts 5 , |
.Xr pta-accounts 5 , |
.Xr pta-journal 5 , |
.Xr pta-journal 5 , |
|
|
has the following limitations: |
has the following limitations: |
.Bl -dash |
.Bl -dash |
.It |
.It |
The CVS file's first line must contain a header. |
Pattern recognition in the |
|
.Pa import/accountname.txt |
|
files is under continued development. |
.It |
.It |
Only CSV files generated by Chase Bank are supported at this time. |
User-defined configuration files are not currently |
|
supported. |
.El |
.El |