Complete list of iChain FormFill tags

  • Document ID:3000667
  • Creation Date:19-Jul-2006
  • Modified Date:27-Apr-2012
    • Micro Focus Products:
      iChain

Environment

Novell iChain 2.3
FormFill (Form Fill)

Situation

This TID is intended as a complete reference of all available FormFill tags.  Associated with each tag is a description of the tag and examples of how it can be used in an iChain FormFill policy.

Resolution

FormFill policies follow standard XML document structure. Containertags require that an ending tag also be present. If no ending tagis required (because the tag is not a container), the tag name endswith a slash (/). For example, <post/> or <debugPost/>.

Table 1 lists all the FormFill tags available for use in a standardpolicy. Table 2 lists the additional FormFill tags that areavailable for use with Citrix implementations.

Table 1:
<urlPolicy>
</urlPolicy>		The<urlPolicy> is the main element in a Form Fill policy.Multiple <urlPolicy> sections may exist in a FormFill policy,each representing a separate page or form to process, or a separateset of criteria or actions to perform. Multiple <urlPolicy>sections may be required to handle conditions such as loginfailures or error messages for the same URL.
<name>
</name>		Subordinate of: <urlPolicy>

Specifies the name of the policy. Although this tag is optional,each policy should have a unique name. Having policy names isespecially important when using <deleteRemembered> tags inpolicies.

NOTE: The tag value cannot contain spaces.
<url>
</url>
Subordinate of: <urlPolicy>

Specifies the URL or form for the iChain Form Fill policy tomatch.

The URL defined in this tag needs to match the name of theprotected resource, not the name of the back end Web server.

