=================================================================== RCS file: /cvs/pta/pta_import.1,v retrieving revision 1.1 retrieving revision 1.16 diff -u -p -r1.1 -r1.16 --- pta/pta_import.1 2020/11/01 22:57:03 1.1 +++ pta/pta_import.1 2020/12/11 20:12:02 1.16 @@ -1,4 +1,4 @@ -.\" $Id: pta_import.1,v 1.1 2020/11/01 22:57:03 schwarze Exp $ +.\" $Id: pta_import.1,v 1.16 2020/12/11 20:12:02 freda Exp $ .\" .\" Copyright (c) 2020 Freda Bundchen .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: November 1 2020 $ +.Dd $Mdocdate: December 11 2020 $ .Dt PTA_IMPORT 1 .Os .Sh NAME @@ -22,70 +22,150 @@ .Nd print pta journal entries from bank CSV file input .Sh SYNOPSIS .Nm pta_import -.Ar file +.Fl I Ar accountname +.Op Ar file .Sh DESCRIPTION The .Nm -utility converts lines from a CSV file generated by a financial +utility converts lines from a CSV +.Ar file +generated by a financial institution into journal entries used by .Xr pta 1 . +.Pp +If the +.Ar file +argument is omitted, standard input is read instead. +.Pp +The +.Ar accountname +argument corresponds to an existing +.Pa ./import/ Ns Ar accountname Ns Pa .txt +configuration file. +.Ss Configuration file format +Each configuration file contains rules +used to import transactions from a financial institution. +Like all +.Xr pta 1 +input files, it is an +.Xr ascii 7 +text file using strings of one or more space characters +as the field delimiter and using the hash character +.Pq Sq # +in the first column to mark lines as ignored. +.Pp +The rules are as follows: +.Bl -tag -width Ds +.It Ic ACCOUNT Ar csv_account_number +The number in +.Xr pta-accounts 5 +of the bank or credit card account this CSV file contains entries for. +This rule is required in every configuration file. +.It Ic AMOUNT Oo Ar debit_column Oc Ar credit_column +The column numbers in the CSV file containing amounts to be +booked on the debit or credits side of the contra account +.Ar account_number , +respectively. +If +.Ar debit_column +is omitted, amounts preceded by a minus sign or enclosed +in parentheses are booked to the debit side. +This rule is required in every configuration file. +.It Ic COSTCENTER Ar costcenter_column +The column number in the CSV file containing the cost center. +Numbering starts from 1. +If this rule is not specified, no cost centers are assigned. +.It Ic DATE Ar date_column date_format +The column number in the CSV file containing the date. +Numbering starts from 1. +The +.Ar date_format +is one of +.Ic MM/DD/YY , +.Ic MM/DD/YYYY , +.Ic YYYY-MM-DD , +or +.Ic DD.MM.YY . +This rule is required in every configuration file. +.It Ic DESCRIPTION Ar descr_column ... +The column numbers in the CSV file to be concatenated to form the +text string for the journal entry. +Numbering starts from 1. +This rule is required in every configuration file. +.It Ic DELIM Ar delimiter +The character used to separate fields. +Most financial institutions use commas but some use semicolons. +This rule is required in every configuration file. +.It Ic HEADER Ar header +Skip the first line of the CSV file if it matches the +.Ar header +line verbatim, or cause parsing to fail if it does not. +.It Ic IGNORE Ar regular_expression +Skip all lines in the CSV file matching the +.Ar regular_expression . +.It Ic QUANTITY Ar quantity_column +The column number in the CSV file containing the number of stock shares. +Numbering starts from 1. +If this rule is not specified, no information about the number of traded +securities is appended to the text string. +.It Ic QUOTE Ar quote +Expects that every field starts and ends with the +.Ar quote +character. +.It Ar selector account_number booking_identifier +Lines in the CSV file that match the +.Ar selector +are associated with the contra account +.Ar account_number +and are assigned the +.Ar booking_identifier . +The selector is a string consisting of regular expressions separated +by delimiters defined in the +.Ic DELIM +rule. +These rules appear after all other rule types. +.El .Sh FILES -.Bl -tag -width import.txt -.It Pa ./import.txt -file containing account numbers associated with CSV categories +Example configuration files: +.Bl -tag -offset indent -width Ds -compact +.It Pa ./import/bbva_usa.txt +.It Pa ./import/capital_one_360.txt +.It Pa ./import/capital_one_credit.txt +.It Pa ./import/chase_credit.txt +.It Pa ./import/etrade_ira.txt +.It Pa ./import/optum_hsa.txt +.It Pa ./import/sparkasse_camt.txt +.It Pa ./import/wellsfargo.txt .El +.Pp +Example CSV files: +.Bl -tag -offset indent -width Ds -compact +.It Pa ./csv/bbva_usa.csv +.It Pa ./csv/capital_one_360.csv +.It Pa ./csv/capital_one_credit.csv +.It Pa ./csv/chase_credit.csv +.It Pa ./csv/etrade_ira.csv +.It Pa ./csv/optum_hsa.csv +.It Pa ./csv/wellsfargo.csv +.El .Sh EXIT STATUS .Ex -std .Sh EXAMPLES Add journal entries to a journal file using a CSV file generated by -a financial institution: +a financial institution, and a configuration file +.Pa ./import/my_bank.txt : .Pp -.Dl "$ pta_import MyCreditCard1234.csv >> journal.txt" +.Dl "$ pta_import -I my_bank downloaded.csv >> journal.txt" .Pp -Suppose a line in the CSV file looks like -.Pp -.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07" -.Pp -Then -.Nm -prints -.Pp -.Dl "20201026 SHOP 9996 1234 17.07 example.com*asldfkj" -.Pp -In this example, the user's -.Pa ./import.txt -contains -.Pp -.Dl "SHOP Shopping 9996" -.Pp -to reflect that their expense account for shopping is 9996 in -.Pa ./accounts.txt -and -.Pp -.Dl "CVSACCOUNT Current Account 1234" -.Pp -to reflect that the account they are importing is 1234 in -.Pa ./accounts.txt . -.Pp -Now suppose a line in the CSV file looks like -.Pp -.Dl "10/27/2020,10/27/2020,Payment Thank You - Web,,Payment,1653.42" -.Pp -Then -.Nm -prints -.Pp -.Dl "20201027 DEFAULTCONTRA 1234 5678 1653.2 Payment Thank You - Web" -.Pp -In this example, the user's -.Pa ./import.txt -has -.Pp -.Dl "DEFAULTCONTRA Contra 5678" -.Pp -to reflect that the default account used to make payments for the -account we are importing is 5678. +The result of applying a configuration file +of the form +.Pa ./import/accountname.txt +to the corresponding CSV file +.Pa ./csv/accountname.csv +may be seen in +.Pa ./regress/import/expected/accountname.out . .Sh SEE ALSO +.Xr pta 1 , .Xr pta-accounts 5 , .Xr pta-journal 5 , .Xr pta-glossary 7 @@ -95,7 +175,7 @@ Currently, has the following limitations: .Bl -dash .It -The CVS file's first line must contain a header. -.It -Only CSV files generated by Chase Bank are supported at this time. +Pattern recognition in the +.Pa import/accountname.txt +files is under continued development. .El