4.6.1 Integration Guide - Edge Documentationdocs.edge-technologies.com/edge-docs/images/7/73/enPortal_4.6.1... · Edge Technologies, Inc. acknowledges th e Sun Developer Network for

frontmatter.fm November 4, 2009

enPortalTM

4.6.1

Integration Guide

2009 Edge Technologies, Inc.

No part of this guide may be reproduced, stored in a retrieval system, or transmitted in any form or any means electronic or mechanical, including photocopying and recording, for any purpose other than the purchasers personal use without the written permission of Edge Technologies, Inc. Information in this document is subject to change without notice.

Disclaimer of Warranty and Statement of Limited Liability

Edge Technologies, Inc. may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property rights except as expressly provided in any written license agreement from Edge Technologies, Inc. While every precaution has been taken in the preparation of this reference guide, Edge Technologies, Inc. assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

Trademarks and Acknowledgements

Edge Technologies, Inc. acknowledges the use of software developed by the Apache Group for use in the Apache HTTP server project. Copyright 1995-1999 The Apache Group. Apache Server is a trademark of the Apache Software Foundation (http://www.apache.org/). All rights reserved.

The Sun logo, Sun Microsystems, SunOS, Solaris, SunNet Manager, Java are trademarks of Sun Microsystems Inc.

UNIX is a registered trademark of the X/Open Company Ltd.

Sybase, Sybase SQL Anywhere, and Adaptive Server are registered trademarks of Sybase Inc.

Oracle is a registered trademark of Oracle Corporation.

Edge Technologies, Inc. acknowledges PostgreSQL Global Development Group for use of the PostgreSQL JDBC driver. Copyright 1997-2005 PostgreSQL Global Development Group. All rights reserved.

HP, HP-UX and OpenView are trademarks of Hewlett-Packard Company.

Microsoft, Windows 95/98/Me/NT/2000/XP are either registered trademarks or trademarks of Microsoft Corporation.

Microsoft Internet Information Server/Services (IIS), Microsoft Exchange Server, Microsoft SQL Server, Microsoft perfmon, Windows Media, and Microsoft Cluster Service are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Netscape and Netscape Navigator are registered trademarks of Netscape Communications Corporation in the United States and other countries. Netscape's logos and Netscape product and service names are also trademarks of Netscape Communications Corporation, which may be registered in other countries.

Red Hat and all Red Hat-based trademarks and logos are trademarks or registered trademarks of Red Hat Inc. in the United States and other countries.

Mozilla and Firefox are registered trademarks of The Mozilla Foundation.

Linux is a registered trademark of Linus Torvalds.

Edge Technologies, Inc. acknowledges that enPortal includes Hypersonic SQL. Copyright 2001-2002, The HSQL Development Group. All rights reserved.

Edge Technologies, Inc. acknowledges the Sun Developer Network for use of the RSS Utilities Package. Copyright 1994-2006 Sun Microsystems, Inc. All rights reserved.

Edge Technologies, Inc. acknowledges The OpenSSL Project for the use of OpenSSL. Copyright 1998-2005 The OpenSSL Project.

Edge Technologies, Inc. acknowledges OReilly & Associates for use of Dynamic HTML:The Definitive Reference by Danny Goodman (ISBN 1-56592-494-0).

Edge Technologies, Inc. acknowledges OReilly & Associates for use of JavaScript

& DHML Cookbook by Danny Goodman (ISBN 0-596-00467-2).

Edge Technologies, Inc. acknowledges Alexandria Software Consulting for use of

the JavaService utility. Copyright 2000 Alexandria Software Consulting. All rights reserved.

Document Version Number: 1.3

Contents

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Associated Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

enPortal Administration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

enPortal Installation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

enPortal Integration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

enPortal Javadoc API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Typographical Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Note, Tip, and Warning Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Syntax and Example Subheadings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Operating System Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 1: Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Content Integration Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Content Integration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Web-based Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

HTTP Requests and Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Direct HTTP Based integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Content Retrieval Service (CRS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Example Integration Micromuse JEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Potential Obstacles to Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Tools Used in Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Application Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

OS Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Network Analyzer / Packet Sniffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Browser Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

enPortal 4.6.1 Integration Guide i

Contents

Product Integration Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Solution Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Solution Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Solution Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Solution Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Managing and Maintaining a Deployed Solution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Product Integration Strategy for Non-Web Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Solution Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Solution Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Solution Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Solution Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Managing and Maintaining a Deployed Solution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 2: Integration Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Package/Integration Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Create a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Create a New Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Edit an Existing Package or Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Delete a Package/Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Authentication Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Create an Authentication Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Edit an Existing Authentication Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Delete an Authentication Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Class Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Create a new Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Edit a Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Delete a Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Handler Placeholder Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Create a new Handler Placeholder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

enPortal 4.6.1 Integration Guideii

Contents

Target Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Create a new Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Edit a Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Delete a Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 3: Single Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Custom Single Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Problem Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Methods of Web-Based Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

LPS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

System Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Functional Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

LPS Integration Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Methods of Automating Web-based Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Cookie Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Cookie Management in the Integration Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Cookie Viewer Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Sample Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Forms-based Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Cookie-based Authentication (Traditional). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Cookie-based Authentication Using Cookie Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Single Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Single Logout Without Cookie Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Single Logout With Cookie Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Additional Authentication Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

enPortal 4.6.1 Integration Guide iii

Contents

Chapter 4: Custom Look And Feels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

LAF Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

LAF Class (Template) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

LAF Instance (Object) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

LAF Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

LAF Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Page Object (Instance) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Custom Page Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Channel Frame Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Style Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Page Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Displaying Current View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Accessing All Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Menus/Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Role Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Creating a New LAF (without Generic Template). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Designing LAF and Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Creating XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Creating a New Page Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Loading a New LAF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Using the Generic Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

LAF Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

XML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Extension of the Generic LAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Chapter 5: Custom Login Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Creating New Login Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

enPortal 4.6.1 Integration Guideiv

Contents

Login Page Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Login Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Browser Type Checking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Auto-fill of the User ID and Domain Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Error Message Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Basic Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Login Page Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Chapter 6: Custom Terms of Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Enabling the Terms of Use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Creating a Custom Terms of Use Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Chapter 7: Custom Authenticators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Authenticators Delivered with the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Creating an Authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Registering an Authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Registering the Standard Custom Authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Registering an LDAP Custom Authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Chapter 8: Custom Error Page Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Custom Handling of HTTP Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Error Handler Rules Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

CRS Error Pages JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Custom Handling of Portal Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Portal Error Page JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

enPortal 4.6.1 Integration Guide v

Contents

Custom Handling of Unresponsive Tomcat Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Service Unavailable Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Chapter 9: Manage Customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Summary of enPortal Upgrade Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Preserving Customizations for System Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

The enPortal File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Export Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

The FilesExport Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Location of Customization Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Chapter 10: Sniffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Create a new Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Integration Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Sniff the Channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Create a Class and Target from a URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

View Raw Data/ Make Request / Delete Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Use the Sniffer Session Administration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Chapter 11: Integration with External Sources of Users . . . . . . . . . . . . . . . . . . . . . 223

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

User Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Domains and Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

LDAP Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

DesignMapping to Internal Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

enPortal 4.6.1 Integration Guidevi

Contents

LDAP IntegrationCase A: XML Parameterized Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Locating the LDAP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Mapping LDAP People to internal Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Mapping LDAP Groups to Internal Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Mapping LDAP Person-to-Group Associations to Internal User-to-Role Assignments. . . . . . . . . . . . . . . . . . . . . . . . . . 229

Deploying the Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

LDAP IntegrationCase B: API Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Creating a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Ensuring Existence of the Domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Retrieving Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Creating and Deleting Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Ensuring Existence of Root Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Retrieve Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Creating, Deleting, or Assigning Users to Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Deploying the Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Appendix A: Common Integration Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Common Integration Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Applets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

HTML Integration Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

enPortal 4.6.1 Integration Guide vii

Contents

Appendix B: Product Integration Module (PIM) Structure . . . . . . . . . . . . . . . . . . . 253

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Channels (Portlets). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Request Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Runtime Handlers (Proxy Channels Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Informal Web Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

AuthDefs (Proxy Channels Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Resolvers (Proxy Channels Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Targets (Proxy PIMs Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

The Load Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Licensing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Views and ViewSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

File Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Distribution/Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Appendix C: Generic LAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Generic LAF Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Page Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Page Object Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Page Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

LAF Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Graphics Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Appendix D: Targeting Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Targeting Channels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Create a Targeted Channel IFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Channel Target IFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

enPortal 4.6.1 Integration Guideviii

Contents

Create a Targeted Channel Using the Channel Target Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Channel Target Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Appendix E: Developer Reference Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

XML Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Authoring XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Constructing Content and Configuring the System Using XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Constructing Accounts Using the AccountDefinitions DTD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Configuring Accounts using the RoleEnvironmentConfiguration DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Constructing Content using the ComponentSpecification DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Creating Folders and Security Controls via XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Constructing Directories and Defining Security Controls Using the DirectoryMetaInfo DTD . . . . . . . . . . . . . . . . . . . 322

Constructing Content Retrieval Rules Using the CRS DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Presentation Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Page Handler API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Custom Tags and the Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Content Retrieval Service (CRS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Inline CRS Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Perl Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

CRS XML Example Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

enPortal 4.6.1 Integration Guide ix

Contents

XML Specifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

DTD Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Account Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Role Environment Configuration Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Directory Folder and Security Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

Content Retrieval Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Authentication Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

Authentication Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

Component Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

LDAPRepository Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

Password Policy Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

Public Customization Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

SHIM Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468

Usage Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468

Contexts For Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

Primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

Javadoc API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

enPortal 4.6.1 Integration Guidex

preface.fm November 4, 2009

Preface

This guide describes how to install, administer, and use enPortal. The following chapters and appendices describe each functional area, and task-oriented examples are provided to assist users and administrators in configuring and using the application.

This preface contains the following sections:

Audience on page 2

About this Guide on page 3

Associated Publications on page 4

Typographical Notation on page 5

Operating System Considerations on page 8

enPortal 4.6.1 Integration Guide 1

Preface

Audience

This guide is intended for both users and administrators, and provides detailed cross-platform information about tools, functions, and capabilities. In addition, it is designed to be used as a reference guide to assist you in designing and configuring your environment.

enPortal 4.6.1 Integration Guide2

About this Guide

About this Guide

This book is organized as follows:

Chapter 1: Integration on page 9

Chapter 2: Integration Builder on page 65

Chapter 3: Single Login on page 105

Chapter 4: Custom Look And Feels on page 141

Chapter 5: Custom Login Pages on page 173

Chapter 6: Custom Terms of Use on page 183

Chapter 7: Custom Authenticators on page 187

Chapter 8: Custom Error Page Handlers on page 193

Chapter 9: Manage Customizations on page 199

Chapter 10: Sniffer on page 211

Chapter 11: Integration with External Sources of Users on page 223

Appendix A: Common Integration Issues on page 241

Appendix B: Product Integration Module (PIM) Structure on page 253

Appendix C: Generic LAF on page 267

Appendix D: Targeting Channels on page 271

Appendix E: Developer Reference Guide on page 279


Preface

Associated Publications

This section provides a description of the primary documentation that accompanies the enPortal product suite.

enPortal Administration Guide

This book is intended for system administrators who need to manage enPortal. It describes how to perform administrative tasks using the enPortal Administrator GUI, command line tools, and process control.

enPortal Installation Guide

This book is intended for enPortal administrators who need to install and deploy enPortal. It includes installation, upgrade, and licensing procedures. In addition, it contains information about configuring the database and security certificates.

enPortal Integration Guide

This book is intended for anyone who will be integrating applications into enPortal. It includes sections on procedures for content integration, Single Login, configuring Look and Feel, authentication, and integrating with external sources of users. The book also details how to use Product Integration Modules (PIMs).

enPortal Javadoc API

The Java API contains all of the interfaces, methods, and variables for the Java classes which are used in the enPortal product. These interfaces are the core of the operation of both the portal server and the servlets run by the tomcat server. The enPortal Java API is generated by the standard Javadoc tool from Sun Microsystems. It is generated as a standard HTML format document. The index page is initial point of access to the entire API.


Typographical Notation


Table 1 shows the typographical notation and conventions used to describe commands, SQL syntax, and graphical user interface (GUI) features. This notation is used throughout this book and other publications.

Table 1: Typographical Notation and Conventions (1 of 2)

Example Description

Monospace The following are described in a monospace font:

Commands and command line options

Screen representations

Source code

Object names

Program names

SQL syntax elements

File, path, and directory names

Italicized monospace text indicates a variable that the user must populate. For example, -password password.

Bold The following application characteristics are described in a bold font style:

Buttons

Frames

Text fields

Menu entries

A bold arrow symbol indicates a menu entry selection. For example, FileSave.

Italic The following are described in an italic font style:

An application window name; for example, the Login window

Information that the user must enter

The introduction of a new term or definition

Emphasized text

[1] Code or command examples are occasionally prefixed with a line number in square brackets. For example:

[1] First command...[2] Second command...[3] Third command...

{ a | b } In SQL syntax notation, curly brackets enclose two or more required alternative choices, separated by vertical bars.

[ ] In SQL syntax notation, square brackets indicate an optional element or clause. Multiple elements or clauses are separated by vertical bars.


Preface

Many commands have one or more command line options that can be specified following a hyphen (-).

Command line options can be string, integer, or BOOLEAN types:

A string can contain alphanumeric characters. If the string has spaces in it, enclose it in quotation (") marks.

An integer must contain a positive whole number or zero (0).

A BOOLEAN must be set to TRUE or FALSE.

SQL keywords are not case-sensitive, and may appear in uppercase, lowercase, or mixed case. Names of ObjectServer objects and identifiers are case-sensitive.

Note, Tip, and Warning Information

The following types of information boxes are used in the documentation:

Note: Note is used for extra information about the feature or operation that is being described. Essentially, this is for extra data that is important but not vital to the user.

Tip: Tip is used for additional information that might be useful for the user. For example, when describing an installation process, there might be a shortcut that could be used instead of following the standard installation instructions.

!!Warning: Warning is used for highlighting vital instructions, cautions, or critical information. Pay close attention to warnings, as they contain information that is vital to the successful use of our products.

| In SQL syntax notation, vertical bars separate two or more alternative syntax elements.

... In SQL syntax notation, ellipses indicate that the preceding element can be repeated. The repetition is unlimited unless otherwise indicated.

,... In SQL syntax notation, ellipses preceded by a comma indicate that the preceding element can be repeated, with each repeated element separated from the last by a comma. The repetition is unlimited unless otherwise indicated.

a In SQL syntax notation, an underlined element indicates a default option.

( ) In SQL syntax notation, parentheses appearing within the statement syntax are part of the syntax and should be typed as shown unless otherwise indicated.

Table 1: Typographical Notation and Conventions (2 of 2)

Example Description



Syntax and Example Subheadings

The following types of constrained subheading are used in the documentation:

Syntax

Syntax subheadings contain examples of ObjectServer SQL syntax commands and their usage. For example:

CREATE DATABASE database_name;

Example

Example subheadings describe typical or generic scenarios, or samples of code. For example:

[1] [2] [6]


Preface

Operating System Considerations

All command line formats and examples are for the standard UNIX shell. UNIX is case-sensitive. You must type commands in the case shown in the book.

Unless otherwise specified, command files are located in the $PORTAL_HOME/bin directory, where $PORTAL_HOME is the UNIX environment variable that contains the path to the enPortal home directory.

On Microsoft Windows platforms, replace $PORTAL_HOME with %PORTAL_HOME% and the forward slash (/) with a backward slash (\).


content.fm November 4, 2009

Chapter 1: Integration

This chapter contains the following sections:

Content Integration Architecture on page 10

Content Integration Overview on page 12

Direct HTTP Based integration on page 14

Content Retrieval Service (CRS) on page 15

Potential Obstacles to Integration on page 17

Tools Used in Integration on page 19

Product Integration Strategy on page 21

Product Integration Strategy for Non-Web Applications on page 42



1.1 Content Integration Architecture

One of the primary goals of enPortal is to deliver visual channels of information in a secure manner to a large web audience. Channels are an expected growth area for any deployment of enPortal.

enPortal is designed to be both flexible and capable of integrating, organizing, securing, and reusing channels. The system allows you to create new channels that display the HTML results of any proxied or unproxied HTTP requests within a channel. This allows existing web applications to be quickly and easily integrated. The design of new web interfaces can also be accomplished within enPortal by creating custom channels using JSP.

Note: Designing custom channels requires a basic understanding of web development disciplines including Java Server Pages (JSP), XML, and HTML. enPortal simplifies the process by handling most of the architectural issues (availability, security, persistence, and so on), allowing you to focus on the design of your channels. Prior to attempting content integration, you must have an overall understanding of the enPortal application that is explained in the enPortal Administration Guide.

enPortals foundation for integrating custom content is the channel. A channel defines an interface that can be messaged directly through HTTP. This allows request messages to be dispatched directly to a channel from any web browser. Furthermore, channels allow data and behavior to be encapsulated - a basic object-oriented principle.

The primary responsibility of the system is to provide an environment to design, instantiate, reference, secure, and broker requests to channels. This is accomplished with a secure directory of channel objects and a registry of channel classes.

The channel model and enPortal environment make the system extremely flexible and extensible. A customer can create new instances of existing channels and design new channels at any time.

The following scenario illustrates the system interaction that takes place when channels are being exercised.

1. An HTTP request is sent from a web browser to enPortal. For example:

http://host:port/enportal/servlet/pd/vdir/aFolder/myChannel? requestType=render

2. The enPortal Request Engine receives the request.

3. The enPortal Request Engine retrieves the specified channel /aFolder/myChannel from the enPortal Business Server ("ServerApp") and handles any channel security exceptions.

Note: This retrieval requires database interaction.


Content Integration Architecture

4. If there are no security constraints, the specified requestType "render" is translated into a JSP call by interrogating the channels specification. For example, the render requestType may map to framework/secured/pkg/aPackage/channelARender.jsp.

5. The request is dispatched to the render request handlers JSP implementation channelARender.jsp along with a copy of the /aFolder/myChannel channel object on which it will operate.

6. The JSP request handler generates an HTML response to the request by examining the internal data of /aFolder/myChannel object and interacting with any necessary external resources.

7. The request completes after the HTML is delivered to the web browser client.

This scenario illustrates that the specification, persistence, and security of channels are managed by the enPortal Business Server, and that the request processing of a channel is performed within the enPortal Request Engine.



1.2 Content Integration Overview

The following sections describe the various aspects of integrating content data from web-based applications.

Web-based Applications

The usual web-based application consists of several discrete functional areas:

Main Start Page - This is the usual entry point of the application. From this section authentication information, initial loading of shared resources (JavaScript, embedded frames) and links to other functional areas are presented. The application is usually designed with the assumption that users will pass through this point when using the application.

Content Pages - These pages are the reason why the user is using the tool. They provide the functionality of the tool or present valuable information to the user.

Authentication Mechanism - This refers to the handshaking performed to validate the credentials of a system user before allowing system access. Web-based applications use a variety of authentication mechanisms. They range from standardized solutions such as Basic/Digest Authentication to proprietary form based solutions.

HTTP Requests and Responses

Before you attempt to integrate content into enPortal, it is important to understand HTTP requests and responses. Both are briefly described below.

Anatomy of an HTTP Request

An HTTP request is sent from the portal to an application so that desired content can be retrieved and displayed in the portal channel.

Request Line - describes the request. It is in the format: Method URI Protocol/Version.Method can be either GET, POST, or HEAD. URI is simply a string that specifies a network resource such as a file or a virtual directory. Protocol/Version is the HTTP version number of the request. For example:

GET /location/myfile.html HTTP/1.0

HTTP Request Header - contains more information about the request. Examples of the information that may be contained in the header are the identity of the requestor and cookies sent from the requestor.

Entity-Body - the contents of the request. This is generally used only for POST requests. It can contain text or binary data that is provided to secondary processes such as CGIs.


Content Integration Overview

Anatomy of an HTTP Response

The HTTP response is returned to the portal from an application server as an answer to an HTTP request.

Status Code - describes the status of the response. It is a 3-digit integer value.

Values of 2XX indicate a successful response.

Values of 3XX indicate a redirection to take place.

Values of 4XX indicate a failure of content retrieval due to something on the server.

Values of 5XX indicate a failure of content retrieval due to a problem with the client or the request.

HTTP Response Headers - contains more information about the response. For example, the header can specify the method used to compress the response body.

Body - the contents of the response (HTML code, image data, and so on.)



1.3 Direct HTTP Based integration

If the application is designed correctly, direct access is available from the browser to the application, and single sign-on is not required, it is possible to use direct access (HTTPChannel) to integrate a product within enPortal. This mechanism is similar to "bookmarking used by the browser.

enPortal generates an HTTP reference to the application. The browser handles all retrievals and presentations. The content is not proxied by the CRS.

This method of integration has several drawbacks:

Access - the browser must have direct access to the content.

Security - there are several security mechanisms on the browser (Java/Javascript) that may prevent the application from working.

Structure - the application may contain unresolvable references, because it expects to be located in a top level frame.

Behavior - the application may takeover or breakout of the main enPortal frame.

Single Sign-on - single sign-on is not supported in this configuration.


Content Retrieval Service (CRS)

1.4 Content Retrieval Service (CRS)

enPortal provides a Content Retrieval Service (CRS) to retrieve content from an external server. The CRS is a transparent web proxy that can be configured to manipulate and change HTTP requests and HTTP responses. The CRS can set up static sockets allowing for the transmission of non-HTTP based content from the client to the server. The integration of new content from a non-web-based application is described in the following section Product Integration Strategy for Non-Web Applications on page 42.

The CRS provides the necessary tools to adjust content so that it will work properly within a channel without compromising the security of your network. It provides many mechanisms to modify and adjust content retrieved via HTTP. Some general functionality provided by the CRS includes:

Ability to retrieve secured content from inside a secured network, without direct access from the client to the web application

Ability to adjust content so that it functions correctly within the context of a enPortal frame

Ability to break down an application into basic functions and extract that functionality into a channel

Ability to provide single sign-on services, and to hide the details of authentication from the client

Ability to modify an applications Look and Feel and to change the branding of the application

Example Integration Micromuse JEL

The example that will serve throughout this section is the integration into enPortal of a Micromuse JEL server 2.0. Figure 1 shows the JEL application:

Figure 1: JEL Server



This application utilizes several technologies and techniques during integration:

Java - the Micromuse JEL is a Java applet.

TCP Connection - the applet uses a real-time TCP connection to exchange license and program data. This connection is proxied by the enPortal server.


Potential Obstacles to Integration

1.5 Potential Obstacles to Integration

Potential obstacles to integrating web-based applications are:

Design issues caused by the assumption that the Main Start Page is the primary means of accessing the content.

Custom authentication mechanisms.

Applet/JavaScript security issues.

Improper code in the content. For example, hard-coded URLs, relative frame based indexing of JavaScript objects, errors.

Content created from Web servers that do not follow Web development standards and specifications.

Code in the content that causes it to "take-over" a enPortal browsers window or create numerous pop-up windows.

Network connectivity issues.

Applet and/or plug-ins utilizing sockets.

Table 2 provides detailed information about these potential problems.

Table 2: Potential enPortal COntent Integration Issues (1 of 2)

Problem Description Symptoms

Java Sandbox Security Applets loaded from a given server are only allowed to make connections to the same server they are loaded from.

The applet does not load properly. An exception may appear in the Java Console.

JavaScript Data Tainting JavaScript loaded from a given server is restricted from accessing certain attributes on objects loaded from a different server.

JavaScript "Access Denied" error messages may pop up or appear in the browsers lower left corner.

Socket Connectivity Some applets require socket connections to secondary servers or ports.

Error messages either in the Java Console or pop-up dialogs or error conditions from the applet/plug-in.

Content Windowing Behavior The content may fill the entire enPortal window or generate new browser windows.

Content takes over the entire browser or multiple pop-up windows are launched outside of enPortal.

Hard-coded URLs Content can have hard-coded URLs referencing a different server other than the enPortal server.

Causes problems with Java Applets Sandbox, JavaScript data-tainting, and network connectivity.

Relative JavaScript Indexing The content can refer to objects that only exist in their parent frames.

"Object not Found" Error messages either in the JavaScript Error Message box, or in pop-up dialogs.



Custom Authentication The content can implement custom authentication mechanisms that restrict the access to internal pages.

Pages will authenticate sporadically when the authentication is present (cookies) or not at all when it is missing.

Embedded hidden frames Many applications embed shared JavaScript code used by sub-pages within hidden frames. These frames are only generated by the Main Start-up page.

"Object not Found" Error messages either in the JavaScript Error Message box, or in pop-up dialogs.

Table 2: Potential enPortal COntent Integration Issues (2 of 2)

Problem Description Symptoms


Tools Used in Integration

1.6 Tools Used in Integration

Gathering information on the structure and resources of an application is an important precursor towards integration. Information on the structure of the application can be gathered through the following mechanisms and tools.

Application Documentation

The Documentation included with the application is often a good primary source of information about the application.

OS Tools

Tools available on the operating system (for example, Netstat, IPConfig, Ping, and so on) can provide information on real-time connections and network connectivity. Often, a problem in displaying content can be related to an incomplete hostname or inaccessible IP address. Netstat can help you determine the status of TCP and UDP connections.

Network Analyzer / Packet Sniffer

A packet sniffer assists in determining the behavior of a distributed application. It allows the raw network traffic between a client and server to be examined. Comparing the network traffic of a web server that occurs when requests are proxied through the enPortal versus when requests are directly sent is a powerful debugging mechanism. However, there are several limitations to this approach:

Network Security Usage of a packet sniffer requires administrative privileges and may constitute a significant security risk on the network.

LocalHost Issues Packet sniffers are generally not able to listen over communications to the loop back (localhost,127.0.0.1). Diagnosing a problem can be made more difficult because of this fact. The observed communications should be conducted on the client machine for connections to a separate server. None of the components (Client, Server, external Web Application) should be located on the same machine.

Filtering Issues Problem diagnosis can be made more difficult by the global nature of these tools. Detailed filtering rules are often required to trim down the output.



Browser Resources

Web browsers provide several useful resources in analysis and debugging.

Properties Window The Properties window is a very useful tool for listing the URL of a particular web resource. This text can be copied and used to create a proxied channel. It is accessed by right-clicking anywhere in the browser window to display the pop-up menu and selecting Properties.

Java Console If the application contains a Java applet, the Java console can provide information on classes loaded, resources requested, and exceptions thrown. This information can be used to identify problems that prevent the content from loading.

Applets can execute in the native Java environment of your web browser or in a Java plug-in environment that has been added to your browser. Be aware that each environment has its own console and a distinct method for activating the console. The following methods are used to activate the Java consoles for some common platforms:

Netscape The Java console in Netscape is started using by selecting ToolsWeb DevelopmentJava Console.

Internet Explorer In IE the Java console is accessed by selecting Tools>Sun Java Console. If this menu option does not appear in the browser, the Java Console must be enabled from the Properties window. The next time IE is started the menu option will appear.

Java Plug-in Start the Java Plug-in Control Panel. This is available in the control panel for later versions of the plug-in and on the taskbar for earlier versions. Select the Show Java Console check box, click the Apply button, and restart all browsers on the machine. The next Java plug-in applet loaded will present a pop-up window containing the Java console

JavaScript Console Netscape provides a JavaScript console for JavaScript debugging. All JavaScript error messages are logged to this console. JavaScript expressions can also be directly typed into this console for immediate evaluation. These expressions are entered by typing JavaScript:expression... on the URL line. The Javascript console is not available in Internet Explorer.

View Source Often, the HTML source code of the web interface can provide information about the application. It is accessed by right-clicking anywhere in a page and selecting View Source.

Trial and Error A useful method for analyzing and debugging an application is to create a proxied channel and experiment with the channels output. The error messages that result will provide insight into the application.


Product Integration Strategy

1.7 Product Integration Strategy

When integrating a web-based application with enPortal, the primary tasks are:

1. Analyzing the solution, as described in Solution Analysis below.

2. Designing the solution, as described in Solution Design on page 28.

3. Implementing the solution, as described in Solution Implementation on page 29.

4. Deploying the solution, as described in Solution Deployment on page 39

5. Managing and maintaining the solution, as described in Managing and Maintaining a Deployed Solution on page 40

The following sections provide instructions for completing each task.

Solution Analysis

To obtain background information, consider the following when carrying out your analysis:

Functionality - determine the aspects of the web application to incorporate into a channel. For example the entire tool could be integrated into a single channel or the functional aspects of the tool could be pulled out and displayed in separate channels.

Technologies - determine the technologies used by the application. Technologies worth noting are Frames, various content/mime types, Java applets, Plug-ins, HTTPS, and TCP Socket based communications.

Application Structure - the structure and functionality of the application should be noted during the analysis phase. Attention should be given to how the application can be broken up into logical functions and eventually into enPortal channels; for example, a Report channel, Map channel and so on.

Network Connectivity Issues - verify connectivity between enPortal and the web application system. This can be accomplished by accessing the web application with a web browser hosted on the enPortal server. Verify connectivity between potential client locations and enPortal. This can be accomplished by accessing the running enPortal with a web browser at the client location.

If the application utilizes a socket as a data source for an applet or program, a separate port must be opened in any firewalls present between the client and the enPortal server. enPortal can proxy multiple client socket connections to an external application socket, so only one port is needed for each type of socket and data source.



Example Analysis/Investigation JEL Applet

The first step in the integration is to analyze the components of the application. For the JEL application there are four components. The following figure illustrates the relationship between these components:

JEL Web Server - this is the web server providing the HTML and applet class files to the requesting browser.

JEL Application Server - this is a Java process on the same machine as the JEL web server that provides a single TCP connection to all clients. This connection provides real-time data to the clients and controls licensing.

JEL Applet - this is the main workhorse of the JEL application. The applet runs inside the Browsers JVM (as through the use of the Java plug-in). It provides for the presentation and manipulation of JEL messages in either a graphical or tabular form.

HTML Page - the HTML page that the JEL web server provides for the web client. It can contain single or multiple Java Applets, additional text, graphics or other presentational features. The following is an HTML page for a sample JEL applet:

[1] [2] [3] JEL - Java Event List Demo 1

Figure 2:



[4] [5] [6] This JEL uses the "jel1" configuration

[7] [8] [9] [10] TCP connection host[11] TCP connection port[12] [15] [16] [17]

This sample JEL HTML output displays two key features affecting integration: use of an applet and use of TCP connection by the applet. The applet code is indicated by the HTML tag. This applet contains two parameters that imply the use of a TCP connection by this applet:

[1] [2]

Both of these parameters are hard coded to default values that may not be acceptable when running this application through enPortal. The 127.0.0.1 value for the host parameter is only correct when the clients located on the same host as the enPortal server. Additionally, the 7575 value for the port may not be appropriate for the configuration of the firewall.

These assertions can be verified by adding the URL for the JEL applet as a proxied channel. Displaying this proxied channel will result in a Failed JEL Connection Output message similar to the one shown in Figure 3.

Figure 3: Failed JEL Connection Message



Performing a Prototype Integration

Once the issues affecting integration have been identified and any connectivity problems issues have been addressed it is useful to prototype the integration in design mode. This allows problems to be quickly identified and resolved.

1. Log in to enPortal.

2. Create a test view.

3. Create an HTTP Proxy channel containing the main page of the application.

4. Start browsing the application.

5. Identify problem areas of the content. The following problem areas may require the creation of a custom CRS rules file:

Content takes over enPortal,

Content produces JavaScript error messages. No error messages are displayed when the content is retrieved directly from the application.

Applets fail to load.

Page/Host not found errors.

Images/links are broken.

CRS Rules File

The next step in prototyping is to create a prototype integration using a CRS rules file. When implementing applications that are well understood and defined, prototyping the integration can also be performed in conjunction with the implementation phase. However, it is recommended that you prototype the integration during the analysis phase for the following reasons:

It is more efficient to discover and address issues during the analysis phase than during the formal design and implementation phases.

The prototype initially developed during the analysis phase will be finalized and fully integrated with enPortal during the implementation phase.

The following instructions explain how to prototype the integration.

1. If any issues are discovered in the content, a CRS rules file should be created to modify the content and correct the error. After the CRS rules are defined, the enPortal JSP server must be restarted, or the CRS Runtime Rules must be reset using the /system/proxy/Manage Proxy channel.

The rules will be applied to the application content as it is being proxied through the enPortal server. This modifies the HTML stream that is returned to the clients web browser to correct the error.



2. After all the issues using the main page are identified, the individual functional components of the application should be pulled out and inserted into the test view as individual channels.

3. Repeat the above steps for each individual page.

CRS XML File

If any issues are uncovered during the initial phase of investigations that are not covered with the default CRS rule set, a new CRS rules file must be created to handle conditions in the content. This rules file will be specific to the channel and located in the runtimehandlers directory. This file is referenced by the channel parameter crsFilename. This parameter contains a , delimited list of all those files required by the channel. The CRS rules files are defined in XML according to the XML DTD specification located in PORTAL_HOME/xmlroot/server/dtds/crs/crsdefinition.dtd.

Custom CRS rules files are stored in the file system at the location /xmlroot/server/crs-custom/.

!!Warning: The CRS rules delivered with the system and the Product Integration Modules are stored in /xmlroot/server/crs/. Do not edit or create your own rules in this folder.

Example Prototype CRS Rules File for a JEL Application

The following is the initial CRS rules file (micromuse-jel.xml) for the Micromuse JEL example. At this point in the example, no rules have been added to the file. The rules file is managed in PORTAL_HOME/xmlroot/server/crs-custom.

[1] [2] [3][4] [5] [6]

Adding Content Modification

The following code, specifically lines 6-17, describes further rules to be inserted into the micromuse-jel.xml file. These rules change the values of the JEL applet parameters in the HTTP Response from the JEL web server.

[1] [2] [3][4] [5] [6] ^(.*)html(.*)[7] ^http://myjelhost(.*)



[8] [9] [10] [11] [12][13] [14] [15] [16] [17] [18]

Match Rules

There are two match rules for this CRS rule. They specify when the other rules should be run.

The first MatchMime specifies that this rule should only be run when the content type is text/html. This is to prevent binary data from being corrupted by the CreateReplacementStream rules.

The second MatchUrl rule tells the CRS to run this rule when the URL of the request starts with the text http://myjelhost (the CRS is proxying a request to the JEL web server).

The combination of these two rules specifies that this rule will only be applied to HTML pages from the JEL Web Server.

Content Rules

There are two CreateReplacementStream rules in this example:

The first modifies all occurrences of the text 127.0.0.1 in the HTTP Response from the JEL web server with another hard-coded value for the enPortal host. This rule is intended to adjust the host parameter in the JEL HTML from the hard-coded 127.0.0.1 to the enPortal host.

The second rule changes the hard-coded 7575 value in the JEL HTML to the value 1234. This will cause the applet to attempt a connection to the enPortal host over port 1234 rather than the hard-coded 127.0.0.1:7575.

Adding Socket Connection

The CreateSocket rule, line 20 in the example below, creates a TCP connection to bind communications to the enPortal JSP server port 1234 to port 7575 of the JEL Server.

[1] [2] [3][4] [5] [6]



[7] ^(.*)html(.*)[8] ^http://myjelhost(.*)[9][10] [11] [12] [13] [14][15] [16] [17] [18] [19][20] [21] [22]

Final Result

The following code shows the results of applying the CRS rules to the JEL HTML. It displays the modification of the hard-coded values (127.0.0.1:7575) to dynamic values (portalserver, 1234) looked up from the channel object. After the component is rendered it will display a functioning JEL applet. A netstat a command issued from the enPortal server will validate that a connection is active to the client over port 1234 and to the JEL application server over port 7575.

[1] [2] [3] JEL - Java Event List Demo 1[4] [5] [6] This JEL uses the "jel1" configuration

[7] [8] [9] [10] [11] [12] [14] [15] [16]



Solution Design

The following steps outline the activities that should be performed when designing your application integration solution. At this point, these are high-level activitiesno artifacts are created.

1. Identify a name for your solution. This will be the name of a new package.

2. Decompose your application into a set of smaller subcomponents. Continue decomposing until each subcomponent identifies functionality that could be reused by invoking the subcomponent with different parameters. These subcomponents will be new channel classes.

3. For each new subcomponent (ChannelClass), identify the parameters that are needed to invoke the "rendering" of the channel. This identifies channel FieldDefinitions. It is a good idea to specify as many FieldDefinitions as possible to ensure the maximum flexibility in runtime channel configuration.

Example Design

For the JEL application, partitioning the existing web interface and stepping through client-server dialoguing scenarios results in the following design. This design identifies the subcomponents and the web accessible interface that they will declare to enPortal.

[1] MM.JELRewrite [2] Superclass - http //Gets uri, baseURL, method[3] Renderer - redirectToRewrite.jsp //Reused render for proxied channel[4] Field - _dataTunnelPort //Port of the JEL application server(7575)[5] Field - _dataTunnelPortLocal // Port used by the enPortal server to client

During implementation these design decisions will require:

Custom XML class - All micromuse JELs are rendered by enPortal through a shared channel class.

XML Object files.

Channel parameterization - The parameters governing the JEL TCP connection are encapsulated into the definition of the channel class. The values of these parameters are accessible to the CRS when it is proxying the channel.

Defining Channel Class/Object Files

In order to minimize code duplication and maximize code reuse, it is beneficial to identify areas of consolidation. This can be accomplished by partitioning the web application into groups of related function calls. A channel class is a key partitioning point of enPortal. It defines a type of channel to be created. This allows the same definition to be shared across several channel objects.



Solution Implementation

The following sections outline the activities that should be performed when implementing your application integration solution.

Creating XML files

Channel and Object definition XML files should be created after the application is prototyped. The Class Definition file will contain the channel class definition for each type of channel created. One channel class should be created for each logical type of channel. The channel class should include each field that can be submitted in the query string as a Field definition.

Unique instance of channel classes are created as Channel objects. These Channel objects contain the unique data that controls their behavior. For HTTP Proxy channels, the location of the external resource that is being proxied is a parameter (field) of the channel that needs to be identified.

Since the proxied integration of an entire application may consist of many individual channels, a named Channel Target is used to maintain the knowledge of the protocol, host, port, and basePath of the web application.

Note: basePath is currently not used.

If the web application is moved to a new location, all the channels proxying to the application can be updated by editing the Channel Target that they reference.

Channel targets, channel objects and views for

Documents

4.6.1 Integration Guide - Edge Documentationdocs.edge-technologies.com/edge-docs/images/7/73/enPortal_4.6.1... · Edge Technologies, Inc. acknowledges th e Sun Developer Network for