An application acknowledgement is a meaningful business response to a transaction or set of transactions. Acknowledgements are commonly used, allowing trading partners to respond with details and business errors in the processing of transactions. This specification defines a general purpose “response” or acknowledgement for trading partners to:

Confirm the receipt of a previous message (a simple confirm).
Define a methodology to handle business-level error, success, and other disposition information.

1.1 Objective

The objective of this project is threefold:

Create a business-level acknowledgement useful to a wide range of HR business process scenarios;
Create a schema which is useful to both an automated system or a manual process;
Identify specific transactional successes and failures.

1.1.1 Benefits Enrollment as a use case

This document refers to the Benefits Enrollment specification as an example of its usage. However, it is intended to be usable in many contexts across the Consortium and was designed to be used as a general purpose application acknowledgement.

1.1.2 Domain Issues

For complex transactions such as benefit enrollments, a receiver needs to have the ability to respond to an original sender beyond only the success or failure of transmission. A receiver needs to respond with a meaningful summary of cardinality, disposition of data (with the ability to refer to the original), and a list of appropriate actions.

Today, these responses are largely handled through manual processes (i.e. email, paper reports, and fax) or in proprietary formats.

1.1.3 Business Reasons – processing results

There is no standard way of communicating processing results of a particular transaction. This schema is necessary in order to allow for a two-way model of data transactions. For example, a sender of an enrollment transaction knows that a transaction has been received; however, without an application acknowledgement, the original sender does not know the status of the receiver’s processes, and therefore does not know the receiver’s ability to print an ID card or pay a claim.

This diagnostic information also enables vendor management activities if a plan sponsor has contracted with a third party to manage benefits enrollment activities.

1.1.4 Business Reasons - simple confirmation

While the Application Acknowledgment schema is capable of delivering business level errors, these elements are not required. This is because there is a use case for the schema to convey a “simple confirmation”. In this instance, the receiver of a previous transaction wishes to respond to the sender with a message that communicates only that they received the message and will process accordingly. No processing results or errors are conveyed.

While there are cases described in which this kind of simple confirmation is handled inside of a messaging envelope, there is also the case where implementations do not keep enveloping information. Here, the simple confirm can serve the purpose of retaining confirmation outside of an envelope.

1.2 Terminology

1.2.1 Payload

The terms XML Document, XML Instance, Message Text, and Payload are used interchangeably within the HR-XML Consortium. They all refer to an XML file conformant to an HR-XML schema. The term "Payload" connotes the usage of this XML data inside an enveloping or messaging framework. Because HR-XML data is intended as transport neutral, it stresses the development of XML data that can be used within any messaging framework. The term Payload is used to describe the HR-XML based XML within some kind of enveloping or messaging framework.

When used as a response to an enrollment transaction, Payload refers to the data submitted in the enrollment transaction for which an instance of the application acknowledgement is generated.

1.2.2 Schema

Elements that contain the word schema refer to the XML schema document from which the received payload was created.

1.2.3 PayloadXPATH

An XPATH to an element in the received payload.

1.2.4 SchemaXPATH

An XPATH to an element in the XML schema document.

1.2.5 Disposition

A description of the end-state of a transaction from the point of view of the receiver. In this design, the disposition element conveys entity identification and whether or not an exception (see below) occurred while processing a specific entity.

1.2.6 Exception

Data or processing conditions that need to be reported back to the sender based on the receiver’s processing of the transaction. Conditions worth reporting are likely to indicate that the receiver is having difficulty processing a specific transaction, or portion of a transaction, but may also be for informational purposes.

1.3 Scope

The Acknowledgement schema gives submitters of a business transaction a way to discover and interpret the outcome of their submission in the business context of the receiving application’s processing of that submission. A distinction is made between two categories of acknowledgement: functional and application. This schema does not deal with functional acknowledgement issues such as the syntactic well-formed payload, or the transport and delivery of the payload. This schema deals with the acknowledgement of the specific business entities and outcomes involved in a transaction. For example, the schema could be used to acknowledge that a particular enrollment subscription has been successfully processed, or that a data inconsistency prevented processing for a particular subscription.

