Novell IDENTITY MANAGER Driver Implementation Guide
Novell®
www.novell.com
Manual Task Service Driver Implementation Guide
Identity Manager
novdocx (en) 17 September 2009
AUTHORIZED DOCUMENTATION
3.6.1
June 05, 2009
Identity Manager 3.6 Manual Task Service Driver Implementation Guide
Legal Notices
Novell, Inc. makes no representations or warranties with respect to the contents or use of this documentation, and
specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose.
Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time,
without obligation to notify any person or entity of such revisions or changes.
Further, Novell, Inc. makes no representations or warranties with respect to any software, and specifically disclaims
any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc.
reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to
notify any person or entity of such changes.
Any products or technical information provided under this Agreement may be subject to U.S. export controls and the
trade laws of other countries. You agree to comply with all export control regulations and to obtain any required
licenses or classification to export, re-export, or import deliverables. You agree not to export or re-export to entities
on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export
laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses.
Please refer to the International Trade Services (http://www.novell.com/company/policies/trade_services) for more
information on exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary
export approvals.
novdocx (en) 17 September 2009
Copyright © 2008-2009 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied,
stored on a retrieval system, or transmitted without the express written consent of the publisher.
Novell, Inc. has intellectual property rights relating to technology embodied in the product that is described in this
document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S.
patents listed on the Novell Legal Patents Web page (http://www.novell.com/company/legal/patents/) and one or
more additional patents or pending patent applications in the U.S. and in other countries.
Novell, Inc.
404 Wyman Street, Suite 500
Waltham, MA 02451
U.S.A.
www.novell.com
Online Documentation: To access the latest online documentation for this and other Novell products, see
the Novell Documentation Web page (http://www.novell.com/documentation).
Novell Trademarks
For Novell trademarks, see the Novell Trademark and Service Mark list (http://www.novell.com/company/legal/
trademarks/tmlist.html).
Third-Party Materials
All third-party trademarks are the property of their respective owners.
novdocx (en) 17 September 2009
novdocx (en) 17 September 2009
4 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
Contents
About This Guide 9
1Overview 11
1.1 Modes of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.1.1 Example: Subscriber Channel E-Mail, Publisher Channel Web Server Response . . 12
1.1.2 Example: Subscriber Channel E-Mail, No Publisher Channel Response . . . . . . . . . 12
1.2 How E-Mail Messages and Web Pages Are Created by the Manual Task Service Driver. . . . 12
1.3 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.4 Replacement Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.5 Replacement Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.6 Template Action Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.7 Subscriber Channel E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.8 Publisher Channel Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
novdocx (en) 17 September 2009
2 Installing Driver Files 19
3 Creating a New Driver 21
3.1 Creating the Driver in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.1.1 Importing the Driver Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.1.2 Configuring the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.1.3 Deploying the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.1.4 Starting the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.2 Creating the Driver in iManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.2.1 Importing the Driver Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.2.2 Configuring the Driver Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.2.3 Starting the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.3 Activating the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4 Upgrading an Existing Driver 27
4.1 Supported Upgrade Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.2 What’s New in Version 3.6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.3 Upgrade Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5 Managing the Driver 29
A Driver Settings, Policies, and Templates 31
A.1 Driver Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
A.1.1 DN of the Document Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
A.1.2 Document Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
A.1.3 Use HTTP Server (true|false) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
A.1.4 HTTP IP Address or Host Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
A.1.5 HTTP Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
A.1.6 Name of KMO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
A.1.7 Name of Keystore File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
A.1.8 Keystore Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Contents 5
A.1.9 Name of Certificate (key alias). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
A.1.10 Certificate Password (key password) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.2 Subscriber Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.2.1 SMTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.2.2 SMTP Account Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.2.3 Default “From” Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.2.4 Additional Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.3 Publisher Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
A.3.1 Additional Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
A.4 Subscriber Channel Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
A.4.1 Blocking Commands from Reaching the Subscriber Channel. . . . . . . . . . . . . . . . . . 35
A.4.2 Generating E-Mail Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
A.5 Subscriber Channel E-Mail Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
A.6 Publisher Channel Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
A.7 Publisher Channel Web Page Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
A.8 Publisher Channel XDS Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
A.9 Trace Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
B Replacement Data 41
B.1 Data Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
B.2 XML Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
B.2.1 <replacement-data>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
B.2.2 <item> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
B.2.3 <url-data> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
B.2.4 <url-query> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
novdocx (en) 17 September 2009
C Automatic Replacement Data Items 47
C.1 Subscriber Channel Automatic Replacement Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
C.2 Publisher Channel Automatic Replacement Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
D Template Action Elements 49
D.1 <form:input>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
D.2 <form:if-item-exists>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
D.3 <form:if-multiple-items> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
D.4 <form:if-single-item> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
D.5 <form:menu> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
E<mail> Element 53
E.1 <mail> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
E.2 <to> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
E.3 <cc> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
E.4 <bcc> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
E.5 <from> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
E.6 <reply-to> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
E.7 <subject> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
E.8 <message> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
E.9 <stylesheet>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
E.10 <template> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
E.11 <filename> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
E.12 <replacement-data> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
6 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
E.13 <resource> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
E.14 <attachment> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
F Data Flow Scenario for a New Employee 57
F.1 Subscriber Channel Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
F.2 Publisher Channel Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
F.3 Description of Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
G Custom Element Handlers for the Subscriber Channel 69
G.1 Constructing URLs for Use with the Publisher Channel Web Server. . . . . . . . . . . . . . . . . . . . 69
G.2 Constructing Message Documents by Using Stylesheets and Template Documents . . . . . . . 70
G.3 SampleCommandHandler.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
G.3.1 Compiling the SampleCommandHandler Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
G.3.2 Trying the SampleCommandHandler Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
H Custom Servlets for the Publisher Channel 71
H.1 Using the Publisher Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
H.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
H.3 SampleServlet.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
H.3.1 Compiling the SampleServlet Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
H.3.2 Trying the SampleServlet Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
novdocx (en) 17 September 2009
Contents 7
novdocx (en) 17 September 2009
8 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
About This Guide
This guide provides information about configuring and using the Manual Task Service driver for
®
Novell
Identity Manager. The guide is organized as follows:
Chapter 1, “Overview,” on page 11
Chapter 2, “Installing Driver Files,” on page 19
Chapter 3, “Creating a New Driver,” on page 21
Chapter 4, “Upgrading an Existing Driver,” on page 27
Chapter 5, “Managing the Driver,” on page 29
Chapter A, “Driver Settings, Policies, and Templates,” on page 31
Appendix B, “Replacement Data,” on page 41
Appendix C, “Automatic Replacement Data Items,” on page 47
Appendix D, “Template Action Elements,” on page 49
Appendix E, “<mail> Element,” on page 53
novdocx (en) 17 September 2009
Appendix F, “Data Flow Scenario for a New Employee,” on page 57
Appendix G, “Custom Element Handlers for the Subscriber Channel,” on page 69
Appendix H, “Custom Servlets for the Publisher Channel,” on page 71
Audience
This guide is intended for administrators, consultants, and network engineers who require a highlevel introduction to Identity Manager business solutions, technologies, and tools.
Documentation Updates
For the most recent version of this document, see the Identity Manager Documentation Web site
(http://www.novell.com/documentation/idm36/index.html).
Additional Documentation
For documentation on other Identity Manager drivers, see the Identity Manager Drivers Web site
(http://www.novell.com/documentation/idm36drivers/index.html).
Documentation Conventions
In Novell documentation, a greater-than symbol (>) is used to separate actions within a step and
items in a cross-reference path.
A trademark symbol (
®
, TM, etc.) denotes a Novell trademark. An asterisk (*) denotes a third-party
trademark.
When a single pathname can be written with a backslash for some platforms or a forward slash for
other platforms, the pathname is presented with a backslash. Users of platforms that require a
forward slash, such as Linux* or UNIX*, should use forward slashes as required by your software.
About This Guide 9
novdocx (en) 17 September 2009
10 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
1
Overview
The Manual Task Service driver is designed to notify one or more users that a data event has
occurred and whether any action is required on the users’ part. In an employee provisioning
scenario, the data event might be the creation of a new User object and the user action might include
assigning an office number by entering data into eDirectory
Other scenarios include notifying an administrator that a new user object has been created or
notifying an administrator that a user has changed data on an object.
This section contains information about how the driver works.
Section 1.1, “Modes of Operation,” on page 11
Section 1.2, “How E-Mail Messages and Web Pages Are Created by the Manual Task Service
Driver,” on page 12
Section 1.3, “Templates,” on page 13
Section 1.4, “Replacement Tokens,” on page 15
Section 1.5, “Replacement Data,” on page 16
TM
or by entering data in an application.
novdocx (en) 17 September 2009
1
Section 1.6, “Template Action Elements,” on page 16
Section 1.7, “Subscriber Channel E-Mail,” on page 16
Section 1.8, “Publisher Channel Web Server,” on page 17
1.1 Modes of Operation
Two primary modes of operation are supported:
Direct Request for Data: An e-mail message is sent requesting that a user enter data into
eDirectory (possibly for consumption by another application). The e-mail recipient responds to
the message by clicking a URL in the message. The URL points to the Web server running in
the Publisher channel of the Manual Task Service driver. The user then interacts with dynamic
Web pages generated by the Web server to authenticate to eDirectory and to enter the requested
data.
Event Notification: An e-mail message is sent to a user without involving the Publisher
channel. The e-mail message might simply be notification that something occurred in
eDirectory, or it might be a request for data through a method other than the Publisher channel's
Web server, such as Novell iManager, another application, or a custom interface.
The following sections provide examples for each of these modes:
Section 1.1.1, “Example: Subscriber Channel E-Mail, Publisher Channel Web Server
Response,” on page 12
Section 1.1.2, “Example: Subscriber Channel E-Mail, No Publisher Channel Response,” on
page 12
Overview
11
1.1.1 Example: Subscriber Channel E-Mail, Publisher Channel Web Server Response
The following is an employee provisioning example scenario in which a new employee's manager
assigns the employee a room number:
1. A new User object is created in eDirectory (for example, by the Identity Manager driver for the
company's HR system).
2. The Manual Task Service driver Subscriber channel sends an SMTP message to the user's
manager and to the manager's assistant. The SMTP message contains a URL that refers to the
Publisher channel Web server. The URL also contains data items identifying the user and
identifying those authorized to submit the requested data.
3. The manager or the manager's assistant clicks the URL in the e-mail message to display an
HTML form in a Web browser. The manager or assistant then does the following:
Selects the DN for his or her eDirectory User object to identify who is responding to the e-
mail message.
Enters his or her eDirectory password.
Enters the room number for the new employee.
Clicks the Submit button.
novdocx (en) 17 September 2009
4. The room number for the new employee is submitted to eDirectory via the Manual Task
Service driver Publisher channel.
1.1.2 Example: Subscriber Channel E-Mail, No Publisher Channel Response
The following is an example scenario in which a new employee's manager assigns the employee a
computer in an asset management system:
1. A new User object is created in eDirectory by the Identity Manager driver for the company's
HR system.
2. The Manual Task Service driver Subscriber channel sends an SMTP message to the user's
manager and to the manager's assistant. The SMTP message contains instructions for entering
data into the asset management system.
3. The manager or assistant enters data into the asset management system.
4. (Optional) The computer identification data is brought into eDirectory via an Identity Manager
driver for the asset management system.
1.2 How E-Mail Messages and Web Pages Are Created by the Manual Task Service Driver
E-mail messages, HTML Web pages, and XDS documents can all be considered documents. The
Manual Task Service driver creates documents dynamically, based on information supplied to the
driver.
Templates are XML documents that contain the boilerplate or fixed portions of a document together
with replacement tokens that indicate where the dynamic, or replacement, portions of the
constructed document appear.
12 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
Both the Subscriber channel and the Publisher channel of the Manual Task Service driver use
templates to create documents. The Subscriber channel creates e-mail messages and the Publisher
channel creates Web pages and XDS documents.
The dynamic portion of a document is supplied via replacement data. Replacement data on the
Subscriber channel is supplied by the Subscriber channel policies, such as the Command
Transformation policy. Replacement data on the Publisher channel is supplied by HTTP data to the
Web server (both URL data and HTTP POST data). The Manual Task Service driver can
automatically supply certain data known to the Manual Task Service driver, such as the Web server
address.
The templates are processed by XSLT style sheets. These template-processing style sheets are
separate from style sheets used as policies in the Subscriber or Publisher channels.
The replacement data is supplied as a parameter to the XSLT style sheet. The output of the style
sheet processing is an XML, HTML, or text document that is used as the body of an e-mail message,
as a Web page, or as a submission to Identity Manager on the Publisher channel.
Replacement data is passed from the Subscriber channel to the Publisher channel via a URL in the email message. The URL contains a query portion that contains the replacement data items.
novdocx (en) 17 September 2009
The Manual Task Service driver ships with predefined style sheets sufficient to process templates in
order to create e-mail documents, HTML documents, and XDS documents. Other custom style
sheets can be written to provide additional processing options.
An advanced method of creating documents is also available, which uses only an XSLT style sheet
and replacement data. No template is involved. However, this guide assumes the template method is
used because the template method is easier to configure and maintain without XSLT programming
knowledge.
1.3 Templates
Templates are XML documents that are processed by a style sheet in order to generate an output
document. The output document can be XML, HTML, or plain text (or anything else that can be
generated through XSLT).
Templates are used in the Manual Task Service driver to generate e-mail message text on the
Subscriber channel, and to generate dynamic Web pages and XDS documents on the Publisher
channel.
Templates contain text, elements, and replacement tokens. Replacement tokens are replaced in the
output document by data supplied to the style sheet processing the template.
Several examples of templates for various purposes follow. In the examples, the replacement tokens
are the character strings that are between two $ characters.
Templates can also contain action elements. Action elements are control elements interpreted by the
template-processing style sheet. Action elements are described in Appendix D, “Template Action
Elements,” on page 49.
The following example template is used to generate an HTML e-mail message body:
Overview 13
<html xmlns:form="http://www.novell.com/dirxml/manualtask/form">
<head></head>
<body>
Dear $manager$,<p/>
<p>
This message is to inform you that your new employee <b>$given-name$
$surname$</b> has been hired.
<p>
You need to assign a room number for this individual. Click <a
href="$url$">Here</a> to do this.
</p>
<p>
Thank you,<br/>
HR Department
</p>
</body>
</html>
The following example template is used to generate a plain text e-mail message body:
<form:text xmlns:form="http://www.novell.com/dirxml/manualtask/form">
Dear $manager$,
novdocx (en) 17 September 2009
This message is to inform you that your new employee $given-name$ $surname$
has been hired.
You need to assign a room number for this individual. Use the following link to
do this:
$url$
Thank you,
The HR Department
</form:text>
The <
form:text
form:text
<
> element is required because templates must be XML documents. The
> element is stripped as part of the template processing.
The following template is used to generate an HTML form used as a Web page for entering data:
<html xmlns:form="http://www.novell.com/dirxml/manualtask/form">
<head>
<title>Enter room number for $subject-name$</title>
</head>
<body>
<link href="novdocmain.css" rel="style sheet" type="text/css"/>
<br/><br/><br/><br/>
<form class="myform" METHOD="POST" ACTION="$url-base$/
process_template.xsl">
<table cellpadding="5" cellspacing="10" border="1" align="center">
<tr><td>
<input TYPE="hidden" name="template" value="post_form.xml"/>
<input TYPE="hidden" name="subject-name" value="$subject-name$"/>
<input TYPE="hidden" name="association" value="$association$"/>
<input TYPE="hidden" name="response-style sheet"
value="process_template.xsl"/>
<input TYPE="hidden" name="response-template"
14 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
value="post_response.xml"/>
<input TYPE="hidden" name="auth-style sheet"
value="process_template.xsl"/>
<input TYPE="hidden" name="auth-template" value="auth_response.xml"/>
<input TYPE="hidden" name="protected-data" value="$protected-data$"/>
You are:<br/>
<form:if-single-item name="responder-dn">
<input TYPE="hidden" name="responder-dn" value="$responder-dn$"/>
$responder-dn$
</form:if-single-item> <form:if-multiple-items
name="responder-dn"> <form:menu name="responder-dn"/> </
form:if-multiple-items>
</td></tr>
<tr><td>
Enter your password: <br/>
<input name="password" TYPE="password" SIZE="20" MAXLENGTH="40"/>
</td></tr>
<tr><td>
Enter room number for $subject-name$:<br/>
<input TYPE="text" NAME="room-number" SIZE="20" MAXLENGTH="20"
value="$query:roomNumber$"/>
</td></tr>
<tr><td>
<input TYPE="submit" value="Submit"/> <input TYPE="reset"
value="Clear"/>
</td></tr>
</table>
</form>
</body>
</html>
novdocx (en) 17 September 2009
The following template is used to generate an XDS document:
<nds>
<input>
<modify class-name="User" src-dn="not-applicable">
<association>$association$</association>
<modify-attr attr-name="roomNumber">
<remove-all-values/>
<add-value>
<value>$room-number$</value>
</add-value>
</modify-attr>
</modify>
</input>
</nds>
1.4 Replacement Tokens
The items delimited by $ in the above example templates are replacement tokens. For example,
$manager$ is replaced by the manager's actual name.
Replacement tokens can appear either in text or in XML attribute values (note the href value on the
<a> element in the first example above).
Overview 15
1.5 Replacement Data
Replacement data consists of strings that take the place of replacement tokens in the output
document generated from a template. Replacement data is either supplied by Subscriber channel
data, Publisher channel HTTP data, or it is supplied automatically by the driver. An additional type
of replacement data is data retrieved from eDirectory via Identity Manager (query data).
Replacement data is more fully described in Appendix B, “Replacement Data,” on page 41.
Subscriber channel data: Subscriber channel replacement data is of two types. The first type is
used as replacement values for replacement tokens in templates for creating e-mail messages. The
second type is placed in the query portion of a URL so that the data is available for use on the
Publisher channel when the URL is submitted to the Publisher's Web server.
HTTP data: Replacement data is supplied to the Publisher channel Web server as URL query string
data, HTTP POST data, or both.
Automatic data: The Manual Task Service driver supplies automatic data. Automatic data items
are described in Appendix C, “Automatic Replacement Data Items,” on page 47.
Query data: Replacement tokens that start with query: are considered to be requests to obtain
current data from eDirectory. The portion of the token that follows query: is the name of an
eDirectory object attribute. The object to query is specified by one of the replacement data items
association, src-dn
preceding sentence.
, or
src-entry-id
. The items are considered in the order presented in the
novdocx (en) 17 September 2009
1.6 Template Action Elements
Action elements are namespace-qualified elements in the template that are used for simple logic
control or that are used to create HTML elements for HTML forms. The namespace used to qualify
the elements is http://www.novell.com/dirxml/manualtask/form. In this document and in the sample
form
templates supplied with the Manual Task Service driver, the prefix used is
Action elements are described in detail in Appendix D, “Template Action Elements,” on page 49.
.
1.7 Subscriber Channel E-Mail
The Subscriber channel of the Manual Task Service driver is designed to send e-mail messages. To
mail
accomplish this, the driver supports a custom XML element named <
mail
Subscriber channel construct a <
creation of a user. An example <
<mail src-dn="\PERIN-TAO\novell\Provo\Joe">
<to>JStanley@novell.com</to>
<cc>carol@novell.com</cc>
<reply-to>HR@novell.com</reply-to>
<subject>Room Assignment Needed for: Joe the Intern</subject>
<message mime-type="text/html">
<stylesheet>process_template.xsl</stylesheet>
<template>html_msg_template.xml</template>
<replacement-data>
<item name="manager">JStanley</item>
<item name="given-name">Joe</item>
<item name="surname">The Intern</item>
<url-data>
> element in response to some eDirectory event, such as the
mail
> element appears below:
>. Policies on the
16 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
<item name="file">process_template.xsl</item>
<url-query>
<item name="template">form_template.xml</item>
<item name="responder-dn" protect="yes">\PERIN-TAO\big-org\phb</
item>
<item name="responder-dn" protect="yes">\PERIN-TAO\big-org\carol</
item>
<item name="subject-name">Joe The Intern</item>
</url-query>
</url-data>
</replacement-data>
<resource cid="css-1">novdocmain.css</resource>
</message>
<message mime-type="text/plain">
<stylesheet>process_text_template.xsl</stylesheet>
<template>txt_msg_template.xml</template>
<replacement-data>
<item name="manager">JStanley</item>
<item name="given-name">Joe</item>
<item name="surname">The Intern</item>
<url-data>
<item name="file">process_template.xsl</item>
<url-query>
<item name="template">form_template.xml</item>
<item name="responder-dn" protect="yes">\PERIN-TAO\big-org\phb</
item>
<item name="responder-dn" protect="yes">\PERIN-TAO\big-org\carol</
item>
<item name="subject-name">Joe The Intern</item>
</url-query>
</url-data>
</replacement-data>
</message>
<attachment>HR.gif</attachment>
</mail>
novdocx (en) 17 September 2009
The Subscriber channel of the Manual Task Service driver uses the information contained in the
<mail>
element to construct an SMTP e-mail message. A URL can be constructed and inserted into
the e-mail message through which the e-mail recipient can respond to the e-mail message. The URL
can point to the Publisher channel Web server or it can point to some other Web server.
mail
The <
> element and its content are described in detail in Appendix E, “<mail> Element,” on
page 53.
1.8 Publisher Channel Web Server
The Publisher channel of the Manual Task Service driver runs a Web server configured so that users
can enter data into eDirectory through a Web browser. The Web server is designed to work in
conjunction with e-mail messages sent from the Subscriber channel of the Manual Task Service
driver.
The Publisher channel Web server can serve static files and dynamic content. Examples of static
.css
files are
based on the replacement data contained in the URL or HTTP POST data.
style sheets, images, etc. Examples of dynamic content are Web pages that change
Overview 17
The Publisher channel Web server is normally configured to allow a user to enter data into
eDirectory in response to an e-mail that was sent by the Subscriber channel. A typical user
interaction with the Web server is as follows:
1. The user uses a Web browser to submit the URL from the e-mail message to the Web server.
The URL specifies the style sheet, template, and replacement data used to create a dynamic
Web page (typically containing an HTML form).
2. The Web server creates an HTML page by processing the template with the style sheet and
replacement data. The HTML page is returned to the user’s Web browser as the resource
referred to by the URL.
3. The browser displays the HTML page and the user enters the requested information.
4. The browser sends an HTTP POST request containing the entered information as well as other
information that originated from the e-mail URL. The DN of the user responding to the e-mail
and the user’s password must be in the POST data.
5. The Web server uses the user’s DN and password to authenticate. If the authentication fails,
then a Web page containing a failure message is returned as the result of the POST request. The
failure message can be constructed by using a style sheet and template specified in the POST
data. If authentication succeeds, processing continues.
6. The Web server constructs an XDS document by using a style sheet and template specified in
the POST data. The XDS document is submitted to Identity Manager on the Publisher channel.
novdocx (en) 17 September 2009
7. The result of the XDS document submission, together with a style sheet and template specified
in the POST data, is used to construct a Web page indicating to the user the result of the data
submission. This Web page is sent to the browser as the result of the POST request.
18 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
2
Installing Driver Files
By default, the Manual Task Service driver files are installed on the Metadirectory server at the
same time as the Metadirectory engine. The installation program extends the Identity Vault’s
schema and installs both the driver shim and the driver configuration files. It does not create the
driver in the Identity Vault (see Chapter 3, “Creating a New Driver,” on page 21) or upgrade an
existing driver’s configuration (see Chapter 4, “Upgrading an Existing Driver,” on page 27)
If you performed a custom installation and did not install the driver on the Metadirectory server, you
have two options:
Install the files on the Metadirectory server, using the instructions in “Installing the
Metadirectory Server” in the Identity Manager 3.6.1 Installation Guide.
Install the Remote Loader (required to run the driver on a non-Metadirectory server) and the
driver files on a non-Metadirectory server where you want to run the driver. See “Installing the
Remote Loader” in the Identity Manager 3.6.1 Installation Guide.
novdocx (en) 17 September 2009
2
Installing Driver Files
19
novdocx (en) 17 September 2009
20 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
3
Creating a New Driver
After the Manual Task Service driver files are installed on the server where you want to run the
driver (see
Vault. You do so by importing the basic driver configuration file and then modifying the driver
configuration to suit your environment.
The driver provides four basic driver configuration files:
Access Request
Cellphone Request
Room Number Request
Welco me E -m ai l
The configuration files include the filters and policies needed to implement each scenario. If you
have a different scenario you want to implement, you should select the basic configuration that most
closely resembles your desired scenario and modify it as needed.
Chapter 2, “Installing Driver Files,” on page 19), you can create the driver in the Identity
novdocx (en) 17 September 2009
3
The following sections provide instructions for creating a new driver:
Section 3.1, “Creating the Driver in Designer,” on page 21
Section 3.2, “Creating the Driver in iManager,” on page 23
Section 3.3, “Activating the Driver,” on page 26
3.1 Creating the Driver in Designer
You create the Manual Task Service driver by importing the driver’s basic configuration file and
then modifying the configuration to suit your environment. After you create and configure the
driver, you need to deploy it to the Identity Vault and start it.
Section 3.1.1, “Importing the Driver Configuration File,” on page 21
Section 3.1.2, “Configuring the Driver,” on page 22
Section 3.1.3, “Deploying the Driver,” on page 22
Section 3.1.4, “Starting the Driver,” on page 23
3.1.1 Importing the Driver Configuration File
1 In Designer, open your project.
2 In the Modeler, right-click the driver set where you want to create the driver, then select New >
Driver to display the Driver Configuration Wizard.
3 In the Driver Configuration list, select the desired Manual Task Driver configuration file
(Access Request, Cellphone Request, Room Number Request, or Wel co me E m ail ), then click
Run.
The configuration files include the filters and policies needed to implement each scenario. If
you have a different scenario you want to implement, you should select the basic configuration
that most closely resembles your desired scenario and modify it as needed.
Creating a New Driver
21
4 On the Import Information Requested page, fill in the following fields:
Driver Name: Specify a name that is unique within the driver set.
Driver is Local/Remote: Select Local if this driver will run on the Metadirectory server
without using the Remote Loader service. Select Remote if you want the driver to use the
Remote Loader service, either locally on the Metadirectory server or remotely on another
server.
novdocx (en) 17 September 2009
5 (Con
6 Cl
7 To review or modify the default configuration settings, click Configure, then continue with the
ditional) If you chose to run the driver remotely, click Next, then fill in the fields listed
below. Otherwise, skip to Step 6.
Remote Host Name and Port: Specify the host name or IP addre
driver’s Remote Loader service is running.
Driver Password: Specify the driver object pa
service. The Remote Loader requires this password to authenticate to the Metadirectory server.
Remote Password: Specify the Remote Loader’s password (as defined
service). The Metadirectory engine (or Remote Loader shim) requires this password to
authenticate to the Remote Loader
ick Next to import the driver configuration.
At this point, the driver is created from the basic configuration file. To ensure that the driver
w
orks the way you want it to for your environment, you must review and modify (if necessary)
the driver’s default configuration settings.
next section, Configuring the Driver.
or
To skip the configuration settings at this time, click Cl
settings, continue with the next section, Configuring the Driver.
ssword that is defined in the Remote Loader
ose. When you are ready to configure the
ss of the server where the
on the Remote Loader
3.1.2 Configuring the Driver
There are many settings, policies, and templates that you use to configure and optimize the driver.
The ones you use depend on what you are trying to accomplish with the driver.
The driver settings, policies, and templates are explained in Chapter A, “Driver Settings, Policies,
and Templates,” on page 31.
After you configure the driver, it must by deployed. Continue with the next section, Deploying the
Driver.
3.1.3 Deploying the Driver
After a driver is created in Designer, it must be deployed into the Identity Vault.
1 In Designer, open your project.
the Modeler, right-click the driver icon or the driver line, then select Live > Deploy.
2 In
3 If yo
22 Identity Manager 3.6 Manual Task Service Driver Implementation Guide
u are authenticated to the Identity Vault, skip to Step 5; otherwise, specify the following
information:
Host: Specify the IP address or DNS name of the server hosting the Identity Vault.
Username: Specify the DN of the user object used to authenticate to the Identity Vault.
Loading...