censhare XSLT commands and extensions

XSLT commands are an extension to XSLT to access the censhare server Java-API.

Introduction

Basic structure:

<cs:command name="[name of the command]" returning="[result variable]">
    <cs:param name="[name of the parameter]" select="[value of the parameter]"/>
    <cs:param name="[name of the parameter]" select="[value of the parameter]"/>
</cs:command>

Results can be collected in 3 ways

• Using the "returning" attribute (define variable with given name and store result in variable):

<xsl:variable name="resultAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.CloneAndCleanAssetXml" returning="resultAssetXml">
    <cs:param name="source" select="asset"/>
</cs:command>

• Using the result of the "cs:command" function

  <xsl:variable name="resultAssetXml">
     <cs:command name="com.censhare.api.assetmanagement.CloneAndCleanAssetXml">
         <cs:param name="source" select="asset"/>
     </cs:command>
  </xsl:variable>

• Using the "dest" parameter (not available for every command)

  <cs:command name="com.censhare.api.io.WriteXML">
     <cs:param name="source" select="$metaDoc"/>
     <cs:param name="dest" select="concat($out, 'EPUB-Debug.xml')"/>
  </cs:command>

Asset management commands

The asset management commands provide the basic asset management functionallity:

• Check in new asset
• Check out asset
• Check in asset
• Check out abort asset
• Update asset
• Update asset with lock
• Commit or flush transaction
• Clone and clean asset XML (allows to copy/clone assets)
• Delete asset

Check in new asset (com.censhare.api.assetmanagement.CheckInNew)

Creates asset from the given XML and performs a check-in of this new asset (with version 1) then. The XML of the checked-in asset is stored in a "returning" attribute or is returned directly.

Parameters

• source The input XML to construct and check in the new asset of (required).

Returns: The corresponding XML of the checked in new asset. If a "returning" attribute is present, the result is stored in a variable with the given name and can be used afterwards. It's also allowed to omit the "returning" attribute. In that case the result document is directly returned by the cs:command function.

Examples:

<xsl:variable name="assetXml">
    <asset name="First test asset" type="temp."/>
</xsl:variable>
<xsl:variable name="resultAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.CheckInNew" returning="resultAssetXml">
    <cs:param name="source" select="$assetXml"/>
</cs:command>

<xsl:variable name="resultAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.CheckInNew" returning="resultAssetXml">
    <cs:param name="source">
        <asset name="First test asset" type="temp."/>
    </cs:param>
</cs:command>

<xsl:variable name="cleanedAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.CloneAndCleanAssetXml" returning="cleanedAssetXml">
    <cs:param name="source" select="$assetXml"/>
</cs:command>
<cs:command name="com.censhare.api.assetmanagement.CheckInNew" returning="checkedInAssetXml">
    <cs:param name="source" select="$cleanedAssetXml"/>
</cs:command>

Check out asset (com.censhare.api.assetmanagement.CheckOut)

Checks out the asset corresponding to the given source. The XML of the checked out asset is stored in a "returning" attribute or is returned directly.

Parameters

• source The asset XML to check out the asset of or the asset id of the corresponding asset (required).

Returns: The corresponding XML of the checked out asset. If a "returning" attribute is present, the result is stored in a variable with the given name and can be used afterwards. It's also allowed to omit the "returning" attribute. In that case the result document is directly returned by the cs:command function.

Example

<xsl:variable name="resultAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.CheckOut" returning="resultAssetXml">
    <cs:param name="source">
        <asset id="211421" currversion="0"/>
    </cs:param>
</cs:command>

<cs:command name="com.censhare.api.assetmanagement.CheckOut" returning="checkedOutAssetXml">
    <cs:param name="source" select="10000"/>
</cs:command>

Check in asset (com.censhare.api.assetmanagement.CheckIn)

Creates an asset from the given XML and performs a check-in of this existing asset using the supplied metadata. The XML of the checked-in asset is stored in a "returning" attribute or is returned directly.

Parameters

• source The asset XML to construct and check in the asset of or the asset id of the corresponding asset (required).

Returns: The corresponding XML of the checked in asset. If a "returning" attribute is present, the result is stored in a variable with the given name and can be used afterwards. It's also allowed to omit the "returning" attribute. In that case the result document is directly returned by the cs:command function.

Example

<xsl:variable name="resultAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.CheckIn" returning="resultAssetXml">
    <cs:param name="source">
        <asset id="211421" currversion="0"/>
    </cs:param>
</cs:command>

Check out abort asset (com.censhare.api.assetmanagement.CheckOutAbort)

Aborts the check out of the asset corresponding to the given source.

Parameters

• source The asset XML to check out abort the asset of or the asset id of the corresponding asset (required).

<xsl:variable name="resultAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.CheckOutAbort" returning="resultAssetXml">
    <cs:param name="source">
        <asset id="211421"/>
    </cs:param>
</cs:command>

Update asset (com.censhare.api.assetmanagement.Update)

Update asset using given asset XML. This doesn't create a new asset version but otherwise allows to change any asset metadata, even change storage items (files).

Parameters

• source The asset XML to construct and update the asset of or the asset id of the corresponding asset (required).

Returns: The corresponding XML of the updated asset. If a "returning" attribute is present, the result is stored in a variable with the given name and can be used afterwards. It's also allowed to omit the "returning" attribute. In that case the result document is directly returned by the cs:command function.

<xsl:variable name="sourceAssetXml">
    <xsl:copy-of select="asset"/>
</xsl:variable>
<xsl:variable name="resultAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.Update" returning="resultAssetXml">
    <cs:param name="source">
        <asset>
            <xsl:copy-of select="$sourceAssetXml/asset/@*"/>
            <xsl:attribute name="name" select="'Test'"/>
            <xsl:copy-of select="$sourceAssetXml/asset/node()"/>
        </asset>
    </cs:param>
</cs:command>

Update asset with lock (com.censhare.api.assetmanagement.UpdateWithLock)

This command tries to construct an asset from the given XML and to lock and update this asset. The XML of the updated asset is stored in a "returning" attribute or is returned directly.

Parameters

• source The asset XML to construct, lock and update the asset or the asset id of the corresponding asset (required).

Returns: The corresponding XML of the updated asset. If a "returning" attribute is present, the result is stored in a variable with the given name and it can be used afterwards. It is also allowed to omit the "returning" attribute. In that case the resulted document is directly returned by the cs:command function.

<cs:command name="com.censhare.api.assetmanagement.UpdateWithLock" returning="updatedAssetXml">
    <cs:param name="source" select="10000"/>
</cs:command>

Commit or flush current transaction (com.censhare.api.assetmanagement.CommitOrFlush)

This command allows to commit the current transaction and it can reset the PersistanceManager ("flush"), whenever needed. A typical use case for commiting is to ensure that assets which were just created can be found using a CBD search in a subsequent part of the XSLT script. A typical use case for flushing is to free up memory in long running XSLT scripts, e.g. setting up assets from a flat recored set.

Parameters

• flush Boolean value which indicates whether flush should be performed.

<cs:command name="com.censhare.api.assetmanagement.CommitOrFlush">
    <cs:param name="flush" select="false()"/>
</cs:command>

Clone / duplicate asset (com.censhare.api.assetmanagement.CloneAndCleanAssetXml)

Tries to construct an asset from the given XML, clones this asset and does some cleaning of the asset. The cleaning includes the deleting of feature nodes with key censhare:uuid, all production flags, interface stuff and all parent asset element relations, for example. The corresponding XML of the resulting asset is stored in a "returning" attribute or is returned directly. Frequently this command is followed by a check-in new.

Parameters

• source The input XML to construct the asset of (required).

Returns: The corresponding XML of the resulting asset. If a "returning" attribute is present, the result is stored in a variable with the given name and can be used afterwards. It's also allowed to omit the "returning" attribute. In that case the result document is directly returned by the cs:command function.

<xsl:variable name="resultAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.CloneAndCleanAssetXml" returning="resultAssetXml">
    <cs:param name="source" select="asset"/>
</cs:command>

Clone / duplicate asset structures (com.censhare.api.assetmanagement.DuplicateAsset)

This method is designed for cloning asset structures. It must be called for every asset of the structure. The IDs of the duplicated assets are stored in the context, this is necessary for cloning relations properly. As a side effect - for duplicating another asset structure the context must be recreated.

Parameters

• source The input XML to construct the asset of (required).

Returns: The corresponding XML of the resulting asset. If a "returning" attribute is present, the result is stored in a variable with the given name and can be used afterwards. It's also allowed to omit the "returning" attribute. In that case, the result document is directly returned by the cs:command function.

<xsl:variable name="resultAssetXml"/>
<cs:command name="com.censhare.api.assetmanagement.DuplicateAsset" returning="resultAssetXml">
    <cs:param name="source" select="asset"/>
</cs:command>

Delete asset (com.censhare.api.assetmanagement.Delete)

Deletes the asset corresponding to the given source and with the given deletion state.

Parameters

• source The asset XML to check out abort the asset of or the asset id of the corresponding asset (required).
• state The deletion state to delete the asset with. This parameter is optional. If omitted the asset is proposed for deletion. The following deletion states are available:
  • proposed (mark as proposed for deletion)
  • none (no/unmark deletion state)
  • marked (mark for deletion)
  • physical (immediately delete)

<cs:command name="com.censhare.api.assetmanagement.Delete">
    <cs:param name="source" select="123456"/>
    <cs:param name="state" select="'proposed'"/>
</cs:command>

Additional examples for asset management tasks

Add asset to basket

<!-- get basket -->
<xsl:variable name="basketAsset"
    select="cs:asset([@censhare:asset.type='order.shoppingbasket.'
    and @censhare:asset.wf_target=system-property('censhare:party-id')]"/>
<!-- create relation to basketAsset -->
<xsl:if test="$basketAsset and empty($basketAsset/child_asset_rel[@key='user.'
        and @child_asset=current()/@id])">
    <xsl:variable name="resultAssetXml"/>
    <cs:command name="com.censhare.api.assetmanagement.Update" returning="resultAssetXml">
        <cs:param name="source">
            <asset>
                <xsl:copy-of select="$basketAsset/@* | $basketAsset/node()"/>
                <child_asset_rel key="user." child_asset="{@id}"/>
            </asset>
        </cs:param>
    </cs:command>
</xsl:if>

Remove asset from basket

<!-- get basket -->
<xsl:variable name="basketAsset"
    select="cs:asset( [@censhare:asset.type='order.shoppingbasket.'
    and @censhare:asset.wf_target=system-property('censhare:party-id')]"/>
<!-- remove relation from basketAsset -->
<xsl:if test="$basketAsset">
    <xsl:variable name="resultAssetXml"/>
    <cs:command name="com.censhare.api.assetmanagement.Update" returning="resultAssetXml">
        <cs:param name="source">
            <asset>
                <xsl:copy-of select="$basketAsset/@*
                    | $basketAsset/node()[not(node-name(.)='child_asset_rel'
                    and @key='user.' and @child_asset=current()/@id)]"/>
            </asset>
        </cs:param>
    </cs:command>
</xsl:if>

Transformations

Asset transformation (com.censhare.api.transformation.AssetTransformation)

Executes an asset transformation using an XSLT stored as resource asset selected by resource-key.

Parameters

• source The input XML to be transformed as XML, URL, file locator, or storage item (required)
• dest The file locator of the destination file where the result of the transformation should be stored (optional) If this parameter is missing, the result is returned as a result of this cs:command function
• stylesheet Source of the stylesheet XML as XML, URL or file locator (required) or
• key Key to the stylesheet resource asset (required)
• xsl-parameters Additional parameters, which are passed directly to the XSL transformation and are not interpreted by the command itself (optional). They can be referenced inside the XSLT by their names as specified in the cs:param's name attribute.
• returning Result of the transformation (optional)

Returns: The result of the transformation as XML. If a "returning" attribute is present, the result is stored in a variable with the given name and can be used afterwards. It's also allowed to omit the "returning" attribute. In that case, the result document is directly returned by the cs:command function.

Example

<!-- Using stylesheet -->
<cs:command name="com.censhare.api.transformation.XslTransformation" returning="dummy">
    <cs:param name="stylesheet" select="concat($config, 'modules/content_export/stylesheets/export.xsl'"/>
    <cs:param name="source" select="$chapterAsset/storage_item[@key='master'][1]"/>
    <cs:param name="dest" select="concat($parentDir, 'chapter-', $chapterAsset/@id, '.xhtml')"/>
    <cs:param name="xsl-parameters">
      <cs:param name="format" select="'xhtml'"/>
    </cs:param>
  </cs:command>

<!-- Using resource asset key -->
<cs:command name="com.censhare.api.transformation.AssetTransformation" returning="dummy">
    <cs:param name="key" select="'censhare:epub-chapter'"/>
    <cs:param name="source" select="$chapterAsset/storage_item[@key='master'][1]"/>
    <cs:param name="dest" select="concat($parentDir, 'chapter-', $chapterAsset/@id, '.xhtml')"/>
    <cs:param name="xsl-parameters">
        <cs:param name="format" select="'xhtml'"/>
        <cs:param name="debug" select="true()"/>
   </cs:param>
</cs:command>

Image transformation (com.censhare.api.transformation.ImageTransformation)

Parameters

• source The input source (image) to be transformed (required). It must reference a storage item or a file
• dest The file locator of the destination file where the result of the transformation should be stored (required). It must reference a file in a virtual file system. The file extension is used to define the target image format (e.g. "a.jpg")
• image-transformation XML node, which contains the image transformations and transformation attributes (required)

Operations:

• Scale: <scale width="220" height="220"/>
• Crop: <crop x="100" y="20" width="220" height="220"/>
• Rotate: <rotate degree="90"/>
• Convert: <convert/> Format conversion (Typically used together with any other operations, e.g. convert color space. Target format is detected by extension of the output file.)
• OPI: <opi/> Create lowres OPI (target format is detected by extension of the output file)
• Flip horizontally: <fliph/>
• Flip vertically: <flipv/>
• Overlay: <overlay overlay-image="cs:file-locator($overlayAsset/storage_item[@key='master'])" opacity="50" gravity="center" tile="false" extra-opts=""/>
• Video frame: <videoframe timecode="0:0:0.000"/>
• Clip: <clip/> (Use an embedded clipping path to produce a new image with a transparent alpha channel)
• Frame: <frame upscale="false" width="100" height="100" gravity="center" clip="false"/> (Scale input image proportionally to fit into a frame of a given width and height):

Example

<cs:command name="com.censhare.api.transformation.ImageTransformation">
    <cs:param name="source" select="$currentAsset/storage_item[@key='master']"/>
    <cs:param name="dest" select="concat($dir, 'imageTransformation/image.jpg')"/>
    <cs:param name="image-transformation">
        <image-transformation>
            <operations>
                <crop x="100" y="20" width="220" height="220"/>
                <rotate degree="90"/>
                <clip/>
            </operations>
            <attributes sharpen="true" out-jpeg-quality="100" out-color="cmyk"/>
        </image-transformation>
    </cs:param>
</cs:command>

Barcode transformation (com.censhare.api.transformation.BarcodeTransformation)

Parameters

• source The input source (any asset) to be transformed (required).
• destination The file locator of the destination file where the result of the transformation should be stored. It must reference a file in a virtual file system (required) (see createVirtualFileSystem).
• barcodeTransformation XML node, which contains the barcode transformations (required).

Parameter values are typically taken from a "module/configuration" asset below the transformation asset itself.

Possible values and interpretation of values:

• type ean8, ean13, qr (further types possible but not implemented yet) file-format: pdf, eps, svg, png
• height mm value
• module-width space between "bars", leave empty for an automatic default value
• margin mm value
• orientation 0, 90, 180, 270 (degrees rotation)
• font font name must be available to the JVM at server startup time
• font-size pt value
• qr-error-correction empty, H, L, M, Q
• dpi dots per inch for rasterized image formats
• antialias true, false for font antialiasing

The source value for the barcode itself is evaluated from the XPath expression within the configuration module, namely its asset_feature 'censhare:barcode.meta', e.g. asset_feature[@feature='censhare:barcode.value']/@value_string

 <cs:command name="com.censhare.api.transformation.BarcodeTransformation">
    <cs:param name="source" select="$source"/>
    <cs:param name="dest" select="$resultFile"/>
    <cs:param name="barcode-transformation">
        <barcode-transformation type="ean13" file-format="pdf" height="30"
        module-width="1" margin="4" orientation="0" font="Courier" font-size="6"
        qr-error-corr="" dpi="300" antialias="true"/>
    </cs:param>
</cs:command>

FOP transformation (com.censhare.api.transformation.FopTransformation)

Executes a FOP (XSL formatting objects) transformation.

Parameters

• source The input XML to be transformed (required). Valid sources are XML, an URL (virtual file system reference, censhare REST URL) or a storage item XML.
• stylesheetSource Source of the stylesheet XML (required). Valid sources are XML, an URL (virtual file system reference, censhare REST URL) or a storage item XML.
• dest The file locator of the destination file where the result of the transformation should be stored (optional). It must reference a file on a temporary file system, typically one that was created by a call to createVirtualFileSystem. If this parameter is missing, the XML result of the transformation is returned as a result of this cs:command function without generating a PDF.
• xslParameters Additional parameters, which are passed directly to the XSL transformation and are not interpreted by the command itself (optional). They can be referenced inside the XSLT by their names as specified in the cs:param's name attribute. The following attributes are additionally passed to the FOP processor: author, title, pdf-base-url, keywords, source-resolution, target-resolution and pdf-base14-kerning.

Returns: An XML Element with attributes containing output file url, page-width [mm], page-height [mm] and line-count of the generated PDF. If the dest parameter was null, the result of the transformation is returned as XML. If a "returning" attribute is present, the result is stored in a variable with the given name and can be used afterwards. It's also allowed to omit the "returning" attribute. In that case, the result is directly returned by the cs:command function.

Example

<cs:command name="com.censhare.api.transformation.FopTransformation" returning="dummy">
    <cs:param name="key" select="'censhare:fop-sample'"/>
    <cs:param name="source" select="$chapterAsset/storage_item[@key='master'][1]"/>
    <cs:param name="dest" select="concat($parentDir, 'chapter-', $chapterAsset/@id, '.pdf')"/>
    <cs:param name="xsl-parameters">
        <cs:param name="target-resolution" select="300"/>
        <cs:param name="title" select="asset/@name"/>
        <cs:param name="asset" select="asset"/>
    </cs:param>
</cs:command>

