BODs encapsulate both behavior and structure for business interactions and facilitate data management between system actors. Simply stated a BOD pairs a verb with a noun. The verb identifies the action that the sender wants the receiver to perform on the noun. Verbs also have a role in the responses from a receiver back to the sender of the original message.

HR-XML draws upon a subset of the standard OAGIS verbs and includes a set of nouns designed around common HR application integration scenarios. HR-XML combines verb and noun according to the OAGIS BOD architecture. Verbs are described in depth in the section called “Subset of OAGIS Verbs Implemented”. The nouns defined within the HR-XML library are described in Chapter 3, Noun Catalogue.

A general representation of the BOD architecture is depicted in the figure below.

Figure 2.1. Basic BOD Architecture

In an actual BOD, the generic names (BusinessObjectDocument, Verb, Noun) are replaced by specific names. For example, the figure below shows a simplified representation of ProcessCandidate BOD, combining the OAGIS verb "oa:Process" with HR-XML's Candidate noun. Note that the use of the "oa:" prefix on the Process verb indicates the element is within the OAGIS namespace.

Figure 2.2. Basic BOD Architecture Applied to HR

As shown in the diagram above, the BOD structure contains an application area and a data area. As shown in the diagram below, the verb and noun are part of the data area.

Figure 2.3. BODs: Major Components

The major components of the BOD architecture break down as follows:

The following is a trivial HR-XML BOD example offered in the spirit of the "hello world" introductory examples often found in programming guides. It is intended to help you tie the concepts from the prior section to XML syntax used by BODs.

Source

<?xml version="1.0" encoding="UTF-8"?>
<ProcessCandidate 
			releaseID="3.0" 
			languageCode="en-US" 
			xsi:schemaLocation="http://www.hr-xml.org/3  ../Developer/BODs/ProcessCandidate.xsd" 
			xmlns="http://www.hr-xml.org/3" 
			xmlns:oa="http://www.openapplications.org/oagis/9" 
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<oa:ApplicationArea>
		<oa:CreationDateTime>2009-10-17T10:09:02.01Z</oa:CreationDateTime>
		<oa:BODID>PC2009-11-17-052</oa:BODID>
	</oa:ApplicationArea>
	<DataArea>
		<oa:Process>
			<oa:ActionCriteria>
				<oa:ActionExpression actionCode="Add">/ProcessCandidate/DataArea/Candidate</oa:ActionExpression>
				<oa:ChangeStatus>
				       <oa:ReasonCode>Candidate Applied</oa:ReasonCode>
				</oa:ChangeStatus>
			</oa:ActionCriteria>
		</oa:Process>
		<Candidate languageCode="en">
			<DocumentID>Hello World!</DocumentID>
			<CandidatePerson>
				<PersonName>
					<FormattedName>Tom Smith</FormattedName>
					<oa:GivenName>Tom</oa:GivenName>
					<FamilyName>Smith</FamilyName>
				</PersonName>
			</CandidatePerson>
		</Candidate>
	</DataArea>
</ProcessCandidate>
<!--


Copyright The HR-XML Consortium. All Rights Reserved. http://www.hr-xml.org 
Copyright (c) 1997-2009 Open Applications Group, Inc. All Rights Reserved 
-->

Note the following:

As you will learn, two different approaches to handling updates are supported. One involves the communication of only "delta" or "incremental" change information whereas the other approach relies on a "snap shot" or full-refesh approach. The example above, by use of an "ActionCode" of "Add" and an "ActionExpression" is indicative of the incremental style of updates. For further information, see the section called “Data Management Approaches”.

The BOD architecture anticipates requests as well as responses. So next in our trivial example would be a response to the ProcessCandidate BOD. An example of a possible response is shown below.

Source

<?xml version="1.0" encoding="UTF-8"?>
<AcknowledgeCandidate 
		    releaseID="3.0"
			languageCode="en-US" 
			xsi:schemaLocation="http://www.hr-xml.org/3  ../Developer/BODs/AcknowledgeCandidate.xsd" 
			xmlns="http://www.hr-xml.org/3" 
			xmlns:oa="http://www.openapplications.org/oagis/9" 
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<oa:ApplicationArea>
		<oa:CreationDateTime>2009-10-17T10:09:02.21Z</oa:CreationDateTime>
		<oa:BODID>PC2009-21-12-123</oa:BODID>
	</oa:ApplicationArea>
	<DataArea>
		<oa:Acknowledge>
         <oa:OriginalApplicationArea>
		       <oa:CreationDateTime>2009-10-17T10:09:02.01Z</oa:CreationDateTime>
		       <oa:BODID>PC2009-11-17-052</oa:BODID>
         </oa:OriginalApplicationArea>		
         <oa:ResponseCriteria>
		        <oa:ResponseExpression actionCode="Accepted">/AcknowledgeCandidate/DataArea/Candidate</oa:ResponseExpression>
		        <oa:ChangeStatus>
		               <oa:Code>Candidate Profile Created</oa:Code>
		        </oa:ChangeStatus>
		</oa:ResponseCriteria>
		</oa:Acknowledge>
		<Candidate languageCode="en">
			<DocumentID>Hello World!</DocumentID>
           </Candidate>		
	</DataArea>
