Configuring additional InfoSphere MDM transactions for the migration proxy service

Configure additional InfoSphere MDM transactions to integrate with the IBM Master Data Management migration proxy service. The proxy service provides a compatibility layer between InfoSphere MDM and IBM Master Data Management, enabling organizations to maintain existing integrations while downstream systems transition to the new platform.

Before you begin

Before you configure a new transaction, identify the following characteristics:

Transaction type: Determine whether the transaction is GET, SEARCH, ADD, or UPDATE.
Record types: Identify which IBM Master Data Management record types are involved (for example, Person, Organization, or Contract).
Complexity: Assess whether the transaction requires multi-domain processing, such as fetching related records or relationships.
Request parameters: Document the parameters that the transaction accepts.

Configuration files overview

Depending on the transaction type and complexity, you might need to configure up to four files:

mapping.json: Defines transaction structure and business object hierarchy (required for all transactions)
query_logic_config.json: Specifies multi-stage query logic (optional, for complex transactions)
properties.json: Defines business object properties and relationships
XML templates: Provide field-level mappings

For more information about these files, see the related topics in the Learn more section at the end of this topic.

Configuring transaction definitions in mapping.json

The mapping.json file defines the structure and processing method for each transaction. This configuration is typically autogenerated. For more information about generation and schema details, see Configuring mapping for the migration proxy service.

Selecting a transaction method

Choose the appropriate method value based on your transaction type and use case:

Transaction methods
Transaction type	Method value	Use case
GET (simple)	`getRecord`	Get a record by ID
GET (conditional)	`conditionalParty`	Get a party of unknown type (Person or Organization)
GET (search-based)	`getToSearch`	Get a record by using search instead of ID lookup
SEARCH	`searchRecord`	Search for records that match criteria
ADD (simple)	`addRecord`	Add a new record
ADD (multi-stage)	`multiStageAdd`	Add an attribute to an existing record (requires pre-fetch)
UPDATE (simple)	`updateRecord`	Update an existing record with pre-fetch logic defined in query logic configuration
UPDATE (multi-stage)	`multiStageUpdate`	Update with pre-fetch logic

If a transaction is configured in query_logic_config.json, the query logic runs first. If the query logic execution fails, the system falls back to default processing by using the method value that is specified in mapping.json. This fallback mechanism provides a safety net for complex transactions while maintaining backward compatibility.

Defining transaction structure for GET and SEARCH transactions

For transactions that retrieve data with inquiry levels, use the following schema structure:

{
  "transactionName": {
    "RequestParams": ["param1", "param2", "InquiryLevel"],
    "Method": "getRecord",
    "RecordType": ["$RecordType"],
    "CumulativeInquiryLevels": ["0", "1", "2"],
    "MainInquiryLevel": "InquiryLevel",
    "InquiryLevel": {
      "RecordName": {
        "0": {
          "TCRMRecordBObj": {
            "TCRMNestedBObj1": {},
            "TCRMNestedBObj2": {}
          }
        },
        "1": {
          "TCRMRecordBObj": {
            "TCRMAdditionalBObj": {
              "TCRMDeeplyNestedBObj": {}
            }
          }
        }
      }
    }
  }
}

Example: GET transaction with inquiry levels

The following example shows a getPerson transaction that retrieves person data at different inquiry levels:

{
  "getPerson": {
    "RequestParams": ["PartyId", "InquiryLevel"],
    "Method": "getRecord",
    "RecordType": ["$Person"],
    "CumulativeInquiryLevels": ["0", "1", "2"],
    "InquiryLevel": {
      "Person": {
        "0": {
          "TCRMPersonBObj": {
            "TCRMPersonNameBObj": {},
            "TCRMPartyIdentificationBObj": {}
          }
        },
        "1": {
          "TCRMPersonBObj": {
            "TCRMPartyAddressBObj": {
              "TCRMAddressBObj": {},
              "TCRMPartyAddressPrivPrefBObj": {}
            }
          }
        },
        "2": {
          "TCRMPersonBObj": {
            "TCRMPartyRelationshipBObj": {}
          }
        }
      }
    }
  }
}

Defining transaction structure for ADD and UPDATE transactions

For transactions that create or modify data, use the following schema structure:

