The HCMS allows you to access storage items (files) of the current context asset.

Introduction

Asset storage items can be mapped in the schema by specifying the file type id using the property "cs:storage.item". They are typically mapped as a string either containing a link to the actual storage item content or the actual content itself.

With this mapping, storage items are always represented as a URL link that can be used to download the content, as a consequence the JSON type of the target property needs to be string. The following properties are used to configure the download link:

  • "cs:storage.item": String containing the storage item file type id (required)
  • "cs:link": Must be present to indicate that the download link is created. The value of the property is ignored and can be of any JSON type.

When reading the entity a URL pointing to the desired storage, an item is created by the Headless CMS. On creation or update, one of the following methods can be used to set the data:

  • A data: direct value URI (as specified by RFC 2397)
  • A URL (schema http or https) from which the Headless CMS downloads the binary data from. The content size for downloads as part of updates is limited to 200MB and transfer must be finished within two minutes. If the URL generated by the Headless CMS is send back to it during an update, the update of the storage item file is skipped.
  • A URL with the scheme formdata followed by a colon and the name of the part in the formdata/multipart request used to update the JSON entity

Example schema:

{
  "type" : "object",
  "properties" : {
    "image": {
        "type" : "string",
        "cs:storage.item" : "master",
        "cs:link" : ""
    }
  }
}

Example entity:

{
  "image": "http://localhost:8080/hcms/v1.0/entity/image/67982/storage/MDY3OTgyLzAvdGh1bWJuYWls"
}

Storage Item inline

With this mapping the storage item file content is mapped to a JSON type string encoded as base64. The following properties are used to configure it:

  • "cs:storage.item": String containing the storage item file type id (required)
  • "cs:$string_type": Must be set to base64

Example schema:

{
  "type" : "object",
  "properties" : {
    "image": {
        "type" : "string",
        "cs:storage.item" : "master",
        "cs:$string_type" : "base64"
    }
  }
}

Example entity:

{
  "image": "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKBAMAAAB/HNKOAAAAD1BMVEUAAAD///9fX18/Pz8fHx9fJrE7AAAACXBIWXMAAA7EAAAOxAGVKw4bAAAAIElEQVQImWNgwAEUgJiJQcGAmcGBQYEJxIOQBkARKAAAIiIBnc84ujIAAAAASUVORK5CYII="
}

XML Content

XML content can be directly mapped inside string typed properties. In addition, the XML can also be mapped split into several fragments.

  • "cs:storage.item": The storage item file type id, type string, (required)
  • "cs:$string_type": Specifies the presentation of the XML, (optional):
    • "plain": Plain unicode text
      • Default value
      • Mime type text/plain
      • Stored by using UTF-8 encoding
    • "xml": xml document
      • Mime type text/xml
  • "cs:storage.$path": Path inside the XML document
    • This declares that the value is not a complete storage item content, but just a single fragment of the XML document stored in the storage item
    • This is not Xpath, but just simple dot-separated list of element names from path to the final element
    • It cannot be used alone, always requires "cs:storage.$xml"
  • "cs:storage.$xml": ID of the defined XML structure
    • It can be used in combination with "cs:storage.$path" or alone

Special care is taken for XML documents, because they are used to store structured data and/or formatted text. A typical example is the article content, which contains both. The structure of the XML document must be defined beforehand (usually at the schema root) and referenced by its id. This allows the same XML structure to be used at different places.

Any level of JSON schema can contain the property "cs:$xml" with any number of new structures defined. The property name is the id of the structure, the value is a JSON object containing:

  • "initial": The initial content of the XML document ("empty" value)
    • required, it must contain at least the root element
  • "processor": Name of the processor used to convert XML between internal and external format
    • Currently there is only one possible value:
      • CenshareXLink: Converts all censhare URLs in XLinks to external (REST API) links and vice versa

A single XML document can be split into several fragments that are separately mapped to different JSON properties. Each of these properties specify the same "cs:storage.item" and "cs:storage.$xml", but different "cs:storage.$path". On export, the value is obtained by finding the element specified by path (and a property is missing if there is no such element). On import, this element is created and deleted (as needed) and its content is updated.

A fragment can be both plain and xml; in the former case, the text value of the element is actually used. In the latter case, the value in JSON string is the selected element with all the content. Note that on import, the name of the element is always the last element of the XML path; the name of the root element in JSON string is actually ignored.

Example schema:

{
  "type": "object",
  "cs:asset.type": "text.",
  "cs:$xml": {
    "article": {
      "processor": "CenshareXLink",
      "initial": "<article><title/><content/></article>"
      }
  },
  "properties": {
    "title": {
      "type": "string",
      "cs:storage.item": "master",
      "cs:storage.$xml": "article",
      "cs:storage.$path": "title",
      "cs:$string_type": "plain"
    },
    "content": {
      "type": "string",
      "cs:storage.item": "master",
      "cs:storage.$xml": "article",
      "cs:storage.$path": "content",
      "cs:$string_type": "xml"
    }
  }
}

Example entity:

{
    "title": "The Title",
    "content": "<content>Some <bold>content</bold></content>"
}

Storage Item Attributes

