This section
provides an easy introduction to the message layout (the "XML
structure" of the document) and introduces some conventions which will be
valid throughout the RSI XML interface.
XML
(Extensible Markup Language) is a "meta language", which allows the
definition of your own languages. It uses tags to give the pure text in
a message a special meaning. Lets look at one example, which shows in which way
address information could be marked up in XML:
<Address>
<Name> Bill C. </Name>
<Street> John F. K. Avenue 33 </Street>
<PostCode> 111-22344 </PostCode>
<City> L.A. </City>
</Address>
One example
tells more then thousand words?! So what do you see? You see that all data is
included in tags . We call them opening tags (e.g. <Name>
)
and closing tags (e.g. </Name>).
In the above example the Address field does not contain pure data itself. It is
used in a way of a container , where we put the name, street, postcode
and city data with the purpose to structure the information.
There are
lots of tools, which support XML in several ways. For example it is easy to
check, if every opening tag is closed. If this is the case, we say a XML
document is well-conformed .
Please
notice, that XML is case sensitive .
For example,
if our message above would contain a name element like <name>
Bill C. </Name> , the message will not be well conformed.
The second
possibility which comes with XML is to define your own language. Why is this
important? Remember our purpose to exchange shipment data. We have to speak the
same language to ensure that sender and receiver give tags the same meaning. RSI
defines a set of tags/elements, which are described within this document.
The technical
part of the language definition is stored in a DTD (Document Type
Definition). The DTD describes, which tags are allowed, in which order they
can appear, whether elements can be repeated and so on.
The
connection between the XML document and the DTD is made within the XML document
by a line like
<!DOCTYPE Interface SYSTEM "interface-v1-2.dtd">
XML Documents which fulfil the requirements of a DTD are called valid . RSI expects the XML-documents to be valid according to the following specification.
In the
following chapter we describe the RSI Interface layout. As already
shown in the little XML example above, we made rich usage of structuring the
information by using containers .
You can see
the structure of the message as a tree or graph. This means elements have
sub-elements ( children, content ) and elements in which they are
included ( parents ). In the next chapter we give a detailed overview
of all possible message elements. Each element appears in one section, where its
content is described, an example is given and its parents are listed.
Last but not
least please notice some remarks on the names of the elements: all elements
begin with a capital letter, followed by small letters. If element names are
concatenated of two or more words, every new word is appended directly with a
capital letter.
Example: CityCode,
CountryName
Throughout
this description the terms element, segment, tag are used synonymous.
All elements
are mandatory, if they are not explicitly declared optional.
Through the
years RSI made a lot of experience exchanging many kinds of data. In our opinion
Email is the easiest way for transferring the data.
We expect the
XML document in the body of the Email-message.
If you
purpose to send an update, please send the whole message again with a new (that
means also a higher) Message
identification number.
As you have
already seen in the introducing examples in this chapter, a XML document is
something like a tree (this is a technical term, which is used in the computer
science to describe a special kind of data structure. This structure has parent
- children relationships, this means, you have exactly one root element the
father/mother of all elements. Then you can define recursively, that all
elements can have one, or more children. Elements with no children are called
leaf.) Remember the address example above, where we have an address container,
which includes other elements, some/none/all of this elements can contain other
elements and so on.
How do we
describe this structure in this document?
We choosed a
way to present this structure, which is best viewed in the html-format which is
suupported by any kind of (web) browser (e.g. Netscapee, MS Internet Explora,
Opera, ...). Each element we used appears in its own section inside this
document, all elements are on the same level, which means we do not display
the hierachy of the message elements by document structure (like putting an
element which belongs to one container, in a kind of subsection). This was not
possible, because some elements appears in different contexts.
So what we
did is to show the parents and the children of each element as (hypertext)
links. According to this we recommend to read the next chapter in a way of
jumping from link to link, which is easier than reading the message from the top
to the bottom! So you should read it like this:
In this
section I will just store some ideas. Use it or skip this section! You are a
programmer and your task is to enable your customer to exchange messages in this
XML format. There will be a few points you have to do:
In my opinion
this is the easiest part. The tree-structure of the XML message allows you to
produce a message in a way like:
{main program
.
.
.
call procedure for the Interface element
.
.
.
end main program}
//*************************************************
procedure Inteface {
write opening-tag
call procedure for Header
for all shipments and tracking events
if (...)
call procedure for Shipment
else
call procedure for TrackingEvent
endif
endfor
write closing-tag
}
//*************************************************
procedure Header {
write opening-tag
call procedure for Sender
call procedure for Receiver
call procedure for MessageId
write closing-tag
}
//*************************************************
.
.
.
This part
depends very strong on your inhouse system. In which way is the data stored?
Which programming environment is used?
I just want
to give one hint: check out the WEB for XML-resources for your environment.
There are quite a lot of useful tools which support rich support for XML data,
especially in JAVA, even in C++.
If you have
already an existing inhouse interface, you can also check out other
possibilities to get the data in your system: transfer the XML-documtent to your
inhouse-interface format. There exists a kind of script language called XSLT
(extensible stylesheet transformation), which could support you.