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

Diff for /pta/pta_import.1 between version 1.1 and 1.9

version 1.1, 2020/11/01 22:57:03 version 1.9, 2020/11/28 15:10:36
Line 22 
Line 22 
 .Nd print pta journal entries from bank CSV file input  .Nd print pta journal entries from bank CSV file input
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .Nm pta_import  .Nm pta_import
 .Ar file  .Fl I Ar accountname
   .Op Ar file
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .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  institution into journal entries used by
 .Xr pta 1 .  .Xr pta 1 .
   .Pp
   If the
   .Ar file
   argument is omitted, standard input is read instead.
   .Pp
   .Ar accountname
   is exactly one of
   .Pp
   .Bl -bullet -offset indent -compact
   .It
   .Cm bbva_usa
   .It
   .Cm capital_one_360
   .It
   .Cm capital_one_credit
   .It
   .Cm chase_credit
   .It
   .Cm etrade_ira
   .It
   .Cm optum_hsa
   .It
   .Cm sparkasse_camt
   .It
   .Cm wellsfargo
   .El
   .Pp
   and 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 DELIM Ar delimiter
   The character used to separate fields.
   This rule is required in every configuration file.
   Most financial institutions use commas but some use semicolons.
   .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 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.
   .El
 .Sh FILES  .Sh FILES
 .Bl -tag -width import.txt  .Bl -tag -width Ds -compact
 .It Pa ./import.txt  .It Pa ./import/bbva_usa.txt
 file containing account numbers associated with CSV categories  .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  .El
   .Pp
   These files contain the header that the financial institution uses, the
   account number from
   .Pa ./accounts.txt
   used by this account, as well as patterns used to map transactions to
   the correct account and booking identifier.
 .Sh EXIT STATUS  .Sh EXIT STATUS
 .Ex -std  .Ex -std
 .Sh EXAMPLES  .Sh EXAMPLES
 Add journal entries to a journal file using a CSV file generated by  Add journal entries to a journal file using a CSV file generated by
 a financial institution:  a financial institution:
 .Pp  .Pp
 .Dl "$ pta_import MyCreditCard1234.csv >> journal.txt"  .Dl "$ pta_import -I chase_credit chasedownload.csv >> journal.txt"
   .Ss Account numbers in the configuration file
   The line
 .Pp  .Pp
 Suppose a line in the CSV file looks like  .Dl ACCOUNT 3235
 .Pp  .Pp
 .Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"  in the configuration file corresponds to a line such as
 .Pp  .Pp
 Then  .Dl 3235 L Capital One credit card
 .Nm  
 prints  
 .Pp  .Pp
 .Dl "20201026 SHOP 9996 1234 17.07 example.com*asldfkj"  in
   .Pa ./accounts.txt .
 .Pp  .Pp
 In this example, the user's  The description
 .Pa ./import.txt  .Qq Capital One credit card
 contains  may vary, but in this example, the account numbers
   .Qq 3235
   match, and the account type is
   .Qq L
   to indicate that it is a liability account.
   .Ss Patterns in the configuration file
   Suppose
 .Pp  .Pp
 .Dl "SHOP Shopping 9996"  .Dl ,,,Automotive,,, 1111 AUTO
 .Pp  .Pp
 to reflect that their expense account for shopping is 9996 in  is a sample entry in the
 .Pa ./accounts.txt  .Pa ./import/chase_credit.txt
 and  file which uses headers of the form
 .Pp  .Pp
 .Dl "CVSACCOUNT Current Account 1234"  .Dl Transaction Date,Post Date,Description,Category,Type,Amount
 .Pp  .Pp
 to reflect that the account they are importing is 1234 in  Then this
 .Pa ./accounts.txt .  .Ar selector
   ignores the transaction date, post date, description, type, and amount.
   It matches the
   .Qq Automotive
   category and maps transactions to account
   .Qq 1111
   defined in
   .Pa ./accounts.txt
   with the
   .Qq Auto
   booking identifier.
   .Ss A sample credit card purchase
   If
   .Pa chasedownload.csv
   file contains
 .Pp  .Pp
 Now suppose a line in the CSV file looks like  .Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07"
 .Pp  .Pp
 .Dl "10/27/2020,10/27/2020,Payment Thank You - Web,,Payment,1653.42"  and
   .Pa ./import/chase_credit.txt
   contains
   .Bd -literal -offset Ds
   ACCOUNT 3234
   ,,,Shopping,,, 9996 SHOP
   .Ed
 .Pp  .Pp
 Then  and
   .Pa ./accounts.txt
   contains
   .Bd -literal -offset Ds
   3234 L Chase credit card
   9996 X shopping
   .Ed
   .Pp
   then the
   .Qq Shopping
   category defined by Chase is mapped to the user's
   .Qq SHOP
   booking identifier, the user's account for shopping
   expenses is defined as
   .Qq 9996
   in their
   .Pa ./accounts.txt ,
   the user's account for the credit card is 3234 in their
   .Pa ./accounts.txt ,
   and
 .Nm  .Nm
 prints  prints
 .Pp  .Pp
 .Dl "20201027 DEFAULTCONTRA 1234 5678 1653.2 Payment Thank You - Web"  .Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj"
   .Ss A complete example
   Suppose
   .Pa ./accounts.txt
   is given by
   .Bd -literal
   1700 A My Bank
   3234 L My Chase Credit Card
   5102 X Physician expenses
   5103 X Dental expenses
   5203 X Shopping
   .Ed
 .Pp  .Pp
 In this example, the user's  and
 .Pa ./import.txt  .Pa chasedownload.csv
 has  is given by
   .Bd -literal
   Transaction Date,Post Date,Description,Category,Type,Amount,Memo
   11/06/2020,11/09/2020,Dr. Joseph Schmoe,Health & Wellness,Sale,-100.00,
   11/06/2020,11/09/2020,Dr. Sally Sue,Health & Wellness,Sale,-183.00,
   11/08/2020,11/08/2020,example.com,Shopping,Sale,-53.83,
   11/04/2020,11/04/2020,Payment Thank You - Web,,Payment,75.43,
   .Ed
 .Pp  .Pp
 .Dl "DEFAULTCONTRA Contra 5678"  and
   .Pa ./import/chase_credit.txt
   is given by
   .Bd -literal
   # Chase credit card header is
   # Transaction Date,Post Date,Description,Category,Type,Amount
   # The format of this file is
   # selector account_number booking_identifier
   # selector is a comma-separated list of regular expressions which
   # matches corresponding fields in the CSV file
   ACCOUNT 3234
   ,,,Automotive,,, 1111 AUTO
   ,,,Bills & Utilities,,, 2222 BILLS
   ,,,Fees & Adjustments,,, 3333 FEES
   ,,,Food & Drink,,, 4444 FOOD
   ,,,Gas,,, 5555 GAS
   ,,,Gifts & Donations,,, 6666 GIFTS
   ,,,Groceries,,, 7777 GROCERIES
   ,,Dr. Sally Sue,,,, 5103 DENTAL
   ,,,Health & Wellness,,, 5102 PHYSICIAN
   ,,,Home,,, 9999 HOME
   ,,,Personal,,, 9998 PERSONAL
   ,,,Professional Services,,, 9997 PRO
   ,,,Shopping,,, 5203 SHOP
   ,,,,Payment,, 1700 PAY
   .Ed
 .Pp  .Pp
 to reflect that the default account used to make payments for the  Then
 account we are importing is 5678.  .Pp
   .Dl pta_import -I chase_credit chasedownload.csv
   .Pp
   outputs
   .Bd -literal
   20201109 PHYSICIAN 5102 3234 100.00 Dr. Joseph Schmoe
   20201109 DENTAL 5103 3234 183.00 Dr. Sally Sue
   20201108 SHOP 5203 3234 53.83 example.com
   20201104 PAY 3234 1700 75.43 Payment Thank You - Web
   .Ed
   .Pp
   Note that the selector for Dr\&. Sally Sue
   in the example configuration file comes before the
   Health & Wellness selector.
   Since the first match wins, transactions for Dr\&. Sally Sue
   can be classified with the DENTAL booking identifier,
   even though the bank's CSV file classifies
   these transactions as Health & Wellness.
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr pta-accounts 5 ,  .Xr pta-accounts 5 ,
 .Xr pta-journal 5 ,  .Xr pta-journal 5 ,
Line 95  Currently,
Line 292  Currently,
 has the following limitations:  has the following limitations:
 .Bl -dash  .Bl -dash
 .It  .It
 The CVS file's first line must contain a header.  Pattern recognition in the
   .Pa import/accountname.txt
   files is under continued development.
 .It  .It
 Only CSV files generated by Chase Bank are supported at this time.  User-defined configuration files are not currently
   supported.
 .El  .El
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.9
CVSweb