IHE ITI TF Vol2

3.24 Query Personnel White Pages [ITI-24]

This section corresponds to transaction [ITI-24] of the IHE IT Infrastructure Technical Framework. Transaction [ITI-24] is used by the Personnel White Pages Consumer and the Personnel White Pages Directory Actors.

3.24.1 Scope

This transaction is used to retrieve information from the Personnel White Pages directory.

The RFC3377 “Lightweight Directory Access Protocol (v3): Technical Specification” specifies a mechanism for making queries of a database corresponding to an LDAP schema. The LDAP client can compose requests in the LDAP query language, and the LDAP server will respond with the results for a single request.

3.24.2 Use Case Roles

Actor: Personnel White Pages Consumer

Role: Requests information about a human workforce member(s)

Actor: Personnel White Pages Directory

Role: Provides information about one or more human workforce member

3.24.3 Referenced Standard

IETF:

RFC2181 - Clarifications to the DNS Specification

RFC1766 - Tags for the Identification of Languages

RFC2251 - Lightweight Directory Access Protocol (v3)

RFC2252 - Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions

RFC2253 - Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names

RFC2256 - A Summary of the X.500(96) User Schema for use with LDAPv3

RFC2798 - Definition of the inetOrgPerson LDAP Object Class

RFC2829 - Authentication Methods for LDAP

RFC2830 - LDAPv3: Extension for Transport Layer Security

RFC3377 - Lightweight Directory Access Protocol (v3): Technical Specification

ISO:

ISO/TS 17090 directory standard for healthcare identity management

CRU:

Projet de schémas d’annuaires et de schémas de registres de resources numériques interopérables pour les administrations Document technique – v1, novembre 2002

ITU-T:

E.123: Notation for national and international telephone numbers

HL7:

HL7 Version 2.5, Chapter 2 – Control

3.24.4 Messages

Figure 3.24.4-1: Interaction Diagram

3.24.5 LDAP Query/Response

The Personnel White Pages Consumer may make a wide variety of queries and cascaded queries using LDAP. The Personnel White Pages Consumer and Personnel White Pages Directory shall support the data model described here.

A commonly supported configuration type has multiple LDAP servers providing access to a common replicated LDAP database. This permits LDAP servers to be located where appropriate for best performance and fault tolerance. The replication rules chosen for the LDAP servers affect the visible data consistency. LDAP permits inconsistent views of the database during updates and replications. This inconsistency may result in a consumer receiving the person’s previous demographics or contact information. This should not be a problem for our use-cases as none of them are life critical.

3.24.5.1 Trigger Events

Personnel White Pages Consumer requires some Personnel White Pages information on one or more human workforce members.

3.24.5.2 Message Semantics

The transaction uses standard LDAP v3 query/response mechanisms.

3.24.5.2.1 User Authentication

Some of the attributes to be retrieved using this transaction may be considered sensitive to the healthcare personnel. It is the responsibility of the Personnel White Pages Directory to enforce these protections. To protect records and/or attributes, the Personnel White Pages Consumer may be called upon to provide user credentials.

Anonymous authentication shall be implemented on Personnel White Pages Directory and is optional for Personnel White Pages Consumer. Anonymous authentication shall be implemented as described in LDAP v3 Section 4.2 Bind Operation.

Simple Authentication shall be implemented on the Personnel White Pages Directory and is optional for the Personnel White Pages Consumer. Simple authentication shall be implemented as described in LDAP v3 Section 4.2 Bind Operation. This authentication type is not recommended for use over networks that are not otherwise secured as the username and password are transferred in the clear. The use of SSL-Simple Authentication is a better choice.

SSL-Simple Authentication shall be implemented on the Personnel White Pages Directory and is optional for the Personnel White Pages Consumer. SSL-Simple Authentication is not defined in any normative text, but is consistently implemented and often referred to as “ldaps”. The PWP Consumer shall connect to port 636 using SSL against the PWP Directory Certificate. The LDAP v3 conversation then continues with Simple Authentication as defined in LDAP v3 Section 4.2 Bind Operation.

PWP specifies read operations on personnel demographics. The use of bi-directional TLS authentication, such as that defined in ATNA Profile, is not necessary as this profile does not provide access to Protected Health Information (PHI). The use of SSL to cover the authentication and query process is sufficient in this Profile.

3.24.5.2.2 Base DN Discovery

The Personnel White Pages represents a branch within the “LDAP” directory. Branches in LDAP are defined by a “Base DN”. The list of Base DNs that are provided by a LDAP directory can be found by doing a LDAP Query with a NULL (i.e., “”) Base DN, and ObjectClass=”DN”. The Personnel White Pages Directory shall contain a person object with the cn=”IHE-ITI-PWP”. The Personnel White Pages Consumer may thus search through the list of Base DNs that the LDAP Directory contains for this cn object. The Personnel White Pages Directory identified in this way shall contain person/inetOrgPerson objects that conform to the Query Personnel White Pages Directory Transaction.

