| [alf-dev] Agenda for ALF Architecture Call Oct 20, 2005 |
For ALF 1.0, all communication will be based on web services, so the Events will travel within a SOAP Envelope. The message will be constructed according to the ALF Web Service Conformance Guidelines document.
Figure 5. ALF Event, showing SOAP Structures
The 3 parts of an Event message are:
· All events definitions have a core defined as org.eclipse.ALF.BasicEvent, which is the same for all Events.
· Following the BasicEvent elements is an optional structure that is defined by ALF Vocabulary Committees and represents the data for different types of objects that occur in tools. In general, there will be a separate structure for each type of object. Examples of objects are Class, Class diagram, Requirement, Baseline, Source file, etc. The ALF 1.0 Event Manager will not make use of the ALF Vocabulary-specific data in determining which Actions to launch.
· Following the ALF-defined object-type structure is another optional structure of tool-specific data. The Event Manager will not make use of such tool-specific data in determining which Actions to launch.
This full form of an Event message can be used by any tool, though it is especially useful for transient tools, such as BUILD programs and batch code scanners that may not exist when a ServiceFlow later needs to access data about the object that triggered the event.
Figure 6.
Simplest Event
The most basic Event can simply convey the BasicEvent data structure. This approach can be used where subsequent ServiceFlows can use the identifying data in the BasicEvent to retrieve the data that would have been conveyed in the ALF Vocabulary structure.
We will begin describing the ALF Event Message structure for ALF.BasicEvent by providing an example.
<Event
ALFEventVersion="1.0"
xmlns="http://www.eclipse.org/ALF/XMLSchema/Events/"
xmlns:cmn="http://www.eclipse.org/ALF/XMLSchema/Vocabularies/Common"
xmlns:iss="http://www.eclipse.org/ALF/XMLSchema/Vocabularies/Issue"
xmlns:srna="http://www.serena.com/ALF/XMLSchema/Vocabularies"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.eclipse.org/ALF/XMLSchema/Events/BasicEvent.xsd">
<EventData>
<EventID>some
UUID</EventID>
<Timestamp>2005-10-05T09:00:00<Timestamp>
<EventType>Object
Created</EventType>
<ObjectArray>
<Object>
<ObjectType>ISSUE</ObjectType>
<ObjectId>12345678</ObjectId>
</ObjectArray>
</Objects>
<Source>
<Product>Serena
TeamTrack</Product>
<ProductVersion>6.5</ProductVersion>
<ProductInstance>tt.mycorp.com</ProductInstance>
</Source>
</EventData>
<Contexts>
<Context nesting="0">
<UserCredentials>X%Hjia4cnmm(A@</UserCredentials>
<InitiatingFlow type="human">someUUID</InitiatingFlow>
</Context>
</Contexts>
<EventDetails>
<iss:ALF_Issue>
<cmn:Identifier>1234</Identifier>
<cmn:Name>Tom Smith's PC cannot
use OutLook with VPN</Name>
<cmn:Description>When the user launches
OutLook, it causes the VPN connection to
close</Description>
<iss:Severity>1</Severity>
<iss:Originator>Tom
Smith</Originator>
<iss:Classification>Communications</Classification>
<iss:AttachmentLinks></AttachmentLinks>
</iss:ALF_Issue>
<cmn:ExtensionData>
<srna:OriginatorPhone>(650)
522-1234</srna:OriginatorProblem>
</cmn:ExtensionData>
</EventDetails>
</Event>
Each element will be described,
below:
The Event element is the outermost node of the document (other than the surrounding SOAP elements). The Event element has an attribute:
· ALFEventVersion – An _expression_ designating the version of the BasicEvent
A container for information describing the nature of the event and its physical origin (the source or emitter of the event.)
<EventID> - A UUID that uniquely identifies the Event instance
<Timestamp> - The date and timestamp (in XML dateTime format) when the tool emitted the event.
<Event Type> - A string indicating the type of event. EventType designates the “verb”; that is what action happened to the Objects that triggered the event. Event types will be enumerated by ALF (see the Appendices.)
<ObjectArray> - A container for the identifications of the objects that the tool was operating on, and caused the event.
<Object> - A container for the
identifications of the objects that the tool was operating on. The intent is
that when the Event pertains to an entity, there will be a single
<Object>. For relationships,
there will usually be two and perhaps more instances of the <Object>
element. The purpose of these
elements is to identify the entity or relationship that was being operated on
and which caused the event.
Notes:
1.
At least for ALF
1.0, we will not consider the possibility of having an Event refer to a set of
objects, other than to express the participants in a relationship.
2.
The primary use
is for Service Flows which may need to access the object that triggered the
event, for example to call back to the tool to obtain additional information.
3.
We need to think about transient
processes, such as a BUILD process, for which an identifier may be a hazy or
transient notion – for those, we may want to make the Object element
optional.
<ObjectType> - The type of entity involved. Note that the word “entity” is taken in its broadest sense, referring to whatever artifact a tool may deal with. For example, for a data modeling tool, an “E-R relationship” is a type of entity to ALF.
[Note: ALF Vocabulary Committees will need to enumerate the possible types, but a preliminary list can be found in an Appendix.]
<ObjectID> - An identifier of the entity that changed within a tool. The identifier must be unique for that installation of the tool. It will not be standardized by ALF for use across all tools. The primary purpose is to allow subsequent ServiceFlows to uniquely identify (and perhaps access) the object that triggered the event.
<Source> - A container describing the source of the event
<Product> - A descriptive name for the tool (i.e., program) that emitted the Event.
<ProductVersion>The release version of the product
<ProductInstance>A unique URL identifying the instance of the tool. The tool need not provide a listener at that URL. This is simply used to identify the specific instance of a tool.
A container for a series of logical contexts. The most recent context appears first. Contexts may be nested in the case where an initial event caused a ServiceFlow to be launched and that ServiceFlow launched other ServiceFlows
<Context> - A container for a description of the logical context that was operating at the time the event occurred. An attribute (nesting=) indicates the [N.B. In order to populate the context, the tool must have access to this information.] A tool not operating in the context of a ServiceFlow has a nesting level of 0. Contexts nest (each incrementing the nesting number) as ServiceFlows recursively invoke other ServiceFlows.
<UserCredentials> - This element
contains the security credentials that may be passed among tools that operate as
part of a ServiceFlow. These
credentials are likely to be encrypted. For example, using WS-Security, the
description of how they were encrypted will be specified in the SOAP Header. [Note: The security and SSO aspects of ALF
are still under investigation and the location, format, and contents of the user
credentials may change.]
<InitiatingWorkflow> - An identification of which workflow (if any) and what type of workflow (ServiceFlow or human) the user was engaged in when the event occurred. For example, in the nested workflow situation, where an event has triggered a ServiceFlow which, in turn, invokes a tool that emits an event, it would be useful to record the nested contexts involved.
<InitiatingEventData> - An optional element used in the situation where an Event occurs within the context of a ServiceFlow. This structure identifies the Event that triggered the ServiceFlow.
[Note: Clearly conveying the context
information places a burden on any tool participating in ALF. First, it must be able to know the
credentials of the user. Second,
the initiating workflow (if any) must be communicated from the workflow to the
tool. Vendors and ALF participants: Please provide
feedback..]
The <EventDetails> conveys the detailed information about the object that triggered the event, for example about a file that was checked into a configuration management tool. For the purposes of the BasicEvent, this element will be of type xs:any. That BasicEvent schema can be included in the concrete schema for a particular object type along with any vendor-specific extensions.
**********************************************************************
This email and any files transmitted with it are confidential and intended solely for the use of the individual or entity to whom they are addressed. Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply e-mail and destroy all copies of the original message.