{
  "transactionName": {
    "RequestParams": [],
    "Method": "addRecord|multiStageAdd|updateRecord|multiStageUpdate",
    "RecordType": ["$RecordType"],
    "TCRMTx": {
      "RecordName": {
        "0": {
          "TCRMRecordBObj": {
            "TCRMNestedBObj1": {},
            "TCRMNestedBObj2": {
              "TCRMDeeplyNestedBObj": {}
            }
          }
        }
      }
    }
  }
}

Example: ADD transaction

The following example shows an addPerson transaction that creates a new person record with addresses and contact methods:

{
  "addPerson": {
    "RequestParams": [],
    "Method": "addRecord",
    "RecordType": ["$Person"],
    "TCRMTx": {
      "Person": {
        "0": {
          "TCRMPersonBObj": {
            "TCRMPersonNameBObj": {},
            "TCRMPartyAddressBObj": {
              "TCRMAddressBObj": {
                "TCRMAddressValueBObj": {}
              }
            },
            "TCRMPartyContactMethodBObj": {
              "TCRMContactMethodBObj": {
                "TCRMPhoneNumberBObj": {}
              }
            },
            "TCRMPartyIdentificationBObj": {}
          }
        }
      }
    }
  }
}

Configuring query logic (optional)

Add query logic configuration when your transaction requires any of the following capabilities:

Converting an InfoSphere MDM GET operation to an IBM Master Data Management search when parameters do not include a record or relationship ID
Returning data from multiple records or relationships (multi-domain transactions) by converting the request to composite calls to IBM Master Data Management
Implementing custom processing scenarios

For more information and working examples, see Configuring query logic for the migration proxy service.

Example: Multi-level GET with query logic

The following example shows a getPerson transaction that retrieves person data with privacy preferences at higher inquiry levels.

Configuration in mapping.json:

{
  "getPerson": {
    "RequestParams": ["PartyId", "InquiryLevel"],
    "Method": "getRecord",
    "RecordType": ["$Person"],
    "CumulativeInquiryLevels": ["0", "1", "2"],
    "InquiryLevel": {
      "Person": {
        "0": {
          "TCRMPersonBObj": {
            "TCRMPersonNameBObj": {},
            "TCRMPartyIdentificationBObj": {}
          }
        },
        "1": {
          "TCRMPersonBObj": {
            "TCRMPartyAddressBObj": {
              "TCRMAddressBObj": {},
              "TCRMPartyAddressPrivPrefBObj": {
                "TCRMRecordInstancePrivPrefBObj": {}
              }
            }
          }
        }
      }
    }
  }
}

Configuration in query_logic_config.json:

{
  "getPerson": [
    {
      "condition": "#transaction.getParams().get('InquiryLevel') == 0",
      "logicName": "queryPersonBasic",
      "stages": [
        {
          "action": "get",
          "content": {
            "identifier": "person",
            "logicType": "getById",
            "idSource": "#transaction.getParams().get('PartyId')"
          }
        }
      ]
    },
    {
      "condition": "#transaction.getParams().get('InquiryLevel') > 0",
      "logicName": "queryPersonWithPrivacyPreferences",
      "stages": [
        {
          "action": "composite",
          "content": {
            "requests": [
              {
                "identifier": "person",
                "logicType": "getById",
                "idSource": "#transaction.getParams().get('PartyId')"
              }
            ],
            "for-each": {
              "select": "'$.responses[?(@.request_id == ' + #requestContext.getRequestNode('person').getRequestId() + ')].response.record.attributes.[\"tcrm_party_address_b_obj\"]..attribute_id as attr_id'",
              "requests": [
                {
                  "identifier": "personPrivPrefs",
                  "logicType": "search",
                  "searchBy": [
                    {
                      "property": "priv_pref_instance_p_k.value",
                      "value": "'{$.variables.attr_id}'"
                    }
                  ],
                  "condition": "equal"
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

When InquiryLevel is 0, the query logic retrieves only the person record. When InquiryLevel is greater than 0, the query logic retrieves the person record and searches for privacy preferences for each tcrm_party_address_b_obj attribute.

Example: Multi-stage UPDATE transaction

The following example shows an updatePerson transaction that updates a person record after fetching existing data, including relationships and related records.

Configuration in mapping.json:

{
  "updatePerson": {
    "RequestParams": [],
    "Method": "updateRecord",
    "RecordType": ["$Person"],
    "TCRMTx": {
      "Person": {
        "0": {
          "TCRMPersonBObj": {
            "TCRMPersonNameBObj": {},
            "TCRMPersonBObj": {
              "TCRMPartyAddressBObj": {
                "TCRMAddressBObj": {
                  "TCRMAddressValueBObj": {},
                  "TCRMAddressNoteBObj": {}
                },
                "TCRMPartyAddressPrivPrefBObj": {
                  "TCRMEntityInstancePrivPrefBObj": {}
                }
              }
            }
          }
        }
      }
    }
  }
}

Configuration in query_logic_config.json:

{
  "updatePerson": [
    {
      "condition": "true",
      "logicName": "queryPersonWithRelationships",
      "stages": [
        {
          "action": "composite",
          "content": {
            "requests": [
              {
                "identifier": "person",
                "logicType": "getById",
                "idSource": "#transaction.getParams().remove('record_id')"
              },
              {
                "identifier": "personRelationships",
                "logicType": "getRelationships",
                "relationshipPath": "'{$.responses[?(@.request_id == ' + #requestContext.getRequestNode('person').getRequestId() + ')].response.record.id}'"
              },
              "for-each": {
                "select": "'$.responses[?(@.request_id == ' + #requestContext.getRequestNode('person').getRequestId() + ')].response.record.attributes.[\"tcrm_party_contact_method_b_obj\",\"tcrm_party_address_b_obj\"]..attribute_id as attr_id'",
                "requests": [
                  {
                    "identifier": "personPrivPrefs",
                    "logicType": "search",
                    "searchBy": [
                      {
                        "property": "priv_pref_instance_p_k.value",
                        "value": "'{$.variables.attr_id}'"
                      }
                    ],
                    "condition": "equal"
                  }
                ]
              }
            ]
          }
        },
        {
          "action": "update",
          "content": {}
        }
      ]
    }
  ]
}

The first stage queries the person record by ID, retrieves relationships, and searches for related records for each tcrm_party_contact_method_b_obj and tcrm_party_address_b_obj attribute. The second stage performs the update operation.

Transaction configuration examples

The following examples demonstrate common transaction configuration patterns.

Simple GET transaction

The following example retrieves a person name by party ID and name type. No query logic is needed because simple GET operations are handled automatically.

{
  "getPersonName": {
    "RequestParams": ["PartyId", "NameUsageType"],
    "Method": "getRecord",
    "RecordType": ["$Person"],
    "InquiryLevel": {
      "PersonName": {
        "0": {
          "TCRMPersonNameBObj": {}
        }
      }
    }
  }
}

SEARCH transaction

The following example searches for persons with optional details. No query logic is needed because search operations are handled automatically.

{
  "searchPerson": {
    "RequestParams": ["SearchCriteria", "InquiryLevel"],
    "Method": "searchRecord",
    "RecordType": ["$Person"],
    "CumulativeInquiryLevels": ["0", "1"],
    "InquiryLevel": {
      "Person": {
        "0": {
          "TCRMPersonSearchBObj": {
            "TCRMPersonSearchResultBObj": {}
          }
        },
        "1": {
          "TCRMPersonSearchBObj": {
            "TCRMPersonSearchResultBObj": {
              "TCRMPersonNameBObj": {},
              "TCRMPartyAddressBObj": {
                "TCRMAddressBObj": {}
              }
            }
          }
        }
      }
    }
  }
}

ADD transaction

The following example adds a new person with addresses and contact methods. No query logic is needed because ADD operations are handled automatically. The proxy service detects related records and relationships and converts the ADD operation to a composite ADD operation.

{
  "addPerson": {
    "RequestParams": [],
    "Method": "addRecord",
    "RecordType": ["$Person"],
    "TCRMTx": {
      "Person": {
        "0": {
          "TCRMPersonBObj": {
            "TCRMPersonNameBObj": {},
            "TCRMPartyAddressBObj": {
              "TCRMAddressBObj": {
                "TCRMAddressValueBObj": {}
              }
            },
            "TCRMPartyContactMethodBObj": {
              "TCRMContactMethodBObj": {
                "TCRMPhoneNumberBObj": {}
              }
            },
            "TCRMPartyIdentificationBObj": {}
          }
        }
      }
    }
  }
}