Configuring properties for the IBM Master Data Management migration proxy service

The properties configuration file (properties.json) defines the behavioral characteristics and relationships of business objects (BObjs) in the migration proxy. The properties configuration complements the mapping configuration by specifying how objects are named, filtered, matched, and correlated during request and response processing.

The migration proxy service properties configuration specifies:

  • Nested object names that map BObjs to IBM Master Data Management type names.
  • Type selectors that filter arrays by specific types.
  • Matching keys that correlate related records during XML response building.
  • Correlation paths that establish parent-child relationships during IBM Master Data Management request creation.
  • Array selectors that filter search result arrays.
  • Object kinds that classify BObjs as records or relationships.

Most of the content of properties.json is autogenerated based on InfoSphere MDM metadata.

Configuration structure

The properties configuration uses a JSON structure where each business object (BObj) is defined as a top-level object:

{
  "TCRMBobjName": {
    "nestedBObjName": "ibm_mdm_type_name",
    "TypeField": "json.path.to.type.field",
    "matchingKeys": [ ... ],
    "correlationPaths": { ... },
    "arraySelectors": { ... },
    "kind": "record|relationship"
  }
}

Key elements

Each business object definition includes the following elements:

  • BObj Name: Key matching the business object name
  • nestedBObjName: IBM Master Data Management type name for this business object (required)
  • Type Selectors: Fields used to filter arrays by type
  • matchingKeys: Array defining how to match related records during XML response building
  • correlationPaths: Object defining parent-child correlations during IBM Master Data Management request creation
  • arraySelectors: Object defining search result filtering
  • kind: Classification as "record" or "relationship"

Nested object names

The nestedBObjName property maps an InfoSphere MDM business object name to its equivalent IBM Master Data Management type name:

"TCRMPersonBObj": {
  "nestedBObjName": "tcrm_person_b_obj_type"
}

This mapping is used to:

  • Construct IBM Master Data Management API calls with the correct type names
  • Build XML responses with the appropriate structure

Object kinds

The kind property classifies business objects as either records or relationships:

"TCRMPersonBObj": {
  "nestedBObjName": "tcrm_person_b_obj_type",
  "kind": "record"
}

"TCRMPartyRelationshipBObj": {
  "nestedBObjName": "tcrm_party_relationship_b_obj_type",
  "kind": "relationship"
}

Valid values:

  • record: Represents an entity record
  • relationship: Represents a relationship between entities

Type selectors

Type selectors enable filtering of business object arrays by specific type values. They are configured for business object that need type-based filtering:

"TCRMPersonNameBObj": {
  "NameUsageType": "record.attributes.tcrm_person_name_b_obj:name_usage_type",
  "nestedBObjName": "tcrm_person_name_b_obj"
}

Type selector components

  • Field Name: The type field name (for example, NameUsageType)
  • JSONPath: Path to the type field in IBM Master Data Management data
  • Format: record.attributes.{array_name}:{field_name}

Dummy type selectors

Dummy type selectors are special markers for business objects that need placeholder type handling:

"TCRMPartyValueBObj": {
  "DummyType": "record.attributes.tcrm_party_value_b_obj:",
  "nestedBObjName": "tcrm_party_value_b_obj"
}

Use dummy type selectors for:

  • Business objects that don't have a real type field
  • Framework internal processing
  • Simple nested objects

Matching keys

Matching keys define the correlation logic used to align records and relationships during XML response construction. When the proxy orchestrates multiple IBM Master Data Management service requests (for example, to retrieve related entities or relationship data), matching keys specify which fields must be compared to ensure correct association and reconstruction of the target object model.

Basic matching keys

Basic matching keys define simple one-to-one field matching:

"TCRMInteractionRelationshipBObj": {
  "matchingKeys": [
    {
      "source": "record.attributes.attribute_id",
      "target": "tcrm_interaction_relationship_b_obj_type:attributes.from_record_id"
    },
    {
      "source": "attribute_id",
      "target": "tcrm_interaction_relationship_b_obj_type:attributes.to_record_id"
    }
  ],
  "nestedBObjName": "tcrm_interaction_relationship_b_obj_type"
}

Matching key components

  • source: JSONPath to the source field in parent JSON. Can start with record.attributes. for record business objects or be a direct attribute name for attribute business objects.
  • target: Type-qualified path to target field in child or relationship
  • Format: {type_name}:attributes.{field_name}

Matching behavior

  • The proxy matches JSONs where the source field equals the target field
  • Multiple matching keys create OR conditions

Matching keys with placement

The placement property indicates where the matched object should be located in the parent JSON:

"TCRMContractPartyRoleBObj": {
  "matchingKeys": [
    {
      "source": "relationship.attributes.to_record_id",
      "placement": "relationship",
      "target": "tcrm_person_b_obj_type:attributes.record_id"
    },
    {
      "source": "relationship.attributes.to_record_id",
      "placement": "relationship",
      "target": "tcrm_organization_b_obj_type:attributes.record_id"
    }
  ],
  "nestedBObjName": "tcrm_contract_party_role_b_obj_type",
  "kind": "relationship"
}

Matching keys with extract

The extract property controls which field from the child JSON to extract:

"TCRMFSPartyBObj": {
  "matchingKeys": [
    {
      "source": "record.attributes.record_id",
      "target": "tcrm_contract_party_role_b_obj_type:attributes.from_record_id",
      "extract": "target"
    },
    {
      "source": "record.attributes.record_id",
      "target": "tcrm_contract_party_role_b_obj_type:attributes.to_record_id",
      "extract": "source"
    }
  ]
}

Correlation paths

Correlation paths establish bindings between parent and child objects using shared identifiers during the creation or update of related records and relationships. The proxy generates or propagates a common value that is embedded in both objects, similar to a primary-foreign key relationship. Correlation paths define which fields in the parent and child structures must share this value to ensure consistent linkage and referential integrity.

Basic correlation paths

"TCRMPersonBObj": {
  "matchingKeys": [ ... ],
  "nestedBObjName": "tcrm_person_b_obj_type",
  "correlationPaths": {
    "TCRMContractPartyRoleBObj-key": {
      "parentPath": "relationship.attributes.to_record_id",
      "childPath": "record.attributes.record_id"
    }
  },
  "kind": "record"
}

Correlation path components

  • Key: Correlation identifier in the format {ChildBObjName}-key
  • parentPath: JSONPath to the parent's correlation field
  • childPath: JSONPath to the child's correlation field

Array selectors

Array selectors filter search result arrays to return only specific items. They are used in search transactions to select primary or preferred items from arrays.

Basic array selectors

"TCRMPersonSearchResultBObj": {
  "arraySelectors": {
    "record.attributes.tcrm_party_address_b_obj": {
      "address_usage_type": "1"
    },
    "record.attributes.tcrm_person_name_b_obj": {
      "name_usage_type": "1"
    }
  }
}

Array selector components

  • Array Path: JSONPath to the array in search results
  • Filter Criteria: Object with field-value pairs to match

Validation rules

Required fields

Every business object entry must have:

  • nestedBObjName (required for all business objects)

Optional fields

  • Type selectors (for example, NameUsageType, AddressUsageType)
  • matchingKeys
  • correlationPaths
  • arraySelectors
  • kind

Configuration examples

Example: Record business object with type selector

This example defines a person name business object with a type selector for filtering by name usage type:

"TCRMPersonNameBObj": {
  "NameUsageType": "record.attributes.tcrm_person_name_b_obj:name_usage_type",
  "nestedBObjName": "tcrm_person_name_b_obj"
}

Example: Relationship business object with matching keys

This example defines a party relationship business object with matching keys and placement:

"TCRMContractPartyRoleBObj": {
  "matchingKeys": [
    {
      "source": "relationship.attributes.to_record_id",
      "placement": "relationship",
      "target": "tcrm_person_b_obj_type:attributes.record_id"
    },
    {
      "source": "relationship.attributes.to_record_id",
      "placement": "relationship",
      "target": "tcrm_organization_b_obj_type:attributes.record_id"
    }
  ],
  "nestedBObjName": "tcrm_contract_party_role_b_obj_type",
  "kind": "relationship"
}

Example: Record business object with correlation paths

This example defines a person business object with correlation paths for establishing parent-child relationships:

"TCRMPersonBObj": {
  "matchingKeys": [
    {
      "source": "record.attributes.attribute_id",
      "target": "tcrm_interaction_relationship_b_obj_type:attributes.from_record_id"
    }
  ],
  "nestedBObjName": "tcrm_person_b_obj_type",
  "correlationPaths": {
    "TCRMContractPartyRoleBObj-key": {
      "parentPath": "relationship.attributes.to_record_id",
      "childPath": "record.attributes.record_id"
    }
  },
  "kind": "record"
}

Example: Search result business object with array selectors

This example defines a person search result business object with array selectors to filter for primary addresses and names:

"TCRMPersonSearchResultBObj": {
  "arraySelectors": {
    "record.attributes.tcrm_party_address_b_obj": {
      "address_usage_type": "1"
    },
    "record.attributes.tcrm_person_name_b_obj": {
      "name_usage_type": "1"
    }
  },
  "nestedBObjName": "tcrm_person_search_result_b_obj"
}

Learn more