How does Specify 7 work with the Web Asset Server?

Documentation Technical Docs
,
1

:book: This article describes how attachments in Specify are linked to attachments on the Web Asset Server / Attachment Server.

Linking an Attachment to the Source

When an attachment is uploaded to Specify, it is added to the database as a set of attachment records (in the attachment table and the joining attachment table, in this case collectionobjectattachment). In this example, I uploaded an attachment for a Collection Object with the catalog number 29499:

Puntius sophore (Hamilton, 1822) specimen
Puntius sophore (Hamilton, 1822) specimen1920×1188 137 KB

Citation: University of Kansas Biodiversity Institute: KUBI Ichthyology Collection KUBI Ichthyology Collection.
Occurrence Detail 656963381

You can build a simple query to show the attachment location, which is what Specify uses to look up the image on the asset server:

image
image2488×1316 273 KB

You can download this query here: CO Attachment.json (3.2 KB), (How to Import a Query)

See that the results show the original filename (the name given to the attachment before it was uploaded) and the actual attachment location (what it is named on the Web Asset Server):

image
image2710×288 48.8 KB

To find the attachments on the Web Asset Server, I need to now construct the appropriate URL to retrieve the image. In this case:

Technical Configuration

Specify builds URLs to obtain assets from the Web Asset Server differently depending on the context (either full resolution or thumbnail). The URLs are constructed with the following parameters:

  • Base URL (baseUrl): comes from the attachment server settings (e.g., https://assets-test.specifycloud.org) for the Specify 7 service (configured in Docker).
  • Collection (coll): the collection key for the database (e.g., sp7demofish) (configured in Docker).
  • Filename (filename): the server-side stored filename from each Attachment record (from the attachmentLocation field in the attachment record directly)
  • Type (type): T for thumbnails/previews used in the gallery, originals use O. If T, you must add the scale component.
  • Scale (scale): The size of the thumbnail to generate. Only used for thumbnails.
  • Download Name (downloadname): Optional, you can specify the download name for the image.

Putting it together, a URL like this will make it possible to download the original attachment at full resolution:

${baseUrl}/fileget?coll=${coll}&type=O&filename=${filename}

and this will get you the thumbnail:

${baseUrl}/fileget?coll=${coll}&type=T&filename=${filename}&scale=123

Optionally, you can specify a download name for the image which will be used automatically if the image is saved to the viewer’s computer. By default, this is the title value from attachment when accessed via Specify directly.

This works for both originals and thumbnails:

${baseUrl}/fileget?coll=${coll}&type=O&filename=${filename}&downloadname=${downloadname}

Find Attachments on the Asset Server

Once you have navigated to the directory the Web Asset Server is configured to grab attachments from, you should see two directories: originals and thumbnails

Note: If you have separated attachments into different directories based on the collection, there may be an intermediary directory with the name set here. This is not the configuration by default and is not generally recommended.

  • originals stores the full resolution, uncompressed images that were uploaded to Specify
  • thumbnails stores the “thumbnailified” images, usually named the same as the original with a suffix indicating the resolution (e.g. _123 in the filename indicates it is a 123x123 thumbnail).

For each original, there can be one or more thumbnails, depending on whether multiple sizes were created.

Originals

You can navigate into the originals directory, where you can find the attachment by simply searching for the attachmentLocation in the Attachment record from Specify (returned in the query results shown above):

example@assets-test:~/attachments/originals$ ls | grep sp64504250189672699317.att.JPG
sp64504250189672699317.att.JPG

Thumbnails

For thumbnails, they are generated on-demand by grabbing the original attachment and downsizing it to the resolution specified. If a thumbnail at that resolution already exists, it will simply display it. If not, it will create a new one.

[!example] Supported Filetypes
While Specify supports any filetype attachments, not all attachments can have thumbnails created for them. Currently, the following are “thumbnailable”:

  • JPEG
  • GIF
  • PNG
  • TIFF
  • PDF

If images have been imported in bulk using an external tool to Specify, thumbnails will not be generated until a user tries to view the thumbnail for that image in Specify. Every supported attachment uploaded directly in Specify will automatically have thumbnails created for them.

If I go to an asset server URL ending with 123 (e.g. filename=sp64504250189672699317.att.JPG&scale=123), it will generate a 123x123 thumbnail. If I modify the URL to end in 512 (e.g. filename=sp64504250189672699317.att.JPG&scale=256), it will generate a 256x256 thumbnail.

Now within the configured attachment directory for the collection/database, you can find both a thumbnail at 123x123 and 256x256:

example@assets-test:~/attachments/thumbnails$ ls | grep sp64504250189672699317
sp64504250189672699317.att_123.JPG
sp64504250189672699317.att_256.JPG

You can modify what size thumbnails are generated by updating the ‘Remote Preferences’ App Resource at the “Global Resources” level to change which is made automatically. For this change to go into effect, make sure to log out and back in. Please note that it might take some time to regenerate all thumbnails.

Modified attachment preview size
Modified attachment preview size1514×586 78.7 KB

attachment.preview_size=123 # this is the default
1 Like