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

Contents

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:

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:

(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:

msgThe current "WijisMessage" XML schema
wij-uriThe current "WijisURI" XML schema
svcThe 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:

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:

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:

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.

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.
serviceProviderURI
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.

serviceDefURI These items are fixed for this entire Conversation. Just copy them directly from incoming.
serviceProviderURI
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:

Notes About The Request Message Tracking Info

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

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:

Notes About The Response

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

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"
    />