XML Representation of Siebel Integration Object Instances

This chapter describes the XML representation of Siebel integration object instances. It includes the following topics:

About Representing Siebel Integration Object Instances as XML Documents

You can represent any integration object instance in Siebel Business Applications as an XML document (or created from a properly formatted XML document). This makes it convenient to save an object to a file for viewing or to send it over a transport, such as HTTP or IBM WebSphere MQ. You can control the format of the XML document through the integration object definition in the Siebel Repository. You can use the EAI XML Converter business service to perform translations between integration object instances and the corresponding XML representation.

Integration Objects

Integration objects are logical representations of Siebel business objects or external application data, such as externally defined XML documents. An integration object is metadata stored in the Siebel Repository. One integration object can be mapped to another integration object. Instances of integration objects are used in integration processes for data exchange. For more information on integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Integration objects are made up of three distinct data sections: the canonical, the external, and the XML, as shown in the following.

The integration object schema in the Siebel Repository is composed of the three data sections shown in the following table.

Table Integration Object Data Type

Name	Purpose
Canonical section	Stores information about an object in a common representation. The names used for objects, components, and fields are the names that the designer wishes to be visible. The data types are the Siebel business component field types that are used by the Object Manager.
External section	Stores information about how the object, component, or field is represented in the external system. For integration objects based on business objects, this can include the business object names, component names, and field names and data types.
XML section	Stores the mapping between an integration object definition and its XML representation. This allows any integration object to be represented as XML.

Elements and Attributes

An XML document consists of one or more elements. An element consists of a start tag and an end tag that enclose character data, nested elements, or both. For example, here is a simple element called Element1, with two tags containing character data:

	<Element1>
		This is character data.
	</Element1>

The next example shows an element nested within another element. Parent-child relationships are frequently represented using nested elements.

	<Element1>
		<NestedElement>
		data
		</NestedElement>
	</Element1>

Elements can have attributes that refine or modify the element’s default attributes. An attribute is a key and value pair of strings, contained within the start tag of an element. In the following example, status is an attribute that is assigned the value test. Attributes are frequently used to specify metadata about an element.

	<Element1 status="test">
		This is character data.
	</Element1>

In the Siebel representation, objects and components are represented by XML elements. A set of integration object instances of a given type are nested within the object element for that type.

An element represents each component. Child components are nested within their parent’s elements. Fields can be either elements nested within their containing component element or attributes of the component element. You can set the XML Style attribute of the integration component field definition to specify which style represents a given field.

How XML Names Are Derived from Integration Objects

When Siebel Tools generates the XML representation of your integration object, it derives the XML element and attribute names from the Siebel Repository names of the integration object, its components, and fields. However, Siebel Repository names can include characters not permitted in an XML name, such as blank spaces. Thus, some translation must be performed to make sure a valid XML name is derived from such a repository name. In addition, XML element names must be unique in the document in which they are defined. This can cause a parsing problem if two integration components have fields with the same name.

To handle these issues, Siebel Tools stores a separate name in the XML Tag attribute of the integration object, component, and field. When you create an integration object using a wizard, the XML Tag attribute is initialized to the value of the Name column, with any illegal characters removed from the name. In addition, Siebel Tools might add a number to the tag name if the same name is already in use by a different object, component, or field. You can change the XML names after the integration object has been created, if necessary.

Elements Within a Siebel Integration Object Document

An integration object can be textually represented as an XML document. In order to exchange data using the Siebel integration object document, you must have an understanding of its XML structure, including elements and attributes. The document can include up to five different types of elements:

Siebel Message Element

When integration object documents are sent to an external system, they might be encapsulated within a SiebelMessage element. This element identifies the document as a Siebel message and indicates that the document includes integration object instances. It can also provide metadata, such as the integration object type and a message ID.

Note: The SiebelMessage element is optional. The presence of this element is determined at run time through arguments to the EAI XML Converter Business Service.

Since the Object List element is optional, SiebelMessage can include a Root component element to allow cases when the Object List element is left blank (omitted). For details on Object List element, see Object List Element.

Attributes

The SiebelMessage element can contain a number of attributes, which are known as the Message Header attributes. In addition, you can add arbitrary attributes to the SiebelMessage element. An XSD or DTD for the document can be dynamically generated inline to include all present attributes. The following standard attributes have well-defined meanings.

Int Object Name

The name of the integration object type contained within the message. If the message is an integration object message, you must specify this property.

MessageId

A unique ID for a given message as it flows through a connector. This is an optional field that might be useful for tracking message processing.

Child Elements

For integration object messages, the SiebelMessage element includes exactly one object list element. Since only one object list element is permitted in each XML document, only one integration object type can be represented in a given document.

Object List Element

