A script suitable for use as a back-end
for the CUPS
print server package is included with OpenGroupware Coils. This
back-end allows for queues to be created that perform HTTP PUT
requests to the server using configurable [per queue] paths. Using OpenGroupware Coils as a CUPS back-end easily enables client applications - and any application - to submit documents to work-flows or to store documents in project folders; the client simply prints via a print queue using a Postscript print driver and the CUPS server converts the document to PDF and pushes it to the server using the specified path. An example of this is a receipt printer - printing to a project document folder allows the document to be filed electronically; event driven document processing can then turn that same PDF around and submit it to an actual print queue if necessary.
Installation
To install the CUPs backend copy the “cups-to-ogo”
script to the appropriate back-end directory
on the print server and modify the permissions to permit the script
to be executed by the CUPs user [typically “lp”
or “root”].
This script does not require OpenGroupware
components or the OpenGroupware package to be installed on the print
server; all Python requirements are satisfied by the Python standard
library.
A tool such as “ps2pdf”
for converting Postscript to PDF will also be required; the script
assumes all content posted to the server is in PDF format. These
tools are generally already installed on any CUPS instance as CUPS
itself uses the ghostscript tool-chain for processing the content of
jobs.
When the script is executed by the CUPS server it
will log messages to the local syslog server under the LPR
facilty.
Configuration
[global]
uri=http://coils.example.com/
auth_mech=plain
ps2pdf=/usr/bin/ps2pdf
username=lp
password=theverysupersecretpassword
Text 2: An example cups-to-ogo.ini configuration file.
The script will attempt to read it's
configuration from an INI file located at
“/etc/cups/cups-to-ogo.ini”.
This location may be overridden by setting the environment variable
OGOCUPSCONFIGINI to the full path of
the required INI file; in order to be effective that environment
variable must be present in the environment of the CUPS server itself
– the environment of the server is inherited by all filters and
back-ends executed by the CUPS instance.
The INI file has a single global section. This
section specifies the URI of the OpenGroupware Coils server, the
authentication information , and the path to the postscript to PDF
conversion tool.
| Section | Parameter | Description |
|---|---|---|
global
|
uri
|
The base URI to the OpenGroupware COILS server. This URI should end with a “/”. |
global
|
auth_mech
|
The authentication mechanism to use when authenticating to the server; at this time only “plain” is supported. |
global
|
ps2pdf
|
The path to the executable postscript to PDF conversion tool. This tool must read its input from standard-input and write the converted document to standard-output. The tool must also be executable within the context of the CUPS server instance. |
global
|
username
|
If auth_mech is “plain” this specifies the user-name to use when performing BASIC authentication to the CUPS server. |
global
|
password
|
If auth_mech is “plain” this specifies the password to use when performing BASIC authentication to the CUPS server. |
Table 2: cups-to-ogo
configuration parameters supported in the cups-to-ogo.ini file.
Once the script has been installed and configured
it should be reported when listing the enabled CUPS back-ends using
the “lpinfo
-v” command on the print server. $ lpinfo -v
network ipp
network socket
direct scsi
network smb
network http
network lpd
network beh
network https
serial serial:/dev/ttyS0?baud=115200
serial serial:/dev/ttyS1?baud=115200
network cups-to-ogo
network socket://192.168.1.10
Text 3: Listing the available CUPS back-ends using "lpinfo -v"
Security
When defining a target to receive documents from
the CUPS integration do not forget to provision security ACLs of the
resource to make it accessible to the user which the back-end
authenticates as. In order to create a document within a folder the
CUPS context must be able to realize the folder's project and have
been granted list and insert permissions on the target folder.
It is recommended that a site create a specific
intranet account for use by the CUPS server for authenticating to the
OpenGroupware instance; this facilitates change control and auditing.
This special purpose account should be excluded from the
all-intranet team to avoid the possibility of inheriting additional
privileges. The CUPS server should never be provided with the
OpenGroupware administrative credentials or any credentials holding
an administrative or developer role. Authentication and access
control related to queuing jobs to queues defined on the CUPS server
is entirely an issue relating to the administration and configuration
of the CUPS instance,.
Creating Queues
Queues for pushing documents to the OpenGroupware Coils server can created using either the CUPS web interface or the
lpadmin command line tool.
The recommended CUPS print driver for all
cups-to-ogo
queues is “Generic
PostScript Printer Foomatic/Postscript”. The
postscript input job will be converted to PDF using the configured
conversion tool.
 |
