Developer’s Guide
How to Develop a Communiqué Digital Asset
Management Solution
1 PURPOSE 3
2 CQ DAM OVERVIEW 4
2.1 2.2 Key CQ DAM Features 4
2.2 How CQ DAM Works 6
2.2.1 Unified Architecture 7 2.2.2 Asset Structuring 7 2.2.3 Ease of Use 7 2.2.4 Performance 8 2.2.5 Extensibility 8 3 CQ DAM COMPONENTS 9 3.1 Servlet Engine 9
3.2 Java Runtime Environment 9
3.3 JavaServer Pages (JSP) compiler 9
3.4 CQ DAM Web Application 9
3.5 CQ DAM Managing Rights 10
4 CQ DAM SUPPORTED FILE TYPES 11
4.1 Audio Files 11
4.2 Document Files 11
4.3 Graphics Files 11
4.4 Supported video files 12
5 CQ DAM ARCHITECTURE 13
5.1 OSGi (Apache Felix) 13
5.2 Project Sling 15
5.3 Graffito’s JCR mapping 15
5.4 CQ DAM WebApp 15
5.5 CQ DAM Content Sharing with JCR 16
6 COMMUNIQUÉ AND CQDAM INTEGRATION 17 7 CQ DAM ADMINISTRATION 22
7.1 CQSE Administration Console 22 7.2 Sling Management Console 22
7.3 CRX Explorer 23
8 CQ DAM EXTENSIONS 24
8.1 Maven2 24
8.2 Eclipse IDE 24
8.3 CQ DAM Extension Development Setup 25 8.4 CQ DAM Extension Examples 25 8.4.1 Adding a Media Handler 25
8.4.2 Adding an Exporter 28
1 Purpose
This guide describes development procedures and examples.
This guide is part of the CQ DAM documentation set, which includes the following documents:
• CQ DAM Installation Guide • CQ DAM User Guide • CQ DAM Developer Guide
If you need further support, contact Day Support at http://daycare.day.com.
Note: When you contact support, you need your product
information, including version number, which is found under About in CQ DAM for product information.
2 CQ DAM Overview
Communiqué Digital Asset Management (CQ DAM) provides enterprise-wide sharing and distribution of an organization’s key digital assets. Users across an organization can store, manage, and access digital assets such as images, graphics, audio, video, and documents through a Web interface.
CQ DAM is part of Day’s Communiqué enterprise content
management suite. It is a standalone digital asset management solution that fully implements the Java Content Repository (JCR).
Note: JCR describes a content repository that is based on JSR-170.
2.1 2.2 Key CQ DAM Features
The following table provides information about key CQ DAM features.
Feature Description Web Browser-based
User Interface
CQ DAM provides an easy-to-use interface with extensive drag and drop support through a Web browser
Here, you can add, view, and share images, documents, audio files, and video files in a variety of file formats. WebDAV and CIFS CQ DAM provides file-system
independent protocols to map the repository as a web folder (WebDAV) or standard drive (CIFS). You can also access assets through the CRX browser. Graphics Support CQ DAM automatically generates
Feature Description Audio Support CQ DAM automatically generates
thumbnails from embedded images. You can import an extensive variety of audio formats. CQ DAM extracts and organizes ID3 tags into an appropriate metadata structure.
Document Support CQ DAM is compatible with a variety of document formats, including Adobe PDF, MS Office, and Quark Express.
Organization Support To help organize assets, CQ DAM provides folders and tags. Assets can have tags so that they can be put into any number of “virtual” folders, keeping only one physical copy. You can also “star” your favorite assets and build a collection of assets using the “tray.” Searching Functionality CQ DAM automatically indexes
documents when they are imported and extracts metadata, enabling full-text searches in documents, as well as keyword searches in metadata or taxonomy.
Process Support CQ DAM provides a workflow and
notifications functionality. Use workflows and notifications to allow joint processing and downloading of any set of assets and to manage access rights to assets.
Collaboration Support CQ DAM provides Lightbox functionality to share assets and anonymously upload assets. You can add annotations to assets.
Feature Description
Metadata Support CQ DAM extracts and indexes metadata from all digital assets while importing. You can add or edit asset metadata information. In addition, you can extend the list of available metadata for any asset type. Metadata is automatically versioned together with the
corresponding asset. Information about digital rights connected to the assets is maintained as a specific type of
metadata. Importing and
Exporting
CQ DAM supports the WebDAV protocol. Import and export multiple digital assets simultaneously using a WebDAV folder. CQ DAM provides XML import and export functionality. You can also download thumbnails, results (metadata), and high-resolution binaries.
Versioning CQ DAM uses JCR versioning functionality for consistent versioning of all digital assets. Versioning creates a snapshot of digital assets at a specific point in time. Logging CQ DAM logs all relevant activities on the
system for later reference.
Security CQ DAM provides DAM-specific rights to metadata, high resolution binaries, and thumbnails, and CRX-specific rights. Preferences You can change the CQ DAM display
2.2.1 Unified Architecture
Assets and their metadata are stored in one location in a standard-compliant way. As a result, users access and manipulate all types of data in CQ DAM’s repository in a standardized way. In addition, any JCR-compliant tool can access the information.
In CQ DAM, content is ordered hierarchically by using nodes and node properties. A node has a primary node type and may have additional node type extensions. As a result, content is classified by node type. For example, there are predefined node types for video, image, or audio files. Each node type includes associated node properties to store the metadata for the asset.
By contrast in a traditional database solution, metadata is stored separately from each asset through the use of tables.
2.2.2 Asset Structuring
Each asset in a JCR repository has an associated node type, which can be used to define the asset type. To add new asset types in CQ DAM, you simply create a new node type.
In a traditional database solution, adding a new asset type means adding a new table and changing the application to support that table.
Because CQ DAM uses a JCR, any JCR-compliant tool is
automatically enabled to use the new node types. In addition, node type definitions contain the associated metadata information and can be easily changed.
CQ DAM does not enforce storing assets in a structured way although you can structure assets, for example, by company division or office location. The hierarchical structure makes it easy to navigate through assets.
2.2.3 Ease of Use
You can easily mount CQ DAM in your file system by using a CIFS drive (recommended) or a WebDAV folder, which lets you drag and drop your structured or unstructured assets into the repository. For example, you can drag an entire tree of files from your files system into the repository and DAM analyzes the contents and assigns the JCR node types accordingly, wherever possible. After you drag and drop your assets into the repository, you can restructure the files by moving them around or you can keep the current structure.
2.2.4 Performance
CQ DAM uses cross-references, which means that a node may have properties referring to other nodes. Cross-references in CQ DAM can create fast, multidimensional taxonomies.
Taxonomies are similar to the tree/folder structures available in a file system. In addition to the predefined taxonomies, users can create their own taxonomies and then classify any assets using the newly created taxonomy.
Taxonomies are stored in a special node in the repository. Any asset classified in a particular taxonomy is classified as a reference. When you search for an asset by taxonomy, you are simply
retrieving the corresponding taxonomy node from the repository along with all referenced assets.
Searching references in CQ DAM is an operation that moves from asset to asset very quickly. On the contrary, in a traditional
database, searching for assets requires the joining of all tables that store asset information, which is labor- and time-intensive.
2.2.5 Extensibility
You can extend CQ DAM's functionality in a variety of areas by writing plug-ins. With these plug-ins, CQ DAM can extend its
capability of extracting metadata and thumbnails, exporting assets, or converting assets from one format to another.
You can add the extensions through Sling at Runtime. CQ DAM does not require a restart of the servlet engine.
In CQ DAM, you can extend the user interface by doing one of the following:
• Media handlers can extract metadata and thumbnails from their respective media format.
• Exporters can export selected assets in any format; for example, CQ DAM could “zip” (compress and bundle) files together or send them in an email.
3 CQ DAM Components
CQ DAM runs as a Web application on a Web server. The installer that comes with CQ DAM installs the following components:
• A servlet engine: The servlet engine runs the servlet. It can be part of an existing Web server or it can have its own server. • A Java Runtime Environment (JRE): The JRE consists of the
Java Virtual Machine and the API. In addition, you can use an existing JRE and deploy it in a third-party servlet container. • JavaServer Pages (JSP) compiler: The JSP compiler parses JSPs
and transforms them into JavaServlets.
• The CQ DAM Web Application: The .war file contains the CQ DAM repository and the CQ DAM Web interface.
3.1 Servlet Engine
The servlet engine runs Java servlets and Java server pages, such as the CQ DAM application. There are three ways to set up a servlet engine:
• Some Web servers contain a servlet engine by default, so you do not need to install anything. Web servers that come with a servlet engine include Sun's Java Web Server (JWS), W3C's Jigsaw, Apache Tomcat, and Gefion Software's LiteWebServer (LWS).
• For other Web servers, you can add the servlet engine as an add-on module. Web servers that require this include
Netscape's Enterprise Server, Microsoft's Internet Information Server (IIS), and the Apache Group's Apache.
• Or you can use the CQ DAM servlet engine that comes with the installer.
3.2 Java Runtime Environment
To use CQ DAM, you need a Java Runtime Environment, which includes the JVM to execute the Java code and an API.
3.3 JavaServer Pages (JSP) compiler
The JSP is included in the CQ DAM installer. It parses JSPs and transforms them into JavaServlets.
3.4 CQ DAM Web Application
The CQ DAM application servlet (.war file) contains the CQ DAM repository and the web interface.
3.5 CQ DAM Managing Rights
Digital Rights Management controls access to or usage of digital data and to restrictions associated with a specific instance of a digital work or device. Digital data includes Internet music, audio CDs and movies.
4 CQ DAM Supported File Types
This section describes all the file types that CQ DAM supports.
4.1 Audio Files
Extension Definition
.mp3 MPEG-1 Audio Layer 3 audio format .wav Waveform audio format
.wma Windows Media Audio format
4.2 Document Files
Extension Definition
.pdf Adobe’s Portable Document Format .doc Microsoft Word document
.pps Microsoft PowerPoint Show document .ppt Microsoft PowerPoint document .qxd QuarkXPress 4.x document
.txt Text document
.xls Microsoft Excel document
4.3 Graphics Files
Extension Definition
.gif Graphics interchange format
.jpeg Joint photographic experts group format .jpg Joint photographic experts group format .png Portable network graphics format
Extension Definition
.psd Adobe Photoshop document .tif Adobe’s tagged image file format
4.4 Supported video files
Extension Definition.avi Microsoft’s Audio Video Interleave
5 CQ DAM Architecture
This section describes the main features of CQ DAM’s architecture, including:
• OSGi (Apache Felix) • Project Sling
• Graffito’s JCR mapping • CQ DAM WebApp
5.1 OSGi (Apache Felix)
The OSGi Alliance, which once was the Open Services Gateway initiative, is an open standards organization founded in March 1999. The Alliance and its members specified a Java-based service
platform that is managed remotely. The core part of the
specification is a framework, which defines an application life cycle model, and a service registry. Based on this framework, most OSGi layers, APIs, and services are defined, including:
• Security, module, life cycle, and service layers • Framework APIs
• Package administration service • Start level service
• Conditional permission administration • Permission administration service • URL handler service
• Log service
• HTTP service (runs servlets) • Device access
• Configuration administration service
The following illustration shows how OSGi fits within the architecture.
The OSGi framework implements a complete and dynamic component model, which is missing in standalone Java/VM
environments. Applications or components (for example, bundles) are installed, started, stopped, updated, and uninstalled remotely without requiring a reboot. Life cycle management is done via APIs, which allow for remote downloading of management policies. The service registry allows bundles to detect new and deleted services and adapt accordingly.
This framework has the following benefits.
• Helps developers to build structured application thru bundles • Resolves application dependencies (using JAR version
information)
• Makes deployment easier • Controls class loaders better
5.2 Project Sling
Project Sling is foundation of the next generation of Day’s Software suite, which includes Communiqué 5, CQ DAM, and CRX Explorer. It is composed of a set of bundles, which provide a set of ready-to-use components and services.
Project sling is built with the new component API derived from the portlet API specification. The component API has new key
functionality including: • Persistence abstraction
• Content centric web applications • Structure page layout
Developers can create their own Sling components and services and deploy the as bundles or assemblies.
5.3 Graffito’s JCR mapping
Project Sling integrates with Graffito‘s JCR mapping. Graffito is an open source framework used to build content based applications such as, content management, document management, forums, blogs and WIKIs.
The Graffito project also contains standalone JCR tools such as, object-content mapping frameworks and JCR node type
management. These tools are used in some projects without the complete Graffito stack. For more information about Graffito, please check the apache website at http://incubator.apache.org/graffito. The Graffito project has new key functionality including:
• Code maintenance assistance through mapping JCR content into Java Object
• Maps JCR content to Sling components
5.4 CQ DAM WebApp
With one .war file, a CQ DAM developer can: • Define OSGi Bundles Repository (OBR) • Initialize OSGi framework and services • Start bundles and assemblies
• Uses a foreign JCR repository or an embedded CRX repository The following illustration shows how CQ DAM WebApp integrates into a servlet engine.
5.5 CQ DAM Content Sharing with JCR
6 Communiqué and CQDAM Integration
This section describes how to install and configure the CQ DAM integration into Communiqué. The following illustration shows how Communiqué and CQDAM are integrated.You must be running Communiqué 4.2, however, CQ DAM and Communiqué can be installed on separate servlet engines.
1. Copy the file nbc-poc-0.2.jar into author/bin/lib. 2. Copy the file crx-rmi-1.3.2.jar into author/bin/lib. 3. Install the package dam-integration.20070529.cq.
4. Install the package dam-integration-config.20070529.cq. 5. Edit the following configuration files:
/config/delivery/dam-connector.xml: this file contains the URL to the CQ DAM repository. The sample configuration will connect to the DAM repository at
rmi://localhost:11599/repository and map the nt:folder and nt:file nodes under /damRoot/data to
/etc/medialib/dam.
/config/delivery/referenceresolver.xml: this file contains all registered reference resolvers. You do not have to change anything here, unless you want to configure an additional resolver.
/config/delivery/delivery-sample.xml: this file is a sample configuration that shows which services you need to add, such as: <service class="com.day.cq.poc.nbc.ReferenceResolverService" config="referenceresolver.xml"/> <service class="com.day.cq.poc.nbc.DAMConnectorService" config="dam-connector.xml"/>
Note: To get more information about the synchronization process you can set the log level for the category ems-connector to DEBUG.
6. If you are running CRX on a different host than Communiqué, set the rmi host system property for the JVM where CRX is running, for example:
-Djava.rmi.server.hostname=192.168.1.100 7. Restart Communiqué.
The following illustrations show how CQ DAM integrates with Communiqué.
There are no changes for Authors, they still select and store the referenced media the same way.
Media library documents are references to a CQ DAM asset (dam://{uuid}).
7 CQ DAM Administration
This section describes CQ DAM administration.
7.1 CQSE Administration Console
Access the Communiqué servlet engine administration console at
http://localhost:8080/admin, after CQ DAM installation.
Use the administration console to deploy new Web applications, for example CRX Explorer, and to control the server status.
7.2 Sling Management Console
Access the Sling management console at
7.3 CRX Explorer
Install CRX Explorer on http://localhost:8080/crx.
CRX Explorer uses RMI access to the shared JCR repository. You can use CRX Explorer with CQ DAM to:
• Manage CQ DAM users and groups • Manage CQ DAM workflows
• Share CQ DAM content using CIFS (recommended) or WebDAV • Extend the CQ DAM application.
8 CQ DAM Extensions
This section describes CQ DAM extension and provides examples.
8.1 Maven2
Maven is a software project management and comprehension tool. It is based on the concept of a Project Object Model (POM). It can help you manage a project’s build, reporting, and documentation from a central piece of information. For more information about Maven, please check to Apache Website at:
http://maven.apache.org.
Maven2 has a simple project setup, which follows best practices and allows you to get a new project or module started in seconds. As it has consistent usage across all projects, you do not need any training time when new developers coming into a project.
Maven2 has superior dependency management including automatic updating and dependency closures (also known as transitive
dependencies). You can work with multiple projects at the same time and extend Maven2 with plug-ins in Java or scripting languages.
As Maven is open source, there is a large and growing repository of libraries and metadata to use out-of-the-box.
To build a new extension for CQ DAM, you must use Maven2. With Maven2, you can easily generate a bundle or assembly, using Day’s plug-in. This allows you to use Day’s Maven2 central repository of JARs.
You can also generate the Eclipse project or create your own Maven2 plug-in to automate tasks.
8.2 Eclipse IDE
Eclipse IDE is an open source community with projects focused on building an open development platform comprised of extensible
8.3 CQ DAM Extension Development Setup
To extend CQ DAM, you must first setup your development environment, to do so, follow the steps below.
1. Download and install Maven2 (2.0.x).
2. Setup your Day Maven central repository as the alternate central repository (For example settings.xml in the .m2 folder).
3. Download and install Eclipse IDE (3.2.x).
4. Optional (but recommended), install Maven2 plug-in for Eclipse 5. Optional (but recommended), install JCR plug-in from Day
Software.
6. Create a new folder
7. Create the POM.xml file within the new folder.
8. Run the following command to build the Eclipse project file. mvn eclipse:eclipse
9. Import the newly created project into the Eclipse workspace. 10. Setup the Eclipse build path additional variable M2_REPO to your
Maven2 local repository folder.
11. Run the following command to build the JAR bundle mvn package
Note: You can also use Maven2 external tools in Eclipse to build the JAR bundle from the IDE.
12. Install the bundle using the Sling management console or using mvn and specify the plug-in.
8.4 CQ DAM Extension Examples
This section provides extension examples.
8.4.1 Adding a Media Handler
To handle new assets, types, and formats add a media handler following the steps below.
1. Create a Service that implements
com.day.cq.dam.MediaHandler, for example, com.day.cq.dam.media.AbstractMediaHandler.
2. Use the following code to define the service (scr) properties to be extracted by the Maven bundle plug-in.
/**
* <code>MyHandler</code>... *
* @scr.component immediate="true"
* label=“MyHandler" description=“My handler" *
* @scr.service interface="com.day.cq.dam.MediaHandler" *
*/
3. Implement extractMetadata(...), and any other methods such as exportMedia(...) and createThumbnails(...). 4. Build the media handler bundle.
5. Install the media handler bundle. 6. Add (import) a new media type.
7. Implement the getDetailToolbarItems() to customize the details view. /** * @see com.day.cq.dam.media.AbstractMediaHandler#getDetailToo lbarItems() */
public ToolbarItem[] getDetailToolbarItems() throws MediaException {
ArrayList list = new ArrayList();
ToolbarButton b1 = new ToolbarButton(); b1.setName("viewText"); b1.setText("Content"); b1.setAltText("View content"); b1.setIconPath("/dam/imgs/toolbar/text_view.gif"); b1.setSmallIconPath("/dam/imgs/menu/text_view.gif"); b1.setAction("setToolboxInnerSrc('zip.jsp')"); list.add(new ToolbarSeparator("s0")); list.add(b1);
8.4.1.1 Media Handler Administration
Once you installed a media handler, you can manage it with the administration Web GUI, which is available at
http://localhost:8080/dam/home/mediahandler.
The administration Web GUI allows you to enable and disable any registered media handlers for handling specific mime types.
8.4.2 Adding an Exporter
Adding an exporter allows users to export selected assets. The CQ DAM Exporter is available in the CQ DAM Web GUI context menu. You can write and Exporter for many tasks, such as format conversion, image processing, PDF generation, and .zip file downloads.
1. Create a service that implements com.day.cq.dam.export.Exporter.
2. Use the following code to define the service (scr) properties to be extracted by the Maven bundle plug-in.
/** *
* @scr.component immediate="true"
label="SampleConverter" description="Sample Converter" * @scr.property name="dam.exporter.iconpath“
value="/dam/imgs/menu/package.gif";
* @scr.property name="dam.exporter.smalliconpath“ value="/dam/imgs/menu/package.gif";
* @scr.property name="dam.exporter.text" value="Download sample..."; * @scr.property name="dam.exporter.alttext" value="Download sample…"; * * @scr.service interface="com.day.cq.dam.export.Exporter“ */
3. Implement the export(...) remark so you can create a new asset instead of a normal download.
4. Build the exporter bundle. 5. Install the exporter bundle.
6. Select one or more assets and right-click
7. In context menu, select the new exporter Download sample....
The Download sampl... is now visible in the context menu. The result can either be a direct download or stored again as a new asset in CQ DAM.
Note: If it‘s stored in CQ DAM it usually falls under the
rendition. Therefore, simply click on View Renditions...
8.4.3 Extending CQ DAM Web GUI
You can extend the CQ DAM Web GUI and write your own custom application, based on Sling components. CQ DAM’s Web GUI has numerous nodes located under the \home node and uses Sling scripted components.
You can extend the CQ DAM Web GUI by creating or overriding Sling components under /apps/dam.
You can map Sling components into Java Object with Graffito JCR Mappings, for example:
<?xml version="1.0" encoding="ISO-8859-1"?> <graffito-jcr> <class-descriptor className="com.day.cq.dam.component.DamScriptContent" jcrNodeType="dam:DamScript" discriminator="false" >
<field-descriptor fieldName="jspComponentPath" jcrName="dam:jspComponentPath" />
</class-descriptor> </graffito-jcr>
You can create your own Sling components or reuse CQ DAM predefined components such as, DamScript.
A bundle can install in the CQ DAM repository using JSON Object notation or XML, and can include any additional files such as, jsp, docroot, gif, and jpg.
Extension of the Web GUI requires knowledge of the new Sling component, Graffito JCR mapping. You can then add new entries to the site structure to map new components (DamScript) under /apps/dam.
8.4.3.1 Extending the Navigation tab
This example shows the results of extending the Navigation Tab to add a new function.
8.4.3.2 Extending the Detail’s View
This example shows the results of extending the Details view‘s Toolbox to add, for example, a Content view button to display the content of the selected media. The following illustration shows the list of files contained in the zip file.
