Configuring mapping for the IBM Master Data Management migration proxy service

The mapping configuration file (mapping.json) defines the structure and behavior of InfoSphere MDM transactions in the IBM Master Data Management migration proxy service. The proxy mapping file serves as the contract between InfoSphere MDM requests and IBM IBM Master Data Management REST API calls.

The migration proxy service mapping configuration specifies:

  • Transaction parameters that each transaction accepts.
  • Transaction methods that define how the transaction is processed.
  • Record types that are involved in the transaction.
  • Inquiry levels that control what data is returned.
  • Business object (BOb) hierarchy that defines the nested structure of response data.

The content of mapping.json is autogenerated based on InfoSphere MDM metadata.

Mapping configuration structure

The mapping configuration uses a JSON structure where each transaction is defined as a top-level object:

{
  "transactionName": {
    "RequestParams": ["param1", "param2"],
    "Method": "methodType",
    "RecordType": ["$RecordType"],
    "InquiryLevel": { ... }
  }
}

Key elements

Each transaction definition includes the following elements:

  • transactionName: The InfoSphere MDM transaction name (for example, getPerson, addContract)
  • RequestParams: Array of parameter names expected in the request
  • Method: Processing method for this transaction
  • RecordType: Array of IBM Master Data Management record types (prefixed with $)
  • InquiryLevel or TCRMTx: Structure definition that varies by transaction type

Transaction definitions

IBM Master Data Management Master Data Management operations. Each definition must include:

  • Request parameters: Input parameters from the XML request
  • Method: Processing strategy
  • Record type: Target record type or types
  • Structure: Either inquiry levels (for GET and SEARCH transactions) or transaction structure (for ADD and UPDATE transactions)

Record types

Record types identify the IBM Master Data Management record being operated on. Record types must be prefixed with $:

"RecordType": ["$Person"]

For transactions that can operate on multiple record types conditionally:

"RecordType": ["$Person", "$Organization"]

Common record types include:

  • $Person - Person entities
  • $Organization - Organization entities
  • $Contract - Contract entities
  • $Interaction - Interaction entities
  • $Claim - Claim entities
  • $Consent - Consent entities

Transaction types

The migration proxy service supports four primary transaction types: GET, ADD, UPDATE, and SEARCH.

GET transactions

GET transactions retrieve data from IBM Master Data Management. They use inquiry levels to control the depth of data returned.

Structure

"getRecord": {
  "RequestParams": ["RecordId", "InquiryLevel"],
  "Method": "getRecord",
  "RecordType": ["$Record"],
  "CumulativeInquiryLevels": ["0", "1", "2"],
  "InquiryLevel": {
    "Record": {
      "0": { },
      "1": { },
      "2": { }
    }
  }
}

Methods

  • getRecord: Get record or attribute
  • conditionalParty: Get party of unknown type (Organization or Person)
  • getToSearch: Perform a search by request parameters instead of usual get

Key fields

  • CumulativeInquiryLevels: Array that indicates which inquiry levels are cumulative, meaning data at lower levels is included
  • InquiryLevel: Nested object defining data structure at each level

ADD transactions

ADD transactions create new records in IBM Master Data Management.

Structure

"addRecord": {
  "RequestParams": [],
  "Method": "addRecord",
  "RecordType": ["$Record"],
  "TCRMTx": {
    "Record": {
      "0": {
        "TCRMRecordBObj": {
          "TCRMNestedBObj1": {},
          "TCRMNestedBObj2": {}
        }
      }
    }
  }
}

Methods

  • addRecord: Add new record and related objects
  • multiStageAdd: Fetch related data, then add new record or attribute

Key fields

  • TCRMTx: Transaction structure defining expected input hierarchy
  • Nested BObjs define the complete input structure

UPDATE transactions

UPDATE transactions modify existing records.

Structure

"updateRecord": {
  "RequestParams": [],
  "Method": "multiStageUpdate",
  "RecordType": ["$Record"],
  "TCRMTx": {
    "Record": {
      "0": {
        "TCRMRecordBObj": {
          "TCRMNestedBObj1": {},
          "TCRMNestedBObj2": {}
        }
      }
    }
  }
}

Methods

  • updateRecord: Update existing record and all related objects
  • multiStageUpdate: Update existing record or attribute

SEARCH transactions

SEARCH transactions query IBM MDM for matching records.

Structure

"searchRecord": {
  "RequestParams": ["SearchCriteria", "InquiryLevel"],
  "Method": "searchRecord",
  "RecordType": ["$Record"],
  "CumulativeInquiryLevels": ["0", "1"],
  "InquiryLevel": {
    "Record": {
      "0": {
        "TCRMRecordSearchBObj": {
          "TCRMRecordSearchResultBObj": {}
        }
      }
    }
  }
}

Methods

  • searchRecord: Search record by search criteria

Inquiry levels

Inquiry levels control the depth and breadth of data returned in GET and SEARCH transactions. Higher levels typically include more nested objects and relationships.

Cumulative inquiry levels

The CumulativeInquiryLevels array indicates which inquiry levels are cumulative, meaning that the data at lower levels is included in higher levels:

"CumulativeInquiryLevels": ["0", "1", "2", "3", "4"]

Inquiry level structure

Each inquiry level defines a complete business object (BObj) hierarchy:

