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