Using the MDM Application Toolkit to build MDM-centric business processes, Part 4: Work with MDM integration services

This is the fourth article in a series that describes how to create process applications for master data by using IBM® Business Process Manager (BPM). Specifically, this series refers to the IBM InfoSphere® Master Data Management (MDM) application toolkit and IBM BPM 8.0.1, both of which are provided with InfoSphere MDM 11.0. This article explores the BPM integration services provided with the Application Toolkit. Learn how these services can help you to create workflows easily that integrate with InfoSphere MDM.

Share:

Tony Garrard (garrard@uk.ibm.com), Senior Software Engineer, IBM Hursley

Tony GarrardTony Garrard, a senior developer currently working on the MDM Application Toolkit, is based at IBM Hursley. He has worked on MDM in various roles since 2006 and has extensive knowledge of MDM, Java EE, Eclipse, web, and test automation technologies. Prior to working on MDM, Tony worked on all of IBM's messaging products from MQ to WebSphere Message Broker. He holds three patents in these subject areas.



26 June 2014

Overview

This article provides guidance on how you can use some of the key IBM InfoSphere MDM integration services in the Application Toolkit. The previous articles in this series explored how to use the core CRUD and search capabilities, the hierarchical tree integration services to retrieve the root node, and how to save the changes to the tree. In this article, learn how to use the remaining integration services to:

  • Call the Physical MDM Txn and MDM inquiry transactions.
  • Call Physical MDM to return the XML response file.
  • Retrieve enumerated data types and code tables.
  • Work with exceptions that are thrown by the integration services.

Prerequisites

This article assumes that you've read the three previous articles in this series and that you are able to create MDM datatypes within BPM. You also need the MDM Transaction guide to work out what transaction, and the type of transaction, that is needed.


Calling the Physical MDM Txn and MDM inquiry transactions

While the Create, Get, Update, Delete, and Search integration services work with physical MDM, there are some limitations due to naming conventions. These integration services work by examining the type of BPM object that is passed in and then determining the MDM business object's name by removing the BObj extension and TCRM prefix, if present. For example, the TCRMPersonBObj becomes Person. The transaction name is then derived depending on the integration service. The Create service prepends “add” so the transaction name used would be addPerson. Similarly, Get, Update, Delete, and Search are prepended for the other relevant integration services. If the transaction in InfoSphere MDM does not follow those naming conventions, you need to use one of the two integration services discussed next.

Physical MDM has two different types of transactions:

  • MDM inquiry transactions, in which you pass in a set of parameters.
  • MDM Txn transactions, in which an MDM business object is supplied.

Figure 1 shows the data mapping for the Physical MDM Txn integration service.

Figure 1. Physical MDM Txn data mapping
A screenshot of the Physical MDM Txn Data Mapping in BPM

Table 1 describes the MDM Txn data mappings.

Table 1. MDM Txn data mappings
Input mappingDescription
MDM connection detailsAn MDM_Connection object that has been configured to point to your MDM server.
MDM transaction nameThe name of the MDM transaction you want to invoke, for example addPerson.
MDM requestThe BPM business object required, for example a TCRMPersonBObj.
MDM transaction controlAn optional MDM_Txn_Control object that is used to help retrieve historical data and is only valid for certain transactions.

The Physical MDM Inquiry integration service is almost identical, except that the MDM request is a list of NameValuePairs. For example, the getPerson inquiry transaction requires that the user supply the parameters PartyId and InquiryLevel.


Calling Physical MDM to return the XML Response

The Physical MDM XML Response service is almost exactly the same as the Physical MDM Txn and Inquiry integration services except that the response is a string that represents the XML of the response object rather than the object itself. The type of the MDM request object determines which integration service is called. For example, if the type is a list of NameValuePairs, the MDM Inquiry integration service is called.

The code in Listing 1 shows how to create an XML document and get to the ResponseObject that is contained within the response using the XPath within a server script node. (tw.local.xmlResponse is a process variable representing the response.)

Listing 1. Create an XML document
// Construct an XML Document given the response string
var doc = new tw.object.XMLDocument(tw.local.xmlResponse);

var response = doc.xpath("/TCRMService/TxResponse/ResponseObject");

There are a few reasons why you might want to use this integration service:

  • If you want to map to your own business objects and do not want to import all the MDM business objects.
  • If you want greater control on what is returned. This is especially true if you're working with MDM subtypes or working within the Physical MDM product domain where the MDM business objects are within an object hierarchy.

Retrieving enumerated data types and code tables

The integration services were created to help you retrieve enumerated data using the Virtual or Physical MDM Get Options integration services. Both integration services return a list of NameValuePairs, which can easily be linked to a select Coach View within your Coach.

For Virtual MDM, the parameters in Table 2 need to be mapped.

Table 2. Virtual Get Options data mappings
Input mappingDescription
MDM connection detailsAn MDM_Connection object that has been configured to point to your MDM server.
Enumerated data typeA string representing the EDT in the virtual model. For example, MARTSTST is the type representing Marital Status.

For Physical MDM, the parameters in Table 3 need to be mapped.

