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