version 1.4, 2020/11/12 14:26:51 |
version 1.5, 2020/11/14 22:15:56 |
|
|
.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 |
.Fl I Ar bankFormat |
.Fl I Ar accountname |
.Op Ar file |
.Op Ar file |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
|
|
.Ar file |
.Ar file |
argument is omitted, standard input is read instead. |
argument is omitted, standard input is read instead. |
.Pp |
.Pp |
.Ar bankFormat |
.Ar accountname |
is exactly one of |
is exactly one of |
.Pp |
.Pp |
.Bl -bullet -offset indent -compact |
.Bl -bullet -offset indent -compact |
Line 50 is exactly one of |
|
Line 50 is exactly one of |
|
.El |
.El |
.Pp |
.Pp |
and corresponds to an existing |
and corresponds to an existing |
.Pa import_ Ns Ar bankFormat Ns Pa .txt |
.Pa import_ Ns Ar accountname Ns Pa .txt |
file in the current directory. |
configuration file in the current directory. |
|
.Ss Configuration file format |
|
Each file of the form |
|
.Pa import_ Ns Ar accountname Ns Pa .txt |
|
in the current directory is a configuration file 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 |
|
Each file contains one line beginning with |
|
.Qq ACCOUNT |
|
and is followed by whitespace and then an account number. |
|
.Pp |
|
Each file contains lines of the form |
|
.Pp |
|
.Ar selector account_number booking_identifier |
|
.Pp |
|
The |
|
.Ar selector |
|
is a string consisting of regular expressions |
|
separated by commas. |
|
Its fields correspond to header fields in the financial |
|
institution's CSV file and is used to classify transactions |
|
that match the search pattern. |
|
The first selector that |
|
matches a transaction wins. |
|
.Pp |
|
The |
|
.Ar account_number |
|
corresponds to an account number in |
|
.Pa ./accounts.txt . |
|
The |
|
.Ar booking_identifier |
|
is defined by the user to classify |
|
the transaction. |
.Sh FILES |
.Sh FILES |
.Bl -tag -width Ds -compact |
.Bl -tag -width Ds -compact |
.It Pa ./import_capital_one_credit.txt |
.It Pa ./import_capital_one_credit.txt |
Line 64 account number from |
|
Line 104 account number from |
|
.Pa ./accounts.txt |
.Pa ./accounts.txt |
used by this account, as well as patterns used to map transactions to |
used by this account, as well as patterns used to map transactions to |
the correct account and booking identifier. |
the correct account and booking identifier. |
.Ss Defining the account number |
|
Each file must contain one line beginning with |
|
.Qq ACCOUNT |
|
and is followed by whitespace and then an account number. |
|
The account number corresponds to the account in |
|
.Pa ./accounts.txt |
|
for the imported account. |
|
.Ss Patterns in the import_bankFormat.txt files |
|
Each file contains lines of the form |
|
.Pp |
|
.Ar selector account_number booking_identifier |
|
.Sh EXIT STATUS |
.Sh EXIT STATUS |
.Ex -std |
.Ex -std |
.Sh EXAMPLES |
.Sh EXAMPLES |
Line 82 Add journal entries to a journal file using a CSV file |
|
Line 111 Add journal entries to a journal file using a CSV file |
|
a financial institution: |
a financial institution: |
.Pp |
.Pp |
.Dl "$ pta_import -I chase_credit chasedownload.csv >> journal.txt" |
.Dl "$ pta_import -I chase_credit chasedownload.csv >> journal.txt" |
.Ss A sample credit card purchase |
.Ss Account numbers in the configuration file |
Suppose a line in the |
The line |
.Pa chasedownload.csv |
|
file looks like |
|
.Pp |
.Pp |
.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07" |
.Dl ACCOUNT 3235 |
.Pp |
.Pp |
If the line matching the |
in the configuration file corresponds to a line such as |
.Qq Shopping |
|
category in the user's |
|
.Pa ./import_chase_credit.txt |
|
file is |
|
.Pp |
.Pp |
.Dl ,,,Shopping,,, 9996 SHOP |
.Dl 3235 L Capital One credit card |
.Pp |
.Pp |
then the |
in |
.Qq Shopping |
|
category defined by Chase is mapped to the user's |
|
.Qq SHOP |
|
booking identifier, and the user's account for shopping |
|
expenses is defined as |
|
.Qq 9996 |
|
in their |
|
.Pa ./accounts.txt . |
.Pa ./accounts.txt . |
.Pp |
.Pp |
We further assume in this example that the user has edited |
|
.Pa ./import_chase_credit.txt |
|
so that the line beginning with |
|
.Qq ACCOUNT |
|
contains the liability account they have defined for their Chase card |
|
in |
|
.Pa ./accounts.txt |
|
.Pp |
|
In this example, |
|
.Pa ./import_chase_credit.txt |
|
contains |
|
.Dl ACCOUNT 3234 |
|
.Pp |
|
Then |
|
.Nm |
|
prints |
|
.Pp |
|
.Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj" |
|
.Ss A sample credit card payment |
|
.Dl "10/27/2020,10/27/2020,Payment Thank You - Web,,Payment,1653.42" |
|
.Pp |
|
Suppose the user's |
|
.Pa ./import_chase_credit.txt |
|
file contains |
|
.Pp |
|
.Dl ,,,,Payment,, 1700 PAY |
|
.Pp |
|
which matches Chase's payment category to the user's asset account |
|
.Qq 1700 |
|
used to pay off the credit card. |
|
Then |
|
.Nm |
|
prints |
|
.Pp |
|
.Dl "20201027 PAY 3234 1700 1653.2 Payment Thank You - Web" |
|
.Ss Account numbers in the import_bankFormat.txt files |
|
For example, if |
|
.Pa ./import_capital_one_credit.txt |
|
contains |
|
.Pp |
|
.Dl ACCOUNT 1293 |
|
.Pp |
|
then there must be a corresponding entry in |
|
.Pa ./accounts.txt |
|
such as |
|
.Pp |
|
.Dl 1293 L Capital One credit card |
|
.Pp |
|
The description |
The description |
.Qq Capital One credit card |
.Qq Capital One credit card |
may vary, but in this example, the account numbers |
may vary, but in this example, the account numbers |
.Qq 1293 |
.Qq 3235 |
match, and the account type is |
match, and the account type is |
.Qq L |
.Qq L |
to indicate that it is a liability account. |
to indicate that it is a liability account. |
.Ss Patterns in the import_bankFormat.txt files |
.Ss Patterns in the configuration file |
Suppose |
Suppose |
.Pp |
.Pp |
.Dl ,,,Automotive,,, 1111 AUTO |
.Dl ,,,Automotive,,, 1111 AUTO |
|
|
with the |
with the |
.Qq Auto |
.Qq Auto |
booking identifier. |
booking identifier. |
|
.Ss A sample credit card purchase |
|
If |
|
.Pa chasedownload.csv |
|
file contains |
|
.Pp |
|
.Dl "10/26/2020,10/26/2020,example.com*asldfkj,Shopping,Sale,-17.07" |
|
.Pp |
|
and |
|
.Pa ./import_chase_credit.txt |
|
contains |
|
.Bd -literal -offset Ds |
|
ACCOUNT 3234 |
|
,,,Shopping,,, 9996 SHOP |
|
.Ed |
|
.Pp |
|
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 |
|
prints |
|
.Pp |
|
.Dl "20201026 SHOP 9996 3234 17.07 example.com*asldfkj" |
.Ss A complete example |
.Ss A complete example |
Suppose |
Suppose |
.Pa ./accounts.txt |
.Pa ./accounts.txt |
|
|
20201108 SHOP 5203 3234 53.83 example.com |
20201108 SHOP 5203 3234 53.83 example.com |
20201104 PAY 3234 1700 75.43 Payment Thank You - Web |
20201104 PAY 3234 1700 75.43 Payment Thank You - Web |
.Ed |
.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 257 has the following limitations: |
|
Line 272 has the following limitations: |
|
.Bl -dash |
.Bl -dash |
.It |
.It |
Pattern recognition in the |
Pattern recognition in the |
.Pa import_bankFormat.txt |
.Pa import_accountname.txt |
files is under continued development. |
files is under continued development. |
.It |
.It |
The only defined import formats are for Chase credit cards, |
The only defined import formats are for Chase credit cards, |
Capital One credit cards, and Optum Health Savings Accounts. |
Capital One credit cards, and Optum Health Savings Accounts. |
.It |
|
Note that the first pattern match wins in |
|
.Pa ./import_bankFormat.txt . |
|
In the complete example above, we put the line containing |
|
.Qq Dr. Sally Sue |
|
before the line matching the |
|
.Qq Health & Wellness |
|
category because we wanted to override the |
|
.Qq Health & Wellness |
|
category, and use the |
|
.Qq Dental expenses |
|
account instead. |
|
.El |
.El |