message tracking info

Every WIJIS Service invocation or response is identified by an accompanying messageTrackingInfo element. This element contains addressing, routing and tracking information in defined attributes.

<msg:messageTrackingInfo
	wij-uri:serviceDefURI='http://wijis.wisconsin.gov/gateway/services/Pointer/request/upload/'
	svc:serviceProviderURI='http://wijis.wisconsin.gov/names/operators/jil/'
	svc:serviceLabel='smallUploadHandler_3'
	svc:serviceRequesterURI='http://wijis.wisconsin.gov/names/operators/ExampleCopShopSubmitter/'
	svc:initialUserURI='http://service.account@wijis.wisconsin.gov/names/operators/ExampleCopShopSubmitter/'
	svc:requesterInvocationNum='56789'
	svc:serviceInvocationNum='-1'
	msg:convSeq='0'
	msg:branchStack='0'
	svc:currentServiceDefURI='http://wijis.wisconsin.gov/gateway/services/Pointer/request/upload/'
	svc:currentServiceProviderURI='http://wijis.wisconsin.gov/names/operators/jil/'
	svc:currentServiceLabel='smallUploadHandler_3'
	svc:currentSendingOperatorURI='http://wijis.wisconsin.gov/names/operators/ExampleCopShopSubmitter/'
/>

<msg:messageTrackingInfo
	wij-uri:serviceDefURI='http://wijis.wisconsin.gov/gateway/services/Pointer/request/upload/'
	svc:serviceProviderURI='http://wijis.wisconsin.gov/names/operators/jil/'
	svc:serviceLabel='smallUploadHandler_3'
	svc:serviceRequesterURI='http://wijis.wisconsin.gov/names/operators/ExampleCopShopSubmitter/'
	svc:initialUserURI='http://service.account@wijis.wisconsin.gov/names/operators/ExampleCopShopSubmitter/'
	svc:requesterInvocationNum='56789'
	svc:serviceInvocationNum='34567'
	msg:convSeq='0'
	msg:branchStack='0/1/0'
	svc:currentServiceDefURI='http://wijis.wisconsin.gov/services/permissions/gatepoint/'
	svc:currentServiceProviderURI='http://wijis.wisconsin.gov/names/operators/wijis/gateway/'
	svc:currentServiceLabel='primary_service'
	svc:currentSendingOperatorURI='http://wijis.wisconsin.gov/names/operators/wijis/gateway/'
	svc:adHocUserURI='http://service.account@wijis.wisconsin.gov/names/operators/wijis/gateway/'
/>

Service Instance Identification

