MessageTrackingInfo Builder's Kit

WIJIS Message Tracking Info Builder's Kit

Your one-stop HOWTO shop for determining how to construct messageTrackingInfo elements for simple cases of WIJIS Service Request and Response messages.

This is a standalone HTML page, requiring no style or content resources from elsewhere. All external links are absolute, not relative. You can copy the source of this to any file, and use it locally as desired.

effective date: 2007-02-19

Overview

Fundamental Rules and Terminology For WIJIS Messaging

Terms And Conventions For These Discussions

Namespace Aliases In These Examples

YOUR_OPERATOR_URI

An Incoming Message's Message Tracking Info: "incoming"

The Parts Of A Message Tracking Info Element

The Two Simplest Kinds of Message Tracking Info

When You Are Making An Initial Service Request

When You Are A Service Provider, Responding To A Request

Message Tracking Info Examples For Individual WIJIS Services

Invoking A WIJIS Service: Pointer Upload Example

Providing a WIJIS Service: Record Retrieval Example

Overview

WIJIS has defined a rich audit-support mechanism for WIJIS Service invocations. This mechanism is called Message Tracking Info. The Message Tracking Info uniquely identifies any Service Request or Response message communicated within WIJIS Space.

Because it distinguishes all messages from each other, Message Tracking Info can also be used to provide Request-Response correlation in an asynchronous processing environment.

Every WIJIS Service Request or Response must have an associated Message Tracking Info element, or else it's not a compliant WIJIS Service communication.

Note that Message Tracking Info is not a complete navigational/ routing mechanism. It does not contain sufficient state to provide that capability. This is Tracking, not Routing. Routing must be handled by a different mechanism. (However, it is entirely appropriate for the routing mechanism to consult information contained in Message Tracking Info, if desired.)

This discussion does not cover payloads, nor general message structure. It's only concerned with one specific item: the Message Tracking Info data structure. This page should explain everything required in order to construct the correct Message Tracking Info for simple Request or Response messages.

Fundamental Rules And Terminology For WIJIS Messaging

The Message Tracking Info assumes the following about messages in WIJIS space:

Messages occur in event-driven clusters of Requests, Responses, forwards, and supporting calls ("side trips") to auxiliary services. Such a cluster of messages is called a Conversation.
No message can belong to more than one Conversation.
Every Conversation is associated with a single precipitating event. This event is always a WIJIS Service Request. This is called the Initial Service Invocation. Every Conversation has exactly one Initial Service Invocation -- no more, no less.
Every WIJIS Service must conform to a Service Definition. The Definition is associated with semantics describing the purpose and nature of the Service, and with XML Schema constraints on message payload content. Every WIJIS Service Definition is identified by a URI.
Every WIJIS Service message is either a Request or a Response. (Error messages are considered to be a subtype of Response, not an independent type.)
WIJIS Message Traffic occurs between components called nodes. Nodes can behave in two ways:
- A Service Requester (aka "Consumer") node
  - sends Requests, and
  - receives Responses.
- A Service Provider node
  - receives Requests, and
  - sends Responses.
Any node that can act as both Requester and Provider for a given Service definition is called a proxy node. Its function is normally to forward a Request or Response to the next node in a well-defined sequence. Such a sequence of service calls -- which must all be made to the same service definition -- is called a proxy chain.
Any node that is not a proxy is called a service endpoint. In other words, a service endpoint is the first or last link in a proxy chain: either the Initial Requester, or a non-delegating Provider of that Service.
The Service Interface definitions (i.e., the behavioral specifications of Requests and Responses) are encapsulating: i.e., it's impossible for a node sending or receiving a message to know whether it's communicating with a proxy or with an endpoint. In other words, no node can be guaranteed to have complete knowledge of the proxy chain of which it is a part.

So far, these are not really unusual definitions or characteristics for a messaging component architecture. However, WIJIS Services requires some additional behaviors which are somewhat more arbitrary:

