Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 4 Transaction Handling : UDT Functionality

UDT Functionality
User-defined transactions (UDTs) allow you to combine several requests into a single aggregate request. The API Transaction Set processes this aggregate request as a unit, providing transactional integrity at the overall request level.
TIBCO ActiveMatrix Adapter for Kenan/BP uses the Document Object Model (DOM) interface to execute standard API-TS and UDT requests.
A generic UDT service is available with the purchase of the UDT module. Direct parsing allows users to parse the UDT response data in a simple way.
Advantages of Using UDT
User-defined transactions offer the following benefits:
They are fast. It is much faster to combine several requests into one and execute them all at once than to send requests individually, one after the other.
They simplify the process of making requests. It is easier to keep track of related requests when they are grouped within a user-defined transaction. You can even design user-defined transactions that mirror the content of a GUI, so that all of the information on the screen at a given time is sent and processed together.
They maintain transactional integrity at the overall request level. If for some reason one part of a user-defined transaction fails, the entire transaction is rolled back.
UDT Service CustomerUdtRequest and AdminUdtRequest are shipped with the Kenan FX UDT module. You can also customize a UDT Service to perform different transactions, for example, to image a transaction process of a particular GUI screen.
UDT Example
An example snippet of a UDT call is as follows:
<?xml version="1.0" encoding="UTF-8" ?>
<Request xmlns:aruba="ARUBA" xmlns:csg="CSG" xmlns:xsi="xmlSchema">
<Header>
<AccountServer e-dtype="int">3 </AccountServer>
<ApplicationName e-dtype="string">null</ApplicationName>
<OperatorName e-dtype="string">null</OperatorName>
</Header>
<CustomerUdtRequest>
<RequestList e-dtype="list">
<Account>
<AccountGet>
<Account>
<Fetch e-dtype="boolean">true</Fetch>
<Key>
<AccountInternalId e-dtype="int">87</AccountInternalId>
</Key>
</Account>
</AccountGet>
<RequestId e-dtype="string">RootAccount</RequestId>
</Account>
<Account>
<AccountBalanceSummary>
<Account>
<Key>
<AccountInternalId>
<Ref e-dtype="string">RootAccount/Account/Key/AccountInternalId</Ref>
</AccountInternalId>
</Key>
</Account>
</AccountBalanceSummary>
<RequestId e-dtype="string">AccountBalanceSummary1</RequestId>
</Account>
<Nrc>
<NrcFind>
<Nrc>
<Fetch e-dtype="boolean">true</Fetch>
<BillingAccountInternalId>
<Equal>
<Ref e-dtype="string">RootAccount/Account/Key/AccountInternalId</Ref>
</Equal>
</BillingAccountInternalId>
</Nrc>
</NrcFind>
<RequestId e-dtype="string">NrcFind1</RequestId>
</Nrc>
</RequestList>
</CustomerUdtRequest>
</Request>
 
In the above XML block, the following sequence of events take place:
1.
The details for an account with AccountInternalId = 87 is retrieved from the Kenan/BP database.
2.
The AccoutBalanaceSummary is calculated for the same Account.
Here what has to be noted is that the AccountInternalId is given as:
<Ref e-dtype="string">RootAccount/Account/Key/AccountInternalId</Ref> And not as an absolute number.

