Contact Method

Recommendation, 2007 April 15

Editor:

Don R. Simonson, Robert Half International Inc.

Authors:

Don R. Simonson, Robert Half International Inc.

Kimberly Bartkus, HR-XML Consortium

Paul Kiel, HR-XML Consortium

Timothy Farlow, Authoria, Inc

Contributors:

Members of Cross Process Objects workgroup

Abstract

This document introduces base contact information data structures and presents construction patterns of their use so as to promote constancy of contact information representation across HR-XML working groups.

Table of Contents

1 Overview.. 3

1.1 Objective. 3

1.1.1 Domain Issues. 3

1.1.2 Business Reasons. 3

1.1.3 Terminology. 3

1.1.4 Basic Information Data Types. 4

1.1.5 Contact Method Data Type. 4

1.2 Design Requirement 4

1.3 Scope. 4

1.3.1 Items Within the Design Scope. 4

1.3.2 Items Outside of Design Scope. 5

2 Telecommunication Number and Online Address Schema Design. 5

2.1 TelcomNumberType. 5

2.1.1 Schema Diagrams. 5

2.1.2 Schema Elements Explained. 6

2.2 MobileTelcomNumberType. 6

2.2.1 Schema Diagrams. 7

2.2.2 Extension Schema Elements Explained. 7

2.3 OnlineAddress. 7

2.3.1 Schema Diagrams. 8

2.3.2 Schema Elements Explained. 8

2.4 ContactMethodType. 8

2.4.1 Schema Diagrams. 9

2.4.2 Schema Elements Explained. 9

3 Implementation Considerations. 10

4 Appendix A – Document Version History. 11

5 Appendix B – Related Documents. 11

6 Appendix C – Reference Examples. 13

6.1 Sample using ContactMethod. 13

6.2 Formatted telecommunication number: 13

6.3 Non-formatted TelcomNumber. 14

1 Overview

1.1 Objective

The objective of this standard is to define Schema data types representing basic contact information. This standard also builds upon these basic data structures a set of Contact Information Schema patterns, which satisfy more complex HR business data exchange and transaction needs. This standard promotes consistent implementation of these patterns.

1.1.1 Domain Issues

Contact information is used in all HR areas. The primary domain issue is this information set varies in the level of detail that is needed from one HR area to another. Thus the need to provide a minimal set of patterns, of varying degrees of detail that satisfy the majority of current use cases.

1.1.2 Business Reasons

Businesses use three common methods of contacting a person or organization, each with different structures.

Postal delivery of a message

2. Telecommunications delivery of a message, both telephone and fax

Online delivery of a message, most commonly internet e-mail

In business, these base level structures are grouped and presented in various contexts. This document addresses a representative set of these patterns.

1.1.3 Terminology

Device type

Describes the type of contact device, such as facsimile, voice, and pager.

Usage

Describes the purpose or use of the contact, such as business or personal.

International prefix (international access number)

When dialing telephone numbers, this is a digit or combination of digits used to indicate that the number following is an International Public Telecommunication Number. These numbers vary by country region. The international prefix symbol (a ‘+’ symbol) is used in formatted numbers as a placeholder for the international prefix. The International prefix is not represented in the TelecomNumber structure.

1.1.4 Basic Information Data Types

The base component data types are TelcomNumberType, MobileTelcomNumberType, InternetEmailAddressType, and InternetWebAddressType, plus existing HR-XML data types of PostalAddress, and PersonName.

Of these base data types, TelcomNumberType is used by multiple device types. Thus the TelcomNumber structure is represented in a named descriptive element, such as Telephone, Mobile, Fax, Pager, etc. to provide clarity in use.

1.1.5 Contact Method Data Type

The base components may be enclosed in a ContactMethodType element, where supplemental contact information is included. This supplemental information conveys how the contact information should be used – e.g. a telephone number may a home phone or a business direct dialed phone or a company main number.

1.2 Design Requirement

· Syntax must be self-documenting.

· Must contain sufficient information to make contact.

· The telecommunication design must conform to ITU E.164 recommendation The International Telecommunications Union (ITU) is an international organization within which governments and the private sector coordinate global telecom networks and services.

· The Telecommunications structure must allow for formatted string representation (non-parsed) and parsed elements, with the subscriber number required.

1.3 Scope

The scope of this document includes the basic contact information data types and implementation usage patterns.

1.3.1 Items Within the Design Scope

All components required for international and national representation of the telephone number.
A construct to represent telecommunication exchanges that clearly shows the contact device type – cell phone, facsimile, pager, etc.
A construct to represent online addresses such as InternetEmailAddress and InternetWebAddress.
Multiple contact information patterns to support basic business needs.

1.3.2 Items Outside of Design Scope

§ Preference indicators – e.g. I prefer that you send e-mail rather than call, or I prefer that you call my cell phone not my desk phone.

