Implementing a custom query transaction
MDM Server provides several hundred transactions to query and modify master data. If you have a business requirement for a query that is not provided by any of the existing transactions and is not possible to achieve the requirement by customizing any of the existing transactions using the mechanisms supported by MDM Server, it may be appropriate to implement a new query transaction.
This might be because you have extended the MDM Server data model to support new types of record or because you need to query a combination of records not supported by any existing transaction.
To implement a new query transaction:
- Understand the requirements
- Design the transaction interface
- Decide how the transaction will be implemented
- Use the MDM Server Workbench to generate skeleton code for the transaction
- Customize the generated code to meet the requirements
- Deploy and test the new transaction
MDM Server supports two styles of transaction interfaces: Inquiry and Txn. This choice affects the format of the transaction request message and the way the transaction is implemented.
An Inquiry-style transaction accepts a number of string arguments, defined as a fixed set of named parameters.
An example of such a transaction is
getPerson using an XML over RMI message, the
request XML looks like this:
getPersonRMI XML request
<TCRMService xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" \ xsi:noNamespaceSchemaLocation="myTCRM.xsd"> <RequestControl> <requestID>100181</requestID> <DWLControl> <requesterName>cusadmin</requesterName> <requesterLanguage>100</requesterLanguage> </DWLControl> </RequestControl> <TCRMInquiry> <InquiryType>getPerson</InquiryType> <InquiryParam> <tcrmParam name="partyId">871122346130007978</tcrmParam> <tcrmParam name="InquiryLevel">0</tcrmParam> </InquiryParam> </TCRMInquiry> </TCRMService>
The parameters are
partyId (the primary key of the
party to return) and
InquiryLevel, which indicates
the amount of detail to return.
getPerson using the web service interface,
with the same values, the request message looks like Listing 2 (omitting
the SOAP envelope).
Listing 2. getPerson web service XML request
<q0:GetPerson> <control> <requestId>100181</requestId> <requesterName>cusadmin</requesterName> <requesterLanguage>100</requesterLanguage> </control> <partyId>871122346130007978</partyId> <inquiryLevel>0</inquiryLevel> </q0:GetPerson>
The Inquiry style should only be used for queries with a small number of parameters, where you will not be likely to modify the interface frequently. In general, the Txn style is considered best practice for new transactions. A Txn-style transaction accepts a single request object that defines the transaction parameters. The request object can have as many fields as required, including nested child objects.
An example of such a transaction is
searchPerson. To invoke
searchPerson using an XML over RMI message,
the request XML might look like Listing 3.
searchPersonRMI XML request
<TCRMService xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" \ xsi:noNamespaceSchemaLocation="myTCRM.xsd"> <RequestControl> <requestID>92345</requestID> <DWLControl> <requesterName>cusadmin</requesterName> <requesterLanguage>100</requesterLanguage> </DWLControl> </RequestControl> <TCRMTx> <TCRMTxType>searchPerson</TCRMTxType> <TCRMTxObject>TCRMPersonSearchBObj</TCRMTxObject> <TCRMObject> <TCRMPersonSearchBObj> <GivenNameOne>Jane</GivenNameOne> <LastName>Smith</LastName> </TCRMPersonSearchBObj> </TCRMObject> </TCRMTx> </TCRMService>
searchPerson using the web service interface, with the same
values, the request message would look like Listing 4 (omitting the SOAP
searchPersonweb service XML request
<q0:SearchPerson> <control> <requestId>92345</requestId> <requesterName>cusadmin</requesterName> <requesterLanguage>100</requesterLanguage> </control> <personSearch> <givenNameOne>Jane</givenNameOne> <lastName>Smith</lastName> </personSearch> </q0:SearchPerson>
The Inquiry-style interface is only used for query transactions, while the Txn-style interface is always used for transactions that add and modify master data records and can also be used for queries.
MDM Server supports two ways of implementing a transaction: as a Business Proxy class or as a Component method. Which you choose is not dependent on the interface style.
To understand the difference, a brief introduction to the architecture of the MDM Server transaction framework is required. The framework has three distinct layers, each of which can contribute to the implementation of a transaction.
Figure 1. Transaction processing layers
An MDM Server transaction like
addPerson is implemented by a Controller
class, which in turn calls one or more Component classes. When you call
addPerson, by default, the base MDM Server Business Proxy class is used
and it just delegates the transaction execution to the Party
Controller class. It is possible to customize the behavior of the
addPerson transaction by providing your own custom Business Proxy
class and associating it with
To implement a custom transaction, you can contribute a new Business Proxy class or new Controller and Component classes (you would never do both).
A Business Proxy class can include whatever Java code you like and also invoke other transactions at the Controller level. It should never directly call Component classes.
Component and Controller classes have methods corresponding to
transactions and usually the Controller method just calls an
equivalent Component method. For custom transactions implemented
this way, you should ignore the Controller class and not add custom
code to it so that the Controller and Component methods behave exactly
the same way. Note that this cannot be assumed for MDM Server
transactions; you will see different behavior from the Component-level
addPerson method from that of the
Component methods can include whatever Java code you like and also call other Component methods.
The most common way of implementing a new transaction is as a Business Proxy. A Business Proxy is used to implement new transactions that mainly need to call existing MDM Server transactions, perhaps modifying the request or response. A Business Proxy is implemented in a single Java class.
An example of a situation where a Business Proxy would be the best way to implement a new query is where you can get the required function by calling existing transactions and combining the results into a single combined response.
For example, you might want to look up a party record and also return
associated party demographics data, using the transactions
The Component method implementation style actually means providing Controller and Component classes, but the transaction behavior is coded in a method in the Component class. This style is appropriate when the transaction implementation is closely related to your data model extensions or you want to call the new transaction from a behavior extension or other Component transaction. Implementation at the Component level allows you to make use of the MDM Server framework to implement the query, and although this style requires more Java classes, the workbench will generate all the skeleton code for you. You may then need to edit the generated classes to add the logic for the new query. In some situations, either approach could be used, in which case, use whichever seems most appropriate or easiest to implement. The following sections will include examples of both approaches.