The Novell Entitlement DTD is provided below. An explanation of the DTD is provided in the two sections following the DTD:
<!-*****************************************************************->
<!-- DirXML Entitlements DTD
<!-- Novell Inc.
<!-- 1800 South Novell Place
<!-- Provo, UT 84606-6194
<!-- Version=1.0.0
<!-- Copyright 2005 Novell, Inc. All rights reserved -->
<!--************************************************************* -->
<!--
Entitlement definition stored in the XmlData attribute of a
DirXML-Entitlement object.
-->
<!ELEMENT entitlement (values?)>
<!ATTLIST entitlement
conflict-resolution (priority | union) "priority"
display-name CDATA #REQUIRED
description CDATA #REQUIRED
>
<!ELEMENT values (query-app | value+)?>
<!ATTLIST values
multi-valued (true | false) "true"
>
<!ELEMENT value (#PCDATA)>
<!ELEMENT query-app (query-xml, result-set)>
<!ELEMENT query-xml ANY>
<!ELEMENT result-set (display-name, description, ent-value)>
<!ELEMENT display-name(token-attr | token-src-dn | token-association)>
<!ELEMENT ent-value (token-association | token-src-dn | token-attr)>
<!ELEMENT description (token-association | token-src-dn | token-attr)>
<!ELEMENT token-association EMPTY>
<!ELEMENT token-attr EMPTY>
<!ATTLIST token-attr
attr-name CDATA #REQUIRED
>
<!ELEMENT token-src-dn EMPTY>
<!--
Entitlement reference stored in the DirXML-EntitlementRef attribute of a DirXML-EntitlementRecipient or a DirXML-SharedProfile object.
-->
<!ELEMENT ref (src?, id?, param?)>
<!ELEMENT param (#PCDATA)>
<!ELEMENT id (#PCDATA)>
<!ELEMENT src (#PCDATA)>
<!--
Entitlement result stored in the DirXML-EntitlementResult attribute of a DirXML-EntitlementRecipient object.
-->
<!ELEMENT result(dn, src, id?, param?, state, status, msg?,timestamp)>
<!ELEMENT dn (#PCDATA)>
<!ELEMENT state (#PCDATA)>
<!ELEMENT status (#PCDATA)>
<!ELEMENT msg ANY>
<!ELEMENT timestamp (#PCDATA)>
<!--
Cached query results stored in the DirXML-SPCachedQuery attribute of a DirXML-Entitlement object.
-->
<!ELEMENT items (item*)>
<!ELEMENT item (item-display-name?, item-description?, item-value)>
<!ELEMENT item-display-name (#PCDATA)>
<!ELEMENT item-description (#PCDATA)>
<!ELEMENT item-value (#PCDATA)>
<!--
Representation of a DirXML-EntitlementRef within the DirXML Script and within the operation-data of an operation in an XDS document.
-->
<!ELEMENT entitlement-impl (#PCDATA)>
<!ATTLIST entitlement-impl
name CDATA #REQUIRED
src CDATA #REQUIRED
id CDATA #IMPLIED
state (0 | 1) #REQUIRED
src-dn CDATA #REQUIRED
src-entry-id CDATA #IMPLIED
>
The Entitlement DTD is broken into five parts: definition, reference, result, cached query, and internal reference information. The heading is just a comment and is optional. In the DTD, the heading for the Entitlement Definition is:
<!-- Entitlement definition stored in the XmlData attribute of a DirXML-Entitlement object. -->
Headings are followed by Elements (ELEMENT) and Attribute lists (ATTLIST). Below is a detailed explanation of the elements and attributes under the Entitlement Definition heading, which is the main heading you need to focus on when creating entitlements.
<!ELEMENT entitlement (values?)>
The root level element is <entitlement>, which can contain a single, optional, child <values> element. This is followed by the Attribute list, which includes conflict-resolution, display-name, and description. Conflict resolution uses Priority or Union attribute values.
conflict-resolution (priority | union) "priority"
Role-Based Entitlements use conflict resolution to determine what should happen when a valued entitlement is applied multiple times to the same object. For example, suppose that user U is a member of Entitlement Policy A and Entitlement Policy B, each of which reference the same valued entitlement E, but with a different set of values. Entitlement E of Entitlement Policy A has values (a, b, c). Entitlement E of Entitlement Policy B has a set of values (c, d, e).
The conflict resolution attribute decides which set of values should apply to user U. If the attribute is set to union, user U is assigned both sets of values (a, b, c, d, e). If it is set to priority, user U would get only one set of values, depending upon which Entitlement Policy has a higher priority.
If an entitlement is single-valued, conflicts must be resolved by priority, because a union of values results in more than one value being applied. Role-Based Entitlements presently uses this attribute; in the future, Workflow Entitlements might also use it.
display-name CDATA #REQUIRED description CDATA #REQUIRED
The literal entitlement name is not necessarily what an entitlement should display. The Display-name and Description attributes are intended for end-user display. (In Designer, you have an option to choose a display name for the entitlement instead of using the actual entitlement name.)
<!ELEMENT values (query-app | value+)?> <!ATTLIST values multi-valued (true | false) "true"
The <values> element is optional and indicates that an entitlement is valued. If you do not use this element, it means an entitlement is valueless. An example of a valued entitlement is an entitlement that grants a distribution list. An example of a valueless entitlement is an entitlement that grants an account in an application, such as the User Account entitlement that comes with the Active Directory driver.
Valued entitlements receive their values from three sources. One source is the external application (designated by the <query-app> element). Another is from a predefined list of enumerated values (one or more <value> elements). The third source is from the entitlement client (a <values> element with no<value> children). The examples are helpful in explaining the way values work.
Valued entitlements may be single-valued or multi-valued, and the default is multi-valued. It is the responsibility of the entitlement client to enforce this restriction.
<!ELEMENT value (#PCDATA)>
Entitlement values are untyped strings.
<!ELEMENT query-app (query-xml, result-set)>
If values come from an external application (such as an e-mail distribution list), you must specify an application query through the <query-xml> element. You extract the results from the query through the <result-set> element. We show two examples of this in Example 2: Application Query Entitlement: External Query.
<!ELEMENT query-xml ANY>
XML queries are XDS-formatted. The <query-xml> command is used to find and read objects from the connected application. The functionality for DirXML rules, object migration, etc. depends on the driver’s implementation of the query command. For more information on XML queries, see the Novell developer documentation on queries.
<!ELEMENT result-set (display-name, description, ent-value)> <!ELEMENT display-name(token-attr | token-src-dn | token-association)> <!ELEMENT ent-value (token-association | token-src-dn | token-attr)> <!ELEMENT description (token-association | token-src-dn | token-attr)> <!ELEMENT token-association EMPTY> <!ELEMENT token-attr EMPTY> <!ATTLIST token-attr attr-name CDATA #REQUIRED
Use the result set element to help you interpret the result of an external application query. There are three pieces of data that are of interest: the display name of the value (the display-name child element), the value’s description (the description child element), and the literal entitlement value (the ent-value child element), which is not displayed.
The token elements <token-src-dn>, <token-association>, <token-attr> are actually placeholders for XPATH expressions that extract the src-dn attribute value, association value, or any attribute values respectively from an XDS-formatted XML document. The DTD assumes that the query result is XDS.
The remaining entitlement headings in the Entitlement DTD serve different functions, but they are not items that you need to focus on when creating an entitlement.
<!-- Entitlement reference stored in the DirXML-EntitlementRef attribute of a DirXML-EntitlementRecipient or a DirXML-SharedProfile object. -->
The information stored in the Entitlement Reference portion of the DTD points to an entitlement object. This information is placed there by the managing agent (such as the Role-Based Entitlement driver, Entitlement.xml, or the Approval Flow driver, UserApplication.xml). This is the triggering event for an action to take place in a connected system. You don’t need to do anything with the DTD under this heading, but you can use this information to ensure that the entitlement object is being referenced.
<!-- Entitlement result stored in the DirXML-EntitlementResult attribute of a DirXML-EntitlementRecipient object. -->
The Entitlement Result portion reports the results about whether an entitlement is granted or revoked. The information includes the state or status of the event and when the event is granted or revoked (through a time stamp). You don’t need to do anything with the elements and attributes under this heading.
<!-- Cached query results stored in the DirXML-SPCachedQuery attribute of a DirXML-Entitlement object. -->
The Entitlement Query portion contains the entitlement values that are gathered from an external application. This information can then be used again if the entitlement client needs to display this information. These values are stored in the DirXML-SPCachedQuery attribute of the Entitlement object. You don’t need to do anything with the elements and attributes under this heading.
<!-- Representation of a DirXML-EntitlementRef within the DirXML Script and within the operation-data of an operation in an XDS document. -->
Because the DTD defines values for more than one document, this EntitlementRef portion is actually not part of the Entitlement definition. You don’t need to do anything with the elements and attributes under this heading.