PROFESSIONAL. Alfresco PRACTICAL SOLUTIONS FOR ENTERPRISE CONTENT MANAGEMENT David Caruana John Newton Michael Farman Michael G. Uzquiano Kevin Roast WILEY Wiley Publishing, Inc.
INTRODUCTION xxix CHAPTER 1: INTRODUCING ALFRESCO 3 For the End User 3 For the Business 4 For the Developer 4 For the IT Organization 4 What Is Enterprise Content Management? 5 The Origins of ECM 6 Enter Alfresco 6 Alfresco Overview 7 The Content Application Server and the Repository 8 Alfresco Applications 8 The Alfresco Web Tier and Surf 9 Alfresco Programming Models 9 Content Applications 10 Knowledge Management 10 Document Management 10 Shared Drive Replacement 11 Enterprise Portals and Intranets 11 Web Content Management 11 Information Publishing 11 Records Management 12 Collaborative Content Development 12 Case Management 12 Alfresco and Your Environment 12 What to Consider 13 The Audience 13 The Number of Users 13 The Architecture 13 The Level of Configuration or Customization 13 The Enterprise IT Environment 14 The Support Requirements What is Professional Open Source Software? 14 Why Use Open Source? 15 Alfresco and the Community 16 14
CHAPTER 2: ARCHITECTURE 19 Guiding Principles "19 Supporting ECM Requirements 19 Simple, Simple, Simple 20 Scaling to the Enterprise A Modular Approach 20 Incorporating Best-of-Breed Libraries 20 Environment Independence 20 A Solid Core 20 Scriptable Extensions 21 A Standards-Based Approach 21 An Architecture of Participation 21 A High-Level Overview 21 The Alfresco Content Application Server 23 The Content Repository 24 Modularity through a Spring Framework 26 Content Services 27 Protocols 28 APIs 30 The Remote API 30 The Embedded API 32 Content Modeling 33 The Alfresco Web Application Framework 35 Deployment Options 37 Embedded Alfresco 38 The Alfresco Content Application Server 38 Clustered Alfresco 38 The Backup Server 39 Multitenancy 39 The Enterprise Infrastructure 40 20 CHAPTER 3: SETTING UP AN ALFRESCO ENVIRONMENT 43 Installing Alfresco 43 Running the Alfresco Installation Wizard 44 Repository Configuration 45 Deploying Extensions 45 Spring Configuration Extensions 46 Web Script Extensions 46 Web Tier Configuration Extensions 47 Share Customization Extensions 47 Packaging Extension Files 48 xvl
Debugging Tips 48 Server-Side JavaScript Logging 48 Server-Side JavaScript Debugging 49 Client-Side JavaScript Logging and Debugging 49 Disabling Caching 50 CHAPTER 4: SERVICES 53 Content Repository Services 54 File and Folder Management 54 Versioning and Check Out/Check In 54 Auditing 55 Authentication, Authorities, and Permissions 55 Modeling 55 Search 56 Content Application Services 56 Content Services 56 Rules and Actions 56 Transformation 56 Metadata Extraction 56 Thumbnailing 56 Control Services 57 Workflow 57 Web Projects 57 Sandboxes 57 Assets 57 Collaboration Services 57 Sites 57 Invite 58 Activity 58 Tagging 58 Commenting 58 How Services Are Built 58 Using Services 59 Embedded APIs 59 Remote APIs 61 Configuring and Extending Existing Services 61 Building a Simple Service 63 Example Counter Service: Tier 1-Java Service Layer 64 Example Counter Service: Tier 2--JavaScript API 64 Example Counter Service: Tier 3--RESTful API 65 xvll
Content Management Interoperability Services (CMIS) 67 CMIS Requirements 68 Core Concepts of CMIS 69 CMIS Services 72 Using CMIS with Alfresco 73 CHAPTER 5: CONTENT MODELING 75 Modeling in Context 76 Deploying a Content Model 77 The Content Metamodel Explained 78 The Metamodel XML Schema 80 The Model Header 80 Model Namespaces 81 Types 82 Properties 84 Associations 85 Constraints 87 Inheritance 89 Aspects 90 Out-of-the-Box Models 92 A Step-by-Step Custom Model 92 Creating Content with JavaScript 96 Model Localization 99 The Relationship to CMIS 101 CHAPTER 6; AUTHENTICATION AND SECURITY 103 Alfresco Authentication 103 Authentication Subsystems 104 Authentication Subsystem Types 104 The Authentication Chain 105 Authentication Configuration Examples 105 Example 1: Customizing alfrescontlm 105 Example 2; The Idap-ad Subsystem 108 Example 3: The passthru Subsystem 111 Alfresco Security 114 Authorities 115 People and Users 115 Groups 116 Zones 116 Application-Related Zones 116 Authentication-Related Zones 117 xviii
Dynamic Authorities and Roles 117 Permissions 118 Access Control Lists 120 ACL Ordering and Evaluation 121 An ACL Example 121 Public Services 124 Configuration 124 Defining Method-Level Security 124 Modifying Access Control 127 Access Control Extension 128 Implementation and Services 128 The Person Service 129 The Authority Service 129 The Permission Service 130 The Ownable Service 130 CHAPTER 7: BUSINESS PROCESS MANAGEMENT 133 Introduction to Workflow in Alfresco 133 HowjBPM Interprets and Implements a Process 134 Nodes and Transitions 135 Actions and Events 137 Tasks, Swimlanes, and Timers 138 Super-States and Sub-Processes 139 Defining a Workflow in Alfresco 141 Creating the Process Definition 143 Deploying a Process Definition 144 Configuring the Alfresco Server 144 Hot-Deploying a Process Definition 145 Testing the Deployment 146 The Task Model 146 Creating a Task Model 147 The Common Task Model 149 Workflow Task Definitions 149 The Start Task 150 Assignment Aspects 151 Workflow Package Actions 151 Accessing Task Attributes 152 Deploying the Task Model 153 Customizing Behavior 153 Process Variables 155 Assigning Tasks and Swimlanes 156 The Alfresco JavaScript Action 157 The ForEachFork Action 158 xix
Configuring the Explorer Web Client 159 Resource Bundles 159 Creating a Resource Bundle 159 Deploying Resource Bundles 161 Configuring Task Property Pages 162 CHAPTER 8: INTRODUCING WEB SCRIPTS 167 Types of Web Scripts 169 Data Web Scripts 169 Presentation Web Scripts 170 The Web Script Framework 170 Hello World Web Script 171 Listing Already-Built Web Scripts 173 Where Can I Invoke a Web Script? 175 Using curl Instead of a Web Browser 176 Authenticating 176 Creating the Hello User Web Script 177 Specifying User Identity 179 Custom Client Authentication 180 Response Formats 180 Adding a Response Format to the Hello User Web Script 181 Selecting a Response Format 182 Anatomy of a Web Script URI 183 Working with Client Limitations 184 Tunneling HTTP Methods 184 Forcing Success Response Status 185 JSON Callbacks 185 Caching 186 CHAPTER 9: HOW TO CREATE A WEB SCRIPT 189 Components of a Web Script 190 Creating a Description Document 191 URI Templates 195 Creating a Controller Script 197 Parsing the Web Script URI 198 Calling Alfresco Services 199 Setting the Response Status Code 201 Constructing the Model 202 Creating a Response Template 202 Accessing the Model 204
Constructing the Model 268 xxl CONTENTS Accessing Alfresco Services 205 FreeMarker Methods 206 Registering and Testing 207 Debugging a Controller Script 208 Multiple Response Templates 209 Response Status Code Templates 211 Step-by-Step: Knowledge Base Search Web Script 213 How Does Knowledge Base Search Work? 218 Testing Knowledge Base Search 219 Complex Root Objects Reference 222 url 222 status 223 cache 224 format 224 webscript 224 server 225 CHAPTER 10: ADVANCED WEB SCRIPTS 227 Internationalization 227 Configuration 231 Content Negotiation 235 Multipart Form Processing 238 The Form Data API 244 formdata 244 formfield 244 Request Processing 245 The JSON Object API 249 JSONArray 249 JSONObject 249 Caching 250 Descriptor Cache Controls 250 Runtime Cache Controls 251 Advanced Descriptor Options 254 Lifecycle 254 Family 255 Run As 255 CHAPTER 11: JAVA-BACKED WEB SCRIPTS 257 Step-by-Step: Folder Listing Java-Backed Web Script 258 Java Approach to Web Scripts 263 Parsing the URI 265 Calling Alfresco Services 265 Setting the Response Status Code 266
Spring-Framework Registration 268 Service Dependencies 269 Creating a New Kind of Web Script 270 Using a New Kind of Web Script 275 CHAPTER 12: UNDERSTANDING THE SURF FRAMEWORK 281 What Is Surf? 281 Basic Concepts 283 Content 283 Content Delivery Services 285 Content Applications 286 Putting It into Action 288 Plug-in for the Spring Framework 289 Model-View-Controller 289 Spring Web MVC 290 Surf View Resolvers 291 Examples 292 A Surf Page 292 Using an Annotated Controller 293 View Composition 294 Pages 295 Templates and Regions 296 Components 299 Presentation Content 300 Surf Objects 301 Templates 302 Web Scripts 302 Example 304 A Java-Backed Web Script 304 Connectors and Credentials 306 Connectors and Endpoints 306 Credentials 307 Authenticators 308 The Remote API 309 Example 310 Scriptable Controller 310 Getting Involved 310 CHAPTER 13: LEVELS OF CUSTOMIZATION 313 Overview The Alfresco Repository 313 315 xxii
Content Models 315 Content Behavior 316 Process Definitions 318 Workflow Models 319 Actions 320 Other Extension Points 321 Alfresco Explorer 321 The Basics 321 Permissions 325 Rules 325 Other Extension Points 328 Alfresco Share 328 The Basics 328 Dashboards 331 Dashlets 332 CHAPTER 14: CUSTOM KNOWLEDGE BASE: GETTING STARTED 333 Overview 334 Content Lifecycle 334 Content Model 335 Knowledge Base Spaces 335 Knowledge Base Articles 336 Constraints 338 Alfresco Explorer Extensions 339 Property Sheets 340 Wizards and Icons 340 Smart Spaces and Scripting 341 Space Templates 342 Installing the Code 343 Stopping the Alfresco Server 343 Adding the Knowledge Base Content Model 344 Adding Alfresco Explorer Configuration 344 Adding the Knowledge Base Search Web Script 344 Putting It into Action 345 Starting the Alfresco Server 345 Signing on to Alfresco Explorer 345 Adding a Script to the Data Dictionary 345 Creating a Knowledge Base Space Template 346 Creating the Space Template 347 Adding an Archived Space 348 Setting Up Content Rules 348 Creating a Knowledge Base 351 xxlll
Contribute a Document 352 Using Alfresco Explorer 352 Using CIFS 354 Editing Your Knowledge Base Article 354 Seeing It in JSON! 355 Sample Code 356 Alfresco Repository 356 Alfresco Explorer 359 Data Dictionary Script 361 Knowledge Base-Search Web Script 362 CHAPTER 15: CUSTOM KNOWLEDGE BASE: BASIC SHARE CUSTOMIZATION 367 Overview 368 Sites 368 Custom Dashlet 370 Browser Dependencies 371 Internationalization (I18N) 371 Custom Site Page 373 A Knowledge Base Component 374 Browser Dependencies 374 Internationalization (I18N) and Configuration 375 Alfresco Share Configuration 376 Custom Site Preset 376 Dashboard Configuration 378 Internationalization (I18N) 378 Installing the Code 379 Stopping the Alfresco Server 380 Adding the Custom Dashlet 380 Adding the Custom Site Page 380 Adding the Web Script 380 Adding the Surf Page 381 Adding the Surf Template Instance 381 Adding the Freemarker Template 381 Adding the Surf Component Bindings 382 Configuring Your Site Page for Alfresco Share 382 Adding the Common Library 383 Configuring a Custom Site Preset 383 Adding the Preset 383 Overriding the Create Site Dialog Drop-Down List 383 Adding Your Custom Message-Bundle 384 Overriding the Message-Bundle Bootstrap Component 384 Adding Files to the Tomcat ROOT Web Application 384 Adding the web.xml File 384 xxiv
Components Preset CSS CONTENTS Adding the Custom Dashlet Dependencies 385 Adding the Custom Page Component Dependencies 385 Putting It into Action 385 Starting the Alfresco Server 385 Creating a New Alfresco Share Site 386 Adding the Custom Dashlet to Your Site 387 Adding the Custom Page to Your Site 388 Creating a Knowledge Base Site 389 Clicking on the Document Library 391 Sample Code 391 Alfresco Share-Custom Dashlet 391 Web Script 391 Alfresco Share-Custom Page 394 Surf Object-Page 394 Surf Object Surf Objects Template Instance 395 395 Template 396 Web Script 397 Alfresco Share-Custom Site Preset 401 Share Object 401 Share Module-Site Creation 402 Alfresco Share-Common Library 403 Alfresco Share-Configuration Files 406 Alfresco Share-Message Bundle 407 Tomcat ROOT Web Application Files 408 - Custom Dashlet 408 Custom Page-CSS and JavaScript 408 CHAPTER 16: CUSTOM KNOWLEDGE BASE: ADVANCED SHARE CUSTOMIZATIONS 413 Overview 414 Alfresco Share Document Library 414 Aspects 415 Actions 416 Workflow 417 Forms in Alfresco Share 418 Alfresco Share Configuration 419 Installing the Code 421 Stopping the Alfresco Server 422 Document Library Services 422 Adding the Custom Workflow 422 Adding the Archive Action Handler 422 Setting Up the Kb: article Aspect 423 Alfresco Share 423 XXV
Adding the Archive Action to the Document Library 423 Configuring Configuring the Alfresco Share Form for ktxarticle Objects 424 Adding the Alfresco Share Form Template 424 Adding Your Custom Message Bundle 424 Overriding the Message Bundle Bootstrap Component 425 Adding Files to the Tomcat ROOT Web Application 425 Adding the web.xml File 425 Adding the Document Library Dependencies 425 Adding the Knowledge Base Article Image 426 Putting It into Action 426 Alfresco Share to Show Your Custom Workflow 423 Restarting the Alfresco Server 426 Setting Up a Knowledge Base 426 Browsing to the Knowledge Base 428 Adding a Document to the Knowledge Base 429 Editing the Document Metadata Using a Form 430 Requesting Approval for Your Document 431 Approving the Document 432 Archiving the Document 433 Sample Code 434 Alfresco Repository 434 Custom Workflow 435 Archive Web Script (POST Handler) 438 Document Library Services 440 Alfresco Share 441 Configuration Files 441 Form Template 443 Document Library-HEAD Override 444 Document Library-Action List 446 Workflow 448 Tomcat ROOT Web Application Files 449 Document Library-Browser Dependencies 449 CHAPTER 17: INTEGRATING WITH OTHER APPLICATIONS 451 Why Integrate Content Management into Applications? 452 Why Not Just Use a File System or a Database? 453 Application Integration Options 455 CMIS 455 Web Scripts 456 File-Based Access 456 OpenSearch and Feeds 456 Java Applications 456 PHP Applications 457 xxvi
.NET Applications 457 Surf Components 457 Authentication and Directory Services 457 Patterns of Content Management Integration 457 Content Service Mappers 458 Using a Content Service Mapper 459 When to Use It 459 Example 459 Property View 462 Using a Property View 462 When to Use It 463 Example: Confluence 463 Article 464 Using the Article Pattern 465 When to Use It 466 Example 466 Query View 467 Using a Query View 468 When to Use It 469 Example: Drupal and OpenSearch 469 Browser View 472 Using a Browser View 472 When to Use It 473 Example: Drupal Repository Browser 474 Librarian 482 Using a Librarian 482 When to Use It 483 Example 484 Catalog View 484 Using a Catalog View 485 When to Use It 486 Example: Image Gallery in Share 486 Attachment 487 Using an Attachment 487 When to Use It 488 Example 488 Annotation 488 Using an Annotation 489 When to Use It 490 Example: Comments in a Share Blog 490 Archive 492 Using an Archive 492 When to Use It 493 Example: Kofax Release Script 494 xxvll
Project Space 499 Using a Project Space 500 When to Use It 500 Review and Approval Workflow 500 Using a Review and Approval Workflow 500 When to Use It 501 Example: Kofax 501 Feed 501 Using a Feed 501 When to Use It 502 Example: Activities Atom Feed 502 Portlet View 503 Using a Portlet View 504 When to Use It 504 Example: Liferay and CMIS 505 Example Integrations 507 Joomla and Drupal 507 Confluence 508 Liferay Portal 508 SAP 509 Kofax Image Scanning 509 Microsoft SharePoint 509 Lotus Quickr 511 Email Clients 511 APPENDIX A: RESTFUL API REFERENCE 3 APPENDIX B: SURF PLATFORM API REFERENCE 43 APPENDIX C: REPOSITORY FREEMARKER TEMPLATE API 61 APPENDIX D: REPOSITORY JAVASCRIPT API REFERENCE 75 APPENDIX E: SURF QUICK REFERENCE 107 INDEX 513 xxviii