Physical Location

Recommendation, 2007 April 15

Editor:

Tim Farlow, Authoria

Kim Bartkus, HR-XML

Contributors:

Tim Farlow, Authoria

Kim Bartkus, HR-XML

Paul Kiel, HR-XML

Chuck Allen, HR-XML

Kathi Dolan, Manpower, Inc.

Suneel Mendiratta, Employease, Inc.

Don Simonson, Robert Half International

Scott Miller, Fidelity Investments

Romuald Restout, Recruitsoft, Inc.

Abstract

A Physical Location is an object that specifies a physical place. This document identifies the various ways a physical location can be described and used in HR-XML specifications.

Table of Contents

1 Overview.. 3

1.1 Objective. 3

1.1.1 Domain Issues. 3

1.1.2 Business Reasons. 3

1.2 Design Requirements. 3

1.3 Scope. 3

1.3.1 Items within the Design Scope. 3

1.3.2 Items Outside of Design Scope. 4

2 Supported Business Processes. 4

2.1 Trading Partner Roles. 4

2.2 Use Case Scenarios. 4

3 Physical Location Schema Design. 6

3.1 Schema Diagrams. 6

3.2 Schema/DTD Elements Explained. 7

4 Implementation Considerations. 9

4.1 Latitude and Longitude Notation. 9

4.2 Data Privacy. 9

4.3 Use of the Area Element 9

5 Appendix A - Document Version History. 10

6 Appendix B – Related Documents. 10

7 Appendix C – References. 11

8 Appendix D – Examples. 11

9 Appendix E – Convert Decimal to Degree/Minute/Second Notation. 17

1 Overview

A Physical Location schema is a reusable component for use by Consortium workgroups needing to specify a physical location.

1.1 Objective

The Physical Location is an object that specifies a physical place. Many HR-XML specifications use some form of location description. For example, a resume work history specifies where previous employers are located, and a resumes speaking event specifies where the event took place.

1.1.1 Domain Issues

References to physical locations occur throughout HR transactions. For example, people do their work at different places, and so resumes, job postings, enrollment information and screening results all contain physical location information.

1.1.2 Business Reasons

Having standard ways of encoding physical locations into HR transactions minimizes the effort that workgroups and standards end users need to exert in order to encode and decode references to these objects.

1.2 Design Requirements

Design requirements include:

· Syntax must be self-documenting

· Schema must be easy to understand and use

Schema must be deployable in existing HR-XML Schemas.

1.3 Scope

This object will support any other HR business process that needs a general way of specifying a physical location. Examples may be found in existing schemas for recruiting and staffing, background checking, and other standards.

1.3.1 Items within the Design Scope

This specification allows the exchange of both point and area locations. For example, a specific address versus an area of 5 countries. The schema supports unstructured points, unstructured areas, and structured points.

Three types of physical location descriptors are within the scope of this standard. These are:

· Locations defined by specifying a latitude/longitude. For example, a building construction work site.

· Locations defined by specifying a postal address.

· Locations defined by a geographical area. For example, an employee residence home postal code used to determine health care provider availability.

Latitude/longitude information can include information about which latitude/longitude system is used (called the “datum”), an altitude, and information describing the accuracy of the measurement.

1.3.2 Items Outside of Design Scope

Excluded from the scope is support for the use of taxing jurisdiction identifiers as a location description. Payroll transactions use taxing jurisdictions should treat this separately from a physical location description.

2 Supported Business Processes

2.1 Trading Partner Roles

Because this is a Cross-Process Object, and not a transaction itself, the roles of trading partners in using this specification will be those of the business processes that pass physical locations. Some of the common patterns for trading partner use of these entities are outlined in the use cases in the next section.

2.2 Use Case Scenarios

There are various business reasons to include physical locations within a schema. These can include but are not limited to facilities, work site locations for taxing calculations, eligible benefits based on physical locations, mapping territories, and, search capabilities based on geographical longitude and latitude locations, etc. to name a few. Following is a more thorough listing of examples where physical location can be applicable.

· Facilities services such as space planning/utilization, mail/package delivery, emergency response, telecom/desk side support, and security. This might be a column, floor, or office number.

