The elements that make up a replacement data document are described below. If no XML attributes are described for an element, then none are allowed.
The <replacement-data> element can appear in the following locations:
As a child of the <message> element under a Subscriber channel <mail> element.
The Manual Task Service driver processes the supplied <replacement-data> element into a standalone <replacement-data> element for use in template processing. The following processing occurs:
If an association value is created for the enclosing <mail> element, an <item name=“association”> element is added to the replacement data. The value of the created element is the association value that is returned to Identity Manager.
If the <replacement-data> element has a <url-data> element child, then the <url-data> element is replaced by several <item> elements that contain constructed URL data. See <url-data> and <url-query>.
As the standalone top-level element of a replacement data document used when constructing a document using a style sheet on either the Subscriber or the Publisher channels.
The <item> element can be a child of the <replacement-data> element, the <url-data> element, or the <url-query> element. The content of the <item> element is the text used in the substitution of replacement tokens in templates. <item> elements are always named by using the name attribute.
name: The value of the name attribute specifies the name by which this data item is referenced by replacement tokens. For example, if the value of the name attribute is manager, then the replacement token $manager$ is replaced by the value contained by <item name=“manager”> element. The name attribute is required.
protect: For <item> elements that are children of <url-query> elements, the protect attribute specifies whether the item is added to the protected data section of the URL query string (see <url-query>. If the protect attribute is present, it must have the value yes.
Certain <item> elements have predefined meanings to either the Subscriber channel, the Publisher channel, or both channels.
template: The Publisher channel treats the value of the template item as the name of the template document to use in generating the response to an HTTP GET request.
When <item name=“template”> appears as a child of the <url-query> element on the Subscriber channel, the value is placed into the URL query data to specify to the Publisher channel Web server the name of the template document to use when responding to the HTTP GET request.
responder-dn: The Publisher channel uses the value of the responder-dn item in HTTP POST data as the DN of the eDirectory object against which the password supplied in the HTTP POST data is validated.
The Web server rejects any HTTP POST request that does not contain a responder-dn value and a password value. In addition, if the HTTP POST data does not contain a protected-data item, then the request is rejected.
The Subscriber channel supplies one or more <item name=“responder-dn” protect=“yes”> elements under the <url-query> element. Because the responder-dn items are used for user authentication, the items must be protected.
password: Supplied to the Publisher channel Web server via HTTP POST data. The item content is the password, which is validated against the eDirectory object specified by the responder-dn item in the POST data. The password item is normally entered in the HTML form used to generate the HTTP POST request.
Example:
<INPUT TYPE= "password" NAME="password" SIZE="20" MAXLENGTH="40"/>
response-template: Supplied to the Web server via HTTP POST data. Used to generate the Web page used as the response to the POST. The response-template item is normally specified by using a hidden INPUT element in the HTML form used to generate the HTTP POST request.
Example:
<INPUT TYPE="hidden" NAME="response-template" VALUE="post_form.xml"/>
response-stylesheet: Supplied to the Web server via HTTP POST data. Used to generate the Web page used as the response to the POST. The response-stylesheet item is normally specified by using a hidden INPUT element in the HTML form used to generate the HTTP POST request.
Example:
<INPUT TYPE="hidden" NAME="response-stylesheet" VALUE="process_template.xsl"/>
auth-template: Supplied to the Web server via HTTP POST data. Used to generate the Web page that is used as the response to the POST if authentication of the user fails. The auth-template item is normally specified by using a hidden INPUT element in the HTML form used to generate the HTTP POST request.
Example:
<INPUT TYPE="hidden" NAME="auth-template" VALUE="auth_response.xml"/>
auth-stylesheet: Supplied to the Web server via HTTP POST data. Used to generate the Web page that is used as the response to the POST if authentication of the user fails. The auth-template item is normally specified by using a hidden INPUT element in the HTML form used to generate the HTTP POST request.
Example:
<INPUT TYPE="hidden" NAME="auth-stylesheet" VALUE="process_template.xsl"/>
protected-data: The protected-data item contains the encrypted data constructed by the Subscriber channel. On the Subscriber channel, the protected data item is an automatically supplied item.
On the Publisher channel, the protected-data item is obtained from the URL query string for an HTTP GET request and is obtained from the POST data for an HTTP POST request.
The protected data item is typically passed from the HTTP GET request into the Web page used to generate the HTTP POST via a replacement token in the template used to construct the response to the HTTP GET.
Example:
<INPUT TYPE="hidden" NAME="protected-data" VALUE="$protected-data$"/>
The <url-data> element is a child of the <replacement-data> element found under the <message> element on the Subscriber channel. It contains <item> elements used to construct the URL and related data items that are supplied to the template used in constructing the e-mail message. It also contains the <url-query> element.
For the purposes of the Manual Task Service driver, URLs consist of five parts:
A scheme such as http, https, or ftp.
A host such as www.novell.com or 192.168.0.1.
A port number. This is a colon followed by a decimal integer. For example, :80 or :8180.
A file or resource specifier. This is typically a filename and can include path information. For example, stylesheets/process_template.xsl.
A query string. This is a collection of name-value pairs, separated by & characters. For example, template=form_template.xml&protected-data=AabABJKEL=
<item> elements under the <url-data> element are ignored unless they are one of the following. All of them are optional.
file: Specifies the file portion of the URL. If used with the Publisher channel Web server, the file item specifies the style sheet to use to construct the initial HTML page returned in response to the URL. If used with a server other than the Publisher channel Web server, the file item specifies the name of the resource that the URL refers to.
If the file item does not appear, the URL file portion defaults to process_template.xsl.
scheme: Optional item found under the <url-data> element. If present, it specifies the scheme portion of the URL (such as http or ftp). The scheme item is typically used only if the URL points at a server other than the Publisher's Web server.
If the scheme item does not appear, the URL scheme defaults to either http or https, depending on the configuration of the Publisher channel Web server.
host: Optional item found under the <url-data> element. If present, specifies the host portion of the URL. The host item is typically used only if the URL were to point at a server other than the Publisher's Web server.
If the host item does not appear, the URL host defaults to the IP address of the server on which the Manual Task Service driver is running (that is, the IP address of the Publisher channel Web server).
port: Optional item found under the <url-data> element. If present, specifies the port portion of the URL. The port item is typically used only if the URL points at a server other than the Publisher's Web server.
If the port item does not appear, the URL port defaults to the port on which the Publisher channel Web server is running.
The <url-query> element is a child of the <url-data> element. It contains <item> elements that are used to construct the query portion of the URL used in the e-mail message.
Each item that appears as a child of the <url-query> element is placed in the query string in the form name=“value” where name is the value of the <item> element's name attribute and value is the string content of the <item> element.
Item elements that appear under <url-query> can have a protect attribute with the value “yes.” If this is the case, the item names and values are encrypted and placed within a generated name-value pair in the URL query string. The name of the generated value is protected-data. The value is the Base64-encoded and encrypted name-value pair or pairs for multivalued attributes.
Protecting data ensures that the data cannot be changed when the URL is submitted to the Publisher channel Web server. For example, the responder-dn data items need to be protected to ensure that only those users authorized to respond to the e-mail message are able to change eDirectory data.
If the URL generated is to be used with the Publisher channel Web server, the <url-query> element must contain at least one <item name=“responder-dn” protect=“yes”> element or the Web server rejects the eventual HTTP POST request.