Subject: Comments on Technical Architecture Specification v1.0
Hello everybody, attached is the list of comments on the TA V1.0 document. Please, do not hesitate to ask me for further clarifications on the comments I made. Also, sometimes I used very "direct" verbs: they are not meant to impose my thinking, but just as a way of writing down. Best regards and congratulations for the document /StefanoTitle:
I would modify the schedule within Chapter 9 as follows:
9.1 Core Components
9.2 Business Process
9.3 Trading Partner
9.4 Message Service
Remove the "object-oriented" reference. "Component-oriented" is enough for the scope of the architecture and XML doesn't prescribe object orientation. In addition, we may think that old-legacy Cobol application could become ebXML-compliant without requiring any OO.
The sentence can read "XML might enable more open, more loosely-coupled, and more component oriented systems than EDI".
Line 251 (and bullet 5 in
I think that this bullet should introduce the name of the CPA as the one which "implements" such arrangements herein described. This would make the further reading more easier by positioning the CPA piece in the context.
Remove the "It SHOULD be noted that". The use of "SHOULD" does not add anything to the meaning of the sentence.
change the full-stop after participation with a semi-colon (-> "...participation; ebXML compliant....")
Line 270, Line 271.
Change the first sentence into the following : "Company A then submits its own Business Profile Information (including implementation details and reference links) to the ebXML Registry".
The items I put in parenthesis (implementation details and reference links) are already the "Business Profile Information" and the way the sentence was previously written implies a duplication.
"...as well as its supported business processes" should be changed into "...as well as its supported business scenarios".
This in order to introduce the "business scenarios" concept that is referenced by a "these" in the next sentence.
It is not clear from this sentence "who and how" verifies the format and the scenarios. I think it should be made clear if it is announced.
Change "...in a business transaction using..." into "...in a business scenario using..."
The sentence "Company B acquires a shrink-wrapped application that is ebXML compliant" should be changed into "Company B acquires an ebXML compliant shrink-wrapped application".
Line 282 thru 284.
Remove the whole sentence starting at "Company A knows..."
This sentence is a repetition of a concept previously between lines 275 and 277.
Typo. "..in that the scenario Company B..." should be "...in that scenario, Company B..."
Remove the end of the sentence "ebXML compliant software interface".
This end-of-sentence implies that there is some automatic negotiation capability in the infrastructure. But this is not specified anywhere else. So, it is misleading.
Remove the end of the sentence "on who it wants to conduct business transactions with Company A".
The end-of-sentence is confusing the reader. The first part of the sentence is enough to understand the idea.
Line 292 thru 294
Remove the end of the sentence starting from "which then triggers..." up to "..(Figure 1, step 5)". The sentence should simply read as "Company A accepts the business agreement."
Again, the part to be removed implies that there is some automatic negotiation capability in the infrastructure. But this is not specified anywhere else. So it is misleading.
Change "..of the ebXML Reference Model is..." into "of the ebXML Architecture Reference Model is...".
Line 326 and 328.
The spacing between the lines is too important. These empty lines should be removed to enhance readability and to be consistent with the rest of the document.
"Service Interfaces.". What is really meant here? Is "Service Interfaces" or "Business Service Interfaces" ?
Anyway, even if they are specified in the Glossary (?) these two terms are very similar and, perhaps, require a better explanation when they are used, at least the first time they are used. Here I do not understand what "Service Interfaces" stands for, what is the meaning.
"User Application interfaces". I do not understand what these interfaces are.
I think it is required a little bit of explanation of what is meant here.
The spacing between the lines is too important. These empty line should be removed to enhance readability and to be consistent with the rest of the document.
Line 379 and 380.
The part "which MAY be accomplished by applying object-oriented principles" should be removed from here and, eventually, added at the end of the paragraph (line 383). It is a "detail" and does not deserve foreground.
Missing comma after ebXML. Should read "In ebXML, interoperability..."
Line 390 Figure 4.
Some comments of this picture.
"Applications" ("internal business application" and "shrink-wrapped application") are pre-existent, they do not get defined at the same time of the ebXML infrastructure. For this reason, the two "Build" arrows in the middle of the figure are out of scope. I would remove them
On the other end, the "Business Service Interface"s need to be built when implementing the ebXML infrastructure. "Build" arrows should point to them
"Register CPP" blocks
and "Retrieval of Profiles..." arrows. It seems that the
CPPs are sent/received automatically by the applications. This
implies automatic negotiation which is not specified anywhere else.
In effect these arrows should not go to the "applications"
but to another box representing "Company A" (an "Company
It is important to distinguish what a "Company X" does (which implies human activity to screen the information) from what the legacy does (which implies the execution of software to properly realize the CPA).
So, I would add the two "Company A" and "Company B" boxes, I would re-direct some arrows as explained before and I would use different line-patterns to distinguish "messaging transfer" which is exploited automatically by the ebXML infrastructure from "human browsing and storing".
Line 390 Figure 4.
The picture does seem too much explained. A lot of focus in the explanation is given to the RegRep, but the picture is dealing with the "Functional Service View" which is more complex and wide than the single RegRep. Some explanation is definitely required here.
Line 395 and 396.
Remove the part of the sentence "is an important part of ebXML.".
Everything is important but, in the context of Figure 4 (which describes the dynamic of implementing the ebXML infrastructure), the RegRep is not at all the most important part.
I would change the lines as follow : "As illustrated in Figure 4 above, the ebXML Registry system serves as the storage facility for the ..."
Line 400 thru 420 (yes, all 21
They should be removed. In the TA document I do not see any need to write a book on GUID/UUID. This is something that will be dealt with by the RegRep Specification. In this context it is not important at all, it does not add anything to the explanation and imposes a "technical implementation" in a context (the technical architecture) which is at a different level.
If really something should be said, it should be "All items stored in the RegRep SHALL be uniquely identified."
Line 421 and 422.
Remove the sentence "A UID reference is ...mechanism."
It is irrelevant (see previous comment).
"...a copy of the ebXML specification".
Specification of what? I think that a Trading Partner may require the "Business Process" definitions of the BPs referenced by some other partner's CPP... Saying "specification" is too generic here.
"..studies the ebXML specification...".
See previous comment. Which specifications are we talking about ?
The part in parenthesis "(stored in it business profile)" should be changed into "(stored in their business profiles)"
The following part of the sentence "...system and a Business Service Interface" should be changed into "...system and a Trading Partner".
The use of "Business Service Interface" implies some automatic negotiation capability in the ebXML infrastructure that is not defined anywhere else.
Change the box "ebXML Business Service Interface (Application)" with a box labelled "Trading Partner" (see previous comment).
Line 466 and 467.
The first sentence of the paragraph should read as follows: "A Trading Partner can now begin the process of discovery and retrieval (Figure 6 below).".
I have removed the reference to the "Business Service Interface" since, used in this context, implies automatic negotiation, which is not specified anywhere else.
Line 469, 470 and 471.
The whole sentence staring at "Requests for updates..." until "...by and ebXML Application" should be removed. The sentence implies that the Business Service Interface is able to automatically talk to the ebXML RegRep and that is able to take initiatives autonomously. This is not specified anywhere else and, thus, is misleading.
What I think is to be said, is that the ebXML RegRep should support such functionalities (update, create etc), not the Business Service Interface nor the ebXML Application.
The two boxes labelled "ebXML Business Service Interface (Application)" should be labelled "Trading Partner" instead. Otherwise there is the assumption of automatic negotiation. See previous comment.
Line 481, 482 and 483.
The sentence "If it becomes necessary..." until "...Discovery and Retrieval Phase." should be removed.
There is no need to use the RegRep at runtime or, at least, it has never been specified anywhere else. This is misleading.
In the explanation of such Figure (which is missing...) I would try to make sure that 2 words are spent on the choreography of the exchange. An ebXML CPA is a choreographed set of Commercial Transactions which are linked together by a well-defined choreography and not only by the TR&P layer. The risk of not properly insisting on this is that customers will understand that ebXML is about "one off" messages.
The reference to "Business Service Interface" should, in reality, be to the "Messaging Service".
Paragraph between line 502 and
Whilst the previous paragraph (494-500) deals with the CPP, this one should deal with the CPA. Actually, a part from the difference in the acronym (CPA instead than CPP) this paragraph looks too much like the previous one and seems a repetition. It would be necessary to exploit the specificity of the CPA here.
The reference to the "Service Interface" is not clear. What is really meant by "service interface" in the context of this sentence?
The sentence "Each Trading Partner SHALL register one and..." is too restrictive. Each partner may register more than one CPP (think to big organizations where each department may register a different CPP...).
Paragraph between Line 519 and
It seems to be a duplication of the previous paragraph (line 511 thru 517), but I think this paragraph is better written and more clear than the previous one. So, my suggestion is to chose between the two paragraphs and not to include both.
The reference "(2) the Business Process (application) requirements...". Why "application" ? The Business Process may be realized by interfacing to existing applications, but I do not think that the Business Process "is the application".
Line 530 to 555 (yes, all of
that including the Figure 8 and Figure 9).
I would move all of this section into a new section (9.1.2 Conceptual View) and position it immediately after the introduction.
The "3 level view of the CPA" is drawn but is not explained. I mean, in these 3 layers, where is the CPA, where is the CPP ? Also, what does "possibility" mean as opposed to "Capability"? This is well defined in the CPA documents, but here is shown without any explanation.
Paragraph 9.1.4 (CPP
This paragraph should be moved, at position 9.1.3 (i.e. In section 9.1, first all CPP related stuff are described, then all CPA related).
Remove "Business Process:" from the beginning of the line
Change "The CPP must be ..." into "The CPP MUST be ..."
Change "The CPP must also reference..." into "The CPP MUST also reference..."
Change "...that BP that the user is capable..." into "...a Business Process tha the Partner is capable..."
Change "The CPP must be ..." into "The CPP MUST be..."
Line 562 and 563.
This whole sentence seems to imply that the CPP should be able to reference the CPA. But this is not possible since the CPP comes before the CPA and, perhaps, independently of it. It also introduce a circular dependency (the CPA should be able to reference the CPP...)
Change "The CPP must be.." into "The CPP MUST be .."
Change "The CPP must be.." into "The CPP MUST be .."
Line 568 and 569.
The sentence "A CPP may also describe binding details that are used to build an ebXML message header." what does it mean? I think that if the meaning is that the CPP should describe which lower-level protocol is to be used and which security constraints should apply, then this should be more clearly stated (perhaps with a little narrative example)
Paragraph 9.1.5 (CPA
This paragraph should be moved, at position 9.1.4 (i.e. In section 9.1, first all CPP related stuff are described, then all CPA related).
Line 573 and 574.
What is the meaning of this sentence? Which is this "software component" that is referenced in the sentence?
Lines 576 thru 579.
This paragraph is a very complex explanation of the Figure 8. It should not appear here (as mentioned before) and should be more readable than this.
The end of the sentence "...with other Trading Partners in shared Business Processes." should be changed into "...with other Trading Partners in shared collaborations.". The use of "Business Process" is repeated in the sentence and a BP cannot describe a BP...
The end of the sentence ", messaging and security considerations." should be removed. It is perhaps true that the physical protocol and the security adds something to the choreography, but this is a technical detail. The choreography is mainly defined by the BP.
Line 647 thru 650.
The sentence includes a contraddiction. It reads as follows. "No language is mandated, but if one is used it should be UML", i.e. "either you do not speak or if you speak you should speak english".
Lines 658, 662, 666 and 667.
All the "SHALL" should be changed into "is". This is NOT a requirement document, it is the explanation of the Technical Architecture. The TA is based on things that have been already specified.
"May reference supporting Metadata" should be changed into "References to supporting Metadata"
Line 675 thru 677.
The last 3 bullets are, logically, part of a different bulleted list because they do not deal qwith "types of information" (as the initial 4 bullets) but with the capabilities of the BP.
Line 705, 706 and 707
The sentence "The mechanism for interfacing..." until "... GUID for each component." should be removed.
The TA document is not the place for implementation details such as UID/GUID.
The two "Registry mechanism" should actually be "Registry instance"
Line 717 and 718
The last part of the sentence, from "and therefore each.." to the end should be removed.
The TA document is not the place for implementation details such as UID/GUID.
Line 831, 832 and 833
The idea behind the use of UID and GUID should be expressed in a different form, by avoiding mentioning explicitely UID and GUID.
The part of the sentence "..., and describe each registered item,..." should be replaced by "..., and describe it, ..."
The "Registry Client" should be replaced by "Registry Interface". The human interaction is built on the Registry interface and is, by itself, a Registry Client !
The "Registry interface" should be "Registry Interface" (italics)
Line 849 and
The "Registry Client" should be "Registry Client" (italics)
Remove "SHALL". The messages have already been defined, this is not a requirement document.
Remove "MAY". I do not think that there is any other place where BP and CC can be registered...
Remove "MAY". It has been said in the previous line that these services MAY be deferred... so there is no need to reiterate the use of MAY.
Line 906 and
The discussion of GUID/UID is not pertinent to the TA document.
thru 912 (all the Registry part).
No mention is made here on the "Repository Information Model" which is an important and distinctive part of the RegRep. A couple of words, a little paragraph on this ?
Change "shall PROVIDE" into "provides". It is a statement, it does not need to be reinforced nor this is a requirement document.
946, 948, 951, 954, 957 (twice), 961, 991 and 995.
All "SHALL" should be removed. This is not a requirement document and the TR&P has well defined all of the things herein mentioned.
Line 948 and
The sentence "It SHALL also utilize and..." until "...(CPA)." should be removed. The same concept is expressed, in a more clear way, later (line 961 and following)
The "MAY be packaged" should be changed into "is packaged".
There is no more decision here, the discussion and decision has been taken. It is not a requirement document.
The word "SHALL" should be removed. Again, there is no more discussion on this, the specs are well on their road and the TA is not a requirement document.
Attached is also a new version of Appendix A, with correct (hope so) wording for the TPA and with correct indentiation of bulleted lists.
eList eXpress LLC