· A New Hire transaction to specify where mail is delivered and phone and/or computer setup is needed.

· Taxes as they relate to work at home or mobile employees versus on site employees. Employees can be eligible for tax credit based on location of work site.

· Temporary assignment tracking to specify where a recruiting base or customer base is located. For example, a geo code to identify longitude/latitude coordinates.

· Zip code list. This varies by insurance carrier. Most carriers define it on a customer level and give a list for that customer. If the employee’s postal code isn’t in the list, they are ‘out of area’.

· HR records and contacts may be based on employee's physical location. HR representatives must be able to identify where to direct data questions. The contact info may be different for a client based on the physical location.

· When clients are planning to close or sell/divest particular plants, factories, or other types of locations, there is a need to know the employees that are affected so mass-calculations, mailings or assisting in preparing data files for determining the pension liability for those employees can be accomplished. May also be used during the analysis of mergers and acquisitions.

· Search capabilities. The geo code may be used if candidate looking for job in a particular area. For example, to find a job in 20 mile area radius of San Francisco. Physical Location could also be used to determine how far a commute might be to a particular location.

· For recently moved offices, there is the need to identify where the employees were physically located (logistics and planning) to decide how much space is needed in the new facility.

· Timecards. When a person works between different locations, there is the need to reflect where the person worked for both locations, based on physical location.

· Screening. The location is critical for credit and criminal checks. For example, a truck driver accident could have occurred on one location, and the individual driving the truck actually lives in another location or the main office address for the truck driver’s business is located in another location.

· Assessments. May specify where the assessment took place. For example, if the ‘test’ was performed in a testing facility.

· Benefits. Plan eligibility may be determined by physical location. It also may be a factor in determining a benefit.

· Privacy laws. Many countries have privacy laws, which specify what information can be kept, or what business processes can be run against the data may be based on where a person lives.

3 Physical Location Schema Design

3.1 Schema Diagrams

3.2 Schema/DTD Elements Explained

