EC Enterprise: Steps to Troubleshooting an EnergyCAP AP or GL Reformatter
Posted by Kurt Kroeker, Last modified by Kurt Kroeker on 18 May 2010 10:25 AM
Problem: My EnergyCAP AP or GL interface/reformatter is malfunctioning.
Solution: The following article should assist you in troubleshooting your own reformatter and give you a list of information items to deliver to Tech Support if you are unsuccessful.
Steps to Troubleshooting an EnergyCAP AP or GL Reformatter
Most EnergyCAP AP and GL interfaces (â€œreformattersâ€) are relatively standardized in their design and function, so this document should prove useful to EnergyCAP reformatter users for high-level troubleshooting. The purposes of this document are twofold: 1) to help users who are experiencing problems with their reformatter to troubleshoot their own issues and determine their sources before contacting Tech Support and 2) to provide a list of informational items for users to deliver to Tech Support if assistance is needed after following the steps outlined in this document.
1. VALIDATE THE APEXPORTDIRECTORY AND APEXPORT ENTRIES
Locate the directory in which the reformatter *.exe file has been installed. This directory should also contain a directory called APEXPORT. APEXPORT will contain bill export files from EnergyCAP. The *.ini file, located in the same directory as the AP reformatter *.exe file, contains important file paths instructing the reformatter where to find various files and folders.
Figure 1 shows an example of a reformatter installed in the C:\Temp\unifirstap directory.Â
Opening the *.ini file shows us the folder path to the reformatter install directory as well as the path to the APEXPORT folder. If the paths in the *.ini file do not match with the locations of the actual *.exe and *.ini files, the reformatter will not function properly. Figure 2 shows the correctly configured *.ini entries, with an explanation of each.
2. VALIDATE THE OUTPUT SUBFOLDER ENTRIES
If the APEXPORT and APEXPORTDIRECTORY entries are correctly configured, we will validate the subfolder entries next. During the reformatting process, there are four folders that are created within the APEXPORT directory as indicated in the *.ini file. Figure 3 shows a description of each folder:Â
As a brief reminder, the APEXPORT directory will contain the files that you export from EnergyCAP through either a scheduled automated process or manually by clicking on File > Export from within EnergyCAPâ€™s Workflow Manager. The EnergyCAP bill export file is usually named APEXPxxxx.txt where the xxxx represents a unique value (usually a timestamp, an ID, or a combination of data items) to ensure that no duplicates of the file are created. The export file contains bill data from EnergyCAP, rendered in a customized format. Figure 4 below shows a sample export file, while Figure 5 shows an example of the contents of the file. The bill export file file USUALLY contains lines that begin with L1, L2, L3, L4, or L5.Â
3. TEST THE REFORMATTER AND VIEW THE LOG FILE(S)
Once you have verified that your reformatter is installed in the proper directory, that the *.ini file reflects the correct folder values, and that a valid bill export file has been placed in the APEXPORT directory, launch the reformatter by double-clicking on the *.exe file.
The reformatter will begin to run. At this point, if the reformatter encounters a problem with the export file, a log file will be created in the same directory as the reformatter *.exe and *.ini; an error log file. If the reformatter partially processed the APEXPxxxx.txt file, then there will be another LOG file in the LOG folder. The LOG folder is located in the directory where the bill export file was placed. In this example, the LOG folder is located in the APEXPORT directory (see Figure 6 below).Â
As such, if the error LOG file appears, we may also look at the second LOG file (the process log) to understand WHERE the reformatter failed â€“ to see if it even processed PART of our APEXPxxxx.txt file or not. The error log tells us WHY and sometimes HOW the reformatter failed, and the process log tells us WHERE in the bill export file it failed.Â
See Figure 7 above to see the location of the LOG folder, where the process logs are created.
This second log fileâ€”the process logâ€”is important because it contains the bill by bill list of what the reformatter was SUCCESSFULLY able to process. Knowing this fact, we know that if we find the last bill that was successfully processed, we can open the APEXPxxxx.txt file, search for that bill line in the file, and know that the problem bill is located RIGHT AFTER that bill in the file. In other words, finding the last bill recorded in the process log allows up to pinpoint the exact bill which is causing the reformatter to fail. However, if this process log is empty or has no bill process records, then we must assume that there is a bigger problem with the reformatter or with the format of the APEXPxxxx.txt file.
Figure 8 below shows a process log in the LOG folder. Figure 9 shows an example of the contents of the process log, with an arrow pointing to the last successfully processed bill. The bill following 188768002_V1 would be the problem bill in this situation.Â
After we identify the last successful bill, we may open the bill export file file and look for that record, knowing that the very next bill contains the problem and is why the file didnâ€™t reformat properly. We find that it is the most simple to open the bill export file with a text editor (such as Notepad, ConTEXT, etc.) and use the â€œFindâ€ feature to locate the last successful bill, as demonstrated in Figure 10 below.Â
4. AFTER FIXING THE PROBLEM BILL, RE-EXPORT ALL THE BILLS FROM ENERGYCAP
Once we locate and fix the problem bill, it is best to re-export the bills from EnergyCAP. However, you MAY edit the export file directly IF you know what is wrong, but we do not recommend this except for experienced users.
To re-export the bills from EnergyCAP, we must first use the Administrator tool to un-export the bills we just exported. There is an article in the Online Help Manual showing how to un-export bills in EnergyCAP using the Administrator utility (http://help.energycap.com or http://help.energycap.com/help-plug-ins/administrator-5.0/unexporting-bills-by-batch-or-ap-export-date-range).
Once the bills are ready to be exported again, make sure you delete the existing APEXPxxxx.txt export file in your APEXPORT directory before you export the bills again using your established process (scheduled task or manual export). The existing file has errors, and the reformatter will try and process the problem file again if you donâ€™t delete it first.
5. REPEAT THE ABOVE TROUBLESHOOTING STEPS UNTIL THE REFORMATTER RUNS CORRECTLY
At this point, if you have successfully corrected the error in EnergyCAP, then when you re-export the bills, the reformatter should process the export file completely unless it encounters another problem bill. If another such error should surface, simply repeat the above steps.Â
Tech Support Assistance
If you are unable to resolve your problem using this guide, please contact Tech Support by logging on to Support Suite (http://support.energycap.com) and submitting a ticket through our online request form. When you do, please include the following information in a ZIP file as an attachment with your ticket.
Your ticket submission should include:
Revised 4/26/2010 by Kurt Kroeker