If a WIJIS Service Request follows a proxy chain, the Response must travel back along the same chain until it reaches its originating Requester component. In other words, a diagram of a WIJIS service Conversation has no "loops" in it, only "branches" (it's what the topologists would term non-reentrant, for whatever that's worth.)
Any link in a proxy chain, except the Initial Requester, may make multiple Service Requests to various Services in Response to receipt of a Request. If it does, it's called a branching node.

(The good news here is that these more complicated issues of message routing topology do not really matter for the likeliest simple cases for messaging.)

Terms And Conventions For These Discussions

Namespace Aliases Used In Code Examples

The following namespace aliases apply to the examples:

msg	The current "WijisMessage" XML schema
wij-uri	The current "WijisURI" XML schema
svc	The current "WijisService" XML schema

(See http://wijiscommons.org/specs/ for the correct namespace URIs for the current version of each schema.)

Your WIJIS Operator URI

There is one item of information that is specific to your operation: the WIJIS Operator URI assigned to your organization. In the examples below, it's represented by the name YOUR_OPERATOR_URI.

Note one particular convention: YOUR_OPERATOR_URI, in this document, does not include the protocol and authority "root" characters http://, which prefix all WIJIS URIs. This doesn't mean that your Operator URI does not begin with that sequence: it does. Always. What this means is that we are using YOUR_OPERATOR_URI to represent the part of your URI that comes after those prefix parts. Okay?

If you need to find out what your Operator URI is, there are two things you need to know:

The authoritative list of WIJIS Operator URIs is found at http://wijiscommons.org/uri/.
If there's any doubt as to which Operator URI is yours - any doubt as to which URI you should extract the value of YOUR_OPERATOR_URI from, in order to make the examples below apply specifically to you - consult with WIJIS.

An Incoming Message's MessageTracking Info: "`incoming`"

We will use the special name incoming to refer to an incoming Request message's Message Tracking Info; a lot of the content of the corresponding Response's Message Tracking Info will depend on incoming.

The Parts Of A Message Tracking Info Element

Message Tracking Info is represented in a WIJIS XML Message as a single XML element, called messageTrackingInfo, with all values presented as attributes.

Message Tracking Info contains a total of 14 possible data items. They serve different purposes, and even though they appear as a simple flattened attribute list in the XML form, they are grouped into nested structures logically:

Initial Invocation Identification Once these properties are established, they remain identical for all other messages in the Conversation; no other Conversation will have this exact set of Message Tracking properties.
- Service Instance Identifier This is all information required to uniquely identify the Service Instance that's called during Initial Invocation:
  - serviceDefURI
  - serviceProviderURI
  - serviceLabel
- Initial Invocation Properties This is information available at the time the Request is sent:
  - serviceRequesterURI
  - requesterInvocationNum
  - initialUserURI
- Initial Invocation Receipt Properties This is information computed and assigned by the Provider upon receipt of the Initial Invocation:
  - serviceInvocationNum
Locating the message within the Conversation No two messages within a given Conversation will have the exact same combination of these two values:
- convSeq
- branchStack
Properties of the Current Service Invocation Information specific to the operation of sending the current message:
- Service Instance Identifier This is all information required to uniquely identify the Service component (Provider or Requester) that's called with the currrent message:
  - currentServiceDefURI
  - currentServiceProviderURI
  - currentServiceLabel
- currentSendingOperatorURI
- adHocUserURI If present, overrides initialUserURI for determining permissions.

A lot more information about these items can be found at http://wijiscommons.org/specs/message_exchange/.

The Two Simplest Kinds of Message Tracking Info

Although Message Tracking Info instances contain information which can appear forbidding and complicated, most of the genuine complexity occurs during proxy and branching operations. Happily, this is nothing that affects the two most common scenarios:

Initial Invocation (simplest Requester operation)
Responding to a Request (simplest Provider operation)

Here's how they work.

Simple Case #1: Message Tracking Info For An Initial Invocation

Determining Message Tracking Info for an Initial Invocation is pretty much a question of filling in the blanks.

serviceProviderURI
serviceDefURI	You get this info from the Provider of the Service you are calling. It never changes for any service call after that, unless The Service Provider tells you it's changing, or You decide to invoke a different service component of which you have knowledge.
serviceLabel
serviceRequesterURI	This is your WIJIS Operator URI (i.e., `http://YOUR_OPERATOR_URI`). You will need to know what that is in order to do any WIJIS Service operations at all. (If you don't know what to use, have a look at http://wijiscommons.org/uri/. If you still don't know, ask WIJIS.)
requesterInvocationNum	This is optional. It's there for your benefit: if you need to track a Service Request/Response Conversation using only information available to you at Request time, this will let you do that. (If you don't want to use it, use the distinguished value "-1".)
serviceInvocationNum	Not yours to assign. Use the distinguished value "-1".
initialUserURI	The WIJIS User URI identifying the user account against which all permissions evaluation will be performed.
convSeq	This will always be "0".
branchStack	This will always be "0".
currentServiceDefURI	These will be exactly the same as `serviceDefURI`, `serviceProviderURI`, `serviceLabel`, and `serviceRequesterURI` respectively.
currentServiceProviderURI
currentServiceLabel
currentSendingOperatorURI
adHocUserURI	You don't use this.

An example of this kind of Message Tracking Info composition can be found here.

Simple Case #2: Message Tracking Info For A Response To A Request

The Message Tracking Info for a Response is not very hard either.

serviceProviderURI
serviceDefURI	These items are fixed for this entire Conversation. Just copy them directly from `incoming`.
serviceLabel
serviceRequesterURI
requesterInvocationNum
serviceInvocationNum
initialUserURI
convSeq	Compute this number by adding 1 to the `convSeq` in `incoming`.
branchStack	This will always be exactly the same as `branchStack` in `incoming`.
currentServiceDefURI	You will need to get these (directly or indirectly) from the Service Provider that owns the component which submitted the Request. This is because you must reply directly to the Requesting component.
currentServiceProviderURI
currentServiceLabel
currentSendingOperatorURI	This is your WIJIS Operator URI (i.e., `http://YOUR_OPERATOR_URI`). You will need to know what that is in order to do any WIJIS Service operations at all. (If you don't know what to use, have a look at http://wijiscommons.org/uri/. If you still don't know, ask WIJIS.)
adHocUserURI	This is probably unnecessary. If you do need to provide an Ad Hoc User identifier, it will probably be your Service User Account.

An example of this kind of Message Tracking Info composition can be found here.

Example #1: Message Tracking Info For Invoking A Pointer Upload Service

In this example, you are generating an Initial Invocation for a WIJIS Service hosted by another entity. This is a Pointer Upload Service example, but (with the exception of the serviceDefURI) the data items would be the same for other WIJIS Services (such as Pointer Count or Pointer Download, for example).

Your Request To The Pointer Upload Service

The Upload Request is being made to a specific Pointer Upload Service component directly exposed by the WIJIS Gateway.

Required Prior Knowledge

In order to construct the Message Tracking Info for the Request, the following extrinsic information is required:

The pointer content is being uploaded by the service_account user account assigned to your Operator URI. The WIJIS User URI for this account is always constructed by prepending the literal String "http://service_account@" to YOUR_OPERATOR_URI.
Knowledge of the correct serviceDefURI for your Request.
- The Request and Response serviceDefURIs can always be found in annotation elements in the Service Interface Definition Schemas, reached via the Specifications page at http://wijiscommons.org/specs/. These are always appInfo elements, whose content is a name-value pair in which the name is serviceDefURI. There will never be more than one such appInfo element in any element declaration.
- In future, we may shift to a different service URI identification scheme; however, unless and until such a change is announced, this is the authoritative declaration.
Knowledge of the Service Instance the Gateway is exposing. In effect, this boils down to knowing
- That the Gateway does provide such a Service in the first place; and
- The correct Service Label for that instance. (Many Services have empty Service Labels, which is logically equivalent to a Null or nonexistent Label. There's nothing wrong with that; it's only a problem (not your problem, though) if more than one service instance has an empty Label.)