"InquiryLevel": {
  "RecordName": {
    "0": {
      "TCRMRecordBObj": {
        "TCRMBasicBObj1": {},
        "TCRMBasicBObj2": {}
      }
    },
    "1": {
      "TCRMRecordBObj": {
        "TCRMAdditionalBObj": {
          "TCRMAdditionalBasicBObj1": {}
        }
      }
    }
  }
}

Multiple inquiry level parameters

Some transactions support multiple inquiry level parameters for fine-grained control:

"getContract": {
  "RequestParams": ["ContractId", "ContractInquiryLevel", "PartyInquiryLevel"],
  "Method": "getRecord",
  "RecordType": ["$Contract"],
  "CumulativeInquiryLevels": ["0", "1", "2", "3"],
  "MainInquiryLevel": "ContractInquiryLevel",
  "InquiryLevel": {
    "Contract": {
      "0": { },
      "1": { }
    }
  }
}

Key fields

  • MainInquiryLevel: Specifies which parameter controls the primary inquiry level

Business object hierarchy

Business objects can be nested to represent hierarchical data structures.

Nested structure

Business objects can be nested to represent hierarchical data:

"TCRMPersonBObj": {
  "TCRMPersonNameBObj": {},
  "TCRMPartyAddressBObj": {
    "TCRMAddressBObj": {
      "TCRMAddressValueBObj": {},
      "TCRMAddressNoteBObj": {}
    }
  },
  "TCRMPartyContactMethodBObj": {
    "TCRMContactMethodBObj": {
      "TCRMPhoneNumberBObj": {}
    }
  }
}

Array BObjs

Some business objects represent arrays of data (for example, multiple addresses or names). These are automatically handled as arrays:

"TCRMPersonBObj": {
  "TCRMPersonNameBObj": {},
  "TCRMPartyAddressBObj": {},
  "TCRMPartyIdentificationBObj": {}
}

Special features

Choice directive

The Choice directive enables including hierarchies from other transactions:

"TCRMContractComponentBObj": {
  "TCRMContractPartyRoleBObj": {
    "Choice": ["$getPartyBasic", "$getPerson", "$getOrganization"]
  }
}

The framework determines the record type at runtime and merges results into the parent structure.

Validation rules

Every transaction must have:

  • RequestParams (can be empty array)
  • Method
  • RecordType
  • Either InquiryLevel or TCRMTx (depending on method)

Configuration examples

Example: Simple GET transaction

This example retrieves a person name by party ID and name type. It uses a single inquiry level with a simple structure:

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

Example: Multi-level GET transaction

This example retrieves person data with three inquiry levels:

  • Level 0: Basic person data (names, IDs)
  • Level 1: Adds addresses and contact methods with privacy preferences
  • Level 2: Adds relationships
"getPerson": {
  "RequestParams": ["PartyId", "InquiryLevel"],
  "Method": "getRecord",
  "RecordType": ["$Person"],
  "CumulativeInquiryLevels": ["0", "1", "2"],
  "InquiryLevel": {
    "Person": {
      "0": {
        "TCRMPersonBObj": {
          "TCRMPersonNameBObj": {},
          "TCRMPartyIdentificationBObj": {}
        }
      },
      "1": {
        "TCRMPersonBObj": {
          "TCRMPersonNameBObj": {},
          "TCRMPartyIdentificationBObj": {},
          "TCRMPartyAddressBObj": {
            "TCRMAddressBObj": {
              "TCRMAddressValueBObj": {}
            },
            "TCRMPartyAddressPrivPrefBObj": {
              "TCRMRecordInstancePrivPrefBObj": {}
            }
          },
          "TCRMPartyContactMethodBObj": {
            "TCRMContactMethodBObj": {
              "TCRMPhoneNumberBObj": {}
            }
          }
        }
      },
      "2": {
        "TCRMPersonBObj": {
          "TCRMPersonNameBObj": {},
          "TCRMPartyIdentificationBObj": {},
          "TCRMPartyAddressBObj": {
            "TCRMAddressBObj": {}
          },
          "TCRMPartyContactMethodBObj": {
            "TCRMContactMethodBObj": {}
          },
          "TCRMPartyRelationshipBObj": {}
        }
      }
    }
  }
}

Example: ADD transaction

This example defines the expected input structure for adding a person with addresses, contact methods, names, and identifications:

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

Example: Transaction with Choice

This example retrieves a contract with components. At level 1, it includes party roles and uses Choice to include the hierarchy for the appropriate party type (basic, person, or organization). It supports two inquiry level parameters:

"getContract": {
  "RequestParams": ["ContractId", "ContractInquiryLevel", "PartyInquiryLevel"],
  "Method": "getRecord",
  "RecordType": ["$Contract"],
  "CumulativeInquiryLevels": ["0", "1", "2"],
  "MainInquiryLevel": "ContractInquiryLevel",
  "InquiryLevel": {
    "Contract": {
      "0": {
        "TCRMContractBObj": {
          "TCRMAdminNativeKeyBObj": {}
        }
      },
      "1": {
        "TCRMContractBObj": {
          "TCRMContractComponentBObj": {
            "TCRMContractPartyRoleBObj": {
              "TCRMAlertBObj": {},
              "Choice": ["$getPartyBasic", "$getPerson", "$getOrganization"]
            },
            "TCRMContractComponentValueBObj": {}
          }
        }
      }
    }
  }
}

Learn more