# INTRODUCTION

# PHIN DIRECTORY EXCHANGE
Information held in local instances of a public health directory must be sharable to ensure that partners have the most current contact information and can support crossjurisdictional communications. Directory exchange is aimed at increasing directory accuracy, reducing redundant maintenance of information in local directories and distributing the burden of maintenance across organizational entities.
There are three main aspects involved in directory exchange: a common exchange schema is required to describe the attributes to be exchanged, a standard exchange protocol must be used to describe the content and the action to be taken by the recipient, and the exchange must be executed in adherence with secure transport requirements.

# WHAT IS AN IMPLEMENTATION GUIDE?
A public health directory exchange implementation guide is a document that describes: a) The circumstances under which directory exchange takes place.
b) The data and schema for the information being exchanged. c) Additional specifications and guidance to assist in directory exchange implementation.

# AUDIENCE
This guide is designed to be used by analysts who need a better understanding of the requirements of directory exchange, and by implementers working to develop PHIN applications.

# DOCUMENT STRUCTURE
The body of this document contains the following major sections:
- Application Requirements and Data Flows: describes the context and usage for directory exchange. - Message Definition: describes the types of messages used to define directory attributes.
- Example Messages: additional information about sample messages that will be useful to implementers. - Appendices: contain information about DSML 1 and vocabularies.

# CONTACTS
For more information on this document, please contact:  The functions defined below should not be considered as a design specification. The diagram and associated functional descriptions should be used to help developers understand the functionality required to implement directory exchange. Each section will describe the responsibilities of this functional area in the overall process of directory exchange. Each partner will design a system that supports these functions.
PHIN

# SENDING PARTNER TRANSLATOR FUNCTION:
The sending partner translator functions are responsible for extracting People, Communication Devices and Organization information from a local version of a public health directory and putting them into a DSML version 1.0 formatted document. Please refer to section "Sending Partner DSML Translator Function" below for more information on how to generate this document.
During the development of the DSML version 1.0 document, appropriate vocabularies must be applied to define things like Organization type and communication device capabilities. Refer to the "Partner Vocabulary Services" section for a more detailed explanation of the vocabulary requirements.
In order to fulfill its responsibilities, a sending partner's translator system needs to support the following functionalities. - The ability to retrieve Person, Communication Devices and Organization information from the partner's public health directory. - The ability to support the functionality defined within the "Partner Vocabulary Services Function" defined below. - The ability to support the "Sending Partner DSML Translator Function" defined below.
- The ability to support the functionality defined within the "Partner Transport Service Function" defined below.

# PARTNER VOCABULARY FUNCTION
The Partner Vocabulary function is a set of processes that can either be implemented manually or automated to maintain vocabularies required to support directory exchange. Having consistent maintainable vocabularies between partners is an important function in any directory exchange solution. Some of the vocabularies required to support directory exchange will be stored and maintained in the PHIN VADS system while others that are more communication device specific are maintained within this implementation guide in Appendix E. Implementers of this function will be required to put a process in place to make sure the vocabularies are maintained.
In order to fulfill its responsibilities, a partner's vocabulary system needs to support the following functionalities. - The ability to synchronize local vocabularies with the PHIN VADS vocabulary service located at  - The ability to maintain a local version of vocabularies required for alerting that are not stored in the PHIN VADS system. These vocabularies are located in Appendix E. - The ability to maintain version control for the vocabularies stored locally.

# SENDING PARTNER TRANSPORT FUNCTION
The Partner Transport Function is responsible for preparing the message for transport to another exchange partner. The mechanism used to transport the data between partners must be compatible with the ebXML transport requirement identified in the PHIN Requirements.
In order to fulfill its responsibilities, a sending partner's transport system needs to support the following functionalities.
- Provide the ability to store the metadata required to send the DSML document to an appropriate partner. - Provide the ability to send a secure electronic message.
Note: If you would like to implement the PHINMS to fulfill this requirement, please refer to the PHINMS Web Site located at /

# RECEIVING PARTNER DSML TRANSLATOR FUNCTION
Each Receiving Partner is responsible for receiving and parsing one or more DSML version 1.0 formatted documents containing Person, Communication Device and Organization information using ebXML described in the "Partner Transport Function" section of this document.
The CDC has developed a DSML translator tool that is available to support this functionality. Please refer to the "CDC DSML Translator Tool" later in this section for additional information about this tool.
In order to fulfill its responsibilities, a receiving partner's translator system needs to support the following functionalities.
- The ability to receive one or more DSML version 1.0 compliant documents from a sending partner. - The ability to parse the DSML version 1.0 compliant documents into an appropriate format to be loaded into your local instance of a public health directory. - The ability to use or map the vocabulary defined in the "Partner Vocabulary
Function" section into a local form if needed.

# RECEIVING PARTNER TRANSPORT SERVICE FUNCTION
The Receiving Partner Transport Function is responsible for receiving and extracting an ebXML compliant message from another exchange partner and loading the data into a local instance of a public health directory. The mechanism used to transport the data between partners must be compatible with the ebXML transport requirement.
In order to fulfill its responsibilities, a receiving partner's transport system needs to support the following functionalities. - Provide the ability to receive a secure transport in accordance with the ebXML transport requirement. - Provide the ability to map vocabularies as defined in section "Partner Vocabulary Function" section of this document to local vocabularies if needed. - Provide the ability to acknowledge back to the sending transport system using the ebXML transport system.

# CDC DSML TRANSLATOR TOOL
The CDC has a DSML translator tool available which consists of a basic database schema that defines three tables to structure People, Communication Devices and Organization information. This tool is distributed free by CDC. The tool assumes that the partner will populate this simple structure from their repository. The tool will then extract the information from the schema and generate an appropriate DSML version 1.0 compliant document suitable for transport to another partner.
The tool can also be executed on the receiving partner's side to parse the DSML version 1.0 document and populate the basic database schema previously described. The receiving partner would then be able to import the information from the basic schema back into their repository. The use of this tool is optional. Each partner can either use the tool as is, receive source code for the tool to modify as needed, or create their own tool to manage the generation of the appropriate DSML version 1.0 compliant document.
For more information on CDC's DSML translator tool please contact the PHIN Help Desk (Email: PHINTech@cdc.gov; Phone: 1-800-532-9929 or 770-216-1299) Any unique identifier can be used; however we suggest using the Organization's name. Additional information may be added to make the reference unique in those cases where there are several organizations with the same name. Although this is not guaranteed to be unique, it is the most unique of the attributes being exchanged. This DSML schema was never meant to directly populate an LDAP repository and was only intended to support structured data exchange.

# PHIN Directory Exchange Implementation Guide
Version:1. 0 This attribute defines the distinguished name reference to the primary organization for this person. This will match the  reference in the organization that you are associating to this person. We will only support single value references for this initial release of the schema. Future releases will be able to support references of a person to multiple organizations. This value should only be populated when device type is "Fax", "Mobile", "Pager", "Satellite" or "Telephone".

# COMMUNICATION DEVICE

# Example Person Message
     top person organizationalPerson inetOrgPerson PhinPerson   John Smith   Smith   AGDR-ADRS-234T-RT67   John is a good Fellow!   John T. Smith   John   john.Smith@cdc.gov   en   Program Manager   Role A Role B   DeKalb   cn=Centers for Disease Control and

# PHIN Directory Exchange Implementation Guide
Version:1. 0 Prevention,ou=phindirOrganizations,DC=phindir,DC=gov    

# Example Communication Device / Telephone Message
     top AlertCommunicationDevice   Telephone1   Main point of contact.   Telephone   BusinessHours   404   444   7777   1         top AlertCommunicationDevice   email1   I can receive this e-mail on my blackBerry 24 hours a day   eMail   24x7   john.Smith@cdc.gov   2   true   false          CDC Headquarters   Edward R. Roybal Campus 1600 Clifton Road, NE   13   Atlanta   30333   13089   404-639-3311   555-123-4567      Fed (HHS) CDC    

# Example Communication Device / Email Message

# Example Organization Message

# INTRODUCTION
The Directory Services Markup Language, or DSML, provides a means for representing directory structural information as an XML document. The intent of DSML is to allow XML-based enterprise applications to leverage profile and resource information from a directory in their native environment. DSML allows XML and directories to work together and provides a common ground for all XML-based applications to make better use of directories. DSML is intended to be a simple XML schema definition that will enable directories to publish basic profile information in the form of an XML document so that it can be easily shared via native Internet protocols (such as HTTP or SMTP), as well as used by other applications. The principal goal is to ensure that directories are able to make a growing breed of XML based applications directory aware. It is not an initial goal of DSML to specify the attributes that all directories must contain, or the method with which the directory information is accessed from the directory. The expectation is that standard protocols (such as LDAP), proprietary access protocols (such as Novell's NDAP) and proprietary APIs (such as Microsoft's ADSI) could produce DSML documents as an optional output.

# A NOTE ON AMBIGUOUS TERMINOLOGY
Because this specification discusses both XML and directories, there is a danger of terminology from one domain being confused with that from the other. In particular, the words "attribute" and "schema" have meaning in both the XML and directory domains. For this reason, this specification always qualifies the word "attribute" as either XML attribute or a directory attribute and likewise with the word "schema".

# THE DSML NAMESPACE URI
In this specification, the prefix "dsml" is used on XML elements to indicate that they belong to the DSML Namespace. The prefix (as with all XML Namespace prefixes) is arbitrary and any suitable prefix may be used (or the namespace declared as default). It is the URI which ultimate identifies the namespace, not the prefix.

# CONCEPTUAL OVERVIEW
A DSML document describes directory entries, a directory schema or both. Each directory entry has a universally unique name called its distinguished name. A directory entry has a number of property-value pairs called directory attributes. Every directory entry is a member of a number of object classes. An entry's object classes constrain the directory attributes the entry may take. Such constraints are described in a directory schema which may be included in the same DSML document or may be in a separate document.

# TOP-LEVEL STRUCTURE
The document element of DSML is of the type dsml which may have a child element of the type directory-entries. This element, in turn, has child elements of the type entry. The dsml element may also (if the document contains a directory schema) have a child element of the type directory-schema which, in turn, has child elements of the type's class and attributetype.
At the top-level, the structure of a DSML document is thus: The top-level element dsml takes an optional XML attribute complete. A value of true indicates that the entries under directory-entries contain no external references. Either all attribute-types and classes referenced are found in the directory-schema section of the document or there are no references at all. A value of false indicates that at least one reference is to an external DSML document containing a directory schema. The default value is true.

# DIRECTORY ENTRIES

# The entry element type
Each entry represented in a DSML document is done so using an element of the type entry.
The entry element contains elements representing the entry's directory attributes. The distinguished name of the entry is indicated by the XML attribute dn.
NOTE: This specification does not provide a canonical form for distinguished names. Because normalization and ordering can vary between producers of DSML, some form of canonicalization would need to be performed by a consumer of DSML before string matching the values of the XML attribute dn.
It was decided to express the distinguished name as an XML attribute rather than a child element because of its identifying characteristic.
  top person organizationalPerson inetOrgPerson  Rabbit prabbit prabbit@dsml.org Peter Peter Rabbit 

# Entry Object Class
The object classes of an entry are represented by oc-value child elements of an objectclass element. The content of each oc-value element indicates an object class to which the entry belongs. In the case where an object class has more than one name, only one name need be used. Both objectclass and oc-value have an optional XML attribute ref. Reference to an attribute-type defining the objectclass directory attribute. The latter would not often be used but is provided to allow for extension of the objectclass directory attribute.
 person organizationalPerson 

# Directory Attributes
Directory attributes (with the exception of "objectclass") are represented by an attr element. This element has a mandatory XML attribute name which indicates a name of the directory attribute. (A directory attribute may have more than one name, but only one need be expressed in the name attribute.)
The value or values of a directory attribute are expressed in child elements of the type value.
NOTE: the content of value is PCDATA and hence any XML markup (or characters that could be treated as markup, namely < or &) must be escaped via CDATA section, character reference or pre-defined entity.
Each attr element may have an optional ref XML attribute whose value is a URI reference (URI + XPointer) pointing to an attribute-type definition in a directory-schema in the same or different DSML document.
For example, if a DSML document with a directory-schema accessible at the URL  has the attribute-type definition  eyecolor The color of the person's eyes ...  then an entry in directory-entries might have a child element  blue 

# Multi-valued Attributes
Where an entry has multiple values for a particular attribute, that attr element has multiple value children.  top person organizationalPerson inetOrgPerson  Rabbit prabbit  prabbit@dsml.org peterr@home.com  Peter Peter Rabbit  6.6.5 Binary Data Directory attributes containing binary data are encoded using an encoding scheme identified by an XML attribute encoding on the value element. At present, DSML supports only base64 as a value, but the encoding XML attribute is included in order to enable support for other encoding schemes in the future. NOTE: base64 encoding, as described in RFC 1521, allows for whitespace characters which are to be ignored by any decoding software. Furthermore, base64 encoding does not introduce   MIICJjCCAY+...   6.7 DIRECTORY SCHEMA