</AcknowledgeCandidate>
<!--


Copyright The HR-XML Consortium. All Rights Reserved. http://www.hr-xml.org 
Copyright (c) 1997-2009 Open Applications Group, Inc. All Rights Reserved 
-->

Basically, this does little more than acknowledge that the entity communicated in the prior ProcessCandidate BOD represented by the DocumentID "Hello World!" was created.

Let's assume that the sender of the original ProcessCandidate changes its mind the following day and wants to cancel the original request. Let's say that this isn't a simple delete, but something that would require some business calculation or approval by the recipient. Such a request might be communicated in a request like the one below.

Source

<?xml version="1.0" encoding="UTF-8"?>
<CancelCandidate 
		    releaseID="3.0"
			languageCode="en-US" 
			xsi:schemaLocation="http://www.hr-xml.org/3  ../Developer/BODs/CancelCandidate.xsd" 
			xmlns="http://www.hr-xml.org/3" 
			xmlns:oa="http://www.openapplications.org/oagis/9" 
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<oa:ApplicationArea>
		<oa:CreationDateTime>2009-10-18T10:07:02.01Z</oa:CreationDateTime>
		<oa:BODID>PC2009-31-27-4123</oa:BODID>
	</oa:ApplicationArea>
	<DataArea>
		<oa:Cancel>
			<oa:ActionCriteria>
				<oa:ActionExpression actionCode="Delete">/CancelCandidate/DataArea/Candidate</oa:ActionExpression>
          <oa:ChangeStatus>
             <oa:ReasonCode>Requested Removal</oa:ReasonCode>
          </oa:ChangeStatus>			
        </oa:ActionCriteria>
		</oa:Cancel>
		<Candidate languageCode="en">
			<DocumentID>Hello World!</DocumentID>
	 </Candidate>
	</DataArea>
</CancelCandidate>
<!--


Copyright The HR-XML Consortium. All Rights Reserved. http://www.hr-xml.org 
Copyright (c) 1997-2009 Open Applications Group, Inc. All Rights Reserved 
-->

The above message instance simply requests that the receiving system cancel the entity represented by the DocumentID "Hello World!". While not shown here, this request would be responded to by another AcknowledgeCandidate message instance that might accept, reject, or possibly modify the cancellation request.

Note that this simple example demonstrates one possible pattern of message exchange using BODs. Dozens of other examples are available within the library documentation. Also see the section called “Subset of OAGIS Verbs Implemented” and the section called “Data Management Approaches” for a complete description of OAGIS verbs and data management features.

The introductory sections have already described the basic structure of a BOD. As described in the section called “Basic BOD Architecture”, a BOD has an ApplicationArea and a DataArea. The DataArea contains a Verb and a Noun. The sections below describe other BOD components not already examined in earlier sections.

Note that all the components described below are defined within the OAGIS namespace. The documentation that appears below, with just a few editorial customizations, has been drawn directly from the OAGIS documentation of these components.

BOD Attributes

Each BOD has the common set of attributes depicted in the diagram below. The use of the attributes is explained below. Note that a single attribute (releaseID) is mandatory and must be populated by implementers.

Figure 2.4. BOD Attributes

releaseID

Release ID is used to identify the release of the HR-XML library to which the BOD belongs. For the BODs from HR-XML 3.0 library, the value of this attribute will be "3.0". The releaseID is a required attribute.

versionID

Version ID is used to identify the version of the Business Object Document. Currently HR-XML does not currently plan to version BODs independently of the release. The versionID attribute is optional and generally would not be used in HR-XML implementations until such time as BODs are versioned independently of the release.

systemEnvironmentCode

The System Environment Code is used to identify whether this particular BOD is being sent as a result of a test or whether it represents production level integration. Often times as new systems are brought online testing must be performed in a production environment in order to ensure integration with existing systems. This attribute allows the integrator to flag these test messages as such. The environment attribute is an optional attribute of the BOD.

languageCode

The languageCode attributes indicates the language of the data being carried in the BOD message. It is possible to override the BOD level language for fields that may need to carry multi-lingual information. Examples of this are Comment and Description elements.

Application Area Described

Each BOD definition and BOD message instance will contain a single ApplicationArea. A single element within a BOD instance is mandatory (CreationDateTime).