The object list element is a container for the integration object instances. The XML Tag attribute value that you specify in the integration object definition becomes the name of this element. By default, an integration object wizard generates an XML Tag value of ListOfName, where Name is the name of the integration object, with any illegal XML characters removed—for example, spaces.

Note: The Object List element is optional. The XML element is not generated if the Object List element is blank (omitted) in the integration object definition.

Attributes

None.

Child Elements

The object list element can include one or more instances of the integration object's root component element. A root component element corresponds to one integration object instance.

Integration Component Elements

An integration component element corresponds to an integration component type in the repository definition.

Component parent-child relationships are represented by a structure in which the child components of a given component type are nested within a component container element. The component container element is, in turn, nested within the parent component instance.

Thus, all components within an integration object instance are indirectly nested within the root component. Only one instance of the root component is allowed for each object instance. The root component is nested within the object list element. The object list element permits multiple integration object instances of a given type within the XML document.

The field children of an integration component element can be either elements or attributes, depending on the XML Style setting for each field. The component container elements of a given component appear after the fields in the XML document.

In the following example, Contact child components are nested within the Account component instance:

	<Account>
	. . . 
	Account Field Elements
	. . . 
		<ListOfContacts>
			<Contact> . . . Contact 1 . . . </Contact>
			<Contact> . . . Contact 2 . . . </Contact>
		</ListOfContacts> 
	<Account>

Attributes

Any field that has an XML Style set to Attribute is an attribute of its component element. The name of the attribute is the same as the XML Tag of the field.

Child Elements

An integration component element can include integration field elements and component container elements. The field elements must appear before the component container elements. The name of a field element is determined by the value of its XML Tag attribute, as defined in Siebel Tools.

Component Container Elements

An integration component container encloses a list of child component instances of the same type. The integration component container organizes child component instances by type and permits the specification of empty containers—functionality needed by the EAI Siebel Adapter. All component types, except the root component, are enclosed within container elements.

By default, the name of a component container element is ListOf plus the element name of the component type it encloses. For example, the component container for Contact is ListOfContact. You can override the default name by specifying a name in the XML Container element field of the component's definition.

Another option is to leave the container element blank. In that case, the component element is the child of the parent component element.

Attributes

None.

Child Elements

Zero or more instances of the component element associated with the container.

Integration Field Elements

An integration field element includes the value of the specified field. It must appear in an instance of its parent integration object type. If a field element has no contents (signified by a start tag immediately followed by an end tag), it is interpreted to mean that the field's value should be set to empty. The same is true when a field’s value is empty; the field element will have a start tag immediately followed by an end tag.

The order in which XML fields appear within their parent component element is determined by the Sequence field in the Tools definition of the field.

All fields are optional. If a field element is not present in a component element, the field is not created in the integration object instance.

Child Elements

Integration component fields have a property called XML Parent Element. If this property contains the name of another field, then that field (either as an attribute or as an element) appears as a child of its parent field’s element.

Example XML Document

The following XML document represents an instance of the Sample Account integration object. This document includes one account instance: A. K. Parker Distribution. The instance has one business address and two contacts.

Note that the PhoneNumber field of the business address appears as an attribute. This means that the XML Style in the field’s definition in Siebel Tools is set to the Attribute style. The rest of the fields are represented by XML elements.

	<SiebelMessage MessageId="" 
	IntObjectName="Sample Account"> 
	<ListofSampleAccount> 
		<Account>
			<Name>A. K. Parker Distribution</Name>
			<Location>HQ-Distribution</Location> 
			<Organization>Siebel Organization</Organization> 
			<Division></Division>
			<CurrencyCode>USD</CurrencyCode> 
			<Description></Description>
			<HomePage></HomePage>
			<ListOfBusinessAddress> 
				<BusinessAddress PhoneNumber="6502955000">
				<City>Menlo Park</City>
				<Country>United States of America</Country>
				<FaxNumber></FaxNumber>
				<StreetAddress>1000 Industrial Way</StreetAddress> 
				<Province></Province>
				<State>CA</State> 
				<PostalCode>94025</PostalCode> 
			</BusinessAddress>
			</ListOfBusinessAddress>
			<ListOfContact> 
				<Contact>
					<FirstName>Stan</FirstName>
					<JobTitle>Senior Mgr of MIS</JobTitle>
					<LastName>Graner</LastName>
					<MiddleName></MiddleName>
					<Organization>Siebel Organization</Organization> 
					<PersonalContact>N</PersonalContact>
				</Contact> 

				<Contact> 
					<FirstName>Susan</FirstName> 
					<JobTitle>President and CEO</JobTitle>
					<LastName>Grant</LastName>
					<MiddleName></MiddleName>
					<Organization>Siebel Organization</Organization>
					<PersonalContact>N</PersonalContact> 
				</Contact> 
			<Contact>
		</ListOfContact>
		</Account>
		</ListofSampleAccount>
		</SiebelMessage>

