Siebel Connector for IAA-XML

This chapter discusses IAA-XML connector syntax, including methods and arguments for the transformation engine, converter, and dispatcher. It includes the following topics:

IAA-XML Syntax and Rules

IAA-XML is the IBM's messaging architecture standard for the Insurance and Financial Services industry. IAA-XML allows different applications having different data models and running on different technologies to inter-operate. The IAA-XML addresses the deficiency of shared semantic and content structure, lack of shared syntax, and technology dependency in today’s inter-application communications. IAA-XML addresses to the need for content definition for the XML messages. These XML messages can support both business-to-customer and business-to-business message models.

The Siebel Connector for IAA-XML performs both inbound and outbound integration. The IAA-XML architecture defines the architectural elements that can appear in IAA-XML messages, as well as the way in which they relate to each other. These architectural elements describe the organization of data and commands into messages, and include the concepts of message, command, aggregate, aggregate relationship and property. The following example illustrates the layers of an IAA-XML message:

<Message id='Message1' version=’1.4’ bodyType=’IAA-XML’
timeStampCreated='2001-12-14T11:55:04'
sourceLogicalId='Siebel'
destinationLogicalId=’CIIS’
authenticationId='SysAdmin'
crfCmdMode=’alwaysRespond’>
<Default>
	<DefaultTime zoneOffset='00:00'/>
</Default>
<CrfActionGroup bodyCategory=’AddAPerson’>
	<CommandReference refid=’Req1’/>
	<KeyGroup id=’R1’ keyGroupType=’Person’>
		<UUID>1514</UUID>
	</KeyGroup>
	<KeyGroup id=’R2’ keyGroupType=’MailingAddress’>
		<UUID>1652</UUID>
	</KeyGroup>
	<KeyGroup id=’R3’ keyGroupType=’WorkPhoneNumber’>
		<UUID>1665</UUID>
	</KeyGroup>
</CrfActionGroup>
<COMMAND> 
	<AddPartyRequest id=’Req1’ cmdType=’request’ cmdMode=’always Respond’ 
	defaultState=’added’>
<Person>
	<KeyGroup refid=’R1’/>
	<birthDate>1961-08-04</birthDate>
	<deathDate>2001-12-20</deathDate>
	<gender>Male</gender>
	<maritalStatus>Married</maritalStatus>
	<grossIncome>
		<currencyAmount>15000</CurrencyAmount>
		<currencyCode>USD</CurrencyCode>
	</grossIncome>
	<PersonName>
		<usage>Legal</use>
		<firstName>Chris</firstName>
		<lastName>Conway</lastName>
		</PersonName>
		</Person>
		</AddPartyRequest>
</COMMAND>
</Message>

The IAA-XML standard is structured in layers to allow reusing elements and facilitating the processing of the messages. Before defining any content for the messages, it is important to identify the overall structure of the messages and the technical elements that are needed in order to process these messages. Starting from the Interface Design Model (maintained in Rational Rose), it is possible to use a generation script (in Visual Basic) to generate IAA-XML Messages. This script uses not only the UML model but also additional generation directives to get to the precision level required by running code. After the DTD is generated, it can be viewed and processed by standard DTD editors and XML tools.

Note: Siebel Connector for IAA-XML can generate IAA-XML even without generating the IAA-XML header. The header is only required to work with IBM MQSFSE product Suite.

Envelope Section

The Siebel Connector for IAA-XML implements the envelope section of an IAA-XML message through the use of envelope integration object generated by the FINS IAA Wizard. The envelope section contains header information for message management, and authentication. The header also defines default defines default routing and message processing (acknowledgement and publication). The header also contains an action group for each IAA-XML command tied together through an XML reference to a COMMAND element wrapping each IAA-XML command. This allows the MQFSE message hub to deal with each IAA-XML command separately for routing and message response purposes. The envelope section is referred as Message Layer in the IAA-XML Specification. The following is an example of message layer.

<Message id='21FGE620108:13:16' version=’1.4’ bodyType=’IAA-XML’
timeStampCreated='2001-08-22-T23:59:00'
timeStampExpired=’2001-10-24-T23:59:00’
sourceLogicalId='FrontEnd'
authenticationId='SysAdmin'
crfPublish=’false’>
	<Default>
	....
	<Default>
	<CrfActionGroup bodyCategory=’AddAPerson’>
	...
	<CrfActionGroup>
</Message>

Body Section

The Siebel Connector for IAA-XML implements the body section of an IAA-XML message through the use of external integration objects generated by the FINS IAA Wizard. The external integration object, which contains the information about an action and the subject of that action, refers to the Command Layer within the Message Layer of the IAA-XML Message. A body section may contain multiple external integration object instances, which corresponds to heterogeneous commands in a message. Each integration object instance provides enough information about the command for the receiving software to process it accurately. The following is an example of a body section in IAA-XML format.

<COMMAND>
	<ModifyPartyRequest id=’123’ cmdType=’request’>
	<SystemInfo/>…</SystemInfo>
	<Person/>…</Person>
	</ModifyPartyRequest >
</COMMAND>

The external integration components refers to the Aggregate Layer in an IAA-XML message. It provides a convenient way to address groups of properties that are often used together. They also may serve as limiting, functional views of the subjects of the commands. External integration components can be referred to through their key, it can also be defined to represent the return of certain operations. The following is an example of external integration component in IAA-XML format.

<PersonName id=’456’>
	<KeyGroup refid=’R3’/>
	<usage>Legal</usage>
	<firstName>Chris</firstName>
	<lastName>Conway</lastName>
</PersonName>

The external integration component fields refers to the Property Layer which defines the atomic elements of the IAA-XML Message specification. An external integration component field defines a single piece of information that is passed between applications. The format of the information is specified in the integration component field's data type. The definition provided with the property describes more precisely the purpose of this information. External integration component fields can only appear inside an external integration component. The following is an example of external integration component field in IAA-XML format.

<Person>
	<birthDate>1962-11-11</birthDate>
</Person>

Note: For details on IAA-XML Standard and specification, see IBM documentation.

FINS IAA Wizard

Siebel Financial Services application provides different wizards to guide you through building various integration objects for integrating data with external applications. You can access these wizards using Siebel Tools. You should use the Integration Object Builder in Siebel Tools to create new Siebel integration objects. For example, you should use the FINS IAA Wizard within Integration Object Builder to build integration objects for the Siebel Connector for IAA-XML. The Integration Object Builder guides you through the process of building the necessary integration object for your integration project. The Integration Object Builder builds a list of valid components from which you can choose the components to include in your integration object. The following table lists all the user properties for FINS IAA Wizard.

Name	Value	Description
DispatcherMapName	IXMLDispMap	The Dispatch Map Name, wizard will use this map to update the key and value.
HasUIControl	Y or N	Internal Use
Integration Object Wizard	Y or N	Internal Use
Integration Object Base Object Type	Siebel Business Object	Internal Use.
Operation KeyWord Match:X	Key/value	Using this user property wizard can find out the possible transaction operation. For example, if query operation always start with <inquiry***> then this user property is set as follows: Name: Operation KeyWord Match:0 Value: inquiry/IXMLOperation_Query where IXMLOperation_Query is defined in Transaction manager user property
Default Command Tag	COMMAND	Used by the Wizard only. Do not change.
Default Message Tag	Message	Used by the Wizard only. Do not change.

Integration Objects

Siebel integration objects allow you to represent integration metadata for Siebel business objects XML as common structures that the EAI infrastructure can understand. Because these integration objects adhere to a set of structural conventions, they can be traversed and transformed programmatically, using Oracle’s Siebel eScript objects, methods, and functions are transformed declaratively using Siebel Data Mapper. To use the Siebel Connector for IAA-XML to integrate data you need to build three different integration objects.

IAA Envelope Integration Object. The Integration Object that defines the envelope and the header portions of the IAA-XML Message. For details, see Creating IAA Envelope Integration Objects.

IAA External Integration Objects. The integration object that defines the IAA-XML data hierarchy. For details, see Creating IAA External Integration Objects.

IAA Internal Integration Objects. The integration object that defines the Siebel data hierarchy. For details, see Creating IAA Internal Integration Objects.

IAA Dispatcher map

The IAA dispatcher map is created automatically by the FINS IAA Wizard. The IAA dispatcher map serves as rule sets for FINS IAA-XML Dispatcher to identify and associate the IAA-XML message to the external integration objects created. It also indicates the Data Transformation Maps to be used for transforming the messages received. For details, see IAA Dispatcher Map.

FINS IAA-XML Transaction Manager

The FINS IAA-XML Transaction Manager executes operations specified in IAA-XML message instance as Siebel database transactions. It walks through heterogeneous commands and execute transactions and invokes Siebel EAI Adapter or other business services, configured in its user properties, multiple times. The FINS IAA-XML Transaction Manager also translates IAA-XML command elements to Siebel Adapter actions and combines return results as a single property set. The following table lists all the user properties for FINS IAA-XML Transaction Manager.

