Keepeek Module - Administrator Guide

November 14, 2025

This guide explains how to install and configure the Keepeek Content Picker module in Jahia.

What you'll learn:

  • How to install the Keepeek module
  • How to configure the connection to Keepeek
  • How the integration works behind the scenes
  • How to troubleshoot common issues

Prerequisites:

  • Jahia 8.2.x or higher
  • Active Keepeek account with API access
  • Administrator access to Jahia

Overview

The Keepeek Content Picker module allows you to browse, select, and display media assets from your Keepeek Digital Asset Management (DAM) system directly within Jahia content. This integration enables you to reference Keepeek images and videos without duplicating files, keeping your content lightweight and always up-to-date with your DAM.

Installation

Installing from the Jahia Store

  1. Log in to jContent as an administrator
  2. Navigate to Administration → Server → Modules and Extensions → Modules
  3. Click the Available modules tab
  4. Search for "Keepeek Content Picker"
  5. Click the install icon next to the module
  6. Wait for the installation to complete (you'll see a confirmation message)

Configuration

After installation, you need to configure the connection to your Keepeek account.

Step 1: Access the Configuration Interface

  1. Open Jahia Tools in your browser: https://your-jahia-domain.com/tools
  2. Navigate to Administration and Guidance → OSGi Console
  3. Click OSGi → Configuration in the left menu

Step 2: Configure Keepeek Provider

  1. Find "Keepeek Provider" in the configuration list

    • You can use the search box to filter by typing "keepeek"
    • The PID (identifier) is: org.jahia.modules.dam.keepeek.provider.config

  2. Enter your Keepeek API credentials (provided by your Keepeek administrator):

    backApiAccount = your-api-account
backApiSecret = your-api-secret

  3. Verify the following settings match your Keepeek instance (these are the default values, adjust them if your Keepeek instance uses different settings):

    backApiSchema = https
backApiEndPoint = iconeek.keepeek.com
backApiPath = /api/dam/medias
backApiSignatureBaseUrl = https://iconeek-thumbnails.dam-broadcast.com
backApiSignatureServicePath = /api/dam/services/images/signatures

  4. Configure picker availability (optional):

    frontApplyOnPickers = image,file,video

    This setting controls which Jahia picker types will show the Keepeek option:

    • image - Keepeek appears in image pickers
    • file - Keepeek appears in file pickers
    • video - Keepeek appears in video pickers

    Example scenarios:

    • frontApplyOnPickers = image,video → Keepeek available for images and videos only
    • frontApplyOnPickers = image → Keepeek available for images only
    • frontApplyOnPickers = file → Keepeek available for file pickers only

    If a Jahia property uses an "Image" picker and frontApplyOnPickers contains image, the Keepeek picker will be accessible. Otherwise, it won't appear as an option.

  5. Review the mount point (this is where Keepeek assets appear in Jahia's content tree):

    edpMountPath = /sites/systemsite/contents/dam-keepeek

    ⚠️ Important: This path must be unique across all external providers in your Jahia installation.

  6. Click Save

Step 3: Verify the Configuration

The provider will automatically start if all required settings are correctly configured:

  • backApiSchema
  • backApiEndPoint
  • backApiAccount
  • backApiSecret
  • backApiPath
  • edpMountPath

You can verify the provider started successfully in two ways:

Option A: Check the Logs

Look for this message in the Jahia logs (digital-factory-data/logs/jahia.log):

INFO  [KeepeekDataSource] - Keepeek mount point service started

Option B: Check the Cache Management

  1. Navigate to Administration → Server → System → Cache Management
  2. Search for "EDPKeepeek"
  3. If you see this cache, the provider has started successfully

If the provider didn't start, check that all required fields are filled in, especially backApiAccount and backApiSecret.

Step 4: Enable for Your Site

  1. Navigate to Administration → Server → Modules and Extensions → Modules
  2. Search for "keepeek" in the module list
  3. Find the Keepeek Content Picker module
  4. Toggle the switch to enable it for your site (e.g., "digitall")
  5. Click Save
  6. Reload your browser page to apply the changes

The Keepeek picker is now ready to use in your site's content.

Understanding the Integration

No Binary Duplication

When you select a Keepeek asset in Jahia, the actual file is not copied to Jahia. Instead:

  1. Only a reference is stored in Jahia content

    • Contains the asset ID and optional transformation parameters

  2. The file stays in Keepeek

    • Your Keepeek DAM remains the single source of truth
    • Updates to the asset in Keepeek are reflected in Jahia (subject to cache duration)

  3. URLs are generated on-demand

    • When a page is rendered, Jahia generates the asset URL
    • The URL points directly to the Keepeek CDN

Benefits:

  • Storage efficiency: No duplicate files in Jahia
  • Up-to-date content: Asset updates propagate to all sites (after cache refresh)
  • Centralized management: All assets managed from your DAM
  • Performance: Keepeek's CDN delivers assets globally

Caching Strategy

The module uses caching to optimize performance and reduce API calls to Keepeek.

Asset Metadata Cache

What is cached:

  • Asset properties (title, dimensions, format)
  • Transformation parameters
  • Generated URLs

Cache duration:

  • Time to Live (TTL): 8 hours (default)
  • Time to Idle (TTI): 1 hour (default)

How it works:

  1. First request → Fetches from Keepeek API → Stores in cache
  2. Subsequent requests → Served from cache
  3. Cache expires after 8 hours or 1 hour of inactivity

Note: If an asset is updated in Keepeek, the change will appear in Jahia after the cache expires (up to 8 hours by default).

Cache Management

Viewing the cache:

  1. Navigate to Administration → Server → System → Cache Management
  2. Search for "EDPKeepeek"
  3. View statistics (size, hit rate, misses)

Clearing the cache:

  • Manual: Restart Jahia
  • Automatic: Cache entries expire after TTL/TTI

Adjusting cache settings:

  1. Navigate to OSGi Configuration
  2. Find Keepeek Cache, PID: org.jahia.modules.dam.keepeek.cache.config
  3. Adjust values: 
    edpCacheTtl = 28800    # 8 hours (in seconds)
edpCacheTti = 3600     # 1 hour (in seconds)

Known Limitations

Compatibility Issues

jContent Thumbnails

  • Thumbnails may not display correctly in jContent versions prior to 3.5.0
  • Impact: Assets can still be selected and displayed on pages; only the thumbnail preview is unavailable in the form card view after a Keepeek asset is selected
  • Workaround: No workaround available, update to 3.5.0 is required
  • Fixed in: 3.5.0 (release pending)

CKEditor 5 Support

  • The Keepeek picker is not compatible with CKEditor 5 (CKE5) until the upcoming module version 1.1.0
  • Current support: CKEditor 4 only
  • Expected release: Version 1.1.0
  • Impact: Cannot insert Keepeek assets into CKE5 rich text fields

JavaScript Modules (NPM)

  • Not compatible with @jahia/javascript-modules-library versions prior to 1.1.0
  • Required version: 1.1.0+
  • Expected release: Upcoming version 1.1.0
  • Impact: React/JSX rendering may fail with older versions

Functional Limitations

"Open in New Tab" Not Supported

  • When a Keepeek asset is selected for a weak reference field, the "Open in new tab" context menu option does not work
  • Reason: External assets are not directly browsable in jContent
  • Workaround: View the asset in the Keepeek DAM interface directly

No Direct Asset Editing

  • Assets cannot be edited directly from Jahia (crop/resize must be done during selection)
  • Workaround: Re-select the asset with new transformations, or edit in Keepeek

Cache Delay for Updates

  • Asset updates in Keepeek are not immediately reflected in Jahia due to caching (default: 8 hours)
  • Workaround: Flush keepeek cache or wait for cache expiration
  • See "Cache Management" section above for cache configuration

Limited Video Format Support

  • Only formats supported by Keepeek's transcoding service are available
  • Common formats: MP4 (H.264), WebM, HLS
  • Unsupported: Proprietary or legacy codecs may require re-encoding in Keepeek

No Batch Operations

  • Cannot bulk-select or bulk-transform multiple Keepeek assets at once
  • Workaround: Select and configure assets individually

Troubleshooting

Assets Not Appearing in the Picker

Check these items:

  • Verify backApiAccount and backApiSecret are configured in OSGi
  • Check logs for: INFO [KeepeekDataSource] - Keepeek mount point service started
  • Open browser console (F12) and look for errors

Images Not Loading on the Website

Check these items:

  • Verify property names match your content definition
  • Check logs for "buildSignedUrl returned null" warnings
  • Verify backApiSignatureBaseUrl in OSGi configuration

Slow Performance

Solutions:

  • Increase timeout values in OSGi Configuration (Keepeek Provider): 
    connectionTimeout = 20000
socketTimeout = 60000
  • Check cache hit rate in Cache Management
  • Use resized images instead of originals

Need More Help?

  1. Check Jahia logs
  2. Enable DEBUG logging: OSGi Console → Log Service → org.jahia.modules.dam.keepeek
  3. Contact Jahia Support: https://jira.jahia.org/

Summary

Key takeaways:

  • The module must be installed and configured before use
  • API credentials are required to connect to Keepeek
  • The provider starts automatically when all required settings are configured
  • Caching optimizes performance (8-hour default TTL)
  • Assets are referenced, not duplicated

For usage instructions, see the Using Keepeek Assets Guide.