XML Schema Definitions (XSDs)

The XML Schema Definition (XSD) language describes the content of an XML document. The definition can describe which elements are allowed and how many times the element can be seen. The schema can be used to generate an integration object through Siebel Tools. The feature is accessed through the Integration Object Builder.

Here is an example of an XSD for the Sample Account integration object as generated by Siebel Tools:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://
example.com/xsd/SampleAccount.xsd" xmlns:xsdLocal="http://example.com/xsd/
SampleAccount.xsd" >
<xsd:element name = "elem1" type ="xsd:string" minOccurs ="0" maxOccurs = "1"/>
<xsd:element name = "elem2" type ="xsd:string" minOccurs ="0" maxOccurs="unbounded"/>
</xsd:schema>

Note: All Siebel data types except DTYPE_ATTACHMENT map to xsd:string. DTYPE_ATTACHMENT maps to xsd:base64Binary.

Document Type Definitions (DTDs)

The Document Type Definition (DTD) provides metadata describing the structure of an XML document. It can be used by validating XML parsers to make sure that a given document instance conforms to the expected structure, that is, the structure defined in the DTD.

You can generate the DTD for an integration object by using the Generate Schema feature in Siebel Tools. The feature is activated by clicking the Generate Schema button in Siebel Tools after selecting a given integration object definition.

Note: Attachment attributes are not supported in DTDs because they are not part of the integration object definition and only appear at runtime.

The SiebelMessage element is optional. It can be omitted by selecting the No Envelope option in the Generate XML Schema wizard.

The DTD for the message header is generated in the actual XML document at run-time. The generation of this inline DTD and a reference to the external portion is enabled through the GenerateDTD parameter of the EAI XML Converter.

Here is an example of a DTD for the Sample Account integration object as generated by Siebel Tools:

	<!-- Siebel DTD Generation -->
	<!-- Shared Element List. These elements are guaranteed --> 
	<!-- to have the same datatype, length, precision, and scale.--> 
	<!ELEMENT Name (#PCDATA) > 
	<!ELEMENT Location (#PCDATA) > 
	<!ELEMENT Division (#PCDATA) > 
	<!ELEMENT Description (#PCDATA) > 
	<!ELEMENT CurrencyCode (#PCDATA) > 
	<!ELEMENT StreetAddress (#PCDATA) > 
	<!ELEMENT State (#PCDATA) > 
	<!ELEMENT PostalCode (#PCDATA) > 
	<!ELEMENT Country (#PCDATA) > 
	<!ELEMENT City (#PCDATA) > 
	<!ELEMENT Organization (#PCDATA) > 
	<!ELEMENT ListofSampleAccount (Account+) >
	<!ELEMENT Account (Name?, 
			Location?, 
			Organization?, 
			Division?, 
			CurrencyCode?, 
			Description?, 
			HomePage?, 
			LineofBusiness?, BusinessAddress?, Contact?)>
	<!ELEMENT HomePage (#PCDATA) > 
	<!ELEMENT LineofBusiness (#PCDATA) > 
	<!ELEMENT BusinessAddress (BusinessAddress*) > 
	<!ELEMENT BusinessAddress (City?, 
			Country?, 
			FaxNumber?, 
			StreetAddress?, 
			Province?, 
			State?, 
			PostalCode?)> 
	<!ATTLIST BusinessAddress PhoneNumber CDATA #IMPLIED > 
	<!ELEMENT FaxNumber (#PCDATA) > 
	<!ELEMENT Province (#PCDATA) > 
	<!ELEMENT Contact (Contact*) > 
	<!ELEMENT Contact (CellularPhone?, 
			FirstName?, 
			HomePhone?, 
			JobTitle?, 
			LastName?, 
			MiddleName?, 
			Organization?, 
			PersonalContact?, 
			Account?, 
			AccountLocation?)> 
	<!ELEMENT CellularPhone (#PCDATA) > 
	<!ELEMENT FirstName (#PCDATA) > 
	<!ELEMENT HomePhone (#PCDATA) > 
	<!ELEMENT JobTitle (#PCDATA) > 
	<!ELEMENT LastName (#PCDATA) > 
	<!ELEMENT MiddleName (#PCDATA) > 
	<!ELEMENT PersonalContact (#PCDATA) > 
	<!ELEMENT Account (#PCDATA) > 
	<!ELEMENT AccountLocation (#PCDATA) >

Note: All fields are optional, but if they are present, then they must appear in the correct order. The definition of a field appears only once at the beginning of the DTD, even if its XML tag appears in multiple components. When creating XML tag names for fields, the wizard only reuses a field name if all instances have the same data type, length, precision, and scale.