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