swift-hcp-material
A command line tool to parse pricing from a pdf and generate an updated
csv file for House Call Pro.
General
This tool requires a little bit of familiarity with using a terminal /
command line.
Installation
This tool can be installed using Homebrew. Click the link
to install if you do not already have Homebrew installed.
Once you have brew installed, you can run the following command to install
this command line tool.
brew tap HHE-DEV/hcp-material && brew install swift-hcp-material
Homebrew manages installation, un-installation, updates, and shell completion.
The terminal application may have to be restarted for shell completion to take
effect.
Installation Notes
Currently there are pre-built binaries for macOS Big Sur and Monterey.
For macOS Monterey there are pre-built binaries for both arm and x86.
If you are not on macOS Big Sur or Monterey then a full version of
Xcode will be required
to build the binary using homebrew.
Usage
To check that installation was successful and the binary is found in your path.
You can use the following command.
hcp-material --help
This tool currently ships with two commands. Below is an explanation and usage
of the commands.
Update Command
This is the default command that is used. It requires a path to the pdf to
parse for the updated pricing and part numbers, a path to the csv file of your
current material pricing and part numbers, and a directory to write the new / updated
csv file to.
Click here to learn how to export your price book materials.
For this example we will say that the pricing is located at ~/Downloads/Pricing.pdf and
that our exported material csv is located at ~/Downloads/Materials.csv. We also want
to write the output file to the /tmp directory.
hcp-material --pdf ~/Downloads/Pricing.pdf --csv ~/Downloads/Materials.csv --output /tmp
You can also ignore parsing pages of the pdf, by adding one or more of the following
options to your command above.
--ignoring-page 1 --ignoring-page 2
Above would not parse / ignore pages 1 and 2.
After running the above command, then there should be an output file at /tmp/output.csv.
The updated pricing gets added as a new column / doesn’t over-write the existing cost
column, so that you can review / make changes prior to uploading back to House Call Pro.
Update Command Notes
The updated_cost column will always have a value in it, if the part number was not
found in the parsed pdf, then it will have the current cost of the item. This is so that
once you have reviewed and are happy with the values in the column, the whole column can
be copied / replace the entire cost column. You can then delete the updated_cost column
and the csv will be ready to be uploaded back to House Call Pro.
Click here to learn how to import materials back into your price book
Sometimes the update command will print an error like below.
CoreGraphics PDF has logged an error. Set environment variable "CG_PDF_VERBOSE" to learn more.
I have not found a way to remove this error, however it does not seem to affect the
updating process.
Parse Command
The tool also comes with a command to print / show what gets parsed from the pdf or csv.
CSV Parsing
An example of a csv parsing command. In this example we will parse and print a csv file
located at ~/Downloads/Materials.csv
hcp-material parse csv ~/Downloads/Materials.csv
PDF Parsing
There is currently only one parsing strategy, which looks for items / lines that end in a
value that can be parsed to a number (this is used as the updated cost). If a number is
able to be parsed from the end of the line, then it looks at the begining of the line, if the
beginning of the line can be parsed as a string, it uses that as the part number.
The part number can not contain any spaces or it will likely not parse the way that you are
expecting it to.
The parsed output of the pdf may contain some strange key / value pairs (for example it
will sometimes parse the page numbers and footer section). These extra key / value pairs
should not affect the updating process.
An example of the parse command is below. In this example we will parse and print the
results from a pdf located at ~/Downloads/Pricing.pdf
hcp-material parse pdf ~/Downloads/Pricing.pdf
You can also ignore parsing pages of the pdf, by adding one or more of the following
options to your command above.
--ignoring-page 1 --ignoring-page 2
Above would not parse / ignore pages 1 and 2.
Known Issues / Difficulties
The description field of an item is a known difficulty. We do our best to handle them, but some
items that are potentially problematic and cause failures are having quotes inside a description
field, or using a quote to represent inches in an item’s description.
Example
An item that has description of 6" duct upgrade will not properly parse / fail, but using a
description such as 6 in. duct upgrade will not be a problem.
Potential Work Around
If you have a lot of descriptions that are complex or have nested quotes, then you can open the
input csv file and remove the entire description column, then re-export to a new csv file, run
the update command, then add the column of descriptions back prior to importing to House Call Pro.