Notes About The Request Message Tracking Info

This example shows practical effect of the more general descriptions in Simple Case #1, above

The first 3 items define the Service Instance, as discussed above.
You need to know your own WIJIS Operator URI. Duh.
If you want to assign a requesterInvocationNum, go ahead (as shown in this example); otherwise, use "-1".
When you send this Request, serviceInvocationNum has not yet been assigned. Use "-1".
convSeq and branchStack are both "0".
currentServiceDefURI, currentServiceProviderURI, currentServiceLabel, and currentSendingOperatorURI are all the same as their corresponding entries in the first 4 items.

The Request `messageTrackingInfo`:


    <msg:messageTrackingInfo 
        wij-uri:serviceDefURI="http://wijis.wisconsin.gov/gateway/services/Pointer/request/upload/" 
        svc:serviceProviderURI="http://wijis.wisconsin.gov/names/operators/wijis/gateway/" 
        svc:serviceLabel="" 
        svc:serviceRequesterURI="http://YOUR_OPERATOR_URI"
        svc:requesterInvocationNum="1160080323713"
        svc:serviceInvocationNum="-1"
        svc:initialUserURI="http://service_account@YOUR_OPERATOR_URI" 
        convSeq="0"
        branchStack="0"
        svc:currentServiceDefURI="http://wijis.wisconsin.gov/gateway/services/Pointer/request/upload/" 
        svc:currentServiceProviderURI="http://wijis.wisconsin.gov/names/operators/wijis/gateway/"
        svc:currentServiceLabel=""
        svc:currentSendingOperatorURI="http://YOUR_OPERATOR_URI"
    />

Example #2: Message Tracking Info For Your Record Retrieval Service

This is the Record Retrieval Service that YOU implement. This means that you are the Service Provider. Service Requesters will be sending their Requests for given Records to your Service, and you need to construct appropriate Responses.

Request To Your Service, from the WIJIS Gateway

In this scenario, the record is being requested by user BLONWH678, who has authenticated to the DOJ Justice Directory. The Request has been sent from the WIJIS Gateway to your Service.

The Request `messageTrackingInfo`:


    <msg:messageTrackingInfo 
        wij-uri:serviceDefURI="http://wijis.wisconsin.gov/gateway/services/RecordRetrieval/request/recordRetrieval/" 
        svc:serviceProviderURI="http://YOUR_OPERATOR_URI" 
        svc:serviceLabel="" 
        svc:serviceRequesterURI="http://wijis.wisconsin.gov/names/operators/gateway/"
        svc:requesterInvocationNum="1160080283713"
        svc:serviceInvocationNum="-1"
        svc:initialUserURI="http://BLONWH678@wijis.wisconsin.gov/names/directories/justiceDirectory/" 
        convSeq="0"
        branchStack="0"
        svc:currentServiceDefURI="http://wijis.wisconsin.gov/gateway/services/RecordRetrieval/request/recordRetrieval/" 
        svc:currentServiceProviderURI="http://YOUR_OPERATOR_URI"
        svc:currentServiceLabel=""
        svc:currentSendingOperatorURI="http://wijis.wisconsin.gov/names/operators/wijis/gateway/"
    />

Constructing Message Tracking Info For Your Response

Your Record Retrieval Service needs to construct a Response to the received Request shown above. The Message Tracking Info for the Response will depend in large part on information available in incoming

Required Prior Knowledge

In order to construct the Message Tracking Info for the Response, the following extrinsic information is required:

