SAP NetWeaver MDM 7.1

MDM71 Java APIs: Search /
Retrieve MDM Records
Applies to:
The developer community looking forward to utilize the features provided by MDM 7.1 For more information,
visit the Master Data Management homepage.
Summary
MDM 7.1 has come up with some unique features. In the coming series of documents I am trying to cover all
the basic features of MDM71. I would be putting up a series of documents covering all major aspects of
MDM Transactions using Java APIs. The first document of the series MDM71 Java API-Getting Started
covered how to create a trusted user session with MDM. In this section we will talk about how to retrieve
records from MDM repository. The word Retrieve and Search are technically the same and are used in the
same context. We will also see how to add filters to search and how to handle some of the common MDM
datatypes.
Author:
Nitin Mahajan
Company: Infosys Technologies Limited

Created on: 25 June 2009
Author Bio
Nitin is associated with Infosys Technologies for over 6 years now with a vast experience on
Java/J2EE/Enterprise Portal/Java WebDynpro applications and since last 3 years has been a
vital part of the Infosys Enterprise Portal team mainly working in the java WebDynpro/portal
administration / NWDI tracks. For MDM 7.1 Nitin has been working on the ramp up version
since December 2008 and has attended the majority of ramp up customer sessions conducted by SAP.
SAP COMMUNITY NETWORK

2009 SAP AG
SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

1
MDM71 Java APIs: Search / Retrieve MDM Records
Table of Contents
1 Getting a Head Start ....................................................................................... Error! Bookmark not defined.
2 The BASIC functions .......................................................................................................................................4
3 Assumptions ....................................................................................................................................................5
4 Repository Structure ........................................................................................................................................6
5 Retrieve MDM Record .....................................................................................................................................7
5.1 Use Filters in Search.................................................................................................................................8
5.1.1
5.1.2
Filter based on Number of fields .......................................................................................................8

Filter based on a search condition ...............................................................................................................8
5.2 Retrieve Different Data Types.................................................................................................................10

5.2.1
Text Fields..................................................................................................................................................10
5.2.2
Lookup Fields.............................................................................................................................................10
5.2.3
Tuples ........................................................................................................................................................10
5.2.4
MultiTuple...................................................................................................................................................11
5.2.5
Retrieving a Lookup field inside a Tuple / Multituple ..................................................................................11
5.2.6
Make sure you dont forget these ...........................................................................................................12
6 Content to follow ............................................................................................................................................13

Related Content................................................................................................................................................14
Copyright............................................................................................................ Error! Bookmark not defined.

2009 SAP AG

2
1 Getting a Head Start

The basic purpose of any data management tool is to maintain the integrity of the data and MDM is one of
those tools. There are some regular MDM clients available to maintain the data in MDM e.g Data Manager,
MDM Console, Syndication Manager etc., but these clients are more for the administrators and should not be
rather cannot be provided to the end users. To simplify the access, SAP has provided simple and straight
forward Java and ABAP APIs to interact with MDM and allow the programmers to build a user friendly user
interface for the end user to interact with MDM. For the purpose, either Java WebDynpro or ABAP
WebDynpro can be used. The scope of the current document is Java WebDynpro.
What is required to start working on MDM
MDM 7.1 on Oracle/MS SQL
Enterprise Portal 7.0 (I have used Sp15 or above)
Latest MDM Java SCAs that match the MDM7.1 version installed, installed on Portal.
MDM_JAVA_API
BP_MDM_TECH
BP_MDM_APP
Latest MDM java APIs that match the MDM7.1 version installed
mdm-admin.jar
mdm-common.jar
mdm-core.jar
mdm-data.jar
mdm-extension.jar
mdm-protocol.jar
MDM 7.1 on Oracle/MS SQL
Appropriate version of NWDS ( SP14 or higher )

2009 SAP AG

3
2 The BASIC functions