Do not include the scheme (http://, https://) when specifying theURL. Specify only host and path. For example: www.address.com/loginform.html

NOTE: An asterisk at the end of the URL means the policy is not anexact match.
<cgiCriteria>
</cgiCriteria>		Subordinate of: <urlPolicy>

Evaluates the query string of a URL (portion after the ?) todifferentiate pages having the same URL.

The <cgiCriteria> tag complements the <url> tag. If a<cgiCriteria> tag exists in a policy, the text in thatsection must appear on the query string for the specified URL inorder for the policy to be deemed a match. Consider the followingURL:

https://webaccess.novell.com/servlet/webacc?Action=User.login

 For this URL, the following policy has been defined:

<url>webaccess.novell.com/servlet/webacc</url>
<cgiCriteria>Action=User.login</cgiCriteria>

This policy will match the URL listed above, but will not matcheither of the following URLs:

https://webaccess.novell.com/servlet/webacc
https://webaccess.novell.com/servlet/webacc?Action=User.logout
<formCriteria>
</formCriteria>		Subordinate of: <urlPolicy>

Causes iChain to find a match if the text specified in the<formCriteria> tag is found on the page. The text containedbetween the beginning and ending tags must appear in the documentreturned by the origin server for the page to be a match. Forexample:

<formCriteria><TITLE>iChainTestPage</TITLE></formCriteria>

iChain searches the HTML page for this string. If the text is foundin the document, the page is a match for the policy. If the text isnot found, the policy does not match.

If the <formCriteria>spans multiple lines, the text on eachline must either be left-justified, or appear in the documentexactly as specified in the policy. White space is not ignored. Forexample:

<formCriteria>
         <TITLE>iChainTestPage</TITLE>
loginForm
</formCriteria>

In the example above, the text<TITLE>iChainTestPage</TITLE> must appear in thedocument preceded by ten spaces, but the text loginForm can appearanywhere in the document at any position in a line. Both lines mustappear in the document for the page to be a match.

NOTE: iChain searches all of the information in these tags. Themore specific your information is, the faster iChain can match theform. Parsing <formCriteria> is a very intensive process foriChain to perform. If possible, using other criteria (such as<cgiCriteria>, <formName>, and <formNum>) ispreferred and can increase performance.
<formName>
</formName>		Subordinate of: <urlPolicy>

Causes the policy to match the page only when the name of the formmatches the <formName>value.

This tag has priority over the <formNum> tag. If both<formNum> tag and <formName> tags exist in the samepolicy, the <formName> tag is used, and a message isdisplayed on the SSO Debug screen indicating that both tags arepresent. For example:

<urlPolicy>
   <name>test</name>
   <url>www.novell.com/signon_welcome/screen</url>
   <formNum>2</formNum>
   <formName>name</formName>
</urlPolicy>

Using the <formName> tag is useful either as an additionalway to determine whether or not to process the page with Form Fill(such as when the same URL is used for both login and contentdisplay), or when multiple forms exist on the same HTML page.
<formNum>
</formNum>		Subordinate of: <urlPolicy>

Causes the policy to process form N, where N represents the forminstance within the document. Forms instances are countedsequentially from the top of the document down. For example:

<formNum>1</formNum>

The first form on the page is number one; the second, number two;and so on. For example:

<urlPolicy>
   <name>test</name>
   <url>www.novell.com/signon_welcome/screen</url>
   <formNum>2</formNum>
</urlPolicy>

This example causes the second form on the page to beprocessed.

If multiple forms exist in a page and neither the <formName>or <formNum> sections are specified in the policy, the firstform in the page is processed by Form Fill and all other forms onthe page are ignored.
<injectStaticValue>
</injectStaticValue>		Subordinate of: <urlPolicy>

Specifies information that will be injected into the form posting.Injected data overrides any values entered by the user, or any datastored in the iChainFormFillCrib, SecretStore, or retrieved fromthe user object via LDAP. Multiple values can be separated with theampersand (&) character.

The following line illustrates the valid way to inject a staticvalue in a Form Fill policy:

<injectStaticValue>city=Provo</injectStaticValue>

The following example illustrates how to supply multiplevalues:

<injectStaticValue>
   A=b&C=def&city=Provo
</injectStaticValue>

In this example, three separate values are injected:
  • The value of "A" is set to "b".
  • The value of "C" is set to "def".
  • The value of "city" is set to "Provo".
<javaScript>
</javaScript>		Subordinate of: <urlPolicy>

Retains JavaScript from the original page. Individual functions canbe listed for retention, or the entry can be left blank to retainall JavaScript in the page.

To retain all JavaScript code from the original page, specify thetag as follows:

<javaScript></javaScript>

To retain only a specific function, specify something similar tothe following:

<javaScript>
   functionName()
</javaScript>
<scriptForPost>
</scriptForPost>		Subordinate of: <urlPolicy>

Works in conjunction with the <javaScript> tag and specifiesadditional functions to be executed prior to the posting of theform.

If this tag is included in the policy, but is empty (no codebetween the open and close tags), the JavaScript function(s)specified in the onsubmit field of the original form tag execute(s)before the form is submitted. For example:

<scriptForPost></scriptForPost>

If this tag is included in the policy and is not empty, the linesare inserted into the <script>section of the documentgenerated by FormFill, and are executed before the form issubmitted. All content in this section must be proper JavaScriptsyntax for the resulting page to work properly. The user mayspecify functions which already appear in the original document, ormay be custom JavaScript that does not appear in the originaldocument. For example:

To execute an existing function called "setCookie" prior to formsubmission:

<scriptForPost>
    setCookie();
</scriptForPost>

To execute custom JavaScript statements:

<scriptForPost>
   document.cookie="myCookieName=myCookieValue";
    document.write("<div>Cookie has beenset.</div>");
</scriptForPost>
<sharedSecret>
</sharedSecret>		Subordinate of: <urlPolicy>

Specifies that users’ credentials are shared with otherapplications such as Novell exteNd Director or NovellSecureLogin.
<secretName>
</secretName>		Subordinate of: <sharedSecret>

Specifies the name of the Shared Secret to be used for this policy.If there is no <secretName> tag, the default secret name istaken from the <name>field of the policy. Following are someexamples of how this can be used:

Example One:
<name>FormFillSharedWithNSL</name>
<url>www.novell.com./formfill/test/*</url>
.........
<sharedSecret>
<secretName>https\://novell.com/nps/servlet/webacc?task\=abc&merg\=def</secretName>
</sharedSecret>
<actions>

NOTE: In the <secretName> field, if there is a colon(:),equal sign (=), and/or a backslash(\) character (these are reservedfor the secret ID), they must be preceded with a backslash(\)character.

Example Two:
<name>FormFillOwnSharedRule</name>
<url>www.novell.com/formfill/test.*</url>
..........
<sharedSecret>
</sharedSecret>
<actions>
...........

Example Two does not have a <secretName>, so the secret nameis the same as the <name>field. It is equivalent to havingthe following line:

<secretname>FormFillOwnSharedRule</secretName>
<migration/>Subordinate of: <sharedSecret>

Migrates the original credentials to Shared Secrets. The originalcredentials are stored in eDirectory or in NovellSecretStore.

NOTE: After migration, the original credential is transferred toShared Secrets and is removed from the old storage (eDirectory orSecretStore).
<actions>
</actions>		Subordinate of: <urlPolicy>

Specifies various actions for iChain to perform for this policy.The <actions>tag can contain <fill>, <post/>,<debugPost/>, <maskedPost/>, <redirect>,<errorRedirect> and <deleteRemembered> elements.
<fill>
</fill>		Subordinate of: <actions>

Delimits a section of the form that requires input. It is asubordinate element of <actions> and must contain either an<input> element, a <select> element, or both. Forexample:

<actions>
   <fill>
       <input name="role" type="radio" value="~title">
   </fill>
   <post/>
</actions>

This example fills in one field.
<input>
</input>		Subordinate of: <fill>

Specifies the form fields that need information and specifies howthat information is to be obtained. The fill section of the policycan have multiple <input> fields. The <input> fieldsyou place within the <fill> element must be specified in theorder they appear on the form. The <input> element has threerequired attributes (name, type, and value), one optional casemodifier attribute (ff_lower_upper), and one optional SharedSecrets attribute. For example:

<fill>
   <input name="username" type="text" value="~cn">
</fill>
<select>
</select>		Subordinate of: <fill>

Sets up a list box field and specifies how that information is tobe obtained. The fill section of the policy can have multiple<select> fields. The <select> fields you place withinthe <fill> element must be specified in the order they appearon the form. The <select> element has three requiredattributes (name, type, and value), one optional case modifierattribute (ff_lower_upper), and one optional Shared Secretsattribute. For example:

<fill>
   <select name="webserv" type="listbox" value="~">
</fill>
 nameAttributeof: <input>, <select>

Specifies the name of the field. This must match the name specifiedin the form.
 type
Attribute of: <input>, <select>

Specifies the type of field. This must match the type specified inthe form. For <input>elements this value can be: radio,checkbox, or text. For a <select> element, it must be set to:listbox.
 valueAttributeof: <input>, <select>

Specifies how the information is to be obtained. The tilde operatorallows you to determine whether the user must enter the informationor whether an eDirectoryTM attribute can be used to obtain theinformation. For more information on how to use this operator, see"The Tilde (~) Operator" in the FormFill chapter of the iChainAdministration Guide.
 ff_lower_upperAttributeof: <input>, <select>

Converts the resulting value to either all uppercase or alllowercase. Valid values for this attribute are "lower" or "upper."For example, to force lowercase conversion:

<fill>
   <input name="username" type="text" value="~cn"ff_lower_upper="lower">
</fill>

To force uppercase conversion:

<fill>
   <input name="username" type="text" value="~cn"ff_lower_upper="upper">
</fill>

If this attribute is not specified, or if the attribute value isnot specified as either "lower" or "upper", no case conversion isperformed on this field.
 ff_shared_name
Attribute of: <input>, <select>
This is a reserved field name for use with Shared Secrets.Some Shared Secrets applications might use a common name to sharethe value. This option works only when secure LDAP isenabled.
The policy name, for example, could be:

<inputname="user.id" value="~">

but in Shared Secrets, the field name is not User.id, it isUsername. In this case, the field is:

<inputname="user.id" value="~" ff_shared_name="Username">

NOTE: The value of the ff_shared_name applies to reading andwriting to or from Shared Secrets. It has nothing to do with theHTML form. For example, the name in the name=value pair of the formsubmission is still user.id, not Username, but the name in thename=value pair in Shared Secrets is Username, not user.id. Ifff_shared_name is missing, FormFill uses the value of name(user.id) as a default value.

<post/>Subordinate of: <actions>

Automatically submits the form.
<maskedPost/>Subordinate of: <actions>

When processing this tag, Form Fill replaces text input fieldvalues (username, password, etc.) with "nov-ss-ff-masked" insteadof the value specified by the "value=" parameter. The appropriatecorresponding values are replaced by iChain when the form issubmitted to the origin server. The user's browser never sees theactual values for these fields.
<debugPost/>Subordinate of: <actions>

Requires a <post/> or <maskedPost/> element. This is atroubleshooting tag that lets you verify that your information iscorrect before you submit the form. We recommend that you use thistag when creating a new policy and that you remove it when you havedetermined that the policy is behaving as expected.
<deleteRemembered>
</deleteRemembered>		Subordinate of: <actions>

Deletes the user's stored data for the named policy from either theichainFormFillCrib attribute or SecretStore, depending on yoursystem configuration. For example:

<deleteRemembered>GroupWise</deleteRemembered>

This example deletes the user's credentials stored for theGroupWise FormFill policy.
<redirect>
</redirect>		Subordinate of: <actions>

Redirects the user to the specified URI. For example:

<redirect>http://my.server.com/loginfailed.html</redirect>

This example redirects the user to the http://my.server.com/loginfailed.htmlpage. The format for the URI is

scheme://host/path

The scheme component is optional. It can be any valid scheme thatthe browser understands, such as http:// or https://. If notspecified, iChain defaults to http://.

The host component is the target server and can be specified byeither IP address or DNS name.

The path component is optional. It can be any valid path for thedesignated host and the resulting URI.

Example URIs for the <redirect>tag and the resultingURI:

https://www.company.com/->https://www.company.com/

www.company.com/loginfail.html->http://www.company.com/loginfail.html

/loginfailure.html->http:///loginfailure.html(this is an invalid URL)

GroupWise->http:///GroupWise(this is an invalid URL)

We recommend that you specify the complete URI for the newlocation.
<errorRedirect>
</errorRedirect>
Subordinate of: <actions>
In the event of an LDAP or NSSS error, the user is redirectedto the specified URL with the following query stringparameters:
  • Stage. The value for Stage is Fill | Post. Fill applies tobuilding the page. Post applies to the data that is processed andreturned.
  • URL. The URL of the original page.
  • Policy. The policy name. Unknown if no policy is found.
  • Error. The decimal error number, like -811.
  • Class. The subsystem that had the error, such as NSSS forSecretStore or LDAP for LDAP problems. See thesys:system\nls\err*.cfg for a list of possible errors.
  • Define. The corresponding #define in the source code.
  • Description. A human readable form of the detected error. TheCFG files contain more information.
For example if the specified URL is http://server/sample_URLerror.html,the user is redirected to:
If this tag is not used and an LDAP or NSSS error isencountered, the user is presented with the
standard iChain error page with corresponding information.
<LocalPolicy>
</LocalPolicy>		Becausethe buffer read limit in Form Fill is 50 KB, iChain lets you storeadditional Form Fill Policies on the local file system of theiChain machine.

Syntax: Add the following to the Form Fill Policy on the ISOobject:

<LocalPolicy>{Filename}</LocalPolicy>

NOTE:  If {FileName} does not contain a slash (\ /) or a colon(:), it is expected to reference a file in thesys:etc\proxy\appliance\config\user\formfill directory; otherwise,iChain reads the information as an absolute path. Multiple<LocalPolicy> tags can be included, but the maximum size ofthe resulting FormFill policy is limited to 1 MB. This tag canappear anywhere in the policy, and is not limited to a particularsection.

Table 2:
<icaFill>
</icaFill>		Subordinate of: <action>

When FormFill encounters ICA files as a response to a GET request,the information contained in this section will be used to rewritethe content for appropriate functionality through iChain.
<icaOriginal>
</icaOriginal>
Subordinate of: <icaFill>
This is a complementary tag of <icaReplace>.
Searches for the specified text in the ICA file received fromthe origin server.  Text in this section is replaced by thecontents of the <icaReplace> section.  Forexample:
<icaOriginal>
[WFClient]
</icaOriginal>
<icaReplace>
</icaReplace>
Subordinate of: <icaFill>
This is a complementary tag of <icaOriginal>.
The contents of this section replaces the contents of thepreviously specified <icaOriginal> section before the data issent to the browser.  For example:
<icaReplace>
[WFClient]
ProxyHost=citrix.novell.com:80
ICHAIN-TOKEN=60
</icaReplace>
ICHAIN-TOKEN is a special keyword that instructs iChain toinject an encrypted one time token, with a validity time frame,specified in seconds.  This ICHAIN-TOKEN is used by theICA client to authenticate to the ICA tunnel accelerator.  Thetoken data that is injected into the ICA file will be similar tothe following:
ProxyType=Secure
 ProxyUsername=5487e3deece6e46bfe39c82d
ProxyPassword=150c40ce5efbc3b5d562e70377c38ad500aa9922
<icaMetaPrivateAddress>
</icaMetaPrivateAddress>
Subordinate of: <icaFill>
This is a complementary tag of<icaMetaPublicAddress>.
This section specifies the DNS name(s) or address(es) of theinternal Metframe server(s).  Any addresses specified in thissection will be replaced by the address specified in the<icaMetaPublicAddress> section before the data is sent to thebrowser.  Multiple entries are specified on individuallines.  For example:
<icaMetaPrivateAddress>
    Address=1.1.1.1
    Address=2.2.2.2
</icaMetaPrivateAddress>
<icaMetaPublicAddress>
</icaMetaPublicAddress>
Subordinate of: <icaFill>
This is a complementary tag of<icaMetaPrivateAddress>.
This section is used to specify the address of the ICAtunnel accelerator.  This address replaces any addressspecified in the <icaMetaPrivateAddress> section in the ICAfile that is sent to the browser.  For example:
<icaMetaPublicAddress>Â
    Address=metaframe.mycompany.com
</icaMetaPublicAddress>

Additional Information

Previously known as TID 667.