1.3.1 Major Components

Summary of payload response
Payload disposition
Exception list

1.3.2 Items within the Design Scope

This schema will be a response to either a synchronous or asynchronous transaction. The concept of an application acknowledgement may apply to many business processes, including benefits enrollment related business activities (i.e. ongoing enrollment updates, open enrollments, auditing between trading partners, etc).

1.3.3 Items Outside of Design Scope

The Application Acknowledgement enables the exchange of business level errors between trading partners. It is not intended to convey transport errors, such as HTTP errors, SOAP fault, etc. Those types of errors have established patterns and should be used as needed.

2 Supported Business Processes

2.1 Trading Partner Roles

The Application Acknowledgement schema supports the exchange of business responses, e.g. successful and unsuccessful processing details, for a transaction or a set of transactions. Trading partners may be employers, HR software vendors, third party administrators or insurance carriers.

The role of the trading partner within the context of the Application Acknowledgement schema is to communicate and/or receive processing details of a given transaction or set of transactions.

· The communication protocol for connectivity and for exchanging formatted XML data across the internet must be decided by the trading partners.

· UniquePayloadTrackingId provides a means for the sender and receiver to reference the payload in a transaction (e.g. an Enrollment payload). The sender of the original transaction specifies a UniquePayloadTrackingId so that the receiver can reference the same value within the acknowledgement transaction. This element was required by the original Enrollment use case, but was made optional to accommodate other use cases.

· ReferenceId is an element that the receiver may optionally specify in the acknowledgment. A ReferenceId might be an order number, confirmation code, or other key necessary for any follow-up transactions (e.g., checking the status of an order). This element was not required by the original Enrollment use case, but was added to accommodate other use cases.

· The processing details, i.e. ExceptionIdentifier and ExceptionMessage, are proprietary to the sender of the acknowledgement. The receiver of the acknowledgement must be able to translate these values into meaningful business results to gain resolution to the specific issue.

2.2 Business Process Name

2.2.1 Summary

The Application Acknowledgement schema supports the exchange of processing details between trading partners. Typical uses of the schema are described below and are depicted in the following diagram:

· The exchange of processing details between an insurance carrier back to an employer or a third party administrator.

2.2.2 Use Case Scenarios