§ Instant Messaging. The use of Instant Messaging is growing, but we believe that it is too early at this stage to include a recommendation for this address type. It is to be revisited by the group at a later date.

2 Telecommunication Number and Online Address Schema Design

2.1 TelcomNumberType

The TelcomNumberType is used to store a telephone number. Telephone numbers can be used to address any device on the Public Switched Telephone Network. Such devices include voice telephones, facsimile machines, and pagers. The number may be either a formatted string or a -set of structured elements. Telephone, Fax, Pager, and TTYTDD elements in this standard are all of type TelcomNumberType.

Example:

</Telephone>

</Telephone>

2.1.1 Schema Diagrams

2.1.2 Schema Elements Explained

Component Name	ContentModel Data type Occurrence: Sequence \| Choice \| All (minOccurs/maxOccurs) Attributes	Definition
/ [TelcomNumberType]	- [TelcomNumberType] - (1/1)	Base data type for [TelcomNumberType] structure.
/ [TelcomNumberType]/ FormattedNumber	- xsd:string - C (1/1)	Formatted string. Contains a telecommunication number string representation. This de-normalized form cannot easily be parsed. When formatted number is present, the non-formatted number MUST not be present.
/ [TelcomNumberType]/ InternationalCountryCode	- xsd:string - S (0/1)	This is the ITU's country code that identifies a specific country, countries in an integrated numbering plan, or a specific geographic area.
/ [TelcomNumberType]/ NationalNumber	- xsd:string - S (0/1)	National (Trunk) Number. This is the code used to indicate that the following numbers are for another AreaCityCode outside the Originating AreaCityCode, but within the originating country. This can usually be inferred from the TelcomCountryCode. It is included for those cases were derivation is not used.
/ [TelcomNumberType]/ AreaCityCode	- xsd:string - S (0/1)	This defines either a numbering area within a country (or group of countries included in one integrated numbering plan or a specific geographic area) or network/service.
/ [TelcomNumberType]/ SubscriberNumber	- xsd:string - S (1/1)	The number identifying a subscriber in a network or numbering area. The SubscriberNumber MUST contain at least one digit. The SubscriberNumber MAY contain hyphens, period, and spaces in addition to the digits. This number may also be known as the "local number".
/ [TelcomNumberType]/ Extension	- xsd:string - S (0/1)	This may contain a PBX extension, a pager PIN, a fax sub-address, or other extended addressing information.

2.2 MobileTelcomNumberType

MobileTelcomNumberType extends TelcomNumberType by adding an smsEnabled attribute.

2.2.1 Schema Diagrams

2.2.2 Extension Schema Elements Explained

Component Name	ContentModel Data type Occurrence: Sequence \| Choice \| All (minOccurs/maxOccurs) Attributes	Definition
/	- MobileTelcomNumberType - (1/1)	Base data type for [MobileTelcomNumberType] structure, for element Mobile.
/ [MobileTelcomNumberType]/ smsEnabled	- xsd:boolean -	SMS (Short Message Service) is a service for sending messages of up to 160 characters (224 characters if using a 5-bit mode) to mobile phones that use Global System for Mobile (GSM) communication.This boolean elements determines if the contact method is sms enabled or not (True/False).
/ [MobileTelcomNumberType]/ [TelcomNumbeType]	- TelcomNumberType	See TelcomNumber structure. MobileTelcomNumberType extends this type.

2.3 OnlineAddress

The OnlineAddress types are used to represent Internet contact addresses. These types do not break down online address structure but simply stores strings. This simple structure is sufficient for HR contact information needs. For example:

<InternetEmailAddress>webmaster@hr-xml.org</InternetEmailAddress>

2.3.1 Schema Diagrams

2.3.2 Schema Elements Explained

Component Name	ContentModel Data type Occurrence: Sequence \| Choice \| All (minOccurs/maxOccurs) Attributes	Definition
/ InternetEmailAddress	- InternetEmailAddressType - xsd:string -	Internet email address.
/ InternetWebAddress	- InternetWebAddressType - xsd:string -	Universal Resource Locator (URL) for a web site. Usually in the form http://www.hr-xml.org. This should include "http://".

2.4 ContactMethodType

ContactMethodType is a structure allowing for the grouping of contact information data by usage, location, and availability.

The first example is of main business office numbers. The second example is for a direct voice line. The third example is at a warehouse in the evenings. The fourth example is a personal mobile phone available 24 by 7.

	Example 1	Example 2	Example 3	Example 4
Use	business	businessDirect	x:onCall	personal
Location	office	office	x:warehouse	onPerson
WhenAvailable			evenings	24x7
Telephone	(333) 123-1234	(333) 123-4321	(332) 223-4411	(422) 111-111
Mobile	(321) 321-4321
Pager	(333) 123-1235
InternetEmailAddress	a.contact@x.com			a.contact@y.net

2.4.1 Schema Diagrams

2.4.2 Schema Elements Explained