What are the basic functions that MDM would be used for
Create Connection and User Session
Create a record / Tuple
Retrieve / Search MDM Records
Update / Modify a record/Tuple
Delete / remove a record / Tuple
Apart from these, there are some common features that everyone would use once MDM is setup
Check in / Check out a record
Run Matching Strategy
In this document we will talk about how to search on MDM repository and how to use the values returned by
retrieve commands.

2009 SAP AG

4
3 Assumptions
Considering the The user id used to create the connection / interaction is created in MDM and in Portal UME.
One should make sure the user id and password are CASE SENSITIVE in MDM, so please ensure this is
taken care of while creating users. We will have following constants that would be required for a MDM
transaction:
MDM SERVER NAME =
SERVER_NAME
DBMS TYPE
ORACLE
DATABASE SERVER
SERVER_NAME
//assuming db on the same server as mdm
USER ID
USER_ID
MDM System object is created on portal and connection test from portal is successful
Assume Portal System Object name mdm71 and system alias name mdm71alias
Trusted connection is setup between MDM and Portal
Follow MDM security guide to setup Trusted Connection
Taking into consideration the connection and session we created in the document MDM71 Java API-Getting
Started, we will use the values and attributes as generated in it. Here is the list of the output from the
document:
Connection Object
connecPool
Server Session Id
srvSessionId
Region Properties
regionProperties
Repository Identifier
repository
Repository Session Id Repository Schema

User Session Id
repSessionId
-
schema
usrSessionIdAdm
For the examples, we will use Customer Repository with minimum required fields. Our MDM Structure is
following

2009 SAP AG

5
4 Repository Structure
Tables
Table Name
Table Code
Table Type
Customers
Customers
Main
Countries
Countries
Lookup
Tuples
Tuple Name
Tuple Code
Phone Number
Phone_Numbers
Fields in Customers Table (Main Table)

Field Name
Field Code
Field Type
Id
Id
AutoId
Business Name
Business_Name
Text
Country
Country
Lookup
Phone Number
Phone_Number
Tuple
Address
Addresses
MultiTuple
Fields in Country Table

Field Name
Field Code
Field Type
Name
Name
Text
Code
Code
Text
Fields in Phone Number Tuple

Field Name
Field
Field
Code
Type
Phone Number
Number
Text
Extension
Extension
Text
Fields in Address MultiTuple

Field Name
Field Code
Field
Type
Street
Street
Text
ZipCode
Zipcode
Text
Phone Number
Phone_Number
Tuple

2009 SAP AG

6
5 Retrieve MDM Record

There are a couple of commands that have been developed to do a fetch on MDM repository. Let us just
start on how to execute a simple retrieve command.
The simplest and most commonly used command is RetrieveLimitedRecordsCommand. To execute the
command we will use the parameters that we prepared in the earlier documents. MDM71 Java APIGetting Started.doc, as mentioned in assumptions.
As we all know, there are certain mandatory attributes that each command have, let us first prepare those
attributes.
First, we need the TableId of the table on which the search has to be done, in our case this is the main table
Customers. To get the table Id
TableId mainTableId = new TableId(1) ;
we use either an index of the table in the repository or you can use repository schema to get the tableId.
TableId mainTableId = schema.getTable(tableName).getId();
Now we need to create the result definition object.
ResultDefinition definition = new ResultDefinition( mainTableId ) ;
//Since we are doing a simple fetch on whole table on all the records, we are not setting anything in the
search object.
Search search = new Search(mainTableId);
RetrieveLimitedRecordsCommand command =
new RetrieveLimitedRecordsCommand(connecPool);
command.setSession(usrSessionIdAdm);
command.setResultDefinition(definition);
command.setSearch(search);
try {
command.execute();
} catch (Exception e) {
e.printStackTrace();
return ;
}
** Explicitly catch CommandException on execution of any MDM command.
On successful completion, the command object will return the result set.
RecordResultSet recordResultSet = command.getRecords( ) ;
The object RecordResultSet conatains an array of records. To retrieve we will have to
use the appropriate method.
Record[] records = recordResultSet.getRecords() ;
Now you can use the records array to process the data as required.
Or if you know the index of the record or if you loop through the records array,
you can use
Record record = recordResultSet.getRecord(int index);