• Service Definition URI
  WIJIS assigns a unique URI to every defined WIJIS Service. (For operational convenience, complementary (but different) URIs are provided for Request and Response operations within a given Service definition. For the time being, these URIs are authoritatively documented in <appInfo> elements in the particular Service's Interface Definition schema.
• Service Provider URI
  Every entity that produces or consumes WIJIS Services is issued a WIJIS Operator URI. The Service Provider must publish its Operator URI as a feature of the Service Instance, but serviceProviderURI is usually easily determined by inspecting the list at http://wijiscommons.org/uri/.
• Service Label
  The Provider defines this value, if required. It's use is to distinguish between multiple operating instances of a given Service (i.e., a specific Service Definition URI) offered by the Provider. If the Label is not known or is not assigned for a specific Service instance, an empty string value is appropriate.

WIJIS User URI

When executing of WIJIS Service operations, permissions are determined by comparing a given User to the item or operation to which access is requested. WIJIS defines Users by assignment of URIs. In format, these follow the URI convention:

(for an authoritative, rigorous and detailed description see the IETF's "Generic URI Syntax" document at http://www.ietf.org/rfc/rfc3986.txt.)

WIJIS defines two types of User URIs: service and user URIs:

• For process-to-process communication, the Service User URI is ordinarily used. Any WIJIS Operator has exactly one Service User Account. The Service User URI is deterministically created from the WIJIS Operator URI by inserting the characters service.account@ after the double slash. Example: http://service.account@wijis.wisconsin.gov/names/operators/ExampleCopShopSubmitter/
• However, in cases when the Service Request is being made in the context of an actual User (e.g., the Gateway making a Record Retrieval request on behalf of a User who is logged in), that User's WIJIS User URI must be used. The User URI is similarly created by inserting a username in the customary position, but:
  • The URI, rather than being a WIJIS Operator URI, is the URI of the WIJIS-recognized Directory Service against which the user is authenticated;
  • The inserted username, instead of the constant literal "service.account", is the login name that the User logged in with.
  Example: If the user is BLONDWH693 when authenticating against the directory service at http://wijis.wisconsin.gov/names/directories/justiceDirectory/, the resulting User URI is:

	http://BLONDWH693@wijis.wisconsin.gov/names/directories/justiceDirectory/

The Service Conversation

A Conversation Tree is the set of all Service Requests and Responses that follow from an initial Service Invocation. The Initial Invocation is also referred to as the Root of the Tree. The combination of a Conversation Sequence and a Branch Stack identifies any Service call or response in the Conversation Tree. So, given the Initial Service Invocation, a Conversation Sequence, and a Branch Stack, it's possible to precisely and unambiguously identify any Service Message passed within WIJIS Space. The usefulness for logging and correlation is obvious.

Service Message Tracking Info, item by item

• Initial Invocation Information, which is a record of the initiating Service Request that spawned the entire chain of Requests, Responses, and logical branches. This Initiating Service Request serves two purposes:
  • It serves as a meta-correlationID, permitting easy association of requests with responses in an asynchronous messaging environment;
  • It is the default ultimate destination of any Response generated as part of the Service Request-Response conversation.
  The Initial Invocation Info consists of:
  • Requester Invocation Number
    An integer number supplied by the Requester when the Request is made; without this, the initial Requester might have trouble determining which Request a given Response is answering. This number can be any integer. WIJIS considers this number to be the "property" of the issuing Requester, and imposes no constraints. If a Requester wishes to make all of its Invocation Numbers "37", that's the Requester's problem.
    (However, a suggestion: using a sufficiently precise timestamp would be an easy and compliant way to generate a very useful Requester Invocation Number. Just saying.)
  • Service Invocation Number
    An integer number supplied by the Service Provider when the Request is received and handled; serves as the final identifying item to distinguish a single instance of Service Invocation. This number can be any integer, except as constrained by the last Service Invocation Number issued:
    • The Service Invocation Number is required to be part of a monotonic, but not necessarily dense, sequence. (This makes it easy to use a sufficiently precise integer timestamp for the value, if desired.)
    • The sequence is scoped to the Service Instance and the Requester. It is thus an error to assign the same number to, or to regress to a smaller number in, two subsequent invocations of the same Service Instance by a given WIJIS Operator.
    • Negative values are permitted, as long as they do not violate monotonicity.
    • A reset of the sequence must be coordinated with WIJIS: the precise time of reset, and the reset value, must be recorded and confirmed to guarantee the integrity of service invocation audits.
• Conversation Tree Information, which tracks the patterns of Request and Response, and the "service call branches" that occur when a Service component makes multiple calls to other Services. This is expressed by two elements:
  • The Conversation Sequence number, which tracks Requests and Responses in order. Conversation Sequence is dense and zero-based: A Request for a Service is Conversation Sequence 0 (zero). A Response to that Request is Conversation Sequence 1 (one). Almost all Service Coversation Sequences are completely described by the two statements above. However, the Conversation Sequence mechanism can support, if necessary, a more complex back-and-forth conversational pattern. In such a pattern, the same Requester responds by sending a new Request, with Conversation Sequence 2, to the same Provider, as a direct consequence of receiving the Conversation Sequence 1 Response. The Response to this Conversation Sequence 2 Request, in turn, would have Conversation Sequence 3. And so on. Some points to make about this pattern:
    • All Service Requests have even-numbered Conversation Sequence numbers.
    • All Service Responses have odd-numbered Conversation Sequence numbers.
    • Conversation Sequence Number can be extended unchanged through an arbitrary sequence of Proxy Service invocations.
    • Conversation Sequence Number can notbe extended unchanged to a call to a different Service.
  • The Branch Stack, which is an immutable Stack-like sequence containing integer elements. It is capable of precisely identifying any position in the Conversation Tree. The Branch Stack is represented in two forms:
    • The Fundamental form, an int[]
    • The Serialized form, a normalized String representation. This is done by writing the Stack numbers in order of decreasing significance, delimited by forward slashes. Thus a Branch Stack of {0, 3, 2, 0} could be written in an XML Attribute as branchStack='0/3/2/0'.
    Note that the Branch Stack is not, operationally, an actual "Stack" data structure; it's simply a sequence of integers, by intention immutable. It's referred to as a "stack" because it represents a given state in a recursive branching activity, which is ordinarily tracked by Stack behavior. Stack operations (e.g. "push", "pop") are defined for this data member only implicitly, in convenience methods that provide a modified copy for branching purposes.
• Current Invocation Information, which is essentially any necessary information about the service that is being called. (Much of this is optional, because it doesn't pertain to all logical cases in Service calls.) In essence, this is the addressing information for the Service Call; in some respects it's inherently redundant, but it may be entirely necessary for supporting addressing resolution at runtime. This category also includes an optional User URI, which can be provided in the new Service Call with the intent that it override the Initial Invocation User URI for purposes of authorization evaluation. If this Current User URI is not present, the Initial User URI must be used by the called Service for any kind of permissions checking.