Annotation of pta/pta_import.1, Revision 1.5
1.5 ! schwarze 1: .\" $Id: pta_import.1,v 1.4 2020/11/12 14:26:51 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.4 schwarze 17: .Dd $Mdocdate: November 12 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.5 ! schwarze 25: .Fl I Ar accountname
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
1.5 ! schwarze 40: .Ar accountname
1.3 schwarze 41: is exactly one of
1.4 schwarze 42: .Pp
43: .Bl -bullet -offset indent -compact
44: .It
45: .Cm capital_one_credit
46: .It
47: .Cm chase_credit
48: .It
49: .Cm optum_hsa
1.3 schwarze 50: .El
51: .Pp
52: and corresponds to an existing
1.5 ! schwarze 53: .Pa import_ Ns Ar accountname Ns Pa .txt
! 54: configuration file in the current directory.
! 55: .Ss Configuration file format
! 56: Each file of the form
! 57: .Pa import_ Ns Ar accountname Ns Pa .txt
! 58: in the current directory is a configuration file used to
! 59: import transactions from a financial institution.
! 60: Like all
! 61: .Xr pta 1
! 62: input files, it is an
! 63: .Xr ascii 7
! 64: text file using strings of one or more space characters
! 65: as the field delimiter and using the hash character
! 66: .Pq Sq #
! 67: in the first column to mark lines as ignored.
! 68: .Pp
! 69: Each file contains one line beginning with
! 70: .Qq ACCOUNT
! 71: and is followed by whitespace and then an account number.
! 72: .Pp
! 73: Each file contains lines of the form
! 74: .Pp
! 75: .Ar selector account_number booking_identifier
! 76: .Pp
! 77: The
! 78: .Ar selector
! 79: is a string consisting of regular expressions
! 80: separated by commas.
! 81: Its fields correspond to header fields in the financial
! 82: institution's CSV file and is used to classify transactions
! 83: that match the search pattern.
! 84: The first selector that
! 85: matches a transaction wins.
! 86: .Pp
! 87: The
! 88: .Ar account_number
! 89: corresponds to an account number in
! 90: .Pa ./accounts.txt .
! 91: The
! 92: .Ar booking_identifier
! 93: is defined by the user to classify
! 94: the transaction.
1.1 schwarze 95: .Sh FILES
1.4 schwarze 96: .Bl -tag -width Ds -compact
1.3 schwarze 97: .It Pa ./import_capital_one_credit.txt
98: .It Pa ./import_chase_credit.txt
99: .It Pa ./import_optum_hsa.txt
1.1 schwarze 100: .El
1.3 schwarze 101: .Pp
102: These files contain the header that the financial institution uses, the
103: account number from
104: .Pa ./accounts.txt
105: used by this account, as well as patterns used to map transactions to
106: the correct account and booking identifier.
1.1 schwarze 107: .Sh EXIT STATUS
108: .Ex -std
109: .Sh EXAMPLES
110: Add journal entries to a journal file using a CSV file generated by
111: a financial institution:
112: .Pp
1.3 schwarze 113: .Dl "$ pta_import -I chase_credit chasedownload.csv >> journal.txt"
1.5 ! schwarze 114: .Ss Account numbers in the configuration file
! 115: The line
1.1 schwarze 116: .Pp
1.5 ! schwarze 117: .Dl ACCOUNT 3235
1.3 schwarze 118: .Pp
1.5 ! schwarze 119: in the configuration file corresponds to a line such as
1.3 schwarze 120: .Pp
1.5 ! schwarze 121: .Dl 3235 L Capital One credit card
1.3 schwarze 122: .Pp
123: in
1.5 ! schwarze 124: .Pa ./accounts.txt .
1.1 schwarze 125: .Pp
1.3 schwarze 126: The description
127: .Qq Capital One credit card
128: may vary, but in this example, the account numbers
1.5 ! schwarze 129: .Qq 3235
1.3 schwarze 130: match, and the account type is
131: .Qq L
132: to indicate that it is a liability account.
1.5 ! schwarze 133: .Ss Patterns in the configuration file
1.3 schwarze 134: Suppose
1.4 schwarze 135: .Pp
1.3 schwarze 136: .Dl ,,,Automotive,,, 1111 AUTO
137: .Pp
138: is a sample entry in the
139: .Pa ./import_chase_credit.txt
140: file which uses headers of the form
141: .Pp
142: .Dl Transaction Date,Post Date,Description,Category,Type,Amount
143: .Pp
144: Then this
145: .Ar selector
146: ignores the transaction date, post date, description, type, and amount.
147: It matches the
148: .Qq Automotive
149: category and maps transactions to account
150: .Qq 1111
151: defined in
152: .Pa ./accounts.txt
153: with the
154: .Qq Auto
155: booking identifier.
1.5 ! schwarze 156: .Ss A sample credit card purchase
! 157: If
! 158: .Pa chasedownload.csv
! 159: file contains
! 160: .Pp
! 161: .Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"
! 162: .Pp
! 163: and
! 164: .Pa ./import_chase_credit.txt
! 165: contains
! 166: .Bd -literal -offset Ds
! 167: ACCOUNT 3234
! 168: ,,,Shopping,,, 9996 SHOP
! 169: .Ed
! 170: .Pp
! 171: and
! 172: .Pa ./accounts.txt
! 173: contains
! 174: .Bd -literal -offset Ds
! 175: 3234 L Chase credit card
! 176: 9996 X shopping
! 177: .Ed
! 178: .Pp
! 179: then the
! 180: .Qq Shopping
! 181: category defined by Chase is mapped to the user's
! 182: .Qq SHOP
! 183: booking identifier, the user's account for shopping
! 184: expenses is defined as
! 185: .Qq 9996
! 186: in their
! 187: .Pa ./accounts.txt ,
! 188: the user's account for the credit card is 3234 in their
! 189: .Pa ./accounts.txt ,
! 190: and
! 191: .Nm
! 192: prints
! 193: .Pp
! 194: .Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj"
1.3 schwarze 195: .Ss A complete example
196: Suppose
197: .Pa ./accounts.txt
198: is given by
199: .Bd -literal
200: 1700 A My Bank
201: 3234 L My Chase Credit Card
202: 5102 X Physician expenses
203: 5103 X Dental expenses
204: 5203 X Shopping
205: .Ed
1.1 schwarze 206: .Pp
1.3 schwarze 207: and
208: .Pa chasedownload.csv
209: is given by
210: .Bd -literal
211: Transaction Date,Post Date,Description,Category,Type,Amount,Memo
212: 11/06/2020,11/09/2020,Dr. Joseph Schmoe,Health & Wellness,Sale,-100.00,
213: 11/06/2020,11/09/2020,Dr. Sally Sue,Health & Wellness,Sale,-183.00,
214: 11/08/2020,11/08/2020,example.com,Shopping,Sale,-53.83,
215: 11/04/2020,11/04/2020,Payment Thank You - Web,,Payment,75.43,
216: .Ed
1.1 schwarze 217: .Pp
1.3 schwarze 218: and
219: .Pa ./import_chase_credit.txt
220: is given by
221: .Bd -literal
222: # Chase credit card header is
223: # Transaction Date,Post Date,Description,Category,Type,Amount
224: # The format of this file is
225: # selector account_number booking_identifier
226: # selector is a comma-separated list of regular expressions which
227: # matches corresponding fields in the CSV file
228: ACCOUNT 3234
229: ,,,Automotive,,, 1111 AUTO
230: ,,,Bills & Utilities,,, 2222 BILLS
231: ,,,Fees & Adjustments,,, 3333 FEES
232: ,,,Food & Drink,,, 4444 FOOD
233: ,,,Gas,,, 5555 GAS
234: ,,,Gifts & Donations,,, 6666 GIFTS
235: ,,,Groceries,,, 7777 GROCERIES
236: ,,Dr. Sally Sue,,,, 5103 DENTAL
237: ,,,Health & Wellness,,, 5102 PHYSICIAN
238: ,,,Home,,, 9999 HOME
239: ,,,Personal,,, 9998 PERSONAL
240: ,,,Professional Services,,, 9997 PRO
241: ,,,Shopping,,, 5203 SHOP
242: ,,,,Payment,, 1700 PAY
243: .Ed
1.1 schwarze 244: .Pp
245: Then
1.4 schwarze 246: .Pp
1.3 schwarze 247: .Dl pta_import -I chase_credit chasedownload.csv
1.4 schwarze 248: .Pp
1.3 schwarze 249: outputs
250: .Bd -literal
251: 20201109 PHYSICIAN 5102 3234 100.00 Dr. Joseph Schmoe
252: 20201109 DENTAL 5103 3234 183.00 Dr. Sally Sue
253: 20201108 SHOP 5203 3234 53.83 example.com
254: 20201104 PAY 3234 1700 75.43 Payment Thank You - Web
255: .Ed
1.5 ! schwarze 256: .Pp
! 257: Note that the selector for Dr\&. Sally Sue
! 258: in the example configuration file comes before the
! 259: Health & Wellness selector.
! 260: Since the first match wins, transactions for Dr\&. Sally Sue
! 261: can be classified with the DENTAL booking identifier,
! 262: even though the bank's CSV file classifies
! 263: these transactions as Health & Wellness.
1.1 schwarze 264: .Sh SEE ALSO
265: .Xr pta-accounts 5 ,
266: .Xr pta-journal 5 ,
267: .Xr pta-glossary 7
268: .Sh BUGS
269: Currently,
270: .Nm
271: has the following limitations:
272: .Bl -dash
273: .It
1.3 schwarze 274: Pattern recognition in the
1.5 ! schwarze 275: .Pa import_accountname.txt
1.3 schwarze 276: files is under continued development.
277: .It
278: The only defined import formats are for Chase credit cards,
279: Capital One credit cards, and Optum Health Savings Accounts.
1.1 schwarze 280: .El
CVSweb