HR-XML 3.0 Standards, 2009 September 23.
Menu: [ Home | Guidelines | BODs | Nouns | Global elements | WSDL | Packages | Code Lists | Master Index ]
Trace back: » ch03s14 | ch46s16 | ch03s30 | ch03s13 | ch02s03 »
The Version 3.0 library relies on a subset of the OAGIS verb catalogue. A glossary for this subset appears below.
Each OAGIS verb has associated semantics. Verbs also have associated structure depending on the verb type (see the section called “Verb Types and Response Patterns”). OAGIS verb names represent a coarse-grain action, response, or request in relation to a Noun. The structure available within each verb type enables communication of fine-grain actions on components within a Noun. Both the semantics and the structure of these verbs are explored in the sections that follow.
It is important to understand the semantics behind the OAGIS verbs. The semantics are intended to be precise. Definitions differ from common usage of the same terms as well as usage under other messaging frameworks.
- Cancel
The Cancel verb is used when the sender of the BOD is not the owner of the data, but is sending a request for the document to be canceled. An example is the Cancel PO where the business implications must be calculated and a simple data processing term such as delete can not fully convey the business meaning and required processing associated with the meaning.
- Change
The Change verb is used when the sender of the BOD is not the owner of the data, but is sending a request for the document to be changed.
- Process
The Process verb is used to request processing of the associated noun by the receiving application or business party.
- Notify
The Notify verb is used to inform the receiving party that an event has occurred or document has been created. For example, a supplier may have a proposed order that is sent to a trading partner. The noun will contain the data that has been proposed.
- Get
The Get verb is to communicate to a business software component a request for an existing piece of information to be returned. The Get may be paired with most of the nouns defined in the OAGIS specification. The response to this request is the Show verb. The behavior of a BOD with a Get verb is quite predictable across most of the nouns. The Get is typically used to retrieve a single piece of information by using that information's primary retrieval field, or key field, but may support certain reporting needs by supporting retrieval of a range of documents matching a given filter. For further information, see the section called “Request Verb Type” and the section called “Get Verb”
- Acknowledge
The Acknowledge verb is used to acknowledge the application receipt of a Process request. This function conveys the result of the original request. An example of this is Acknowledge PO, where a Process PO has been issued and the corresponding business application acknowledges the receipt of the PO and responds with an acceptance or a counter offer.
- ConfirmBOD
The Confirm verb is used to respond to a request to confirm the receipt of information by the receiving system. The request for confirmation is set by the sending application in the ApplicationArea\Sender\Confirmation field of the original BOD. The Confirm conveys the result of the original request i.e. whether or not the message was understood and was successfully processed.
- Respond
The Respond verb is used to communicate relative to another document. It may be used to communicate agreement, questions, answers to a question, or disagreement with the related document.
- Show
The Show verb is used when sending the information about a specific instance of a business document or entity. The Show verb may be used to respond to a Get request or it can be used in a publish scenario, where it pushes information to other applications based on a business event. Although BODs based on this verb do not commonly cause updates to occur, there may be times when the component receiving the Show decides to use the information it receives to update. See the section called “Show Verb”.
- Sync
The Sync verb is used when the owner of the data is passing or publishing that information or change in information to other software components. This is to be used when the receiver of the SyncBOD does not own the data. This verb is commonly used when mass changes are necessary or when a publish and subscribe mechanism is used in the integration architecture.The purposes of this verb include application integrity and ease of data entry for the business user by enabling a single point of input.
The structure of a verb is determined by its type. There are three types of OAGIS verbs. The three verb types are:
Action. These include verbs to create or otherwise act upon a business object. Action verbs include "Process," "Change," "Notify," etc. See the section called “Action Verb Type”.
Response. A response enables a receiver to reply or send relevant meta-data back to the sender of the original message instance. A response can be a response to a message with an Action verb or even a response to another response message. See the section called “Response Verb Type”.
Request. A request verb enables the communication of "read" data management instructions from a message sender to a receiver. The "Get" verb currently is the only request verb. Depending on the implementation, "read" instructions could encompass the simple retrieval of a discrete document or piece of data as well as complex queries or filters applied against a broad collection of objects. See the section called “Request Verb Type”
The table below shows which of the OAGIS verbs used within the HR-XML library are of which verb type. For each verb, the associated "noun-specific" and "noun-independent" responses (if any) also are indicated. As you can see, "ConfirmBOD" is the noun-independent "catch-all" response. It can be used as a simple confirmation receipt of a request as opposed to responding to specific business content within a request message. ConfirmBOD also is used to report exceptions in the processing of requests.
Table 2.1. Verb Types and Responses
| Verb | Verb Type | Noun-Specifc Response | Noun-Independent Response |
|---|---|---|---|
| Cancel[noun] | Action | Acknowledge[noun] | ConfirmBOD |
| Change[noun] | Action | Acknowledge[noun] | ConfirmBOD |
| Process[noun] | Action | Acknowledge[noun] | ConfirmBOD |
| Notify[noun] | Action | Acknowledge[noun] | ConfirmBOD |
| Get[noun] | Request | Show[noun] | ConfirmBOD |
| Acknowledge[noun] | Response | None | ConfirmBOD |
| ConfirmBOD | Response | None | None |
| Respond[noun] | Response | None | ConfirmBOD |
| Show[noun] | Response | None | ConfirmBOD |
Action verbs convey operations to be performed upon, or in relation to, a noun. Broadly speaking, action verbs encompass the kind of operations that "create," "update," and "delete" verbs convey under the so-called "CRUD" convention commonly used in referencing basic computer storage operations. The OAGi action verbs used within the HR-XML library are: Cancel, Change, Notify, Process, and Sync.
The diagram below shows the elements of the ActionVerbType definition.
The ActionVerbType depicted in the diagram above breaks down as follows:
An action verb supports zero-to-many ActionCriteria. Each ActionCriteria supports zero-to-many ActionExpressions and zero-to-one ChangeStatus.
The ActionExpression is the mechanism used to represent the data management instructions in a BOD instance. Specifically, this includes identification of the element(s) and the action to be taken on those elements. Identification of the element may consist of its location in the schema structure and possibly additional key value information if it is necessary to identify a specific element of interest in a BOD instance.
ChangeStatus may be used to communicate state change information (e.g. the EffectiveDateTime and ReasonCode for the state change as well as the FromStateCode and ToStateCode).
The ActionExpression has two attributes: actionCode and expressionLanguage. The actionCode attribute of ActionExpression specifies an action to be taken by the receiver of the BOD instance. The actionCode is restricted to a value domain. The actionCode's value domain includes: Add, Change, Delete, and Replace.
The noun or nouns within a BOD instance represent the entity or entities being managed. The ActionExpression, where used, sets the scope within the noun to which the instruction specified within the actionCode is applied. The following patterns apply:
"Add" - the noun content represents the entities being added.
"Change" - the noun content represents the change entities.
"Delete" - the content of the noun represents or identifies the entities being deleted.
"Replace" - the noun content represents the replacement entities.
Response verbs are used by message receivers to convey meta-data to the sender of an original message instance. The OAGIS response verbs are Acknowledge, Confirm, Respond, and Show.
Response verbs are used in several different data management contexts. Consider that response verbs are used in message instances that respond to:
Action verb message instances. For example, the Acknowledge verb would be used in a message instance responding to a message constructed with a Process verb. In this case, the response message conveys the functional result of the action specified in the original message instance.
Request verb messages instances. For example, the Show verb would be used in a message instance responding to a message constructed with a Get verb. In this case, the response message conveys data for the entities matching the "read" instruction specified in the original request message instance.
As explained in the section called “Verb Types and Responses”, the Confirm verb is the noun-independent verb conveying message receipt and can be used in a response to a message using any other verb. Consider that a message instance using the Show verb might be responded to with a message instance using the Confirm response verb.
The diagram below shows the elements of the ResponseVerbType definition.
The ResponseVerbType depicted in the diagram above breaks down as follows:
The ResponseExpression has two attributes: actionCode and expressionLanguage.
The actionCode specifies an action that was taken by the receiver of the BOD instance.
The ResponseExpression.actionCode is restricted to a value domain. The actionCode’s value domain includes: Accepted, Modified, and Rejected.
The Show verb is based on the ResponseVerbType. It is used in message instances returning the results of "read" instructions sent in a message instance using the Get verb. The diagram below illustrates the Show verb's extension of the ResponseVerbType.
The extension includes several attributes whose values may be set as part of a Show response. The attributes are defined as follows:
recordSetStartNumber. The record number identifying the first record returned in the Show response. The producer of the Show response generates this number. It is used by the requesting system to determine the start number of the subsequent Get request.
recordSetCount. Number of records in the recordSet.
recordSetTotal. Number of total records in a recordSet.
recordSetCompleteIndicator. Indicates whether this is the last segment of the recordSet.
recordSetReferenceID. Unique identifier of the RecordSet. It is generated by the producer of the Show response as a result of the original Get request.
The request verbs are the OAGi language elements through which Read data management instructions are conveyed by message senders to receivers. As shown in Table 2.1, “Verb Types and Responses”, "Get" currently is the only verb implementing RequestVerbType. Figure 2.9, “OAGIS RequestVerbType” shows the elements of the RequestVerbType schema definition. The single element, Expression, has one attribute, expressionLanguage.
The Get verb is to communicate a request for an existing piece of information to be returned. The Get is typically used to retrieve a single piece of information by using an ID for the related element. However, Get may also support certain reporting needs by enabling the retrieval of a range of documents matching a given filter. An example might be a filter constructed to retrieve all ScreeningOrders or StaffingOrders or other documents with a given status.
The schema definition for the Get verb extends RequestVerbType as shown in Figure 2.10, “OAGIS GetType”.
The extension includes several attributes whose values may be set as part of a Get request. The attributes are defined as follows:
uniqueIndicator. Indicates whether duplicates should be filtered out.
maxItems. Communicates the maximum number of records which should be returned in a segment from a recordSet.
recordSetSaveIndicator. A true value indicates that receiver should save the record set.
recordSetStartNumber. The record number identifying the first record that should be returned in the Show response. This attribute is specified on subsequent Get requests, not an initial Get request (see Initial and Subsequent Get Operations ). The requesting system may determine this number from the prior Show response. For further information, see the section called “Show Verb”.
recordSetReferenceID. Unique identifier of the RecordSet. It is generated by the producer of the Show response as a result of the original Get request.
Initial and Subsequent Get Operations
A initial Get request may be followed by related Get requests. As mentioned above, it is necessary to distinguish an initial request, from subsequent requests in that the recordSetStartNumber would only appear on the related, subsequent requests. These initial and subsequent Get requests are related in that they execute a single read operation using the same selection and filter criteria. The subsequent Get request(s) may be communicated when an initial Get request results in more records that can be returned in a single Show response. In other words, more records than allowed by the maxItems indicator.