MathXML transformation (com.censhare.api.transformation.MathMLTransformation)

Executes transformations of a MathML source to some image format.

Parameters

• source The input XML to be transformed (required). Valid sources are XML, an URL (virtual file system reference, censhare REST URL) or a storage item XML.
• dest The file locator of the destination file where the result of the transformation should be stored. It must reference a file in a virtual file system (required) (see createVirtualFileSystem).
• mathMLTransformation XML node with all possible parameters.

Example

<cs:command name="com.censhare.api.transformation.MathMLTransformation">
    <cs:param name="source" select="$currentAsset/storage_item[@key='master']"/>
    <cs:param name="dest" select="concat($dir, 'images/output.jpg')"/>
    <cs:param name="mathml-transformation">
        <mathml-params>
            <font-map>path/to/fontmap.file</font-map>
            <font-size>36</font-size>
            <dpi>300</dpi>
            <padding>10</padding>
            <anti-alias>true</anti-alias>
        </mathml-params>
    </cs:param>
</cs:command>

Office transformations

Read Excel file (com.censhare.api.Office.ReadExcel)

Executes the extraction of MS-Excel data (XLS or XLSX) into normalized XML.

Parameters

• source The input source (Excel file) to be transformed (required). It must reference a storage_item or a file.
• dest The file locator of the destination file where the result of the transformation should be stored. It must reference a file in a virtual file system (required) (see createVirtualFileSystem).
• maxRows maximum number of rows for normalizing borders and empty cells used to limit memory impact for very Excel files with huge amount of cells, default is unlimited
• maxCols maximum number of columns for normalizing borders and empty cells used to limit memory impact for very Excel files with huge amount of cells, default is unlimited
• sheetIdx Extraction (level = "full") is only done for that specific sheet index, default is 0
• level If set to "info" only sheet info, named ranges info and style info is extracted, default is "full"

Example

<cs:command name="com.censhare.api.Office.ReadExcel">
    <cs:param name="source" select="$source"/>
    <cs:param name="dest" select="$resultFile"/>
    <cs:param name="level" select="'full'"/>
    <cs:param name="sheet-index" select="'0'"/>
    <cs:param name="max-rows" select="'1000'"/>
    <cs:param name="max-columns" select="'1000'"/>
</cs:command>

Read Word file (com.censhare.api.Office.ReadWord)

Executes the extraction of MS-Word data (DOC or DOCX) into normalized XML.

Parameters

• source The input source (Excel file) to be transformed (required). It must reference a storage_item or a file.
• dest The file locator of the destination file where the result of the transformation should be stored. It must reference a file in a virtual file system (required) (see createVirtualFileSystem).

Example

<cs:command name="com.censhare.api.Office.ReadWord">
    <cs:param name="source" select="$source"/>
    <cs:param name="dest" select="$resultFile"/>
</cs:command>

Write Excel (com.censhare.api.office.WriteExcel)

Writes an Excel file out of string or XML input.

Parameters

• source The input source (string or XML) to be transformed (required).
• dest The file locator of the destination file where the result of the transformation should be stored. It must reference a file in a virtual file system (required) (see createVirtualFileSystem).

Example

<cs:command name="com.censhare.api.office.WriteExcel">
  <cs:param name="source" select="$xmlsource"/>
  <cs:param name="dest" select="$path"/>
</cs:command>

Additional resources

• Screencast - XSLT Excel export (based on Apache POI)

Global Context

Set static properties (com.censhare.api.context.SetProperty)

Set static properties (variables) in global context.

This command sets a variable in the global context. Those variables can be accessed in all templates, included stylesheets and sub-transformations. Most commonly used to provide input parameters for a transformation (e.g. for a test setup) or to return result parameters from a transformation back to the calling process.

Known input properties:

• censhare:auto-delete Flag if the working directory should be deleted automatically at end of the transaction. It can be set to false for debugging purposes. (Default: true)
• censhare:logger Named context logger to use.

Known result properties:

• censhare:result-file-locator REST URL to the result file or directory.
• censhare:result-mimetype The mime type of the result file. If missing, the defined output mime type of the transformation is taken.

Example

<cs:command name="com.censhare.api.context.SetProperty">
    <cs:param name="name" select="'censhare:auto-delete'"/>
    <cs:param name="value" select="'false'"/>
</cs:command>

I/O

Read XML (com.censhare.api.io.ReadXML)

Reads XML content from a file or a storage item.

The command reads XML from an input source, which can be either a file or a storage item, and returns it as XML document. If a "returning" attribute is present, the result is stored in a variable with the given name and can be used afterwards. If the returning clause is missing the result document is directly returned by the cs:command function.

Parameters

• source The input source from which to read. Valid sources are an URL (virtual file system reference, censhare REST URL) or a storage item XML.

Returns: The XML document.

Example

<cs:command name="com.censhare.api.io.ReadXML" returning="content">
    <cs:param name="source" select="asset/storage_item[@key='master'][1]"/>
</cs:command>

Write XML (com.censhare.api.io.WriteXML)

Serializes an XML document into a file.

Parameters

• source The XML to be written (required).
• dest The file locator of the destination file (required). It must reference a file in a virtual file system (see createVirtualFileSystem).
• output An XML element "output" providing various serialization properties like pretty printing or encoding (optional). This element is identical to the XSLT output function (xsl:output) and supports most of its attributes (see also XslSerializer):

<output
    name? = qname
    method? = "xml" | "html" | "xhtml" | "text" | qname-but-not-ncname
    byte-order-mark? = "yes" | "no"
    cdata-section-elements? = qnames
    doctype-public? = string
    doctype-system? = string
    encoding? = string
    escape-uri-attributes? = "yes" | "no"
    include-content-type? = "yes" | "no"
    indent? = "yes" | "no"
    media-type? = string
    normalization-form? = "NFC" | "NFD" | "NFKC" | "NFKD" | "fully-normalized" | "none" | nmtoken
    omit-xml-declaration? = "yes" | "no"
    standalone? = "yes" | "no" | "omit"
    undeclare-prefixes? = "yes" | "no"
    use-character-maps? = qnames
    version? = nmtoken/>

Example

<cs:command name="com.censhare.api.io.WriteXML">
    <cs:param name="source" select="$metaDoc"/>
    <cs:param name="dest" select="concat($out, 'EPUB-Debug.xml')"/>
    <cs:param name="output">
        <output indent="yes"/>
    </cs:param>
</cs:command>

Copy file (com.censhare.api.io.Copy)

Copies a file or a storage item into a destination file.

The input source, which can be either a file or a storage item, is copied to the destination without any transformations. If you want to transform the file in any way, use one of the transformation commands instead.

The command does not return a result.

Parameters

• source The input source to be copied. Valid sources are an URL (virtual file system reference, censhare REST URL) or a storage item XML.
• dest The URL of the destination file. It must reference a file on a temporary file system, typically one that was created by a call to createVirtualFileSystem.

Example Copy a storage item

<cs:command name="com.censhare.api.io.Copy">
    <cs:param name="source" select="asset/storage_item[@key='master'][1]"/>
    <cs:param name="dest" select="concat($out, 'result/image.jpg')"/>
</cs:command>

Example Copy a file

<cs:command name="com.censhare.api.io.GetFilesystemRef" returning="config">
    <cs:param name="name" select="'config-runtime'"/>
</cs:command>
<cs:command name="com.censhare.api.io.Copy">
    <cs:param name="source" select="concat($config, 'modules/resources/logo.jpg')"/>
    <cs:param name="dest" select="concat($out, 'result/image.jpg')"/>
</cs:command>

List directory (com.censhare.api.io.List)

Lists all files and folders of a given file reference (including files in subfolders).

Parameters

• source The source folder reference to list the files from. Valid source is an URL: file system reference (e.g. censhare:///service/filesystem/temp/dir), virtual file reference (see createVirtualFileSystem) or server file system reference (see getFilesystemRef).

• filter - The filter string (e.g. '*.jpg') to filter the returned files.

Returns: An XML containing nodes representing the files and folders. The syntax of the result is:

<list url=":url_of_source">
    <item name=":name_of_file" modified-date=":modified_date_of_file" type=":file_or_directory" url=":url_of_file" length=":length_of_file"/>
    <item name=":name_of_file2" ...
</list>

Example List all JPG files and all folders of a temp filesystem folder.

<cs:command name="com.censhare.api.io.List">
    <cs:param name="source" select="'censhare:///service/filesystem/temp/hotfolder1'"/>
    <cs:param name="filter" select="'*.jpg'"/>
</cs:command>

For example the result of file system reference "censhare:///service/filesystem/temp/hotfolder1" might be:

<list url="censhare:///service/filesystem/temp/hotfolder1">
    <item name="test.jpg" modified-date="2013-08-12T10:51:50Z" type="file" url="censhare:///service/filesystem/temp/hotfolder1/test.jpg" length="14377"/>
    <item name="sub" modified-date="2014-06-11T15:46:21Z" type="directory" url="censhare:///service/filesystem/temp/hotfolder1/sub" length="170"/>
    <item name="test2.jpg" modified-date="2013-08-15T10:51:50Z" type="file" url="censhare:///service/filesystem/temp/hotfolder1/sub/test2.jpg" length="12597"/>
</list>

Delete file or directory (com.censhare.api.io.Delete)

Deletes given file or folder.

Parameters

• source The source file reference to be deleted. Valid source is an URL: file system reference (e.g. censhare:///service/filesystem/temp/dir), virtual file reference (see createVirtualFileSystem) or server file system reference (see getFilesystemRef).

Example Delete file 'test.jpg' in a temp filesystem folder.

<cs:command name="com.censhare.api.io.Delete">
    <cs:param name="source" select="'censhare:///service/filesystem/temp/hotfolder1/test.jpg'"/>
</cs:command>

Move file or directory (com.censhare.api.io.Move)

Moves given file or folder to given destination.

Parameters

• source The source file reference to be moved. Valid source is an URL: file system reference (e.g. censhare:///service/filesystem/temp/dir), virtual file reference (see createVirtualFileSystem) or server file system reference (see getFilesystemRef).
• dest The destination folder reference. Valid destination is an URL: file system reference (e.g. censhare:///service/filesystem/temp/dir), virtual file reference or (see createVirtualFileSystem)

Example Move file 'test.jpg' in a temp filesystem folder to another temp filesystem folder.

<cs:command name="com.censhare.api.io.Move">
    <cs:param name="source" select="'censhare:///service/filesystem/temp/hotfolder1/test.jpg'"/>
    <cs:param name="dest" select="'censhare:///service/filesystem/temp/hotfolder2'"/>
</cs:command>

Rename file or directory (com.censhare.api.io.Rename)

Renames given file or folder to given name.

Parameters

• source The source file reference to be renamed. Valid source is an URL: file system reference (e.g. censhare:///service/filesystem/temp/dir), virtual file reference (see createVirtualFileSystem) or server file system reference (see getFilesystemRef).
• newFileName The new file name (dest) used for renaming the given source file or folder.

Example Rename file 'test.jpg' in a temp filesystem to 'test2.jpg'.

<cs:command name="com.censhare.api.io.Rename">
    <cs:param name="source" select="'censhare:///service/filesystem/temp/hotfolder1/test.jpg'"/>
    <cs:param name="dest" select="'test2.jpg'"/>
</cs:command>

Create virtual file system (com.censhare.api.io.CreateVirtualFileSystem)

Creates a (possibly virtual) temporary directory, which can be used by the caller to write files into it.

The virtual file system is created in a temporary directory on the server's local temp file system. It is for the exclusive use of the caller. It will automatically be deleted at end of the corresponding command or transaction.

The result of the command is a file locator, i.e. a reference to the file system, which is stored in a variable. The name of the variable must be specified by the caller within the attribute "returning".

Since it's only allowed to modify or create files within a virtual file system, all file references must be prefixed by a virtual file system reference. As a file reference is an (internal) URL, this can simply be done using string concatenation (see example below). Any attempt to write outside a virtual file system will lead to an error.

Parameters

• format The result format of the file system (optional). If the file system should be packed into an archive, this parameter must be specified. Supported archive formats are "zip" and "epub-zip". "epub-zip" is like "zip" but creates a "mimetype" file entry in the topmost hierarchy of the zip archive unless it is already included in the list of file entries. This "mimetype" entry is needed to have a predefined content and byte position to comply with the epub standard. If the parameter is missing, the result will be a directory structure.
• compressionLevel (optional). If the format parameter is 'zip' this will set the compression level for the whole ZIP archive file. A sample use is when creating 'ePub' archives. They require to have no compression for the included MIME type file. valid values: 0..9 (0 - no compression, 9 - highest compression) default: 9

Returns: The URL identifying the virtual file system. This string can be used for all subsequent output file references.

Example Create a virtual file system (ZIP file) and copy a file into it.

<cs:command name="com.censhare.api.io.CreateVirtualFileSystem" returning="zip">
    <cs:param name="format" select="'zip'"/>
    <cs:param name="compression-level" select="0"/>
</cs:command>

<cs:command name="com.censhare.api.io.Copy">
    <cs:param name="source" select="asset/storage_item[@key='master'][1]"/>
    <cs:param name="dest" select="concat($zip, 'images/image.jpg')"/>
</cs:command>

Create virtual file system (com.censhare.api.io.CloseVirtualFileSystem)

Closes a virtual file system.

Actually closing a file system is only necessary for file systems that are realized as an archive (ZIP, epub-zip). But it's good practice to explicitly close every virtual file system, which was created by the caller before. A closed file system must no longer be accessed, neither for read nor write.

If the file system is a ZIP (or epub-zip) archive, it is possible to provide a parameter "dest". The resulting ZIP file will be stored at that destination. The "dest" must be a file reference into another virtual file system.

If the virtual file system was created with the "epub-zip" format it will be closed as such, no matter if the format parameter here is set as "zip" or "epub-zip" or even left out.

Parameters

• id The file system reference as returned in createVirtualFileSystem.
• name The name of the result archive file (optional). This parameter is ignored if the file system is either no ZIP archive or the parameter "dest" is specified.
• dest A file reference where the archive file should be stored (optional). This parameter is ignored if the file system isn't an archive.

Returns: The URL identifying the resulting directory or archive file. It can be used as a "censhare:result-file-locator" return parameter.

Example

<cs:command name="com.censhare.api.io.CreateVirtualFileSystem" returning="out">
    <cs:param name="format" select="'zip'"/>
    <cs:param name="compression-level" select="0"/>
</cs:command>

...

<cs:command name="com.censhare.api.io.CloseVirtualFileSystem" returning="zip">
    <cs:param name="id" select="$out"/>
    <cs:param name="name" select="concat(asset/@name, '.zip')"/>
</cs:command>

Get file system reference (com.censhare.api.io.GetFilesystemRef)

Get a reference to a server file system for reading only.

Returns a reference to the named file system, which must be a server file system. This file system can be used for reading only. It is not possible to write into it.

Currently, the only supported file system is the server's configuration ("config-runtime"). That way it is possible to include additional resources like config files or XSLT stylesheets, which are not stored as resource assets.

Parameters

• name The name of the file system.

Example

<cs:command name="com.censhare.api.io.GetFilesystemRef" returning="config">
    <cs:param name="name" select="'config-runtime'"/>
</cs:command>
<cs:command name="com.censhare.api.transformation.XslTransformation" returning="xml">
    <cs:param name="stylesheet" select="concat($config, 'modules/content_export/stylesheets/export.xsl'"/>
    <cs:param name="source" select="asset/storage_item[@key='master'][1]"/>
</cs:command>

Validate XML schema (com.censhare.api.io.ValidateXmlSchema)

Validates a source XML against a schema defined by a REST URL.

Parameters

• source The input XML to be transformed (required). Valid sources are XML, a URL (virtual file system reference, censhare REST URL) or a storage item XML.
• schema The REST URL of the schema resource asset.

Returns: Boolean which indicates whether the XML was validated against the selected schema.

Example

<xsl:variable name="schema-key" select="'csc:schema-for-image'"/>
<cs:command name="com.censhare.api.io.ValidateXmlSchema">
    <cs:param name="source" select="$query-xml"/>
    <cs:param name="schema" select="concat('censhare:///service/assets/asset;censhare:resource-key=', $schema-key, '/storage/master/file')"/>
</cs:command>

Write text string into a file (com.censhare.api.io.WriteText)

Serializes a plain text string into a file.

Parameters

• source The plain text to be written (required).
• dest The file locator of the destination file (required). It must reference a file in a virtual file system.
• unescape Boolean which indicates whether escaped elements need to be written back as original characters (optional).

Example

<xsl:variable name="temp-file-url" select="concat('censhare:///service/filesystem/temp/', $macro-asset/@id, '.groovy')" />
<cs:command name="com.censhare.api.io.WriteText">
    <cs:param name="source" select="'This is text.'" />
    <cs:param name="dest" select="$temp-file-url" />
    <cs:param name="unescape" select="false()" />
</cs:command>

Command

Dynamically creates and executes server commands.

Execute command (com.censhare.api.command.Execute)

Dynamically creates and executes server commands.

Parameters

• source The command XML to execute.
• timeout Maximum time required for the command execution. By default, it is 1 hour.

Example

<xsl:variable name="command-xml">
    <cmd timeout="1000">
        <xml-info title="my-create-master-data" locale="__ALL"/>
        <cmd-info name="admin.export_import.xml-data-import"/>
        <commands currentstep="0">
            <command method="importXml" scriptlet="modules.admin.export_import.XmlDataImport" target="ScriptletManager"/>
        </commands>
        <content>
        </content>
        <param to-do="both"/>
    </cmd>
</xsl:variable>
<!-- setup the data -->
<cs:command name="com.censhare.api.Command.execute">
    <cs:param name="source" select="$command-xml"/>
    <cs:param name="timeout" select="1000"/>
</cs:command>

Message

Updates assets with messages in the case of an event.

Create asset message (com.censhare.api.message.Create)

Creates asset message.

Parameters

• asset-id The id of the asset, the message is appended to.
• title The title of the message.
• text The actual message.
• level Optional value of the message level (see java.util.logging.Level).

Returns: The asset XML of the appended asset.

Example

<xsl:variable name="error-message-title" select="'Adjusting Responsibilities'" />
<cs:command name="com.censhare.api.message.Create">
    <cs:param name="asset-id" select="asset/@id" />
    <cs:param name="title" select="$error-message-title" />
    <cs:param name="text" select="'some text'" />
    <cs:param name="level" select="'FINER'" />
</cs:command>

Event

Creates and sends events.

Send an event (com.censhare.api.event.Send)

Constructs and sends an event.

Parameters

• source The event XML to send (required).

Returns: The resulting XML of the created event. If a "returning" attribute is present, the result is stored in a variable with the given name and it can be used afterwards. It is also allowed to omit the "returning" attribute. In that case, the resulted document is directly returned by the cs:command function.

Example

<xsl:variable name="event2-xml">
    <event target="AssetEvent" method="rebuild-preview" param0="15506" param1="1" param2="0"/>
</xsl:variable>
<cs:command name="com.censhare.api.event.SendEvent">
    <cs:param name="source" select="$event2-xml" />
</cs:command>

XMLDiff

API class for special XML-based diff methods.

Compare XMLs (com.censhare.api.xmlDiff.textDiff)

Text-based comparison of two XML documents. The XML structure/markup of the new document is kept and enhanced with markers containing information about the modified text content.

Parameters

• old The old version of the XML to compare.
• new The new version of the XML to compare.
• delete-marker Optional parameter which specifies with which markup the detected changes are surrounded.
• insert-marker Optional parameter which specifies with which markup the detected changes are surrounded.

Returns: The merged XML which contains all XML markup of the new version, keeping the desired XML structure. Text deletions and text insertions are surrounded by marker elements.

Example

<xsl:param name="delete-marker" as="element()">
    <change type="deletion" mode="test"/>
</xsl:param>
<xsl:variable name="version1" select="doc(concat('censhare:///service/assets/asset/id/', '15915'))"/>
<xsl:variable name="version2" select="doc(concat('censhare:///service/assets/asset/id/', '15926'))"/>

<cs:command name="com.censhare.api.xmlDiff.textDiff">
    <cs:param name="old" select="$version1" />
    <cs:param name="new" select="$version2" />
    <cs:param name="delete-marker" select="$delete-marker"/>
    <cs:param name="insert-marker">
        <inserted type="newtext"></inserted>
    </cs:param>
</cs:command>

Render

Render (com.censhare.api.renderer.Render)

Executes the rendering commands given through the Render-Client.

Exceptions are thrown if there is no Render-Client available

The method returns the complete command XML as returned from a regular renderer command. Typically you would extract @corpus:asset-temp-filesystem and @corpus:asset-temp-filepath from /cmd/renderer/command[@method='preview'] to access e.g. the rendered previews.

Please note that currently modules.renderer.aa-call-renderer must exist and is used as a dummy command.

The timeout for rendering commands is currently hardcoded to 120 seconds.

Parameters

• context implicitly set
• facility String, currently allowed values: "indesign-6.0" for CS-4, "indesign-7.0" for CS-5, "indesign-7.5 for CS-5.5, "indesign-8.0" for CS-6
• timeout int value in seconds to timeout Renderer operations
• instructions The command XML that will be sent to the Renderer containing both renderer instructions/commands and the list of asset XMLs.

Example

<cs:command name="com.censhare.api.Renderer.Render">
    <cs:param name="facility" select="'indesign-7.0'"/>
    <cs:param name="timeout" select="'240'"/>
    <cs:param name="instructions">
        <cmd>
            <renderer>
                <command method="open" asset_id="15884" document_ref_id="15884"/>
                <command method="correct-document" document_ref_id="15884"/>
                <command method="preview" spread="false" asset_element_id="1" document_ref_id="15884"/>
                <command method="preview" spread="false" asset_element_id="2" document_ref_id="15884"/>
                <command method="preview" spread="false" asset_element_id="3" document_ref_id="15884"/>
                <command method="close" document_ref_id="15884"/>
            </renderer>
            <assets>
                <asset id="1245" ...>
                    <asset_element .../>
                </asset>
            </assets>
        </cmd>
    </cs:param>
</cs:command>

Methods

Note: Always place the correct-document method directly after the open method at the beginning of the command sequence. The correct-document method checks, cleans up, and corrects the document ID and other metadata if necessary. Otherwise, the rendering can lead to unexpected errors.

• check-missing-fonts
• check-placed-collections
• close
• copy-pagearea
• copy-pagearea-asset
• correct-document
• debug
• detach
• detach-pagearea
• edit-placement
• eps
• mark-not-printable-boxes
• move-box
• move-pagearea
• open
• pdf
• place
• place-collection
• preview
• rename-group
• save
• script
• text-content
• update-asset-element-structure
• update-auto-client-variant
• update-content
• update-geometry
• update-placeholder

PDF

Combine PDF (com.censhare.api.pdf.CombinePDF)

Combines pages from the given PDF input files.

If attribute source@pages is missing all pages are taken as input.

Parameters

• context implicitly set
• sources list of source specifications
• dest The file locator of the destination file where the generated PDF should be stored (optional). It must reference a file in a virtual file system (see createVirtualFileSystem). If this parameter is missing an IllegalStateException is thrown.

Returns: XML

Example

<cs:command name="com.censhare.api.pdf.CombinePDF" returning="resultVariable">
    <cs:param name="dest" select="$dest"/>
    <cs:param name="sources">
        <source href="file:/modules/test/test.pdf" pages="(1,2,3)"/>
        <source href="http://www.censhare.com/_storage/19623/122939/censhare+Feature+Summary.pdf"/>
        <source href="censhare:///service/assets/asset/id/203917/storage/master/file/145053.pdf"/>
        <source href="censhare:///service/filesystem/temp/_69e9d2f4-9038-4b24-9840-2d72266d64af/1.pdf"/>
    </cs:param>
</cs:command>

Get PDF info (com.censhare.api.pdf.InfoPDF)

Get structure info from PDF input files.

Sample source values

censhare:///service/assets/asset/id/203917/storage/master/file/145053.pdf
censhare:///service/filesystem/temp/_69e9d2f4-9038-4b24-9840-2d72266d64af/1.pdf
http://www.censhare.com/_storage/19623/122939/censhare+Feature+Summary.pdf
file:/modules/test/test.pdf

Parameters

• contextimplicitly set
• source see examples above

Example

<cs:command name="com.censhare.api.pdf.InfoPDF" returning="resultVariable">
    <cs:param name="source" select="$source"/>
</cs:command>

Sample result

<?xml version="1.0" encoding="UTF-8"?>
<InfoPDF version="1.0">
  <Catalog>
    <AcroForm object-number="2" object-generation="0">
      <AcroForm>
        <DA>/Helv 0 Tf 0 g </DA>
        <DR>
          <Encoding>
            <PDFDocEncoding object-number="57" object-generation="0">
              <PDFDocEncoding>
                <Differences>
                  <item>24</item>
                  <item>breve</item>
                  <item>caron</item>
                  <item>circumflex</item>
...

Get PDF form info (com.censhare.api.pdf.formPDF)

Get structure form data from PDF input files.

The type parameter is optional. If left out we try to first access the XFA and as a fallback the XFDF part of the source PDF. The type will be reported in the result XML attribute form-data@type.

sample source values:

censhare:///service/assets/asset/id/203917/storage/master/file/145053.pdf
censhare:///service/filesystem/temp/_69e9d2f4-9038-4b24-9840-2d72266d64af/1.pdf
http://www.censhare.com/_storage/19623/122939/censhare+Feature+Summary.pdf
file:/modules/test/test.pdf

Parameters

• context implicitly set
• source see examples above
• type ["FDF"|"XFDF"|"XFA"]

Returns: XML

Example

<cs:command name="com.censhare.api.pdf.FormPDF">
    <cs:param name="source" select="'censhare:///service/assets/asset/id/203917/storage/master/file/145053.pdf'"/>
</cs:command>

Sample result

<?xml version="1.0" encoding="UTF-8"?>
<form-data type="XFDF">
  <xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">
    <ids original="16449DB8CB323843F2F1CB2033C0242D" modified="B392B9652234447B9CDFE0740F491CDA"/>
    <fields>
      <field name="LastName">
        <value>Content for last name</value>
      </field>
      <field name="FirstName">
        <value>Content for first name</value>
      </field>
      <field name="MiddleName">
        <value>Content for middle name</value>
      </field>
    </fields>
...

HTTP request (com.censhare.api.Http.request)

Send HTTP requests.

Example

<cs:command name="com.censhare.api.Http.request" returning="resultVariable">
    <cs:param name="request">
        <request method="GET" href="http://localhost:9000/ws/rest/service/assets/asset/id/10000"
                username="me" password="secret" auth-method="basic"
                content-type="text/xml"
                timeout="15">
            <header name="Connection" value="close"/>
            <header name="AcceptLanguage" value="de-DE,de;q=0.8,en-US;q=0.6,en;q=0.4"/>
            <header name="Custom-Header" value="foo"/>
        </request>
    </cs:param>
</cs:command>

Mandatory parameters

• href target URL, e.g. http://www.example.com/path?param1=foo&param2=bar
• method ['GET'|'POST'|'PUT'|'DELETE'|'MOVE']

Request parameters

• username
• password
• timeout defaults to 15 seconds
• auth-method "basic" is the only supported authentication method at the moment
• content-type for POST requests If "multipart/form-data" the body may be build up with nodes, please see below. If any other MIME type is set the content of or will be sent
• href-target target URL, e.g. http://webdav.example.com/directory/new-file-name.txt
• overwrite default to false, only considered for HTTP MOVE

Form parameters

• name
• value String encoding currently only with UTF-8
• source
• mimetype defaults to "binary/octet-stream"
• filename specify Content-Disposition filename, an arbitrary number otherwise

Sample usage (POST)

<cs:command name="com.censhare.api.Http.request">
    <cs:param name="request">
        <request method="POST" href="http://server.example.com/path"
              content-type="multipart/form-data">
            <header name="Accept" value="application/xml"/>
            <body>
                <form name="foo" value="182531"/>
                <form name="bar" value="783C6749DA2058E9"/>
                <form name="file-variant1" mimetype="application/xml"
                    source="censhare:///service/filesystem/temp/payload.xml"/>
                <form name="file-variant2" mimetype="application/xml"
                    source="censhare:///service/assets/asset/id/10000/storage/master/file"
                    filename="choose-your-own-filename"/>
                <form name="file-variant3" mimetype="application/xml">
                    <whatever-inline>
                        <xml-structure>you like</xml-structure>
                    </whatever-inline>
                </form>
            </body>
        </request>
    </cs:param>
</cs:command>

Sample usage (MOVE)

<cs:command name="com.censhare.api.Http.request">
    <cs:param name="request">
        <request method="MOVE"
            auth-method="digest" username="me-the-user" password="this-is-a-secret">
            href="http://webdav.example.com/directory/new-file-name.upload-in-progress.tmp"
            href-target="http://webdav.example.com/directory/new-file-name.txt" overwrite="false">
        </request>
    </cs:param>
</cs:command>

Please note that accessing the input file with source="censhare:///service/filesystem/temp/payload.xml" is the fastest. Currently, we cannot use input streams as source and buffer in a temporary file.

Parameters

• context implicitly set
• req request as XML parameter

Returns: XML HTTP response

Mail

Note: mails@account-name must be the configured mail account in services/E-mail Mail service will throw a NullPointerException if there is no recipient at all.

Send mail (com.censhare.api.Mail.SendMail)

Send mail using the server-side Mail Service.

Example

<cs:command name="com.censhare.api.Mail.SendMail" returning="resultVariable">
    <cs:param name="source">
        <mails account-name="corpus">
            <mail sender-address="corpus@censhare.de" subject="Message of the day">
                <recipient type="to" address="ar@censhare.de"/>
                <content mimetype="text/html" transfer-charset="UTF-8">&lt;p&gt;¡Misericordia!&lt;/p&gt;</content>
            </mail>
            <mail sender-address="corpus@censhare.de" subject="Message of the day">
                <recipient type="to" address="ar@censhare.de"/>
                <multipart-body>
                    <content mimetype="text/plain" transfer-charset="ISO-8859-1">Ciao</content>
                </multipart-body>
                <multipart-body filename="no-picture-of-me!" url="censhare:///service/assets/asset/id/29943/storage/image2/file"/>
            </mail>
        </mails>
    </cs:param>
</cs:command>

Parameters

• context implicitly set
• source mail body as specified in MailService.sendMail(AXml))

Returns: Timestamp.

Since version 2017.4.2 and 2017.5.0 you may add further mail headers as needed. The following example shows how to reference an original mail in a reply, thereby allow mail clients to display a threaded tree.

<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:cs="http://www.censhare.com/xml/3.0.0/xpath-functions">

  <xsl:output method="xml" indent="yes"
              omit-xml-declaration="no" encoding="UTF-8"/>

  <xsl:template match="/">

    <xsl:variable name="result-xml">
      <cs:command name="com.censhare.api.mail.SendMail">
        <cs:param name="source">
          <mails account-name="corpus">
            <mail
                sender-address="corpus2@censhare.com"
                subject="Some topic started"
                >
              <mail-header name="Message-ID">&lt;4711-1@censhare.com&gt;</mail-header>
              <recipient type="to" address="ar@censhare.de"/>
              <content mimetype="text/plain" transfer-charset="UTF-8">Let's see how to start ...
              </content>
            </mail>
            <mail
                sender-address="corpus2@censhare.com"
                subject="Re: Some topic started"
                >
              <mail-header name="Message-ID" >&lt;4711-2@censhare.com&gt;</mail-header>
              <mail-header name="In-Reply-To">&lt;4711-1@censhare.com&gt;</mail-header>
              <mail-header name="References" >&lt;4711-1@censhare.com&gt;</mail-header>
              <recipient type="to" address="ar@censhare.de"/>
              <mail-header name="DEMO-foo" >DEMO ...</mail-header>
              <content mimetype="text/plain" transfer-charset="UTF-8">&gt; Let's see how to start ...
Don't worry, we succeed.</content>
            </mail>
          </mails>
        </cs:param>
      </cs:command>
    </xsl:variable>
    <xsl:copy-of select="$result-xml"/>

  </xsl:template>

</xsl:stylesheet>

Check mailbox (com.censhare.api.Mail.ListMail)

Check mail using the server-side service MailService.checkMail(AXml).

Example

<cs:command name="com.censhare.api.Mail.ListMail" returning=":resultVariable">
    <cs:param name="source">
        <mails account-name="corpus" folder="INBOX"/>
    </cs:param>
</cs:command>

Remarks:

• Id 1 is the oldest E-mail
• There is no locking of the folder.
• You have to call listMail() again to monitor for freshly arriving E-mails. After successful execution, the input parameter XML is enriched. A new attribute mails@timestamp is set to the timestamp of execution. For each mail found in the checked folder, a new XML node mail is generated

Sample result

<mails account-name="corpus2" folder="INBOX" timestamp="2013-09-04T10:00:12.573Z">
    <mail id="1" replyto-address="Kerio Connect Team &lt;noreply-connect-client@kerio.com&gt;" from-address="Kerio Connect Team &lt;noreply-connect-client@kerio.com&gt;" mime-msg-id="&lt;-2020976776-20170@xena.censhare.de&gt;" subject="Lernen Sie den neuen Kerio Connect Client kennen!" sent-date="Wed Mar 20 12:23:43 CET 2013">
        <recipient address="corpus2 &lt;corpus2@censhare.de&gt;" type="to"/>
    </mail>
    <mail id="2" replyto-address="Axel Rose &lt;ar@censhare.de&gt;" from-address="Axel Rose &lt;ar@censhare.de&gt;" mime-msg-id="&lt;EBDE132D-02A0-4554-9F1E-2A5DF4F7590A@censhare.de&gt;" subject="und nun" sent-date="Mon Sep 02 13:47:22 CEST 2013">
        <recipient address="corpus2@censhare.de" type="to"/>
    </mail>
    <mail id="3" replyto-address="Axel Rose &lt;ar@censhare.de&gt;" from-address="Axel Rose &lt;ar@censhare.de&gt;" mime-msg-id="&lt;F8CFD4D3-64AE-4827-ACD2-7F8BDFEAE94B@censhare.de&gt;" subject="mit Anhang" sent-date="Mon Sep 02 14:21:45 CEST 2013">
        <recipient address="&quot;corpus2@censhare.de&quot; &lt;corpus2@censhare.de&gt;" type="to"/>
    </mail>
</mails>

Parameters

• context implicitly set
• source mails configuration for account and folder MailService.sendMail(AXml))

Returns: XML (see example above)

Read mail (com.censhare.api.Mail.ReadMail)

Read mail using the server-side service MailService.receiveMail(AXml).

<cs:command name="com.censhare.api.Mail.ReadMail" returning=":resultVariable">
    <cs:param name="source">
        <mails account-name="corpus" folder="INBOX" show-envelope="false">
            <mail id="1" delete-after-reading="false"/>
        </mails>
    </cs:param>
</cs:command>

Mails Parameters

• account-name account (must exist preconfigured in mail service)
• folder inbox folder, defaults to INBOX.
• id id value as returned from MailService.checkMail(com.censhare.support.xml.AXml)
• delete-after-reading message is deleted after being read, default is false
• show-envelope return node containing all headers as attributes, default is true use MailService.deleteMail(com.censhare.support.xml.AXml) for top secure delete-before-read :)

After successful execution, the input parameter XML is enriched. A new attribute mails@timestamp is set to the timestamp of execution. For each mail read in the checked folder the XML node mail contains optionally the data and all parts.

Sample result

<mails account-name="corpus2" folder="INBOX" timestamp="2013-09-04T13:14:05.524Z">
    <mail id="3" delete-after-reading="false" replyto-address="Axel Rose &lt;ar@censhare.de&gt;" from-address="Axel Rose &lt;ar@censhare.de&gt;" subject="mit Anhang" content-type="multipart/alternative; &#xd;&#xa;&#x9;boundary=&quot;Apple-Mail=_BAA60BA2-1817-4828-8512-A551263F9145&quot;" sent-date="2013-09-02T12:21:45Z">
        <recipient address="&quot;corpus2@censhare.de&quot; &lt;corpus2@censhare.de&gt;" type="to"/>
        <envelope Return-Path="&lt;ar@censhare.de&gt;" X-Spam-Level="" X-Spam-Status="No, hits=0.0 required=6.0&#xd;&#xa;&#x9;tests=AWL: -0.776,BAYES_00: -1.665,HTML_IMAGE_ONLY_04: 1.172,&#xd;&#xa;&#x9;HTML_IMAGE_RATIO_02: 0.437,HTML_MESSAGE: 0.001,T_REMOTE_IMAGE: 0.01,&#xd;&#xa;&#x9;TOTAL_SCORE: -0.821,autolearn=no" X-Envelope-To="corpus2@censhare.de" X-Footer="Y2Vuc2hhcmUuZGU=" Content-Type="multipart/alternative; boundary=&quot;Apple-Mail=_BAA60BA2-1817-4828-8512-A551263F9145&quot;" From="Axel Rose &lt;ar@censhare.de&gt;" Received="from localhost ([127.0.0.1])&#xd;&#xa;&#x9;by xena.censhare.de&#xd;&#xa;&#x9;(using TLSv1/SSLv3 with cipher AES128-SHA (128 bits))&#xd;&#xa;&#x9;for corpus2@censhare.de;&#xd;&#xa;&#x9;Mon, 2 Sep 2013 14:21:47 +0200" Subject="mit Anhang" To="&quot;corpus2@censhare.de&quot; &lt;corpus2@censhare.de&gt;" Date="Mon, 2 Sep 2013 14:21:45 +0200" Message-Id="&lt;F8CFD4D3-64AE-4827-ACD2-7F8BDFEAE94B@censhare.de&gt;" Mime-Version="1.0 (Mac OS X Mail 6.5 \(1508\))" X-Mailer="Apple Mail (2.1508)"/>
        <content type="text/plain; charset=us-ascii">ein Bild

        </content>
        <content type="text/html; charset=us-ascii">&lt;html&gt;&lt;head&gt;&lt;meta http-equiv="Content-Type" content="text/html charset=us-ascii"&gt;&lt;/head&gt;&lt;body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "&gt;ein Bild&lt;div&gt;&lt;br&gt;&lt;/div&gt;&lt;div&gt;&lt;img id="e8c1c476-56bd-4b90-a3a4-91e149516ed6" height="401" width="599" apple-width="yes" apple-height="yes" src="cid:DA4E86F7-9F81-42D2-AED4-523B7DFB9370"&gt;&lt;/div&gt;&lt;/body&gt;&lt;/html&gt;</content>
        <content filename="wedding-kiss.jpg" Content-Type="image/jpg;&#xd;&#xa;&#x9;x-unix-mode=0644;&#xd;&#xa;&#x9;name=&quot;wedding-kiss.jpg&quot;" Content-Disposition="inline;&#xd;&#xa;&#x9;filename=wedding-kiss.jpg" Content-Transfer-Encoding="base64" Content-Id="&lt;DA4E86F7-9F81-42D2-AED4-523B7DFB9370&gt;" url="censhare:///service/filesystem/temp/325563.jpg"/>
    </mail>
</mails>

Note that the mime type derived from content@Content-Type cannot always be successfully matched to an existing censhare MIME-type. You have to work around this yourself in the XSLT.

All headers a verbatim copies of the values received from the E-mail server

Parameters

• context implicitly set
• source mails configuration for account and folder MailService.receiveMail(AXml))

Returns: XML (see example above)

Delete mail (com.censhare.api.Mail.DeleteMail)

Delete mail using the server-side service MailService.receiveMail(AXml).

Example

<cs:command name="com.censhare.api.Mail.DeleteMail" returning=":resultVariable">
    <cs:param name="source">
        <mails account-name="corpus" folder="INBOX">
            <mail id="1"/>
            <mail id="2"/>
        </mails>
    </cs:param>
</cs:command>

Mails Parameters

• account-name account (must exist preconfigured in mail service)
• folder inbox folder, defaults to INBOX.
• id id value as returned from MailService.checkMail(com.censhare.support.xml.AXml)

After successful execution, the input parameter XML is enriched. A new attribute mails@timestamp is set to the timestamp of execution.

Parameters

• context implicitly set
• source mails configuration for account and folder MailService.deleteMail(AXml))

Returns: Source XML

Command handlers

This section describes the XSLT extension to access (censhare 5) command handler methods. With this it is possible to call every execution method (Java method annotated with com.censhare.server.support.api.impl.CommandAnnotations.Execute) of any command handler (Java class annotated with com.censhare.server.support.api.impl.CommandAnnotations.CommandHandler). The syntax here is a bit different from the XSLT commands described above:

<cs:create-command name=":name_of_command_handler" application-asset-id=":context_assed_ID_of_asset_application" returning=":result_of_whole_command">
  <cs:command name=":name_of_command_handler_method" returning=":result_of_method">
    <cs:param name="xml-input">
      <input_parameter_as_XML_node/>
    </cs:param>
  </cs:command>
  <cs:command name=":name_of_command_handler_method">
    <cs:param name="xml-input|json-input" select=":select_of_input_parameter_in_XML_or_JSON_form"/>
  </cs:command>
</cs:create-command>

The actual method call is done in two steps here: First, the command handler itself is created by using the XSL instruction cs:create-command and then one or more methods of this command handler can be called by using the child instruction cs:command. The attributes of the first instruction are

• name: Name of the command handler as set with the command attribute of the Java annotation com.censhare.server.support.api.impl.CommandAnnotations.CommandHandler.
• application-asset-id (optional): This is only needed for the special command handler asset application which needs a context asset for initialization. If this is set the open method of the asset application is automatically called after initialization with the given asset ID. It is designated as an attribute value template, i.e. it is possible to use an XPath expression surrounded by curly brackets like {$assetId} or {asset/@id} as well.
• returning (optional): If given the result of the whole command (which is the concatenation of the result all the child cs:command instructions without returning attribute) is stored in a variable with the corresponding name, otherwise, the result is just returned.

The instruction cs:command has the following attributes:

• name (optional): Name of the command handler method (annotated with com.censhare.server.support.api.impl.CommandAnnotations.Execute) to be executed. It is possible to omit this attribute in case of a command handler with request scope where only one execution method exists and then this method is called.
• returning (optional): If given the result of the method is stored in a variable with the corresponding name, otherwise the result is just returned.

If the command handler method needs an input parameter one cs:param instruction has to be present as a child of cs:command. If no parameter is needed this child node can also be omitted. More than one cs:param children, however, are resulting in an XPath runtime exception. The attributes and child nodes of cs:param are specified as follows.

• name (optional): Here only two fixed values are allowed: xml-input for the input parameter to be specified in XML representation or json-input for the JSON form of it. If the attribute is missing, xml-input is assumed as default.
• select (optional): An XPath expression to select the input parameter in XML or JSON form. Since this is a "select-or-sequence" expression, this attribute may be omitted but then a child node defining the input parameter has to be present.

In the following, some examples for executing a command handler method are given.

Example 1: create a new asset with specified name from template asset

Here a method of a request command handler is called, therefore no method name is needed.

<cs:create-command name="com.censhare.api.dam.assetmanagement.createFromTemplate">
  <cs:command>
    <cs:param name="xml-input">
      <input templateAssetId="35609" newAssetName="Duplicated Asset"/>
    </cs:param>
  </cs:command>
</cs:create-command>

The same command using an input parameter in JSON form would look like this:

<cs:create-command name="com.censhare.api.dam.assetmanagement.createFromTemplate">
  <cs:command>
    <cs:param name="json-input" select="'
      {
        &quot;templateAssetId&quot;: 35609,
        &quot;newAssetName&quot;: &quot;Duplicated Asset&quot;
      }
    '"/>
  </cs:command>
</cs:create-command>

Example 2: move a task in the project editor

Here an asset application command handler method is called which requires a context asset to be given.

<cs:create-command name="com.censhare.api.applications.projectplanning.ProjectPlanningApplication" application-asset-id="71421">
  <cs:command name="setAssetStartEndDate">
    <cs:param name="xml-input">
      <input assetRef="asset/id/71423/version/9" startDate="2016-08-14T08:00:00+02:00" endDate="2016-08-16T08:00:00+02:00" kind="moveRecursive"/>
    </cs:param>
  </cs:command>
</cs:create-command>

Example 3: place a picture using the layout editor and call the renderer

This is an example where two methods of one (asset application) command handler have to be called.

<cs:create-command name="com.censhare.api.applications.layouteditor.LayoutEditorApplication" application-asset-id="10400">
  <cs:command name="placeAsset">
    <cs:param name="xml-input">
      <input documentId="document/10400" placementTargetId="box/b402" assetRef="asset/id/10402/currversion/0" checkBeforePlace="true"/>
    </cs:param>
  </cs:command>
  <cs:command name="callRenderer">
    <cs:param name="xml-input">
      <input documentId="document/10400"/>
    </cs:param>
  </cs:command>
</cs:create-command>

censhare XSLT extensions

cs:diff-items

Calculates the edits required to change one list into another.

Example

<xsl:stylesheet version="2.0"
 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns:cs="http://www.censhare.com/xml/3.0.0/xpath-functions"
 exclude-result-prefixes="xs cs">

 <xsl:output method="xhtml" indent="yes" encoding="UTF-8" omit-xml-declaration="yes"/>

 <xsl:variable name="a" select="tokenize('The quick brown fox jumps over the lazy dog.', ' ')"/>
 <xsl:variable name="b" select="tokenize('The quick fox jumps over the lazy cat.', ' ')"/>

 <xsl:template match="/">
   <!-- equals-function is optional -->
   <xsl:variable name="result">
   <cs:diff-items select-old="$a" select-new="$b">
     <cs:matching-items>
       <xsl:value-of select="."/>
       <xsl:text> </xsl:text>
       </cs:matching-items>
     <cs:deleted-items>
       <span style="background-color:red">
       <xsl:value-of select="."/>
       <xsl:text> </xsl:text>
       </span>
     </cs:deleted-items>
     <cs:inserted-items>
       <span style="background-color:green">
       <xsl:value-of select="."/>
       <xsl:text> </xsl:text>
       </span>
     </cs:inserted-items>
   </cs:diff-items>
   </xsl:variable>
   <xsl:copy-of select="for $x in $result return $x"/>
 </xsl:template>

</xsl:stylesheet>

Output:

The quick <span style="background-color:red">brown </span>fox jumps over the lazy <span style="background-color:red">dog. </span>
<span style="background-color:green">cat. </span>

cs:diff-tree

Performs a tree comparison.

Example

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet  version="2.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:cs="http://www.censhare.com/xml/3.0.0/xpath-functions"
    exclude-result-prefixes="xs cs">

    <xsl:output method="xml" indent="yes" encoding="UTF-8" omit-xml-declaration="yes"/>

    <xsl:variable name="old">
        <test>
            <testkey>
                <test key="1">
                    <testorder>
                        <testorder value2="1" value1="1" />
                        <testorder value2="2" value1="2" />
                        <testorder value2="3" value1="3" />
                        <testorder value2="4" value1="4" />
                        <testorder value2="5" value1="5" />
                    </testorder>
                </test>
                <test key="2" />
                <test key="3" />
            </testkey>
            <testorder>
                <testorder value2="1" value1="1" />
                <testorder value2="2" value1="2" />
                <testorder value2="3" value1="3" />
                <testorder value2="4" value1="4" />
                <testorder value2="5" value1="5" />
            </testorder>
            <testorder-default-compare>
                <testorder value2="1" value1="1" />
                <testorder value2="2" value1="2" />
                <testorder value2="3" value1="3" />
                <testorder value2="4" value1="4" />
                <testorder value2="5" value1="5" />
            </testorder-default-compare>
        </test>
    </xsl:variable>
    <xsl:variable name="new">
        <test>
            <testkey>
                <test key="1">
                    <testorder>
                        <testorder value2="1" value1="1" />
                        <testorder value2="2" value1="3" />
                        <testorder value2="5" value1="5" />
                        <testorder value2="6" value1="6" />
                    </testorder>
                </test>
                <test key="3" />
                <test key="4" />
            </testkey>
            <testorder>
                <testorder value2="1" value1="1" />
                <testorder value2="2" value1="3" />
                <testorder value2="5" value1="5" />
                <testorder value2="6" value1="6" />
            </testorder>
            <testorder-default-compare>
                <testorder value2="1" value1="1" />
                <testorder value2="2" value1="3" />
                <testorder value2="5" value1="5" />
                <testorder value2="6" value1="6" />
            </testorder-default-compare>
        </test>
    </xsl:variable>

    <xsl:template match="/">
        <cs:diff-tree select-old="$old" select-new="$new">
            <cs:order match-new="testorder" match-old="testorder">
                <true />
            </cs:order>
            <cs:order match-new="testkey" match-old="testkey">
            </cs:order>
            <cs:compare match-new="testorder/child::node()" match-old="testorder/child::node()">
                <xsl:param name="old" />
                <xsl:param name="new" />
                <xsl:if test="$old/@value1 =  $new/@value1">
                    <true />
                </xsl:if>
            </cs:compare>
            <cs:compare match-new="testkey/child::node()" match-old="testkey/child::node()">
                <xsl:param name="old" />
                <xsl:param name="new" />
                <xsl:if test="$old/@key =  $new/@key">
                    <true />
                </xsl:if>
            </cs:compare>
            <!--
            <cs:matching-items>
                <matching>
                    <xsl:copy-of select="." />
                </matching></cs:matching-items> 
            <cs:deleted-items>
                <deleted>
                    <xsl:copy-of select="." />
                </deleted> 
            </cs:deleted-items> 
            <cs:inserted-items>
                <inserted>
                    <xsl:copy-of select="." />
                </inserted>
            </cs:inserted-items>
            -->
        </cs:diff-tree>
    </xsl:template>
</xsl:stylesheet>

Result (without cs:matching-items):

<test>
  <testkey>
    <test key="1">
      <testorder>
        <testorder value2="1" value1="1"/>
        <testorder value2="2" value1="2" op="deleted"/>
        <testorder value2="2" value1="3" op="modified"/>
        <testorder value2="4" value1="4" op="deleted"/>
        <testorder value2="5" value1="5"/>
        <testorder value2="6" value1="6" op="inserted"/>
      </testorder>
    </test>
    <test key="3"/>
    <test key="2" op="deleted"/>
    <test key="4" op="inserted"/>
  </testkey>
  <testorder>
    <testorder value2="1" value1="1"/>
    <testorder value2="2" value1="2" op="deleted"/>
    <testorder value2="2" value1="3" op="modified"/>
    <testorder value2="4" value1="4" op="deleted"/>
    <testorder value2="5" value1="5"/>
    <testorder value2="6" value1="6" op="inserted"/>
  </testorder>
  <testorder-default-compare>
    <testorder value2="1" value1="1"/>
    <testorder value2="2" value1="2" op="deleted"/>
    <testorder value2="3" value1="3" op="deleted"/>
    <testorder value2="4" value1="4" op="deleted"/>
    <testorder value2="2" value1="3" op="inserted"/>
    <testorder value2="5" value1="5"/>
    <testorder value2="6" value1="6" op="inserted"/>
  </testorder-default-compare>
</test>

cs:compare has optional mode="node|detail".

cs:level attribute of xsl:message

This extension attribute with local name level in namespace http://www.censhare.com/xml/3.0.0/xpath-functions of the xsl:message instruction, is used to control the level of logging when writing the message. The attribute specification (used as attribute value template) with the ordered (descending) logging level outputs is as follows:

cs:level? = { "off" | "severe" | "warning" | "info" | "config" | "fine" | "finer" | "finest" | "all" }

If the level attribute is missing, the value "info" is taken as default. Since according to the specification in https://www.w3.org/TR/xslt20/#element-message the writing of messages is implementation-defined, it is not mandatory to respect this attribute in the defined writer for the specific XPath context. However, in almost all cases when executing an XSLT in our standard, a default writer is now defined which forwards to a java.util.logging.Logger for logging with the specified level (see XPathContext.setLoggingMessageWriter).

Examples

<xsl:stylesheet  version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:cs="http://www.censhare.com/xml/3.0.0/xpath-functions">

    <xsl:param name="debug" select="true()"/>
    <xsl:param name="level" select="if ($debug) then 'info' else 'fine'"/>

    <xsl:template match="/">
        <!-- Unchanged behaviour when no level attribute is specified: write message by logging with "info" level. -->
        <xsl:message>This is some message text.</xsl:message>

        <!-- New behaviour when level attribute is specified: write message by logging with "fine" level. -->
        <xsl:message cs:level="fine">This is some message text.</xsl:message>

        <!-- New behaviour when level attribute is specified: write message by logging with "warning" level. -->
        <xsl:message cs:level="warning" select="'This is some message text.'"/>

        <!-- New behaviour when level attribute is specified: write message by logging with level as defined by variable. -->
        <xsl:message cs:level="{$level}">This is some message text.</xsl:message>
    </xsl:template>

</xsl:stylesheet>

fn:system-property

Additionally to the standard properties (see fn:system-property) the following censhare specific (proprietary) properties are available (since censhare 4.5.0):

• censhare:party-id, the ID of the current user, in whose context the XSLT/XPath is executed.
• censhare:is-admin-mode, returns true if client runs in administration mode, false otherwise. [Client only]
• censhare:url-prefix, prefix to construct REST-URLs, typically "censhare:///service/". Web-Clients provide different strings including host and port.
• censhare:browser-url-prefix, REST-URL prefix for external or embedded Web browsers, containing the port number of the client's embedded Web server. For example: http://localhost:64496/service/. [Client only]
• censhare:client-type, identifier/type of the client, e.g. "javaclient", "webclient".
• censhare:client-version, version number of the client as string, e.g. "4.5.0".
• censhare:laf-background, look & feel information about the client's appearance. Possible values are "bright" or "dark". [Client only]
• censhare:laf-icon-set, look & feel information about the used icon set. [Client only]
• censhare:server-name, the name of the censhare server.
• censhare:server-version, the version of the censhare server as string, e.g. "4.5.0".
• censhare:host-name, the name of the localhost (machine) where this XSLT/XPath is executed.
• censhare:vfs-version, the current VFS version.

Note: Properties marked with [Client only] are only available if the corresponding XSLT/XPath expression is evaluated by the client or Web client itself. They are empty if the evaluation takes place on the server-side, e.g. when within an asset transformation.

Examples

    system-property('xsl:version')
    -> 2.0
    system-property('xsl:product-name')
    -> censhare XSLT
    system-property('censhare:party-id')
    system-property('censhare:is-admin-mode')
    system-property('censhare:url-prefix')
    system-property('censhare:client-type')
    system-property('censhare:client-version')
    system-property('censhare:browser-url-prefix')
    system-property('censhare:laf-background')
    system-property('censhare:laf-icon-set')
    system-property('censhare:server-name')
    system-property('censhare:server-version')
    system-property('censhare:host-name')

Additional Resources

• censhare XSLT Extensions
• censhare XSLT Commands Training