IBM Match 360 as a Service API Reference

Introduction

Last updated: 2025-09-26

IBM Match 360 as a Service provides REST API endpoints that enable you to connect its powerful master data matching capabilities to your systems and processes. IBM Match 360 as a Service is an IBM Cloud service delivered through IBM Cloud Pak for Data as a Service that enables you to establish a single, trusted, 360-degree view of your customers -- a digital twin. IBM Match 360 includes cloud-native, machine learning-assisted, self-service analytics and matching tools that deliver better business insights.

Business users and systems can access IBM Match 360 data to search, view, and analyze master data entities. With IBM Match 360 as a Service, you can ensure that your users and systems have a total view of your data. With a seamlessly integrated, cross-solution cloud experience, your users can discover master data directly in the space where they expect to consume it.

The IBM Match 360 as a Service API supports:

Loading and mapping data
Customizing the data model
Configuring the matching algorithm
Running matching
Retrieving master data entity and record details
MDM job management
Running multiple operations at once by using a composite transaction

For more information about using IBM Match 360 as a Service, see the Cloud Pak for Data as a Service documentation.

Tip: To access the API documentation by using the Swagger UI tool, open a web browser and go to: https://api.{endpoint-location}.mdm.watson.cloud.ibm.com/api-{api-name}/explorer/. Replace {endpoint-location} in the URL with the location code of your deployment's multizone region, and replace {api-name} with the name of the IBM Match 360 API service you are accessing: data, model, job, matching, or configuration.

For example, to access the API in the Dallas global endpoint (us-south), go to the following URLs:

Configuration API (config): https://api.dataplatform.cloud.ibm.com/mdm/api-configuration/explorer/
Entity Maintenance API (data): https://api.dataplatform.cloud.ibm.com/mdm/api-data/explorer/
Job API (job): https://api.dataplatform.cloud.ibm.com/mdm/api-job/explorer/
Matching API (matching): https://api.dataplatform.cloud.ibm.com/mdm/api-matching/explorer/
Model API (model): https://api.dataplatform.cloud.ibm.com/mdm/api-model/explorer/

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install --save master-data—management-cloud

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
  <groupId>com.ibm.cloud</groupId>
  <artifactId>mdm</artifactId>
  <version>1.0.6</version>
</dependency>
Copy to clipboard

Gradle

implementation 'com.ibm.cloud:mdm:1.0.6'

GitHub https://github.com/IBM/mdm-java-sdk

The code examples on this tab use the client library that is provided for Python.

Installation

pip install master-data-management

Endpoint URLs

The IBM Match 360 as a Service API uses the Dallas global endpoint URL for all regions. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://api.dataplatform.cloud.ibm.com

Example request to the Dallas endpoint

curl -u "apikey:{apikey}" -X {request_method} "https://api.dataplatform.cloud.ibm.com/{method_endpoint}"

Replace {apikey}, {request_method}, and {method_endpoint} in this example with the values for your particular API call.

Example request to the Dallas endpoint:

const MasterDataManagementV1 = require('ibm/master-data-management/v4');
const { IamAuthenticator } = require('ibm/auth');

const masterDataManagement = new MasterDataManagementV1({
  version: '{version}',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  url: 'https://api.dataplatform.cloud.ibm.com/{method_endpoint}',
});

Replace {apikey}, {version}, and {method_endpoint} in this example with the values for your particular API call.

Example request to the Dallas endpoint:

import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.ibm.cloud.mdm.v1.Mdm;
Authenticator authenticator = new BearerTokenAuthenticator("<access-token>");
Mdm mdm = new Mdm(crn, Mdm.DEFAULT_SERVICE_NAME, authenticator);

Replace <access-token> in this example with the values for your particular API call.

Later, when the access token expires, the application must acquire a new access token, then set it on the authenticator. Subsequent request invocations will include the new access token.

authenticator.setBearerToken("<new-access-token>")

Alternatively, use external configuration and provide values for the following properties:

MDM_URL=https://api.dataplatform.cloud.ibm.com/
MDM_AUTH_TYPE=bearertoken
MDM_BEARER_TOKEN=<access-token>

and access the service by using:

Mdm service = Mdm.newInstance(crn);

Example request to the Dallas endpoint:

from ibm import MasterDataManagementV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
master_data_management = MasterDataManagementV1(
    version='{version}',
    authenticator=authenticator
)

master_data_management.set_service_url('https://api.dataplatform.cloud.ibm.com/{method_endpoint}')

Replace {apikey}, {version}, and {method_endpoint} in this example with the values for your particular API call.

Error handling

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.

HTTP error code	Description	Recovery
`200`	Success	The request was successful.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access '{namespace}'.
`404`	Not Found	The requested resource could not be found.
`408`	Request Timeout	The connection to the server timed out. Wait a few minutes, then try again.
`409`	Conflict	The entity is already in the requested state.
`500`	Internal Server Error	offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

ErrorContainer

Field name	Type	Description
status_code	integer	The HTTP status code of the response.
errors	`List<ErrorMessage>`	A list of errors.
trace	string	The lower case UUID that uniquely identies the request.

ErrorMessage

Field name	Type	Description
code	string	A snake_case string succinctly identifying the problem.
message	string	An explanation of the solution to the problem.
more_info	string	A publicly-accessible URL where information about the error can be read in a web browser.
target	`ErrorTarget`	An error target model.

ErrorTarget

Field name	Type	Description
type	string	The type of the error target. One of: `field`, `parameter`, or `header`.
name	string	The name of the field, parameter, or header.

When the Node SDK receives an error response from the IBM Match 360 service, it creates an Error object with information describing the error that occurred. This error object is passed as the first parameter to the callback function for the method. The contents of the error object are as shown in the following table:

Errors

Error field	Description
code	The HTTP status code returned.
message	A message describing the error.

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

Exception	Description
IllegalArgumentException	An invalid argument was passed to the method.

When the Java SDK receives an error response from the IBM Match 360 service, it generates an exception from the com.ibm.master_data_management.service.exception package. All service exceptions contain the following fields:

Error field	Description
statusCode	The HTTP status code returned
message	A message describing the error

The Python SDK generates an exception for any unsuccessful method invocation. When the Python SDK receives an error response from the IBM Match 360 service, it generates a MasterDataManagementAPIException containing the following fields:

Error field	Description
code	The HTTP status code returned
message	A message describing the error
info	A dictionary of additional information about the error

masterDataManagement.method(params,
    function(err, response) {
        // The error will be the first argument of the callback
        if (err.code == 404) {
            // Handle Not Found (404) error
        } else if (err.code == 413) {
            // Handle Request Too Large (413) error
        } else {
            console.log('Unexpected error: ', err.code);
            console.log('error:', err);
        }
    });
Copy to clipboard

Example error handling

try {
    // Invoke an IBM Match 360 method
} catch (NotFoundException e) {
    // Handle Not Found (404) exception
} catch (RequestTooLargeException e) {
    // Handle Request Too Large (413) exception
} catch (ServiceResponseException e) {
    // Base class for all exceptions caused by error responses from the service
    System.out.println("Service returned status code " + e.getStatusCode() + ": " + e.getMessage());
}
Copy to clipboard

Example error handling

from master_data_management import MasterDataManagementAPIException
try:
    # Invoke an IBM Match 360 method
except MasterDataManagementAPIException as ex:
    print "Method failed with status code " + str(ex.code) + ": " + ex.message
Copy to clipboard

Authentication

To authenticate to the IBM Match 360 API, you pass a bearer token in an Authorization header. The token is associated with a user name.

The bearer authentication token can be obtained using cURL: curl -X POST https://iam.cloud.ibm.com/identity/token -H "content-type: application/x-www-form-urlencoded" -H "accept: application/json" -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=APIKEY"

The following cURL example shows authentication being passed using a bearer token: curl -X PUT --header "Authorization: Bearer {accessToken}" --header "Accept: application/json" "{url}/mdm/configuration/v1/config_data_model/publish_model?project_id=config_42d00915_1497_4d65_90af_cfd09d015769%3A31925406598685396&crn=CRN”

Replace {accessToken} with your authentication bearer token.

Generating a bearer token. The response includes an accessToken property.

Replace {cpd_cluster_host} and {port} with the details for the service instance. Replace {username} and {password} with your IBM Cloud Pak for Data credentials.

curl -k -u "{username}:{password}" "https://{cpd_cluster_host}{:port}/v1/preauth/validateAuth"

Authenticating to the API. Replace {accessToken} with your authentication bearer token.

curl -H "Authorization: Bearer {accessToken}" "{url}/v1/{method}"

Example header parameter in a request:

masterDataManagement.methodName(
    {
        parameters,
        headers: {
            'Custom-Header': '{header_value}'
        }
    }, function(err, response) {
        if (err)
            console.log('error:', err);
        else
            console.log(response);
    }
);
Copy to clipboard

Example header parameter in a request:

ReturnType returnValue = masterDataManagement.methodName(parameters)
        .addHeader("Custom-Header", "{header_value}")
        .execute();
Copy to clipboard

Example header parameter in a request:

response = masterDataManagement.methodName(
    parameters,
    headers = {
        'Custom-Header': '{header_value}'
    })

Running composite transactions

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"
        }
      }
    }
  }
}

In this example scenario, a data steward wants to perform a probabilistic search for a particular payload and then perform the following operations based on the result of the probabilistic search:

If there are no records who has a score above ALT(Auto link threshold), then create a new record in the system.
If there exists records in the system who has a similarity score above ALT (autolink threshold), get the system identifier of the record using GET record call and then add a new additional attribute to all these records using PATCH record.

Here is the JSON payload for this scenario:

{
  "variables": {
    "last_name": "HAWKIN",
    "given_name": "DAVID",
    "phone_number": "647-255-1021",
    "person_record_id": "1223345"
  },
  "requests": [
    {
      "request_id": 1,
      "method": "POST",
      "path": "/mdm/v1/probabilistic_search",
      "params": {
        "include_logical_key": true,
        "details": "low",
        "min_score": "0",
        "max_score": 200,
        "offset": 0,
        "entity_type": "person_entity",
        "limit": 10
      },
      "req_body": {
        "record_type": "person",
        "attributes": {
          "home_telephone": {
            "phone_number": "{$.variables.phone_number}"
          },
          "legal_name": {
            "last_name": "{$.variables.last_name}",
            "given_name": "{$.variables.given_name}"
          }
        }
      }
    }
  ],
  "for_each": {
    "select": "$.responses[?(@.request_id == 1)].response.records[?(@.score > 110)] as item",
    "requests": [
      {
        "request_id": 2,
        "path": "/mdm/v1/records/bysourceid",
        "method": "GET",
        "params": {
          "record_type": "person",
          "record_id": "{$.item.record_id}",
          "record_source": "{$.item.record_source}"
        }
      },
      {
        "request_id": 3,
        "method": "PATCH",
        "path": "/mdm/v1/records/{$.responses[?(@.request_id == 2)].response.record.id}",
        "req_body": {
          "attributes": {
            "mailing_address": {
              "province_state": "CA",
              "city": "COLOMA",
              "zip_postal_code": "95613",
              "address_line1": "5955 EAST ST ANNE STREET",
              "address_line2": "Unit-89"
            }
          },
          "type": "record",
          "type_name": "person"
        }
      }
    ]
  }
}
Copy to clipboard

When to use composite transactions

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 Match 360 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 Match 360 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.

This composite transaction sample has two parts: (a) get a record by its source ID, and then (b) take the recordNumber from the response of the first request and use it to complete a different operation:

{
  "requests": [
    {
      "requestId": 1,
      "path": "mdm/v1/records/bysourceid",
      "method": "GET",
      "params": {
        "recordType": "person",
        "recordId": "34353434",
        "recordSource": "MDM"
      }
    },
    {
      "requestId": 2,
      "path": "mdm/v1/records/{$.requests[?(@.requestId == 1)].response.attributes.recordNumber}",
      "method": "PUT",
      "req_body": {
        <REQUEST-BODY>
      }
    }
  ]
}
Copy to clipboard

Example composite transaction scenario

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.

Formatting the JSON payload of a composite transaction

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 Match 360 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>
      }
    }
  ]
}

This sample shows the JSON for substituting values from variables

{
  "variables": {
    "recordNumber": 442234234
  },
  "requests": [
    {
      "path": "mdm/v1/records/${$.variables.recordNumber}",
      "method": "GET"
    },
    {
      "path": "mdm/v1/records/${$.variables.recordNumber}/relationships",
      "method": "GET"
    }
  ]
}
Copy to clipboard

Using values from variables or responses in requests

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.

This sample shows the JSON for substituting values from responses in composite transactions:

{
  "requests": [
    {
      "requestId": 1,
      "path": "mdm/v1/records/bysourceid",
      "method": "GET",
      "params": {
        "recordType": "person",
        "recordId": "34353434",
        "recordSource": "MDM"
      }
    },
    {
      "requestId": 2,
      "path": "mdm/v1/records/{$.requests[?(@.requestId==1)].response.attributes.recordNumber}",
      "method": "PUT",
      "req_body": {
        "attributes": {
          "legal_name": {
            "given_name": "Jane"
          },
          "mailing_address": {
            "province_state": "CA",
            "city": "COLOMA",
            "zip_postal_code": "95613",
            "address_line1": "5955 EAST ST ANNE STREET",
            "address_line2": "Unit-89"
          },
          "birth_date": {
            "value": "22-12-1975",
            "recordLastUpdated": "{$.requests[?(@.requestId==1)].response.attributes.recordNumber}"
          }
        },
        "type": "record",
        "type_name": "person"
      }
    }
  ]
}
Copy to clipboard

Adding conditional logic to a composite transaction

{{ 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)

If-match/else logic

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.

This sample shows to use if-match/else logic in a composite transaction:

{
  "requests": [
    {
      "request_id": 1,
      "path": "/mdm/v1/records/bysourceid",
      "method": "GET",
      "params": {
        "record_type": "person",
        "record_id": "12345",
        "record_source": "MDM"
      }
    }
  ],
  "choose": {
    "if_match": [
      {
        "condition": "{$.responses[?(@.request_id == 1)].response.data.code} == '404'",
        "requests": [
          {
            "request_id": 2,
            "method": "POST",
            "path": "/mdm/v1/records",
            "req_body": {
              "attributes": {
                "maiden_name": {
                  "last_name": "PATTERSON",
                  "given_name": "CONNIE"
                },
                "legal_name": {
                  "last_name": "HAWKIN",
                  "given_name": "DAVID"
                },
                "display_name": {
                  "value": "DAVID HAWKIN"
                },
                "record_start": {
                  "value": "2019-02-01 07:42:56.627"
                },
                "social_insurance_number": {
                  "identification_number": "867807131"
                },
                "gender": {
                  "value": "M"
                },
                "personal_email": {
                  "email_id": "908254903577664099"
                },
                "record_source": "SourceA",
                "mobile_telephone": {
                  "phone_number": "647-255-1021"
                },
                "record_id": "12345",
                "record_last_updated": "1549006976633"
              },
              "type_name": "person",
              "type": "record"
            }
          }
        ]
      }
    ],
    "else": {
      "message": {
        "code": "1200",
        "text": "If condition failed",
        "type": "Warning"
      }
    }
  }
}
Copy to clipboard

Looping logic

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.

This sample shows how to use a looping condition in a composite transaction to update the addresses of all records that match the search criteria:

{
  "variables": {},
  "requests": [
    {
      "request_id": 1,
      "method": "POST",
      "path": "/mdm/v1/search",
      "params": {
        "return_type": "results",
        "limit": "2",
        "offset": "0",
        "include_total_count": true,
        "include": null,
        "exclude": null
      },
      "req_body": {}
    }
  ],
  "for_each": {
    "select": "$.responses[0].response.data.results as item",
    "choose": {
      "if_match": [
        {
          "condition": "{$.item.type_name} != \"person\"",
          "requests": [
            {
              "loop_count": 1,
              "request_id": 5,
              "method": "PATCH",
              "path": "/mdm/v1/records/{$.item.record_number}",
              "req_body": {
                "attributes": {
                  "mailing_address": {
                    "province_state": "CA",
                    "city": "COLOMA",
                    "zip_postal_code": "95613",
                    "address_line1": "5955 EAST ST ANNE STREET",
                    "address_line2": "Unit-89"
                  }
                },
                "type": "record",
                "type_name": "person"
              }
            }
          ]
        }
      ],
      "else": {
        "message": {
          "code": "1200",
          "text": "If condition failed",
          "type": "warning"
        }
      }
    }
  }
}
Copy to clipboard

Running a composite transaction

To run a composite transaction:

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.

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>"
    }
  ]
}

Supported APIs for composite transactions

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.

Endpoint	Method	Operation ID
/mdm/v1/entities/{id}/records	GET	list_data_records_for_entity
/mdm/v1/entities/{id}	GET	get_data_entity
/mdm/v1/entities/{id}	PUT	replace_data_entity
/mdm/v1/entities/{id}	PATCH	update_data_entity
/mdm/v1/entities/{id}/relationships	GET	list_data_relationships_for_entity
/mdm/v1/entities/{id}/related_records	GET	list_data_related_records_for_entity
/mdm/v1/groups/{id}	GET	get_group
/mdm/v1/groups/{id}	PUT	put_group
/mdm/v1/groups/{id}	DELETE	delete_data_group
/mdm/v1/groups/by_associated_object/{id}	GET	get_all_groups
/mdm/v1/groups/by_associated_object/{id}	PATCH	patch_by_associated_object
/mdm/v1/groups	POST	create_group
/mdm/v1/groups	GET	get_groups
/mdm/v1/groups/search	POST	search_groups
/mdm/v1/groups/{id}/associations	PATCH	patch_group_associations
/mdm/v1/groups/bysourceid	GET	get_group_by_source_id
/mdm/v1/hierarchies/by_associated_object/{id}	GET	get_all_hierarchy
/mdm/v1/hierarchies/{id}	GET	get_hierarchy
/mdm/v1/hierarchies/{id}	DELETE	delete_data_hierarchy
/mdm/v1/hierarchies/{id}	PATCH	update_data_hierarchy
/mdm/v1/hierarchies/{id}/configuration	GET	get_hierarchy_configuration
/mdm/v1/hierarchies/{id}/configuration	PUT	put_hierarchy_configuration
/mdm/v1/hierarchies/{id}/configuration	DELETE	delete_hierarchy_configuration
/mdm/v1/hierarchies/{id}/broken_branches	GET	hierarchy_broken_branches
/mdm/v1/hierarchies/{id}/centric_view	GET	get_hierarchy_node_centric_view
/mdm/v1/hierarchies	POST	create_data_hierarchy
/mdm/v1/hierarchies	GET	get_all_hierarchies
/mdm/v1/hierarchies/{id}/branches/{branch_node_id}	DELETE	delete_hierarchy_branch
/mdm/v1/hierarchies/{id}/member_search	GET	hierarchy_member_search
/mdm/v1/records/{id}/related_records	GET	list_data_related_records_for_record
/mdm/v1/records/{id}/entities	GET	list_data_entities_for_record
/mdm/v1/records/{id}/accumulated_updates	GET	potential_overlay_records
/mdm/v1/records/{id}/relationships	GET	list_data_relationships_for_record
/mdm/v1/records/{id}	GET	get_data_record
/mdm/v1/records/{id}	PUT	replace_data_record
/mdm/v1/records/{id}	DELETE	delete_data_record
/mdm/v1/records/{id}	PATCH	patch_data_record
/mdm/v1/records	GET	list_data_records
/mdm/v1/records	POST	create_data_record
/mdm/v1/records/bysourceid	GET	get_data_record_params
/mdm/v1/records/{id}/relationships/{relationship_id}	GET	get_data_relationship_for_record
/mdm/v1/records/bysource_system_id	GET	get_data_record_multisource
/mdm/v1/relationships	POST	create_data_relationship
/mdm/v1/relationships/{id}	GET	get_data_relationship
/mdm/v1/relationships/{id}	PUT	replace_data_relationship
/mdm/v1/relationships/{id}	DELETE	delete_data_relationship
/mdm/v1/search	POST	search_data
/mdm/v1/probabalistic_search	POST	search_matching_index

Gets all the attributes of a specific type for the data model present in configuration space.

GET /mdm/v1/config_data_model/attributes

ServiceCall<ConfigDataModelAttributes> getConfiguratorConfigDataModelAttributes(GetConfiguratorConfigDataModelAttributesOptions getConfiguratorConfigDataModelAttributesOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Use the GetConfiguratorConfigDataModelAttributesOptions.Builder to create a GetConfiguratorConfigDataModelAttributesOptions object that contains the parameter values for the getConfiguratorConfigDataModelAttributes method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
type_category
Required*
string
The type category of the data model attributes
type_name
Required*
string
The type name of the type category to identify data model attributes

GetConfiguratorConfigDataModelAttributesOptions

The getConfiguratorConfigDataModelAttributes options.

Get Config Data Model Record Type Attributes

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/config_data_model/attributes?type_name=person&type_category=employee&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Response

Response Body

ConfigDataModelAttributes

The Config Data Model attributes for a record type.

ConfigDataModelAttributes

The Config Data Model attributes for a record type.

Status Code

200
Config Data Model Type attributes retrieved.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in fetching Config Data Model Record Type attributes.

Example responses

Status 200

{
  "attributes": [
    {
      "name": "record_id",
      "default_display_name": "Record identifier"
    },
    {
      "name": "record_source",
      "default_display_name": "Record source"
    }
  ]
}
Copy to clipboard

Success example

{
  "attributes": [
    {
      "name": "record_id",
      "default_display_name": "Record identifier"
    },
    {
      "name": "record_source",
      "default_display_name": "Record source"
    }
  ]
}
Copy to clipboard

Gets the data model present in configuration space.

GET /mdm/v1/config_data_model

ServiceCall<ConfigDataModel> getConfiguratorConfigDataModel(GetConfiguratorConfigDataModelOptions getConfiguratorConfigDataModelOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Use the GetConfiguratorConfigDataModelOptions.Builder to create a GetConfiguratorConfigDataModelOptions object that contains the parameter values for the getConfiguratorConfigDataModel method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Gets the data model present in the configuration space

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/config_data_model?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorConfigDataModelOptions getConfiguratorConfigDataModelOptions = new GetConfiguratorConfigDataModelOptions();

Response<ConfigDataModel> response = mdmService.getConfiguratorConfigDataModel(getConfiguratorConfigDataModelOptions).execute();
ConfigDataModel configDataModel = response.getResult();

System.out.println(configDataModel);

Response

Response Body

ConfigDataModel

Collection of record and relationship types and system properties definition

ConfigDataModel

Collection of locale, record types, relationship types, system properties definition in configuration space.

Status Code

200
Config data model is returned
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem getting config data model. An internal error occurred while attempting to get config data model.

Example responses

Status 200

{
  "record_types": [
    {
      "name": "person",
      "default_display_name": "person",
      "properties": [
        {
          "name": "record_source",
          "data_type": "String",
          "default_display_name": "Record Source",
          "designation": "source"
        },
        {
          "name": "social_security_number",
          "data_type": "identification",
          "cardinality": "*",
          "default_display_name": "Social Security Number"
        }
      ],
      "source_systems": [
        {
          "name": "MDMSP",
          "default_display_name": "MDMS Person",
          "quality_factors": {
            "completeness": 100,
            "accuracy": 100,
            "correctness": 100,
            "age_relevancy": 100,
            "data_relevancy": 100,
            "consistency": 100
          }
        }
      ]
    }
  ],
  "data_types": [
    {
      "name": "identification",
      "default_display_name": "identification",
      "properties": [
        {
          "name": "identification",
          "data_type": "String",
          "default_display_name": "Identification Value"
        },
        {
          "name": "identification_number",
          "data_type": "String",
          "default_display_name": "Identification Number"
        }
      ]
    }
  ]
}
Copy to clipboard

Success example

{
  "record_types": [
    {
      "name": "person",
      "default_display_name": "person",
      "properties": [
        {
          "name": "record_source",
          "data_type": "String",
          "default_display_name": "Record Source",
          "designation": "source"
        },
        {
          "name": "social_security_number",
          "data_type": "identification",
          "cardinality": "*",
          "default_display_name": "Social Security Number"
        }
      ],
      "source_systems": [
        {
          "name": "MDMSP",
          "default_display_name": "MDMS Person",
          "quality_factors": {
            "completeness": 100,
            "accuracy": 100,
            "correctness": 100,
            "age_relevancy": 100,
            "data_relevancy": 100,
            "consistency": 100
          }
        }
      ]
    }
  ],
  "data_types": [
    {
      "name": "identification",
      "default_display_name": "identification",
      "properties": [
        {
          "name": "identification",
          "data_type": "String",
          "default_display_name": "Identification Value"
        },
        {
          "name": "identification_number",
          "data_type": "String",
          "default_display_name": "Identification Number"
        }
      ]
    }
  ]
}
Copy to clipboard

Replaces the config data model present in configuration space.

PUT /mdm/v1/config_data_model

ServiceCall<ConfigDataModel> replaceConfiguratorConfigDataModel(ReplaceConfiguratorConfigDataModelOptions replaceConfiguratorConfigDataModelOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Use the ReplaceConfiguratorConfigDataModelOptions.Builder to create a ReplaceConfiguratorConfigDataModelOptions object that contains the parameter values for the replaceConfiguratorConfigDataModel method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

ConfigDataModel

Collection of record and relationship types and system properties definition

Examples:

ReplaceConfiguratorConfigDataModelOptions

The replaceConfiguratorConfigDataModel options.

Replace Config Data Model

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/config_data_model?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"locale":"en_us","system_properties":{"record_types":{"collection_id":{"label":"Collection ID","description":"Optional identifier for identifying a collection of records","data_type":"String","editable":true,"indexed":true},"record_source":{"label":"Record source","description":"A user provided record source.","data_type":"String","editable":true,"indexed":true},"record_id":{"label":"Record identifier","description":"User provided or autogenerated record identifier","data_type":"String","editable":true,"indexed":true},"record_number":{"label":"Record number","description":"System generated record number","data_type":"String","editable":false,"indexed":true},"record_last_updated":{"label":"Record last updated","description":"System generated record last updated","data_type":"Long","editable":false,"indexed":false}},"entity_types":{"entity_id":{"label":"Entity identifier","data_type":"String","editable":false,"indexed":true},"entity_last_updated":{"label":"Entity last updated time","data_type":"Long","editable":false,"indexed":false}},"attribute_types":{"attribute_last_updated":{"label":"Attribute last updated date","description":"Entity last updated time","data_type":"Long","editable":false,"indexed":false}},"relationship_types":{"relationship_last_updated":{"label":"Relationship last updated date","description":"Entity last updated time","data_type":"Long","editable":false,"indexed":false}}},"record_types":{"person":{"label":"Person","description":"The record type for person records.","entity_types":{"person_entity":{"label":"Person Entity","description":"The entity type for person records."}},"attributes":{"birth_date":{"label":"Birth Date","description":"The birth date associated with this person record.","attribute_type":"string","classification":"","cardinality":"LIST","indexed":true,"matching_type":"DATE"},"gender":{"label":"Gender","description":"The gender of the the person associated with this record.","attribute_type":"string","classification":"","cardinality":"LIST","indexed":true,"matching_type":"GENDER"},"primary_residence":{"label":"Primary Residence","description":"Indicates that this address is a primary residence.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"mailing_address":{"label":"Mailing Address","description":"Indicates that this address is a mailing address.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"home_telephone":{"label":"Home Telephone","description":"Indicates that this phone number is for a home telephone.","attribute_type":"telephone","classification":"","cardinality":"LIST","indexed":true},"mobile_telephone":{"label":"Mobile Telephone","description":"Indicates that this phone number is for a mobile telephone.","attribute_type":"telephone","classification":"","cardinality":"LIST","indexed":true},"personal_email":{"label":"Personal Email","description":"Indicates that this email address is a personal email address.","attribute_type":"email","classification":"","cardinality":"LIST","indexed":true},"twitter":{"label":"Twitter","description":"Indicates that this social media type is Twitter.","attribute_type":"social_media","classification":"","cardinality":"LIST","indexed":true},"drivers_licence":{"label":"Driver's Licence","description":"Indicates that this identifier is a driver's license.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"passport":{"label":"Passport","description":"Indicates that this identifier is a passport.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"credit_card":{"label":"Credit Card","description":"Indicates that this identifier is a credit card.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"PAYMENTCARDNUMBER"},"social_insurance_number":{"label":"Social Insurance Number","description":"Indicates that this identifier is a social insurance number.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"legal_name":{"label":"Legal Name","description":"Indicates that this name is a legal name.","attribute_type":"person_name","classification":"","cardinality":"LIST","indexed":true},"previous_name":{"label":"Previous Name","description":"Indicates that this name is a previous name.","attribute_type":"person_name","classification":"","cardinality":"LIST","indexed":true}}},"organization":{"label":"Organization","description":"The record type for organization records.","entity_types":{"organization_entity":{"label":"Organization Entity","description":"The entity type for org records."}},"attributes":{"business_name":{"label":"Business Name","description":"Indicates that this name is a business name.","attribute_type":"organization_name","classification":"","cardinality":"LIST","indexed":true},"doing_business_as":{"label":"Doing Business As","description":"Indicates that this name is a Doing Business As name.","attribute_type":"organization_name","classification":"","cardinality":"LIST","indexed":true},"abbreviated_name":{"label":"Abbreviated Name","description":"Indicates that this name is an abbreviated name.","attribute_type":"organization_name","classification":"","cardinality":"LIST","indexed":true},"business_address":{"label":"Business Address","description":"Indicates that this address is a business address.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"mailing_address":{"label":"Mailing Address","description":"Indicates that this address is a mailing address.","attribute_type":"address","classification":"","cardinality":"LIST","indexed":true},"business_telephone":{"label":"Business Telephone","description":"Indicates that this phone number is for a business telephone.","attribute_type":"telephone","classification":"","cardinality":"LIST","indexed":true},"business_email":{"label":"Business Email","description":"Indicates that this email address is a business email.","attribute_type":"email","classification":"","cardinality":"LIST","indexed":true},"business_tax_identification":{"label":"Business Tax Identification","description":"Indicates that this identifier is a business tax identification number.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"},"duns":{"label":"DUNS","description":"Indicates that this identifier is a D-U-N-S Number.","attribute_type":"identification","classification":"","cardinality":"LIST","indexed":true,"matching_type":"NATIONALIDENTIFIER"}}}},"attribute_types":{"address":{"label":"Address","description":"The address locations associated with a record. Only one address per usage value is allowed. For example, there can only be one mailing address for a contact.","classification":"","matching_types":["ADDRESS"],"fields":{"residence":{"label":"Residence Value","description":"The type of residence for this address, such as home, apartment, or suite.","classification":"","indexed":true},"address_line1":{"label":"Address Line 1","description":"The first line of this address.","classification":"","indexed":true},"address_line2":{"label":"Address Line 2","description":"The second line of this address.","classification":"","indexed":true},"address_line3":{"label":"Address Line 3","description":"The third line of this address.","classification":"","indexed":true},"city":{"label":"City","description":"The city of this address.","classification":"","indexed":true},"zip_postal_code":{"label":"Postal Code","description":"The postal code of this address.","classification":"","indexed":true},"residence_number":{"label":"Residence Number","description":"The residence number of this address.","classification":"","indexed":true},"province_state":{"label":"State/Province Value","description":"The state or province of this address.","classification":"","indexed":true},"county":{"label":"County","description":"The county of this address.","classification":"","indexed":true},"country":{"label":"Country Value","description":"The country of this address.","classification":"","indexed":true},"latitude_degrees":{"label":"Latitude Degrees","description":"The latitude of this address.","classification":"","indexed":true},"longitude_degrees":{"label":"Longitude Degrees","description":"The longitude of this address.","classification":"","indexed":true}}},"telephone":{"label":"Telephone","description":"Indicates that this attribute is a telephone number. Create attributes of this type for each category of telephone number, such as mobile, home, or business.","classification":"","matching_types":["PHONE"],"fields":{"phone_number":{"label":"Phone Number","description":"A string containing the digits for this telephone number.","classification":"","indexed":true}}},"email":{"label":"Email","description":"Indicates that this attribute is an email address. Create attributes of this type for each category of email address, such as personal or business.","classification":"","matching_types":["EMAIL"],"fields":{"email_id":{"label":"Email Id","description":"A string containing the email address value.","classification":"","indexed":true}}},"social_media":{"label":"Social Media","description":"Indicates that this attribute is a social media handle or user name. Create attributes of this type for each social media platform, such as Twitter or Instagram.","classification":"","matching_types":["SOCIALMEDIA"],"fields":{"social_media_handle":{"label":"Social Media Handle","description":"A string containing the handle or user name value.","classification":"","indexed":true}}},"identification":{"label":"Identification","description":"A unique identifier that can be used to distinguish a party from others.","classification":"","matching_types":["NATIONALIDENTIFIER","PAYMENTCARDNUMBER","OTHERIDENTIFIER"],"fields":{"identification_number":{"label":"Identification Number","description":"The actual alphanumeric identifier. For example, if the identification type indicates a social security number, then this value contains the 9 characters of the social security number.","classification":"","indexed":true}}},"person_name":{"label":"Person Name","description":"Information about a name associated with a person record.","classification":"","matching_types":["PERSONNAME"],"fields":{"generation":{"label":"Generation Value","description":"Identifies familial generational information in the form of a generation type. Examples include The First, The Second, Junior or Senior.","classification":"","indexed":true},"prefix":{"label":"Prefix Value","description":"The name prefix, such as Mr, Mrs, Miss, Dr, and others.","classification":"","indexed":true},"given_name":{"label":"Given Name","description":"The first given name of a person. Commonly known as the first name.","classification":"","indexed":true},"middle_name":{"label":"Middle Name","description":"The second given name of a person. Commonly known as the middle name.","classification":"","indexed":true},"last_name":{"label":"Last Name","description":"The surname or family name of a person. Commonly known as the last name.","classification":"","indexed":true},"suffix":{"label":"suffix","description":"The name suffix, such as Jr, MD, Esq, PhD, and others.","classification":"","indexed":true},"full_name":{"label":"Full name","description":"The complete name of this person in a single string, including first, middle, and last names.","classification":"","indexed":true}}},"organization_name":{"label":"Organization Name","description":"Information about a name associated with an organization record.","classification":"","matching_types":["ORGNAME"],"fields":{"name":{"label":"name","description":"The organization name.","classification":"","indexed":true}}},"string":{"label":"Simple attribute","description":"A single field primitive attribute","classification":"","fields":{"value":{"label":"Value","description":"","classification":"","indexed":true}}}},"relationship_types":{"linkage":{"label":"Linkage","label_from_source":"Linked into","label_from_target":"Linked from","description":"This is the built in linkage relationship type the matching engine creates between records and their resolved entities","cardinality":"ONE2MANY","directional":true}}}" 
Copy to clipboard

Example request

RecordType recordTypeModel = new RecordType.Builder()
  .label("testString")
  .build();
ReplaceConfiguratorConfigDataModelOptions replaceConfiguratorConfigDataModelOptions = new ReplaceConfiguratorConfigDataModelOptions.Builder()
  .build();

Response<ConfigDataModel> response = mdmService.replaceConfiguratorConfigDataModel(replaceConfiguratorConfigDataModelOptions).execute();
ConfigDataModel configDataModel = response.getResult();

System.out.println(configDataModel);
Copy to clipboard

Response

Response Body

ConfigDataModel

Collection of record and relationship types and system properties definition

ConfigDataModel

Collection of locale, record types, relationship types, system properties definition in configuration space.

Status Code

200
Config data model is replaced.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem replacing config data model. An internal error occurred while attempting to replace the config data model.

Example responses

Status 200

{
  "record_types": [
    {
      "name": "person",
      "default_display_name": "person",
      "properties": [
        {
          "name": "record_source",
          "data_type": "String",
          "default_display_name": "Record Source",
          "designation": "source"
        },
        {
          "name": "social_security_number",
          "data_type": "identification",
          "cardinality": "*",
          "default_display_name": "Social Security Number"
        }
      ],
      "source_systems": [
        {
          "name": "MDMSP",
          "default_display_name": "MDMS Person",
          "quality_factors": {
            "completeness": 100,
            "accuracy": 100,
            "correctness": 100,
            "age_relevancy": 100,
            "data_relevancy": 100,
            "consistency": 100
          }
        }
      ]
    }
  ],
  "data_types": [
    {
      "name": "identification",
      "default_display_name": "identification",
      "properties": [
        {
          "name": "identification",
          "data_type": "String",
          "default_display_name": "Identification Value"
        },
        {
          "name": "identification_number",
          "data_type": "String",
          "default_display_name": "Identification Number"
        }
      ]
    }
  ]
}
Copy to clipboard

Success example

{
  "record_types": [
    {
      "name": "person",
      "default_display_name": "person",
      "properties": [
        {
          "name": "record_source",
          "data_type": "String",
          "default_display_name": "Record Source",
          "designation": "source"
        },
        {
          "name": "social_security_number",
          "data_type": "identification",
          "cardinality": "*",
          "default_display_name": "Social Security Number"
        }
      ],
      "source_systems": [
        {
          "name": "MDMSP",
          "default_display_name": "MDMS Person",
          "quality_factors": {
            "completeness": 100,
            "accuracy": 100,
            "correctness": 100,
            "age_relevancy": 100,
            "data_relevancy": 100,
            "consistency": 100
          }
        }
      ]
    }
  ],
  "data_types": [
    {
      "name": "identification",
      "default_display_name": "identification",
      "properties": [
        {
          "name": "identification",
          "data_type": "String",
          "default_display_name": "Identification Value"
        },
        {
          "name": "identification_number",
          "data_type": "String",
          "default_display_name": "Identification Number"
        }
      ]
    }
  ]
}
Copy to clipboard

Gets the configuration health status.

GET /mdm/v1/configuration_health

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
target
string
a target of the health check, ie. fdb, rabbitmq

Default: all

Response

Response Body

ConfigurationHealth

Response object for get configuration api health

Status Code

200
Configuration ms health status is returned
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem getting configuration ms health status. An internal error occurred while attempting to get configuration ms health status

Example responses

Status 200

{
  "status": "healthy/unhealthy.",
  "severity": "info/critical.",
  "message": "Additional details of the configuration health status.",
}
Copy to clipboard

Export all configuration metadata to the folder path in shared volume

POST /mdm/v1/configuration_export

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Status Code

204
Successfully exported configuration metadata.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Fetch the current value of job status polling metadata. This is useful to debug the issues with auto resumption of matching/loading job after pod restart

GET /mdm/v1/job_status_polling_metadata/{process_name}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Path Parameters

process_name
Required*
string
The process name to proceed matching or loading

Example: matching

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

MatchingJobStatusPollingMetadata

Status Code

200
Fetched job status polling metadata successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Job status poling metadata do not exist in the system.
500
Unexpected error occured while fetching job status poling metadata.

Example responses

loading
matching

Replace job status polling metadata

PUT /mdm/v1/job_status_polling_metadata/{process_name}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Path Parameters

process_name
Required*
string
The process name to proceed matching or loading

Example: matching

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

PairDecisionCreateRequest

Request details for creating comparison record pair decision.

Examples:

Response

Response Body

PairDecision

Pair and corresponding user decision details.

Status Code

201
Job status polling metadata replaced successfully.
400
The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occurred in replacing Job status polling metadata.

No Sample Response

This method does not specify any sample responses.

Fetch existing mapping pattern.

GET /mdm/v1/mapping_pattern

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

MappingPattern

Response wrapper with details of Asset Mapping patterns.

Status Code

200
Fetched existing mapping pattern successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Mapping patterns do not exist in the system.
500
Unexpected error occured while fetching mapping patterns.

Example responses

Status 200

{
  "id": "config_1:4186180239988952",
  "last_update_date": "2024-04-12T06:11:09.000Z",
  "created_date": "2024-04-12T00:00:00.000Z",
  "mapping_patterns": [
    {
      "mapping_pattern_hash": "307e7a7d9757fb186ad8f106d4d92279e366b6c1f723b4de068f65a63d2303f3",
      "mapping_pattern_id": "436cbd13-fd5b-380d-bb2a-870cb64983e5",
      "mapping_pattern_name": "",
      "source_of_mapping": "config_metadata",
      "mapping_pattern_last_updated_date": "2024-01-05T15:28:12.000Z",
      "assets": [
        {
          "project_id": "",
          "asset_id": "",
          "asset_name": ""
        }
      ],
      "asset_record_type": "person",
      "asset_type": "person",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "data_mapping_name": "record_id",
          "exclude_column": false
        },
        {
          "key": "COLUMN2",
          "data_mapping_attribute_type": "person_name",
          "data_mapping_name": "legal_name.middle_name",
          "exclude_column": false
        }
      ]
    }
  ]
}
Copy to clipboard

Store/Replace mapping patterns.

PUT /mdm/v1/mapping_pattern

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

MappingPattern

Response wrapper with details of Asset Mapping patterns.

Examples:

Response

Response Body

MappingPattern

Response wrapper with details of Asset Mapping patterns.

Status Code

200
Stored/Replaced mapping pattern successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Unexpected error occured while storing/updating mapping patterns.

Example responses

Status 200

{
  "mapping_patterns": [
    {
      "mapping_pattern_hash": "307e7a7d9757fb186ad8f106d4d92279e366b6c1f723b4de068f65a63d2303f3",
      "mapping_pattern_id": "436cbd13-fd5b-380d-bb2a-870cb64983e5",
      "mapping_pattern_name": "",
      "source_of_mapping": "config_metadata",
      "mapping_pattern_last_updated_date": "2024-01-05T15:28:12.000Z",
      "assets": [
        {
          "project_id": "",
          "asset_id": "",
          "asset_name": ""
        }
      ],
      "asset_record_type": "person",
      "asset_type": "person",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "data_mapping_name": "record_id",
          "exclude_column": false
        },
        {
          "key": "COLUMN2",
          "data_mapping_attribute_type": "person_name",
          "data_mapping_name": "legal_name.middle_name",
          "exclude_column": false
        }
      ]
    }
  ]
}
Copy to clipboard

Gets the matching statistics (such as number of entities, entity size distributions, etc.) for the specified record type.

GET /mdm/v1/match_statistics

ServiceCall<MatchStatistics> getConfiguratorMatchingStatistics(GetConfiguratorMatchingStatisticsOptions getConfiguratorMatchingStatisticsOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Use the GetConfiguratorMatchingStatisticsOptions.Builder to create a GetConfiguratorMatchingStatisticsOptions object that contains the parameter values for the getConfiguratorMatchingStatistics method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
Record type of match statistics

Example: person
entity_type
Required*
string
Entity type of match statistics

Example: person_entity

GetConfiguratorMatchingStatisticsOptions

The getConfiguratorMatchingStatistics options.

Get matching statistics

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/match_statistics?record_type=person&entity_type=person_entity&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorMatchingStatisticsOptions getConfiguratorMatchingStatisticsOptions = new GetConfiguratorMatchingStatisticsOptions.Builder()
  .recordType("person")
  .entityType("person_entity")
  .build();

Response<MatchStatistics> response = mdmService.getConfiguratorMatchingStatistics(getConfiguratorMatchingStatisticsOptions).execute();
MatchStatistics matchStatistics = response.getResult();

System.out.println(matchStatistics);
Copy to clipboard

Response

Response Body

MatchStatistics

The Statistics of the match process results.

MatchStatistics

The Statistics of the match process results.

Status Code

200
Statistics retrieved
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Error occurred in get resource process. Resource does not exist
500
Error in fetching statistics

Example responses

Status 200

{
  "entity_breakdown": {
    "average": 2,
    "standard_deviation": 0,
    "variance": 0,
    "max": 4,
    "count": 500,
    "min": 1
  },
  "largest_entities": [
    {
      "entity_id": 40976536,
      "entity_size": 4
    }
  ],
  "entity_size_distribution": [
    {
      "entity_count": 5,
      "entity_size": 120
    }
  ],
  "summary": {
    "total_records": 2500,
    "singleton_count": 300,
    "distinct_sources": 4,
    "data_assets": 9,
    "entities_count": 950
  },
  "status": {
    "date_completed": {},
    "comparison_count": 120,
    "bucket_count": 9,
    "run_time": 159000
  }
}
Copy to clipboard

Success example

{
  "entity_breakdown": {
    "average": 2,
    "standard_deviation": 0,
    "variance": 0,
    "max": 4,
    "count": 500,
    "min": 1
  },
  "largest_entities": [
    {
      "entity_id": 40976536,
      "entity_size": 4
    }
  ],
  "entity_size_distribution": [
    {
      "entity_count": 5,
      "entity_size": 120
    }
  ],
  "summary": {
    "total_records": 2500,
    "singleton_count": 300,
    "distinct_sources": 4,
    "data_assets": 9,
    "entities_count": 950
  },
  "status": {
    "date_completed": {},
    "comparison_count": 120,
    "bucket_count": 9,
    "run_time": 159000
  }
}
Copy to clipboard

Lists the pair analysis for given tenant.

GET /mdm/v1/pair_analysis

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

PairAnalysisResponse

Status Code

200
Pair analysis is fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
The pair analysis for the given record and entity type not found.
500
Error in getting Pair analysis.

No Sample Response

This method does not specify any sample responses.

Adds a new pair analysis in configuration space. This allows to store result of tuning job with thresholds

POST /mdm/v1/pair_analysis

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

PairAnalysisResponse

Examples:

Response

Response Body

PairAnalysisResponse

Status Code

201
Pair Analysis created successfully.
400
Error in pair Analysis. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in creating asset for the given Pair analysis data.

No Sample Response

This method does not specify any sample responses.

This is a internal REST call.

DELETE /mdm/v1/pair_analysis

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Status Code

default
default response

No Sample Response

This method does not specify any sample responses.

Updates the pair analysis. Unknown attributes will be ignored

PATCH /mdm/v1/pair_analysis

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
Record type of comparison pair
entity_type
Required*
string
Entity type of comparison pair

Request Body

Required*

UpdatePairAnalysis

Examples:

Response

Response Body

UpdatePairAnalysis

Status Code

200
Pair analysis was updated successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
The pair analysis for the given record and entity type not found.
500
Error updating pair analysis.

No Sample Response

This method does not specify any sample responses.

Update the pair analysis and create pair decision.

PATCH /mdm/v1/pair_analysis/update_pair

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
Record type of comparison pair
entity_type
Required*
string
Entity type of comparison pair

Request Body

Required*

PairUpdateRequest

Request containing both pair decision and pair analysis data.

Examples:

Response

Response Body

PairUpdateRequest

Request containing both pair decision and pair analysis data.

Status Code

200
Pair analysis was updated and Pair decision was created successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
The pair analysis for the given record and entity type not found.
500
Error updating pair analysis and creating pair decision

No Sample Response

This method does not specify any sample responses.

Gets the pair analysis for given entity and record type.

GET /mdm/v1/pair_analysis/data

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
Record type of comparison pair
entity_type
Required*
string
Entity type of comparison pair

Response

Response Body

PairAnalysisResponse

Status Code

200
Pair analysis is fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
The pair analysis for the given record and entity type not found.
500
Error in getting Pair analysis.

No Sample Response

This method does not specify any sample responses.

Delete the comparison record pair decision.

DELETE /mdm/v1/pair_decisions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
Record type of comparison pair
entity_type
Required*
string
Entity type of comparison pair
record_number_1
string
Record identifier of comparison pair
record_number_2
string
Record identifier of comparison pair

Response

Status Code

204
Comparison record pair decision for given id is fetched successfullly.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Gets the configuration metadata with all assets, their mappings, loading status, matching status, etc.

GET /mdm/v1/configuration_metadata

ServiceCall<ConfigurationMetadata> getConfiguratorConfigurationMetadata(GetConfiguratorConfigurationMetadataOptions getConfiguratorConfigurationMetadataOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Use the GetConfiguratorConfigurationMetadataOptions.Builder to create a GetConfiguratorConfigurationMetadataOptions object that contains the parameter values for the getConfiguratorConfigurationMetadata method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Get configuration metadata

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorConfigurationMetadataOptions getConfiguratorConfigurationMetadataOptions = new GetConfiguratorConfigurationMetadataOptions();

Response<ConfigurationMetadata> response = mdmService.getConfiguratorConfigurationMetadata(getConfiguratorConfigurationMetadataOptions).execute();
ConfigurationMetadata configurationMetadata = response.getResult();

System.out.println(configurationMetadata);

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

ConfigurationMetadata

Configuration metadata details.

Status Code

200
configuration metadata for given id is fetched successfullly.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

Example responses

Status 200

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}
Copy to clipboard

Success example

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}
Copy to clipboard

Replaces the configuration metadata. It would replace the configuration data including asset information, matching attributes, etc.

PUT /mdm/v1/configuration_metadata

ServiceCall<ConfigurationMetadata> replaceConfiguratorConfigurationMetadata(ReplaceConfiguratorConfigurationMetadataOptions replaceConfiguratorConfigurationMetadataOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Use the ReplaceConfiguratorConfigurationMetadataOptions.Builder to create a ReplaceConfiguratorConfigurationMetadataOptions object that contains the parameter values for the replaceConfiguratorConfigurationMetadata method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

ConfigurationMetadata

Configuration metadata details.

Examples:

ReplaceConfiguratorConfigurationMetadataOptions

The replaceConfiguratorConfigurationMetadata options.

Replace configuration metadata

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"collaborators":"AP","storage_type":"Cloud storage","project_id":"0e4bb17d-4871-40a5-b5a1-55b2866fe000","catalog_id":"ee1de5f6-54da-4246-95bc-7bc282151000","description":"Example project","role":"admin","name":"Project 1"}" 
Copy to clipboard

Example request

ReplaceConfiguratorConfigurationMetadataOptions replaceConfiguratorConfigurationMetadataOptions = new ReplaceConfiguratorConfigurationMetadataOptions.Builder()
  .projectId("52a72453-597c-4fb3-a518-c815225e3ea9")
  .catalogId("8a3cc967-81c4-49a3-86a2-208059819b24")
  .description("sample configuration metadata")
  .name("configuration_metadata")
  .build();

Response<ConfigurationMetadata> response = mdmService.replaceConfiguratorConfigurationMetadata(replaceConfiguratorConfigurationMetadataOptions).execute();
ConfigurationMetadata configurationMetadata = response.getResult();

System.out.println(configurationMetadata);
Copy to clipboard

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

ConfigurationMetadata

Configuration metadata details.

Status Code

200
configuration metadata successfully replaced
400
Error in replacing configuration metadata. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in replacing configuration metadata.

Example responses

Status 200

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}
Copy to clipboard

Success example

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}
Copy to clipboard

Updates the configuration metadata with the information provided in the request.

PATCH /mdm/v1/configuration_metadata

ServiceCall<ConfigurationMetadata> updateConfiguratorConfigurationMetadata(UpdateConfiguratorConfigurationMetadataOptions updateConfiguratorConfigurationMetadataOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Use the UpdateConfiguratorConfigurationMetadataOptions.Builder to create a UpdateConfiguratorConfigurationMetadataOptions object that contains the parameter values for the updateConfiguratorConfigurationMetadata method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

ConfigurationMetadata

Configuration metadata details.

Examples:

UpdateConfiguratorConfigurationMetadataOptions

The updateConfiguratorConfigurationMetadata options.

Update configuration metadata

curl -X PATCH --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"collaborators":"AP","storage_type":"Cloud storage","project_id":"0e4bb17d-4871-40a5-b5a1-55b2866fe000","catalog_id":"ee1de5f6-54da-4246-95bc-7bc282151000","description":"Example project","role":"admin","name":"Project 1"}" 
Copy to clipboard

Example request

UpdateConfiguratorConfigurationMetadataOptions updateConfiguratorConfigurationMetadataOptions = new UpdateConfiguratorConfigurationMetadataOptions.Builder()
  .projectId("52a72453-597c-4fb3-a518-c815225e3ea9")
  .catalogId("8a3cc967-81c4-49a3-86a2-208059819b24")
  .description("sample configuration metadata")
  .name("configuration_metadata")
  .build();

Response<ConfigurationMetadata> response = mdmService.updateConfiguratorConfigurationMetadata(updateConfiguratorConfigurationMetadataOptions).execute();
ConfigurationMetadata configurationMetadata = response.getResult();

System.out.println(configurationMetadata);
Copy to clipboard

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

ConfigurationMetadata

Configuration metadata details.

Status Code

200
configuration metadata successfully updated
400
Error in updating configuration metadata. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in getting configuration metadata.

Example responses

Status 200

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}
Copy to clipboard

Success example

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}
Copy to clipboard

The previous algorithm for generating the mapping pattern has been replaced with new algorithm.The existing mapping pattern id in the project metadata should be regenerated by using the current mapping pattern id generation logic.

POST /mdm/v1/configuration_metadata/regenerate_mapping_pattern_id

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

ConfigurationMetadata

Configuration metadata details.

Status Code

200
The regeneration of the mapping pattern id has been completed successfully
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Unexpected error occurred during the regeneration of mapping pattern id.

Example responses

Status 200

{
  "name": "configuration_metadata",
  "description": "sample configuration metadata",
  "storage_type": "Cloud storage",
  "project_id": "52a72453-597c-4fb3-a518-c815225e3ea9",
  "catalog_id": "8a3cc967-81c4-49a3-86a2-208059819b24",
  "role": "admin",
  "collaborators": "AP",
  "assets": [
    {
      "asset_name": "person-100.csv",
      "asset_status": "Mapped",
      "asset_record_type": "Person",
      "asset_source": "project",
      "asset_mappings": [
        {
          "key": "COLUMN1",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_source",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        },
        {
          "key": "COLUMN2",
          "classified_class": "X",
          "data_mapping_name": "record_id",
          "data_mapping_default_display_name": "record_id",
          "exclude_column": "FALSE",
          "auto_mapped": true,
          "completeness_percent": "90"
        }
      ],
      "asset_id": "0777c0a7-9a3f-40a8-a094-c85091fa2ec7"
    }
  ]
}
Copy to clipboard

Lists the Configurator process details for all processes, optionally filtered by process status.

GET /mdm/v1/configuration_metadata/processes

ServiceCall<ProcessList> listConfiguratorProcesses(ListConfiguratorProcessesOptions listConfiguratorProcessesOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Use the ListConfiguratorProcessesOptions.Builder to create a ListConfiguratorProcessesOptions object that contains the parameter values for the listConfiguratorProcesses method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
status
string
Unique status param to get the processes based on it. i.e. Not-Initiated, In-progress, Complete and Error

Example: In-progress

ListConfiguratorProcessesOptions

The listConfiguratorProcesses options.

List the process details

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/processes?status=Complete&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListConfiguratorProcessesOptions listConfiguratorProcessesOptions = new ListConfiguratorProcessesOptions.Builder()
  .status("In-progress")
  .build();

Response<ProcessList> response = mdmService.listConfiguratorProcesses(listConfiguratorProcessesOptions).execute();
ProcessList processList = response.getResult();

System.out.println(processList);

Response

Response Body

ProcessList

Response wrapper with the list of Processes.

ProcessList

Response wrapper with the list of Processes.

Status Code

200
Processes retrieved.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting processes.

Example responses

Status 200

{
  "processes": [
    {
      "record_type_label": "Person",
      "record_type": "person",
      "process_name": "match",
      "process_count": "0",
      "message": "Match completed successfully and statistics updated.",
      "status": "Complete"
    }
  ]
}
Copy to clipboard

Success example

{
  "processes": [
    {
      "record_type_label": "Person",
      "record_type": "person",
      "process_name": "match",
      "process_count": "0",
      "message": "Match completed successfully and statistics updated.",
      "status": "Complete"
    }
  ]
}
Copy to clipboard

Create the Configurator process to publish data, publish model, match and delete assets.

POST /mdm/v1/configuration_metadata/processes

ServiceCall<ProcessStatus> createConfiguratorProcess(CreateConfiguratorProcessOptions createConfiguratorProcessOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Use the CreateConfiguratorProcessOptions.Builder to create a CreateConfiguratorProcessOptions object that contains the parameter values for the createConfiguratorProcess method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

ProcessRequest

Process creation request details.

Examples:

CreateConfiguratorProcessOptions

The createConfiguratorProcess options.

Add the process details

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/processes?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"process_name":"publish_data","asset_source_details":{"project":{"cos_endpoint":"https://s3.us-south.cloud-object-storage.appdomain.cloud","cos_bucket_name":"bucket-name","cos_api_key":"project_api_key"}},"initiator":"IAM ID" }" 
Copy to clipboard

Example request

ProcessRequestAssetSourceDetailsProject processRequestAssetSourceDetailsProjectModel = new ProcessRequestAssetSourceDetailsProject.Builder()
  .cosBucketName("bucket-name")
  .cosApiKey("project_api_key")
  .cosEndpoint("https://s3.us-south.cloud-object-storage.appdomain.cloud")
  .build();
ProcessRequestAssetSourceDetails processRequestAssetSourceDetailsModel = new ProcessRequestAssetSourceDetails.Builder()
  .project(processRequestAssetSourceDetailsProjectModel)
  .build();
CreateConfiguratorProcessOptions createConfiguratorProcessOptions = new CreateConfiguratorProcessOptions.Builder()
  .processName("publish_data")
  .assetSourceDetails(processRequestAssetSourceDetailsModel)
  .initiator("IAM ID")
  .build();

Response<ProcessStatus> response = mdmService.createConfiguratorProcess(createConfiguratorProcessOptions).execute();
ProcessStatus processStatus = response.getResult();

System.out.println(processStatus);
Copy to clipboard

Response

Response Body

ProcessStatus

Process Status.

ProcessStatus

Process Status.

Status Code

201
Process created successfully.
400
Error in process creation. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting processes.

Example responses

Status 201

{
  "status": "In-Progress_bulkderive",
  "message": "Matching is in progress."
}
Copy to clipboard

Success example

{
  "status": "In-Progress_bulkderive",
  "message": "Matching is in progress."
}
Copy to clipboard

Status 201

{
  "status": "In-progress",
  "message": "Publish model is initiated."
}
Copy to clipboard

Success example

{
  "status": "In-progress",
  "message": "Publish model is initiated."
}
Copy to clipboard

Status 201

{
  "status": "In-progress",
  "message": "Import Snapshot is initiated."
}
Copy to clipboard

Success example

{
  "status": "In-progress",
  "message": "Import Snapshot is initiated."
}
Copy to clipboard

Status 201

{
  "status": "In-progress",
  "message": "Asset Deletion is initiated!",
  "summary": {
    "asset_id_1": "Delete-in-progress"
  }
}
Copy to clipboard

Success example

{
  "status": "In-progress",
  "message": "Asset Deletion is initiated!",
  "summary": {
    "asset_id_1": "Delete-in-progress"
  }
}
Copy to clipboard

Status 201

{
  "message": "Bulk load of data is initiated.",
  "status": "In-progress"
}
Copy to clipboard

Success example

{
  "message": "Bulk load of data is initiated.",
  "status": "In-progress"
}
Copy to clipboard

Replaces asset information in the configuration with the information provided in the request.

PUT /mdm/v1/configuration_metadata/assets/{asset_id}

ServiceCall<AssetMetadata> replaceConfiguratorConfigurationAsset(ReplaceConfiguratorConfigurationAssetOptions replaceConfiguratorConfigurationAssetOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Use the ReplaceConfiguratorConfigurationAssetOptions.Builder to create a ReplaceConfiguratorConfigurationAssetOptions object that contains the parameter values for the replaceConfiguratorConfigurationAsset method.

Path Parameters

asset_id
Required*
string
Unique identifier of project asset

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

AssetMetadataUpdateRequest

Request object for updating an asset.

Examples:

ReplaceConfiguratorConfigurationAssetOptions

The replaceConfiguratorConfigurationAsset options.

Replace configuration metadata asset

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/assets/d8868c51-a96e-48ab-a4cd-0000000?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"asset_created_date":"{}","asset_mappings":[{"exclude_column":false,"auto_mapped":true,"completeness_percent":100,"data_mapping_default_display_name":"Record Source","classified_class":"GEN","data_mapping_name":"gender","key":"COLUMN 1"}],"asset_name":"Person10k.csv","asset_status":"Mapped","asset_record_type":"Person"}" 
Copy to clipboard

Example request

AssetMapping assetMappingModel = new AssetMapping.Builder()
  .completenessPercent("100")
  .dataMappingName("record_source")
  .excludeColumn(false)
  .autoMapped(false)
  .classifiedClass("X")
  .key("COLUMN1")
  .build();
ReplaceConfiguratorConfigurationAssetOptions replaceConfiguratorConfigurationAssetOptions = new ReplaceConfiguratorConfigurationAssetOptions.Builder()
  .assetId("testString")
  .assetName("Person10.csv")
  .assetStatus("Mapped")
  .assetCreatedDate("2020-05-12 13:21:21.727000+00:00")
  .assetMappings(new java.util.ArrayList<AssetMapping>(java.util.Arrays.asList(assetMappingModel)))
  .build();

Response<AssetMetadata> response = mdmService.replaceConfiguratorConfigurationAsset(replaceConfiguratorConfigurationAssetOptions).execute();
AssetMetadata assetMetadata = response.getResult();

System.out.println(assetMetadata);
Copy to clipboard

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

200
Asset replaced successfully.
400
Error in replacing asset. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in replacing asset for the given configuration metadata.

Example responses

Status 200

{
  "asset_name": "Person10.csv",
  "asset_status": "Mapped",
  "asset_record_type": "Person",
  "asset_created_date": {},
  "asset_mappings": [
    {
      "key": "COLUMN1",
      "classified_class": "X",
      "data_mapping_name": "record_source",
      "data_mapping_default_display_name": "Record Source",
      "exclude_column": false,
      "auto_mapped": false,
      "completeness_percent": 100
    },
    {
      "key": "COLUMN2",
      "classified_class": "T",
      "data_mapping_name": "",
      "data_mapping_default_display_name": "",
      "exclude_column": true,
      "auto_mapped": false,
      "completeness_percent": 100
    }
  ],
  "asset_id": "asset_id",
  "asset_last_updated_date": "2021-05-17T19:00:34.000Z"
}
Copy to clipboard

Success example

{
  "asset_name": "Person10.csv",
  "asset_status": "Mapped",
  "asset_record_type": "Person",
  "asset_created_date": {},
  "asset_mappings": [
    {
      "key": "COLUMN1",
      "classified_class": "X",
      "data_mapping_name": "record_source",
      "data_mapping_default_display_name": "Record Source",
      "exclude_column": false,
      "auto_mapped": false,
      "completeness_percent": 100
    },
    {
      "key": "COLUMN2",
      "classified_class": "T",
      "data_mapping_name": "",
      "data_mapping_default_display_name": "",
      "exclude_column": true,
      "auto_mapped": false,
      "completeness_percent": 100
    }
  ],
  "asset_id": "asset_id",
  "asset_last_updated_date": "2021-05-17T19:00:34.000Z"
}
Copy to clipboard

Update the asset fields in the configuration metadata with the information provided in the request. Only the fields given in the request will be updated.

PATCH /mdm/v1/configuration_metadata/assets/{asset_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Path Parameters

asset_id
Required*
string
Unique identifier of project asset

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

AssetMetadataPatchRequest

Request object for updating an asset.

Examples:

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

200
Asset fields updated successfully.
400
Error in updating the asset. The request is invalid. Please revalidate the input and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occurred in updating the asset for the given asset id.

Example responses

Status 200

{
  "asset_name": "Person10.csv",
  "asset_status": "Mapped",
  "asset_record_type": "Person",
  "asset_created_date": {},
  "asset_mappings": [
    {
      "key": "COLUMN1",
      "classified_class": "X",
      "data_mapping_name": "record_source",
      "data_mapping_default_display_name": "Record Source",
      "exclude_column": false,
      "auto_mapped": false,
      "completeness_percent": 100
    },
    {
      "key": "COLUMN2",
      "classified_class": "T",
      "data_mapping_name": "",
      "data_mapping_default_display_name": "",
      "exclude_column": true,
      "auto_mapped": false,
      "completeness_percent": 100
    }
  ],
  "asset_id": "asset_id",
  "asset_last_updated_date": "2021-05-17T19:00:34.000Z"
}
Copy to clipboard

Gets the process details for the specified process name.

GET /mdm/v1/configuration_metadata/processes/{process_name}

ServiceCall<ProcessModelStatus> getConfiguratorProcess(GetConfiguratorProcessOptions getConfiguratorProcessOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Use the GetConfiguratorProcessOptions.Builder to create a GetConfiguratorProcessOptions object that contains the parameter values for the getConfiguratorProcess method.

Path Parameters

process_name
Required*
string
Unique process name to get the process status. i.e. publish_model, publish_data, match, delete_asset and import_snapshot

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
string
Unique record type associated with the process

Example: person
entity_type
string
Unique entity type associated with the process

Example: person_entity

GetConfiguratorProcessOptions

The getConfiguratorProcess options.

Get configurator process

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/processes/publish_model?record_type=person&entity_type=person_entity&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorProcessOptions getConfiguratorProcessOptions = new GetConfiguratorProcessOptions.Builder()
  .processName("testString")
  .recordType("person")
  .entityType("person_entity")
  .build();

Response<ProcessModelStatus> response = mdmService.getConfiguratorProcess(getConfiguratorProcessOptions).execute();
ProcessModelStatus processModelStatus = response.getResult();

System.out.println(processModelStatus);
Copy to clipboard

Response

Response Body

ProcessModelStatus

Details of the Process.

ProcessModelStatus

Details of the Process.

Status Code

200
Process retrieved.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem processing request. Please check if you have provided correct process name.
500
Error in getting process.

Example responses

Status 200

{
  "record_type_label": "Person",
  "record_type": "person",
  "process_name": "match",
  "process_count": "0",
  "message": "Match completed successfully and statistics updated.",
  "status": "Complete"
}
Copy to clipboard

Success example

{
  "record_type_label": "Person",
  "record_type": "person",
  "process_name": "match",
  "process_count": "0",
  "message": "Match completed successfully and statistics updated.",
  "status": "Complete"
}
Copy to clipboard

Adds a new asset in configuration metadata. This can be called when new asset is getting added into configuration space.

POST /mdm/v1/configuration_metadata/assets

ServiceCall<AssetMetadata> addConfiguratorConfigurationAsset(AddConfiguratorConfigurationAssetOptions addConfiguratorConfigurationAssetOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Use the AddConfiguratorConfigurationAssetOptions.Builder to create a AddConfiguratorConfigurationAssetOptions object that contains the parameter values for the addConfiguratorConfigurationAsset method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

AssetMetadataCreateRequest

Request details for creating new Data Asset.

Examples:

AddConfiguratorConfigurationAssetOptions

The addConfiguratorConfigurationAsset options.

Add configuration metadata asset

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/configuration_metadata/assets?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"asset_created_date":"{}","asset_mappings":[{"exclude_column":false,"auto_mapped":true,"completeness_percent":100,"data_mapping_default_display_name":"Record Source","classified_class":"GEN","data_mapping_name":"gender","key":"COLUMN 1"}],"asset_id":"d8868c51-a96e-48ab-a4cd-0000000","asset_name":"Person10k.csv","asset_status":"Mapped","asset_record_type":"Person"}" 
Copy to clipboard

Example request

AssetMapping assetMappingModel = new AssetMapping.Builder()
  .completenessPercent("100")
  .dataMappingName("record_source")
  .excludeColumn(false)
  .autoMapped(false)
  .classifiedClass("X")
  .key("COLUMN1")
  .build();
AddConfiguratorConfigurationAssetOptions addConfiguratorConfigurationAssetOptions = new AddConfiguratorConfigurationAssetOptions.Builder()
  .assetId("asset_id")
  .assetName("Person10.csv")
  .assetStatus("Mapped")
  .assetCreatedDate("2020-05-12 13:21:21.727000+00:00")
  .assetMappings(new java.util.ArrayList<AssetMapping>(java.util.Arrays.asList(assetMappingModel)))
  .build();

Response<AssetMetadata> response = mdmService.addConfiguratorConfigurationAsset(addConfiguratorConfigurationAssetOptions).execute();
AssetMetadata assetMetadata = response.getResult();

System.out.println(assetMetadata);
Copy to clipboard

Response

Response Body

AssetMetadata

Response wrapper with details of Data Asset Metadata.

AssetMetadata

Response wrapper with details of Data Asset Metadata.

Status Code

201
Asset created successfully.
400
Error in created asset. The request you used is invalid. Please revalidate and try again.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Internal error occured in creating asset for the given configuration metadata.

Example responses

Status 201

{
  "asset_id": "asset_id",
  "asset_name": "Person10.csv",
  "asset_status": "Mapped",
  "asset_record_type": "Person",
  "asset_created_date": {},
  "asset_mappings": [
    {
      "key": "COLUMN1",
      "classified_class": "X",
      "data_mapping_name": "record_source",
      "data_mapping_default_display_name": "Record Source",
      "exclude_column": false,
      "auto_mapped": false,
      "completeness_percent": 100
    },
    {
      "key": "COLUMN2",
      "classified_class": "T",
      "data_mapping_name": "",
      "data_mapping_default_display_name": "",
      "exclude_column": true,
      "auto_mapped": false,
      "completeness_percent": 100
    }
  ],
  "asset_last_updated_date": "2021-05-17T18:58:59.000Z"
}
Copy to clipboard

Success example

{
  "asset_id": "asset_id",
  "asset_name": "Person10.csv",
  "asset_status": "Mapped",
  "asset_record_type": "Person",
  "asset_created_date": {},
  "asset_mappings": [
    {
      "key": "COLUMN1",
      "classified_class": "X",
      "data_mapping_name": "record_source",
      "data_mapping_default_display_name": "Record Source",
      "exclude_column": false,
      "auto_mapped": false,
      "completeness_percent": 100
    },
    {
      "key": "COLUMN2",
      "classified_class": "T",
      "data_mapping_name": "",
      "data_mapping_default_display_name": "",
      "exclude_column": true,
      "auto_mapped": false,
      "completeness_percent": 100
    }
  ],
  "asset_last_updated_date": "2021-05-17T18:58:59.000Z"
}
Copy to clipboard

Resets configuration to original state.

POST /mdm/v1/reset_configuration

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Status Code

201
The reset was successfully performed and the metadata store is cleared.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem resetting metadata. An internal error occurred while attempting to reset.

No Sample Response

This method does not specify any sample responses.

GET /mdm/v1/matching/version

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

object

Status Code

200
The version check was successfully performed.
500
Problem getting version. An internal error occurred while attempting to determine the version.

No Sample Response

This method does not specify any sample responses.

Get version properties from config map. It will contain the running version of the service

GET /mdm/v1/data/version

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

SystemLiveness

Whether the system is live or not.

Status Code

200
The version properties has been retrieved successfully
500
An internal error occurred while retrieving the version properties.
503
Service is not available and can not perform the operation now

No Sample Response

This method does not specify any sample responses.

GET /mdm/v1/model/version

Request

No Request Parameters

This method does not accept any request parameters.

Response

Response Body

object

Status Code

200
The version check was successfully performed.
500
Problem getting version. An internal error occurred while attempting to determine the version.

No Sample Response

This method does not specify any sample responses.

Get snapshot by Id

GET /mdm/v1/snapshots/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Path Parameters

id
Required*
string
Id of the snapshot

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

SnapshotDetailedResponse

Response wrapper with the details of the snapshot

Status Code

200
Snapshot with given id is fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

This service updates the name and description of a snapshot.

PUT /mdm/v1/snapshots/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Path Parameters

id
Required*
string
The unique identifier of a snapshot

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

UpdateSnapshotSummary

Request wrapper object for snapshot summary of model assets

Response

Response Body

UpdateSnapshotSummary

Request wrapper object for snapshot summary of model assets

Status Code

200
The snapshot has been successfully updated.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

No Sample Response

This method does not specify any sample responses.

delete snapshot by Id

DELETE /mdm/v1/snapshots/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Path Parameters

id
Required*
string
Id of the snapshot

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

SnapshotDetailedResponse

Response wrapper with the details of the snapshot

Status Code

200
Snapshot with given id is deleted successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

Get snapshots

GET /mdm/v1/snapshots

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

SnapshotListResponse

Response wrapper with the list of Snapshots.

Status Code

200
Snapshots are fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

No Sample Response

This method does not specify any sample responses.

This service creates a snapshot of current config assets.

POST /mdm/v1/snapshots

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

SnapshotSummaryRequest

Request wrapper object for post a snapshot of model assets

Examples:

Response

Response Body

SnapshotSummaryRequest

Request wrapper object for post a snapshot of model assets

Status Code

201
The snapshot of model assets has been successfully created.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

No Sample Response

This method does not specify any sample responses.

Compare snapshot

PUT /mdm/v1/snapshots/compare

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

SnapshotCompareRequest

Request wrapper with the details of the snapshot for comparison with current configuration

Examples:

Response

Response Body

SnapshotCompareResponse

Response wrapper with the details of the snapshot comparison with current configuration

Status Code

200
Snapshot comparison is generated and fetched successfully.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error in getting configuration metadata.

Example responses

Status 200

{
  "data_model": {
    "attribute_types": {
      "address": {
        "matching_types": {
          "__current": [
            "ADDRESS"
          ],
          "__incoming": [
            "ADDRESS"
          ],
          "__change": "unchanged"
        },
        "description": {
          "__current": "The address locations associated with a record.",
          "__incoming": "The address locations associated with a record type.",
          "__change": "modified"
        },
        "label": {
          "__current": "Address",
          "__incoming": "Address",
          "__change": "unchanged"
        },
        "classification": {
          "__current": "",
          "__incoming": "",
          "__change": "unchanged"
        },
        "fields": {
          "country": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "The country of this address.",
              "__incoming": "The country of this address.",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Country value",
              "__incoming": "Country value",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 4,
            "__change": "unchanged"
          },
          "address_line1": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "The first line of this address.",
              "__incoming": "The first line of this address.",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Address line 1",
              "__incoming": "Address line 1",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 4,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 2,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 1,
        "__unchanged": 4,
        "__change": "modified"
      },
      "string": {
        "description": {
          "__current": "A single field primitive attribute",
          "__incoming": "A single field primitive attribute",
          "__change": "unchanged"
        },
        "label": {
          "__current": "Simple attribute",
          "__incoming": "Simple attribute",
          "__change": "unchanged"
        },
        "classification": {
          "__current": "",
          "__incoming": "",
          "__change": "unchanged"
        },
        "fields": {
          "value": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Value",
              "__incoming": "Value",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 4,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 4,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 1,
      "__unchanged": 1,
      "__change": "modified"
    },
    "system_properties": {
      "attribute_types": {
        "attribute_last_updated": {
          "settable": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "indexed": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "editable": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "data_type": {
            "__current": "Long",
            "__incoming": "Long",
            "__change": "unchanged"
          },
          "description": {
            "__current": "The time an attribute was last updated",
            "__incoming": "The time an attribute was last updated",
            "__change": "unchanged"
          },
          "label": {
            "__current": "Attribute last updated date",
            "__incoming": "Attribute last updated date",
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 6,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 1,
        "__change": "unchanged"
      },
      "entity_types": {
        "entity_id": {
          "indexed": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "editable": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "data_type": {
            "__current": "String",
            "__incoming": "String",
            "__change": "unchanged"
          },
          "description": {
            "__current": "",
            "__incoming": "",
            "__change": "unchanged"
          },
          "label": {
            "__current": "Entity identifier",
            "__incoming": "Entity identifier",
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 5,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 1,
        "__change": "unchanged"
      },
      "relationship_types": {
        "from_record_id": {
          "settable": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "editable": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "data_type": {
            "__current": "String",
            "__incoming": "String",
            "__change": "unchanged"
          },
          "description": {
            "__current": "The record id this relationship is coming from",
            "__incoming": "The record id this relationship is coming from",
            "__change": "unchanged"
          },
          "label": {
            "__current": "From record id",
            "__incoming": "From record id",
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 5,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 1,
        "__change": "unchanged"
      },
      "version": {
        "__current": "v3",
        "__incoming": "v3",
        "__change": "unchanged"
      },
      "record_types": {
        "collection_id": {
          "settable": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "indexed": {
            "__current": true,
            "__incoming": true,
            "__change": "unchanged"
          },
          "editable": {
            "__current": false,
            "__incoming": false,
            "__change": "unchanged"
          },
          "data_type": {
            "__current": "String",
            "__incoming": "String",
            "__change": "unchanged"
          },
          "description": {
            "__current": "Optional identifier for identifying a collection of records",
            "__incoming": "Optional identifier for identifying a collection of records",
            "__change": "unchanged"
          },
          "label": {
            "__current": "Collection ID",
            "__incoming": "Collection ID",
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 6,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 1,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 0,
      "__unchanged": 5,
      "__change": "unchanged"
    },
    "relationship_types": {
      "linkage": {
        "internal": {
          "__current": true,
          "__incoming": true,
          "__change": "unchanged"
        },
        "label_from_source": {
          "__current": "Linked into",
          "__incoming": "Linked into",
          "__change": "unchanged"
        },
        "label_from_target": {
          "__current": "Linked from",
          "__incoming": "Linked from",
          "__change": "unchanged"
        },
        "directional": {
          "__current": true,
          "__incoming": true,
          "__change": "unchanged"
        },
        "description": {
          "__current": "This is the built in linkage relationship type",
          "__incoming": "This is the built in linkage relationship type",
          "__change": "unchanged"
        },
        "label": {
          "__current": "Linkage",
          "__incoming": "Linkage",
          "__change": "unchanged"
        },
        "cardinality": {
          "__current": "ONE2MANY",
          "__incoming": "ONE2MANY",
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 7,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 0,
      "__unchanged": 1,
      "__change": "unchanged"
    },
    "locale": {
      "__current": "en_us",
      "__incoming": "en_us",
      "__change": "unchanged"
    },
    "record_types": {
      "person": {
        "entity_types": {
          "person_entity": {
            "default": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "The entity type for person records.",
              "__incoming": "The entity type for person records.",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Person entity",
              "__incoming": "Person entity",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 3,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "description": {
          "__current": "The record type for person records.",
          "__incoming": "The record type for person records.",
          "__change": "unchanged"
        },
        "attributes": {
          "primary_residence": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "Indicates that this address is a primary residence.",
              "__incoming": "Indicates that this address is a primary residence.",
              "__change": "unchanged"
            },
            "attribute_type": {
              "__current": "address",
              "__incoming": "address",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Primary residence",
              "__incoming": "Primary residence",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "cardinality": {
              "__current": "LIST",
              "__incoming": "LIST",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 6,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "label": {
          "__current": "Person",
          "__incoming": "Person",
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 4,
        "__change": "unchanged"
      },
      "organization": {
        "entity_types": {
          "organization_entity": {
            "default": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "The entity type for org records.",
              "__incoming": "The entity type for org records.",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Organization entity",
              "__incoming": "Organization entity",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 3,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "description": {
          "__current": "The record type for organization records.",
          "__incoming": "The record type for organization records.",
          "__change": "unchanged"
        },
        "attributes": {
          "mailing_address": {
            "indexed": {
              "__current": true,
              "__incoming": true,
              "__change": "unchanged"
            },
            "description": {
              "__current": "Indicates that this address is a mailing address.",
              "__incoming": "Indicates that this address is a mailing address.",
              "__change": "unchanged"
            },
            "attribute_type": {
              "__current": "address",
              "__incoming": "address",
              "__change": "unchanged"
            },
            "label": {
              "__current": "Mailing address",
              "__incoming": "Mailing address",
              "__change": "unchanged"
            },
            "classification": {
              "__current": "",
              "__incoming": "",
              "__change": "unchanged"
            },
            "cardinality": {
              "__current": "LIST",
              "__incoming": "LIST",
              "__change": "unchanged"
            },
            "__added": 0,
            "__removed": 0,
            "__modified": 0,
            "__unchanged": 6,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "label": {
          "__current": "Organization",
          "__incoming": "Organization",
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 4,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 0,
      "__unchanged": 2,
      "__change": "unchanged"
    },
    "__added": 0,
    "__removed": 0,
    "__modified": 1,
    "__unchanged": 4,
    "__change": "modified"
  },
  "match_settings": {
    "person": {
      "person_entity": {
        "matching_thresholds": {
          "clerical_review_threshold": {
            "__current": 8,
            "__incoming": 8,
            "__change": "unchanged"
          },
          "auto_link_threshold": {
            "__current": 8,
            "__incoming": 8,
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 2,
          "__change": "unchanged"
        },
        "matching_attributes": {
          "__current": [
            {
              "name": "mailing_address",
              "data_type": "address"
            }
          ],
          "__incoming": [
            {
              "name": "mailing_address",
              "data_type": "address"
            }
          ],
          "__change": "unchanged"
        },
        "matching_fields": {
          "address": {
            "__current": [
              "address_line1",
              "country"
            ],
            "__incoming": [
              "address_line1",
              "country"
            ],
            "__change": "unchanged"
          },
          "__added": 0,
          "__removed": 0,
          "__modified": 0,
          "__unchanged": 1,
          "__change": "unchanged"
        },
        "__added": 0,
        "__removed": 0,
        "__modified": 0,
        "__unchanged": 3,
        "__change": "unchanged"
      },
      "__added": 0,
      "__removed": 0,
      "__modified": 0,
      "__unchanged": 1,
      "__change": "unchanged"
    },
    "__added": 0,
    "__removed": 0,
    "__modified": 0,
    "__unchanged": 1,
    "__change": "unchanged"
  },
  "__added": 0,
  "__removed": 0,
  "__modified": 1,
  "__unchanged": 1,
  "__change": "modified"
}
Copy to clipboard

Suggest data mappings from MDM data model based on the generic classes of IBM Knowledge Catalog with which the asset is profiled.

Suggest data mappings from MDM data model based on the generic classes of Watson Knowledge Catalog with which the asset is profiled.

POST /mdm/v1/suggest_data_mappings

ServiceCall<SuggestedDataMapping> suggestConfiguratorDataMappings(SuggestConfiguratorDataMappingsOptions suggestConfiguratorDataMappingsOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Use the SuggestConfiguratorDataMappingsOptions.Builder to create a SuggestConfiguratorDataMappingsOptions object that contains the parameter values for the suggestConfiguratorDataMappings method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
Record type for data mapping suggestions

Example: person

Request Body

Required*

SuggestedDataMappingRequest

Suggested Data Mapping Request details.

Examples:

SuggestConfiguratorDataMappingsOptions

The suggestConfiguratorDataMappings options.

Suggest data mappings

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/suggest_data_mappings?record_type=person&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

DataMapping dataMappingModel = new DataMapping.Builder()
  .classifiedClass("X")
  .key("COLUMN1")
  .build();
SuggestConfiguratorDataMappingsOptions suggestConfiguratorDataMappingsOptions = new SuggestConfiguratorDataMappingsOptions.Builder()
  .recordType("person")
  .columns(new java.util.ArrayList<DataMapping>(java.util.Arrays.asList(dataMappingModel)))
  .build();

Response<SuggestedDataMapping> response = mdmService.suggestConfiguratorDataMappings(suggestConfiguratorDataMappingsOptions).execute();
SuggestedDataMapping suggestedDataMapping = response.getResult();

System.out.println(suggestedDataMapping);
Copy to clipboard

Response

Response Body

SuggestedDataMapping

Response wrapper with details of Suggested Data Mappings.

SuggestedDataMapping

Response wrapper with details of Suggested Data Mappings.

Status Code

200
Suggested mappings are fetched
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Unexpected error occured while getting data mappings.

Example responses

Status 200

{
  "suggested_data_mappings": [
    {
      "data_mapping_default_display_name": "Gender",
      "data_mapping_name": "gender",
      "classified_class": "GEN",
      "key": "COLUMN 1"
    }
  ]
}
Copy to clipboard

Success example

{
  "suggested_data_mappings": [
    {
      "data_mapping_default_display_name": "Gender",
      "data_mapping_name": "gender",
      "classified_class": "GEN",
      "key": "COLUMN 1"
    }
  ]
}
Copy to clipboard

Gets suggested matching attributes for the record type based on mappings of assets of the specified record type.

GET /mdm/v1/suggested_matching_attributes

ServiceCall<SuggestedMatchAttributes> getConfiguratorSuggestedMatchingAttributes(GetConfiguratorSuggestedMatchingAttributesOptions getConfiguratorSuggestedMatchingAttributesOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.configurator.read

Request

Use the GetConfiguratorSuggestedMatchingAttributesOptions.Builder to create a GetConfiguratorSuggestedMatchingAttributesOptions object that contains the parameter values for the getConfiguratorSuggestedMatchingAttributes method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
Record type for matching attribute suggestions

GetConfiguratorSuggestedMatchingAttributesOptions

The getConfiguratorSuggestedMatchingAttributes options.

Suggests matching attributes

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/suggested_matching_attributes?record_type=person&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetConfiguratorSuggestedMatchingAttributesOptions getConfiguratorSuggestedMatchingAttributesOptions = new GetConfiguratorSuggestedMatchingAttributesOptions.Builder()
  .recordType("testString")
  .build();

Response<SuggestedMatchAttributes> response = mdmService.getConfiguratorSuggestedMatchingAttributes(getConfiguratorSuggestedMatchingAttributesOptions).execute();
SuggestedMatchAttributes suggestedMatchAttributes = response.getResult();

System.out.println(suggestedMatchAttributes);

Response

Response Body

SuggestedMatchAttributes

Response wrapper for attributes suggested for running match process.

SuggestedMatchAttributes

Response wrapper for attributes suggested for running match process.

Status Code

200
Suggested matching attributes are retrieved
400
Project assets are missing or in invalid state.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Error occured while getting suggested matching attributes.

Example responses

Status 200

{
  "suggested_matching_attributes": [
    {
      "matching_attribute_default_display_name": "Gender",
      "matching_attribute_name": "gender"
    }
  ]
}
Copy to clipboard

Success example

{
  "suggested_matching_attributes": [
    {
      "matching_attribute_default_display_name": "Gender",
      "matching_attribute_name": "gender"
    }
  ]
}
Copy to clipboard

This service initiates asynchronous processing of the weight tuning job.
Weight tuning is the process to improve the weight for the matching algorithm based on given set of match decisions from data stewards.

This service initiates asynchronous processing of the weight tuning job.
Weight tuning is the process to improve the weight for the matching algorithm based on given set of match decisions from data stewards.

POST /mdm/v1/weight_tuning_job

ServiceCall<TuningJobResponse> createWeightTuningJob(CreateWeightTuningJobOptions createWeightTuningJobOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.manage

Request

Use the CreateWeightTuningJobOptions.Builder to create a CreateWeightTuningJobOptions object that contains the parameter values for the createWeightTuningJob method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
Record type of match statistics

Example: person
entity_type
Required*
string
Entity type of match statistics

Example: person_entity

CreateWeightTuningJobOptions

The createWeightTuningJob options.

Example request

CreateWeightTuningJobOptions createWeightTuningJobOptions = new CreateWeightTuningJobOptions.Builder()
  .recordType("person")
  .entityType("person_entity")
  .build();

Response<TuningJobResponse> response = mdmService.createWeightTuningJob(createWeightTuningJobOptions).execute();
TuningJobResponse tuningJobResponse = response.getResult();

System.out.println(tuningJobResponse);
Copy to clipboard

Response

Response Body

TuningJobResponse

Response object for asynchronous processing of a tuning job

TuningJobResponse

Response object for asynchronous processing of a tuning job.

Status Code

201
The weight tuning job has been successfully created.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 201

{
  "created_at": "",
  "image": "mdm-tuning-job",
  "job_name": "weight-tuning",
  "last_updated_at": "",
  "id": "2ba3ed28-00c7-42e4-9cc9-8c74bf5e4ff0",
  "input": {},
  "status": "Running"
}
Copy to clipboard

Success example

{
  "created_at": "",
  "image": "mdm-tuning-job",
  "job_name": "weight-tuning",
  "last_updated_at": "",
  "id": "2ba3ed28-00c7-42e4-9cc9-8c74bf5e4ff0",
  "input": {},
  "status": "Running"
}
Copy to clipboard

Get version properties from config map. It will contain the running version of the service

GET /mdm/v1/configuration/version

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

200
The version properties has been retrieved successfully
500
An internal error occurred while retrieving the version properties.
503
Service is not available and can not perform the operation now

No Sample Response

This method does not specify any sample responses.

Get version properties from config map. It will contain the running version of the service

GET /mdm/job/version

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

200
The version properties has been retrieved successfully
500
An internal error occurred while retrieving the version properties.
503
Service is not available and can not perform the operation now

No Sample Response

This method does not specify any sample responses.

This service initiates asynchronous processing of the export rules job.

POST /mdm/v1/bulk_export_linkage_rules

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
do_wait
boolean
Wait for job finish, default is false

Default: false
executor_count
integer
The number of spark executors

Example: 1
executor_memory
string
Amount of memory to use per executor process

Example: 8g
executor_core_count
integer
The number of cores to use on each executor

Example: 1
spark_parallelism
integer
The number of partitions to be used by spark

Example: 2

Request Body

Required*

PostExportRulesRequest

The wrapper object for export manual rules request body

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "job_id": "",
  "exit_code": 0,
  "arguments": "runExportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}
Copy to clipboard

This service initiates asynchronous processing of the match job.
Matching is the process to compare two or more records and create linkages between the matched records.

This service initiates asynchronous processing of the match job.
Matching is the process to compare two or more records and create linkages between the matched records.

POST /mdm/v1/bulk_match

ServiceCall<PostCloudJob> createMatchingMatchJob(CreateMatchingMatchJobOptions createMatchingMatchJobOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.manage

Request

Use the CreateMatchingMatchJobOptions.Builder to create a CreateMatchingMatchJobOptions object that contains the parameter values for the createMatchingMatchJob method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
The data type identifier of source records, ie. person, organization, contract

Example: person
entity_type
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: person_entity
do_force
boolean
Force to re-match all records, default is false

Default: false
do_deduplicate
boolean
Deduplicate pairs, default is false

Default: false
do_analytics
boolean
collect analysis report, default is false

Default: false
do_replicate
boolean
Replicate entity id, default is true

Default: true
do_checkpoint
boolean
Do checkpoint

Default: false
resume_from_driver
boolean
Resume from step copying entity id, default is false

Default: false
pairs_per_score
string
The maximum number of pairs to be retained for pair review.

Default: 1000
Example: 1000
sampling_dense_region
string
The distance from the clerical review and autolink thresholds that have increased pair sampling. A value of 10 indicates that there will be more sample pairs with matching scores within 10 points of either threshold.

Default: 10
Example: 10
sampling_population_factor
string
The factor by which pair sampling will increase for pairs that fall within the area defined by sampling_dense_region.

Default: 2
Example: 2
executor_count
integer
The number of spark executors

Example: 1
executor_memory
string
Amount of memory to use per executor process

Example: 8g
executor_core_count
integer
The number of cores to use on each executor

Example: 1
spark_parallelism
integer
The number of partitions to be used by spark

Example: 2
log_cos_endpoint
string
IBM COS end point for job log storage.

Example: http://s3.us-south.cloud-object-storage.appdomain.cloud
log_cos_bucket
string
IBM COS bucket for job log storage.

Example: mdmdata
log_cos_access_key
string
IBM COS access key for spark log storage

Example: b33037e4e8954207a434cc032c1139d1
log_cos_secret_key
string
IBM COS secret key for spark log storage

Example: <hex string>

CreateMatchingMatchJobOptions

The createMatchingMatchJob options.

Initiate match job

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_match?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&record_type=person&entity_type=person_entity&executor_count=1&executor_memory=8g&executor_core_count=1&log_cos_endpoint=http://s3.us-south.cloud-object-storage.appdomain.cloud&log_cos_bucket=mdmdata&log_cos_access_key=b33037e4e8954207a434cc032c1139d1&log_cos_secret_key=hex_string&do_force=false&do_deduplicate=false&do_analytics=false&do_replicate=false" 
Copy to clipboard

Example request

CreateMatchingMatchJobOptions createMatchingMatchJobOptions = new CreateMatchingMatchJobOptions.Builder()
  .recordType("person")
  .entityType("person_entity")
  .executorCount(Long.valueOf("1"))
  .executorMemory("8g")
  .executorCoreCount(Long.valueOf("1"))
  .sparkParallelism(Long.valueOf("2"))
  .logCosEndpoint("http://s3.us-south.cloud-object-storage.appdomain.cloud")
  .logCosBucket("mdmdata")
  .logCosAccessKey("b33037e4e8954207a434cc032c1139d1")
  .logCosSecretKey("<hex string>")
  .build();

Response<PostCloudJob> response = mdmService.createMatchingMatchJob(createMatchingMatchJobOptions).execute();
PostCloudJob postCloudJob = response.getResult();

System.out.println(postCloudJob);
Copy to clipboard

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

PostCloudJob

Response object for asynchronous processing of a job.

Status Code

202
The request has been successfully created.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 202

{
  "created_at": "",
  "image": "mdm-spark-job",
  "job_name": "match-bulkmatcher",
  "last_updated_at": "",
  "id": "b10502a6-b336-4452-b15d-bbda67b95299",
  "input": {},
  "spark_configuration": {},
  "status": "Queued"
}
Copy to clipboard

Success example

{
  "created_at": "",
  "image": "mdm-spark-job",
  "job_name": "match-bulkmatcher",
  "last_updated_at": "",
  "id": "b10502a6-b336-4452-b15d-bbda67b95299",
  "input": {},
  "spark_configuration": {},
  "status": "Queued"
}
Copy to clipboard

This service initiates asynchronous processing of the import rules job.

POST /mdm/v1/bulk_import_linkage_rules

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
do_wait
boolean
Wait for job finish, default is false

Default: false
executor_count
integer
The number of spark executors

Example: 1
executor_memory
string
Amount of memory to use per executor process

Example: 8g
executor_core_count
integer
The number of cores to use on each executor

Example: 1
spark_parallelism
integer
The number of partitions to be used by spark

Example: 2

Request Body

Required*

PostImportRulesRequest

The wrapper object for import manual rules request body

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "job_id": "",
  "exit_code": 0,
  "arguments": "runImportRules.sh -d person -m person_entity",
  "start_time": "",
  "end_time": "",
  "process_id": 0
}
Copy to clipboard

This service initiates asynchronous processing of a matching export job.
Match export job exports the existing matching data, pairs data, data quality data and workflow data to a given path under /service-exports.

POST /mdm/v1/bulk_matching_export

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
executor_count
integer
The number of spark executors

Example: 1
executor_memory
string
Amount of memory to use per executor process

Example: 8g
executor_core_count
integer
The number of cores to use on each executor

Example: 1
spark_parallelism
integer
The number of partitions to be used by spark

Example: 2
output_path
string
The output path under /service-exports for the exported data

Default: /service-exports/matching
Example: /service-exports/customFolder

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

202
The request has been successfully created.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.
501
The request cannot be processed due to the server not supporting the required functionality

Example responses

Status 202

{
  "created_at": "",
  "image": "mdm-spark-job",
  "job_name": "match-bulkmatchingexport",
  "last_updated_at": "",
  "id": "854ed8ca-dddf-4862-b069-58cb15eba138",
  "input": {},
  "spark_configuration": {},
  "status": "Queued"
}
Copy to clipboard

This service initiates asynchronous processing of the derive job.
Data derivation is the process to standardize and generate buckets for the input records.

This service initiates asynchronous processing of the derive job.
Data derivation is the process to standardize and generate buckets for the input records.

POST /mdm/v1/bulk_derive

ServiceCall<PostCloudJob> createMatchingDeriveJob(CreateMatchingDeriveJobOptions createMatchingDeriveJobOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.manage

Request

Use the CreateMatchingDeriveJobOptions.Builder to create a CreateMatchingDeriveJobOptions object that contains the parameter values for the createMatchingDeriveJob method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
The data type identifier of source records, ie. person, organization, contract

Example: person
do_force
boolean
Force to re-derive all records, default is false

Default: false
csv_file
string
The delimited text file name, ending with .csv/.tsv for comma/tab separated format.

Example: /usr/mdm-matching/sample/person-100.tsv
csv_column
string
comma separated column names in the data file

Example: record_source,,record_id,legal_name.given_name,legal_name.last_name,primary_residence.address_line1,primary_residence.city,primary_residence.province_state,primary_residence.zip_postal_code,,home_telephone.phone_number,business_address.address_line1,business_address.city,business_address.province_state,business_address.zip_postal_code,,home_telephone.phone_number.1,social_security_number.identification_number,health_card.identification_number,birth_date.value,gender.value
cos_endpoint
string
IBM COS end point (i.e. https://s3.us-east.cloud-object-storage.appdomain.cloud)

Example: http://s3.us-south.cloud-object-storage.appdomain.cloud
cos_bucket
string
IBM COS bucket (i.e. bucket-27200-lwx4cfvcue)

Example: mdmdata
cos_access_key
string
IBM COS access key (i.e. cf4965cebe074720a4929759f57e1214)

Example: b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret
cos_secret_key
string
The unique secret code to access IBM COS

Example: <hex string>
executor_count
integer
The number of spark executors

Example: 1
executor_memory
string
Amount of memory to use per executor process

Example: 8g
executor_core_count
integer
The number of cores to use on each executor

Example: 1
spark_parallelism
integer
The number of partitions to be used by spark

Example: 2
log_cos_endpoint
string
IBM COS end point for job log storage.

Example: http://s3.us-south.cloud-object-storage.appdomain.cloud
log_cos_bucket
string
IBM COS bucket for job log storage.

Example: mdmdata
log_cos_access_key
string
IBM COS access key for spark log storage

Example: b33037e4e8954207a434cc032c1139d1
log_cos_secret_key
string
IBM COS secret key for spark log storage

Example: <hex string>

CreateMatchingDeriveJobOptions

The createMatchingDeriveJob options.

Initiate data derivation job

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_derive?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&record_type=person&csv_file=person-100.tsv&csv_column=record_source,,record_id,legal_name.given_name,legal_name.last_name,primary_residence.address_line1,primary_residence.city,primary_residence.province_state,primary_residence.zip_postal_code,,home_telephone.phone_number,business_address.address_line1,business_address.city,business_address.province_state,business_address.zip_postal_code,,home_telephone.phone_number.1,social_security_number.identification_number,health_card.identification_number,birth_date.value,gender.value&cos_endpoint=http://s3.us-south.cloud-object-storage.appdomain.cloud&cos_bucket=mdmdata&cos_access_key=1234567&cos_secret_key=7654321&executor_count=1&executor_memory=8g&executor_core_count=1&log_cos_endpoint=http://s3.us-south.cloud-object-storage.appdomain.cloud&log_cos_bucket=mdmdata&log_cos_access_key=b33037e4e8954207a434cc032c1139d1&log_cos_secret_key=hex_string" 
Copy to clipboard

Example request

CreateMatchingDeriveJobOptions createMatchingDeriveJobOptions = new CreateMatchingDeriveJobOptions.Builder()
  .recordType("person")
  .csvFile("/usr/mdm-matching/sample/person-100.tsv")
  .csvColumn("record_source,,record_id,legal_name.given_name,legal_name.last_name,primary_residence.address_line1,primary_residence.city,primary_residence.province_state,primary_residence.zip_postal_code,,home_telephone.phone_number,business_address.address_line1,business_address.city,business_address.province_state,business_address.zip_postal_code,,home_telephone.phone_number.1,social_security_number.identification_number,health_card.identification_number,birth_date.value,gender.value")
  .cosEndpoint("http://s3.us-south.cloud-object-storage.appdomain.cloud")
  .cosBucket("mdmdata")
  .cosAccessKey("b33037e4e8954207a434cc032c1139d1 #pragma: allowlist secret")
  .cosSecretKey("<hex string>")
  .executorCount(Long.valueOf("1"))
  .executorMemory("8g")
  .executorCoreCount(Long.valueOf("1"))
  .sparkParallelism(Long.valueOf("2"))
  .logCosEndpoint("http://s3.us-south.cloud-object-storage.appdomain.cloud")
  .logCosBucket("mdmdata")
  .logCosAccessKey("b33037e4e8954207a434cc032c1139d1")
  .logCosSecretKey("<hex string>")
  .build();

Response<PostCloudJob> response = mdmService.createMatchingDeriveJob(createMatchingDeriveJobOptions).execute();
PostCloudJob postCloudJob = response.getResult();

System.out.println(postCloudJob);
Copy to clipboard

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

PostCloudJob

Response object for asynchronous processing of a job.

Status Code

202
The request has been successfully created.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 202

{
  "created_at": "",
  "image": "mdm-spark-job",
  "job_name": "match-bulkderiver",
  "last_updated_at": "",
  "id": "2ba3ed28-00c7-42e4-9cc9-8c74bf5e4ff0",
  "input": {},
  "spark_configuration": {},
  "status": "Running"
}
Copy to clipboard

Success example

{
  "created_at": "",
  "image": "mdm-spark-job",
  "job_name": "match-bulkderiver",
  "last_updated_at": "",
  "id": "2ba3ed28-00c7-42e4-9cc9-8c74bf5e4ff0",
  "input": {},
  "spark_configuration": {},
  "status": "Running"
}
Copy to clipboard

This service initiates asynchronous processing of a report job.
Report job creates a report of the existing derived data that includes information like matching summary, largest entities, etc..

This service initiates asynchronous processing of a report job.
Report job creates a report of the existing derived data that includes information like matching summary, largest entities, etc..

POST /mdm/v1/bulk_report

ServiceCall<PostCloudJob> createMatchingReportJob(CreateMatchingReportJobOptions createMatchingReportJobOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.manage

Request

Use the CreateMatchingReportJobOptions.Builder to create a CreateMatchingReportJobOptions object that contains the parameter values for the createMatchingReportJob method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
The data type identifier of source records, ie. person, organization, contract

Example: person
entity_type
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: person_entity
executor_count
integer
The number of spark executors

Example: 1
executor_memory
string
Amount of memory to use per executor process

Example: 8g
executor_core_count
integer
The number of cores to use on each executor

Example: 1
spark_parallelism
integer
The number of partitions to be used by spark

Example: 2
job_list
string
Comma separated analytics report identifier to be collected, ie. entity_summary, bucket_summary

Default: entity_summary,bucket_summary
Example: entity_summary,bucket_summary
do_analytics
boolean
collect analysis report, default is false

Default: false

CreateMatchingReportJobOptions

The createMatchingReportJob options.

Initiate report job

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_report?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&record_type=person&entity_type=person_entity&executor_count=1&executor_memory=8g&executor_core_count=1&job_list=entity_summary,bucket_summary&do_analytics=false" 
Copy to clipboard

Example request

CreateMatchingReportJobOptions createMatchingReportJobOptions = new CreateMatchingReportJobOptions.Builder()
  .recordType("person")
  .entityType("person_entity")
  .executorCount(Long.valueOf("1"))
  .executorMemory("8g")
  .executorCoreCount(Long.valueOf("1"))
  .sparkParallelism(Long.valueOf("2"))
  .jobList("entity_summary,bucket_summary")
  .build();

Response<PostCloudJob> response = mdmService.createMatchingReportJob(createMatchingReportJobOptions).execute();
PostCloudJob postCloudJob = response.getResult();

System.out.println(postCloudJob);
Copy to clipboard

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

PostCloudJob

Response object for asynchronous processing of a job.

Status Code

202
The request has been successfully created.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 202

{
  "created_at": "",
  "image": "mdm-spark-job",
  "job_name": "match-bulkreporter",
  "last_updated_at": "",
  "id": "854ed8ca-dddf-4862-b069-58cb15eba138",
  "input": {},
  "spark_configuration": {},
  "status": "Queued"
}
Copy to clipboard

Success example

{
  "created_at": "",
  "image": "mdm-spark-job",
  "job_name": "match-bulkreporter",
  "last_updated_at": "",
  "id": "854ed8ca-dddf-4862-b069-58cb15eba138",
  "input": {},
  "spark_configuration": {},
  "status": "Queued"
}
Copy to clipboard

This service initiates asynchronous processing of the generate pairs job.

POST /mdm/v1/bulk_generate_pairs

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.manage

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
entity_type
Required*
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: person_entity
record_type
Required*
string
The data type identifier of source records, ie. person, organization, contract

Example: person
do_wait
boolean
Wait for job finish, default is false

Default: false
max_pairs
string
The maximum number of pairs to return

Default: 500
Example: 500
executor_count
integer
The number of spark executors

Example: 1
executor_memory
string
Amount of memory to use per executor process

Example: 8g
executor_core_count
integer
The number of cores to use on each executor

Example: 1
spark_parallelism
integer
The number of partitions to be used by spark

Example: 2
exclude_reviewed_pairs
boolean
Exclude reviewd pairs. Default is false

Default: false

Response

Response Body

PostCloudJob

Response object for asynchronous processing of a job

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "job_id": "44465189566855168",
  "arguments": "runPairScore.sh -d person -m person_entity",
  "start_time": "2021-02-17T10:55:09.264Z",
  "process_id": 1550,
  "end_time": "2021-02-17T10:55:22.487Z",
  "exit_code": 0,
  "metrics": {
    "total_pairs": 118,
    "bucket_count_compared": 1125,
    "bucket_count_large": 0,
    "bucket_count_singleton": 1776,
    "record_count_updated": 0,
    "record_count_deleted": 0,
    "record_count_no_buckets": 0,
    "record_count_low_score": 0,
    "record_count_candidate": 100,
    "pair_comparison_count": 5614,
    "pair_matched_count": 5101
  }
}
Copy to clipboard

This service resolves the matching workflow with given workflow id.

POST /mdm/v1/data_quality/remediation_workflows/{workflow_id}/resolve

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.write

Request

Path Parameters

workflow_id
Required*
string
The workflow identifier of an workflow as assigned by the system

Example: cd4431f4-505b-11ed-bdc3-0242ac120002

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Status Code

204
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

No Sample Response

This method does not specify any sample responses.

This service get the matching workflow with given workflow id.

GET /mdm/v1/data_quality/remediation_workflows/{workflow_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Path Parameters

workflow_id
Required*
string
The unique identifier of a workflow as assigned by the system

Example: cd4431f4-505b-11ed-bdc3-0242ac120002

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

GetSingleRemediationWorkflow

The wrapper object for get single workflow response

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "type": "potential_match",
  "id": "cd4431f4-505b-11ed-bdc3-0242ac120002",
  "entities": [
    "person_entity-48242682",
    "person_entity-93523223"
  ],
  "last_update_date": "2022-10-31T16:18:01.864Z",
  "last_update_user": "ID1234",
  "bulk_action": {
    "decision": "link",
    "comments": "these entities are obviously the same."
  },
  "bulk_recommendation": {
    "action": "link",
    "probability": "0.5689"
  },
  "issue_actions": [
    {
      "issue_id": 123456,
      "decision": "link",
      "records": [
        "1",
        "2"
      ],
      "comments": "the social id is matching",
      "last_update_date": "2022-10-31T16:18:01.864Z",
      "last_update_user": "ID1234"
    }
  ]
}
Copy to clipboard

This service deletes the matching workflow with given workflow id.

DELETE /mdm/v1/data_quality/remediation_workflows/{workflow_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.write

Request

Path Parameters

workflow_id
Required*
string
The workflow identifier of an workflow as assigned by the system

Example: cd4431f4-505b-11ed-bdc3-0242ac120002

Query Parameters

crn
Required*
string
The cloud resource name of the service.
remove_workflow_instance
boolean
The API will not delete workflow instance if the value is set to false. Default is true

Default: true

Response

Status Code

204
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

No Sample Response

This method does not specify any sample responses.

This service updates the matching workflow with given workflow id.

PATCH /mdm/v1/data_quality/remediation_workflows/{workflow_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.write

Request

Path Parameters

workflow_id
Required*
string
The workflow identifier of an workflow as assigned by the system

Example: cd4431f4-505b-11ed-bdc3-0242ac120002

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

PatchRemediationWorkflow

The wrapper object for patch remediation workflow request

Examples:

Response

Response Body

GetSingleRemediationWorkflow

The wrapper object for get single workflow response

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "type": "potential_match",
  "id": "cd4431f4-505b-11ed-bdc3-0242ac120002",
  "entities": [
    "person_entity-48242682",
    "person_entity-93523223"
  ],
  "last_update_date": "2022-10-31T16:18:01.864Z",
  "last_update_user": "ID1234",
  "bulk_action": {
    "decision": "link",
    "comments": "these entities are obviously the same."
  },
  "bulk_recommendation": {
    "action": "link",
    "probability": "0.5689"
  },
  "issue_actions": [
    {
      "issue_id": 123456,
      "decision": "link",
      "records": [
        "1",
        "2"
      ],
      "comments": "the social id is matching",
      "last_update_date": "2022-10-31T16:18:01.864Z",
      "last_update_user": "ID1234"
    }
  ]
}
Copy to clipboard

This service reports the entity confidence metrics.

GET /mdm/v1/data_quality/entity_confidence_metrics

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
entity_type
Required*
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: person_entity
update_dq_dashboard
boolean
The API will report the entity confidence metrics to DQ dashboard when the parameter is true. Default is false

Default: false

Response

Response Body

ReportEntityMetrics

Response wrapper object for getting entity quality metrics

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "entity_count_with_potential_match_issues": 10,
  "total_entity_count": 50
}
Copy to clipboard

This service compares the input records and returns comparison details.
This service supports comparing two records by supplying payload or record_id.
This service also supports self comparison of a single input record.

This service compares the input records and returns comparison details.
This service supports comparing two records by supplying payload or record_id.
This service also supports self comparison of a single input record.

POST /mdm/v1/compare

ServiceCall<Compare> compareMatchingIndex(CompareMatchingIndexOptions compareMatchingIndexOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Use the CompareMatchingIndexOptions.Builder to create a CompareMatchingIndexOptions object that contains the parameter values for the compareMatchingIndex method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
entity_type
Required*
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: person_entity
details
string
The level of information detail in response, ie. low, high, debug

Default: low
record_number1
int64
The unique identifier of the first source record as assigned by the system

Example: 123456789
record_number2
int64
The unique identifier of the second source record as assigned by the system

Example: 123456789
record_type
string
The data type identifier of source records, ie. person, organization, contract

Default: person
Example: person

Request Body

Required*

CompareRecordsRequest

The wrapper object for collection of records

Examples:

CompareMatchingIndexOptions

The compareMatchingIndex options.

Compare records

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/compare?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&details=debug&entity_type=person_entity&record_number1=1234567890&record_number2=1234567899&record_type=person" --data "{"records":[{"record_type":"person","attributes":{"record_source":"MDM","record_id":"6","record_last_updated":"2017-10-02 18:08:23.638","birth_date":[{"value":"1961-08-24T00:00:00"}],"gender":[{"value":"mALe"}],"primary_residence":[{"record_start":"2017-10-02 18:08:23.689","record_last_updated":"2017-10-02 18:08:23.69","residence":"condo","address_line1":"7959 SW King AVE","city":"Toronto","zip_postal_code":"L5D4K8","residence_number":"120","province_state":"ON","county":"Peel","country":"canada"}],"home_telephone":[{"record_start":"2017-10-02 18:08:23.793","record_last_updated":"2017-10-02 18:08:23.793","phone_number":"905-722-5903","contact_method":"Telephone Number"}],"mobile_telephone":[{"record_start":"2017-10-02 18:08:23.793","record_last_updated":"2017-10-02 18:08:23.793","phone_number":"416-722-5903","contact_method":"Telephone Number"}],"personal_email":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"personal_email","email_id":"brownb@us.ibm.com","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"social_security_number":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"social_security_number","identification_number":"982588729873","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"drivers_licence":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"drivers_licence","identification_number":"803356781","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"passport":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"passport","identification_number":"EG346ASS9820M","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"legal_name":[{"record_start":"2017-10-02 18:08:23.641","record_last_updated":"2017-10-02 18:08:23.641","generation":"phd","usage":"Legal","prefix":"rev","given_name":"Bobby","middle_name":"Don","last_name":"Brown","suffix":"2d"}]}},{"record_type":"person","attributes":{"record_source":"MDMx","record_id":"7","record_last_updated":"2017-10-02 18:08:23.638","birth_date":[{"value":"1961-08-23T00:00:00"}],"gender":[{"value":"mALe"}],"primary_residence":[{"record_start":"2017-10-02 18:08:23.689","record_last_updated":"2017-10-02 18:08:23.69","residence":"condo","address_line1":"7950 SW King AVE","city":"Toronto","zip_postal_code":"L5D4K8","residence_number":"120","province_state":"ON","county":"Peel","country":"canada"}],"home_telephone":[{"record_start":"2017-10-02 18:08:23.793","record_last_updated":"2017-10-02 18:08:23.793","phone_number":"905-722-5903","contact_method":"Telephone Number"}],"personal_email":[{"record_last_updated":"2017-10-02 18:08:23.651","usageValue":"personal_email","email_id":"brownb@us.ibm.com","record_start":"2017-10-02 18:08:23.651","usageType":"6"}],"legal_name":[{"record_start":"2017-10-02 18:08:23.641","record_last_updated":"2017-10-02 18:08:23.641","generation":"phd","usage":"Legal","prefix":"rev","given_name":"Boby","middle_name":"Don","last_name":"Brown","suffix":"2d"}]}}]}" 
Copy to clipboard

Example request

SingleRecordRequestAttributes singleRecordRequestAttributesModel = new SingleRecordRequestAttributes.Builder()
  .recordLastUpdated(Long.valueOf("1506982103000"))
  .recordId("2")
  .recordSource("MDM")
  .add("birth_date", "[{\"value\":\"11/05/1993\"}]")
  .add("gender", "[{\"value\":\"male\"}]")
  .add("primary_residence", "[{\"record_start\":\" \",\"address_line1\":\"7908 NE VAN TRUMP AVE\",\"city\":\"LEFOR\",\"province_state\":\"Texas\"}]")
  .build();
SingleRecordRequest singleRecordRequestModel = new SingleRecordRequest.Builder()
  .recordType("person")
  .attributes(singleRecordRequestAttributesModel)
  .build();
CompareMatchingIndexOptions compareMatchingIndexOptions = new CompareMatchingIndexOptions.Builder()
  .records(new java.util.ArrayList<SingleRecordRequest>(java.util.Arrays.asList(singleRecordRequestModel)))
  .entityType("person_entity")
  .recordNumber1(Long.valueOf("123456789"))
  .recordNumber2(Long.valueOf("123456789"))
  .recordType("person")
  .build();

Response<Compare> response = mdmService.compareMatchingIndex(compareMatchingIndexOptions).execute();
Compare compare = response.getResult();

System.out.println(compare);
Copy to clipboard

Response

Response Body

Compare

Response object for comparing records

Compare

Response object for comparing records.

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "score": 238,
  "score_category": "matched",
  "record_number1": 168071492364660740,
  "record_number2": 168071476032040960
}
Copy to clipboard

Success example

{
  "score": 238,
  "score_category": "matched",
  "record_number1": 168071492364660740,
  "record_number2": 168071476032040960
}
Copy to clipboard

This service retrieves member records of a cluster. Clusters can be created for the records of an entity. A cluster represents a closely matched collection of records of an entity.

GET /mdm/v1/clusters/{cluster_id}/records

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Path Parameters

cluster_id
Required*
string
The cluster identifier of a cluster as assigned by the system

Example: entity_type-123456789-0

Query Parameters

crn
Required*
string
The cloud resource name of the service.
offset
integer
The number of entries to skip before returning a page of results. The default offset is 0.

Default: 0
limit
integer
The maximum expected number of entries in each page of results. The default limit is 10.

Default: 10

Response

Response Body

GetClusterRecords

Response wrapper object for getting member records from a cluster

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "first": {
    "href": "https://matching:9443/mdm/v1/clusters/person_entity-110505294894774272-0/records?crn=:::::::msk::&offset=0&limit=10"
  },
  "last": {
    "href": "https://matching:9443/mdm/v1/clusters/person_entity-110505294894774272-0/records?crn=:::::::msk::&offset=0&limit=10"
  },
  "total_count": 1,
  "offset": 0,
  "limit": 10,
  "members": "[110505294894774272]"
}
Copy to clipboard

This service provides entity members, matched pairs, and manual rules.

POST /mdm/v1/entity_detail

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

EntityRequest

The wrapper object of entity and record numbers

Response

Response Body

EntityResponse

Response object for entity details

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "records": [
    {
      "record_number": "52538957658369024",
      "entity_number": "52538957658369024",
      "score": "186"
    },
    {
      "record_number": "52538759671491584",
      "entity_number": "52538759671491584",
      "score": "186"
    },
    {
      "record_number": "52538887606152192",
      "entity_number": "52538759671491584",
      "score": "186"
    }
  ],
  "pairs": [
    {
      "source": "52538759671491584",
      "target": "52538887606152192",
      "score": "183",
      "type": "LINKED"
    },
    {
      "source": "52538759671491584",
      "target": "52538957658369024",
      "score": "58",
      "type": "NOT_LINKED"
    },
    {
      "source": "52538887606152192",
      "target": "52538957658369024",
      "score": "67",
      "type": "NOT_LINKED"
    }
  ]
}
Copy to clipboard

This service retrieves the information about a job which is identified with the supplied job id.

This service retrieves the information about a job which is identified with the supplied job id.

GET /mdm/v1/matching_jobs/{job_id}

ServiceCall<GetMatchingJobs> getMatchingJobInfo(GetMatchingJobInfoOptions getMatchingJobInfoOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Use the GetMatchingJobInfoOptions.Builder to create a GetMatchingJobInfoOptions object that contains the parameter values for the getMatchingJobInfo method.

Path Parameters

job_id
Required*
string
The unique identifier of the job.

Example: 95364

Query Parameters

crn
Required*
string
The cloud resource name of the service.

GetMatchingJobInfoOptions

The getMatchingJobInfo options.

Retrieve information for a job

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/matching_jobs/95364?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetMatchingJobInfoOptions getMatchingJobInfoOptions = new GetMatchingJobInfoOptions.Builder()
  .jobId("95364")
  .build();

Response<GetMatchingJobs> response = mdmService.getMatchingJobInfo(getMatchingJobInfoOptions).execute();
GetMatchingJobs getMatchingJobs = response.getResult();

System.out.println(getMatchingJobs);

Response

Response Body

GetMatchingJobs

Response object for get matching job

GetMatchingJobs

Response object for get matching job.

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "image": "mdm-spark-job",
  "job_name": "match-bulkderiver",
  "created_at": "2021-07-08T06:55:53.000Z",
  "id": "2a01507e-92a8-41c4-8568-2b3dec10889b",
  "last_updated_at": "2021-07-08T07:01:41.000Z",
  "started_at": "2021-07-08T06:55:53.000Z",
  "status": "Success"
}
Copy to clipboard

Success example

{
  "image": "mdm-spark-job",
  "job_name": "match-bulkderiver",
  "created_at": "2021-07-08T06:55:53.000Z",
  "id": "2a01507e-92a8-41c4-8568-2b3dec10889b",
  "last_updated_at": "2021-07-08T07:01:41.000Z",
  "started_at": "2021-07-08T06:55:53.000Z",
  "status": "Success"
}
Copy to clipboard

This service adds or updates a collection of manual link/unlink rules.

This service adds or updates a collection of manual link/unlink rules.

PUT /mdm/v1/linkage_rules

ServiceCall<Map<String, List<RulesEntityRule>>> replaceMatchingRule(ReplaceMatchingRuleOptions replaceMatchingRuleOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.write

Request

Use the ReplaceMatchingRuleOptions.Builder to create a ReplaceMatchingRuleOptions object that contains the parameter values for the replaceMatchingRule method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

RulesRequest

The wrapper object of linkage rules

ReplaceMatchingRuleOptions

The replaceMatchingRule options.

Add or update manual link/unlink

curl -X PUT --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/linkage_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"entity_type":"person_entity","{"rules":[{"record_numbers":["32995408531474430"],"rule_type":"unlink","description":"test"}]}}" 
Copy to clipboard

Example request

RulesRequestRule rulesRequestRuleModel = new RulesRequestRule.Builder()
  .ruleType("testString")
  .recordNumbers(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .description("testString")
  .build();
ReplaceMatchingRuleOptions replaceMatchingRuleOptions = new ReplaceMatchingRuleOptions.Builder()
  .rules(new java.util.ArrayList<RulesRequestRule>(java.util.Arrays.asList(rulesRequestRuleModel)))
  .entityType("testString")
  .build();

Response<Map<String, List<RulesEntityRule>>> response = mdmService.replaceMatchingRule(replaceMatchingRuleOptions).execute();
Map<String, List<RulesEntityRule>> mapStringListRulesEntityRule = response.getResult();

System.out.println(mapStringListRulesEntityRule);
Copy to clipboard

Response

Response type: Map<String, List<RulesEntityRule>>

Response Body

object

Response wrapper object for linkage rules

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
409
The request cannot be processed due to presence of quarantine record(s)
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}
Copy to clipboard

Success example

{
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}
Copy to clipboard

This service compares the input pairs of records and returns comparison details.
This service supports comparing multiple pairs of records by supplying pairs of record numbers in the payload.

This service compares the input pairs of records and returns comparison details.
This service supports comparing multiple pairs of records by supplying pairs of record numbers in the payload.

POST /mdm/v1/batch_compare

ServiceCall<BatchComparePairsResponse> batchCompareMatchingIndex(BatchCompareMatchingIndexOptions batchCompareMatchingIndexOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Use the BatchCompareMatchingIndexOptions.Builder to create a BatchCompareMatchingIndexOptions object that contains the parameter values for the batchCompareMatchingIndex method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
entity_type
Required*
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: person_entity
record_type
Required*
string
The data type identifier of source records, ie. person, organization, contract

Example: person
details
string
The level of information detail in response, ie. low, high, debug

Default: low

Request Body

Required*

BatchComparePairsRequest

The wrapper Object for pairs of record numbers

Examples:

BatchCompareMatchingIndexOptions

The batchCompareMatchingIndex options.

Example request

BatchComparePairsRequestPair batchComparePairsRequestPairModel = new BatchComparePairsRequestPair.Builder()
  .recordNumber1("123")
  .recordNumber2("456")
  .build();
BatchCompareMatchingIndexOptions batchCompareMatchingIndexOptions = new BatchCompareMatchingIndexOptions.Builder()
  .pairs(new java.util.ArrayList<BatchComparePairsRequestPair>(java.util.Arrays.asList(batchComparePairsRequestPairModel)))
  .entityType("person_entity")
  .recordType("person")
  .build();

Response<BatchComparePairsResponse> response = mdmService.batchCompareMatchingIndex(batchCompareMatchingIndexOptions).execute();
BatchComparePairsResponse batchComparePairsResponse = response.getResult();

System.out.println(batchComparePairsResponse);
Copy to clipboard

Response

Response Body

BatchComparePairsResponse

The wrapper object for the comparison details of the pairs compared

BatchComparePairsResponse

The wrapper object for the comparison details of the pairs compared.

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "comparison_details": [
    {
      "score": 238,
      "score_category": "matched",
      "record_number1": 168071492364660740,
      "record_number2": 168071476032040960
    }
  ]
}
Copy to clipboard

Success example

{
  "comparison_details": [
    {
      "score": 238,
      "score_category": "matched",
      "record_number1": 168071492364660740,
      "record_number2": 168071476032040960
    }
  ]
}
Copy to clipboard

This service retrieves the information and explanation of a cluster. Clusters can be created for the records of an entity. A cluster represents a closely matched collection of records of an entity.

GET /mdm/v1/clusters/{cluster_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Path Parameters

cluster_id
Required*
string
The cluster identifier of a cluster as assigned by the system

Example: entity_type-123456789-0

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Response

Response Body

GetCluster

Response wrapper object for retrieving one cluster

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "cluster_id": "person_entity-93822496058376193-1",
  "entity_id": "person_entity-93822496058376200",
  "records_count": 1,
  "anomaly": false,
  "explanation": {
    "primary_residence": {
      "city": [
        "MONT",
        "ALTO"
      ],
      "postal_code": [
        "17237"
      ]
    },
    "gender": {}
  }
}
Copy to clipboard

This service retrieves the derived data for a given input record.

GET /mdm/v1/index

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_number
int64
The unique identifier of a source record as assigned by the system

Example: 1234567890
record_source
string
The source system name of the record

Example: MDM
record_id
string
The record identifier of the record

Example: 123456
record_type
string
The data type identifier of source records, ie. person, organization

Example: person

Response

Response Body

GetIndex

Response wrapper object for retrieving the derived matching data for given source record keys

Status Code

200
The request has been successfully finished.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "self_scores": {
    "person_entity": 344
  },
  "record_number": 35676912450780160,
  "buckets": [],
  "standardized_values": " "
}
Copy to clipboard

This service computes and returns a preview of the derived data for the input records.
Data derivation is the process to standardize and generate buckets for the input records.

POST /mdm/v1/derive

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
details
string
The level of information detail in response, ie. low, high, debug

Default: low

Request Body

Required*

DeriveRecordsRequest

The wrapper object for collection of records

Examples:

Response

Response Body

PostDerive

Response object for previewing the derived matching data for given records

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "index_response": [
    {
      "record_id": "1",
      "record_type": "person",
      "record_source": "MDM",
      "algorithm_name": "person",
      "standardized_values": {},
      "buckets": []
    }
  ]
}
Copy to clipboard

This service provides a preview of the impacted entities by hypothesizing one or more manual link/unlink rules.

This service provides a preview of the impacted entities by hypothesizing one or more manual link/unlink rules.

POST /mdm/v1/linkage_rules_preview

ServiceCall<Map<String, Map<String, List<String>>>> createMatchingEntityPreview(CreateMatchingEntityPreviewOptions createMatchingEntityPreviewOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Use the CreateMatchingEntityPreviewOptions.Builder to create a CreateMatchingEntityPreviewOptions object that contains the parameter values for the createMatchingEntityPreview method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

RulesRequest

The wrapper object of linkage rules

CreateMatchingEntityPreviewOptions

The createMatchingEntityPreview options.

Preview entity composition

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/linkage_rules_preview?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"entity_type":"person_entity","{"rules":[{"record_numbers":["32995408531474430"],"rule_type":"unlink","description":"test"}]}}" 
Copy to clipboard

Example request

RulesRequestRule rulesRequestRuleModel = new RulesRequestRule.Builder()
  .ruleType("testString")
  .recordNumbers(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .description("testString")
  .build();
CreateMatchingEntityPreviewOptions createMatchingEntityPreviewOptions = new CreateMatchingEntityPreviewOptions.Builder()
  .rules(new java.util.ArrayList<RulesRequestRule>(java.util.Arrays.asList(rulesRequestRuleModel)))
  .entityType("testString")
  .build();

Response<Map<String, Map<String, List<String>>>> response = mdmService.createMatchingEntityPreview(createMatchingEntityPreviewOptions).execute();
Map<String, Map<String, List<String>>> mapStringMapStringListString = response.getResult();

System.out.println(mapStringMapStringListString);
Copy to clipboard

Response

Response type: Map<String, Map<String, List<String>>>

Response Body

object

Response wrapper object for previewing the impacted entities by hypothesizing one or more linkage rules

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
409
The request cannot be processed due to presence of quarantine record(s)
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "person_entity": {
    "35678330629897216": [],
    "35678327655087104": [
      "35678330629897216",
      "35678327655087104"
    ]
  }
}
Copy to clipboard

Success example

{
  "person_entity": {
    "35678330629897216": [],
    "35678327655087104": [
      "35678330629897216",
      "35678327655087104"
    ]
  }
}
Copy to clipboard

This service retrieves all record_ids that are assigned with the same entity_id.

This service retrieves all record_ids that are assigned with the same entity_id.

GET /mdm/v1/entity_ids/{entity_id}

ServiceCall<GetRecordKeys> getMatchingRecords(GetMatchingRecordsOptions getMatchingRecordsOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Use the GetMatchingRecordsOptions.Builder to create a GetMatchingRecordsOptions object that contains the parameter values for the getMatchingRecords method.

Path Parameters

entity_id
Required*
string
The entity identifier of an entity as assigned by the system

Example: entity_type-123456789

Query Parameters

crn
Required*
string
The cloud resource name of the service.

GetMatchingRecordsOptions

The getMatchingRecords options.

Retrieve record ids

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entity_ids/entity_type-123456789?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetMatchingRecordsOptions getMatchingRecordsOptions = new GetMatchingRecordsOptions.Builder()
  .entityId("entity_type-123456789")
  .build();

Response<GetRecordKeys> response = mdmService.getMatchingRecords(getMatchingRecordsOptions).execute();
GetRecordKeys getRecordKeys = response.getResult();

System.out.println(getRecordKeys);

Response

Response Body

GetRecordKeys

Response wrapper object for getting the record keys of a given entity_id

GetRecordKeys

Response wrapper object for getting the record keys of a given entity_id.

Status Code

200
The request has been successfully finished.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

{ "records": [] }
{ "records": [] }

This service searches for the supplied payload and returns record_ids of potential matches.
The order of record_ids in the response is determined by matching algorithms.

This service searches for the supplied payload and returns record_ids of potential matches.
The order of record_ids in the response is determined by matching algorithms.

POST /mdm/v1/probabilistic_search

ServiceCall<PostSearch> searchMatchingIndex(SearchMatchingIndexOptions searchMatchingIndexOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Use the SearchMatchingIndexOptions.Builder to create a SearchMatchingIndexOptions object that contains the parameter values for the searchMatchingIndex method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
include_logical_key
boolean
To include logical keys in the response, default is true

Default: true
details
string
The level of information detail in response, ie. low, high, debug

Default: low
min_score
integer
The minimum score to filter the matching records in the results. The default min_score is 0.
max_score
integer
The maximum score to filter the matching records in the results. The default max_score is 32767.
offset
integer
The number of entries to skip before returning a page of results. The default offset is 0.
entity_type
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Default: person_entity
limit
integer
The maximum expected number of entries in each page of results. The default limit is 20.

Request Body

Required*

SingleRecordRequest

The wrapper Object for a single record

Examples:

SearchMatchingIndexOptions

The searchMatchingIndex options.

Search records by matching algorithm

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/probabilistic_search?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"record_type":"person","attributes":{"record_source":"PERSONLIST","record_id":"101","birth_date":[{"value":"2007-01-02"}],"gender":[{"value":"F"}],"primary_residence":[{"address_line1":"232 S RICHELIEU ST.E","city":"PORT NORRIS","zip_postal_code":"8349","province_state":"NJ"}],"business_address":[{"address_line1":"9852 WEST DORSET STREET","city":"SHADE GAP","zip_postal_code":"17255","province_state":"PA"}],"home_telephone":[{"phone_number":"248-0677"}],"social_security_number":[{"identification_number":"117-85-3320"}],"health_card":[{"identification_number":"788-71-4075"}],"legal_name":[{"given_name":"MARGUERITE","last_name":"NICKLES"}]}}" 
Copy to clipboard

Example request

SingleRecordRequestAttributes singleRecordRequestAttributesModel = new SingleRecordRequestAttributes.Builder()
  .recordLastUpdated(Long.valueOf("1506982103000"))
  .recordId("2")
  .recordSource("MDM")
  .add("birth_date", "[{\"value\":\"1964-08-21 00:00:00\"}]")
  .add("gender", "[{\"value\":\"mALe\"}]")
  .add("legal_name", "[{\"record_start\":\"017-10-02 18:08:23.689\",\"generation\":\"NEWBORN\",\"given_name\":[\"GIRL1\",\"GIRL1\",\"GIRL2\",\"GIRL3\",\"GIRL4\"],\"middle_name\":\"BABYGIRL\"}]")
  .build();
SearchMatchingIndexOptions searchMatchingIndexOptions = new SearchMatchingIndexOptions.Builder()
  .recordType("person")
  .attributes(singleRecordRequestAttributesModel)
  .build();

Response<PostSearch> response = mdmService.searchMatchingIndex(searchMatchingIndexOptions).execute();
PostSearch postSearch = response.getResult();

System.out.println(postSearch);
Copy to clipboard

Response

Response Body

PostSearch

Response object for searching the potential matches of a given search criteria

PostSearch

Response object for searching the potential matches of a given search criteria.

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "records": [
    {
      "record_id": "101",
      "score": 238,
      "record_source": "PERSONLIST"
    },
    {
      "record_id": "1",
      "score": 238,
      "record_source": "PERSONLIST"
    }
  ]
}
Copy to clipboard

Success example

{
  "records": [
    {
      "record_id": "101",
      "score": 238,
      "record_source": "PERSONLIST"
    },
    {
      "record_id": "1",
      "score": 238,
      "record_source": "PERSONLIST"
    }
  ]
}
Copy to clipboard

This service retrieves all manual link/unlink rules for specified entity.

This service retrieves all manual link/unlink rules for specified entity.

GET /mdm/v1/entities/{entity_id}/linkage_rules

ServiceCall<Map<String, List<RulesEntityRule>>> listMatchingRules(ListMatchingRulesOptions listMatchingRulesOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Use the ListMatchingRulesOptions.Builder to create a ListMatchingRulesOptions object that contains the parameter values for the listMatchingRules method.

Path Parameters

entity_id
Required*
string
The entity identifier of an entity as assigned by the system

Example: person_entity-1234

Query Parameters

crn
Required*
string
The cloud resource name of the service.

ListMatchingRulesOptions

The listMatchingRules options.

Retrieve an entity's manual links/unlinks

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entities/{entity_id}/linkage_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&entity_id=person_entity-1234" 
Copy to clipboard

Example request

ListMatchingRulesOptions listMatchingRulesOptions = new ListMatchingRulesOptions.Builder()
  .entityId("person_entity-1234")
  .build();

Response<Map<String, List<RulesEntityRule>>> response = mdmService.listMatchingRules(listMatchingRulesOptions).execute();
Map<String, List<RulesEntityRule>> mapStringListRulesEntityRule = response.getResult();

System.out.println(mapStringListRulesEntityRule);

Response

Response type: Map<String, List<RulesEntityRule>>

Response Body

object

Response wrapper object for linkage rules

Status Code

200
The request has been successfully finished.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "person_entity": [
    {
      "last_updated": "1611866992413",
      "rule_type": "UNLINK",
      "src_recno": "42690607485214720",
      "description": "string",
      "target_recno": "42690601550274560",
      "user": "admin"
    }
  ]
}
Copy to clipboard

Success example

{
  "person_entity": [
    {
      "last_updated": "1611866992413",
      "rule_type": "UNLINK",
      "src_recno": "42690607485214720",
      "description": "string",
      "target_recno": "42690601550274560",
      "user": "admin"
    }
  ]
}
Copy to clipboard

This service retrieves the sample pairs from the generated pairs of records for analysis.

GET /mdm/v1/pairs

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
The data type identifier of source records, ie. person, organization, contract

Example: person
entity_type
Required*
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: person_entity
size
integer
The number of pairs to be retrieved from the generated pairs

Default: 1
Example: 1
offset
integer
The number of pairs to skip before returning the result

Default: 0

Response

Response Body

GetPairs

Response wrapper object for getting the sample pairs from the generated pairs

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

[
  {
    "score": 207,
    "record_number_1 ": "47096809827657730",
    "comparison_details": {
      "gender_compare": 3,
      "address_compare": 52,
      "phone_compare": 52,
      "name_compare": 34,
      "identifiers_compare": 54,
      "birth_date_compare": 12
    },
    "id": 4.709680982765773e+33,
    "category": "matched",
    "record_number_2": "47096809840240640"
  }
]
Copy to clipboard

This service retrieves all assigned entity_ids for a given record.

GET /mdm/v1/entity_ids

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_number
int64
The unique identifier of a source record as assigned by the system

Example: 1234567890
record_source
string
The source system name of the record

Example: MDM
record_id
string
The record identifier of the record

Example: 123
record_type
string
The data type identifier of source records, ie. person, organization

Example: person

Response

Response Body

GetEntityIds

Response wrapper object for getting entity ids

Status Code

200
The request has been successfully finished.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "entities": [
    {
      "entity_type": "person_entity",
      "entity_id": 32995408531474430
    }
  ]
}
Copy to clipboard

This service retrieve all the clusters for records belonging to an entity. Returns existing clusters if present, otherwise, they are generated, stored and then returned.

GET /mdm/v1/entities/{entity_id}/clusters

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Path Parameters

entity_id
Required*
string
The entity identifier of an entity as assigned by the system

Example: entity_type-123456789

Query Parameters

crn
Required*
string
The cloud resource name of the service.
offset
integer
The number of entries to skip before returning a page of results. The default offset is 0.

Default: 0
limit
integer
The maximum expected number of entries in each page of results. The default limit is 10.

Default: 10
anomalous_only
boolean
The response would contain only anomalous clusters when it is set to true. Default is false

Default: false
fetch_total_count
boolean
The response would return total_count as the number of persisted clusters when set to true, otherwise the size of the response. Default is true

Default: true

Response

Response Body

GetEntityClusters

Response wrapper object for getting the clusters of a given entity_id

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "first": {
    "href": "https://matching:9443/mdm/v1/entities/person_entity-107883101313352704/clusters?crn=:::::::msk::&offset=0&limit=2&anomalous_only=false"
  },
  "last": {
    "href": "https://matching:9443/mdm/v1/entities/person_entity-107883101313352704/clusters?crn=:::::::msk::&offset=4&limit=2&anomalous_only=false"
  },
  "next": {
    "href": "https://matching:9443/mdm/v1/entities/person_entity-107883101313352704/clusters?crn=:::::::msk::&offset=2&limit=2&anomalous_only=false"
  },
  "results": [
    {
      "cluster_id": "person_entity-107883101313352704-0",
      "records_count": 1,
      "anomaly": false
    },
    {
      "cluster_id": "person_entity-107883101313352704-1",
      "records_count": 1,
      "anomaly": false
    }
  ],
  "total_count": 5,
  "offset": 0,
  "limit": 2
}
Copy to clipboard

This service retrieves a summary of all derived data in system (e.g. entity distribution).

GET /mdm/v1/summary

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
The data type identifier of source records, ie. person, organization, contract

Example: person
entity_type
Required*
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: person_entity
count_list
string
Comma separated counts and statistics, ie. total_records, total_entities

Default: total_records,total_active_records,total_inactive_records,unique_source_count,total_entities,total_records_with_record_filter,stats_and_entities
Example: total_records,total_entities

Response

Response Body

GetSummary

Response wrapper object for summary of derived matching data

Status Code

200
The request has been successfully finished.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
"total_records": 100,
"unique_source_count": 1,
"total_entities": 27,
"total_records_with_record_filter": 2,
"stats_and_entities": {
"entity_size_stats": {},
}
}
Copy to clipboard

This service retrieves all manual link/unlink rules for given record and entity type.

This service retrieves all manual link/unlink rules for given record and entity type.

GET /mdm/v1/records/{record_number}/linkage_rules

ServiceCall<Map<String, List<RulesEntityRule>>> getMatchingRecordRules(GetMatchingRecordRulesOptions getMatchingRecordRulesOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Use the GetMatchingRecordRulesOptions.Builder to create a GetMatchingRecordRulesOptions object that contains the parameter values for the getMatchingRecordRules method.

Path Parameters

record_number
Required*
int64
The unique identifier of a source record as assigned by the system

Example: 123456789

Query Parameters

crn
Required*
string
The cloud resource name of the service.
entity_type
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: entity-type

GetMatchingRecordRulesOptions

The getMatchingRecordRules options.

Retrieve an record's manual links/unlinks

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/records/{record_number}/linkage_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&record_number=123456789&entity_type=person_entity" 
Copy to clipboard

Example request

GetMatchingRecordRulesOptions getMatchingRecordRulesOptions = new GetMatchingRecordRulesOptions.Builder()
  .recordNumber(Long.valueOf("123456789"))
  .entityType("entity-type")
  .build();

Response<Map<String, List<RulesEntityRule>>> response = mdmService.getMatchingRecordRules(getMatchingRecordRulesOptions).execute();
Map<String, List<RulesEntityRule>> mapStringListRulesEntityRule = response.getResult();

System.out.println(mapStringListRulesEntityRule);
Copy to clipboard

Response

Response type: Map<String, List<RulesEntityRule>>

Response Body

object

Response wrapper object for linkage rules

Status Code

200
The request has been successfully finished.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "person_entity": [
    {
      "src_recno": "35677335438998529",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user2",
      "last_updated": "1605178647781"
    }
  ]
}
Copy to clipboard

Success example

{
  "person_entity": [
    {
      "src_recno": "35677335438998529",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user2",
      "last_updated": "1605178647781"
    }
  ]
}
Copy to clipboard

This service removes one or more manual link/unlink rules supplied by user.

This service removes one or more manual link/unlink rules supplied by user.

POST /mdm/v1/delete_linkage_rules

ServiceCall<Map<String, List<RulesEntityRule>>> deleteMatchingRule(DeleteMatchingRuleOptions deleteMatchingRuleOptions)

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.write

Request

Use the DeleteMatchingRuleOptions.Builder to create a DeleteMatchingRuleOptions object that contains the parameter values for the deleteMatchingRule method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

RulesRequest

The wrapper object of linkage rules

DeleteMatchingRuleOptions

The deleteMatchingRule options.

Remove manual link/unlink

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/delete_linkage_rules?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"entity_type":"person_entity","{"rules":[{"record_numbers":["32995408531474430"],"rule_type":"unlink","description":"test"}]}}" 
Copy to clipboard

Example request

RulesRequestRule rulesRequestRuleModel = new RulesRequestRule.Builder()
  .ruleType("testString")
  .recordNumbers(new java.util.ArrayList<String>(java.util.Arrays.asList("testString")))
  .description("testString")
  .build();
DeleteMatchingRuleOptions deleteMatchingRuleOptions = new DeleteMatchingRuleOptions.Builder()
  .rules(new java.util.ArrayList<RulesRequestRule>(java.util.Arrays.asList(rulesRequestRuleModel)))
  .entityType("testString")
  .build();

Response<Map<String, List<RulesEntityRule>>> response = mdmService.deleteMatchingRule(deleteMatchingRuleOptions).execute();
Map<String, List<RulesEntityRule>> mapStringListRulesEntityRule = response.getResult();

System.out.println(mapStringListRulesEntityRule);
Copy to clipboard

Response

Response type: Map<String, List<RulesEntityRule>>

Response Body

object

Response wrapper object for linkage rules

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
409
The request cannot be processed due to presence of quarantine record(s)
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}
Copy to clipboard

Success example

{
  "person_entity": [
    {
      "src_recno": "35677335438998528",
      "target_recno": "35677332186315776",
      "rule_type": "LINK",
      "description": "string",
      "user": "user1",
      "last_updated": "1605178647780"
    }
  ]
}
Copy to clipboard

This service checks for the existence of valid and invalid linkage rules for specified entity type when record filter is enabled.*

GET /mdm/v1/linkage_rules/exist

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
The data type identifier of source records, ie. person, organization, contract

Example: person
entity_type
string
The data type identifier of entity, ie. person_entity, organization_entity, household_entity

Example: person_entity
invalid
boolean
To check if invalid manual linkage rules exist, default is false

Default: false

Response

Response Body

RulesExist

Response wrapper object of checking existence of linkage rules

Status Code

200
The request has been successfully finished.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
404
The request cannot be processed due to resource not found.
500
The request cannot be processed due to an unexpected system error.

Example responses

{ "linkage_rules_exist": "true", }

This service retrives details about all the bucket hashes supplied as an input

POST /mdm/v1/bucket_details

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
The data type identifier of source records, ie. person, organization, contract

Example: person
include_standardized_data
boolean
To check if invalid manual linkage rules exist, default is false

Default: false

Request Body

Required*

PostHashDetailsRequest

The wrapper Object for list of bucket hashes

Response

Response Body

object

Response wrapper object for bucket hash details

Status Code

200
The request has been successfully finished.
400
The request cannot be processed due to user error.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

Example responses

Status 200

{
  "1277079518137406915": {
    "candidate_records_count": 1,
    "bucket_group": 1,
    "member_records": [
      "130063453988585473"
    ],
    "isLarge": false,
    "contributing_prehashed_value": "JRLT",
    "contributing_attributes_derived_data": {
      "130063453988585473": {
        "legal_name": [
          {
            "last_name": [
              "TEEL"
            ],
            "given_name": [
              "JERRY"
            ]
          }
        ]
      }
    }
  }
}
Copy to clipboard

GET /mdm/v1/matching_health

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.matching.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
target
string
a target of the health check, ie. es, fdb, rabbitmq, neo4j, all

Default: all

Response

Response Body

GetMatchingHealth

Response object for get matching health

Status Code

200
The matching service is healthy on the specified target.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

No Sample Response

This method does not specify any sample responses.

GET /mdm/v1/model_health

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.model.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
target
string
a target of the health check, ie. fdb, rabbitmq

Default: all

Response

Response Body

GetModelHealth

Response object for get model health

Status Code

200
The model service is healthy on the specified target.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

No Sample Response

This method does not specify any sample responses.

A delete can target either records or relationships in the graph. If not specified, records are targeted by default. There are four options for a delete:

Delete by search, which removes all elements matching a search criteria. This delete type is only supported for records.
Delete by source, which removes all elements of a specified source.
Delete by asset, which removes all elements loaded from a particular asset or list of assets.
Full delete, which removes all elements from the graph.

There are four options for a delete:

Delete by search, which removes all records matching a search criteria.
Delete by source, which removes all records of a specified record source.
Delete by asset, which removes all records loaded from a particular asset or list of assets.
Full delete, which removes all records from the graph.

POST /mdm/v1/bulk_delete

ServiceCall<BulkDeleteJob> runDataBulkDelete(RunDataBulkDeleteOptions runDataBulkDeleteOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.manage

Request

Use the RunDataBulkDeleteOptions.Builder to create a RunDataBulkDeleteOptions object that contains the parameter values for the runDataBulkDelete method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
executor_count
integer
The number of spark executors

Example: 1
executor_memory
string
Amount of memory to use per executor process

Example: 8g
executor_core_count
integer
The number of cores to use on each executor

Example: 1
spark_parallelism
integer
The number of partitions to be used by spark

Example: 2
batch_size
integer
batch size of the query parameter

Default: 1000
Example: 1000
retry_count
integer
No.of retries, if any failure occur

Example: 10

Request Body

Required*

BulkDeleteRequest

Valid object defining the bulk delete job information.

RunDataBulkDeleteOptions

The runDataBulkDelete options.

Start an operation to bulk delete data from the graph

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_delete?crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"delete_type":"full"}" 
Copy to clipboard

Example request

RunDataBulkDeleteOptions runDataBulkDeleteOptions = new RunDataBulkDeleteOptions.Builder()
  .deleteType("asset")
  .build();

Response<BulkDeleteJob> response = mdmService.runDataBulkDelete(runDataBulkDeleteOptions).execute();
BulkDeleteJob bulkDeleteJob = response.getResult();

System.out.println(bulkDeleteJob);

Response

Response Body

BulkDeleteJob

Information about a bulk delete job.

BulkDeleteJob

Information about a bulk delete job.

Status Code

202
The bulk delete job was successfully started.
400
Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem performing bulk delete. An internal error occurred while attempting to perform the operation.

Example responses

Status 202

{
  "job_id": "24403560707830722",
  "job_type": "delete",
  "process_ids": [
    "b3ba096d-c625-4d2f-ad12-285966f61cb0"
  ],
  "start_time": "1603483531000",
  "status": "running",
  "delete_type": "source",
  "record_source": "MDM"
}
Copy to clipboard

Success example

{
  "job_id": "24403560707830722",
  "job_type": "delete",
  "process_ids": [
    "b3ba096d-c625-4d2f-ad12-285966f61cb0"
  ],
  "start_time": "1603483531000",
  "status": "running",
  "delete_type": "source",
  "record_source": "MDM"
}
Copy to clipboard

Once the data load job is queued, track the status of the job to completion using the Job APIs.

To run a sample bulk load, provide the type as 'sample' and the directory_ref identifying which sample data set to load. directory_path is not required when type is set to 'sample', if provided it will be ignored. The available sample data sets are sample_contract_small, sample_consent_small, sample_contract, and sample_consent, and these are the only acceptable values for 'directory_ref'.
To run a bulk load of custom data, provide the type as 'dfs' and the directory_path pointing to the relative location of the data within the storage system. 'directory_ref' is not required when type is set to 'dfs', if provided it will be ignored. Data source directories are expected to adhere to the following format, if not otherwise specified under 'data_structure' in the request body:

record.properties
relationship.properties
group.properties
group_association.properties
record
--[record data files]
relationship
--[relationship data files]
group
--[group data files]
group_association
--[group_association data files]

To run a bulk load of data from the IBM Knowledge Catalog, provide the type as 'wkc' and either the 'project_id' or 'catalog_id' of the resource that contains the data. If both are provided, 'catalog_id' will be used by default. 'directory_ref' and 'directory_path' are not required when type is set to 'wkc', if provided they will be ignored. The data asset id and properties must be specified under 'data_structure' in the request body.
For bulk loads of type 'dfs' or 'wkc', required data properties must be supplied either in a properties file or by specifying the properties contents in the request. If both a file and properties contents are provided, the properties contents will take precedence. Properties contents must include 'file_type' to be valid.
To enable efficient deletion of a data asset in the future after bulk loading completes, please ensure that the optional 'collection_id' attribute is specified in the set of properties defined in the request. Alternatively, the value can be configured using the 'json.collection.id' or 'csv.collection.id' property in the data load properties file, depending on your data structure.
For CSV import option if includes_header_row is set as true then header must be present in all partitions.

To specify a COS directory, directory_path should be in the format <bucket_name>/<directory_path>. If the COS bucket is not the provided tenant bucket, the origin field must be set to external and an IAM API key with access to the bucket must be provided in the api_key field. If the data directories do not follow the above format, the data structure field must be provided.

Once the data load job is queued, track the status of the job to completion using the Job APIs.

To run a sample bulk load, provide the type as 'sample' and the directory_ref identifying which sample data set to load. directory_path is not required when type is set to 'sample', if provided it will be ignored. The available sample data sets are sample_contract_small, sample_consent_small, sample_contract, and sample_consent, and these are the only acceptable values for 'directory_ref'.
To run a bulk load of custom data, provide the type as 'dfs' and the directory_path pointing to the relative location of the data within the storage system. 'directory_ref' is not required when type is set to 'dfs', if provided it will be ignored. Data source directories are expected to adhere to the following format, if not otherwise specified under 'data_structure' in the request body:

--[record data files] relationship
--[relationship data files]

To run a bulk load of data from the Watson Knowledge Catalog, provide the type as 'wkc' and either the 'project_id' or 'catalog_id' of the resource that contains the data. If both are provided, 'catalog_id' will be used by default. 'directory_ref' and 'directory_path' are not required when type is set to 'wkc', if provided they will be ignored. The data asset id and properties must be specified under 'data_structure' in the request body.
For bulk loads of type 'dfs' or 'wkc', required data properties must be supplied either in a properties file or by specifying the properties contents in the request. If both a file and properties contents are provided, the properties contents will take precedence. Properties contents must include 'file_type' to be valid.

POST /mdm/v1/bulk_load

ServiceCall<BulkLoadJob> runDataBulkLoad(RunDataBulkLoadOptions runDataBulkLoadOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.write

Request

Use the RunDataBulkLoadOptions.Builder to create a RunDataBulkLoadOptions object that contains the parameter values for the runDataBulkLoad method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
executor_count
integer
The number of spark executors

Example: 1
executor_memory
string
Amount of memory to use per executor process

Example: 8g
executor_core_count
integer
The number of cores to use on each executor

Example: 1
batch_size
integer
Batch Size

Example: 100
record_volume
int64
Record Volume

Example: 5000
spark_parallelism
integer
The number of partitions to be used by spark

Example: 2
is_initial_load
boolean
Is initial load of data

Default: false
Example: true

Request Body

Required*

BulkLoadRequest

Valid object defining the data source and parameters for the bulk load job.

RunDataBulkLoadOptions

The runDataBulkLoad options.

Start a bulk load of data into the graph

curl -X POST --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/bulk_load?crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" --data "{"data_source":{"directory_path":"34dcd76c-f083-4186-8e0f-5a6a43bf481f/","type":"dfs"},"data_structure":{"record_path":"person/record/person-100.csv","record_properties":"person/record.properties"}}" 
Copy to clipboard

Example request

DataLoadSource dataLoadSourceModel = new DataLoadSource.Builder()
  .type("dfs")
  .build();
RunDataBulkLoadOptions runDataBulkLoadOptions = new RunDataBulkLoadOptions.Builder()
  .dataSource(dataLoadSourceModel)
  .build();

Response<BulkLoadJob> response = mdmService.runDataBulkLoad(runDataBulkLoadOptions).execute();
BulkLoadJob bulkLoadJob = response.getResult();

System.out.println(bulkLoadJob);
Copy to clipboard

Response

Response Body

BulkLoadJob

Information about a bulk load job.

BulkLoadJob

Information about a bulk load job.

Status Code

202
The bulk load job was successfully started.
400
Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem performing bulk load. An internal error occurred while attempting to perform the operation.
503
Problem performing bulk load. A bulk load process is already running.

Example responses

Status 202

{
  "job_id": "11734859286522966",
  "job_type": "bulk_load",
  "process_ids": [
    "3d2a5f4a-4784-4562-9252-2aa5afa3547f",
    "cfdf26ea-040e-4ce1-80b4-a7491acd0198"
  ],
  "start_time": "1603479295000",
  "status": "running",
  "load_stage": "vertices"
}
Copy to clipboard

Success example

{
  "job_id": "11734859286522966",
  "job_type": "bulk_load",
  "process_ids": [
    "3d2a5f4a-4784-4562-9252-2aa5afa3547f",
    "cfdf26ea-040e-4ce1-80b4-a7491acd0198"
  ],
  "start_time": "1603479295000",
  "status": "running",
  "load_stage": "vertices"
}
Copy to clipboard

Run an update of records and relationships in the graph by creating, modifying and deleting data in a single transaction. This operation is intended for incremental updates of data. Please use the bulk load feature when loading large volumes of data.

The operation runs as follows:

Performs all relationship deletions first, then record deletions.
After the deletions are completed, all record upserts (i.e. insertions and updates) are performed next, followed by relationship upserts.
Any element found in both deletions and upserts is treated as a deletion, and is removed from the upserts list before processing.
Any other case of a duplicated element will cause the update to fail.
If the 'ignore_redundant_updates' parameter is set to 'true', any update with a timestamp that is not newer than the existing timestamp for that element will not be applied, but it will not cause the entire transaction to fail. If the flag is set to 'false', invalid timestamps will cause a transaction failure.
If 'operation_strategy' is set to 'patch', any attributes not specified will be unchanged on the existing record or relationship. Attributes and fields can be removed by setting the attribute or field value to null. If 'operation_strategy' is not set to 'patch', existing attributes on the record or relationship will be overwritten.
A failed update will cause all changes performed by the transaction to be reverted back to the original graph state.

Run an update of records and relationships in the graph by creating, modifying and deleting data in a single transaction. This operation is intended for incremental updates of data. Please use the bulk load feature when loading large volumes of data.

The operation runs as follows:

Performs all relationship deletions first, then record deletions.
After the deletions are completed, all record upserts (i.e. insertions and updates) are performed next, followed by relationship upserts.
Any element found in both deletions and upserts is treated as a deletion, and is removed from the upserts list before processing.
Any other case of a duplicated element will cause the update to fail.
If the 'ignore_redundant_updates' parameter is set to 'true', any update with a timestamp that is not newer than the existing timestamp for that element will not be applied, but it will not cause the entire transaction to fail. If the flag is set to 'false', invalid timestamps will cause a transaction failure.
A failed update will cause all changes performed by the transaction to be reverted back to the original graph state.

POST /mdm/v1/ongoing_sync

ServiceCall<Void> runDataOngoingSync(RunDataOngoingSyncOptions runDataOngoingSyncOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.manage

Request

Use the RunDataOngoingSyncOptions.Builder to create a RunDataOngoingSyncOptions object that contains the parameter values for the runDataOngoingSync method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
ignore_redundant_updates
boolean
Whether to ignore updates that fail due to missing or invalid 'record_last_updated' timestamps.

Default: false

Request Body

Required*

SyncUpdateRequest

Valid object defining the elements to be inserted, updated or deleted on the graph.

RunDataOngoingSyncOptions

The runDataOngoingSync options.

Example request

RunDataOngoingSyncOptions runDataOngoingSyncOptions = new RunDataOngoingSyncOptions.Builder()
  .build();

Response<Void> response = mdmService.runDataOngoingSync(runDataOngoingSyncOptions).execute();

Response

Status Code

204
The updates have been successfully processed.
400
Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem performing bulk update. An internal error occurred while attempting to update the graph.

No Sample Response

This method does not specify any sample responses.

Execute composite transactions.

PUT /mdm/v1/composite_service

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.write

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

CompositeRequest

Valid object defining the composite transaction.

Response

Response Body

CompositeResponse

Status Code

201
Composite transaction has been successfully executed.
400
Problem executing composite transaction. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem executing composite transaction. An internal error occurred while attempting to create the record.

No Sample Response

This method does not specify any sample responses.

GET /mdm/v1/data_health

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
target
string
a target of the health check for fdb (fdb, es, rabbitmq, all) and neo4j (neo4j, rabbitmq, all)

Default: all

Response

Response Body

DataHealthStatusResponse

Response object for get data health

Status Code

200
The data service is healthy on the specified target.
401
The request cannot be processed due to authentication error.
403
The request cannot be processed due to insufficient permission error.
500
The request cannot be processed due to an unexpected system error.

No Sample Response

This method does not specify any sample responses.

View attributes for an entity in a consolidated view based on defined composite view rules from the request.

POST /mdm/v1/entities

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Query Parameters

crn
Required*
string
The cloud resource name of the service.
entity_type
Required*
string
Entity Type

Request Body

Required*

RecordIdList

List of recordIds for which composite view is to be found

Examples:

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

200
The composite view has been successfully retrieved.
400
Problem getting composite view of entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting composite view of entity. Entity with id <entity_id> does not exist.
500
Problem getting composite view of entity. An internal error occurred while attempting to retrieve the composite view.

Example responses

Status 200

{
  "entity": {
    "attributes": {
      "birth_date": {
        "attribute_last_updated": "1548936483016",
        "value": "1934-05-11T00:00:00.000Z"
      },
      "entity_last_updated": "1603572360787",
      "gender": {
        "attribute_last_updated": "1548936483016",
        "value": "F"
      },
      "legal_name": {
        "attribute_last_updated": "1548936483016",
        "last_name": "LEES",
        "given_name": "KAROLYN"
      },
      "primary_residence": {
        "attribute_last_updated": "1548936483189",
        "address_province_state_value": "KY",
        "address_city": "ELLIOTTVILLE",
        "address_zip_postal_code": "40317",
        "address_line_1": "106 EAST SYCAMORE ST.",
        "address_record_id": "215054896528318812",
        "address_line_2": "Unit-701"
      },
      "record_id": "216754896528315937",
      "record_source": "MDM"
    },
    "id": "person_entity-53496",
    "type": "entity",
    "record_count": 1,
    "type_name": "person_entity"
  },
  "metadata": {
    "href": "${host}/mdm/v1/entities/person_entity-53496?crn=${crn}",
    "id": "person_entity-53496",
    "updated_at": "2020-10-24T20:46:00.787Z"
  }
}
Copy to clipboard

View a list of member records that form the entity.

GET /mdm/v1/entities/{id}/records

ServiceCall<DataRecordsResponse> listDataRecordsForEntity(ListDataRecordsForEntityOptions listDataRecordsForEntityOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Use the ListDataRecordsForEntityOptions.Builder to create a ListDataRecordsForEntityOptions object that contains the parameter values for the listDataRecordsForEntity method.

Path Parameters

id
Required*
string
The unique identifier of the entity.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
limit
integer
The maximum number of records to return in each page of results. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10
offset
integer
The number of records to skip before returning a page of results.

Default: 0
include
string[]
Record attributes from the data model to include in the results.

Possible values: contains only unique items
Examples:
[ "legal_name.given_name" ]
exclude
string[]
Record attributes from the data model to exclude from the results.

Possible values: contains only unique items
Examples:
[ "legal_name.given_name" ]
include_total_count
boolean
Flag to include the total record count on pages other than the first.

Default: true

ListDataRecordsForEntityOptions

The listDataRecordsForEntity options.

List the records linked into an entity

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entities/12345/records?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::&include=legal_name.given_name&exclude=legal_name.last_name" 
Copy to clipboard

Example request

ListDataRecordsForEntityOptions listDataRecordsForEntityOptions = new ListDataRecordsForEntityOptions.Builder()
  .id("testString")
  .include(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .exclude(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .build();

Response<DataRecordsResponse> response = mdmService.listDataRecordsForEntity(listDataRecordsForEntityOptions).execute();
DataRecordsResponse dataRecordsResponse = response.getResult();

System.out.println(dataRecordsResponse);
Copy to clipboard

Response

Response Body

DataRecordsResponse

Paged information about a collection of records.

DataRecordsResponse

Paged information about a collection of records.

Status Code

200
The entity records have been successfully retrieved.
400
Problem getting records for entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting records for entity: Entity with id <entity_id> does not exist.
500
Problem getting records for entity. An internal error occurred while attempting to retrieve the records.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/records?crn=${crn}&return_type=results_as_entities&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/records?crn=${crn}&return_type=results_as_entities&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "records": [
    {
      "attributes": {
        "birth_date": {
          "attribute_last_updated": "1548936483016",
          "value": "1934-05-11T00:00:00.000Z"
        },
        "gender": {
          "attribute_last_updated": "1548936483016",
          "value": "F"
        },
        "legal_name": {
          "attribute_last_updated": "1548936483016",
          "last_name": "LEES",
          "given_name": "KAROLYN"
        },
        "primary_residence": {
          "attribute_last_updated": "1548936483189",
          "address_province_state_value": "KY",
          "address_city": "ELLIOTTVILLE",
          "address_zip_postal_code": "40317",
          "address_province_state_type": "21",
          "address_line_1": "106 EAST SYCAMORE ST.",
          "address_record_id": "215054896528318812",
          "address_line_2": "Unit-701"
        },
        "record_id": "216754896528315937",
        "record_last_updated": "1603572360787",
        "record_source": "MDM"
      },
      "id": "53496",
      "type": "record",
      "record_number": 53496,
      "type_name": "person"
    }
  ]
}
Copy to clipboard

Success example

{
  "first": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/records?crn=${crn}&return_type=results_as_entities&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/records?crn=${crn}&return_type=results_as_entities&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "records": [
    {
      "attributes": {
        "birth_date": {
          "attribute_last_updated": "1548936483016",
          "value": "1934-05-11T00:00:00.000Z"
        },
        "gender": {
          "attribute_last_updated": "1548936483016",
          "value": "F"
        },
        "legal_name": {
          "attribute_last_updated": "1548936483016",
          "last_name": "LEES",
          "given_name": "KAROLYN"
        },
        "primary_residence": {
          "attribute_last_updated": "1548936483189",
          "address_province_state_value": "KY",
          "address_city": "ELLIOTTVILLE",
          "address_zip_postal_code": "40317",
          "address_province_state_type": "21",
          "address_line_1": "106 EAST SYCAMORE ST.",
          "address_record_id": "215054896528318812",
          "address_line_2": "Unit-701"
        },
        "record_id": "216754896528315937",
        "record_last_updated": "1603572360787",
        "record_source": "MDM"
      },
      "id": "53496",
      "type": "record",
      "record_number": 53496,
      "type_name": "person"
    }
  ]
}
Copy to clipboard

View attributes for an entity in a consolidated view based on defined composite view rules from the Model APIs.

GET /mdm/v1/entities/{id}

ServiceCall<DataEntityResponse> getDataEntity(GetDataEntityOptions getDataEntityOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Use the GetDataEntityOptions.Builder to create a GetDataEntityOptions object that contains the parameter values for the getDataEntity method.

Path Parameters

id
Required*
string
The unique identifier of the entity.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
include
string[]
Record attributes from the data model to include in the results.

Possible values: contains only unique items
Examples:
[ "legal_name.given_name" ]
exclude
string[]
Record attributes from the data model to exclude from the results.

Possible values: contains only unique items
Examples:
[ "legal_name.given_name" ]

GetDataEntityOptions

The getDataEntity options.

Get the composite view for an entity

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entities/12345?include=legal_name.given_name&exclude=legal_name.last_name&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

GetDataEntityOptions getDataEntityOptions = new GetDataEntityOptions.Builder()
  .id("testString")
  .include(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .exclude(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .build();

Response<DataEntityResponse> response = mdmService.getDataEntity(getDataEntityOptions).execute();
DataEntityResponse dataEntityResponse = response.getResult();

System.out.println(dataEntityResponse);
Copy to clipboard

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

200
The composite view has been successfully retrieved.
400
Problem getting composite view of entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting composite view of entity. Entity with id <entity_id> does not exist.
500
Problem getting composite view of entity. An internal error occurred while attempting to retrieve the composite view.

Example responses

Status 200

{
  "entity": {
    "attributes": {
      "birth_date": {
        "attribute_last_updated": "1548936483016",
        "value": "1934-05-11T00:00:00.000Z"
      },
      "entity_last_updated": "1603572360787",
      "gender": {
        "attribute_last_updated": "1548936483016",
        "value": "F"
      },
      "legal_name": {
        "attribute_last_updated": "1548936483016",
        "last_name": "LEES",
        "given_name": "KAROLYN"
      },
      "primary_residence": {
        "attribute_last_updated": "1548936483189",
        "address_province_state_value": "KY",
        "address_city": "ELLIOTTVILLE",
        "address_zip_postal_code": "40317",
        "address_line_1": "106 EAST SYCAMORE ST.",
        "address_record_id": "215054896528318812",
        "address_line_2": "Unit-701"
      },
      "record_id": "216754896528315937",
      "record_source": "MDM"
    },
    "id": "person_entity-53496",
    "type": "entity",
    "record_count": 1,
    "type_name": "person_entity"
  },
  "metadata": {
    "href": "${host}/mdm/v1/entities/person_entity-53496?crn=${crn}",
    "id": "person_entity-53496",
    "updated_at": "2020-10-24T20:46:00.787Z"
  }
}
Copy to clipboard

Success example

{
  "entity": {
    "attributes": {
      "birth_date": {
        "attribute_last_updated": "1548936483016",
        "value": "1934-05-11T00:00:00.000Z"
      },
      "entity_last_updated": "1603572360787",
      "gender": {
        "attribute_last_updated": "1548936483016",
        "value": "F"
      },
      "legal_name": {
        "attribute_last_updated": "1548936483016",
        "last_name": "LEES",
        "given_name": "KAROLYN"
      },
      "primary_residence": {
        "attribute_last_updated": "1548936483189",
        "address_province_state_value": "KY",
        "address_city": "ELLIOTTVILLE",
        "address_zip_postal_code": "40317",
        "address_line_1": "106 EAST SYCAMORE ST.",
        "address_record_id": "215054896528318812",
        "address_line_2": "Unit-701"
      },
      "record_id": "216754896528315937",
      "record_source": "MDM"
    },
    "id": "person_entity-53496",
    "type": "entity",
    "record_count": 1,
    "type_name": "person_entity"
  },
  "metadata": {
    "href": "${host}/mdm/v1/entities/person_entity-53496?crn=${crn}",
    "id": "person_entity-53496",
    "updated_at": "2020-10-24T20:46:00.787Z"
  }
}
Copy to clipboard

Replace the existing persisted entity with the new set of attributes. Any existing editable entity-level attributes not specified in the request will be removed from the entity.

PUT /mdm/v1/entities/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.write

Request

Path Parameters

id
Required*
string
The unique identifier of the entity.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

DataEntity

Valid object defining the attributes of an entity to replace the existing entity-level attributes. All non-entity attributes will be ignored.

Examples:

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

200
The entity attributes have been successfully updated.
400
Problem updating attributes of entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem updating attributes of entity. Entity is not persisted on the graph.
500
Problem updating attributes of entity. An internal error occurred while attempting to update the entity attributes.

Example responses

Status 200

{
  "entity": {
    "attributes": {
      "birth_date": {
        "value": "1934-05-11T00:00:00.000Z"
      },
      "entity_last_updated": "1603572360787",
      "gender": {
        "attribute_last_updated": "1548936483016",
        "value": "F"
      },
      "legal_name": {
        "attribute_last_updated": "1548936483016",
        "last_name": "LEES",
        "given_name": "KAROLYN"
      },
      "primary_residence": {
        "attribute_last_updated": "1548936483189",
        "address_province_state_value": "KY",
        "address_city": "ELLIOTTVILLE",
        "address_zip_postal_code": "40317",
        "address_line_1": "106 EAST SYCAMORE ST.",
        "address_record_id": "215054896528318812",
        "address_line_2": "Unit-701"
      },
      "family_name": {
        "attribute_last_updated": "1548936483016",
        "value": "Doe"
      },
      "record_id": "216754896528315937",
      "record_source": "MDM"
    },
    "id": "person_entity-53496",
    "type": "entity",
    "record_count": 1,
    "type_name": "person_entity"
  },
  "metadata": {
    "href": "${host}/mdm/v1/entities/person_entity-53496?crn=${crn}",
    "id": "person_entity-53496",
    "updated_at": "2020-10-24T20:46:00.787Z"
  }
}
Copy to clipboard

Patch the existing persisted entity with the new set of attributes. Any existing editable entity-level attributes not specified in the request will be retained in the entity.

PATCH /mdm/v1/entities/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.write

Request

Path Parameters

id
Required*
string
The unique identifier of the entity.

Query Parameters

crn
Required*
string
The cloud resource name of the service.

Request Body

Required*

DataEntity

Valid object defining the attributes of an entity to patch the existing entity-level attributes. All non-entity attributes will be ignored.

Examples:

Response

Response Body

DataEntityResponse

Information and metadata about the composite view of an entity.

Status Code

200
The entity attributes have been successfully patched.
400
Problem patching attributes of entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem patching attributes of entity. Entity is not persisted on the graph.
500
Problem patching attributes of entity. An internal error occurred while attempting to patch the entity attributes.

Example responses

Status 200

{
  "entity": {
    "attributes": {
      "birth_date": {
        "value": "1934-05-11T00:00:00.000Z"
      },
      "entity_last_updated": "1603572360787",
      "gender": {
        "attribute_last_updated": "1548936483016",
        "value": "F"
      },
      "legal_name": {
        "attribute_last_updated": "1548936483016",
        "last_name": "LEES",
        "given_name": "KAROLYN"
      },
      "primary_residence": {
        "attribute_last_updated": "1548936483189",
        "address_province_state_value": "KY",
        "address_city": "ELLIOTTVILLE",
        "address_zip_postal_code": "40317",
        "address_line_1": "106 EAST SYCAMORE ST.",
        "address_record_id": "215054896528318812",
        "address_line_2": "Unit-701"
      },
      "family_name": {
        "attribute_last_updated": "1548936483016",
        "value": "Doe"
      },
      "record_id": "216754896528315937",
      "record_source": "MDM"
    },
    "id": "person_entity-53496",
    "type": "entity",
    "record_count": 1,
    "type_name": "person_entity"
  },
  "metadata": {
    "href": "${host}/mdm/v1/entities/person_entity-53496?crn=${crn}",
    "id": "person_entity-53496",
    "updated_at": "2020-10-24T20:46:00.787Z"
  }
}
Copy to clipboard

View a list of relationships that exist between the given entity and other nodes on the graph. This endpoint does not include internal relationships in the resulting list of relationships.

GET /mdm/v1/entities/{id}/relationships

ServiceCall<DataRelationshipsResponse> listDataRelationshipsForEntity(ListDataRelationshipsForEntityOptions listDataRelationshipsForEntityOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Use the ListDataRelationshipsForEntityOptions.Builder to create a ListDataRelationshipsForEntityOptions object that contains the parameter values for the listDataRelationshipsForEntity method.

Path Parameters

id
Required*
string
The ID of the entity.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
relationship_types
string[]
The relationship types to return.
include_record_relationships
string
Whether to include entity record relationships to other nodes.

Default: false
offset
integer
The number of relationships to skip over.

Default: 0
limit
integer
The number of relationships to be returned. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10
source_include
string[]
Attributes from the data model to include in the results for the source vertex.

Possible values: contains only unique items
Examples:
[ "all" ]
target_include
string[]
Attributes from the data model to include in the results for the target vertex.

Possible values: contains only unique items
Examples:
[ "all" ]

ListDataRelationshipsForEntityOptions

The listDataRelationshipsForEntity options.

Example request

ListDataRelationshipsForEntityOptions listDataRelationshipsForEntityOptions = new ListDataRelationshipsForEntityOptions.Builder()
  .id("testString")
  .build();

Response<DataRelationshipsResponse> response = mdmService.listDataRelationshipsForEntity(listDataRelationshipsForEntityOptions).execute();
DataRelationshipsResponse dataRelationshipsResponse = response.getResult();

System.out.println(dataRelationshipsResponse);

Response

Response Body

DataRelationshipsResponse

Paged information about a collection of relationships.

DataRelationshipsResponse

Paged information about a collection of relationships.

Status Code

200
The relationships have been successfully retrieved.
400
Problem getting relationships for entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting relationships for entity. Entity not found.
500
Problem getting relationships for entity. An internal error occurred while attempting to retrieve the relationships.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/entities/456/relationships?crn=${crn}&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/entities/456/relationships?crn=${crn}&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "relationships": [
    {
      "attributes": {
        "relationship_id": "997554896611881692",
        "relationship_last_updated": "1548937318815",
        "relationship_source": "MDM",
        "from_record_id": "358354896586841797",
        "from_record_source": "MDM",
        "from_record_type": "preference",
        "to_record_id": "998254896587316451",
        "to_record_source": "MDM",
        "to_record_type": "organization"
      },
      "id": "215tzl-5cw8-q7f9-oi7u8",
      "source": {
        "id": "4344",
        "type": "record",
        "type_name": "person"
      },
      "target": {
        "id": "456",
        "type": "entity",
        "type_name": "person_entity"
      },
      "type": "relationship",
      "type_name": "preference_association"
    }
  ]
}
Copy to clipboard

Success example

{
  "first": {
    "href": "${host}/mdm/v1/entities/456/relationships?crn=${crn}&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/entities/456/relationships?crn=${crn}&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "relationships": [
    {
      "attributes": {
        "relationship_id": "997554896611881692",
        "relationship_last_updated": "1548937318815",
        "relationship_source": "MDM",
        "from_record_id": "358354896586841797",
        "from_record_source": "MDM",
        "from_record_type": "preference",
        "to_record_id": "998254896587316451",
        "to_record_source": "MDM",
        "to_record_type": "organization"
      },
      "id": "215tzl-5cw8-q7f9-oi7u8",
      "source": {
        "id": "4344",
        "type": "record",
        "type_name": "person"
      },
      "target": {
        "id": "456",
        "type": "entity",
        "type_name": "person_entity"
      },
      "type": "relationship",
      "type_name": "preference_association"
    }
  ]
}
Copy to clipboard

View a list of records that have a relationship to the member records of the specified entity based on the specified relationship type. All records related to the specified entity will be returned regardless of relationship direction. The relationship type is expected to be defined in the data model.

GET /mdm/v1/entities/{id}/related_records

ServiceCall<RelatedRecords> listDataRelatedRecordsForEntity(ListDataRelatedRecordsForEntityOptions listDataRelatedRecordsForEntityOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Use the ListDataRelatedRecordsForEntityOptions.Builder to create a ListDataRelatedRecordsForEntityOptions object that contains the parameter values for the listDataRelatedRecordsForEntity method.

Path Parameters

id
Required*
string
The unique identifier of the entity.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
record_type
Required*
string
The type of records to return in results.
relationship_type
Required*
string
The type of relationship between related records and entity member records.
limit
integer
The maximum number of records to return in each page of results. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10
offset
integer
The number of records to skip before returning a page of results.

Default: 0
include
string[]
Record attributes from the data model to include in the results.

Possible values: contains only unique items
Examples:
[ "legal_name.given_name" ]
exclude
string[]
Record attributes from the data model to exclude from the results.

Possible values: contains only unique items
Examples:
[ "legal_name.given_name" ]
include_total_count
boolean
Flag to include the total record count on pages other than the first.

Default: true

ListDataRelatedRecordsForEntityOptions

The listDataRelatedRecordsForEntity options.

List the records associated with entity records

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/entities/12345/related_records?relationship_type=party_relationship&record_type=person&limit=10&offset=0&crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListDataRelatedRecordsForEntityOptions listDataRelatedRecordsForEntityOptions = new ListDataRelatedRecordsForEntityOptions.Builder()
  .id("testString")
  .recordType("testString")
  .relationshipType("testString")
  .include(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .exclude(new java.util.ArrayList<String>(java.util.Arrays.asList("legal_name.given_name")))
  .build();

Response<RelatedRecords> response = mdmService.listDataRelatedRecordsForEntity(listDataRelatedRecordsForEntityOptions).execute();
RelatedRecords relatedRecords = response.getResult();

System.out.println(relatedRecords);
Copy to clipboard

Response Body

RelatedRecords

Paged information about a set of other records related to an entity or a record.

RelatedRecords

Paged information about a set of other records related to an entity or a record.

Status Code

200
The related records for the entity have been successfully retrieved.
400
Problem getting related records for entity. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
404
Problem getting related records for entity. Entity with id does not exist.
500
Problem getting related records for entity. An internal error occurred while attempting to retrieve the records.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/related_records?crn=${crn}&relationship_type=party_relationship&record_type=person&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/related_records?crn=${crn}&relationship_type=party_relationship&record_type=person&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "related_records": [
    {
      "attributes": {
        "record_id": "535354896573139473",
        "record_last_updated": "1603572360787",
        "record_source": "MDM",
        "usage_type": {
          "attribute_last_updated": "1548936483189",
          "value": "3"
        },
        "usage_value": {
          "attribute_last_updated": "1548936483189",
          "value": "Retail Banking"
        }
      },
      "id": "192616",
      "type": "record",
      "record_number": 192616,
      "type_name": "preference"
    }
  ]
}
Copy to clipboard

Success example

{
  "first": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/related_records?crn=${crn}&relationship_type=party_relationship&record_type=person&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/entities/person_entity-53496/related_records?crn=${crn}&relationship_type=party_relationship&record_type=person&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "total_count": 1,
  "related_records": [
    {
      "attributes": {
        "record_id": "535354896573139473",
        "record_last_updated": "1603572360787",
        "record_source": "MDM",
        "usage_type": {
          "attribute_last_updated": "1548936483189",
          "value": "3"
        },
        "usage_value": {
          "attribute_last_updated": "1548936483189",
          "value": "Retail Banking"
        }
      },
      "id": "192616",
      "type": "record",
      "record_number": 192616,
      "type_name": "preference"
    }
  ]
}
Copy to clipboard

View a summary list of export jobs that have been requested.

GET /mdm/v1/data_exports

ServiceCall<DataExports> listDataExports(ListDataExportsOptions listDataExportsOptions)
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

mdm-oc.data.read

Request

Use the ListDataExportsOptions.Builder to create a ListDataExportsOptions object that contains the parameter values for the listDataExports method.

Query Parameters

crn
Required*
string
The cloud resource name of the service.
offset
integer
The number of exports to skip before returning a page of results.

Default: 0
limit
integer
The maximum number of exports to return in each page of results. The maximum limit is 50.

Possible values: value ≤ 50
Default: 10
include_expired
boolean
Whether to include exports with expired files.

Default: true

ListDataExportsOptions

The listDataExports options.

List the export jobs

curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/mdm/v1/data_exports?crn=crn:v1:bluemix:public:mdm-oc:us-south:a/122c69f0e8296804c9eebf4dbd4530e4:f4d408e3-25ec-4d48-87fe-ac82018c3b32::" 
Copy to clipboard

Example request

ListDataExportsOptions listDataExportsOptions = new ListDataExportsOptions.Builder()
  .build();

Response<DataExports> response = mdmService.listDataExports(listDataExportsOptions).execute();
DataExports dataExports = response.getResult();

System.out.println(dataExports);

Response

Response Body

DataExports

Paged information about a collection of exports.

DataExports

Paged information about a collection of exports.

Status Code

200
The list of exports was retrieved successfully.
400
Problem getting list of exports. Input validation failed.
401
Problem processing request. The user is not authenticated.
403
Problem processing request. The user is not authorized to perform the request.
500
Problem getting list of exports. An internal error occurred while attempting to retrieve the list of exports.

Example responses

Status 200

{
  "first": {
    "href": "${host}/mdm/v1/data_exports?crn=${crn}&record_type=person&local=true&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/data_exports?crn=${crn}&record_type=person&local=true&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "exports": [
    {
      "end_time": "1603483621000",
      "job_id": "24403560707830722",
      "job_type": "export",
      "process_ids": [
        "b3ba096d-c625-4d2f-ad12-285966f61cb0"
      ],
      "start_time": "1603483531000",
      "status": "succeeded",
      "file_expired": false,
      "file_name": "records",
      "search_criteria": {
        "filters": [],
        "query": {
          "expressions": [
            {
              "condition": "equal",
              "expressions": [],
              "value": "JOHN"
            }
          ],
          "operation": "and"
        },
        "search_type": "record"
      }
    }
  ],
  "total_count": 1
}
Copy to clipboard

Success example

{
  "first": {
    "href": "${host}/mdm/v1/data_exports?crn=${crn}&record_type=person&local=true&offset=0&limit=10"
  },
  "last": {
    "href": "${host}/mdm/v1/data_exports?crn=${crn}&record_type=person&local=true&offset=0&limit=10"
  },
  "limit": 10,
  "offset": 0,
  "exports": [
    {
      "end_time": "1603483621000",
      "job_id": "24403560707830722",
      "job_type": "export",
      "process_ids": [
        "b3ba096d-c625-4d2f-ad12-285966f61cb0"
      ],
      "start_time": "1603483531000",
      "status": "succeeded",
      "file_expired": false,
      "file_name": "records",
      "search_criteria": {
        "filters": [],
        "query": {
          "expressions": [
            {
              "condition": "equal",
              "expressions": [],
              "value": "JOHN"
            }
          ],
          "operation": "and"
        },
        "search_type": "record"
      }
    }
  ],
  "total_count": 1
}
Copy to clipboard

Run a data export job to export the results of a search. Export format, search criteria, and file name are configurable in the message body. The file name must only contain alphanumeric characters, and be 64 characters or less.

The operation runs as follows:

On public cloud, instance metadata must be configured and include valid bucket credentials before an export job is started.
A compression type must be provided when a partition type of 'executor_count' is specified.

Run a data export job to export the results of a search. Export format, search criteria, and file name are configurable in the message body. The file name must only contain alphanumeric characters, and be 64 characters or less.

The operation runs as follows:

A compression type must be provided when a partition type of 'executor_count' is specified.

POST /mdm/v1/data_exports

ServiceCall<DataExport> createDataExport(CreateDataExportOptions createDataExportOptions)

Introduction

Endpoint URLs

Error handling

Authentication

Running composite transactions

When to use composite transactions

Example composite transaction scenario

Formatting the JSON payload of a composite transaction

Using values from variables or responses in requests

Adding conditional logic to a composite transaction

If-match/else logic

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

Looping logic

Running a composite transaction

Supported APIs for composite transactions

Methods

Get Config Data Model Type Attributes

Authorization

Request

Query Parameters

crn

type_category

type_name

GetConfiguratorConfigDataModelAttributesOptions

typeCategory

typeName

Response

Response Body

attributes

ConfigDataModelAttributes

attributes

dataType

defaultDisplayName

designation

name

Status Code

200

401

403

500

Get config data model

Authorization

Request

Query Parameters

crn

Response

Response Body

system_properties

attribute_types

any property

relationship_types

any property

locale

record_types

any property

hierarchy_types

any property

node_types

any property

group_types

any property

is_model_published

ConfigDataModel

recordTypes

label

attributes

classification

indexed

label

description

attributeType

cardinality

description

entityTypes

description

label

relationshipTypes

rules

source

recordTypes