Accounting for Fiery Prints Accurately on PaperCut
===================================================

Background
----------
Unlike most standalone printers, printers with Fiery controllers have the ability to hold and
reprint jobs and to change print job settings after jobs are submitted.

This poses problems for PaperCut print job accounting that records print jobs at job submission
time.


fiery_papercut.exe
------------------
fiery_papercut.exe is a program that tracks job print on Fierys and logs them on PaperCut.

It continually monitors a specified list of Fierys and records prints under a PaperCut Shared
Account named "Fiery.account". The username the job is logged under is the name of the user
recorded by the Fiery.


Requirements
------------
PaperCut version 13 or later is recommended. fiery_papercut.exe will probably work with older
versions of PaperCut but has only been tested on version 13 and later.

Fiery system FS100 or later. If you have a Windows Fiery System 9 Rel2 or later then you must
download "Fiery Extended Applications Package 4.0" from http://w3.efi.com/ .


Limitations
-----------
fiery_papercut logs the jobs performed on the Fiery into the PaperCut database. It logs the jobs
under the username of the user recorded on the Fiery and under the PaperCut shared account
"Fiery.account".

These jobs are logged after the job is printed by the Fiery. For this reason it is not
possible for the "Account Selection" or other PaperCut print popups to be triggered for
Fiery jobs.


Setting up
----------
1. Copy the contents of the zip file to a directory on your computer. This must be
    a Windows PC, but can be a different computer to the PaperCut Server.

2. Login to the PaperCut application.

    Turn off tracking of the Fiery controlled printers in PaperCut.

        In the PaperCut web admin interface, go to

            Printers : <your printer> : Advanced Charging

        and set the cost per page to 0.

    (This will prevent double-charging of prints).

   NOTE: If you are running fiery_papercut on a different computer to the PaperCut server, you
         will need to open up access of the PaperCut API to the remote fiery_papercut. To do this,
         go to the Options->Advanced tab, and edit the 'Security->Allowed XML Web Services callers'
         to include the IP address of the computer running fiery_papercut.

3. Create a CSV file of IP addresses, usernames and passwords of the Fiery controlled printers.

    The username and password are the Fiery username and password you use to log in to your
    Fiery from Command Workstation, the Fiery printer web interface or other Fiery clients.

    Each row is <IP address>,<user name>,<password>
    e.g.
        191.61.23.42,admin,La331e
        191.61.23.43,John,Fl1pper
        191.61.23.44,Betty,Sk1ppy

    Save this as fierys.csv (or any name that you choose). See example_fierys.csv for an example
    of such a CSV file.

4. Open a command prompt and cd to the directory where you copied the contents of the zip file in
   step 1 above.

5.  Run the following command line.

    fiery_papercut.exe -L fierys.csv -p <PaperCut admin password>

    NOTE: If running the Fiery tool on the different machine to the PaperCut server you must
          specify the network address/IP of the PaperCut server using the -s parameter.  e.g.

    fiery_papercut.exe -L fierys.csv -s <papercut network address> -p <PaperCut admin password>


Running
-------
The Fiery jobs tracked so far can be seen in the PaperCut web admin interface.

    - Jobs are logged as print jobs in the Shared Account "Fiery.account"
    - Each job is stored with a comment that contains the Fiery id.
    - The printer name and user name for each job are read from the Fiery the
       job was printed on. They will usually match the printer name and user
       name for the same printer and user on PaperCut but this is not guaranteed.


Debugging
---------
NOTE: Please do not delete or modify the papercut.fiery.log file. It is used for debugging.

If fiery_papercut.exe does not work then the first thing to try is connecting to one Fiery at a
time.

Run the following command line for each of your Fierys. The -y option will perform a dry run. It
will read job records from the Fiery but not write those records to PaperCut. This will check if
fiery_papercut.exe works with that Fiery.

  fiery_papercut.exe -S <fiery ip> -U <fiery user> -P <fiery password> -y

- If there are error messages for a given Fiery then fiery_papercut.exe will need to be updated to
  work with that Fiery.

- If fiery_papercut does not write error messages for any Fiery then the problem you are having is
   most likely to do with PaperCut setup. In this case re-run fiery_papercut.exe with the
   same command line as before but add -d to the command line. (There needs to be a space before the
   -d.) e.g

  fiery_papercut.exe -L fierys.csv -p <PaperCut admin password> -d

In all the above cases, diagnostics will be written to the papercut.fiery.log file in the
the directory where you ran fiery_papercut.exe

Send papercut.fiery.log to support@papercut.com and explain what you were trying to do and the
approximate times you did it.

The PaperCut developers should be able to fix most of these cases quickly.


Internals
---------
    The Fierys currently being tracked are in the PaperCut Config Editor.

    You can find the PaperCut config editor in the PaperCut web admin interface

        Options : Advanced : Config editor (advanced)

    - Search for "fiery" (without the quotes) in Quick find
    - Name "fiery.list" has a list of IP addresses of Fierys being tracked.
    - Each Fiery being tracked has an entry "fiery:<IP>" with a value that looks like
      {'username': 'admin', 'password': 'secret', 'max_id': 4}
        The username and password values (admin and secret in this example) are
        used to log in to the Fiery. max_id is the maximum Fiery job id for this
        Fiery recorded in the PaperCut Job Log.
        NOTE: Sometimes you will see a value like
            {'username': 'admin', 'password': 'secret', 'max_id': 4, pending_max_id: 7}
        This means that this script stopped while it was recording Fiery jobs
        with ids in the range 5-7 on PaperCut.
        If you ever see this then you will need to
        - check which of the jobs in the range 5-7 have been recorded in the
          PaperCut Job Log. You can find this by sorting PaperCut Shared Account
          "Fiery.account" Job Log by  date and checking the comment of the latest job.
        - set max_id to the highest Fiery id
        - delete the pending_max_id
        - e.g. if the highest Fiery id logged is 6 then you would set the above 
              value to {'username': 'admin', 'password': 'secret', 'max_id': 6}

Logging
-------
All of fiery_papercut's activity is logged in papercut.fiery.log.

Advanced
--------
Type the following command line to see all the advanced options:

  fiery_papercut.exe -h

Some of these that you may find useful are

    -y
    -d
    -v

    PaperCut tech support may ask you to use these options. They make fiery_papercut.exe
    give detailed information about how it is interacting with PaperCut and the Fierys
    it is connected to.

    -a <account name>

    This sets the PaperCut shared account name for Fiery prints to <account name>
    instead of its default "Fiery.account"

NOTE!
-----
    The Fiery passwords are stored in the PaperCut config editor. If you do not want to store
    passwords then you should not run fiery_papercut.


Reference
---------
http://www.papercut.com/kb/Main/RIPDevices 

