Technical Blog Post
Abstract
MDM AE pMDM with RESTful web services
Body
MDM AE pMDM with RESTful web services
New in MDM v11.4 is the ability to submit REST requests to the service controller.
No more complex SOAP client code, or worst EJB remote calls!
Previously, interactions with MDM Operational server were possible with EJB/RMI, JMS, JAX-WS and JAX-RPC(deprecated). We have now added JAX-RS to the mix.
Possible payloads that are accepted are application/xml and application/json. JSON support was added in v11.4 FP1.
It is important to note that all REST interaction are using one RESTful service “MDMWSRESTful”, PUT method type only and accessed via URI http://server:port/com.ibm.mdm.server.ws.restful/resources/MDMWSRESTful.
The same xml request/response payload used for EJB/RMI is used for REST interactions.
ASI (Adaptive Service Interface) can be used in conjunction with the RESTful service. This is particularly useful if a simplified XML/JSON structure is required for interactions or if the MDM solution must adapt to a certain XML industry standard such as IFW, ACCORD, and NIEM.
For the full list of capabilities and supported request headers consult the following documentation link:
Interacting with MDMRESTful service
Using Apache Wink (or any other REST client api of choice), you can with minimal code submit a request to the MDM Hub Operational Server
Here’s a sample client leveraging Apache Wink demonstrating an MDM RESTful call:
ClientConfig config = new ClientConfig();
// setup basic authentication
BasicAuthSecurityHandler basicAuthHandler = new BasicAuthSecurityHandler();
basicAuthHandler.setUserName("mdmadmin");
basicAuthHandler.setPassword("mdmadmin");
basicAuthHandler.setSSLRequired(false);
config.handlers(basicAuthHandler);
RestClient rc = new RestClient(config);
Resource r = rc.resource("http://myserver.com:9080/com.ibm.mdm.server.ws.restful/resources/MDMWSR…;);
// optional MDM headers
r.header("TargetApplication", "");
r.header("RequestType", "");
r.header("Parser", "");
r.header("ResponseType", "");
r.header("Constructor", "");
r.header("OperationType", "");
r.header("ASI_Request", "");
r.header("ASI_Response", "");
// submit put request of the xml payload.
String response = r.contentType("application/xml")
.accept("application/xml")
.put(String.class, requestPayload);
The above code will submitting an MDM xml payload and expecting back an xml response.
This is determined by the ‘Content-type’ and ‘Accept’ http header properties.
Here’s a look at a getParty xml payload and response:
Request XML:
<TCRMService xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.ibm.com/mdm/schema"
xsi:schemaLocation="http://www.ibm.com/mdm/schema MDMDomains.xsd">
<RequestControl>
<requestID>100187</requestID>
<DWLControl>
<requesterName>cusadmin</requesterName>
<requesterLocale>en</requesterLocale>
</DWLControl>
</RequestControl>
<TCRMInquiry>
<InquiryType>getParty</InquiryType>
<InquiryParam>
<tcrmParam name="PartyId">1</tcrmParam>
<tcrmParam name="PartyType">P</tcrmParam>
<tcrmParam name="InquiryLevel">1</tcrmParam>
</InquiryParam>
</TCRMInquiry>
</TCRMService>
Response XML (portion of the response has been trimmed):
<TCRMService
xmlns="http://www.ibm.com/mdm/schema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ibm.com/mdm/schema MDMDomains.xsd">
<ResponseControl>
<ResultCode>SUCCESS</ResultCode>
<ServiceTime>123</ServiceTime>
<DWLControl>
<requesterName>mdmadmin</requesterName>
<requesterLanguage>100</requesterLanguage>
<requesterLocale>en</requesterLocale>
<userRole>mdm_admin</userRole>
<requestID>100187</requestID>
</DWLControl>
</ResponseControl>
<TxResponse>
<RequestType>getParty</RequestType>
<TxResult>
<ResultCode>SUCCESS</ResultCode>
</TxResult>
<ResponseObject>
<TCRMPersonBObj>
<PartyId>1</PartyId>
<DisplayName>Jane Doh</DisplayName>
…
<DWLStatus>
<Status>0</Status>
</DWLStatus>
</TCRMPersonBObj>
</ResponseObject>
</TxResponse>
</TCRMService>
The same request/response as JSON, using application/json, as both content-type and accept:
Request JSON:
{
"TCRMService": {
"@schemaLocation": "http:\/\/www.ibm.com\/mdm\/schema MDMDomains.xsd",
"RequestControl": {
"requestID": 604157,
"DWLControl": {
"requesterName": "cusadmin",
"requesterLocale": "en"
}
},
"TCRMInquiry": {
"InquiryType": "getParty",
"InquiryParam": {
"tcrmParam": [{
"@name": "PartyId",
"$": "1"
},
{
"@name": "PartyType",
"$": "P"
},
{
"@name": "InquiryLevel",
"$": "1"
}]
}
}
}
}
Response JSON (full response is shown):
{
"TCRMService": {
"@schemaLocation": "http://www.ibm.com/mdm/schema MDMDomains.xsd",
"ResponseControl": {
"ResultCode": "SUCCESS",
"ServiceTime": "86",
"DWLControl": {
"requesterName": "mdmadmin",
"requesterLanguage": "100",
"requesterLocale": "en",
"userRole": "mdm_admin",
"requestID": "604157"
}
},
"TxResponse": {
"RequestType": "getParty",
"TxResult": {
"ResultCode": "SUCCESS"
},
"ResponseObject": {
"TCRMPersonBObj": {
"PartyId": "1",
"DisplayName": "Jane Doh",
"PreferredLanguageType": "100",
"PreferredLanguageValue": "English",
"ComputerAccessType": "1",
"ComputerAccessValue": "14.4K Baud",
"PartyType": "P",
"CreatedDate": "2015-09-10 15:16:47.583",
"SinceDate": "2015-09-10 00:00:00.0",
"StatementFrequencyType": "1",
"StatementFrequencyValue": "Annually",
"ClientStatusType": "1",
"ClientStatusValue": "Active",
"AlertIndicator": "N",
"SolicitationIndicator": "N",
"ConfidentialIndicator": "N",
"ClientPotentialType": "1",
"ClientPotentialValue": "Client",
"ClientImportanceType": "4",
"ClientImportanceValue": "Medium",
"DoNotDeleteIndicator": "1",
"PartyLastUpdateDate": "2015-09-10 15:16:50.138",
"PartyLastUpdateUser": "mdmadmin",
"PartyLastUpdateTxId": "616244191260573356",
"PersonPartyId": "1",
"BirthDate": "1966-08-25 00:00:00.0",
"BirthPlaceType": "1",
"BirthPlaceValue": "Afghanistan",
"GenderType": "M",
"UserIndicator": "N",
"AgeVerifiedWithType": "2",
"AgeVerifiedWithValue": "Passport",
"HighestEducationType": "5",
"HighestEducationValue": "Master Degree",
"CitizenshipType": "1",
"CitizenshipValue": "Afghanistan",
"NumberOfChildren": "3",
"MaritalStatusType": "2",
"MaritalStatusValue": "Single",
"PartyActiveIndicator": "Y",
"PersonLastUpdateDate": "2015-09-10 15:16:50.31",
"PersonLastUpdateUser": "mdmadmin",
"PersonLastUpdateTxId": "616244191260573356",
"TCRMPartyAddressBObj": [
{
"PartyAddressIdPK": "826144191261145264",
"PartyId": "1",
"AddressId": "828144191261121794",
"AddressUsageType": "1",
"AddressUsageValue": "Primary Residence",
"StartDate": "2001-06-11 00:00:00.0",
"AddressGroupLastUpdateDate": "2015-09-10 15:16:51.591",
"AddressGroupLastUpdateUser": "mdmadmin",
"AddressGroupLastUpdateTxId": "616244191260573356",
"LocationGroupLastUpdateDate": "2015-09-10 15:16:51.451",
"LocationGroupLastUpdateUser": "mdmadmin",
"LocationGroupLastUpdateTxId": "616244191260573356",
"TCRMAddressBObj": {
"AddressIdPK": "828144191261121794",
"ResidenceType": "2",
"ResidenceValue": "Detached House",
"AddressLineOne": "120 Richmond St",
"City": "Toronto",
"ZipPostalCode": "M5A 1P4",
"ResidenceNumber": "789",
"ProvinceStateType": "108",
"ProvinceStateValue": "ON",
"CountyCode": "1",
"CountryType": "31",
"CountryValue": "Canada",
"LatitudeDegrees": "180",
"LongitudeDegrees": "90",
"AddressLastUpdateDate": "2015-09-10 15:16:51.216",
"AddressLastUpdateUser": "mdmadmin",
"AddressLastUpdateTxId": "616244191260573356",
"DWLStatus": {
"Status": "0"
}
},
"DWLStatus": {
"Status": "0"
}
}
],
"TCRMPartyIdentificationBObj": [
{
"IdentificationIdPK": "826744191261084265",
"PartyId": "1",
"IdentificationType": "1",
"IdentificationValue": "Social Security Number",
"IdentificationNumber": "1245",
"IdentificationStatusType": "2",
"IdentificationStatusValue": "Active",
"IdentificationExpiryDate": "2005-08-11 23:59:59.0",
"StartDate": "2002-02-02 00:00:00.0",
"PartyIdentificationLastUpdateDate": "2015-09-10 15:16:50.841",
"PartyIdentificationLastUpdateUser": "mdmadmin",
"PartyIdentificationLastUpdateTxId": "616244191260573356",
"DWLStatus": {
"Status": "0"
}
}
],
"TCRMPersonNameBObj": [
{
"PersonNameIdPK": "822844191261056191",
"NameUsageType": "1",
"NameUsageValue": "Legal",
"PrefixType": "12",
"PrefixValue": "Miss",
"GivenNameOne": "Jane",
"StdGivenNameOne": "JANE",
"LastName": "Doh",
"StdLastName": "DOH",
"PersonPartyId": "1",
"StartDate": "2002-02-02 00:00:00.0",
"PersonNameLastUpdateDate": "2015-09-10 15:16:50.56",
"PersonNameLastUpdateUser": "mdmadmin",
"PersonNameLastUpdateTxId": "616244191260573356",
"LastUpdatedBy": "mdmadmin",
"LastUpdatedDate": "2015-09-10 15:16:50.56",
"DWLStatus": {
"Status": "0"
}
}
],
"DWLStatus": {
"Status": "0"
}
}
}
}
}
}
How does MDM handle the JSON requests/responses?
The default MDM JSON model is actually based on the core XML schema model (MDMCommon.xsd and MDMDomains.xsd). Internally, MDM will validate the JSON using these schemas.
We use a “Mapped notation” api to build the JSON. A couple things to note about this implementation:
- XML elements that contain nested elements will be mapped to JSON objects (ie. <TCRMPersonBObj> will be "TCRMPersonBObj": { … })
- XML element values will be mapped to a JSON name/value pair (ie. <GivenNameOne>Jane</GivenNameOne> will be "GivenNameOne": "Jane")
- XML element attributes become JSON name/value pairs within the JSON object. (ie. <tcrmParam name="PartyId">1</tcrmParam> will be "tcrmParam": { "@name": "PartyId", "$": "1" }) Note the attribute is prefix with “@”. The xml element value will be mapped to the name/value pair using the name “$”. The “@” and “$” characters are used to distinguish the attribute value from the element’s value.
- XML array elements, an XML document which contains multiple nested elements of the same name will automatically be mapped to a JSON array. (ie.
<TCRMPersonNameBObj>
<PersonNameIdPK>822844191261056191</PersonNameIdPK>
<NameUsageType>1</NameUsageType>
...
</TCRMPersonNameBObj>
<TCRMPersonNameBObj>
<PersonNameIdPK>821544198626606646</PersonNameIdPK>
<NameUsageType>2</NameUsageType>
...
</TCRMPersonNameBObj> will be
"TCRMPersonNameBObj": [ {
"PersonNameIdPK": "822844191261056191",
"NameUsageType": "1",
...
},
{
"PersonNameIdPK": "821544198626606646",
"NameUsageType": "2",
...
}] )
There are instances where we need to force the return of a JSON array. This is the case for list type elements in MDM or results which include multiple elements. To control this behavior, you can set the elements which need to be forced as JSON array using the Configuration Management element “/IBM/DWLCommonServices/Restful/JsonResponse/ArrayObjects” (comma separated value list).
Don’t want to write any code to test your MDM services?
Using Firefox/Chrome POSTMAN REST client extension, you can submit your requests directly to the backend server securely.
Enter REST URL as http://localhost:9080/com.ibm.mdm.server.ws.restful/resources/MDMWSRESTful
Choose “PUT” as the HTTP method
Set headers: Content-Type and Accept to either application/xml or application/json
Set authorization by supplying credentials using Basic Auth tab.
Another great tool is SOAPUI. This tool can be used to fully automate your functional and regression testing by submitting REST requests. For more info on this tool visit http://www.soapui.org/.
Another option is using cURL (http://curl.haxx.se/)
cURL is a cmd line tool for transferring data using a URL syntax.
curl --user "mdmadmin:mdmadmin" -X PUT
-H "Content-Type: application/xml"
-H "Accept: application/xml"
-d @getParty.xml "http://localhost:9080/com.ibm.mdm.server.ws.restful/resources/MDMWSREST…;
UID
ibm11142206