# Object Classes
Each directory entry has a number of object classes, indicated by elements of the type objectclass.
An object class is defined with a class element in a directory-schema. The class element takes an ID XML attribute id to make referencing easier.
The object class definition for the "person" object class might look like: <dsml:class id="person"
superior="#top" type="structural"> person ... 2.5.6.6       

# id (XML attribute)
A locally unique identifier for the object class. This enables the object class to be referenced across the Web, in particular from the ref XML attribute of an entry's objectclass or a subclass's superior XML attribute.

# superior (XML attribute)
The URI Reference of class(es) from which this one is derived.

# type (XML attribute)
One of structural, abstract or auxiliary.

# obsolete (XML attribute)
One of true or false. Defaults to false.

# name (child element)
The NAME of the object class.

# description (child element)
The optional DESC of the object class.

# object-identifier (child element)
The object identifier (OID) of the object class.

# attribute (child element)
A directory attribute type that entries of this class may or must have.

# ref (XML attribute on attribute element)
The URI Reference of the directory attribute type.

# required (XML attribute on attribute element)
One of true or false. Indicates whether entries of this class are required to have the directory attribute or not.
XML attributes were chosen in those cases where the information provides unique identification (using an ID attribute not only ensures uniqueness but allows for ease of reference via XPointer), is an enumeration (which, in a DTD, can only be constrained for attributes) or is a reference.

# Attribute Type Definitions
Directory attribute types are defined in a similar way to object classes.
For example:
 cn ... 2.5.4.3   mail ... 0.9.2342.19200300.100.1.3 0.9.2342.19200300.100.3.5 

# id (XML attribute)
A locally unique identifier for the attribute type. This enables the attribute type to be referenced across the Web, in particular from the ref XML attribute of an entry's attr or a derived directory attribute's superior XML attribute.

# superior (XML attribute)
The URI Reference of attribute type from which this one is derived.

# obsolete (XML attribute)
One of true or false. Defaults to false.

# single-value (XML attribute)
One of true or false. Defaults to false.

# user-modification (XML attribute)
One of true or false. Defaults to true.

# name (child element)
The NAME of the attribute type.

# description (child element)
The optional DESC of the attribute type.

# object-identifier (child element)
The object-identifier (OID) of the object class.

# syntax (child element)
An OID indicating the allowed syntax of values of this attribute type. 10. bound (XML attribute on syntax) The suggested minimum upper bound for the attribute type.

# equality (child element)
An OID indicating the equality matching rule.

# ordering (child element)
An OID indicating the equality matching rule.

# substring (child element)
An OID indicating the equality matching rule.
XML attributes were chosen in those cases where the information provides unique identification (using an ID attribute not only ensures uniqueness but allows for ease of reference via XPointer), is an enumeration (which, in a DTD, can only be contained for attributes) or is a reference.

# CONFORMANCE
In defining conformance, it is useful to divide DSML documents into four types:
1. Documents containing neither directory schema nor any references to an external schema. 2. Documents containing no directory schema but containing at least one reference to an external schema. 3. Documents containing only a directory schema. 4. Documents containing both a directory schema and entries.
A producer of DSML must be able to produce documents of type 1. A producer of DSML may, in addition, be able to produce documents of types 2 thru 4.
A producer that can produce documents of type 1 is said to be a level 1 producer. A producer than can produce documents of all four types is said to be a level 2 producer. Future specifications will provide a mechanism for specifying during a request to a level 2 producer, which type of document is to be returned.
A consumer of DSML must be able to handle all four document types although it need not be able to make use of the directory schema information (either local or externally referenced).
A consumer that can handle DSML documents of all four types is said to be a level 1 consumer. A consumer that can additionally make use of the directory schema information (either local or externally referenced) is said to be a level 2 consumer.                                      structural abstract auxiliary                                

# PHIN Directory Exchange Implementation Guide
Version:1. 0

# Revision Date: 5/16/2007
Page 46 of 55                                             

# PHIN Directory Exchange Implementation