.\" $Id: pta_import.1,v 1.15 2020/12/11 20:08:21 freda Exp $
.\"
.\" Copyright (c) 2020 Freda Bundchen
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: December 11 2020 $
.Dt PTA_IMPORT 1
.Os
.Sh NAME
.Nm pta_import
.Nd print pta journal entries from bank CSV file input
.Sh SYNOPSIS
.Nm pta_import
.Fl I Ar accountname
.Op Ar file
.Sh DESCRIPTION
The
.Nm
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
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, and a configuration file
.Pa ./import/my_bank.txt :
.Pp
.Dl "$ pta_import -I my_bank downloaded.csv >> journal.txt"
.Pp
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-accounts 5 ,
.Xr pta-journal 5 ,
.Xr pta-glossary 7
.Sh BUGS
Currently,
.Nm
has the following limitations:
.Bl -dash
.It
Pattern recognition in the
.Pa import/accountname.txt
files is under continued development.
.El