Annotation of pta/pta_import.1, Revision 1.3
1.3 ! schwarze 1: .\" $Id: pta_import.1,v 1.2 2020/11/01 23:07:35 schwarze Exp $
1.1 schwarze 2: .\"
3: .\" Copyright (c) 2020 Freda Bundchen
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.2 schwarze 17: .Dd $Mdocdate: November 1 2020 $
1.1 schwarze 18: .Dt PTA_IMPORT 1
19: .Os
20: .Sh NAME
21: .Nm pta_import
22: .Nd print pta journal entries from bank CSV file input
23: .Sh SYNOPSIS
24: .Nm pta_import
1.3 ! schwarze 25: .Fl I Ar bankFormat
1.2 schwarze 26: .Op Ar file
1.1 schwarze 27: .Sh DESCRIPTION
28: The
29: .Nm
1.2 schwarze 30: utility converts lines from a CSV
31: .Ar file
32: generated by a financial
1.1 schwarze 33: institution into journal entries used by
34: .Xr pta 1 .
1.2 schwarze 35: .Pp
36: If the
37: .Ar file
38: argument is omitted, standard input is read instead.
1.3 ! schwarze 39: .Pp
! 40: .Ar bankFormat
! 41: is exactly one of
! 42: .Bl -tag -width Ds
! 43: .It capital_one_credit
! 44: .It chase_credit
! 45: .It optum_hsa
! 46: .El
! 47: .Pp
! 48: and corresponds to an existing
! 49: .Qq import_bankFormat.txt
! 50: file in the current directory.
1.1 schwarze 51: .Sh FILES
1.3 ! schwarze 52: .Bl -tag -width Ds
! 53: .It Pa ./import_capital_one_credit.txt
! 54: .It Pa ./import_chase_credit.txt
! 55: .It Pa ./import_optum_hsa.txt
1.1 schwarze 56: .El
1.3 ! schwarze 57: .Pp
! 58: These files contain the header that the financial institution uses, the
! 59: account number from
! 60: .Pa ./accounts.txt
! 61: used by this account, as well as patterns used to map transactions to
! 62: the correct account and booking identifier.
! 63: .Ss Defining the account number
! 64: Each file must contain one line beginning with
! 65: .Qq ACCOUNT
! 66: and is followed by whitespace and then an account number.
! 67: The account number corresponds to the account in
! 68: .Pa ./accounts.txt
! 69: for the imported account.
! 70: .Ss Patterns in the import_bankFormat.txt files
! 71: Each file contains lines of the form
! 72: .Pp
! 73: .Ar selector account_number booking_identifier
1.1 schwarze 74: .Sh EXIT STATUS
75: .Ex -std
76: .Sh EXAMPLES
77: Add journal entries to a journal file using a CSV file generated by
78: a financial institution:
79: .Pp
1.3 ! schwarze 80: .Dl "$ pta_import -I chase_credit chasedownload.csv >> journal.txt"
! 81: .Ss A sample credit card purchase
! 82: Suppose a line in the
! 83: .Pa chasedownload.csv
! 84: file looks like
1.1 schwarze 85: .Pp
1.3 ! schwarze 86: .Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"
1.1 schwarze 87: .Pp
1.3 ! schwarze 88: If the line matching the
! 89: .Qq Shopping
! 90: category in the user's
! 91: .Pa ./import_chase_credit.txt
! 92: file is
! 93: .Pp
! 94: .Dl ,,,Shopping,,, 9996 SHOP
! 95: .Pp
! 96: then the
! 97: .Qq Shopping
! 98: category defined by Chase is mapped to the user's
! 99: .Qq SHOP
! 100: booking identifier, and the user's account for shopping
! 101: expenses is defined as
! 102: .Qq 9996
! 103: in their
! 104: .Pa ./accounts.txt .
! 105: .Pp
! 106: We further assume in this example that the user has edited
! 107: .Pa ./import_chase_credit.txt
! 108: so that the line beginning with
! 109: .Qq ACCOUNT
! 110: contains the liability account they have defined for their Chase card
! 111: in
! 112: .Pa ./accounts.txt
! 113: .Pp
! 114: In this example,
! 115: .Pa ./import_chase_credit.txt
! 116: contains
! 117: .Dl ACCOUNT 3234
1.1 schwarze 118: .Pp
119: Then
120: .Nm
121: prints
122: .Pp
1.3 ! schwarze 123: .Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj"
! 124: .Ss A sample credit card payment
! 125: .Dl "10/27/2020,10/27/2020,Payment Thank You - Web,,Payment,1653.42"
! 126: .Pp
! 127: Suppose the user's
! 128: .Pa ./import_chase_credit.txt
! 129: file contains
! 130: .Pp
! 131: .Dl ,,,,Payment,, 1700 PAY
! 132: .Pp
! 133: which matches Chase's payment category to the user's asset account
! 134: .Qq 1700
! 135: used to pay off the credit card.
! 136: Then
! 137: .Nm
! 138: prints
1.1 schwarze 139: .Pp
1.3 ! schwarze 140: .Dl "20201027 PAY 3234 1700 1653.2 Payment Thank You - Web"
! 141: .Ss Account numbers in the import_bankFormat.txt files
! 142: For example, if
! 143: .Pa ./import_capital_one_credit.txt
1.1 schwarze 144: contains
145: .Pp
1.3 ! schwarze 146: .Dl ACCOUNT 1293
1.1 schwarze 147: .Pp
1.3 ! schwarze 148: then there must be a corresponding entry in
1.1 schwarze 149: .Pa ./accounts.txt
1.3 ! schwarze 150: such as
! 151: .Dl 1293 L Capital One credit card
1.1 schwarze 152: .Pp
1.3 ! schwarze 153: The description
! 154: .Qq Capital One credit card
! 155: may vary, but in this example, the account numbers
! 156: .Qq 1293
! 157: match, and the account type is
! 158: .Qq L
! 159: to indicate that it is a liability account.
! 160: .Ss Patterns in the import_bankFormat.txt files
! 161: Suppose
! 162: .Dl ,,,Automotive,,, 1111 AUTO
! 163: .Pp
! 164: is a sample entry in the
! 165: .Pa ./import_chase_credit.txt
! 166: file which uses headers of the form
! 167: .Pp
! 168: .Dl Transaction Date,Post Date,Description,Category,Type,Amount
! 169: .Pp
! 170: Then this
! 171: .Ar selector
! 172: ignores the transaction date, post date, description, type, and amount.
! 173: It matches the
! 174: .Qq Automotive
! 175: category and maps transactions to account
! 176: .Qq 1111
! 177: defined in
! 178: .Pa ./accounts.txt
! 179: with the
! 180: .Qq Auto
! 181: booking identifier.
! 182: .Ss A complete example
! 183: Suppose
! 184: .Pa ./accounts.txt
! 185: is given by
! 186: .Bd -literal
! 187: 1700 A My Bank
! 188: 3234 L My Chase Credit Card
! 189: 5102 X Physician expenses
! 190: 5103 X Dental expenses
! 191: 5203 X Shopping
! 192:
! 193: .Ed
1.1 schwarze 194: .Pp
1.3 ! schwarze 195: and
! 196: .Pa chasedownload.csv
! 197: is given by
! 198: .Bd -literal
! 199: Transaction Date,Post Date,Description,Category,Type,Amount,Memo
! 200: 11/06/2020,11/09/2020,Dr. Joseph Schmoe,Health & Wellness,Sale,-100.00,
! 201: 11/06/2020,11/09/2020,Dr. Sally Sue,Health & Wellness,Sale,-183.00,
! 202: 11/08/2020,11/08/2020,example.com,Shopping,Sale,-53.83,
! 203: 11/04/2020,11/04/2020,Payment Thank You - Web,,Payment,75.43,
! 204: .Ed
1.1 schwarze 205: .Pp
1.3 ! schwarze 206: and
! 207: .Pa ./import_chase_credit.txt
! 208: is given by
! 209: .Bd -literal
! 210: # Chase credit card header is
! 211: # Transaction Date,Post Date,Description,Category,Type,Amount
! 212: # The format of this file is
! 213: # selector account_number booking_identifier
! 214: # selector is a comma-separated list of regular expressions which
! 215: # matches corresponding fields in the CSV file
! 216: ACCOUNT 3234
! 217: ,,,Automotive,,, 1111 AUTO
! 218: ,,,Bills & Utilities,,, 2222 BILLS
! 219: ,,,Fees & Adjustments,,, 3333 FEES
! 220: ,,,Food & Drink,,, 4444 FOOD
! 221: ,,,Gas,,, 5555 GAS
! 222: ,,,Gifts & Donations,,, 6666 GIFTS
! 223: ,,,Groceries,,, 7777 GROCERIES
! 224: ,,Dr. Sally Sue,,,, 5103 DENTAL
! 225: ,,,Health & Wellness,,, 5102 PHYSICIAN
! 226: ,,,Home,,, 9999 HOME
! 227: ,,,Personal,,, 9998 PERSONAL
! 228: ,,,Professional Services,,, 9997 PRO
! 229: ,,,Shopping,,, 5203 SHOP
! 230: ,,,,Payment,, 1700 PAY
! 231: .Ed
1.1 schwarze 232: .Pp
233: Then
1.3 ! schwarze 234: .Dl pta_import -I chase_credit chasedownload.csv
! 235: outputs
! 236: .Bd -literal
! 237: 20201109 PHYSICIAN 5102 3234 100.00 Dr. Joseph Schmoe
! 238: 20201109 DENTAL 5103 3234 183.00 Dr. Sally Sue
! 239: 20201108 SHOP 5203 3234 53.83 example.com
! 240: 20201104 PAY 3234 1700 75.43 Payment Thank You - Web
! 241: .Ed
1.1 schwarze 242: .Sh SEE ALSO
243: .Xr pta-accounts 5 ,
244: .Xr pta-journal 5 ,
245: .Xr pta-glossary 7
246: .Sh BUGS
247: Currently,
248: .Nm
249: has the following limitations:
250: .Bl -dash
251: .It
1.3 ! schwarze 252: Pattern recognition in the
! 253: .Pa import_bankFormat.txt
! 254: files is under continued development.
! 255: .It
! 256: The only defined import formats are for Chase credit cards,
! 257: Capital One credit cards, and Optum Health Savings Accounts.
1.1 schwarze 258: .It
1.3 ! schwarze 259: Note that the first pattern match wins in
! 260: .Pa ./import_bankFormat.txt .
! 261: In the complete example above, we put the line containing
! 262: .Qq Dr. Sally Sue
! 263: before the line matching the
! 264: .Qq Health & Wellness
! 265: category because we wanted to override the
! 266: .Qq Health & Wellness
! 267: category, and use the
! 268: .Qq Dental expenses
! 269: account instead.
1.1 schwarze 270: .El
CVSweb