Many elements drive the success or failure of an HR-XML data exchange. The Application Acknowledgement schema supports the response to any HR-XML exchange. This response will include success or failure of the file and success or failure of each individual entity. The response includes a payload summary with entity counts that a receiver may reconcile against the original file sent. The response will also include a list of any entities that passed or failed processing. Entity failures will be categorized by severity level (Fatal, Warning, or Informational, error codes that provide an explanation of the issue that are sender specific, and the party responsible for follow-up (Sender or Receiver).

2.2.3 Diagrams

An entity missing required data is a specific example for communicating an acknowledgement response between entities. This section describes the specific processes. Section 7 (Appendix C – Reference Examples) provides actual XML examples.

Upon a marriage event, a Person elects to add his/her spouse to medical coverage. The

Person sends enrollment to the Employer’s Human Resources department, Administrator, or Carrier. Any of these three recipients can then inform the other two, depending on the division of administrative responsibilities. If the date of birth for the spouse is missing from the request to add the spouse to the medical coverage, a response must make it back to the original sender (person) from any of the three entities.

3 Schema Design

3.1 Application Acknowledgement Schema

3.1.1 Diagram

A high level diagram can be found below.

3.1.2 Elements Explained

Elements and Attributes [Global types listed alphabetically in following table.]	ContentModel* Data type Occurrence: Sequence \| Choice \| All (minOccurs/maxOccurs) Attributes	Definition
/ ApplicationAcknowledgement	- AcknowledgeType - (1/1) PayloadResponseSummary - PayloadResponseSummaryType - S (1/1) PayloadDisposition - PayloadDispositionType - S (0/1) UserArea - [see include/import] - S (0/1)	Contains information about the acknowledgement of a transmission.
/ ApplicationAcknowledgement/ PayloadResponseSummary	- PayloadResponseSummaryType - S (1/1)	Contains summary and identifying information about the payload or message text response.
/ ApplicationAcknowledgement/ PayloadDisposition	- PayloadDispositionType - S (0/1)	Contains information regarding the disposition of the entities within the payload or message text.

3.2 Payload Response Summary Type

3.2.1 Diagram

3.2.2 Elements Explained

/ [PayloadResponseSummaryType]	ReferenceId - EntityIdType - S (0/) TransportMessageId - xsd:string - S (0/1) UniquePayloadTrackingId - EntityIdType - S (0/) TransactionReceiptTimestamp - DateTimeType - S (0/1) ProcessingTimestamp - DateTimeType - S (0/*) AcknowledgementCreationTimestamp - DateTimeType - S (0/1) ReceivedPayloadSummary - [complexType] - S (0/1)
/ [PayloadResponseSummaryType]/ ReferenceId	- EntityIdType - S (0/*)	Contains an identifier, such as an “order number” or “confirmation code,” that might be used in follow-up transactions or communications.
/ [PayloadResponseSummaryType]/ TransportMessageId	MessageIdType - xsd:string - S (0/1) MessageId - EntityIdType - S (1/1)	Contains identifying information about the original transaction for which the acknowledgement is being returned. [BusinessRule(s): Matches the transport layer id. ]
/ [PayloadResponseSummaryType]/ TransportMessageId/ MessageIdType	- xsd:string - S (0/1)	Identifies the type of message sent in the transaction for which acknowledgement is being returned. [Example(s): MQ Series Transaction Id, ebXML Message Id, Defined by Trading Partners. ]
/ [PayloadResponseSummaryType]/ TransportMessageId/ MessageId	- EntityIdType - S (1/1)	The message identifier of the transaction for which application acknowledgement is being returned.
/ [PayloadResponseSummaryType]/ UniquePayloadTrackingId	- EntityIdType - S (0/1)	An identifier to tie the original transaction to the acknowledgement of that transaction. [BusinessRule(s): The sender in a trading partnership will provide this value in the initial message; the value will be repeated in this element to produce an acknowledgement of a specific payload. ]
/ [PayloadResponseSummaryType]/ TransactionReceiptTimestamp	- DateTimeType - S (0/1)	The date and time at which the message containing the payload was received.
/ [PayloadResponseSummaryType]/ ProcessingTimestamp	xsd:extension base: DateTimeType description - xsd:string -	The date and time at which a particular processing action was performed on the payload. [BusinessRule(s): The description attribute will contain text meaningful to both parties in the exchange. ] [Example(s): An acknowledgement sender could provide date/times such as "Medical Coverages Processed" or "Claims Ready". Value applies to non-exception cases. ]
/ [PayloadResponseSummaryType]/ ProcessingTimestamp/ description	- xsd:string -	This optional attribute is available to provide additional information.
/ [PayloadResponseSummaryType]/ AcknowledgementCreationTimestamp	- DateTimeType - S (0/1)	The date and time at which this acknowledgement was created. [BusinessRule(s): It is recommended to use the time at which the acknowledgement payload was completed. ]
/ [PayloadResponseSummaryType]/ ReceivedPayloadSummary	ReceivedPayloadSchemaURI - xsd:anyURI - S (0/1) EntityInfo - [complexType] - S (0/*)	Contains summary information regarding the received payload or message text.
/ [PayloadResponseSummaryType]/ ReceivedPayloadSummary/ ReceivedPayloadSchemaURI	- xsd:anyURI - S (0/1)	A URI indicating where the schema used to create the payload or message text being acknowledged can be found.
/ [PayloadResponseSummaryType]/ ReceivedPayloadSummary/ EntityInfo	EntityInstanceAxisXPath - xsd:string - S (0/1) Count - xsd:nonNegativeInteger - S (1/1) EntityShortName - xsd:string - S (0/1)	Contains information about the entity.
/ [PayloadResponseSummaryType]/ ReceivedPayloadSummary/ EntityInfo/ EntityInstanceAxisXPath	- xsd:string - S (0/1)	An XPath to the entity level in the xml instance. The instance is located by ReceivedPayloadSchemaURI. [BusinessRule(s): The path does not indicate which occurrence of the entity, only the axis. For example, it may be Enrollment/Organization/Subscriber - not indicating which Subscriber occurrence. ]
/ [PayloadResponseSummaryType]/ ReceivedPayloadSummary/ EntityInfo/ Count	- xsd:nonNegativeInteger - S (1/1)	Determines the total number of a collection of items.
/ [PayloadResponseSummaryType]/ ReceivedPayloadSummary/ EntityInfo/ EntityShortName	- xsd:string - S (0/1)	A non-standard or shorter name for the entity identified by the EntityXPath. [Example(s): Subscriber, Families with medical coverage, Life insurance coverage with total volume over 2 million dollars. ]

3.3 Payload Disposition Type

3.3.1 Diagram

3.3.2 Elements Explained

/ [PayloadDispositionType]	EntityDisposition - [complexType] - S (0/*)
/ [PayloadDispositionType]/ EntityDisposition	EntityIdentifier - EntityIdType - S (0/1) EntityShortName - xsd:string - S (0/1) EntitySchemaXPath - xsd:string - S (0/1) EntityInstanceXPath - xsd:string - S (1/1) EntityNoException - xsd:string - C (1/1) EntityException - EntityExceptionType - C (1/1)	Contains disposition information for a single entity. [BusinessRule(s): This is repeatable for batched entities. For example, representing a Subscriber in Enrollment. ]
/ [PayloadDispositionType]/ EntityDisposition/ EntityIdentifier	- EntityIdType - S (0/1)	The identifier for the entire entity disposition. [Example(s): Subscriber Id ]
/ [PayloadDispositionType]/ EntityDisposition/ EntityShortName	- xsd:string - S (0/1)	A non-standard or shorter name for the entity identified by the EntityXPath. [Example(s): Subscriber, Families with medical coverage, Life insurance coverage with total volume over 2 million dollars. ]
/ [PayloadDispositionType]/ EntityDisposition/ EntitySchemaXPath	- xsd:string - S (0/1)	Defines the "root" level at which the exception applies by reference to the schema. [BusinessRule(s): This is an XPath not for the XML payload instance, but the XML document that is the schema itself. ]
/ [PayloadDispositionType]/ EntityDisposition/ EntityInstanceXPath	- xsd:string - S (1/1)	The XPath to the entity in the payload. [BusinessRule(s): This is the full XPath and not simply pointing to the axis in general. For example in Enrollment, this value would be an XPath to the Subscriber element (including the occurrence of the Subscriber in the instance - such as Enrollment/Organization/Subscriber[position()=2]). ]
/ [PayloadDispositionType]/ EntityDisposition/ EntityNoException	- xsd:string - C (1/1)	Contains information about the entities successfully accepted in the payload transaction.
/ [PayloadDispositionType]/ EntityDisposition/ EntityException	- EntityExceptionType - C (1/1)	Contains information about the entities not accepted in the payload transaction. [BusinessRule(s): This is the main reusable that can be incorporated into SOAP fault scenario. ]

3.4 Entity Exception Type

3.4.1 Diagram

3.4.2 Elements Explained

/ [EntityExceptionType]	EntityXMLFragment - xsd:anyType - S (0/1) Exception - ExceptionType - S (1/*)
/ [EntityExceptionType]/ EntityXMLFragment	- xsd:anyType - S (0/1)	The XML snippet beginning with the root element pointed to by the EntityInstanceXPath.
/ [EntityExceptionType]/ Exception	- ExceptionType - S (1/*)	Business level exceptions regarding the specified entity. [BusinessRule(s): This would not include enveloping or XML related exceptions. ]
/ [EntityExceptionType]/ Exception/ ExceptionIdentifier	- xsd:string - S (0/1)	This is an Id or code used by the organization generating the acknowledgement to identify the specific exception.
/ [EntityExceptionType]/ Exception/ ExceptionSeverity	xsd:restriction base: xsd:string [Enumerations]: Fatal, Warning, Information	Specifies the severity of the exception. [BusinessRule(s): Fatal specifies that no records were processed. Warning specifies that all records may not have processed. Information specifies that all records were processed but a problem may exist which needs notification. ] [Example(s): Fatal, Warning, Information ]
/ [EntityExceptionType]/ Exception/ ExceptionMessage	- xsd:string - S (1/1)	A message defining the exception of the entity.
/ [EntityExceptionType]/ Exception/ ExceptionScopeSchemaXPath	- xsd:string - S (0/1)	The level or point at which processing stops (within the entity). [BusinessRule(s): If fatal severity, this will match the EntitySchemaXPath. If warning severity, this will be the point at which processing stops within the entity. ]
/ [EntityExceptionType]/ Exception/ SubordinateEntityXPath	- xsd:string - S (0/*)	Provides additional Xpath information to help with the resolution of the exception. [BusinessRule(s): This will be an XPATH that can be used against the XML fragment included in the exception reporting. ]
/ [EntityExceptionType]/ Exception/ Followup	responsibleForFollowup xsd:restriction base: xsd:string [Enumerations]: No Followup Needed, Payload Source Organization, Acknowledgement Source Organization - - OrganizationId - EntityIdType - S (0/1) OrganizationName - xsd:string - S (0/1) PersonName - PersonNameType - S (0/1) ContactInfo - ContactMethodType - S (0/*)	Contains contact information about the person and organization responsible for correcting the exception.
/ [EntityExceptionType]/ Exception/ Followup/ responsibleForFollowup	xsd:restriction base: xsd:string [Enumerations]: No Followup Needed, Payload Source Organization, Acknowledgement Source Organization	Indicates who is responsible for correcting the exception or whether a follow-up is required. [Example(s): No follow-up needed, payload source organization, acknowledgement source organization. ]
/ [EntityExceptionType]/ Exception/ Followup/ OrganizationId	- EntityIdType - S (0/1)	Unique identifier for the organization. It may be an internal identifier assigned by the sender.
/ [EntityExceptionType]/ Exception/ Followup/ OrganizationName	- xsd:string - S (0/1)	The name by which an organization or enterprise is known as established under the laws of a country, state, province or ruling governmental body for the purpose of conducting business transactions.
/ [EntityExceptionType]/ Exception/ Followup/ PersonName	- PersonNameType - S (0/1)	The name of a person.
/ [EntityExceptionType]/ Exception/ Followup/ ContactInfo	- ContactMethodType - S (0/*)	Contains information to contact a person or entity. [Example(s): Person Name, Organization Name, Contact Method ]
/ [EntityExceptionType]/ Exception/ AdditionalData	Description - xsd:string - S (1/1) Value - xsd:string - S (1/1)	Allows trading partner specific structured information or extensions.
/ [EntityExceptionType]/ Exception/ AdditionalData/ Description	- xsd:string - S (1/1)	Describes the contextual information relating to a specific element. [Example(s): Description defining an Organization's mission or purpose. Description of stock plan. Description of payment terms and conditions. ]
/ [EntityExceptionType]/ Exception/ AdditionalData/ Value	- xsd:string - S (1/1)	A numerical quantity that is assigned or determined by calculation or measurement. [Synonym(s): Description, Quantity, Amount ]

4 Implementation Considerations

4.1 Introduction

The successful adoption of any HR-XML standard requires consistent interpretation among trading partners of certain situations. This section provides practical guidelines for using the HR-XML Application Acknowledgement schema in these situations. While an attempt is made to recommend a preferred approach for interpreting these situations, it is recognized that the capabilities of current source and receiving systems may vary widely from the suggested approach. For many situations an alternative approach is provided.

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 Timestamps

In the Application Acknowledgement there are a variety of timestamp elements. Prior to moving into production with a trading partner make sure that timestamp definitions are clearly defined. For example TransactionReceiptTimestamp could mean one thing to an Originator and something else to a Receiver. To avoid misunderstandings they need to be defined in advance.

4.4 Mutually Defined Sections

In the Application Acknowledgement schema, there are a few sections that are mutually defined. Before you send instances in production you will want to make sure and draft a trading partner agreement that defines the valid values that you will be sending in these areas. Elements like PayloadSummary and ExceptionIdentifier are strings and need to be defined prior to sending instances back to the originator.

5 Appendix A - Document Version History

Date	Description
2004-02-19	Initial draft
2004-03-08	Added Implementation Guidelines, schema diagram
2004-04-27	The schema was renamed to ApplicationAcknowledgement for more general use and moved to the CPO folder. Updated all sections to reflect changes from meeting discussions.
2004-May-20	Added examples, updated diagrams and definition tables based on final schema changes, updated section 2.
2004-June-3	Updated based on CPO/TSC feedback: rename EntityCount to EntityInfo; change ExceptionScopeSchemaXPath to optional; allow both PersonName and Organization info within Follow-up.
2004-June-07	Added terminology to clarify instance, payload and XML document.
2004-Aug-02	Approved by HR-XML Membership
2005-Aug	Made some required elements optional for general use case of a simple confirmation message.
2005-Oct	Changed UniquePayloadTrackingId from 1/1 to 0/1. Updated doc to clarify that the specification is available for use cases outside the benefits enrollment arena. Any reference to enrollment is now an example of the usage.
2006-Jan-13	Added ReferenceId for order numbers, confirmation codes, etc.
2005-Nov	Changed MessageIdType from an enum to a simple string.
2006-Feb-28	Approved by Consortium
2007-Apr-15	Approved by Consortium

6 Appendix B – Related Documents

Reference	Link
Application Acknowledgement	http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/ApplicationAcknowledgement.xsd http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/ApplicationAcknowledgement1.xml http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/ApplicationAcknowledgement2.xml http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/ApplicationAcknowledgement3.xml http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/ApplicationAcknowledgement4.xml http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/ApplicationAcknowledgement5.xml
Entity Identifiers	http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/EntityIdentifiers.html
Contact Method	http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/ContactMethod.html
Person Name	http://ns.hr-xml.org/2_5/HR-XML-2_5/CPO/PersonName.html

7 Appendix C – Reference Examples

While Benefits Enrollment use cases are described here, the Application Acknowledgement is intended for usage across the Consortium.

7.1 Example 1- Successful Record Processing

On April 1, 2004 two new hires were successfully enrolled in the company’s medical plan. That information was provided in the Enrollment XML instance document sent from TPA Inc. to Premier Company.

<MessageIdType>MQSeriesTransactionID</MessageIdType>

</MessageId>

</TransportMessageId>

</UniquePayloadTrackingId>

<ReceivedPayloadSchemaURI>http://ns.hr-xml.org/2_4/Enrollment/Enrollment.xsd</ReceivedPayloadSchemaURI>

<EntityInstanceAxisXPath>/Enrollment/Organization/Subscriber</EntityInstanceAxisXPath>

<EntityShortName>Subscriber</EntityShortName>

</EntityInfo>

</ReceivedPayloadSummary>

</PayloadResponseSummary>

</EntityIdentifier>

<EntityShortName>Medical Enrollment</EntityShortName>

<EntitySchemaXPath>/Enrollment</