Note: The first LDAP server that yields a result on the search for IHE-ITI-PWP can be used. There is no need to search further.

3.24.5.2.3 Query Encoding

Note that the LDAP transactions utilize UTF-8 encoding unless otherwise noted. The schema shown here is the commonly used schema found in X.500 Schema for LDAP and inetOrgPerson. Extensions beyond this schema are not recommended. The base schema must be preserved to ensure interoperability. Schema extensions shall not introduce attributes that duplicate the meaning of any attribute specified in this Profile.

These attributes are multi-valued unless explicitly defined as single-valued. At this time there is no universally implemented method to distinguish the purpose for any of the instances in a multi-valued attribute. The IHE recommends that the first entry contain the preferred value, and that applications use the first entry whenever a single value must be selected.

The following table shows the attributes found in Person (OrganizationalPerson and ResidentialPerson) as defined in RFC2256 and inetOrgPerson as defined in RFC2798. The first three columns contain the definitions from the standards for reference. Within the table the fourth column is the IHE recommendation for use with further discussion found in the fifth column.

KEY for IHE REQ Column:

R – The Personnel White Pages Directory shall contain valid values for these attributes. These values are critical to Healthcare workflow.

R2 – The Personnel White Pages Directory shall contain valid values for these attributes if the value is available. These attributes are sufficiently useful that the provider should utilize it in the defined way. Personnel White Pages Consumers should expect that the information in these attributes are valid, but shall be robust to empty values.

O – The Personnel White Paged Directory may contain values for these optional attributes. The IHE has identified sufficiently useful purpose or defined an interoperable way to use the value. The IHE may profile these values in future profiles.

D – Although these attributes are defined in inetOrgPerson/Person, their use is discouraged. This is typically due to the attribute being obsolete, poorly implemented, or not available for query.

Table 3.24.5-1: Attributes found in Person (OrganizationalPerson and ResidentialPerson)