2009 SAP AG

7
5.1 Use Filters in Search

The retrieved values can be filtered down based on different aspects e.g. one does not want all fields to be
retrieved or some one wants to set a search criterion to the result. All this is possible with MDM.
5.1.1 Filter based on Number of fields
This is possible to do with the result definition (RD). The procedure is to create an array of fieldIds of the
fields that you want to retrieve, or you use the repository schema to set all the fields to the RD.
Lets consider our main table Customers. If we want to retrieve all fields from MDM:
int numOfFields =schema.getTableSchema(tableId).getFields().length;
FieldId fields[]=new FieldId[numOfFields];
FieldProperties[] fieldProperties=schema.getTableSchema(tableId).getFields();
for(int i=0;i<numOfFields;i++){
fields[i]=fieldProperties[i].getId();
}
The object fields would contain all the fieldIds of the table.
Take another example where we want only 2 fields to be part of the result. Say BusinessName and Id:
FieldId fields[] = new FieldId[2] ;
Use the following command to get the fieldId of the field
FieldId fieldId = schema.getField(tableName,fieldCode).getId();
FieldId fiBusinessName = schema.getField(Customers, Business_Name).getId();
FieldId fiId = schema.getField(Customers, Id).getId();
Similarly, if you have more fields you can create a bigger array and use it. You can set the field Ids of any
field type. Now set this array to result Definition
definition.setSelectFields( fields ) ;
This will ensure that only the fields mentioned / included in the result definition are returned as a part of the
record.
5.1.2 Filter based on a search condition
We use filters if we want to add a condition to the search/retrieval. E.g return the customers where Business
name is SAP, or return the customers where Business Name is SAP or INFOSYS. How to do this? Let us
see.
We need a search constraint to implement this requirement. There are certain APIs that are available to build
different type of search constraints and set those to the search object. Here we will use the examples for a
few of those.
Say we want to set a filter, where the returned records are of Customers where Business Name is SAP.
String strBusinessName = "SAP" ;
FieldSearchDimension fsdBusinessName = null;
SearchConstraint scBusinessName = null;
SearchParameter spBusinessName = null;
fsdBusinessName=
new FieldSearchDimension(
schema.getFieldId("Customers", "Business_Name") );
scBusinessName = new TextSearchConstraint(strBusinessName,
TextSearchConstraint.EQUALS);
spBusinessName =
new SearchParameter(fsdBusinessName, scBusinessName );
Search search = new Search(mainTableId);
search.addSearchItem(spBusinessName);

2009 SAP AG

8
This is how you would prepare the search object. Depending on your requirement, you can set the search
constraint to various types
TextSearchConstraint.CONTAINS
TextSearchConstraint.BOOLEAN_SEARCH_CONSTRAINT
TextSearchConstraint.KEYWORD_SEARCH_CONTRAINT
TextSearchConstraint.ENDS_WITH
In the above piece of code, on the flip side, if your requirement is to search
all customers excluding the ones with business name SAP.
Use the following search constraint
TextSearchConstraint.EXCLUDES
To add multiple values to the search, prepare as many searchconstraints and keep
adding to the search object. It is advised to use SearchGroup if the search
constraints are too high.
If your field type on which you want to to filter the record is a lookup table.
Just use the QualifierSearchDimension intead.
The type of search constraint will change based on the data type and not the
field type.
In the methods discussed till now, we have used the example of main table as the search table. It is not that
you can retrieve only on the main table, you can have a search/retrieve done on the lookup tables also using
the same procedure.

2009 SAP AG

9
5.2 Retrieve Different Data Types

