OpenGroupware Server Side Filters

OSSF [OpenGroupware Server Side Filter] modules provide for server-side transformations of work-flow messages and groupware documents via simple HTTP GET requests. Use of OSSF facilitates the simplification of client applications by allowing them to offline some complex and expensive operations to the OpenGroupware Coils server. OSSF modules can be used when requesting message or document content via either the AttachFS or the WebDAV presentation protocols.

All activation of OSSF is performed by adding parameters to the URL when retrieving the document or message. The URL parameter ossfchain activates a sequence of service-side filters. The value of this parameter is a comma-separated value of filters to activate; the filters will be daisy-chained in the order they are specified in the parameter. Parameters can be specified for each filter by passing those parameters in the URL prefixed by the appropriate filter's sequence in the OSSF chain. So a parameter of 0.name=value will pass the specified value as the parameter name to the first filter in the chain. A value of 1.name=value will do the pass the parameter to the second filter in the chain, and so on.

Even if only one filter is specified the parameters for that filter must be prefixed with "0.".

If a filter requires no parameters then no parameters need to be specified.

The sequence of filters may be important; in some cases a filter may change the MIME type of the data-stream and some filters will only accept input of an appropriate type. For example in count mode the json OSSF will change the MIME-type of the document from "application/json" to "text/plain" The pdftotext OSSF will also change the MIME type from "application/pdf" to "text/plain".

Currently implemented OSSF modules are:

• json - Supports counting, paginating, and filtering JSON content.
• pdftotext - Returns just the plain text portion of a PDF document.
• thumbnail - Resizes image content allowing the client to quickly download just a thumbnail of the specified document.
• autocrop - Reduce an image to the bounding box defined by the presence of an data; this removes the transparent margins around an image.
• __rml - Transform RML content into a PDF document.
• background - Overlay an image onto a solid background color of the same size as the image.
• markdown - Transform Markdown input into HTML.

Some OSSF Modules In Detail

The JSON OSSF

The json OSSF allows the client to request information about the contents of a JSON document or retrieve only a selected portion of the document. The primary use-case for the json OSSF is the instance where a client application needs to access a large JSON document; this can be slow and resource intensive if the client does not itself support streaming parsing or caching. With the json OSSF the client can paginate through the document, or filter it to just the desired records, just by specifying URL parameters.

The json OSSF can operate in one of two modes: count and pagination. Mode is specified via the mode parameter. In both modes the filter requires a path parameter; this value specifies the path to the elements of the JSON document that should either to be returned either to the client or counted.

No additional parameters are supported in count mode. The result of count mode is a "text/plain" response indicating the number of records found in the JSON document.

In pagination mode a range parameter is supported; if no range is specified pagination will always process the entire input stream. The value format for range is two integers separated by a hyphen, such as "1001-2000”,to indicate a specific range or a head / tail range such as "-1000” or "1001-” which will return all items up to or following the specified value. Ranges are inclusive; so a range of "1-5” will return five elements [if available].

The criteria parameter allows the data elements from the JSON input document to be filtered based upon value; all the elements matching the specified path are evaluated until the specified range is filled or the input stream is exhausted. Criteria is specified in the form of "key,value”. If the key can be interpreted as an integer value all list, dictionary and string elements matching the path are evaluated; the key is used as a key for dictionary values and as an index for list and string elements. If the key is not numeric only dictionary elements are evaluated. Numeric types, either integer or decimal, cannot be evaluated with the criteria parameter. All evaluation is based upon equality; comparisons to character or string types are case-sensitive. When specifying a key to act as an offset in a string or list the first character of the value is 0.

http://coils.example.com/dav/Workflow/Routes/ExampleRoute/17945730/output?ossfchain=json&0.mode=pagination&0.path=item&0.range=1-5&0.criteria=1,70801310'


The URL to filter the JSON output message of process 17945730; this will return the first five elements [range=1-5] of the outer-most list [path=item] when the second element of the list has the value “70801310” [criteria=1,70801310].

The pdftotxt OSSF

The “pdftotxt” filter will attempt to return all of the text from the PDF input stream. The output of this filter is primarily intended to facilitate searching. The output is unstructured text with a MIME type of “text/plain”.

The thumbnail OSSF

The thumbnail filter will modify either a PNG or JPEG image to be no larger than any of the dimensions specified; desired maximum width and height are specified using the width and height parameters, respectively. If either width or height are not specified then they default to the original width or height of the image, respectively. The aspect ratio of the image is preserved.

Thumbnails are generated using a high-quality anti-aliasing filter.

An input stream representing data other than a PNG or JPEG will raise an exception thus terminating the filter chain and returning an HTTP error code for the clients request.

http://coils.example.com/dav/Projects/Facility%20-%20TriadService%20Troy/Documents/Photos/Facility-1-OGo16235520.JPG?ossfchain=thumbnail&0.width=200&0.height=200Retrieve a 200x200 thumbnail of the specified groupware document.

In Closing

OSSF makes some tedious things easier for your custom web UI or other client.

If you have an idea or need for a useful OSSF join the coils-project mail list and let's discuss implementing it. Building an OSSF is almost as easy as using them. More detail regarding OSSF is available in WMOGAG (Whitemice Consulting OpenGroupware Adminsitrator's Guide).