This article seeks to help you learn more about your AP/GL interfaces, which I'll refer to as "reformatters." The ultimate goal here is to equip you to be able to solve a host of reformatter-related issues which may come up over time. First, we will examine what reformatters are and how they work, and then provide some information to help you diagnose problems and find solutions to reformatter-related issues.
What is a reformatter?
Simply put, a reformatter is an executable file, compiled in VisualBasic, which transforms bills exported from EnergyCAP into a target format for a client's AP/GL system. For all clients, although the input for a reformatter will always be the same (bill export files from EnergyCAP), the output will almost always be completely different since each output format is tailored to the accounting system used by the client. Reformatters read EnergyCAP export files, store the values, and then make use of complex business logic to produce an output file which can then be imported into other information systems.
What do I need to make my reformatter work?
Although not all reformatters function the same way, there are some essential ingredients to each reformatter:
These are all the files necessary to set up the reformatter. They should all be in the same directory once installed. For example, you wouldn't want to have the reformatter executable in one directory and the INI file in another directory. This will cause the reformatter to crash. That's pretty straightforward.
- The reformatter itself: (an executable file)
- This will be run with a scheduled task or manual operation by the client
- The configuration INI file
- This should be located in the same directory as the reformatter
- You will need to reconfigure this file. More on this later.
- The *APEXPORT folder
- This is where the reformatter expects to find the ECAP export filels
- The name may vary depending upon the reformatter
Obviously, you'll need an input file as well to make this work, but for now, these files are all you need. There are some files that are created by the reformatter, which I will address shortly.
What does the reformatter do, exactly?
Again, although it depends upon the reformatter, there is probably a cluster of folders created in the reformatting process.
Some reformatters require these names (DONE, COMPLETED, etc.) to be the names of each folder. Other reformatters allow the output folders to be named anything you want, provided they are set correctly in the INI configuration file.
- This folder contains completed, reformatted output files.
- This folder contains a copy of the original EnergyCAP export file when the reformatter process is complete.
- This folder contains the process logs for each reformatting process.
- This folder will contain the output files during the process.
- If the reformatter finishes successfully, the output files in this directory will be moved to the DONE folder. Otherwise, they will remain in the TEMP folder.
The reformatter also creates a number of files when it runs, probably including (but not limited to) those mentioned below:
- Output file(s)
- Sometimes more than 1 is created in the output. It depends upon the reformatter.
- Can be found in whatever folder is specified in the DONE entry in the INI file.
- May be named according to the date-time of the reformatting process, or according to the name of the original ECAP export file.
- Process Log
- This is a line-by-line log of the reformatters actions performed upon each bill.
- Each line provides "clues" to be able to find the bill processed (e.g. total cost, account code, etc.).
- Can be found in whatever folder is specified in the LOG entry in the INI file.
- Error Log
- Contains a very short error message, usually programming-related if the reformatter encountered something it did not expect.
- This log is only created if there is was a problem during the reformatting process.
- Can be found in the same directory as reformatter.
What should I submit to Tech Support when I have a reformatter-related problem?
When you submit a reformatter-related ticket, we can provide you with the most detailed help if you provide us with the following:
- The design spec for the interface.
- The process log.
- The error log from the installation folder.
- A copy of the failed ECAP export file.
- A description of the problem/error as well as a description of how the reformatter is being executed.
- A copy of the partially-reformatted file from the TEMP folder.
- A screenshot of the command prompt output when running the reformatter, if there is any.
- Any documentation on how the reformatter works (e.g. readme, instructions, etc.).
Reformatter Troubleshooting Tips
Tip #1: Make sure your INI file is configured correctly.
Having a wrongly-configured INI file is the cause of much grief and frustration when setting up the reformatter for the first few times. To make this easier, take a look at this explanation of each entry in the INI file.
- APEXPORT - what's the name of the folder where the ECAP exports are?
- APEXPORTDIRECTORY - what directory is the APEXPORT folder located in?
- DONE - where should I create/place reformatted output files?
- TEMP - where should I create/place partially-reformatted output files?
- LOG - where should I create/place process log files?
- COMPLETED - where should I create/place processed EnergyCAP export files?
As I said, the biggest problem you'll face early on in a reformatter setup is correctly configuring this INI file! It's not that hard to edit, just open the INI file with Notepad or another text editor, copy and paste the directory paths you want into the corresponding entry values, and you'll be fine (as long as they are valid directory paths).
Tip #2: It's not always the reformatter's fault when something goes awry.
Some of you will have very simple reformatter processes while others will have very complex reformatter processes with lots of moving parts. Try to get a feel for how each piece of the reformatting process works. Ask yourself if any other scripts are involved. What does each script do? Do you have an automated scheduled task that runs the reformatter every so often? This is the type of detective work that is necessary to troubleshoot a reformatter issue, and more often than not, it's something that happened in EnergyCAP that has caused the issue at hand, not the reformatter.
If you have any reformatter-related questions that haven't been addressed in this article, please leave a comment and further articles may be forthcoming!
Keywords: reformatter, interface, broken, export, A/P, G/L, AP, GL, troubleshoot