IBM Match 360 with Watson | IBM Cloud API Docs

Introduction

Last updated: 2021-12-07

IBM Match 360 with Watson (Beta) provides APIs that enable you to connect the IBM Match 360 with Watson service's powerful master data matching capabilities to your systems and processes. IBM Match 360 with Watson (IBM Match 360) 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 on Cloud Pak for Data 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 with Watson APIs support:

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

For more information about using the IBM Match 360 with Watson 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 APIs in the Dallas global endpoint (us-south), go to the following URLs: - Configuration API: https://api.us-south.mdm.watson.cloud.ibm.com/api-configuration/explorer/ - Entity Maintenance API: https://api.us-south.mdm.watson.cloud.ibm.com/api-data/explorer/ - Job API: https://api.us-south.mdm.watson.cloud.ibm.com/api-job/explorer/ - Matching API: https://api.us-south.mdm.watson.cloud.ibm.com/api-matching/explorer/ - Model API: https://api.us-south.mdm.watson.cloud.ibm.com/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>

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 with Watson 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 below properties

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

and access the service 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 with Watson 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 with Watson 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 with Watson 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);
        }
    });

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());
}

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

Authentication

To authenticate to the IBM Match 360 with Watson 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);
    }
);

Example header parameter in a request

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

Example header parameter in a request

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

Gets the data model present in configuration space.

GET /mdm/v1/config_data_model

ServiceCall<ConfigDataModel> getConfiguratorConfigDataModel(GetConfiguratorConfigDataModelOptions getConfiguratorConfigDataModelOptions)

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

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 locale, record types, relationship types, system properties definition in configuration space.

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

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

Replaces the config data model present in configuration space.

PUT /mdm/v1/config_data_model

ServiceCall<ConfigDataModel> replaceConfiguratorConfigDataModel(ReplaceConfiguratorConfigDataModelOptions replaceConfiguratorConfigDataModelOptions)

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 locale, record types, relationship types, system properties definition in configuration space.

Examples:

ConfigDataModelExample

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

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

Response

Response Body

ConfigDataModel

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

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

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

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)

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

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

Success example

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

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)

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

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

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

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

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

GET /mdm/v1/configuration_metadata/processes

ServiceCall<ProcessList> listConfiguratorProcesses(ListConfiguratorProcessesOptions listConfiguratorProcessesOptions)

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

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

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

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

POST /mdm/v1/configuration_metadata/processes

ServiceCall<ProcessStatus> createConfiguratorProcess(CreateConfiguratorProcessOptions createConfiguratorProcessOptions)

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:

PublishDataExample-all_assets

PublishDataExample-selective_assets

AssetDeletionExample

PublishModelExample

MatchingExample

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

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

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",
  "message": "Matching is in progress."
}

Success example

{
  "status": "In-Progress",
  "message": "Matching is in progress."
}

Status 201

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

Success example

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

Status 201

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

Success example

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

Status 201

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

Success example

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

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

GET /mdm/v1/configuration_metadata

ServiceCall<ConfigurationMetadata> getConfiguratorConfigurationMetadata(GetConfiguratorConfigurationMetadataOptions getConfiguratorConfigurationMetadataOptions)

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

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

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

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)

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:

ConfigurationMetadataExample

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

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

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

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

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

PATCH /mdm/v1/configuration_metadata

ServiceCall<ConfigurationMetadata> updateConfiguratorConfigurationMetadata(UpdateConfiguratorConfigurationMetadataOptions updateConfiguratorConfigurationMetadataOptions)

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:

ConfigurationMetadataExample

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

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

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

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

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)

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:

projectAssetExample

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

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

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

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

Gets the process details for the specified process name.

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

ServiceCall<ProcessModelStatus> getConfiguratorProcess(GetConfiguratorProcessOptions getConfiguratorProcessOptions)

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

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

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

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

Success example

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

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)

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:

projectAssetExample

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

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

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

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

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)

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:

DataMappingExample

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

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

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

Success example

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

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)

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

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

Success example

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

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)

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

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

Success example

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

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.

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)

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.

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

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

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

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
record
--[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.

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)

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.

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

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

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

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

View a list of member records that form the entity.

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

ServiceCall<DataRecordsResponse> listDataRecordsForEntity(ListDataRecordsForEntityOptions listDataRecordsForEntityOptions)

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:
View
exclude
string[]
Record attributes from the data model to exclude from the results.

Possible values: contains only unique items
Examples:
View

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" 

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

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

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

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)

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:
View
exclude
string[]
Record attributes from the data model to exclude from the results.

Possible values: contains only unique items
Examples:
View

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

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

Response Body

RelatedRecords

Paged information about a set of other records related to an entity or a record.

Introduction

Endpoint URLs

Error handling

Authentication

Methods

Get config data model

Authorization

Request

Query Parameters

crn

Response

Response Body

record_types

any property

relationship_types

any property

attribute_types

any property

locale

system_properties

any property

ConfigDataModel

recordTypes

label

attributes

classification

indexed

label

description

attributeType

cardinality

description

entityTypes

description

label

relationshipTypes

rules

source

recordTypes

entityTypes

target

recordTypes

entityTypes

labelFromSource

labelFromTarget

directional

label

cardinality

description

attributes

classification

indexed

label

description

attributeType

cardinality

attributeTypes

label

description

classification

fields

description

classification

indexed

label

locale

systemProperties

recordTypes

editable

label

description

dataType

indexed

entityTypes

editable

label

description

dataType

indexed

relationshipTypes