Table 3. Physical Get Options data mappings
Input mappingDescription
MDM connection detailsAn MDM_Connection object that has been configured to point to your MDM server.
MDM Codetable nameThe name of the Physical MDM codetable. For example, CDMARITALSTTP for Marital Status.
LocaleAn optional string representing one of the supported MDM locales to be returned. The string can either be the locale, such as fr, or the language, such as 200. The default is en.
SelectorAn optional NameValuePair, which you can use to change the data that is returned from the response of the CodeTypeBObj. By default, the integration service returns the name and tp_cd as the name and value. By specifying what element in the CodeTypeBObj is the name and what is the value, users can return data more appropriate to their needs.

Working with exceptions thrown by the integration services

All of the integration services may throw exception errors. It is important to determine what these errors are and what remediation or changes to the process flow might be required. To catch the errors thrown from invoking the nested integration service, you need to attach an Error Intermediate Event (the lightning bolt symbol), as shown in Figure 2.

Figure 2. Integration service using an Error Intermediate Event
A screenshot of an example Integration Service using an Error Intermediate Event

Table 4 describes the exceptions thrown by MDM integration services.

Table 4. Exceptions thrown by MDM integration services
ExceptionDescription
MDMBPMConnectionExceptionIs due to an error connecting to the MDM operational server, such as the wrong hostname or authentication details.
MDMBPMConversionExceptionIs thrown if there is an error converting between MDM and TWObjects. This exception is most likely due to a disparity between an object in MDM and an object defined in BPM.
MDMBPMOperationExceptionIs thrown when the request to MDM fails, usually due to invalid data.

All of the exceptions extend the java.lang.Exception, which supplies message and cause, with the attribute in Listing 2.

Listing 2. Extend java.lang.Exception
String reasonCode : The supplied reasonCode for the
failure

The MDMBPMOperationException adds the attribute in Listing 3.

Listing 3. Attribute from MDMBPMOperationException
 ArrayList<MDMBPMResponseMessage> errors : A list of ResponseMessages
                    detailing an error

The MDMBPMResponseMessage includes information in Listing 4.

Listing 4. MDMBPMResponseMessage
errType : The ErrorType (e.g. FVERR)
mdmThrowable : The throwable that MDM made
reasonCode : The MDM reasonCode
errorMessage : The error message associated with the error

In the Server Script node, the error would be made available by accessing tw.system.error, which is an XML element. You would then be able to use XPath to parse the error to retrieve the data needed.

Listing 5 shows an example failure.

Listing 5. Example failure
<error type="mdm.bpm.exceptions.MDMBPMOperationException"
	description="MDMBPMOperationException">
	<cause type="java.lang.Throwable" description="cause"></cause>
	<errors type="java.util.ArrayList" description="ArrayList">
		<element type="mdm.bpm.exceptions.MDMBPMResponseMessage"
			description="MDMBPMResponseMessage">
			<errType type="java.lang.String" description="String">READERR
			</errType>
			<errorMessage type="java.lang.String" description="String">The
				following is not found: Person</errorMessage>
			<mdmThrowable type="java.lang.String" description="String">
			</mdmThrowable>
			<reasonCode type="java.lang.String" description="String">2092
			</reasonCode>
		</element>
	</errors>
...
</error>

To retrieve the MDMBPMResponseMessage, you can use the code in Listing 6 within a Server Script node.

Listing 6. MDMBPMResponseMessage
var err = tw.system.error;
var mdmResponseMessage = err.errors[0].element[0];

You can also retrieve the message by using the XPath, as in Listing 7.

Listing 7. xpath
var msgs = err.xpath("//element[@type='mdm.bpm.exceptions.MDMBPMResponseMessage']");

// Log the error messages found in the errors
for(var i=0; i<msgs.length; i++){
    log.info(msgs.item(i).errorMessage);
}

Hints and tips

If you are struggling to invoke any of the MDM integration services, it might be easier to diagnose the issue by placing a TCP/IP monitor in-between your BPM and MDM server. The monitor is provided with the MDM Workbench that you possibly used to create the MDM BPM business objects. The monitor shows all requests and responses made between BPM and MDM.

When you create your WSDL for Physical MDM, try to reduce the size of your business objects. Also try to include only the attributes you need in your process flow. Careful tailoring of the MDM objects can significantly improve the performance of the integration services. Physical MDM also has highly recursive objects: an object may also include another object of the same type.

Table 5 highlights a few of the available fix packs that might fix certain issues.

Table 5. BPM APARs for recursive objects
APARLinkProblem
JR45937: COACH LOADING FOREVER WHEN OPENED IN THE BROWSER. LOG FILE SHOWS TWCLASS DATE WAS NOT EVALUATED ERRORhttp://www-01.ibm.com/support/docview.wss?uid=swg1JR45937When trying to run a process that should show a coach, the browser tries to load it forever. However the coach is not displayed.
JR45518: BPM PROCESS DESIGNER 8.0.1 CRASHhttp://www-01.ibm.com/support/docview.wss?uid=swg1JR45518If the coach has cycle structure variable or the variable has a deep tree structure, when building the binding data map, it potentially caused Out Of Memory problem.

Conclusion

This article discussed how to use the remaining MDM integration services when developing InfoSphere MDM workflows. For easier error-handling within a process flow, it also covered working with the exceptions that may be thrown by the integration services. The integration services provided with the Application Toolkit help process designers to construct processes easily that integrate with InfoSphere MDM.

Resources

Learn

Get products and technologies

  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, or use a product in a cloud environment.

Discuss

  • Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=975488
ArticleTitle=Using the MDM Application Toolkit to build MDM-centric business processes, Part 4: Work with MDM integration services
publish-date=06262014