Table of Contents
Using the Preview Agent to get pictures out of FotoWeb (Legacy)
29. April 2025
Table of Contents
The FotoWeb Preview Agent is available in FotoWeb with an API license. It provides functionality for dynamically resizing images and delivering them via HTTP in JPEG RGB format. It takes a search string as input and returns a preview in the requested size of the newest file in the search result.
Note: The Preview Agent API is deprecated and will be set to End of Life on July 1st, 2024.
If you have integrations that display previews in real-time, we recommend looking into alternative solutions such as obtaining temporary preview links from the RESTful API.
The Preview Agent is a legacy API for delivering image renditions. For performance reasons, the maximum rendition size is 2048 pixels. However, even if the original image is smaller than 2048 pixels, it will be scaled up to 2048 pixels if this size (or a larger size) is requested.
The preview agent is not designed for downloading original images, and attempting to use it for this purpose is not recommended. We recommend using the rendition API instead, as it can deliver the original file in its original size and format.
Accessing the Preview Agent
To access Preview Agent, you need to send a HTTP request to the following URL:
http://servername.domain.com/fotoweb/cmdrequest/rest/PreviewAgent.fwx
Enabling the agent
The agent must be explicitly enabled for a group of users on a site before it can be used.
Parameters
The Preview Agent receives all its parameters through the query string:
| Parameter | Description |
|---|---|
| sr | The search string to pass to the Index Manager. |
| sz | Used to specify the size of the returned preview, in pixels. |
| rs | Resolution (DPI) - must be between 1 and 1000. |
| pg | Page (e.g. of a PDF document) |
| qy | Preview quality from 40 (lowest) to 100 (highest). If no quality parameter is given or is outside the given range, the default quality will be delivered. (Configurable in the Operations Center) |
| ar | The id of the archive to search in. |
| username (optional) | The username of a valid user in FotoWeb with download access to the archive. |
| password (optional with username) | The password of the FotoWeb user. |
Authentication
The Preview Agent is integrated with the authentication scheme used by the other FotoWeb modules. This means that a user who has logged in to FotoWeb will be recognized by the Preview Agent (using the session cookie). It is, therefore, unnecessary to send a username and password explicitly through the query string if the user is already logged in. In this case, access control and event logging will happen using the user's credentials. It is possible to bypass this authentication by explicitly sending the credentials through the username and password parameters.
Return values
200 OK
The search returned one or more files and a preview of the newest file has been returned in the message body. The return type will be image/jpeg and the body will consist of binary image data.
400 Bad Request
A required parameter is missing or invalid.
403 Forbidden
The current user does not have download access in the specified archive.
404 Not Found
No files matched the specified search string.
500 Internal Server Error
The server was unable to communicate with Index Manager, or another error occurred.
Examples
Searching for 'auto' in archive 5004 at http://fotoweb.fotoware.com with a preview size of 400 pixels:
http://fotoweb.fotoware.com//fotoweb/cmdrequest/rest/PreviewAgent.fwx?ar=5004&sr=auto&sz=400
Preview delivered from the Preview Agent
Searching for 'soccer' in archive 5000 on the same server with a preview of 400 pixels. This archive is not open for guest users. Therefore, 'username' and 'password' parameters are supplied in the query string:
.jpg)
Preview delivered from the Preview Agent