The ApplicationArea serves four main purposes:

1. To identify the sender of the message.

2. To identify when the document was created.

3. To provide authentication of the sender through the use of a digital signature, if applicable.

4. To uniquely identify a BOD instance. The BOD ID field is the Globally Unique Identifier for the BOD instance.

Note

The ApplicationArea carries information that an application may need to know in order to communicate in an integration of two or more business applications. The ApplicationArea is used at the applications layer of communication. Middleware and integration frameworks such as Web services provide the communication layer itself.

The components within the Application Area are illustrated and explained below.

Figure 2.5. Application Area

Sender

The Sender identifies characteristics and control identifiers that relate to the application that created the Business Object Document. The sender area can indicate the logical location of the application and/or database server, the application, and the task that was processing to create the BOD.

The Sender area also provides the ability to create an audit trail to allow users to drill down from their Receiving business application to the information used to complete the business transaction being communicated in the BOD.

In today’s business environments and advanced technology frameworks a single BOD may be routed to multiple destinations or receivers. For this reason, it is not feasible for the sending system to "know" all of the possible destinations of a BOD. For this reason, the Open Applications Group has made a conscious decision NOT to include a Receiver in the ApplicationArea. This is left to the middleware or infrastructure framework to ensure delivery to all locations that are interested in the content of the BOD.

LogicalID

The Logical Identifier element provides the logical location of the server and application from which the Business Object Document originated. It can be used to establish a logical to physical mapping, however its use is optional.

Each system or combination of systems should maintain an external central reference table containing the logical names or logical addresses of the application systems in the integration configuration. This enables the logical names to be mapped to the physical network addresses of the resources needed on the network.

Note

The technical implementation of this Domain Naming Service is not dictated by this specification.

This logical to physical mapping may be done at execution time by the application itself or by a middleware transport mechanism, depending on the integration architecture used.

This provides for a simple but effective directory access capability while maintaining application independence from the physical location of those resources on the network.

ComponentID

The Component ID provides a finer level of control than Logical Identifier and represents the business application that issued the Business Object document. Its use is optional.

TaskID

The Task ID describes the task that initiated the need for the Business Object Document to be created. Tasks are triggered by events - so a task is a generalization between an action and a triggering event.

ReferenceID

Reference ID enables the sending application to indicate the instance identifier of the event or task that caused the BOD to be created. This allows drill back from the BOD message into the sending application. The may be required in environments where an audit trail must be maintained for all transactions.

ConfirmationCode

The Confirmation Code request is an option controlled by the Sender business application. It is a request to the receiving application to send back a confirmation BOD to the sender. The confirmation Business Object Document may indicate the successful processing of the original Business Object Document or return error conditions if the original Business Object Document was unsuccessful.

The confirmation request has the following valid values:

• Never. No confirmation Business Object Document requested

• OnError. Send back a confirmation Business Object Document only if an error has occurred

• Always. Always send a confirmation Business Object Document

AuthorizationID

The Task ID describes the task that initiated the need for the Business Object Document to be created. Tasks are triggered by events - so a task is a generalization between and action and a triggering event.

The Authorization Identifier describes the point of entry, such as the machine or device the user uses to perform the task that caused the creation of the Business Object Document.

The Authorization Identifier is used as a return routing mechanism for a subsequent BOD, or for diagnostic or auditing purposes. Valid Authorization Identifiers are implementation specific. The Authorization Identifier might be used for authentication in the business process.

In returning a BOD, the receiving application would pass the Authorization Identifier back to the controller to allow the message to be routed back to the hand held terminal.

CreationDateTime

CreationDateTime is the date time stamp that the given instance of the Business Object Document was created. This date must not be modified during the life of the Business Object Document.

Signature

If the BOD is to be signed the signature element is included, otherwise it is not.

Signature will support any digital signature that maybe used by an implementation of OAGIS. The qualifyingAgency identifies the agency that provided the format for the signature.

This element supports any digital signature specification that is available today and in the future. This is accomplished by not actually defining the content but by allowing the implementation to specify the digital signature to be used via an external XML Schema namespace declaration. The Signature element is defined to have any content from any other namespace.

This allows the user to carry a digital signature in the xml instance of a BOD. The choice of which digital signature to use is left up to the user and their integration needs.

For more information on the W3C’s XML Signature specification refer to: http://www.w3.org/TR/xmldsig-core/.

BODID

The BODID provides a place to carry a Globally Unique Identifier (GUID) that will make each Business Object Document uniquely identifiable. This is a critical success factor to enable software developers to use the Globally Unique Identifier (GUID) to build the following services or capabilities:

1. Legally binding transactions

2. Transaction logging

3. Exception handling

4. Re-sending

5. Reporting

6. Confirmations

7. Security