Name	Value	Description
DispatcherMapName	IAADispMap	Transaction manager uses this map to tag the Body information for other component. This value can be set as a runtime input argument as well.
IgnoreSvcMethodArgs	true or false	This parameter allows runtime input arguments.
SaveInFileForRollback	<filename>	The filename to save current record for future rollback when rollback operation is desired.
SaveInMemForRollback	<filename>	The session key to set or look up the record cached in memory if rollback operation is desired.
XXX (Operation)	ServiceName/MethodName/Argument	Type of operation to use. For details, see Configuring the IAA-XML Business Service.

The FINS IAA-XML Transaction Manager uses the pre-built methods described in the following table to process inbound or outbound.

Name	Display Name	Description
Execute	Execute Transaction	This method can be used for inbound or outbound purpose, as long as the integration object instance is provided. Note that you should use the Execute Outbound method when Row Id is the only available input.
ExecuteOutbound	Execute Outbound	This method can only be used for outbound purpose to execute operation specified in input arguments. See the table of Method Arguments for ExecuteOutbound Method.
ExecuteSave	Execute and Save	This method executes outbound operation specified in input arguments and also saves the transaction into memory or file. See the table of Method Arguments for ExecuteSave Method.

FINS IAA-XML Transaction Manager business service uses combination of user property, method, and method arguments to achieve different tasks. The following table lists all the method arguments available to use with FINS IAA-XML Transaction Manager business service.

Argument	Default Value	Description
OnlyIOI	false	This is only used for Inbound integration. The inbound message may contain header, body, and envelope portion. When Transaction Manager takes the proper operation against the Siebel application, the integration object instances for response is generated as well. All information from the request message is dropped if this value were set to true. Therefore, the FINS IAA-XML Converter and FINS IAA-XML Data Transformation Engine do not need to deal with the overheads. If this is not set to true then request information will still be carried over.
XMLHierarchy	N/A	Property set in internal integration object hierarchy.
IXMLMapPath	N/A	Store the key value for the dispatch map. FINS IAA-XML Transaction Manager will use it to lookup the value, and attach necessary value into integration object instance.
PrimaryRowId	N/A	The PrimaryRowId of the integration object.
SiebelFINSOperationOut	N/A	The outbound operation FINS IAA-XML Transaction Manager takes through its user property.
SearchSpec	N/A	The Search Specification for query.
PlaceToSave	mem	PlaceToSave indicates whether the rollback instance is getting from file or mem. Valid value are "file" or "mem."
RollbackInError	false	Indicates whether the transaction should be rolled back. Valid values are "true" or "false."
ReportErrInMsg	false	Indicates to report error to screen. Valid values are "true" or "false."

Although these arguments are available to be used by FINS IAA-XML Transaction Manager but not all can be used with each method. The following three tables list all the method arguments for each method.

Argument	Display Name	Data Type	Type	Optional
OnlyIOI	Only produce Integration Object Instance	String	Input	Yes
XMLHierarchy	XML Property Set	Hierarchy	Input/Output	Yes

Argument	Display Name	Data Type	Type	Optional
IXMLMapPath	IXML Map Path	String	Input	No
PrimaryRowId	Primary Row Id	String	Input	Yes
SiebelFINSOperationOut	Outbound Operation	String	Input	No
SearchSpec	Search Specification	String	Input	Yes
XMLHierarchy	XML Property Set	Hierarchy	Input/Output	No

Argument	Display Name	Data Type	Type	Optional
IXMLMapPath	IXML Map Path	String	Input	No
PrimaryRowId	Primary Row Id	String	Input	Yes
SiebelFINSOperationOut	Outbound Operation	String	Input	No
SearchSpec	Search Specification	String	Input	Yes
XMLHierarchy	XML Property Set	Hierarchy	Output	No
PlaceToSave	Place To Save	String	Input	Yes

FINS IAA-XML Data Transformation Engine

The Siebel Data Mapper provides you with a declarative interface to specify maps for both inbound and outbound data transformation. The maps you set up using the Siebel Data Mapper call the FINS IAA-XML Data Transformation Engine to complete the data transformation. The FINS IAA-XML Data Transformation Engine both transforms Siebel internal object hierarchy to external integration object hierarchy, defined in IAA-XML DTD, and external integration object hierarchy to Siebel internal integration object hierarchy. The FINS IAA-XML Data Transformation Engine walks through and transform elements in heterogeneous commands and with proper input integration objects and maps it combines results as a single property set. The FINS IAA-XML DTE also removes the empty-valued integration component fields when required. Using the Siebel Data Mapper one can often reduce or even eliminate the number of scripts you need to write.

Note: For details on Siebel Data Mapper and EAI Data Mapping Engine, the base components for FINS IAA-XML Data Transformation Engine, refer to Business Processes and Rules: Siebel Enterprise Application Integration.

Like any other Siebel business service, FINS IAA-XML Data Transformation Engine has specific methods as described in the following table.

Name	Display Name	Description
ToExternal	Transform To External Hierarchy	Transforms Siebel internal integration object hierarchy into the IAA-XML external hierarchy.
ToInternal	Transform To Siebel Hierarchy	Transform IAA-XML external hierarchy into the Siebel internal integration object hierarchy.

FINS IAA-XML Data Transformation Engine business service uses combination of method, and method arguments to achieve different tasks. The following table lists all the method arguments available to use with FINS IAA-XML Data Transformation Engine business service.

Argument	Default Value	Description
XMLHierarchy	N/A	Property set in internal or external integration object hierarchy.
<MapArgs>	N/A	See Business Processes and Rules: Siebel Enterprise Application Integration.

Each method defined for the FINS IAA-XML Data Transformation Engine business service takes some input arguments and produces some output arguments as listed in the following two tables.

Name	Display Name	Data Type	Type	Optional
XMLHierrarchy	XML Property Set	Hierarchy	Input/Output	No
<MapArgs>	-	String	Input	Yes

Name	Display Name	Data Type	Type	Optional
XMLHierrarchy	XML Property Set	Hierarchy	Input/Output	No
<MapArgs>	-	String	Input	Yes

FINS IAA-XML Converter

The FINS IAA-XML Converter provides a way to convert data from the IAA property set to IAA-XML messages for outbound communication, and converts IAA-XML messages received to IAA property set for inbound communication. It iterates through the requests and responses in the message to construct the IBM EID Hub aggregated in the header section. It also constructs the envelope section of the message and data type formatting for fields. The following table lists all the user property for this converter.

Name	Value	Description
EscapeNames	true or false	If set to true, the converter replaces illegal XML name characters with escape characters. Otherwise, it will ignore illegal XML name characters. The default value is true.
HierarchyFormat	XML Hierarchy	Format of the property set input or output. For Internal Use.
XMLEnvIntObjectName	<integration object name>	Name of an integration object that defines the content and hierarchy for the envelope and header section of IAA-XML. The default envelope integration object is "IAA Envelope."

This service provides several ready-to-use-methods as described in the following table.

Methods	Display Name	Description
PropSetToXML	PropSetToXML	Converts an integration object hierarchy to XML string.
PropSetToXMLPropSet	PropSetToXMLPropSet	Converts an integration object hierarchy to XML hierarchy.
XMLToPropSet	XMLToPropSet	Converts an XML string to an integration object hierarchy.
XMLPropSetToPropSet	XMLPropSetToPropSet	Converts an XML hierarchy to an integration object hierarchy.
ErrorHandler	ErrorHandler	Constructs the XML hierarchy to respond to the external systems when undesired operation or configuration errors occurred.

For each method defined the FINS IAA-XML Converter business service takes input arguments and produces output arguments. These arguments are described in the following table.

Argument	Default	Description
XML Document	N/A	XML document streams.
Escape Names	true	Escape characters, invalid XML characters, to be removed or not.
Ignore Character Set Conversion Errors	false	If some characters cannot be represented in destination character set, for example, local codepage, the errors can be ignored.
XML Character Encoding	N/A	XML character encoding to use in the output XML document. If encoding is blank or not supported, errors will be produced.
XML Header Text	N/A	Text to pre-append to the XML document.
XML Hierarchy	N/A	Property Set in external integration object or XML hierarchy.
External Entity Directory	N/A	Location of an external entity files, such as a DTD file.
Validate External Entity	false	If true, the XML parser will validate the document according to the DTD specified in the <DocType> element.
Truncate Field Values	true	truncate field values.
Contains Inline Attachments	true	Indicates the message contains attachment documents.
GereralErrorMessageText	N/A	The general text to be pre-append to the <errorMessageText> element in IAA fault section.
ErrorMessageText	N/A	The actual error text to be set to the <errorMessageText> element in IAA fault section.
ErrorCode	N/A	The actual error code to be set to the <errorCode> element in IAA fault section.
ErrXMLHierarchy	N/A	Input hierarchy will contain the request XML hierarchy to be associated with when generating the respond XML hierarchy. This argument can be ignored. Output hierarchy will contain the XML hierarchy with <ErrorInfo> aggregate generated.

Each FINS IAA-XML Converter method uses group of these method arguments to convert the data for the next service in the integration process. The following five tables display the method arguments for each method.

Name	Default Display Name	Data Type	Type	Optional
<Value>	XML Document	String	Output	Yes
EscapeName	Escape Name	String	Input	Yes
IgnoreCharSetConvErrors	Ignore Character String Set Conversion Errors	String	Input	Yes
XMLCharEncoding	XML Character Encoding	String	Input	Yes
XMLHeaderText	XML Header Text	String	Input	Yes
XMLHierarchy	XML Hierarchy	Hierarchy	Input	No

Name	Default Display Name	Data Type	Type	Optional
XMLHierarchy	<IgnoreEmptyTag>	Hierarchy	Input/Output	No

Name	Default Display Name	Data Type	Type	Optional
<Value>	XML Document	String	Input	No
EscapeName	Escape Name	String	Input	Yes
ExternalEntityDirectory	External Entity Directory	String	Input	Yes
IgnoreCharSetConvErrors	Ignore Character String Set Conversion Errors	String	Input	Yes
ValidateExternalEntity	Validate External Entity	String	Input	Yes
XMLCharEncoding	XML Character Encoding	String	Output	Yes
XMLHierarchy	XML Hierarchy	Hierarchy	Output	Yes

Name	Default Display Name	Data Type	Type	Optional
ContainsInlineAttachments	Contains Inline Attachments	String	Input	Yes
TruncateFieldValues	Truncate Field Values	String	Input	Yes
XMLHierarchy	XML Hierarchy	Hierarchy	Input/Output	No

Name	Default Display Name	Data Type	Type	Optional
GeneralErrorMessageText	General Error Message Text	String	Input	Yes
ErrorMessageText	Error Message Text	String	Input	No
ErrorCode	Error Code	String	Input	No
XMLHierarchy	Err XML Hierarchy	Hierarchy	Input/Output	No

FINS IAA-XML Dispatcher

The FINS IAA-XML Dispatcher is responsible for receiving and dispatching inbound messages. It receives the inbound message and scans the message for any commands specified in its rule sets dispatcher map and associate the integration objects for the connector components. It then parses the envelope of the message and converts it to the header property set and passes both, the integration objects for the specified action, the envelope layer property set and the XML message to the connector components for further processing. The following table lists all the user properties for FINS IAA-XML Dispatcher.

Name	Value	Description
DispatcherMapName	<integration object name>	Name of an integration object that details the dispatching rules and syntax for the IAA-XML standard. This map is usually created along with all the other integration objects by the wizard. The default map name is “IAADispMap".
XMLEnvIntObjectName	<integration object name>	Name of an integration object that defines the content and hierarchy for the envelope and header section of IAA-XML. The default envelope integration object is “IAA Envelope".
XMLFaultObject_O	<path to fault section or element>	This allows dispatcher to identify a fault section with the first token and further confirm it with the value of second token if applicable. Extra fault objects can be added by incrementing the name with _1, _2, and so on. An example for the value for this user property name is XMLFaultObject_1 and value is //IOI/@cmdstatus;fail.

The IAA-XML Dispatcher business service provides ready-to-use methods and method arguments described in the next two tables.

Methods	Display Name	Description
DispatchMessage	Dispatch Message	Validates the incoming XML message. If the message conforms to the dispatching rules, integration object names and other necessary information will be attached. It also checks for the respective envelope, header and fault section of the message and identifies them.

For each method defined the FINS IAA-XML Dispatcher business service takes input arguments and produces output arguments. These arguments are described in the next two tables.

Argument	Default	Description
XML Hierarchy	N/A	Property Set in XML hierarchy.

Name	Display Name	Data Type	Type	Optional
XMLHierarchy	XML Hierarchy	Hierarchy	Input/Output	No

Transport Adapter

Transport Adapter is a pre-built business service providing interface between Siebel application and external applications. Transports allow Siebel Financial Services applications to exchange data with external applications using standard technologies for both synchronous and asynchronous communication protocols.

Transports provide connectivity to virtually any communication protocol that can represent data as text or binary messages, including MQSeries from IBM, MSMQ from Microsoft, and HTTP.

Note: For details on transport adapter, refer to Transports and Interfaces: Siebel Enterprise Application Integration.