Attribute Name	Source	Definition Standard-defined Optionality Description	IHE REQ	IHE Comment
aliasedObjectName	RFC2256	Alias Object Name Optional The aliasedObjectName attribute is used by the directory service if the entry containing this attribute is an alias.	O
audio	RFC2798	Audio Optional Not well defined	D	The audio format defined is obsolete.
businessCategory	RFC2798	Business Category Optional describes the kind of business performed by an organization	D	Not well defined.
carLicense	RFC2798	Vehicle license or registration plate Optional Used to record the values of the license or registration plate associated with an individual (e.g., 6ABC246)	O
cn	RFC2256	Common Name Required This is the X.500 commonName attribute, which contains a name of an object. If the user is a person, it is typically the person's full name. (e.g., Barbara Jensen)	R	See Section 3.24.5.2.3.1 Use of language tag and HL7 Name Data Type.
departmentNumber	RFC2798	Department Number Optional Identifies a department within an organization. This can be numeric or alphanumeric (e.g., Radiology)	O
description	RFC2798	Description Optional This attribute contains a human-readable description of the object.	D
destinationIndicator	RFC2256	Destination Indicator Optional This attribute is used for the telegram service	D	Originally defined as part of telegram addressing.
displayName	RFC2798	Display Name Optional Singular When displaying a person’s name, especially within a one-line summary list, it is useful to be able to identify a name to be used. Since other attribute types such as 'cn' are multivalued, an additional attribute type is needed. Display name is defined for this purpose. (e.g., Babs Jensen)	R
employeeNumber	RFC2798	Employee Number Optional Singular Numeric or alphanumeric identifier assigned to a person, typically based on order of hire or association with an organization. (e.g., 42)	O
employeeType	RFC2798	Employee Type Optional Used to identify the employer to employee relationship. Typical values used will be "Contractor", "Employee", "Intern", "Temp", "External", and "Unknown" but any value may be used. (e.g., External)	O
facsimileTelephoneNumber	RFC2256	FAX Number Optional A value of this attribute is a telephone number for a facsimile terminal (and, optionally, its parameters). (e.g., +1 408 555 1992)	R2	See Section 3.24.5.2.3.3 Phone Numbers.
givenName	RFC2798	Name Optional The givenName attribute is used to hold the part of a person's name which is not their surname nor middle name. (e.g., Barbara)	R2
homePhone	RFC2798	Home Phone Optional (e.g., +1 408 555 1862)	O
homePostalAddress	RFC2798	Home Postal Address Optional This attribute contains a home address used by a Postal Service to perform services for the object.	O
initials	RFC2798	Initials Optional The initials attribute contains the initials of some or all of an individual’s names, but not the surname(s). (e.g., BJJ)	R2
internationaliSDNNumber	RFC2798	International ISDN Number Optional	D
jpegPhoto	RFC2798	JPEG Photograph Optional Used to store one or more images of a person using the JPEG File Interchange Format	O
l	RFC2256	Locality Name Optional This is the X.500 localityName attribute, which contains the name of a locality, such as a city, county or other geographic region.	O
labeledURI	RFC2798	URI Optional (e.g., http://www.ihe.net IHE Home)	O
mail	RFC2798	E-Mail Address Optional User’s e-mail address in RFC822 compliant form (e.g., bjensen@siroe.com)	R2
manager	RFC2798	Manager Optional Distinguished Name of the Manager	O	In Healthcare the manager of an individual is not clear. The manager attribute does not include enough information to determine the type of manager indicated.
mobile	RFC2798	Mobile/cellular phone number Optional A value of this attribute is a telephone number complying with ITU Recommendation E.123. (e.g., +1 408 555 1941)	R2	This attribute should contain only business use mobile phone numbers. See Section 3.24.5.2.3.3 Phone Numbers.
o	RFC2256	Organization Optional Highest-level organization name, e.g., a company name, to which ou attribute entries belong. (e.g., Saint-ihe-hospital.local)	R2
objectClass	RFC2256	Object Class Required The values of the objectClass attribute describe the kind of object which an entry represents. The objectClass attribute is present in every entry, with at least two values. One of the values is either "top" or "alias". (e.g., top, person, organizationalPerson, inetOrgPerson)	R
ou	RFC2256	Organizational Unit Name Optional This is the X.500 organizationalUnitName attribute, which contains the name of an organizational unit. (e.g., Radiologists)	R2
pager	RFC2798	Pager phone number Optional A value of this attribute is a telephone number complying with ITU Recommendation E.123.	R2	This attribute should contain only business use mobile phone numbers. See Section 3.24.5.2.3.3 Phone Numbers.
photo	RFC2798	Photo Optional Photo attribute values are encoded in G3 fax format with an ASN.1 wrapper.	D	The format is too cumbersome. See jpegPhoto.
physicalDeliveryOfficeName	RFC2256	Post Office Name Optional This attribute contains the name that a Postal Service uses to identify a post office.	R2
postalAddress	RFC2256	Postal Address Optional This attribute contains an address used by a Postal Service to perform services for the object.	R2
postalCode	RFC2256	Postal Code Optional This attribute contains a code used by a Postal Service to identify a postal service zone, such as a US ZIP code	R2
postOfficeBox	RFC2256	Post Office Box Optional This attribute contains the number that a Postal Service uses when a customer arranges to receive mail at a box on premises of the Postal Service.	R2
preferredDeliveryMethod	RFC2798	Delivery Method Optional Singular Coded value (delivery-value) (e.g., any, physical, telephone)	O
preferredLanguage	RFC2798	Preferred Language Optional Singular Preferred written or spoken language for a person. Values for this attribute type MUST conform to the definition of the Accept-Language header field defined in [RFC2068] with one exception: the sequence "Accept-Language" ":" should be omitted. The following example indicates that this person prefers French, prefers British English 80%, and general English 70%. (e.g., fr, en-gb;q=0.8, en;q=0.7)	R2
registeredAddress	RFC2256	Registered Address Optional A postal address suitable for reception of expedited documents, where it is necessary to have the recipient accept delivery.	O
roomNumber	RFC2798	Room Number Optional	O
secretary	RFC2798	Secretary Optional Distinguished name of the secretary	O
seeAlso	RFC2798	See Also references Optional Distinguished name of other interesting Objects	D
sn	RFC2256	Surname Required This is the X.500 surname attribute, which contains the family name of a person (e.g., Jensen)	R
st	RFC2256	State or Province Optional This is the X.500 stateOrProvinceName attribute, which contains the full name of a state or province	R2
street	RFC2256	Street Address Optional This is the X.500 streetAddress attribute, which contains the physical address of the object to which the entry corresponds, such as an address for package delivery.	R2
telephoneNumber	RFC2256	Telephone number Optional A value of this attribute is a telephone number complying with ITU Recommendation E.123.	R2	See Section 3.24.5.2.3.3 Phone Numbers.
teletexTerminalIdentifier	RFC2798	Teletex Terminal Identifier Optional	D
telexNumber	RFC2798	Telex Number Optional	D
title	RFC2256	Title Optional This attribute contains the title, such as "Vice President", of a person in their organizational context. The "personalTitle" attribute would be used for a person's title independent of their job function. (e.g., manager, product development)	R2
uid	RFC2798	User ID Optional The user ID use for system login. (e.g., bjensen)	O	See Section 3.24.5.2.3.2 Use of uid.
userCertificate	RFC2798	User Identity Certificate Optional This attribute is to be stored and requested in the binary form, as 'userCertificate;binary'.	D	The PKCS12 format includes the private key and shall not be publicly available.
userPassword	RFC2256	User password Optional Passwords are stored using an Octet String syntax and are not encrypted. Transfer of cleartext passwords are strongly discouraged where the underlying transport service cannot guarantee confidentiality and may result in disclosure of the password to unauthorized parties.	D	Generally Not Accessible.
userPKCS12	RFC2798	User PKCS #12 Optional PKCS #12 [PKCS12] provides a format for exchange of personal identity information. When such information is stored in a directory service, the userPKCS12 attribute should be used. This attribute is to be stored and requested in binary form, as 'userPKCS12;binary'. The attribute values are PFX PDUs stored as binary data.	D	The PKCS12 format includes the private key and shall not be publicly available.
userSMIMECertificate	RFC2798	User S/MIME Certificate Optional A PKCS#7 [RFC2315] SignedData, where the content that is signed is ignored by consumers of userSMIMECertificate values. It is recommended that values have a `contentType' of data with an absent `content' field. Values of this attribute contain a person's entire certificate chain and an smimeCapabilities field [RFC2633] that at a minimum describes their SMIME algorithm capabilities. Values for this attribute are to be stored and requested in binary form, as 'userSMIMECertificate;binary'. If available, this attribute is preferred over the userCertificate attribute for S/MIME applications.	O
x121Address	RFC2256	Address for X.121 Optional	D
x500uniqueIdentifier	RFC2798	Unique identifier Optional The x500UniqueIdentifier attribute is used to distinguish between objects when a distinguished name has been reused. This is a different attribute type from both the "uid" and "uniqueIdentifier" types.	O

3.24.5.2.3.1 Use of language tag and HL7 Name Data Type (XCN)

Many people have different variations of their name to be used depending on the context and language. This is easily supported in LDAP through the use of the language tag as documented in RFC1766. This language tag can be applied to any attribute but is most useful on names.

HL7 has a well-defined format for encoding names (HL7 XCN). LDAP ‘name’ attributes marked with a language tag of “lang-x-ihe” shall be encoded using the HL7 XCN Data Type. UTF-8 shall be used for any characters outside ASCII.

Example use of the language tag:

objectclass: Top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
dn: cn=Wang XiaoDong, ou=Radiologists, o=Saint-ihe-hospital.local
cn: Wang XiaoDong
cn: XiaoDong, Wang, Florida Department of Health:123456789
cn;lang-cn: 王小東
cn;lang-x-ihe: ^Wang^XiaoDong^^^^^^^^^^^^A~^王^小東^^^^^^^^^^^^I
sn: Wang
givenname: XiaoDong
givenname;lang-cn: 小東
sn;lang-cn: 王
ou: People
uid: XiaoDong
title: Sample HL7 person
mail:Wang.XiaoDong@foo.bar.com
telephonenumber: 555-555-5678

3.24.5.2.3.2 Use of uid

The uid attribute is a multi-valued attribute that is intended to be used for User ID. It is likely that one of the values for uid will be the enterprise User ID. Enterprises that implement the PWP Profile shall implement the following values for the uid attribute:

If an enterprise has implemented both IHE ITI EUA and PWP Profiles, one of the uid attributes shall contain the IHE ITI EUA user identity in <user>@<realm> format.

If an enterprise has implemented a UPIN, one of the uid attributes shall contain the UPIN value in the format <UPIN>@UPIN. Where a UPIN is the Universal Physician Identification Number as assigned by the assigning authority in which the facility operates (e.g., CMS in the USA).

3.24.5.2.3.3 Phone Numbers

Phone numbers shall be represented in the PWP Directory using E.123 notation. E.123 is a notation for national and international telephone numbers. Recommendation E.123 defines a standard way to write telephone numbers, e-mail addresses, and web addresses. It recommends the following formats (when dialing the area code is optional for local calling):

Telephone number:

National notation (042) 123 4567

International notation +31 42 123 4567

E.123 also recommends that a hypen (-), space ( ), or period (.) be used to visually separate groups of numbers. The parentheses are used to indicate digits that are sometimes not dialed. A slash (/) is used to indicate alternate numbers. This information is important if you want to make sure people know how to dial a phone number in a specific country.

The use of National notation and International notation will be a local PWP Directory policy. PWP Consumers shall expect to receive both notations.

3.24.5.2.4 Expected Actions

The Personnel White Pages Directory shall provide the appropriate response to the indicated query given LDAP query rules, local access control policy, and the current information it the directory.

Note: Any attribute is valid to query on, the results of the query may be quick or may take a long time to complete. Each Personnel White Pages Directory will be optimized differently based on architecture and configuration. We expect that the following attributes will be query keys more often than others (cn, displayname, objectclass, sn, uid, givenName, initials, mail, o, ou, and employeeNumber).

Directory shall support Anonymous, Simple, and SSL-Simple Authentications.