External Assets XML

Concept

The "External Assets" panel allows a user to drop images from external systems into a document.

Administrators can configure the panel by providing the following URLs:

• Directory List URL: this dynamic page should return XML describing the directories
• Asset List URL: this dynamic page should return XML describing the assets available in a selected directory. The URL can contain %id%, which is replaced by the ID of the selected directory.
• Search URL: the XML format returned is identical to the Asset List URL XML. The search URL can contain %search%, which is replaced by the search term entered by the user
• Post URL: also containing %id% for the selected directory. See lower

Any of the URLs can contain additional replacement patterns: External XML URL replacement

The "External Assets" panel can be found in the default Admin WorkSpace under the "Resources" tab. Depending on the content, this Panel will be visualized in various ways:

• If only a single directory is returned by the Directory List URL, the tree will be hidden, and its content shown immediately
• If no Directory list URL or Search URL is provided (one of both is required), the "Browse" / "Search" navigation will be updated accordingly
• If a Post URL is provided, the "Browse for Local File" button is included in the Panel

There are 2 ways of working with external assets:

• Images are downloaded from the external system into the CHILI Asset Management when requested
• A preview of the image is provided and shown in the document. No download of the original file is made to CHILI Publisher's Asset directories. The original image is only downloaded when needed (f.e. on PDF generation).

The difference between both is made in the xml structure of the feed, an indication is made if the image needs to be downloaded or not.

XML Definitions

Directory XML

<directories>
  <item id="1" name="Main Directory">
    <item id="2" name="Sub Directory 1"/>
    <item id="3" name="Sub Directory 2"/>
  </item>
  <item id="4" name="Main Directory 2"/>
</directories>

The directory XML contains items (in a hierarchical structure) describing the available directories. Each directory requires an "id" and "name" attribute.
The editor will replace "%id%" in the Asset List URL and the Post URL with the value from the attribute "id" of the selected directory.

When only an asset list needs to be made available to the end user, you need to provide a single directory item in your XML.
When a single directory is returned by the Directory List URL, the directory tree in the panel will be hidden the content of the directory is shown immediately

Some attributes can be used on the item level of the directory XML :

• "allowPost" attribute: if "false", posting to that directory is prohibited even if a postURL is provided in the External Assets Panel
• "postURL" attribute: if provided, this overrides the post URL configured in the External Assets Panel for this directory
• "postToChiliDir" attribute: if set to "true", in combination with the "chiliRelativeDirPath" attribute, this will allow upload of files directly to the CHILI DAM, rather than having to go through the Post URL
• "chiliRelativeDirPath": on "item" node of individual directory provides an easy way to load a single directory of CHILI images into the External Assets Panel, without needing to translate XML

Asset XML

<assets>
  <item id="1" name="boober1.jpg" fileName="boober1.jpg" remoteURL="http://my-assets-server/temp/boober1.jpg" thumb="http://my-assets-server/temp/thumb-boober1.jpg" targetPath="TEMP_DOWNLOADS2" reuseExisting="false"  />
  <item id="2" name="boober2.jpg" fileName="boober2.jpg" remoteURL="http://my-assets-server/temp/boober2.jpg"  thumb="http://my-assets-server/temp/thumb-boober2.jpg" targetPath="TEMP_DOWNLOADS2" reuseExisting="true"
 remoteModificationDate="21/03/2012 13:05:10" />
  <item id="3" name="boobertoy.jpg" fileName="boobertoy.jpg" remoteURL="http://my-assets-server/temp/boobertoy.jpg" thumb="http://my-assets-server/temp/thumb-boobertoy.jpg" targetPath="TEMP_DOWNLOADS2" />
  <item id="4" name="boobertoy2.jpg" fileName="boobertoy2.jpg" remoteURL="http://my-assets-server/temp/boobertoy2.jpg"  thumb="http://my-assets-server/temp/thumb-boobertoy2.jpg" targetPath="TEMP_DOWNLOADS2" previewOverrideURL="http://my-assets-server/temp/preview-boobertoy2.png" previewOverrideExtension="png" previewOverrideIsPermanent="true" />
</assets>

The list of assets for a particular directory contains a list items. Each item requires the following attributes:

• id: unique ID of the image
• name: display name for the panel
• fileName: name of the asset when downloaded and inserted into CHILIs Asset Management area
• remoteURL: url (accessible from the server) of the original file
• thumb: url (accessible from the client) of a thumbnail of the file
• targetPath: location in CHILIs Asset Management where the image will be stored. This folder must already exist as CHILI won't make the folder.
• reuseExisting: default = "true". If true, the system will look for an existing resource in CHILI, at the location "targetPath/fileName". If this exists, that resource is reused, rather than having a new version created. Reusing also means the file (or the preview override) is not downloaded
• remoteModificationDate: if provided in combination with 'reuseExisting', the remote asset will be downloaded again (replacing the matching asset in CHILI) if it has been modified since the previous creation/replacement in CHILI's DAM
• previewOverrideURL: optional. a URL to an image which will be used as the preview master see ResourceItemAddPreviewOverride)
• previewOverrideExtension: extension of the preview override file (required if previewOverrideURL is provided)
• previewOverrideIsPermanent: default = "false". Indicates whether or not the preview override is removed when the underlying resource changes

Optional attributes:

• allowDelete: if the current directory is loaded directly from CHILI, and if this attribute = "true", the shown grid allows deletion of the assets (similar to the normal DAM Feed Panel)
• autoRefreshMs: if provided (and numeric and > 0), the results of the last action will be repeated after X milliseconds

It is also supported (in addition to external "item" nodes) to include the definition XML of an asset (as returned by ResourceSearch, ResourceGetTree, etc.) to easily combine existing CHILI assets into the External Assets Panel, without needing to construct other XML

External Asset without downloading XML

<assets>
    <item id="1" name="My image 1" remoteURL="http://www.myurl.com/ServePreview.aspx?img=my_img1&type=%TYPE%&transformationID=%transformationID%" thumb="http://www.myurl.com/ServePreview.aspx?img=my_img1&type=thumb"
    highResPdfURL="http://www.myurl.com/ServePdf?name=my_img1.pdf&quality=%quality%&transformationID=%transformationID%" keepExternal="true" accessibleFromClient="true" >
        <fileInfo width="3064" height="1600" resolution="300" fileSize="2.3MB" />
    </item>
    <item id="2" name="My image 2" remoteURL="http://www.myurl.com/ServePreview.aspx?img=my_img1&type=%TYPE%&transformationID=%transformationID%" thumb="http://www.myurl.com/ServePreview.aspx?img=my_img1&type=thumb"
    highResPdfURL="http://www.myurl.com/ServePdf?name=my_img1.pdf&quality=%quality%&transformationID=%transformationID%" keepExternal="true" accessibleFromClient="true" >
        <fileInfo width="3433" height="2120" resolution="300" fileSize="389KB" />
    </item>
</assets>

The “name” and “thumb” attributes are used to fill the table in the “External Assets” tab (“Resources” pane).

The “remoteURL” is used for previews and only transparent PNGs are allowed. 
The attribute must contain 3 GET parameters:

• “img=[img name]”
• “type=%TYPE%”. The value “%TYPE%” will be replaced automatically with the correct preview type. 
  More info on these can be found here: Webservice DataTypes - previewType
• “transformationID=%transformationID%”. Will be replaced with the ID of a transformation (if the image frame has one).

The script that serves the images in the correct format (with a transformation applied if necessary) to the editor is not provided by CHILI Publish.

The “highResPdfURL” must contain the link to the image (in PDF format), and this will be the image that is used for document PDF generation.

Can contain 2 GET parameters:

• “quality=%quality%”. Image quality as defined in the PDF export settings. Must be original, lowres, lowresbitmaps, medium, thumb, profile.
• “transformationID=%transformationID%”. Will be replaced with the ID of a transformation (if one is defined for the image frame).

The script that serves the PDFs to the CHILI service is not provided by CHILI Publish. When creating one please bear in mind the requested quality and transformation.

The “keepExternal” attributes indicates that an image should not be imported into the CHILI Publisher's Asset directories.

The “accessibleFromClient” indicates whether the images can be accessed from the client

• true: the external image is viewable/downloadable from the client (add CORS headers to the returned image if it's not on the same origin as CHILI publisher)
• false: the external image is not accessible from the client, and should be served using the backoffice preview_external.aspx page (which will be on the same domain, so no CORS involved)

The FileInfo element

<fileInfo width="3433" height="2120" resolution="300" fileSize=1.2MB" />

The resolution attribute indicates at what resolution the external image should be rendered at 100% resize. E.g.: A 2480x2480 pixel image at 300 DPI resolution will render at 8.26 in (209,97mm) if the scale is 100%.
At a resolution of 72 DPI, that same image would be rendered at 34.44 in (874,89mm) if we ask CHILI publisher to scale the image to 100%.

External assets with authentication (eg: cookies or headers)

Client side

When using External assets which require authentication (eg: via cookie or Authorization headers), we are obliged to request the image with the necessary headers, by setting the "crossOrigin" on our image elements to "useCredentials".
This will make the browser forward the existing headers to the domain in the request of the images.
In your existing integration, you will first need to handle the authentication process so your browser has obtained the necessary headers.

To change the way how our editor requests the images, we introduced a soap call "ApiKeySetRequestWithCredentialsForDomain".
As the name illustrates, you can now set the "useCredentials" property once per domain in the APIkey.
The default value is now false, so if not set, images in our image elements are requested as "Anonymous" for the "crossOrigin".

ApiKeySetRequestWithCredentialsForDomain(apiKey, domain, useCredentials)

• apiKey: a valid APIkey
• domain: domain with wildcards ("*", "http//google.com", "*.integration.be")
• useCredentials: true or false

Server side

The PDF generation (which happens server side) should be able to pass the authentication headers to access the given assets (or the PDF generation will return unexpected results).
Headers can be set per domain in the API key by using ApiKeySetRequestHeaderForDomain, with the arguments apiKey, domain, headerFieldKey, headerFieldValue. 

ApiKeySetRequestHeaderForDomain(apiKey, domain, headerFieldKey, headerFieldValue)

• apiKey: a valid APIkey
• domain: domain with wildcards ("*", "http//google.com", "*.integration.be")
• headerFieldKey: The name of the header that you want to set
• headerFieldValue: The value for that header

Load external assets via javascript

Our API allows loading of external assets via JavaScript.
The function is called "LoadContentFromExternalServerXmlString".  It takes an xml file, describing the external asset, as input.

You can find a sample below: 

     var xmlString = '<item id="2" 
                            name="Peter Griffin" 
                            remoteURL="http://192.168.0.52/EA_NEW/Serve.aspx?img=Peter-Griffin-transparant.png&amp;amp;type=%TYPE%"
                            thumb="http://192.168.0.52/EA_NEW/Serve.aspx?img=Peter-Griffin-transparant.png&amp;amp;type=thumb" 
                            highResPdfURL="http://192.168.0.52/EA_NEW/Assets/Peter-Griffin-transparant.pdf" 
                            keepExternal="true" 
                            accessibleFromClient="true"> ' +
                                  '<fileInfo width="397" height="400" resolution="72" fileSize="280 kB" /> ' +
                     '</item>';
      
     function setExternalAssetImage() { 
          SetImageContent(xmlString);
     }


     // Sample code: this will set the external asset on every image frame
     function SetImageContent(assetDefinitionXML) {
          var numFrames = editor.GetObject("document.pages[0].frames").length;
          for (var j = 0; j < numFrames; j++)
          {
               var type = editor.GetObject("document.pages[0].frames[" + j + "].type");
               if (type == "image") { 
                    editor.ExecuteFunction("document.pages[0].frames[" + j + "]", "LoadContentFromExternalServerXmlString", assetDefinitionXML);
               }
          } 
     }

Post URL

If a Post URL is provided in the Panel, a "Browse for local file" button (similar to the DAM Feed panel) is shown to the user. The selected file is uploaded to the Post URL, where an external asset repository can store it in the selected directory.
The file data itself is posted to the URL (in the HTTP form variables as a HTTP POST command) as:

• file_name: the name of the uploaded file
• file_data: the base64 encoded file data

The post URL should return an XML string describing the result, being one of:

• success: an "item" node similar to the one returned by the assets URL (of the newly created asset)
• error: an XML string with an "errorMessage" attribute on the DocumentElement. E.g.: <result errorMessage="Failed to save the file" />