Some attributes of storage items can be mapped by using the property "cs:storage.$attribute" with the attribute name as a value. These mappings are only for reading, the values are always ignored on creation or update.

Available storage item attributes are:

  • mimetype: string, always available
  • filelength: integer, always available
  • hashcode: string, available for all types
  • width_px and height_px: integer, only for images
  • dpi: integer, only for images
  • colordepthbits: integer, only for some images
  • color: string, only for images, contains the color schema, typically "rgb"

Storage item attribute can either be used stand alone in conjunction with the property "cs:storage.item" to specify the storage item type:

{
    "mime": {
        "type": "string",
        "cs:storage.$attribute": "mimetype",
        "cs:storage.item": "master"
    }
}

Or it can be mapped together with a storage mapping in a common JSON object using the property "cs:storage.$value_property" on the storage item mapping:

{
    "storage": {
        "type": "object",
        "cs:storage.item": "master",
        "cs:storage.$value_property": "content",
        "cs:$string_type": "plain",
        "properties": {
            "content": {
                "type": "string"
            },
            "mime": {
                "type": "string",
                "cs:storage.$attribute": "mimetype"
            }
        }
    }
}

Media Mapping

The media mapping can be used to expose pre and on-demand generated variants of media content for consumption, e.g. image cropping variants, video size variants. This mapping is read only and does nothing on creation and update. Media mapping generates base URLs into the property that need to be extended by appending variant ids to create a URL that points to a variant. The admissible variants are part of the schema configuration. Since the mapping returns URLs the property type needs to be string and the media mapping is indicated with the child property cs:media of type object. This child object contains the variant ids as properties of type object in turn containing the configuration of the property. The variant type of the variant needs to be defined in the property "type".

Below is an example illustrating the abstract principle. Schema:

{
  "type" : "object",
  "properties" : {
    "image": {
        "type" : "string",
        "cs:media" : {
          "small" : {
            "type" : "…"
          },
          "large" : {
            "type" : "…"
          }
        }
    }
  }
}

It results in an entity like this:

{
  "image": "http://localhost:8080/hcms/v1.0/entity/image/68824/media/MDA2ODgyNC8w"
}

And the URLs of the actual variants are http://localhost:8080/hcms/v1.0/entity/image/68824/media/MDA2ODgyNC8w/small and http://localhost:8080/hcms/v1.0/entity/image/68824/media/MDA2ODgyNC8w/large.

Variant Type Storage

The variant type storage provides access to a storage item specified by the property storageKey.:

Example schema:

{
  "cs:media": {
    "preview": {
      "type": "storage",
      "storageKey": "preview"
    }
  }
}

Variant Type Dynamic Image

The variant type dynamic_image provides access to dynamically generated images. The dynamic image generation needs to be enabled in the global service configuration. It supports the following options:

  • aspectRatio: Aspect ratio for the generated image e.g. 16:9, value type string
  • with: Width for the generated image in pixel, value type integer
  • height: Height for the generated image in pixel, value type integer
  • cropKey: ID of the censhare image crop to use for the selection of the clipping, value type string
  • fileFormat: Format of the generated image (either "jpg" or "png"), value type string
  • quality: Quality for JPEG images as number between 0 and 100, value type integer
  • backgroundColor: Color to fill the transparencies when converting to JPEG images as hexdecimal RGB color (e.g. "#ff00ff"), value type string
  • watermarkAssetId: ID if an image asset to overlay as a watermark, value type integer
  • watermarkOpacity: Opacity of the watermark as floating point number between 0 and 1.0 inclusive, value type number

At least width or height must be specified and can be combined with aspectRatio. width, height and aspectRatio must not be specified together.

Example schema:

{
  "cs:media": {
    "medium": {
      "type": "dynamic_image",
      "width": 400,
      "asepectRatio": "4:3",
      "fileFormat": "jpg"
    }
  }
}

Asset elements

To handle assets with element structures e.g. PDFs with their individual pages, you can map elements to an array of objects using "cs:element.key": "actual". Currently this mapping is read only and just the actual elements are supported.

The mapping does not generate anything besides the empty object for each element. You need to either use the storage or media mappings mentioned above or use the element attribute. The element attribute mapping is configured using the property cs:element.$attribute with one of the following values:

  • kind the element kind, must be mapped to a JSON string
  • width_mm, height_mm, xoffsmm or yoffsmm the element geometry, must be mapped to a JSON number

Example schema:

{
  "type" : "object",
  "properties" : {
    "pages": {
      "type" : "array",
      "items": {
        "type": "object",
        "cs:element.key": "actual",
        "properties": {
          "preview": {
            "type": "string",
            "cs:storage.item": "preview",
            "cs:link": ""
          },
          "kind": {
            "type": "string",
            "cs:element.$attribute": "kind"
          }
        }
      }
    }
  }
}

Example entity:

{
  "pages": [
    {
      "preview": "http://localhost:8080/hcms/v1.0/entity/image/67982/storage/MDA2ODgyNS8x",
      "kind": "page"
    },
    {
      "preview": "http://localhost:8080/hcms/v1.0/entity/image/67982/storage/MDA2ODgyNS8y",
      "kind": "page"
    }
  ]
}