Moreover, the initial XML block (ref pt. 1) has
<RequestId e-dtype="string">RootAccount</RequestId>.
This means all subsequent references to this account can be made with the RootAccount symbol.
3.
Similarly, the next block finds out the Non-recurring charges for this account. Here too, we see that the BillingAccountInternalId has been equated to
RootAccount/Account/Key/AccountInternalId.
This is an example of UDTs at work. This method of one request accessing variables from another request is also known as the X-Path method. There are several ways to refer to data from other requests of the same UDT call:
Refer to the UDT documentation for more usage details.
Enabling User-Defined Transactions
The generic UDT Service provided by Kenan is called CustomerUdtRequest with a corresponding XSD Schema called CustomerUdtRequest.xsd; the CustomerUdtRequest.xsd file has references to over 60.xsd schema files, so the schema reference for UDT covers all available operations using UDT, and is a fairly large set of.xsd files.
A UDT customization tool is provided to reduce the size of the schema and modify the XSD elements for compatibility with TIBCO Designer XML utilities.
The tool pops up a dialog prompting the user to select objects they need to use in the project. Only the user selection is imported into the project.
The UDT process is majorly composed of two steps: UDT trimming and UDT validation.
The UDT Tool assumes that all XSD files keep the original CSG folder structure. That is because the UDT tool needs to load referred XSD files, and it uses CSG’s folder structure to find the related files.
Using the UDT Tool
You can use the UDT tool from the TIBCO Designer. First set up a basic Kenan Adapter Configuration and follow these steps to use the UDT functionality.
1.
2.
a.
The Source XSD file should be a CustomerUdtRequest.xsd or AdminUdtRequest.xsd provided by Kenan/BP and in the original Kenan/BP folder structure.
b.
c.
d.
e.
Click the Generate button.
Figure 2 Generating the XSD Files
The custom XSD files will be created in the output folder specified. The following files will be generated to the output folder when the source file CustomerUdtRequest.xsd is used:
A Ref XML element is added to request.xsd. This allows the user to construct UDT requests with XPath referencing.
3.
a.
Go back to TIBCO Designer and from the Project menu, select Import Resources from File, Folder, URL..
b.
In the Import Resource or File dialog box, select Folder from the Format drop down menu and browse to select the folder that contains the custom XSD files (the same folder that you specified as output directory when generating the custom XSD files). Click OK.
Figure 3 Import XSD Files
XPath and Element Reference
The XPath language provides a means of navigating to a particular element in an XML document. The portion of the XPath language used in UDTs lets you identify an XML element within a DOM using a path, much like a directory path in a file system.
Within a UDT, each request has a <RequestId> element that gives a unique name to that request. You can use this name (within an XPath path) to access elements from a previous request within that call.
In the Request List, when an element has two operations, and one operation depends on the other, you need a mechanism to create a reference.
To understand this, consider the following example:
1.
Create a request that provides some data for subsequent requests to refer to. For example, use an <AccountGet> call and request the ID for an account (using the <RequestID> element).
2.
Create a subsequent request within the same UDT call that refers to something in the object returned by the first request. For example, an <AccountBalanceSummary> call.
In this case, the second request depends on data received from the first request. The AccountBalanceSummary Call retrieves the balance of the account, which was retrieved in the first request (AccountGet) in the UDT Call.
Steps for Element Reference
To do this, follow these steps:
1.
2.
3.
4.
Click the corresponding content type for that element in the Content column. You will then see the Content type button. Click it and change the Content Type to Mixed.
Figure 4 Element Reference
5.
Figure 5 Insert the Reference
The Ref element is defined in the UDT tool-generated 'request.xsd'. If the new xsd file set has been generated outside of the UDT tool and imported into Business Works, the original request.xsd will not include this Ref element, and Ref will not display.
6.
Click Apply to save changes.
This element can now reference another element.
An Example of a Customized CustomerUDTRequest Schema
Here is an example of a customized CustomerUDTRequest.xsd file, it has fewer referred schema files and a simple structure:
<?xml version = "1.0" encoding = "UTF-8"?>
<!--Generated by Turbo XML. Conforms to w3c http://www.w3.org/2001/XMLSchema-->
<xsd:schema xmlns = "CSG"
targetNamespace = "CSG"
xmlns:xsd = "http://www.w3.org/2001/XMLSchema"
elementFormDefault = "qualified"
attributeFormDefault = "unqualified">
<xsd:include schemaLocation = "Account.xsd"/>
<xsd:include schemaLocation = "AccountBalances.xsd"/>
<xsd:include schemaLocation = "AccountHqContract.xsd"/>
<xsd:include schemaLocation = "AccountId.xsd"/>
<xsd:include schemaLocation = "BalanceLineItem.xsd"/>
<xsd:include schemaLocation = "Nrc.xsd"/>
<xsd:element name = "CustomerUdtRequest">
    <xsd:complexType>
    <xsd:sequence>
    <xsd:element name = "RequestList">
    <xsd:complexType>
<xsd:sequence>
    <xsd:element name = "Account" type = "AccountRequest"/>
    <xsd:element name = "Nrc" type = "NrcRequest"/>
</xsd:sequence>
<xsd:attribute name = "e-dtype" fixed = "list" type = "xsd:string"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:complexType name = "RequestHeader">
<xsd:sequence>
<xsd:element name = "RequestId">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base = "xsd:ID">
<xsd:attribute name = "e-dtype" fixed = "string" type = "xsd:string"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name = "InputRequest" minOccurs = "0">
<xsd:complexType>
<xsd:sequence minOccurs = "0">
<xsd:element name = "RequestId">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base = "xsd:IDREF">
<xsd:attribute name = "e-dtype" fixed = "string" type = "xsd:string"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
<xsd:element name = "RelationshipId" minOccurs = "0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base = "xsd:IDREF">
<xsd:attribute name = "e-dtype" fixed = "string" type = "xsd:string"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name = "AccountRequest">
<xsd:complexContent>
<xsd:extension base = "RequestHeader">
<xsd:sequence minOccurs = "0">
<xsd:element ref = "AccountGet"/>
<xsd:element ref = "AccountBalanceSummary"/>
<xsd:element name = "SubRequest" minOccurs = "0">
<xsd:complexType>
<xsd:sequence maxOccurs = "unbounded">
<xsd:sequence>
<xsd:element name = "RelationshipId" type = "String" fixed = "Nrc_AccountBalances_Ref"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element name = "NrcRequest" minOccurs = "0">
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base = "NrcRequest">
<xsd:sequence>
<xsd:element name = "RelationshipId" type = "String" fixed = "Nrc_Parent"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:schema>
An Example of Customized CustomerUDTResponse Schema
Here is an example of a customized CustomerUDTResponse.xsd file:
 
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="CSG" targetNamespace="CSG" elementFormDefault="qualified" attributeFormDefault="unqualified">
<xsd:include schemaLocation="Account.xsd" />
<xsd:include schemaLocation="Product.xsd" />
<xsd:include schemaLocation="request.xsd" />
<xsd:include schemaLocation="AsyncRequest.xsd" />
<xsd:include schemaLocation="BatchRequest.xsd" />
<xsd:include schemaLocation="BulkOrderRequest.xsd" />
<xsd:element name="UDTResponse">
<xsd:complexType>
<xsd:all>
<xsd:element name="UDTResponseList">
<xsd:complexType>
<xsd:attribute name="list" />
<xsd:choice>
<xsd:element ref="AccountSequenceGetResponse" />
<xsd:element ref="AccountCreateResponse" />
<xsd:element ref="AccountGetResponse" />
<xsd:element ref="AccountExtendedDataFindResponse" />
<xsd:element ref="AccountChildCountResponse" />
<xsd:element ref="AccountFindResponse" />
<xsd:element ref="AccountFindByOrderNumberResponse" />
<xsd:element ref="AccountFindCountResponse" />
<xsd:element ref="AccountUpdateResponse" />
<xsd:element ref="AccountActivateResponse" />
<xsd:element ref="AccountReactivateResponse" />
<xsd:element ref="AccountBalanceSummaryResponse" />
<xsd:element ref="NetworkStatusResponse" />
<xsd:element ref="AccountActiveChildCountResponse" />
<xsd:element ref="AccountFindWithExtendedDataResponse" />
<xsd:element ref="ProductCreateResponse" />
<xsd:element ref="ProductGetResponse" />
<xsd:element ref="ProductAlternateGetResponse" />
<xsd:element ref="ProductExtendedDataFindResponse" />
<xsd:element ref="ProductExternalFindResponse" />
<xsd:element ref="ProductFindResponse" />
<xsd:element ref="ProductUpdateResponse" />
<xsd:element ref="CurrencyDeriveResponse" />
<xsd:element ref="ProductFindWithExtendedDataResponse" />
<xsd:element ref="ProductDisconnectValidateResponse" />
<xsd:element ref="ProductUpdateValidateResponse" />
<xsd:element ref="ProductFindByServiceOrderResponse" />
<xsd:element ref="ProductBillToReevaluateResponse" />
<xsd:element ref="AsyncRequestCreateResponse" />
<xsd:element ref="BatchRequestCancelResponse" />
<xsd:element ref="BatchRequestCancelRunResponse" />
<xsd:element ref="BatchRequestCloseResponse" />
<xsd:element ref="BatchRequestCreateResponse" />
<xsd:element ref="BatchRequestDeleteResponse" />
<xsd:element ref="BatchRequestParticipantDispositionSummaryResponse" />
<xsd:element ref="BatchRequestFindResponse" />
<xsd:element ref="BatchRequestGetResponse" />
<xsd:element ref="BatchRequestReopenResponse" />
<xsd:element ref="BatchRequestRestartResponse" />
<xsd:element ref="BatchRequestResumeResponse" />
<xsd:element ref="BatchRequestResumeAllResponse" />
<xsd:element ref="BatchRequestScheduleResponse" />
<xsd:element ref="BatchRequestSequenceGetResponse" />
<xsd:element ref="BatchRequestSuspendResponse" />
<xsd:element ref="BatchRequestSuspendAllResponse" />
<xsd:element ref="BatchRequestTerminateResponse" />
<xsd:element ref="BatchRequestUnscheduleResponse" />
<xsd:element ref="BatchRequestUpdateResponse" />
<xsd:element ref="BatchRequestWorkSubmitResponse" />
<xsd:element ref="BulkOrderRequestByAccountCreateResponse" />
<xsd:element ref="BulkOrderRequestByAccountGetResponse" />
<xsd:element ref="BulkOrderRequestByAccountUpdateResponse" />
<xsd:element ref="BulkOrderRequestByServiceCreateResponse" />
<xsd:element ref="BulkOrderRequestByServicetGetResponse" />
<xsd:element ref="BulkOrderRequestByServiceUpdateResponse" />
</xsd:choice>
</xsd:complexType>
</xsd:element>
</xsd:all>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Direct Parsing of UDT Response
The following is an example of the original UDT response data from Kenan/BP.
 
<?xml version = '1.0' encoding = 'UTF-8'?>
<Request xmlns="CSG" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Header>
<AccountServer e-dtype="int">3</AccountServer>
<CallCorrelation e-dtype="string">oracle.xml.parser.v2.XMLElement@38717323</CallCorrelation>
</Header>
<UDTResponse>
<UDTResponseList e-dtype="list">
<UDTResponse>
<Account>
<AccountCategory e-dtype="int">2</AccountCategory>
                       ......
                      <VipCode e-dtype="int">0</VipCode>
</Account>
<RequestId e-dtype="string">AccountGet</RequestId>
<RequestObjName e-dtype="string">Account</RequestObjName>
    </UDTResponse>
  <UDTResponse>
<Product>
<ArchFlag e-dtype="boolean">false</ArchFlag>
<AutoActivation e-dtype="int">0</AutoActivation>
                      ......
                     <ViewStatus e-dtype="int">1</ViewStatus>
</Product>
<RequestId e-dtype="string">ProductGet</RequestId>
<RequestObjName e-dtype="string">Product</RequestObjName>
</UDTResponse>
</UDTResponseList>
</UDTResponse>
</Request>
The response result information for each request method is contained in a pair of XML elements: UDTResponse, which are marked in bold.
When the direct parsing function is enabled in TIBCO Designer, the adapter makes some modification to the structure of the original response data to simplify the data parsing process. The following is an example of response data with the direct parsing enabled. The UDT request is exactly the same with the one associated with the above mentioned example.
 
<?xml version = '1.0' encoding = 'UTF-8'?>
<Request xmlns="CSG" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Header>
<AccountServer e-dtype="int">3</AccountServer>
<CallCorrelation e-dtype="string">oracle.xml.parser.v2.XMLElement@58c16b18</CallCorrelation>
</Header>
<UDTResponse>
<UDTResponseList e-dtype="list">
<AccountGetResponse>
<Account>
<AccountCategory e-dtype="int">2</AccountCategory>
<AccountExternalId e-dtype="string">339</AccountExternalId>
                      ......
                     <VipCode e-dtype="int">0</VipCode>
</Account>
<RequestId e-dtype="string">AccountGet</RequestId>
<RequestObjName e-dtype="string">Account</RequestObjName>
</AccountGetResponse>
<ProductGetResponse>
<Product>
<ArchFlag e-dtype="boolean">false</ArchFlag>
                      ......
                      <ViewStatus e-dtype="int">1</ViewStatus>
</Product>
<RequestId e-dtype="string">ProductGet</RequestId>
<RequestObjName e-dtype="string">Product</RequestObjName>
</ProductGetResponse>
</UDTResponseList>
</UDTResponse>
</Request>
The response result information for each request method is contained in a pair of XML elements: ProductGetResponse or AccountGetResponse, which are marked in bold. You can use the response schema (CustomerUdtResponse.xsd) generated by the UDT Tools to parse this response easily using TIBCO ActiveMatrix BusinessWorks. Please refer to TIBCO Adapter for Kenan/BP Example Guide for more information.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved