Developer s Guide. How to Develop a Communiqué Digital Asset Management Solution

Transcription

1 Developer s Guide How to Develop a Communiqué Digital Asset Management Solution

2 1 PURPOSE 3 2 CQ DAM OVERVIEW Key CQ DAM Features How CQ DAM Works Unified Architecture Asset Structuring Ease of Use Performance Extensibility 8 3 CQ DAM COMPONENTS Servlet Engine Java Runtime Environment JavaServer Pages (JSP) compiler CQ DAM Web Application CQ DAM Managing Rights 10 4 CQ DAM SUPPORTED FILE TYPES Audio Files Document Files Graphics Files Supported video files 12 5 CQ DAM ARCHITECTURE OSGi (Apache Felix) Project Sling Graffito s JCR mapping CQ DAM WebApp CQ DAM Content Sharing with JCR 16 6 COMMUNIQUÉ AND CQDAM INTEGRATION 17 7 CQ DAM ADMINISTRATION CQSE Administration Console Sling Management Console CRX Explorer 23 8 CQ DAM EXTENSIONS Maven Eclipse IDE CQ DAM Extension Development Setup CQ DAM Extension Examples Adding a Media Handler Adding an Exporter Extending CQ DAM Web GUI 29 2

3 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 Note: When you contact support, you need your product information, including version number, which is found under About in CQ DAM for product information. 3

4 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 Key CQ DAM Features The following table provides information about key CQ DAM features. Feature Web Browser-based User Interface Description 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 Graphics Support Video Support 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. CQ DAM automatically generates thumbnails from embedded images. You can convert and recompress images, and perform image editing functions such as scaling and adding watermarks. In CQ DAM, you can import and export Final Cut Pro edit decision lists (EDL), produce scene sequences and clips, extract keyframes, and add annotations and attachments to video assets. 4

5 Feature Audio Support Document Support Organization Support Searching Functionality Process Support Collaboration Support Description 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. CQ DAM is compatible with a variety of document formats, including Adobe PDF, MS Office, and Quark Express. 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. 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. 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. CQ DAM provides Lightbox functionality to share assets and anonymously upload assets. You can add annotations to assets. 5

6 Feature Metadata Support Importing and Exporting Versioning Logging Security Preferences Description 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. 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. 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. CQ DAM logs all relevant activities on the system for later reference. CQ DAM provides DAM-specific rights to metadata, high resolution binaries, and thumbnails, and CRX-specific rights. You can change the CQ DAM display language. 2.2 How CQ DAM Works As a digital asset management tool based on the Java content repository (JCR), CQ DAM stores all information, including assets and their metadata in the same repository. Traditional solutions use a database and a file system that store metadata and assets separately. CQ DAM s advantages over traditional solutions include a unified architecture, asset structure, ease of use, and increased performance. 6

7 2.2.1 Unified Architecture Assets and their metadata are stored in one location in a standardcompliant 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 Asset Structuring Ease of Use 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. 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. In traditional solutions, assets must have a predefined structure. 7

8 2.2.4 Performance Extensibility 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. 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 . 8

9 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. 9

10 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. 10

11 4 CQ DAM Supported File Types This section describes all the file types that CQ DAM supports. 4.1 Audio Files Extension Definition.mp3.wav.wma MPEG-1 Audio Layer 3 audio format Waveform audio format Windows Media Audio format 4.2 Document Files Extension Definition.pdf.doc.pps.ppt.qxd.txt.xls Adobe s Portable Document Format Microsoft Word document Microsoft PowerPoint Show document Microsoft PowerPoint document QuarkXPress 4.x document Text document Microsoft Excel document 4.3 Graphics Files Extension Definition.gif.jpeg.jpg.png Graphics interchange format Joint photographic experts group format Joint photographic experts group format Portable network graphics format 11

12 Extension Definition.psd.tif Adobe Photoshop document Adobe s tagged image file format 4.4 Supported video files Extension Definition.avi.qt Microsoft s Audio Video Interleave Apple s QuickTime 12

13 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 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. 13

14 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 Enhances Hotfix installation For more information about OSGi, please check the OSGi website and wikipedia page

15 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-touse 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 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. 15

16 5.5 CQ DAM Content Sharing with JCR CQ DAM shares content with JCR as illustrated below: CQ DAM initializes with an embedded CRX repository bundle or CRX standalone Web application. It is shared over JNDI and RMI, and accessible via Samba (CIFS) or WebDAV. Note: CIFS is recommended with CQ DAM. 16

17 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 jar into author/bin/lib. 3. Install the package dam-integration cq. 4. Install the package dam-integration-config 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"/> 17

18 Note: To get more information about the synchronization process you can set the log level for the category emsconnector 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= Restart Communiqué. The following illustrations show how CQ DAM integrates with Communiqué. CQ DAM Folders are mapped as a media library page. CQ DAM Assets are mapped into media library paragraphs 18

19 There are no changes for Authors, they still select and store the referenced media the same way. 19

20 Media library documents are references to a CQ DAM asset (dam://{uuid}). The packages add a new API to resolve the reference to the CQ DAM asset. 20

21 21

22 7 CQ DAM Administration This section describes CQ DAM administration. 7.1 CQSE Administration Console Access the Communiqué servlet engine administration console at 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 after CQ DAM installation. Use the Sling management console to manage service configurations and install new bundles and assemblies, for example a customized media handler, media exporter, or feature for CQ DAM. 22

23 7.3 CRX Explorer Install CRX Explorer on 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. 23

24 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: 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 frameworks, tools, and runtimes, for building, deploying, and managing software through its lifecycle. For more information about Eclipse IDE, please check the Eclipse website at Eclipse is a powerful Integrated Development Environment (IDE) for Java, extendible with plug-ins. Day plug-in available at Maven2 plug-in at 24

25 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 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. 25

26 /** * <code>myhandler</code>... * immediate="true" * label= MyHandler" description= My handler" * 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. /** 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); ToolbarItem items[] = (ToolbarItem[]) list.toarray(new ToolbarItem[list.size()]); return items; } 8. Check the details view, to confirm the addition. A new button appears in the detail s view for this media type. 26

27 Media Handler Administration Once you installed a media handler, you can manage it with the administration Web GUI, which is available at The administration Web GUI allows you to enable and disable any registered media handlers for handling specific mime types. 27

28 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. /** * immediate="true" label="sampleconverter" description="sample Converter" name="dam.exporter.iconpath value="/dam/imgs/menu/package.gif"; name="dam.exporter.smalliconpath value="/dam/imgs/menu/package.gif"; name="dam.exporter.text" value="download sample..."; name="dam.exporter.alttext" value="download sample "; * 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... 28

29 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 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 "?> <graffito-jcr> <class-descriptor classname="com.day.cq.dam.component.damscriptcontent" jcrnodetype="dam:damscript" discriminator="false" > <field-descriptor fieldname="path" path="true" /> 29

30 <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 Extending the Navigation tab This example shows the results of extending the Navigation Tab to add a new function. 30

31 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. 31