PROFESSIONAL.

Alfresco®

PRACTICAL SOLUTIONS FOR ENTERPRISE

CONTENT MANAGEMENT

David Caruana

John Newton

Michael Farman

Michael G. Uzquiano

Kevin Roast

WILEY

Wiley Publishing, Inc.

CONTENTS

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 14

What is Professional Open Source Software? 14

Why Use Open Source? 15

Alfresco and the Community 16

CONTENTS

CHAPTER 2: ARCHITECTURE 19

Guiding Principles "19

Supporting ECM Requirements 19

Simple, Simple, Simple 20

Scaling to the Enterprise 20

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

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

CONTENTS

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

CONTENTS

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

CONTENTS

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

CONTENTS

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

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

Constructing the Model 268

xxl

CONTENTS

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

xxii

Overview

The Alfresco Repository

313

315

CONTENTS

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

CONTENTS

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

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 — Template Instance 395

Surf Objects — Components 395

Template 396

Web Script 397

Alfresco Share-Custom Site Preset 401

Share Object — Preset 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 - CSS 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

CONTENTS

Adding the Archive Action to the Document Library 423

Configuring Alfresco Share to Show Your Custom Workflow 423

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

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

CONTENTS

.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

CONTENTS

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