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

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