Annotation of pta/pta_import.1, Revision 1.17
1.17 ! freda 1: .\" $Id: pta_import.1,v 1.16 2020/12/11 20:12:02 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.15 freda 17: .Dd $Mdocdate: December 11 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.14 freda 40: The
1.5 schwarze 41: .Ar accountname
1.14 freda 42: argument corresponds to an existing
1.8 freda 43: .Pa ./import/ Ns Ar accountname Ns Pa .txt
44: configuration file.
1.5 schwarze 45: .Ss Configuration file format
1.8 freda 46: Each configuration file contains rules
1.7 freda 47: used to import transactions from a financial institution.
1.5 schwarze 48: Like all
49: .Xr pta 1
50: input files, it is an
51: .Xr ascii 7
52: text file using strings of one or more space characters
53: as the field delimiter and using the hash character
54: .Pq Sq #
55: in the first column to mark lines as ignored.
56: .Pp
1.7 freda 57: The rules are as follows:
58: .Bl -tag -width Ds
59: .It Ic ACCOUNT Ar csv_account_number
60: The number in
61: .Xr pta-accounts 5
62: of the bank or credit card account this CSV file contains entries for.
63: This rule is required in every configuration file.
1.11 freda 64: .It Ic AMOUNT Oo Ar debit_column Oc Ar credit_column
65: The column numbers in the CSV file containing amounts to be
66: booked on the debit or credits side of the contra account
67: .Ar account_number ,
68: respectively.
69: If
70: .Ar debit_column
71: is omitted, amounts preceded by a minus sign or enclosed
72: in parentheses are booked to the debit side.
1.15 freda 73: This rule is required in every configuration file.
1.10 freda 74: .It Ic COSTCENTER Ar costcenter_column
75: The column number in the CSV file containing the cost center.
76: Numbering starts from 1.
77: If this rule is not specified, no cost centers are assigned.
78: .It Ic DATE Ar date_column date_format
79: The column number in the CSV file containing the date.
80: Numbering starts from 1.
81: The
82: .Ar date_format
83: is one of
84: .Ic MM/DD/YY ,
85: .Ic MM/DD/YYYY ,
86: .Ic YYYY-MM-DD ,
87: or
88: .Ic DD.MM.YY .
89: This rule is required in every configuration file.
1.11 freda 90: .It Ic DESCRIPTION Ar descr_column ...
91: The column numbers in the CSV file to be concatenated to form the
92: text string for the journal entry.
93: Numbering starts from 1.
1.15 freda 94: This rule is required in every configuration file.
1.7 freda 95: .It Ic DELIM Ar delimiter
96: The character used to separate fields.
1.15 freda 97: Most financial institutions use commas but some use semicolons.
1.7 freda 98: This rule is required in every configuration file.
99: .It Ic HEADER Ar header
100: Skip the first line of the CSV file if it matches the
101: .Ar header
102: line verbatim, or cause parsing to fail if it does not.
103: .It Ic IGNORE Ar regular_expression
104: Skip all lines in the CSV file matching the
105: .Ar regular_expression .
1.10 freda 106: .It Ic QUANTITY Ar quantity_column
107: The column number in the CSV file containing the number of stock shares.
108: Numbering starts from 1.
109: If this rule is not specified, no information about the number of traded
110: securities is appended to the text string.
1.7 freda 111: .It Ic QUOTE Ar quote
112: Expects that every field starts and ends with the
113: .Ar quote
114: character.
1.17 ! freda 115: .It Ar selector account_number booking_identifier Op Ar subaccount
1.7 freda 116: Lines in the CSV file that match the
1.5 schwarze 117: .Ar selector
1.7 freda 118: are associated with the contra account
1.17 ! freda 119: .Ar account_number ,
! 120: the optional
! 121: .Ar subaccount ,
1.7 freda 122: and are assigned the
123: .Ar booking_identifier .
124: The selector is a string consisting of regular expressions separated
125: by delimiters defined in the
126: .Ic DELIM
127: rule.
1.15 freda 128: These rules appear after all other rule types.
1.7 freda 129: .El
1.1 schwarze 130: .Sh FILES
1.12 freda 131: Example configuration files:
132: .Bl -tag -offset indent -width Ds -compact
1.8 freda 133: .It Pa ./import/bbva_usa.txt
1.9 freda 134: .It Pa ./import/capital_one_360.txt
1.8 freda 135: .It Pa ./import/capital_one_credit.txt
136: .It Pa ./import/chase_credit.txt
1.9 freda 137: .It Pa ./import/etrade_ira.txt
138: .It Pa ./import/optum_hsa.txt
1.8 freda 139: .It Pa ./import/sparkasse_camt.txt
140: .It Pa ./import/wellsfargo.txt
1.1 schwarze 141: .El
1.3 schwarze 142: .Pp
1.12 freda 143: Example CSV files:
144: .Bl -tag -offset indent -width Ds -compact
145: .It Pa ./csv/bbva_usa.csv
146: .It Pa ./csv/capital_one_360.csv
147: .It Pa ./csv/capital_one_credit.csv
148: .It Pa ./csv/chase_credit.csv
149: .It Pa ./csv/etrade_ira.csv
150: .It Pa ./csv/optum_hsa.csv
151: .It Pa ./csv/wellsfargo.csv
152: .El
1.1 schwarze 153: .Sh EXIT STATUS
154: .Ex -std
155: .Sh EXAMPLES
156: Add journal entries to a journal file using a CSV file generated by
1.13 freda 157: a financial institution, and a configuration file
158: .Pa ./import/my_bank.txt :
1.1 schwarze 159: .Pp
1.13 freda 160: .Dl "$ pta_import -I my_bank downloaded.csv >> journal.txt"
1.1 schwarze 161: .Pp
1.13 freda 162: The result of applying a configuration file
163: of the form
164: .Pa ./import/accountname.txt
165: to the corresponding CSV file
166: .Pa ./csv/accountname.csv
167: may be seen in
168: .Pa ./regress/import/expected/accountname.out .
1.1 schwarze 169: .Sh SEE ALSO
1.16 freda 170: .Xr pta 1 ,
1.1 schwarze 171: .Xr pta-accounts 5 ,
172: .Xr pta-journal 5 ,
173: .Xr pta-glossary 7
174: .Sh BUGS
175: Currently,
176: .Nm
177: has the following limitations:
178: .Bl -dash
179: .It
1.3 schwarze 180: Pattern recognition in the
1.8 freda 181: .Pa import/accountname.txt
1.3 schwarze 182: files is under continued development.
1.1 schwarze 183: .El
CVSweb