Now that we have the records that we wanted to retrieve from MDM, there is still more work involved in
retrieving different data types from the record.
As we all know, MDM accepts only MDMValue to be set into the record. Its the same the other way around,
MDM returns only the MDMValue type when we do a retrieve. We then have to type case the MDMValue
depending on the data type.
5.2.1 Text Fields
This is the simplest and most commonly used data type in MDM and thus simplest to handle. The MDM
Value returned for these fields is of Simple data type String.
FieldId fiBusinessName = schema.getFieldId("Customers", "Business_Name");
Assuming we retrieved an array of records from recordResultset,
String businessName = records[i].getFieldValue(fiBusinessName ).toString( ) ;
For different fields other than lookup, tuple and a multituple, the processing is similar to what is mentioned
above. We will now look into how to retrieve a lookup table value from the main record.
5.2.2 Lookup Fields
Depending upon what you need as part of the lookup table, there are various APIs available.
FieldId fiCountry = schema.getFieldId("Customers", "Country");
If you are just looking for the display value of the lookup table,
String strCountryDisplay = records[i].getLookupDisplayValue() ;
If you are looking for the complete lookup record
Record lookupRecords[] = records[i].findLookupRecords( fiCountry ) ;
Since, the lookup table has only 1:1 mapping, we are sure there is only one record in the array.
Record countryRec = lookupRecords[0] ;
This record can be used to retrieve different attributes of the country record mapped to the main table.
5.2.3 Tuples
The next important field value type is Tuple. We have to bear in mind that the tuple is not just a single value,
it is a complete record in itself. So playing with tuples is very tricky.
Lets see how would I retrieve the Phone Number tuple value from the main table.
FieldId fiPhoneNumber = schema.getFieldId( "Customers", "Phone_Numbers" ) ;
Record[] addRecords = rs.getRecords() ;
TupleValue tvPhoneNum = (TupleValue) records[0].getFieldValue(fiPhoneNumber ) ;
This tuple value can be further used to retrieve different field values.
TupleDefinitionProperties tdpPhNum =
schema.getTupleDefinition( "Phone_Number" ) ;
TupleDefinitionId tdiPhNum = tdpPhNum.getId() ;
TupleDefinitionSchema dfPhNum =
schema.getTupleDefinitionSchema( tdiPhNum ) ;
FieldId fiExtn = dfPhNum.getFieldId( "Extn" ) ;

2009 SAP AG

10
String strExtn = tvPhoneNum.getFieldValue( fiExtn ).toString( ) ;

In case the you want to retrieve a tuple field value which is a lookup field inside the tuple, there are some
additional steps that needs to be done while fetching the records from MDM. We will take this up after
discussing how to retrieve MultiTuple Values from MDM.
5.2.4 MultiTuple
Retrieving multituple is almost similar to retrieving a tuple value. Multituple is nothing but a field type that
allows you to have 1:N mapping of record with tuple values of same type. A multituple contains an array of
tuple values.
This is how one should retrieve a field value from a tuple of multituple field type:
FieldId fiAddress = schema.getFieldId( "Customers", "Addresses" ) ;
Record[] records = rs.getRecords() ;
MultiTupleValue mtvAddress =
(MultiTupleValue) records[0].getFieldValue( fiAddress ) ;
TupleDefinitionProperties tdpAddress =
schema.getTupleDefinition( "Address" ) ;
TupleDefinitionId tdiAddress = tdpAddress.getId() ;
TupleDefinitionSchema dfAddress =
schema.getTupleDefinitionSchema( tdiAddress ) ;
FieldId fiStreet = dfAddress.getFieldId( "Street" ) ;
TupleValue[] tvAddress = mtvAddress.getUntouchTupleRecords() ;
String strStreet = tvAddress[0].getFieldValue( fiStreet ).toString() ;
5.2.5 Retrieving a Lookup field inside a Tuple / Multituple
Incase the requirement involves retrieving a lookup field value where the lookup table is referenced in the
tuple / multituple value, there are some additional steps need to be done at the time of using the retrieve
limited records command.
This requires setting up an array of ResultDefinitions of all the lookup tables to the retrieve command. Since
we have one lookup table, we can assume the size of the array to be 1.
ResultDefinition[] rds = new ResultDefinition[1] ;
As in our case we have a lookup table Country. Create a result definition of the lookup table country
Earlier we saw how to retrieve all fieldIds of a table, use the same logic to get the fieldId array of all fields of
Country table. Assume:
FieldId fiCountries = //array of fieldIds for all fields of country table;
TableId tiCountry = schema.getTableId( "Countries" );
ResultDefinition rdCountry = new ResultDefinition( tiCountry ) ;
rdCountry.setSelectFields( fiCountries ) ;
rds[0] = rdCountry ;
Now set this result definition into the retrieve command as
command.setSupportingResultDefinitions( rds ) ;
If the above part is done at the time of retrieving the records from MDM, the method to retrieve the lookup
values from a tuple / multituple using the following command

