Media set requests

Last update: November 3, 2023

CREATED FOR:

  • Developer
  • User

Image Serving provides a mechanism for fetching a hierarchial text response (xml or json) which represents all of the resources and metadata associated with catalog::ImageSet for a particular record.

The viewers can use this mechanism to generate responses to inform the presentation of simple images, videos, video sets, swatch sets, spin sets, page sets (e-catalogs), and media sets.

Request syntax

The set response for a catalog::ImageSet can be retrieved by using the req=set modifier and referencing the catalog record id in the net path. Alternately, the image set can be specified directly in the URL by using the imageset= modifier. If the imageset= modifier is used to specify the imageset, the entire value should be enclosed in curly braces in order to escape the image set value and ensure that any included modifiers are not interpreted as being part of the URL query string.

Types of set responses

The set mechanism supports the following types of responses:

simple imagesAn image record without catalog::ImageSet defined.
simple videosA video record in the static content catalog.
swatch setsA set of items consisting of a reference to an image record and an optional separate reference to an image record used as a swatch.
hierarchical swatch setsA set of items consisting of a basic swatch item or a reference to a swatch set record.
spin setsA set of items consisting of a simple list of image IDs.
two-dimensional spin setsA set of items consisting of a simple image or a reference to a basic spin set.
page setsA set of items consisting of a list of up to three page images
media setsA set of items consisting of simple images, video sets, swatch sets, hierarchical swatch sets, spin sets, two-dimensional spin sets, page sets, and video assets. Each media set item can also contain an optional swatch.
video setsA set of items consisting of a list of simple videos.

Outer set type detection

When an req=set request is received, the type of response to generate is determined by the value of catalog::AssetType. If catalog::AssetType is not defined, then the response type is determined by the following rules:

  • If record is found in the image catalog AND catalog::ImageSet is defined

    • Assume e-catalog set if at least one entry in record Imageset field contains a colon
    • Assume media set if at least one entry in record Imageset field contains two semi-colons.
    • Assume image set if at least one entry in record Imageset field contains one semi-colon.
    • Assume spin set if no entry contains colon nor semi-colon but at least one entry contains referenced set or in-line set (this is a 2D spin set).
    • Assume unknown set if no entry contains colon nor semi-colon nor referenced set nor in-line set (i.e comma separated list of images).

  • If record is found in both image AND static content catalogs

    • Assume video if file extension is in following set: mp3, mp4, flv, f4v, swf, xml
    • Assumage image otherwise

  • If record is found in static content catalog but NOT in image catalog

    • Assume video if file extension is in following set: mp3, mp4, flv, f4v, swf, xml
    • Assume static otherwise

  • If record in found in image catalog but NOT in static content catalog

    • Assume image

  • If record is NOT found in the image catalog and NOT found in static content catalog

    • Assume file-based video if file extension is in following set: mp3, mp4, flv, f4v, swf, xml
    • Assume file-based image otherwise

In all cases, the resultant xml response conforms to the specified XML document with set root node corresponding to the detected type.

Inner set type detection

When the outer set is detected as type media set, the response contains a set of media set items corresponding to each media set entry in catalog::ImageSet. If the optional type parameter is specified for a particular media set entry, it is mapped to an output type according to the following table:

Input typeOutput type
imgimg
basicimg
advanced_imageimg
img_setimg_set
advanced_image_setimg_set
advanced_swatchsetimg_set
spinspin
videovideo
video_setvideo_set
staticstatic
ecatecat

If the optional type parameter for a particular media set entry is not specified or corresponds to an unsupported type, the media set item type is auto-detected using the same rules as were applied at the outer set level.

XML specification

The returned xml response conforms to the following specification:

http://crc.scene7.com/is-docs/examples/mediaset.dtd

LabelKey

The labelkey= modifier is used together with the catalog::UserDatafield to generate labels for images and swatches. The catalog:UserData field is parsed as a set of key/value pairs and the labelkey indexes in to this set to retrieve the value for the given key. This value is then returned in the l attribute for the s and i.

Enforced restrictions

In order to limit the size of the response and prevent self-referential issues, the maximum nesting depth is controlled by the server property PS::fvctx.nestingLimit. If this limit is exceeded, an error is returned.

In order to limit the size of the xml responses for large e-catalog sets, private metadata is suppressed for brochure set items according to the server property PS::fvctx.brochureLimit. All private metadata associated with the brochure is exported until the brochure limit is reached. After the limit is exceeded, private maps and userdata is suppressed and a corresponding flag is set to indicate which type of data was suppressed.

Nested media sets are not supported. A nested media set is defined as a media set which contains a media set item of type media set. If this condition is detected, an error is returned.