Knowledge of the correct serviceDefURI for the Response.
- In general, the convention is that the URI pathelement "request/" be replaced with the pathelement "response/". However, doublecheck that: that convention is not authoritative. The annotation in the Service Definition schema is the only authoritative resource for this.
- In specific, the Request and Response serviceDefURIs can always be found in annotation elements in the Service Interface Definition Schemas, reached via the Specifications page at http://wijiscommons.org/specs/. These are always appInfo elements, whose content is a name-value pair in which the name is serviceDefURI. There will never be more than one such appInfo element in any element declaration.
- In future, we may shift to a different service URI identification scheme; however, unless and until such a change is announced, this is the authoritative declaration.
Knowledge of the Response Service Instance to which the Response will be returned:
- It's a WIJIS Service requirement that the Response travel back along the same chain of proxy nodes as was followed by the incoming Request. So, you need to know the Service Instance Identification Information for that node. This is not available from inspection of the incoming Request's Message Tracking Info. so it's necessary to do one of two things:
  - If there is a way of determining the Instance Identification Information of the invoking node at runtime, then that can be used. (In fact, that's the ideal situation.)
  - Otherwise, an agreed prior return path, compliant with WIJIS Service Response topology requirements, must be negotiated with the invoking WIJIS Operator. (That's probably how Record Retrieval would work, since it's such a simple operational situation.)

Notes About The Response

This example shows practical effect of the more general descriptions in Simple Case #2, above

The first 7 items identify the Conversation and say nothing about this individual message. They therefore remain identical to those in incoming, with one exception: You have computed and assigned a serviceInvocationNum, which became the final item of these seven "conversation identifiers".
convSeq is taken from incoming, treated as an integer, and incremented by 1. (This is absolutely required behavior when generating (as opposed to forwarding) a Response to an incoming Request.)
branchStack is copied unchanged from incoming. (This is always the case when generating a Response to an incoming Request.)
These are the items that identify the Service Instance to which the Response is sent. These need to be determined by external computing or prior agreement, as described above:
- currentServiceDefURI
- currentServiceProviderURI
- currentServiceLabel

The Response `messageTrackingInfo`:


    <msg:messageTrackingInfo 
        wij-uri:serviceDefURI="http://wijis.wisconsin.gov/gateway/services/RecordRetrieval/request/recordRetrieval/" 
        svc:serviceProviderURI="http://YOUR_OPERATOR_URI 
        svc:serviceLabel="" 
        svc:serviceRequesterURI="http://wijis.wisconsin.gov/names/operators/gateway/"
        svc:requesterInvocationNum="1160080283713"
        svc:serviceInvocationNum="1160080284456"
        svc:initialUserURI="http://BLONWH678@wijis.wisconsin.gov/names/directories/justiceDirectory/" 
        convSeq="1"
        branchStack="0"
        svc:currentServiceDefURI="http://wijis.wisconsin.gov/gateway/services/RecordRetrieval/response/recordRetrieval/" 
        svc:currentServiceProviderURI="http://wijis.wisconsin.gov/names/operators/wijis/gateway/"
        svc:currentServiceLabel=""
        svc:currentSendingOperatorURI="http://YOUR_OPERATOR_URI"
    />

WIJIS Message Tracking Info Builder's Kit

Contents

Overview

Fundamental Rules And Terminology For WIJIS Messaging

Terms And Conventions For These Discussions

Namespace Aliases Used In Code Examples

Your WIJIS Operator URI

An Incoming Message's MessageTracking Info: "incoming"

The Parts Of A Message Tracking Info Element

The Two Simplest Kinds of Message Tracking Info

Simple Case #1: Message Tracking Info For An Initial Invocation

Simple Case #2: Message Tracking Info For A Response To A Request

Example #1: Message Tracking Info For Invoking A Pointer Upload Service

Your Request To The Pointer Upload Service

Required Prior Knowledge

Notes About The Request Message Tracking Info

The Request messageTrackingInfo:

Example #2: Message Tracking Info For Your Record Retrieval Service

Request To Your Service, from the WIJIS Gateway

The Request messageTrackingInfo:

Constructing Message Tracking Info For Your Response

Required Prior Knowledge

Notes About The Response

The Response messageTrackingInfo:

An Incoming Message's MessageTracking Info: "`incoming`"

The Request `messageTrackingInfo`:

The Request `messageTrackingInfo`:

The Response `messageTrackingInfo`: