**README Error Handling**

# Contents

* [General error handling](#general)
    * [Invalid data](#invalid-data)
    * [Missing file](#missing-file)
* [Browser closed when still processing](#browser-closed)
    * [You don't know how to access the server with a FTP client](#browser-closed-without-ftp)
    * [You know how to access the server with a FTP client](#browser-closed-with-ftp)



# <a name="general"></a>General error handling

If you have an error not specially mentioned in this document then you should look carefully at the error message: In many cases it will point you into the right direction.


## <a name="invalid-data"></a>Invalid data
If you see for example the following error message:

**Invalid amount (< 0)** `2`, `Amount`, `-1`

The error message says that you should look at the field `Amount` of the `2`nd recipient, as the value of this field is `-1` and you have configured the QR bill processor in the section `Amount information` to use the `individual amount` of a recipient. Fix the amount of this recipient entry and go on.  
BTW: You will get this error immediately after uploading the `Recipients.csv`, at least if you have done the desired configuration **before** you have uploaded the `Recipients.csv`.


## <a name="missing-file"></a>Missing file
If you see something like that:

**File does not exist** //`[some path]`/qr-bills/data/`[some profile]`/input/`MailData.json`

whereby `[some path]` depends on your installation on your web server and `[some profile]` depends on the currently selected profile.

The error message says that the file `MailData.json` is missing. Upload the missing file and you are set.  
BTW: Errors like this one are easily detected by pressing `Dry run QR bills`.



# <a name="browser-closed"></a>Browser closed when still processing

Probably, you have accidentially closed the browser application during processing the QR bills.  
When you re-open the browser, you won't see any status, therefore you don't know nothing about the result of the QR bills processing.

But the QR bill processing on the server was going on and has possibly finished successfully, at least if you don't have too many recipients (depending on settings at your web hoster).


## <a name="browser-closed-without-ftp"></a>You don't know how to access the server with a FTP client

Just press the button `Dry run` in the web interface.  
You will see the remaining part of the messages of the last (crashed) run in the status section before you see the messages created by the new run by pressing the button `Dry run`. The new messages start at the line:

    *** Dry run *** (no PDFs stored, no e-mails sent)

Everything before this line, are messages from the last (crashed) run. Typically, the last lines before this line are:

    [ {profile} ] CONGRATULATIONS: All recipients successfully processed!
    Download protocol file.
    Download ZIP archive.

You see, the process was running to the end, and everything has been done although you have closed the browser.  
Download the protocol and make sure that every recipient has been processed. Download the ZIP archive and look at the included PDF files and the protocol.

Remark: 

- The text `{profile}` contains the name of the current profile.



## <a name="browser-closed-with-ftp"></a>You know how to access the server with a FTP client

To get the status you may visit the server with your FTP client.  

Typically in this case, you will see two files named `qr-bills.status` and `qr-bills.statusTracking` in the output directory that are used to communicate with the web interface. This temporary files are normally deleted by the web interfaces as soon as the processing has finished. Therefore, if you see these files then the web interface has crashed somehow (in this case because you have closed the browser). You may delete the two files, as we may consult other files to detect the status of the crashed run.

Look at the protocol `qr-bills-protocol.csv` located in the sub directory `YYYYMMDD-hhmmss` (where `[YYYYMMDD]` is the date, `hhmmss` the time when you have started the processing) in the output directory, and you will see that all the recipients were processed (listed in this file). In this directory you will also find all the PDF files created by this processing and a ZIP file `YYYYMMDD-hhmmss.zip` containing the protocol and the PDF files. 

Look at the log file `qr-bills_YYYYMMDD.log` (where `YYYYMMDD` is the current date) and you will see in the last few lines something like:

    YYYY-MM-DD hh:mm:ss.uuuuuu -> => Status: [ {profile} ] <strong>CONGRATULATIONS</strong>: All recipients successfully processed!
    YYYY-MM-DD hh:mm:ss.uuuuuu -> => Status: Download <a href="qr-bills-output/YYYYMMDD-hhmmss/qr-bills-protocol.csv">protocol file</a>.
    YYYY-MM-DD hh:mm:ss.uuuuuu -> Ignoring file '.', not adding to the ZIP archive.
    YYYY-MM-DD hh:mm:ss.uuuuuu -> Ignoring file '..', not adding to the ZIP archive.
    YYYY-MM-DD hh:mm:ss.uuuuuu -> ZIP file YYYYMMDD-hhmmss.zip contains 5 entries
    YYYY-MM-DD hh:mm:ss.uuuuuu -> => Status:  Download <a href="qr-bills-output/YYYYMMDD-hhmmss/YYYYMMDD-hhmmss.zip">ZIP archive</a>.
    YYYY-MM-DD hh:mm:ss.uuuuuu -> processing finished

where `YYYY-MM-DD` is the date, `hh:mm:ss.uuuuuu` is the time with microseconds.  
The text `[ {profile} ] CONGRATULATIONS: All recipients successfully processed!` and the two download links usually are shown in the status section of the web interface (that's why the texts are prefixed by `=> Status: `).  
You see, the process was running to the end, and everything has been done although you have closed the browser.

Remark: 

- The text `{profile}` contains the name of the current profile.
