[BACK]Return to pta_import.1 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / pta

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