Component Name	ContentModel Data type Occurrence: Sequence \| Choice \| All (minOccurs/maxOccurs) Attributes	Definition
/	- ContactMethodType - (1/1)	Base data type for ContactMethod structure.
/ [ContactMethodType]/ Use	- contactMethodUsePatternExtensionType - S (0/1)	Describes the usage of the contact, such as "business", "businessDirect", or "personal". It does not include the device type.
/ [ContactMethodType]/ Location	- contactMethodLocationPatternExtensionType - S (0/1)	Describes the general physical location of the contact information destination, such as "office", "home', or "onPerson".
/ [ContactMethodType]/ WhenAvailable	- contactMethodWhenAvailableType - S (0/1)	Text string suggesting an appropriate time frame when the use of the addresses in this ContactMethod is relevant. For example: 24x7, weekdays, or weekends.
/ [ContactMethodType]/ Telephone	- TelcomNumberType - S (0/1)	Voice Device TelcomNumber
/ [ContactMethodType]/ Mobile	- MobileTelcomNumberType - S (0/1)	Mobile Device TelcomNumber
/ [ContactMethodType]/ Fax	- TelcomNumberType - S (0/1)	Facsimile Device TelcomNumber
/ [ContactMethodType]/ Pager	- TelcomNumberType - S (0/1)	Pager Device TelcomNumber
/ [ContactMethodType]/ TTYTDD	- TelcomNumberType - S (0/1)	TTY is the acronym for Teletypewriter. TDD is the acronym for Telecommunication Device for the Deaf. Both are devices of TelcomNumber.
/ [ContactMethodType]/ InternetEmailAddress	- InternetEmailAddressType - S (0/1)	Internet email address.
/ [ContactMethodType]/ InternetWebAddress	- InternetWebAddressType - S (0/1)	Universal Resource Locator (URL) for a web site. Usually in the form http://www.hr-xml.org. This should include "http://".
/ [ContactMethodType]/ PostalAddress	- PostalAddressType - S (0/1)	Describes a postal address used for delivery of mail. See PostalAddress specification for details.

3 Implementation Considerations

Contact information can be used in numerous business contexts. This section illustrates implementation samples and suggestions.

Our pattern architecture deliberately avoids the use attribute structures, to ensure maximum flexibility of the implementations of the patterns.

Note that while the ContactMethod pattern includes PersonName and PostalAddress elements, these and the other elements are optional, thus they should not imply that they be populated when the information exists elsewhere in the document.

Generally, when in the business analysis phase, it is determined that multiple phone numbers are required to be identified by use, location and availability, then the use of Contact Method pattern is suggested. In cases where only phone, fax, email is needed, then the flat pattern is suggested. For the in between cases that need only differentiation by use (BusinessPhone./PersonalPhone), or by location (Office/Home/Mobile), or by availability (DaytimePhone/EveningPhone) , it is left up to the team’s best judgment as to use of the Contact Method pattern, or to follow the Basic Contact Element Naming pattern.

4 Appendix A – Document Version History

Date	Description
2001 Feb 28	Initial Draft
2001 August 27	Expanded Document focus of patterns to representing contact information built from the basic constructs of PersonName, PostalAddress, TelcomNumber, InernetEmailAddress, and InternetWebAddress and introduced new supplemental contact elements.
2001 Sept 5	Added Usage,Location,WhenAvailable elements
2001 Nov 18	Added Postal Address to ContactMethodType
2001 Nov 15	Reduced the pattern set to just ContactMethod Changed document name from contact Information Patterns to Contact Method
2001-Dec-20	Recommendation presented to membership for review.
2003-Jan-01	Default and targetNamespace changed. Otherwise unchanged.
2003-Feb-26	Approved recommendation by HR-XML Consortium. The default and targetNamespaces of all HR-XML schemas have been standardized. This recommendation is available as part of the HR-XML 2_3 architecture.
2006-Feb-28	Approved by Consortium
2007-Apr-15	Approved by Consortium

5 Appendix B – Related Documents

Additionally:

ITU E-series – Overall network operation, telephone service, service operation and human factors

[E.164] Recommendation E.164/I.331 (05/97) – The international public telecommunication numbering plan
[E.123] Recommendation E.123 (11/88) – Notation for national and international telephone numbers
[E.164_719] Annex to ITU Operational Bulletin No. 719 – 1.VII.2000
ITU Recommendations in force - http://www.itu.int/publications/
ITU International Country Codes and Dialing Procedures - http://www.itu.int/

Other Related Documents

American Disabilities Act – http://www.usdoj.gov/crt/ada/adahom1.htm
URL Guide at RFC 1738 – http://www.ietf.org/rfc/rfc1738.txt

6 Appendix C – Reference Examples

6.1 Sample using ContactMethod

6.2 Formatted telecommunication number:

</Telephone>

6.3 Non-formatted TelcomNumber

</Telephone>

</Telephone>

<Fax>

</Fax>