Modes of Operation

Two primary modes of operation are supported:

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:

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:

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 final, constructed document appear.

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 DirXML 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 DirXML on the Publisher channel.

Replacement data is passed from the Subscriber channel to the Publisher channel via a URL in the e-mail message. The URL contains a query portion that contains the replacement data items.

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 if desired.

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.

Templates

This section describes document creation templates as used in the Manual Task Service Driver.

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 using XSLT).

Templates are used 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 and appear in bold.

Templates can also contain action elements. Action elements are control elements interpreted by the template-processing style sheet. Action elements are described in Section F.0, Manual Task Service Driver: Template Action Elements Reference. In the following examples action elements also appear in bold.

The following example template is used to generate an HTML e-mail message body:

<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$,

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> element is required because templates must be XML documents. The <form:text> 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" 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>

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>

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

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 Section D.0, Manual Task Service Driver: Replacement Data.

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 templates supplied with the Manual Task Service driver, the prefix used is form.

The elements appearing in bold in the above examples are action elements.

Action elements are described in detail in Section F.0, Manual Task Service Driver: Template Action Elements Reference.

Subscriber Channel E-Mail

The Subscriber channel of the Manual Task Service Driver is designed to send e-mail messages. To accomplish this, the driver supports a custom XML element named <mail>. Policies on the Subscriber channel construct a <mail> element in response to some eDirectory event (such as the creation of a user). An example <mail> element appears below:

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

The Subscriber 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.

The <mail> element and its content are described in detail in Section G.0, Manual Task Service Driver: <mail> Element Reference.

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 files are .css style sheets, images, etc. Examples of dynamic content are Web pages that change based on the replacement data contained in the URL or HTTP POST data.

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:

Driver Settings

This section describes parameters that appear in the “Driver Settings” section in the driver object user interface.

Many of these parameters are actually for the Publisher channel Web server. They appear under the Driver Settings area because the Manual Task Service Driver Subscriber also needs access to them.

<template>templates/e-mail _template#XmlData</template>

Subscriber Settings

Settings for the Subscriber channel are described in this section.

Publisher Settings

Settings for the Publisher channel are described in this section.

Subscriber Channel Policies

The configuration of the Subscriber channel policies depends on what a particular installation wants to accomplish with the Manual Task Service Driver. However, there are certain guidelines that might be helpful.

In general, the best place to construct a <mail> element to send to the Subscriber is in the Command Transformation policy. The reason for this is that most DirXML engine processing has been completed by the time commands reach the Command Transformation policy. This means that Create Policies have been processed for add events (allowing vetoing of add events for objects that don't have all the attributes necessary for constructing the e-mail, for example). This also means that modify events for objects without associations have already been converted to add events.

The XSLT style sheet that constructs the e-mail message might or might not need to query eDirectory for additional information.

For example, if the e-mail message is simply a welcome message to a new employee, then the add command can contain all the information necessary: Given Name, Surname, and Internet E-mail Address. This is accomplished by specifying in the Create policy that Given Name, Surname, and Internet E-mail Address are required attributes. This ensures that only add commands that contain the necessary information can reach the Command Transformation.

However, if the e-mail message is a message to the manager of an employee, then the style sheet needs to query eDirectory. The manager DN can be obtained from the add event for the employee's User object, but a query must be made to obtain the manager's e-mail address because that information is an attribute of the manager's User object.

In addition, if e-mail notifications are being generated as the result of modify commands for objects that are associated with the driver, then queries must be made to obtain information not contained in the modify command.

Subscriber Channel E-Mail Templates

E-mail templates are XML documents containing boilerplate and replacement tokens. E-mail templates are used to generate e-mail message body text. See Templates for general information about templates.

The replacement tokens used in an e-mail template dictate the <item> elements that must be supplied as children of the <replacement-data> element that is constructed by the Subscriber channel policy that constructs the <mail> element. For example, if the e-mail template has the replacement token $employee-name$ then there must be an <item name=“employee-name”> element in the replacement data for the <message> element. If the employee name item is not present, the resulting e-mail message body has no text in the location occupied by the replacement token in the template.

E-mail templates can be used to generate message bodies that are plain text, HTML, or XML.

If an e-mail template generates a plain text message, it must be processed by a style sheet that specifies plain text as its output type. If the style sheet does not specify plain text as its output type, then undesirable XML escaping will occur. The default Manual Task Service Driver style sheet, process_text_template.xsl, is normally used for processing templates that result in plain text.

Publisher Channel Policies

In most implementations of the Manual Task Service Driver, no Publisher channel policies are needed. This is because is it possible to construct the Web page and XDS templates so they result in exactly the XDS required and the XDS need not be further processed by policies.

If policies are required they will be very specific to an installation.

Publisher Channel Web Page Templates

Web page templates are XML documents containing boilerplate and replacement tokens. Web page templates are used to generate Web page documents (typically HTML documents). See Templates for general information about templates.

Replacement tokens in Web page templates dictate what replacement data is supplied as URL query data on the Subscriber channel. Replacement data on the Publisher channel is obtained from the URL query string for HTTP GET requests and from the URL query string and the POST data for HTTP POST requests.

As an example of the flow of replacement data from the Subscriber channel to the e-mail message and then to the Publisher channel Web server, consider the following scenario.

The Manual Task Service Driver is configured so that a new employee's manager is asked to assign a room number to the new employee. The trigger for the e-mail to the manager is the <add> command for a new User object that is processed by the Subscriber channel Command Transformation policy.

When the manager clicks a URL in the e-mail message, a Web page is displayed in the manager's Web browser. The Web page must indicate for whom the manager is entering a room number.

To accomplish this, the <url-query> element on the Subscriber channel contains a replacement data item that identifies the new user by name:

<item name=”subject-name”>Joe the Intern</item>

This causes the URL query string to contain (among other things) “subject-name=Joe%20the%20Intern”. (The “%20” is a URL-encoded space).

The manager's Web browser submits the URL to the Publisher channel Web server when the manager clicks the URL in the e-mail message. The Web server constructs a replacement data item named subject-name with the value Joe the Intern.

The Web page template also specified by the URL contains a replacement token $subject-name$. When the Web page template is processed by the style sheet to construct the Web page, the replacement token is replaced by Joe the Intern, which customizes the Web page for the employee whose User object creation caused the e-mail to be sent.

For additional information on a complete Subscriber-channel-to-Publisher-channel transaction, see Section H.0, Manual Task Service Driver: Data Flow Scenario for New Employee.

Publisher Channel XDS Templates

XDS templates are XML documents containing boilerplate and replacement tokens. XDS templates are used to generate XDS documents that are submitted to Identity Manager on the Manual Task Service Driver's Publisher channel. See Templates under the Overview section for general information about templates.

Replacement tokens in XDS templates dictate some of the replacement data that is supplied to the Web server as data in an HTTP POST request.

For example, consider the following XDS template:

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

The replacement tokens in the template dictate that the HTTP POST data must supply an association value and a room-number value.

Normally the association value would originate in the Subscriber channel. The Subscriber channel e-mail would place association=some value in the query string of the URL that is placed in the e-mail message. The Web page template used to generate the Web page when the URL is submitted to the Web server would typically place the association value in a hidden INPUT element:

<INPUT TYPE="hidden" NAME="association" VALUE="$association$"/>

Placing the association value as a hidden INPUT element causes the “association=some value” pair to be submitted as part of the HTTP POST data.

The room-number value is entered in the Web page using an INPUT element similar to the following:

<input TYPE="text" NAME="room-number" SIZE="20" MAXLENGTH="20"/>

If the manager enters 1234 and clicks Submit, the Web browser sends “room-number=1234” as part of the HTTP POST data.

The Web server then generates an <item name=“association”> replacement data item and an <item name=“room-number”> replacement data item which are used when processing the XDS template.

The XDS document is generated by processing the XDS template with the style sheet specified in the POST data. Then the XDS document is submitted to Identity Manager on the Manual Task Service Driver's Publisher channel.

Trace Settings

The Manual Task Service Driver outputs messages with various trace levels: