IBM Master Data Management on IBM Software Hub provides APIs that enable you to connect the IBM Master Data Management service's powerful master data matching capabilities to your systems and processes. IBM Master Data Management enables you to establish a single, trusted, 360-degree view of your customers. IBM Master Data Management includes machine learning-assisted, self-service analytics and matching tools that deliver better business insights.

Business users and systems can access IBM Master Data Management data to search, view, and analyze master data entities. With IBM Master Data Management on IBM Software Hub, you can ensure that your users and systems have a total view of your data. With a seamlessly integrated, cross-solution experience, your users can discover master data directly in the space where they expect to consume it.

The IBM Master Data Management APIs support:

• Loading and mapping data
• Customizing the data model
• Configuring the matching algorithm
• Running matching
• Retrieving master data entity and record details
• MDM job management

Important: This reference documentation is for the v1 API, which applies to IBM Master Data Management for IBM Software Hub 5.0 and above, and IBM Match 360 for Cloud Pak for Data 4.0.1 and above.

For more information about IBM Master Data Management on IBM Software Hub, see the service's documentation in the IBM Software Hub documentation. For more information about IBM Match 360 on IBM Cloud Pak for Data 4.x, see the service's documentation in the IBM Cloud Pak for Data documentation.

The IBM Master Data Management service endpoint is based on your IBM Software Hub deployment URL: https://{cpd_cluster_host}/mdm/{match360-microservice}/. The valid microservice values are:

• model
• matching
• configuration
• data
• job

For example, if your instance is deployed at https://www.example.com:31843, you can access the IBM Master Data Management model APIs at https://www.example.com:31843/mdm/model/.

Additionally, you can access, discover, and run API commands with the Swagger UI API Explorer at the URL https://{cpd_cluster_host}/<MDM_INSTANCE_ID>/api-{match360-microservice}/explorer/#. For example, using the same instance host as in the previous example and an instance ID of 1664447707275339, you can access the Swagger UI API Explorer IBM Master Data Management APIs at the following URLs:

• Model: https://www.example.com/1664447707275339/api-model/explorer/#
• Matching: https://www.example.com/1664447707275339/api-matching/explorer/#
• Configuration: https://www.example.com/1664447707275339/api-configuration/explorer/#
• Data: https://www.example.com/1664447707275339/api-data/explorer/#
• Job: https://www.example.com/1664447707275339/api-job/explorer/#

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

ErrorResponse

ErrorAuthentication

ErrorHTML

ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

The Java SDK generates an exception for any unsuccessful method invocation. All methods that accept an argument can also throw an IllegalArgumentException.

When the Java SDK receives an error response from the IBM Master Data Management service, it generates an exception containing the following fields:

The Python SDK generates an exception for any unsuccessful method invocation. When the Python SDK receives an error response from the IBM Master Data Management service, it generates an exception containing the following fields:

After you install IBM Master Data Management on IBM Software Hub, you must give users access to the service by creating user groups and adding users to them.

Only the IBM Software Hub administrator who installs IBM Master Data Management is granted access to the service by default. To provide other users with access to the service, the administrator user must add them to the appropriate user groups. For example, to create and set up a master data configuration asset, users must belong to the DataEngineer group.

To access IBM Master Data Management, an IBM Software Hub user must belong to one of the following specialized groups:

• DataEngineer: DataEngineer group members have full rights to configure a IBM Master Data Management service instance, onboard data sources, customize the data model, tune and customize the matching algorithm, run matching, view or create jobs, create pair review requests, and view or edit entities and records in the master data explorer. DataEngineer users can create and set up a master data configuration asset. DataEngineer users can also view and manage governed data.
• DataSteward: Data Steward group members can onboard data sources, run matching, view the data model, view ongoing jobs, complete pair review tasks, and view or edit entities and records in the master data explorer.
• PublisherUser: PublisherUser group members can publish data from an IBM InfoSphere® Master Data Management instance, through the MDM Publisher tool, into IBM Master Data Management. PublisherUser members can onboard data sources, customize the data model, and view or create jobs. PublisherUser users can also view and manage governed data.
• EntityViewer: EntityViewer group members have read-only permission in an IBM Master Data Management instance. They can view the master data, the model, the results of matching, and ongoing jobs.

For information about creating the necessary IBM Master Data Management user groups and granting users access to IBM Master Data Management, see Giving users access to IBM Master Data Management in the IBM Software Hub documentation.

After access has been granted to users, IBM Master Data Management can accept authenticated API calls from those users.

To authenticate to the IBM Master Data Management API, you can use either a ZenAPIKey token or a service instance token. You must first generate the token from the IBM Software Hub platform, and then you can include it in the Authorization header of calls to the IBM Master Data Management API.

In IBM Software Hub (and Cloud Pak for Data 4.8.4 and later), you can authenticate to the IBM Master Data Management API by using a ZenAPIKey token.

The ZenApiKey token is built from the platform API key. To generate an API key through the IBM Software Hub user interface:

1. Log in to the IBM Software Hub web client.
2. From the toolbar, click your avatar.
3. Click Profile and settings.
4. Click API key > Generate new key.
5. Click Generate.
6. Click Copy and save your key somewhere safe. You cannot recover this key if you lose it.

Alternatively, you can call the IBM Software Hub Generate API key method. Note: this method must be called with Bearer access token authorization.

When you get the API Key from the user experience or from the "generate API Key" method, you must Base64 encode <username>:<api_key> to get the ZenAPIKey token.

Using a ZenAPIKey token to authorize your IBM Master Data Management API calls

Pass the ZenApiKey token in the Authorization header of an API request to authorize your IBM Master Data Management API calls. To provide the ZenApiKey token in an API Authorization header, run the following curl command:

curl -X GET 'https://{cpd_cluster_host}/<API_PATH>' -H 'Authorization: ZenApiKey {token}' -H 'Content-type: application/json'

Replace the following values in the curl command:

• <API_PATH> - the path of your desired API (Such as /mdm/model/v1/jobs).
• {token} - the platform ZenApiKey authentication token.

After authenticating to the IBM Software Hub platform, obtain a service instance token to authenticate to your IBM Master Data Management instance.

Service instance tokens expire 20 minutes after creation.

To retrieve a service instance token, view the service instance details in the IBM Software Hub web interface:

1. Log into the IBM Software Hub web interface.
2. Navigate to My Instances and select the appropriate IBM Master Data Management instance.
3. Click View details.

The service instance token is displayed in the Access Information section.

Service instance tokens are only valid for a particular instance of IBM Master Data Management.

Using a service instance token to authorize your IBM Master Data Management API calls

Pass the service instance token as Bearer token in the Authorization header of an API request to authorize your IBM Master Data Management API calls.

To provide the service instance token in an API Authorization header, run the following curl command:

curl -X GET 'https://{cpd_cluster_host}/<API_PATH>' -H 'Authorization: ZenApiKey {token}' -H 'Content-type: application/json'

Replace the following values in the curl command:

• <API_PATH> - the path of your desired API (Such as /mdm/model/v1/jobs).
• {token} - the service instance authentication token.

To use the Swagger UI API Explorer with the IBM Master Data Management API, you must first obtain a service instance ID. Then, you can navigate to the Swagger UI API Explorer and use it with the IBM Master Data Management API. Get your service instance ID by using the /zen-data/v3/service_instances API.

Run the following curl command:

curl -X GET 'https://{cpd_cluster_host}/zen-data/v3/service_instances?add_on_type=mdm-app' -H 'Authorization: ZenApiKey {token}' -H 'Content-type: application/json'

The curl command produces the following response in JSON format:

{
   "limit":20,
   "offset":0,
   "service_instances":[
      {
         "addon_type":"mdm-app",
         "addon_version":"1.0.0",
         "created_at":"<TIMESTAMP>",
         "description":"string",
         "display_name":"<SERVICE-DISPLAY-NAME>",
         "id":"<SERVICE-INSTANCE-ID>"
         ...
      }
   ],
   "total_count":1
}

The service instance ID is returned in the id property of the response.

After you have the service instance ID, you can authorize the API explorer:

1. Navigate to the Swagger API Explorer by browsing to https://{cpd_cluster_host}/<MDM_INSTANCE_ID>/api-model/explorer/# (replace <MDM_INSTANCE_ID> with your service instance ID number).
2. Click Authorize at the top of the page.
3. Enter the service instance token.
4. Click Authorize and then click Close.

The API Explorer passes your service instance token automatically for every API invoked from the API Explorer page.

Composite transactions bundle multiple REST API calls into a single composite_service endpoint request. Composite transactions can reduce network overhead, centralize error handling, and produce a consolidated response for the entire sequence of operations.

In the most basic form, a composite transaction contains a series of single transactions, run one after another. You can run composite transactions on your master data to complete several data operations at once by using the \mdm\v1\composite_service API endpoint. The composite operations are treated as a single unit of work, which means:

• If all of the operations complete successfully, then all of the resulting data changes are committed.
• If any one operation fails, then the entire composite transaction fails and any completed changes are rolled back as a single unit of work.

This all-or-none strategy is important so that composite transactions are not left partially complete.

Composite transactions include specially-formatted JSON object payloads that describe how each operation in the composite should be run.

During processing of a composite transaction, the responses from earlier operations can be used as input in the requests for later operations, as required by your business needs. Each composite transaction can also use predefined variables as input for its operation requests.

Composite transactions can also implement conditional logic to determine how each unit of work should be run.

This sample JSON shows an entire composite transaction JSON payload with placeholders:

{
  "variables": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  },
  "requests": [
    {
      "request_id": 0,
      "method": "string",
      "path": "string",
      "params": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
      },
      "req_body": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
      },
      "exclude_in_response": true
    }
  ],
  "choose": {
    "if_match": [
      {
        "condition": "string",
        "requests": [
          {
            "request_id": 0,
            "method": "string",
            "path": "string",
            "params": {
              "additionalProp1": {},
              "additionalProp2": {},
              "additionalProp3": {}
            },
            "req_body": {
              "additionalProp1": {},
              "additionalProp2": {},
              "additionalProp3": {}
            },
            "exclude_in_response": true
          }
        ]
      }
    ],
    "else": {
      "requests": [
        {
          "request_id": 0,
          "method": "string",
          "path": "string",
          "params": {
            "additionalProp1": {},
            "additionalProp2": {},
            "additionalProp3": {}
          },
          "req_body": {
            "additionalProp1": {},
            "additionalProp2": {},
            "additionalProp3": {}
          },
          "exclude_in_response": true
        }
      ],
      "message": {
        "code": "string",
        "text": "string",
        "type": "string"
      }
    }
  },
  "for_each": {
    "select": "string",
    "requests": [
      {
        "request_id": 0,
        "method": "string",
        "path": "string",
        "params": {
          "additionalProp1": {},
          "additionalProp2": {},
          "additionalProp3": {}
        },
        "req_body": {
          "additionalProp1": {},
          "additionalProp2": {},
          "additionalProp3": {}
        },
        "exclude_in_response": true
      }
    ],
    "choose": {
      "if_match": [
        {
          "condition": "string",
          "requests": [
            {
              "request_id": 0,
              "method": "string",
              "path": "string",
              "params": {
                "additionalProp1": {},
                "additionalProp2": {},
                "additionalProp3": {}
              },
              "req_body": {
                "additionalProp1": {},
                "additionalProp2": {},
                "additionalProp3": {}
              },
              "exclude_in_response": true
            }
          ]
        }
      ],
      "else": {
        "requests": [
          {
            "request_id": 0,
            "method": "string",
            "path": "string",
            "params": {
              "additionalProp1": {},
              "additionalProp2": {},
              "additionalProp3": {}
            },
            "req_body": {
              "additionalProp1": {},
              "additionalProp2": {},
              "additionalProp3": {}
            },
            "exclude_in_response": true
          }
        ]
        "message": {
          "code": "string",
          "text": "string",
          "type": "string"
        }
      }
    }
  }
}

A composite transaction is generally used to group related or dependent business transactions that you want to execute as a single unit of work. It is also valuable if you plan to implement simple if-match/else or looping logic between transactions. Composite transactions in IBM Master Data Management are often used by upstream or downstream systems in an Extract, Transform, and Load (ETL) flow to work with master data.

You can use a composite transaction to combine multiple, related transactions and avoid calling the IBM Master Data Management server multiple times. For example, consider a use case where you need to gather Customer 360 type information. You could run a composite transaction that performs multiple GET operations to return information about all of the records, relationships, groups, and hierarchies connected to a single person entity.

Composite transactions are not always the correct choice. Since all operations in a composite are run as one unit of work, you should refrain from grouping too many single transactions in one composite. The more single transactions there are in a composite, the longer it will take to complete the unit of work. This can lead to issues with transaction timeout errors.

Tip: To avoid timeout problems, try not to include more than four single operations within each composite transaction.

For example, consider a composite transaction containing three operations: two that add two new records into the system, and then another that creates a relationship between them. This transaction includes three separate transactions:

• Post Record
• Post Record
• Post Relationships

After the first two transactions are complete, the Post Relationships transaction needs to refer to the recordNumber values of the records created in the first two Post Record transactions. The composite_service transaction can use the two recordNumber values from the Post Record responses in the Post Relationships request. For details, see Using values from variables or responses in requests.

A basic composite transaction is a series of single API transactions, with the instructions for performing these transactions contained in the composite transasction's JSON payload.

The JSON of each composite transaction has two main sections:

• An optional variables section containing values to be shared by all of the component operations.
• An array of transaction API requests, optionally including conditions and optionally using values from the variables section or from responses of earlier requests.

The basic JSON structure is as follows:

{
  "variables":
    {
       <VARIABLE-DEFINITIONS>
    },
  "requests": [
    {
      <REQUEST-1>
    },
    {
      <REQUEST-2>
    },
      ...
    {
      <REQUEST-n>
    }
  ]
}

In the variables section, replace with actual key-value pairs.

In the requests section, the JSON for each request object includes the following parameters:

• request_id: A unique ID for this request within the composite transaction. You can use this ID to refer to this request in subsequent requests within the composite. For example, a request can refer to the ID of a previous request to allow it to use some of its returned values.
• exclude_in_response: Determines whether to exclude the response of this request in the final response payload of the composite_service transaction.
  • true: Exclude from final response
  • false: Include in final response
• method: The type of REST API method to use in this request: GET, POST, PUT, DELETE, or PATCH.
• path: The path to the IBM Master Data Management API method to use in this request. For a list of supported API endpoints, see Supported APIs for composite transactions.
• params: The parameters required for this API request, if applicable.
• req_body: The JSON payload content for this API request, if applicable.

Here is the basic structure of the request objects:

{
  "requests": [
    {
      "requestId": <ID>,
      "path": "<ENDPOINT-PATH>",
      "method": "<METHOD-TYPE>",
      "params": {
        <PARAMETERS>
      }
    },
    {
      "requestId": <ID>,
      "path": "<ENDPOINT-PATH>",
      "method": "<METHOD-TYPE>",
      "req_body": {
        <REQUEST-BODY>
      }
    }
  ]
}

When structuring a composite transaction, you can substitute values either from a variable (defined in the variables section of the request) or from the response payload of an earlier request in the composite. You can substitute values in either the path element or the req_body element of a request.

To substitute values in a request, use the standard JSONPath syntax to select and extract the JSON values from within a given JSON payload. Enclose the substitute variables in curly braces. Within the curly braces, you can optionally use the standard JSONPath expressions.

{{ site.data.keyword.mdm-oc_short }} composite transactions can perform conditional logic to determine how a unit of work should be run. There are two types of conditional operations:

• if-match/else
• looping (for_each)

The if-match/else condition lets you choose which operation to run based on the response of an earlier operation in the composite. Use standard JSONPath comparison functions to define each conditions.

To use if-match/else logic, include a choose JSON object in your payload that uses the following syntax:

{
  "choose": {
    "if_match": [
      {
        "condition": "{JSONPath comparison}",
        "requests": [
          {
            <REQUEST-OBJECT>
          }
        ]
      },
      {
        "condition": "{JSONPath comparison}",
        "requests": [
          {
            <REQUEST-OBJECT>
          }
        ]
      }
    ],
    "else_block": {
      "requests": [
        {
          <REQUEST-OBJECT>
        }
      ]
    }
  }
}

Each choose object can contain one if-match object.

Each if-match object can contain multiple condition objects and one else_block object.

If none of the conditions matches, then the else_block section is run.

Providing custom error messages in composite transactions that use if-match/else logic

If your composite transaction includes if-match/else logic, but none of the conditions match, you might want to provide a meaningfull error message in the response to describe the situation. In the composite transaction, you can use the message section of the else object to include text that the user sees when none of the conditions match.

To include a message section, use the following syntax:

"message": { 
	"code": "<UNIQUE-MESSAGE-ID>", 
	"text": "<TEXT-TO-DISPLAY>", 
	"type": "<MESSAGE-TYPE>"
} 

The <MESSAGE-TYPE> can be one of the following values:

• error: If the type is error, then the composite transaction fails and all changes are rolled back.
• warning: If the type is warning, the composite transaction is allowed to complete, but the specified message is returned to the user.

The for_each condition lets you iterate through a collection of objects (such as from a response to a GET operation) and then run a secondary operation on each of the objects.

To use looping logic, include a for_each JSON object in your payload that uses the following syntax:

{
  "for_each": {
    "select": "{$.responses.requests[?(@.requestId == <REQUEST-ID>)].response.*} as var",
    "requests": [
      {
        <REQUEST-OBJECT>
      }
    ]
  }
}

The for_each object contains a select attribute and a var attribute:

• The mandatory select attribute points to an object-set-expression, which gets evaluated against a collection of objects at runtime.
• The var attribute is a reference name that you can give to associate it with each object in the collection, as the collection is iterated through.

In each for_each object, you can include one or more requests for sub-transactions. When the object-set expression is evaluated to return a collection of objects, each of the requests is run as many times as there are objects in the collection.

You can also include a choose object, which enables you to further qualify the loop with if-match/else logic.

To run a composite transaction:

1. Define and structure the JSON payload of your composite transaction:

   • Optionally, define variables in the variables section.
   • Define each request in the requests section, using conditions and substituting values as needed.

2. Submit the JSON as part of an API request that uses the composite_service endpoint.

   PUT /mdm/v1/composite_service
   Host: https://api.dataplatform.cloud.ibm.com/
   Authorization: Bearer <BEARER-TOKEN>
   
   {
     "variables": {
       "<VARIABLE-DEFINITIONS>"
   },
     "requests": [
       {
         "<REQUEST-1>"
       },
       {
         "<REQUEST-2>"
       },
       ...
       {
         "<REQUEST-n>"
       }
     ]
   }
   

You can include the following data API endpoints as operations within your composite transactions. These endpoints are all included in the {{ site.data.keyword.mdm-oc_short }} data microservice, with the exception of the probabilistic_search endpoint. Transactions that include bulk operations or that are asynchrous are not supported.