| Illustration 1: CUPS web interface for creating a new print queue, via "Add Printer". |
In order to facilitate uploads into collections, via either AttachFS or WebDAV, as well as to allow capturing of all source meta-data replacement labels may be placed in the queue's URI. These strings have the form of “${label}” where label is the label name; each label in the queue's URI will be replaced with the appropriate value when a job is processed.
For example, to submit a print job [converted to a PDF document] to a work-flow route named “MailMeExample” and include the user name of the user who submitted the job to the CUPS server a queue URI of “cups-to-ogo://dav/Workflow/Routes/MailMeExample/input?username=${user}” would be used. The content of the print job would be the input message of the new process [instance of the work-flow route] and an XATTR named “username” would be created and attached to the process, the value of that XATTR would be the name of the username of the user who authenticated to the CUPS server.
For example, to submit a print job [converted to a PDF document] to a work-flow route named “MailMeExample” and include the user name of the user who submitted the job to the CUPS server a queue URI of “cups-to-ogo://dav/Workflow/Routes/MailMeExample/input?username=${user}” would be used. The content of the print job would be the input message of the new process [instance of the work-flow route] and an XATTR named “username” would be created and attached to the process, the value of that XATTR would be the name of the username of the user who authenticated to the CUPS server.
| Label | Description |
|---|---|
user
|
The user name of the context which submitted the print job [and potentially authenticated to the CUPS server]. This value will be URL quoted when the URL is constructed as user names may contain punctuation and whitespace. |
id
|
The job id assigned to the job by the CUPS server. |
title
|
The title attribute of the print job. This value will be URL quoted when the URL is constructed as job titles may contain punctuation and whitespace. |
guid
|
Generates a GUID string. This is intended for use-cases when a unique identifier is required within the PUT URI. |
Text 4: Substitution
labels supported by the cups-to-ogo backend.
Another common use for the CUPS backend is to
auto-file jobs to project folders. This can be accomplished by
setting the URI of the queue to an AttachFS target
indicating the folder in which to file the document. Note that
auto-filing, auto-printing, etc... are still effective – those
services do no consider the origin of the document. In order to file
a document into a project folder with an object id of 8,891,874 a
queue should be created with a URI of “cups-to-ogo://
attachfs/8891874/${guid}.pdf?mode=file”.
Note how this is a standard AttachFS URI; the file mode is
specified since we desire to create a document rather than an
attachment. A unique file name within the folder is required so the
guid
substitution label is used; from this URI a unique named document
will be created with a “pdf”
file extension.
cupsJobUser:
attribute: cupsJobUser
namespace: 57c7fc84-3cea-417d-af54-b659eb87a046
cupsJobTitle:
attribute: cupsJobTitle
namespace: 57c7fc84-3cea-417d-af54-b659eb87a046
cupsJobId:
attribute: cupsJobId
namespace: 57c7fc84-3cea-417d-af54-b659eb87a046Text 5: Example for adding the three CUPS meta-data related properties to the server's object property alias map.
Three object-properties have been defined in the
document management name-space intended to contain the CUPS
job information. To expose these properties for use in AttachFS URIs
add them to the property aliases map of the server. If the
properties are exposed as the default aliases the additional
meta-data can be recorded as object properties of the new document by
extending the URI of the previous example to “cups-to-ogo://attachfs/8891874/${guid}.pdf?mode=file&pa.cupsJobId=${id}&pa.cupsJobUser=${user}&pa.cupsJobTitle=${title}”.
Debugging
When the script is executed by the CUPS server it
will log messages to the local syslog server under the LPR
facilty.
Provided the back-end attempts to submit a job to
the OpenGroupware server – meaning the input for the filter was
processed successfully – the result provided back to the CUPS
server will depend upon the server's response to the HTTP PUT.
A success response, any of 200 [OK], 201
[Created], 202 [Accepted], 204 [No Content], or 301 [Moved
Permanently] result in a status 0 [OK]
to the CUPS server indicating the job was successfully processed and
the server may proceed to the next job.
A server response of 401 [Authentication
Required], 419 [Authentication Time Out], 511 [Network Authentication
Required], 496 [No Certificate], or 495 [Certificate Error] results
in a status of 2 [Authenticated Required2]
indicating to the CUPS server than an authentication or identity
related issue occurred. CUPS will place the job on hold and add the
“cups-held-for-authentication”
keyword to the “jobs-reasons”
CUPS job attribute.
If the server response indicates a temporary error
by responding with 423 [Locked (WebDAV)], 409 [Conflict], 408
[Request Timeout], or 429 [Too Many Requests (Back Off)] the CUPS
status of 6 [Retry]
will be returned. This status indicates the CUPS server may retry
the job at a later time; the server may still proceed to processing
the next job in the queue.
A response value of either 418 [Teapot] or 451
[Unavailable For Legal Reasons] will result in CUPS
status 5 [Cancel].
The CUPS server responds to a status 5 by automatically canceling
the current job and proceeding to the next job.
Any other server response, most notably a 404 [Not
Found] or 500 [Server Error], will return status 1 [Failed]
to the server. The server will respond to this status using the
queues defined error-policy attribute. Generally speaking the CUPS
default error policy is to change the queue to a paused state when
encountering a status 1 [Failed] response; a paused queue will
continue to accept jobs but will not attempt to submit them to the
backend.