2009 SAP AG

11
Record[] lookupRecords = tvValue.findLookupRecords( lookFieldId ) ;

The details of the use of this method are mentioned in Section 5.2.2.
5.2.6 Make sure you dont forget these
Null Pointer checks
Whenever
you
retrieve
value
from
MDM,
check
it
for
MDMValue
Type
NullValue. How to do that?

if (! mdmValueFax.equals (new NullValue ()))
{ }
Common Exceptions
CommandException
ConnectionException
NullPointer
illegalargument

2009 SAP AG

12
6 Content to follow
The next document, we will talk about how to modify and delete a record / tuple value. MDM71 Java APIModify Delete MDM Records.doc.

2009 SAP AG

13
Related Content
http://help.sap.com/javadocs/MDM71/current/API/index.html
For more information, visit the Master Data Management homepage.

2009 SAP AG

14
Disclaimer and Liability Notice

This document may discuss sample coding or other information that does not include SAP official interfaces and therefore is not
supported by SAP. Changes made based on this information are not supported and can be overwritten during an upgrade.
SAP will not be held liable for any damages caused by using or misusing the information, code or methods suggested in this document,
and anyone using these methods does so at his/her own risk.
SAP offers no guarantees and assumes no responsibility or liability of any type with respect to the content of this technical article or
code sample, including any liability resulting from incompatibility between the content within this document and the materials and
services offered by SAP. You agree that you will not hold, or seek to hold, SAP responsible or liable with respect to the content of this
document.

2009 SAP AG

15

SAP NetWeaver MDM 7.1

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SAP NetWeaver MDM 7.1

Uploaded by

Copyright:

Available Formats

MDM71 Java APIs: Search /

Retrieve MDM Records

Company: Infosys Technologies Limited

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

Filter based on Number of fields .......................................................................................................8

5.2 Retrieve Different Data Types.................................................................................................................10

Retrieving a Lookup field inside a Tuple / Multituple ..................................................................................11

Make sure you dont forget these ...........................................................................................................12

6 Content to follow ............................................................................................................................................13

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

1 Getting a Head Start

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

2 The BASIC functions

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

Repository Session Id Repository Schema

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

Fields in Customers Table (Main Table)

Fields in Country Table

Fields in Phone Number Tuple

Fields in Address MultiTuple

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

5 Retrieve MDM Record

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

5.1 Use Filters in Search

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

5.2 Retrieve Different Data Types

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

String strExtn = tvPhoneNum.getFieldValue( fiExtn ).toString( ) ;

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

Record[] lookupRecords = tvValue.findLookupRecords( lookFieldId ) ;

Null Pointer checks

NullValue. How to do that?

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records

SAP COMMUNITY NETWORK

SDN - sdn.sap.com | BPX - bpx.sap.com | BOC - boc.sap.com

MDM71 Java APIs: Search / Retrieve MDM Records