(1.3)

# Working with External Assets

CHILI publisher's "External Assets" is one resource for image files that can be accessed when creating and customizing a CHILI document.
This 4App allows tagging and filtering 4ALLPORTAL DAM images and import them to a CHILI document. Results can be filtered on a user-specific basis by mapping user data from an external (shop) system with your 4ALLPORTAL.

Please note: Working with "External Assets" requires an already configured secret.

# How Does it Work?

In order to import images as External Assets, you create an asset filter in the 4ALLPORTAL. By doing so, you generate two filter-specific API endpoints (Asset List URL and Directory List URL). Use them to link this filter with a document in the CHILI publisher.

As soon as the External Assets of a document are requested, CHILI publisher calls the linked 4ALLPORTAL API endpoint (Asset List URL) and gets all images that result from this filter and stores them in its DAM Feed.

Your filter can also consider specific parameters and user data. For this, the Asset URL includes a variable for a secure web token to encode and decode parameters or sensitive user data. The variable is filled by CHILI publisher, generating a secure token using your defined parameters (e.g. a logged-in user's credentials) automatically. The 4ALLPORTAL maps and decodes this information and CHILI only offers assets that meet the conditions.

CHILI DAM Feed

CHILI publisher does not request images from the 4ALLPORTAL directly. In order to access an asset faster, CHILI stores all assets with own item IDs into its own DAM Feed. Also, the previews you see in the templates are CHILI own previews. CHILI checks for asset updates automatically and updates its DAM Feed accordingly.

With the default connector, an asset is updated when:

  • it is created or deleted
  • its name, mount, or path changed
  • the preview is recalculated

# Step 1: Define your Use Case

Before you create a filter, think about your desired search result: What kind of External Assets do you need in a CHILI document? Do you need a broad image selection for your graphic designer to initially create a template? Or do you want to offer only specific images, e.g. only for users of a certain company, or only for logged-in John Doe?

# Step 2: Create an External Assets Filter

Open your 4ALLPORTAL, navigate to module General/External Assets Filter and choose Create in your toolbox for a new filter:

field description example
Filter name enter a name (special characters, spaces and upper case are not supported), this name will be used as URL path variable (more details) mood_images
Description give a description Mood images free for all users
Metadata filter enter the conditions you want to use for filtering as XML (more details about conditions) (opens new window) example filter
Download profile choose the download profile with which CHILI shall get the assets (you can enter the name of any available download profile in your system) large (default)
Target directory for CHILI publisher DAM Feed add the folder in the CHILI publisher own DAM Feed where the resulting files from this filter should be downloaded at (CHILI creates this folder automatically) 4allportal/external_assets/mood
Personalization filter enter the conditions you want to use for filtering via Token claims as XML (more details about conditions) (opens new window) example filter
  • Switch Reuse existing files: default = "false". If true, the system will look for an existing resource in CHILI, at the location "TargetDirectory/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.
  • Switch Update previews in CHILI publisher: default = "false". Indicates whether or not the preview override is removed when the underlying resource changes.

When you are done, save your settings.

# Asset Filter: Static Results

The specifications you make in section Asset Filter do the same as our "Saved filter" function, where you store a performed search. The settings made here produce a general filter result without considering personalized data. Use it to get a broad selection in a CHILI document, e.g. for your graphic designer to create a template or for images all users may access.

For this, you need to define a Metadata filter condition. CHILI then gets all filtered assets and downloads them in the chosen quality to the chosen folder of its DAM Feed.

Please note: In case no Metadata filter or Personalization filter is specified, all your assets will be exposed, so be sure to configure your conditions correctly.

# Default Metadata Field for Tagging

With this 4App comes a default metadata field for CHILI related tagging: Navigate to an asset's detail view and add a keyword to field Keyword for the asset filter (technical name: chili_tag, allows only strings) in panel CHILI Publisher Integration:

This asset could now be filtered via an External Asset Filter by defining it as condition in field Metadata filter like this:

<conditions>
    <condition>
        <sql>`chili_tag` = 'mood'</sql>
    </condition>
</conditions>

Please note: Metadata field chili_tag is only a default. You can use any metadata field from the file module to create a filter, e.g. filtering for an entry from a general field "keywords", or an entry from a field "photographer" or "company".

# Personalization

If you want to specify a filter result on a user or use case specific basis, make additional settings in section Personalization.
Map parameters, e.g. user data, from your external (web shop) system with the corresponding contents from a metadata field in your 4ALLPORTAL, if you want these parameters to match before making the filter assets available in a CHILI document.

In field Personalization filter, you can add a list of conditions to filter fields from your external system with 4ALLPORTAL fields.
Your external fields can be configured in the condition and be called as a Template-Expression. e.g. {FIELD_NAME}.

The settings made here produce personalized filter results that differ with every use case or logged-in user. Use it to get only a specific selection of user, target group or use case restricted images.

# Example Filter with Personalization

You designed a template for a business card with the option to personalize. Use External Assets to offer a logged-in user all employee profile images of their company.

Metadata filter settings

<conditions>
    <condition>
        <sql>`image_type` = 'portrait'</sql>
    </condition>
</conditions>

Personalization filter settings

For this mapping:

Parameter mapping Comparator Metadata field
company EQUAL company_name
position EQUAL title_job
max_size_image LESS THAN width

use this condition:

<conditions>
    <condition>
        <sql><![CDATA[ `company_name` = '{company}' AND title_job = '{position}' AND {max_size_image} < width ]]></sql>
    </condition>
</conditions>

If you personalize a filter like this, CHILI only offers images

  • where the shop user's company name is found as a value in metadata field "company_name"
  • where the shop user's position is found as a value in metadata field "title_job" (e.g. "Marketing")
  • which width is not higher than the shop defined maximal size (in order to prevent too large job files)

A user must thus be member of a certain company and member of the marketing department to access all profile images.

Find more example use cases here.

Please note: In order to map data, make sure the values are identical in both external (shop) system and 4ALLPORTAL. For user-specific filtering, a shop user must also be registered in your 4ALLPORTAL with an identical id, lastname, company name, etc.

# URL Usage

As soon as you saved your filter, you find new section URL Usage just below your filter's properties. These filter-specific URLs generate automatically and are the filter-specific API endpoints CHILI publisher must call to get the filter's results. They consist of:

  • your base URL (https://example.4allportal.com)
  • 4ALLPORTAL API endpoint (chili/api / chili/api/directories)
  • filter name ({filter_name}) - only Asset List URL
  • filter results (assets?) - only Asset List URL
  • token (token={token}) - only Asset List URL

Examples:

  • Asset List URL: https://example.4allportal.com/chili/api/mood_images/assets?token=%token%
  • Directory List URL: https://example.4allportal.com/chili/api/directories

These URLs must now be added to the External Assets of a CHILI publisher document.

Follow these steps to test your Asset List URL.

# Step 3: Add a Filter to CHILI Publisher

  1. Start your CHILI publisher and open the document in which you want to access a filter's results.
  2. Go to tab Resources on the left side and click the pencil (mouseover) on the right side of panel External Assets.
  3. The "Properties: External Assets" menu opens.
  4. Add Asset List URL and Directory URL from your filter to fields Asset List URL and Directory List URL.
  5. Close the pop-up window.

You can now access the filter's results in this document.

# Personalize Single Frames

Following the above steps, you link an asset filter to a whole CHILI document. However, you can also use different kinds of personalization levels in one document and add your API endpoints only to certain frames.

# Example Use Cases

# Example 1

Your graphic designer wants to create a template for a travel agency flyer. They need all available images from your 4ALLPORTAL on the subject of Italy in CHILI. To get a general result, create a filter like this:

Asset Filter settings

<conditions>
   <condition>
      <value1 type="field">
         <value>location</value>
      </value1>
      <operator>EQUAL</operator>
      <value2>
         <value>Italy</value>
      </value2>
   </condition>
</conditions>

OR

<conditions>
  <condition>
    <sql>`location` = 'Italy'</sql>
  </condition>
</conditions>

Personalization settings

Because you do not need any personalization, leave it empty.

# Example 2

Your Italy flyer template is available in your web shop. You want to offer all partner travel agents a personalization with images only from hotels they actually work with. To get user-specific results, create a filter like this:

Asset Filter settings

<conditions>
   <condition>
      <value1 type="field">
         <value>location</value>
      </value1>
      <operator>EQUAL</operator>
      <value2>
         <value>Italy</value>
      </value2>
   </condition>
</conditions>

OR

<conditions>
  <condition>
    <sql>`location` = 'Italy'</sql>
  </condition>
</conditions>

Personalization settings

<conditions>
   <condition>
      <value1 type="field">
         <value>travel_agency</value>
      </value1>
      <operator>EQUAL</operator>
      <value2>
         <value>{company_name}</value>
      </value2>
   </condition>
</conditions>

OR

<conditions>
  <condition>
    <sql>`travel_agency` = '{company_name}'</sql>
  </condition>
</conditions>

In this case, the asset filter gets all Italy images. The personalization filters only images that are tagged with the logged-in users company in a field "travel_agency" (which you fill at every hotel image).

# Example 3

You also offer promotional gifts travel agents can personalize with their logo. Depending on the chosen product (a ball, a mug, a cap etc.) and the chosen color, you offer the printable images.

Asset Filter settings

<conditions>
   <condition>
      <value1 type="field">
         <value>image_type</value>
      </value1>
      <operator>EQUAL</operator>
      <value2>
         <value>logo</value>
      </value2>
   </condition>
</conditions>

OR

<conditions>
  <condition>
    <sql>`image_type` = 'logo'</sql>
  </condition>
</conditions>

Personalization settings


<conditions>
  <condition>
    <value1 type="field">
      <value>travel_agency</value>
    </value1>
    <operator>EQUAL</operator>
    <value2>
      <value>{company_name}</value>
    </value2>
  </condition>
  <condition>
    <value1 type="field">
      <value>product_type</value>
    </value1>
    <operator>LIKE</operator>
    <value2>
      <value>{product_group}</value>
    </value2>
  </condition>
  <condition>
    <value1 type="field">
      <value>color_detection</value>
    </value1>
    <operator>NOT EQUAL</operator>
    <value2>
      <value>{color}</value>
    </value2>
  </condition>
</conditions>

OR

<conditions>
  <condition>
    <sql>`travel_agency` = '{company_name}' AND `product_type` LIKE '{product_group}' AND `color_detection` NOT EQUAL '{color}'</sql>
  </condition>
</conditions>

In this case, the asset filter gets all logos. The personalization filters only logos of the logged-in user's agency, only logos that are tagged with the fitting product_type and only logos that do not have the same color as the gift's main color.

← Working with External Snippets →

Request missing documentation