Elements and Attributes [Global types listed alphabetically in following table.]	ContentModel* Data type Occurrence: Sequence \| Choice \| All (minOccurs/maxOccurs) Attributes	Definition
/ PhysicalLocation	- PhysicalLocationType - (1/1) Id - EntityIdType - S (0/1) Name - xsd:string - S (0/1) EffectiveDate - [complexType] - S (0/1) SpatialLocation - SpatialLocationType - S (0/1) TravelDirections - xsd:string - S (0/) PostalAddress - [see include/import] - S (0/1) Area - LocationAreaType - S (0/) Comments - xsd:string - S (0/1)	Container to describe a physical place. [Example(s): Southwest Territory, 50 miles south of Dallas, Building 5A, actual postal address. ]
/ PhysicalLocation/ Id	- EntityIdType - S (0/1)	A unique identifier used to reference the entity. The Id is associated with the higher level element.
/ PhysicalLocation/ Name	- xsd:string - S (0/1)	A descriptive identifier within the given context.
/ PhysicalLocation/ EffectiveDate	StartDate - LocalDateNkNaType - S (0/1) EndDate - LocalDateNkNaType - S (0/1)	Date or time interval on or during which information or events are effective. [BusinessRule(s): It is recommended that all EffectiveDate elements contain at least a StartDate subelement. This date is inclusive. Dates are represented in accordance with ISO 8601. ] [Example(s): Interval during which a person worked at a position; Dates when benefits were in effective; Date of Certification; Date of License ]
/ PhysicalLocation/ EffectiveDate/ StartDate	- LocalDateNkNaType - S (0/1)	Contains the (inclusive) date, period, or interval the event becomes active or begins. [BusinessRule(s): This date is inclusive. Dates are represented in accordance with ISO 8601. ] [Example(s): Position start date, assignment start date, rate change, effective date ]
/ PhysicalLocation/ EffectiveDate/ EndDate	- LocalDateNkNaType - S (0/1)	Contains the (inclusive) date, period, or interval the event becomes inactive or ends. [BusinessRule(s): This date is inclusive. Dates are represented in accordance with ISO 8601. ]
/ PhysicalLocation/ SpatialLocation	- SpatialLocationType - S (0/1) Latitude - LatitudeType - S (1/1) Longitude - LongitudeType - S (1/1) Altitude - xsd:decimal - C (0/1) AltitudeMeanSeaLevel - xsd:decimal - C (0/1) HorizontalAccuracy - NonNegativeDecimal - S (0/1) VerticalAccuracy - NonNegativeDecimal - S (0/1)	The location relating to a specific point on the earth. This is determined by a coordinate system. [Example(s): One common coordinate system is the Latitude-Longitude-Altitude coordinate system using WGS-84 datum (World Geodetic Reference System of 1984). ]
/ PhysicalLocation/ SpatialLocation/ Latitude	- LatitudeType - S (1/1)	The angular distance of a place north or south of the earth’s equator. [BusinessRule(s): Latitude is expressed in decimal notation, with a range of -90 south to 90 north, where 0 is at the equator. ]
/ PhysicalLocation/ SpatialLocation/ Longitude	- LongitudeType - S (1/1)	The angular distance of a place east or west of the prime meridian at Greenwich, England. [BusinessRule(s): Longitude is expressed in decimal notation, with a range of -180 west to 180 east. ]
/ PhysicalLocation/ SpatialLocation/ Altitude	- xsd:decimal - C (0/1)	The height of an object or point in relation to the earth's surface. [BusinessRule(s): This value is expressed in meters. ]
/ PhysicalLocation/ SpatialLocation/ AltitudeMeanSeaLevel	- xsd:decimal - C (0/1)	The height of an object or point in relation to sea level or above the mean sea level. [BusinessRule(s): This value is expressed in meters. ]
/ PhysicalLocation/ SpatialLocation/ HorizontalAccuracy	- NonNegativeDecimal - S (0/1)	The margin of error for longitude and latitude coordinates. [BusinessRule(s): This value is expressed in meters. ]
/ PhysicalLocation/ SpatialLocation/ VerticalAccuracy	- NonNegativeDecimal - S (0/1)	The margin of error for the altitude coordinate. [BusinessRule(s): This value is expressed in meters. ]
/ PhysicalLocation/ TravelDirections	- xsd:string - S (0/*)	Provides directions to the site. These could include directions by bus, air, car, walking, etc.
/ PhysicalLocation/ Area	- LocationAreaType - S (0/) type - [Union]: LocationAreaTypeType, xStringPatternExtensionType - - Description - xsd:string - S (1/1) Area - LocationAreaType - S (0/)	A geographical base with distinct boundaries as agreed upon by trading partners.
/ [LocationAreaType] / type	- [Union]: LocationAreaTypeType, xStringPatternExtensionType	Further defines the associated element in the context provided. [BusinessRule(s): Additional values are permitted if preceded by an x: ]
/ PhysicalLocation/ Area/ Description	- xsd:string - S (1/1)	Describes the contextual information relating to a specific element.
/ PhysicalLocation/ Comments	- xsd:string - S (0/1)	Describes the contextual information relating to a group of elements.

Global types (alphabetically listed)	ContentModel* Data type Occurrence: Sequence \| Choice \| All (minOccurs/maxOccurs) Attributes	Definition
/ [LatitudeType]	xsd:restriction base: xsd:decimal	Globally scoped data type. See element or attribute declaration for definition.
/ [LocationAreaTypeType]	xsd:restriction base: xsd:string [Enumerations]: municipality, postalcode, countrycode, region	Globally scoped data type. See element or attribute declaration for definition.
/ [LongitudeType]	xsd:restriction base: xsd:decimal	Globally scoped data type. See element or attribute declaration for definition.
/ [NonNegativeDecimal]	xsd:restriction base: xsd:decimal	Globally scoped data type. See element or attribute declaration for definition.

4 Implementation Considerations

4.1 Latitude and Longitude Notation

In general, latitude and longitude coordinates may be expressed in degree or decimal notation. However, this specification REQUIRES that coordinates be expressed in decimal notation. An algorithm to convert from decimal to degree/minute/second notation is available in Appendix E.

Example: A degree longitude value of W87.53 must be converted to a decimal longitude value of -87.91188.

Additionally, coordinates may be expressed in positive or negative values. These values correlate directly with north/south and east/west coordinates. The latitude range is from -90° south to +90° north. The longitude range is from -180° west to +180° east.

4.2 Data Privacy

Human resources data, by its very nature, is personal data. The laws of many jurisdictions as well as codes of fair information practice require organizations to handle personal data in a way that protects individuals from loss of privacy.

The data exchange specifications developed by the HR-XML Consortium are designed to be useful across many jurisdictions and within a variety of business contexts. It is not feasible for the HR-XML Consortium to develop specific privacy guidance for every jurisdiction or business context in which the Consortium's specifications might be implemented. When implementing data exchanges using the HR-XML Consortium's data definitions (or, for that matter, using any other type of data exchange mechanism), organizations are advised to examine the privacy protections that may be required under applicable law and codes of fair information practice.

For information on protecting personal data, general references include: European Union Data Protection Directive (95/46/EC); the Association Computing Machinery Code of Ethics (1992); Canadian Standards Association Model Code for the Protection of Personal Information (1995 – PIPEDA); and U.S.-EU Safe Harbor Principles and FAQs (2000).

4.3 Use of the Area Element

The Area element is intended to be a flexible structure for describing geographic areas. The use cases for describing an area are many, and the repeatable, hierarchical design of the element is the result. This section describes how to use recursion and iteration of area elements.

When one area element is hierarchically below another, then the lower element represents an area that must be entirely within the area represented by the element’s parent. For example, a parent element may represent a country, and a child of this element could represent a state, province, or region within the country. The resulting structure describes the region within the country. Hierarchical structures are useful for giving context to a very specific area. For example, just specifying an area by postal code is not sufficient without placing it within an area representing a country because postal codes need that context for proper interpretation.

When area elements are peers of each other, then the total area described is the union of all the areas. For example, I can describe Southeast Asia with a set of area elements for all the countries within Southeast Asia.

Combinations of hierarchical and repeating areas allow for detailed description of complex areas.

It is relatively straightforward to turn area elements into textual descriptions. But because of the complexity associated with describing real world areas, trading partners will need to come to agreement on the contents of area elements if they wish to make computations based on area data.

5 Appendix A - Document Version History

Date	Description
2003-07-10	Initial draft
2003-07-16	Replaced “Description” with “Name”, “Comments” and “TravelDirections”. Filled in some missing sections.
2003-07-31	Removed Position and promoted Longitude and Latitude. Changed altitude elements to a choice. Updated document, including new definitions.
2003-09-12	Reorganized Area as repeatable hierarchy. Added examples.
2003-09-25	Add implementation guidelines for lat/long pattern. Changed Identifier to Id with entityIdType.
2003-12-29	Updated references of decimal vs. degree notation. Changed examples to use decimal notation. Specification now requires decimal notation.
2004-01-02	Changed Area/Value to Area/Description. Value typically denotes a monetary or material worth.
2004-01-08	Changed top level Area to multiple occurrence. Added job posting example.
2004-02-05	Added implementation notes for the Area element.
2004-02-26	Added Effective Date elements.
2004-08-02	Approved by membership.
2006-Feb-28	Approved by Consortium
2007-Apr-15	Approved by Consortium

6 Appendix B – Related Documents

Reference	Link
Physical Location Schema	http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/PhysicalLocation.xsd
Postal Address	http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/PostalAddress.html

7 Appendix C – References

Korkea-aho, Mari. (2001) Location Information in the Internet, Chapter 11.3-11.5. http://www.hut.fi/~mkorkeaa/licthesis/LicThesis-Mari-Korkea-aho-Final-Version-08102001.pdf

8 Appendix D – Examples

1. Temporary assignment tracking. Where recruiting base or customer base is located – geo code, identify longitude/latitude coordinates.

<Id>

</Id>

<Name>Midwest Distribution Center</Name>

</SpatialLocation>

<TravelDirections>From the south, take I=94 north to exit 356, turn left on Kilbourn, past three red lights and turn left into the ABC Company driveway. Stay right and follow signs to loading dock</TravelDirections>

<Region>Milwaukee</Region>

<Municipality>String</Municipality>

<StreetName>E. Kilbourn Ave</StreetName>

</DeliveryAddress>

<GivenName>Aaron</GivenName>

<MiddleName>Edward</MiddleName>

</PersonName>

<AdditionalText>String</AdditionalText>

<OrganizationName>ABC Company</OrganizationName>

</Recipient>

</PostalAddress>

<Comments>Mr. Sisk must sign all timecards</Comments>

</TemporaryAssignmentTracking>

2. When clients are planning to close or sell/divest particular plants, factories, or other types of locations, there is a need to know the employees that are affected so mass-calculations, mailings or assisting in preparing data files for determining the pension liability for those employees can be accomplished. May also be used during the analysis of mergers and acquisitions.

<Name>Lower Falls Mill</Name>

</EffectiveDate>

</Area>

</PhysicalLocation>

<Name>Newman Mills</Name>

</EffectiveDate>

</Area>

</PhysicalLocation>

<Name>Rockford Mills</Name>

</EffectiveDate>

</Area>

</PhysicalLocation>

</PlantClosingAffectedArea>

3. Search capabilities – GEO Code may be used if candidate is looking for job in a specific area - for example, to find a job in 20-mile area radius of San Francisco. Could also be used for commute information in Candidate schema.

</SpatialLocation>

</WorklLocation>

</CommuterInfo>

4. For recently moved offices, there is the need to identify where the employees were physically located (logistics and planning) to decide how much space is needed in the new facility.

<Name>3rd floor cube 394</Name>

<EndDate>notKnown</EndDate>

</EffectiveDate>

<Comments>Last one on the right</Comments>

</Location>

</WorkerInfo>

5. Describes the service area for an insurance carrier. If the employer’s municipality isn’t included, they are considered ‘out of area’.

</Id>

<Name>Georgia Service Area</Name>

</EffectiveDate>

<Description>Atlanta</Description>

</Area>

<Description>Marietta</Description>

</Area>

<Description>Norcross</Description>

</Area>

</PhysicalLocation>

</ServiceArea>

6. HR records and contacts may be based on employee’s physical location. HR representatives must be able to identify where to direct data questions. The contact information may be different for a client based on the physical location.

<Name>AL Sprocket Processing Plant</Name>

</EffectiveDate>

<TravelDirections>I-65 South, Exit 196</TravelDirections>

<Municipality>McIntosh</Municipality>

<AddressLine>1567 Mobile Street</AddressLine>

</DeliveryAddress>

</PostalAddress>

</PhysicalLocation>

</Office>

7. Time Cards - In this example, the employee submitted a timecard for two locations. The tax rates may be applied differently for each location.

<Id>

</Id>

<Name>Dallas Facility</Name>

<Description>Dallas</Description>

</Area>

<Comments>Weekend shift is located in Dallas.</Comments>

</WorkLocation>

<AdditionalData type="Task">Repair</AdditionalData>

</TimeInterval>

<Id>

</Id>

<Name>Ft Worth Factory</Name>

<Description>Ft. Worth</Description>

</Area>

<Comments>Weekday shift in Ft. Worth. City taxes apply.</Comments>

</WorkLocation>

<AdditionalData type="Task">Production</AdditionalData>

</TimeInterval>

</ReportedTime>

</TimeCard>

8. Screening – this location is critical for credit checks, and criminal checks. For example, a truck driver accident could have occurred on one location, and the individual driving the truck actually lives in another location i.e., county, region, state, etc. or the main office address for the truck driver’s business is located in another location.

<Description>Meridith County</Description>

<Description>Little Rock</Description>

</Area>

</VehicleAccidentLocation>

<Region>Connecticut</Region>

<Municipality>Hartford</Municipality>

<StreetName>Oak Street</StreetName>

</DeliveryAddress>

</PostalAddress>

</DriverHomeAddress>

9. Assessments – could list in the transaction where the assessment took place. For example, if the ‘test’ was performed in a testing facility.

<Name>Educational Services of Cleveland</Name>

<TravelDirections>Take Interstate 75 exit 27. Travel South on Paul Huff Parkway for 2.1 miles. Turn left onto US 11. Center is on the right. </TravelDirections>

<Municipality>Cleveland</Municipality>

<AddressLine>1721 North Lee Highway</AddressLine>

</DeliveryAddress>

</PostalAddress>

<Comments>Hours of operation are 9:00 AM to 5:00 PM, Monday through Friday.</Comments>

</PhysicalLocation>

</TestingFacility>

10. Time Cards - In this example, the employee submitted a timecard for two locations. The tax rates may be applied differently for each location.

<Name>Regional HQ</Name>

<TravelDirections>”I-43 north to Silver Spring exit, north on Pt. Washington two blocks, turn right on Lexington by the Kinkos, go one block. Road dead ends at parking lot</TravelDirections>

<Region>Upper Midwest</Region>

<StreetName> “N. Ironwood Road “</StreetName>

</DeliveryAddress>

<FormattedName type="presentation">”D. Turcq”</FormattedName>

</PersonName>

<OrganizationName>ABC Company</OrganizationName>

</Recipient>

</PostalAddress>

<Description>Wisconsin</Description>

<Description>Milwaukee</Description>

<Description>Glendale</Description>

</Area>

<Comments>String</Comments>

</PhysicalLocation>

11. Job Posting – identifies the location of a job or position, allowing for more specificity of the area.

<Name>Regional HQ</Name>

<TravelDirections>”I-43 north to Silver Spring exit, north on Pt. Washington two blocks, turn right on Lexington by the Kinkos, go one block. Road dead ends at parking lot</TravelDirections>

<Region>Upper Midwest</Region>

<StreetName> “N. Ironwood Road “</StreetName>

</DeliveryAddress>

<FormattedName type="presentation">”D. Turcq”</FormattedName>

</PersonName>

<OrganizationName>ABC Company</OrganizationName>

</Recipient>

</PostalAddress>

<Description>Wisconsin</Description>

<Description>Milwaukee</Description>

<Description>Glendale</Description>

</Area>

</PhysicalLocation>

9 Appendix E – Convert Decimal to Degree/Minute/Second Notation

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>

<xsl:template name="decimalToDegreesMinutesSeconds">

<xsl:param name="latlongdecimal" />

<xsl:param name="negativesign" />

<xsl:param name="positivesign" />

<xsl:variable name="baseval"><xsl:value-of select="round($latlongdecimal * 3600) div 3600" /></xsl:variable>

<xsl:choose>

<xsl:when test="$baseval < 0">

<xsl:variable name="integer"><xsl:value-of select="floor(-$baseval)"/></xsl:variable>

<xsl:variable name="decimal"><xsl:value-of select="-$baseval - floor(-$baseval)"/></xsl:variable>

<xsl:variable name="minutes"><xsl:value-of select="floor($decimal * 60)"/></xsl:variable>

<xsl:variable name="decimalSeconds"><xsl:value-of select="($decimal * 60) - $minutes"/></xsl:variable>

<xsl:variable name="seconds"><xsl:value-of select="round($decimalSeconds * 60)"/></xsl:variable>

<xsl:value-of select="$integer"/>° <xsl:value-of select="$minutes"/>' <xsl:value-of select="$seconds"/>"

<xsl:value-of select="$negativesign" />

</xsl:when>

<xsl:otherwise>

<xsl:variable name="integer"><xsl:value-of select="floor($baseval)"/></xsl:variable>

<xsl:variable name="decimal"><xsl:value-of select="$baseval - floor($baseval)"/></xsl:variable>

<xsl:variable name="minutes"><xsl:value-of select="floor($decimal * 60)"/></xsl:variable>

<xsl:variable name="decimalSeconds"><xsl:value-of select="($decimal * 60) - $minutes"/></xsl:variable>

<xsl:variable name="seconds"><xsl:value-of select="round($decimalSeconds * 60)"/></xsl:variable>

<xsl:value-of select="$integer"/>° <xsl:value-of select="$minutes"/>' <xsl:value-of select="$seconds"/>"

<xsl:value-of select="$positivesign" />

</xsl:otherwise>

</xsl:choose>

</xsl:template>

<xsl:template match="/">

<xsl:call-template name="decimalToDegreesMinutesSeconds">

<xsl:with-param name="latlongdecimal" select="Location/longitude"/>

<xsl:with-param name="negativesign" select="string('E')"/>

<xsl:with-param name="positivesign" select="string('W')"/>

</xsl:call-template>

</xsl:template>

</xsl:stylesheet>