Introduction
IBM Match 360 with Watson on IBM Cloud Pak for Data 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) enables you to establish a single, trusted, 360-degree view of your customers. IBM Match 360 includes 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, you can ensure that your users and systems have a total view of your data. With a seamlessly integrated, cross-solution experience, your users can discover master data directly in the space where they expect to consume it.
The IBM 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
Important: This reference documentation is for the v1 API, which applies to IBM Match 360 with Watson for Cloud Pak for Data 4.0.1 and above.
For more information about IBM Match 360 with Watson on Cloud Pak for Data, see the service's documentation in the IBM Cloud Pak for Data documentation.
Service endpoint
The IBM Match 360 with Watson service endpoint is based on your Cloud Pak for Data deployment URL.
https://<CPD_CLUSTER_HOST>:<PORT>/mdm/model/
For example, if your instance is deployed at https://www.example.com:31843
, you can access the IBM Match 360 APIs at https://www.example.com:31843/mdm/model/
.
Additionally, you can access, discover, and run API commands with the Swagger UI API Explorer at the URL https://<CPD_CLUSTER_HOST>/<MDM_INSTANCE_ID>/api-model/explorer/#
. For example, using the same instance host as in the previous example and an instance ID of 1664447707275339
, you can access the Swagger UI API Explorer IBM Match 360 APIs at https://www.example.com/1664447707275339/api-model/explorer/#
.
Example
curl -H "Authorization: Bearer {token}" -X {request_method} "https://<CPD_CLUSTER_HOST>:<PORT>/mdm/model/<METHOD>"
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. |
202 |
Accepted | The request was understood and accepted. Processing will continue in the background. |
202 |
No Content | The request was successful. No content will be returned. |
400 |
Bad Request | The input parameters in the request 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 try again. If this error persists, contact the account owner to check your permissions. |
403 |
Forbidden | The supplied authentication is not authorized to access the resource. Contact the account owner to check your permissions. |
404 |
Not Found | The requested resource could not be found. |
405 |
Method Not Allowed | The request is not allowed for the requested resource. |
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. |
410 |
Gone | The requested resource is no longer available and will not become available in the future. |
500 |
Internal Server Error | Your request could not be processed due to an internal error. Check server logs for more details. |
503 |
Service Unavailable | The requested service is currently unavailable. Wait a few minutes and try again. |
ErrorResponse
Name | Description |
---|---|
code integer |
HTTP error code. |
error string |
Human-readable error string, like 'Invalid image file'. |
ErrorAuthentication
Name | Description |
---|---|
status string |
The status of error. |
statusInfo string |
Information about the error. |
ErrorHTML
Name | Description |
---|---|
Error string |
HTML description of the error. |
statusInfo string |
Information about the error. |
ErrorInfo
Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.
Name | Description |
---|---|
code integer |
HTTP status code. |
description string |
Human-readable error description. For example, File size limit exceeded . |
error_id string |
Codified error string. For example, limit_exceeded . |
The Java SDK generates an exception for any unsuccessful method invocation. All methods that accept an argument can also throw an IllegalArgumentException
.
Exception | Description |
---|---|
IllegalArgumentException | An invalid argument was passed to the method. |
When the Java SDK receives an error response from the IBM Match 360 service, it generates an exception containing the following fields:
Field | Description |
---|---|
statusCode | The HTTP status code returned |
message | A message describing the error |
The Python SDK generates an exception for any unsuccessful method invocation. When the Python SDK receives an error response from the IBM Match 360 service, it generates an exception containing the following fields:
Field | Description |
---|---|
code | The HTTP status code returned |
message | A message describing the error |
info | A dictionary of additional information about the error |
Example error handling
try {
// Invoke a 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());
}
Authentication
To authenticate to the API, you must pass an IBM Cloud Pak for Data service instance token in an Authorization
header. You can retrieve the instance token by viewing the service instance details in the Cloud Pak for Data web interface or using the the /zen-data/v2/serviceInstance/users
API.
Service instance tokens expire 20 minutes after creation.
To obtain a service instance token and authorize your IBM Match 360 with Watson API calls, complete the following steps:
Granting users access to IBM Match 360
You can grant users access to IBM Match 360 in two ways:
- With the Cloud Pak for Data web interface.
- With the the
/zen-data/v2/serviceInstance/users
API.
Users must be assigned one of the following roles:
- Data Engineer - Data Engineer users have full rights to configure a IBM Match 360 service instance, onboard data sources, customize the data model, customize the matching algorithm, run matching, view or create jobs, complete pair analysis tasks, and view or edit entities and records in the master data explorer.
- Data Steward - Data Steward users can onboard data sources, run matching, view the data model, view ongoing jobs, complete pair analysis tasks, and view or edit entities and records in the master data explorer.
- Publisher User - The Publisher User role is used primarily to publish data from an IBM InfoSphere® Master Data Management instance, through the MDM Publisher tool, into IBM Match 360. Publisher Users can onboard data sources, customize the data model, and view or create jobs.
- Entity Viewer - Entity Viewer users have read-only permission in an IBM Match 360 instance. They can view the master data, the model, the results of matching, and ongoing jobs. They can also complete pair analysis tasks.
Granting access to users with the Cloud Pak for Data web interface
To grant access to users by using the Cloud Pak for Data web interface:
- Log into the Cloud Pak for Data web interface.
- Navigate to My Instances, then select the specified instance.
- Click the Manage access option.
- If the user is not listed on the manage access page:
- Select the Add users option.
- Select the specified users and select the role of Data Engineer, Data Steward, Publisher User, or Entity Viewer.
- Click Add to complete the role assignment.
- If the user is already listed on the manage access page:
- Hover over the specified user and select the Edit option.
- Select the role of Data Engineer, Data Steward, Publisher User, or Entity Viewer.
- Click Save to complete the role assignment.
Granting access to users with the Cloud Pak for Data API
To grant access to users by using the /zen-data/v2/serviceInstance/users
API, first run the following curl command to get all users present in Cloud Pak for Data:
curl -k -X GET https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/users -H 'authorization: Bearer <PLATFORM_TOKEN>'
Then use the /zen-data/v2/serviceInstance/users
API to assign the users roles while granting them access by running the following curl command:
curl -k -X POST \
https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/users/ \
-H 'Authorization: Bearer <PLATFORM_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"serviceInstanceID":"<PROVISIONED_INSTANCE_ID>",
"users":[
{
"display_name":"<DISPLAY_NAME>",
"role":"<MATCH360_ROLE>",
"uid":"<USER_ID>",
"username":"<USER_NAME>"
}
]
}'
Replace the following values in the above curl command:
<CPD_CLUSTER_HOST>:<PORT>
- your Cloud Pak for Data cluster host and port.<PLATFORM_TOKEN>
- the user platform token.<PROVISIONED_INSTANCE_ID>
- the instance ID of your provisioned instance.<DISPLAY_NAME>
,<USER_ID>
, and<USER_NAME>
- the user display name, user ID, and user name obtained from the/zen-data/v2/serviceInstance/users
API.<MATCH360_ROLE>
- the desired IBM Match 360 role:DataEngineer
,DataSteward
,PublisherUser
, orEntityViewer
.
curl -k -X POST https://ibm-nginx-svc-lite.apps.cpd-lb.ibm.com/zen-data/v2/serviceInstance/users/ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwic3ViIjoiYWRtaW4iLCJpc3MiOiJLTk9YU1NPIiwiYXVkIjoiRFNYIiwicm9sZSI6IkFkbWluIiwicGVybWlzc2lvbnMiOlsiYWRtaW5pc3RyYXRvciIsImNhbl9wcm92aXNpb24iXSwidWlkIjoiMTAwMDMzMDk5OSIsImF1dGhlbnRpY2F0b3IiOiJkZWZhdWx0IiwiZGlzcGxheV9uYW1lIjoiYWRtaW4iLCJpYXQiOjE1NzQzNjI2MDksImV4cCI6MTU3NDQwNTgwOX0.olm53bABcdVE6J9vi-VbRU13cr3B0MKRMVq6D4H-W7tXPZOLDvdsIKhCpW0aBi_iryE1sSgIdIb663RmW_nws2wxlpYWHtvigPwY5OVsr8dIA_wRlsCC96JnVa0GB0adM7U-qSfEruTTWZTLxL-gr4EucUXSZ84aii9ukMtN4VUDTvKsa9xJtnQY4W3owdezRzbG_6UkcvjtWzTLTUGIQisCBTkKZsoroGQuDkiiBTtJdNT8T_rZ6nqNQ6y-wsgZ6LMSCKJA_TC65jTJvu8903UoNzW2wnK7Z_Dt_oob9TYOOzNlkaa1YSQewmBhixV08wr8tmLOOzwtOxwCf5Ya-A' -H 'Content-Type: application/json' -d '{
"serviceInstanceID":"1582510653894",
"users":[
{
"display_name":"user1",
"role":"DataSteward",
"uid":"1000331001",
"username":"user1"
}
]
}'
In this example, the user user1
is granted DataSteward
access to the sample-0 (1582510653894) instance.
After access has been granted to users, service instance tokens will be accepted by IBM Match 360.
Retrieving the platform token with the Cloud Pak for Data API
To retrieve the platform token by using the /icp4d-api/v1/authorize
API, run the following curl command:
curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/authorize' -H 'Content-type: application/json' -d '{ "username": "<USER_NAME>", "password": "<PASSWORD" }'
Replace the following values in the curl command:
<CPD_CLUSTER_HOST>:<PORT>
- your Cloud Pak for Data cluster host and port.<USER_NAME>
- your Cloud Pak for Data user name.<PASSWORD>
- your Cloud Pak for Data password.
curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/authorize' -H 'Content-type: application/json' -d '{ "username": "<USER_NAME>", "password": "<PASSWORD" }'
Retrieving the service instance ID with the Cloud Pak for Data API
To retrieve the service instance ID with the /zen-data/v3/service_instances
API, run the following curl command:
curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v3/service_instances?add_on_type=mdm-app' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'
Replace the following values in the curl command:
<CPD_CLUSTER_HOST>:<PORT>
- your Cloud Pak for Data cluster host and port.<PLATFORM_TOKEN>
- the user platform token.
This command produces the following JSON response:
{
"limit":20,
"offset":0,
"service_instances":[
{
"addon_type":"mdm-app",
"addon_version":"1.0.0",
"created_at":"2020-05-10T22:15:55.557740Z",
"description":"string",
"display_name":"MDM1",
"id":"1583878225057"
...
}
],
"total_count":1
}
The service instance ID will be returned in the id
property of the response.
curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v3/service_instances?add_on_type=mdm-app' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'
The service instance ID will be returned in the id
property of the response.
Obtaining the service instance token
After you have your service instance ID, you can obtain a service instance token in one of two ways:
- With the Cloud Pak for Data web interface.
- With the Cloud Pak for Data API.
Service instance tokens expire 20 minutes after creation.
Retrieving the service instance token with the Cloud Pak for Data web interface
To retrieve the service instance token by using the Cloud Pak for Data web interface:
- Log into the Cloud Pak for Data web interface.
- Navigate to My Instances, then select the appropriate IBM Match 360 instance.
- Click View details.
The service instance token is displayed in the Access Information section.
Retrieving the service instance token with the Cloud Pak for Data API
To retrieve the service instance token by using the /zen-data/v2/serviceInstance/token
API, run the following curl command:
curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/token' -H 'Authorization: Bearer <PLATFORM_TOKEN> \
-d '{
"serviceInstanceID": "<PROVISIONED_INSTANCE_ID>",
"expiryTime:" <EXPIRY_TIME>
}'
Replace the following values in the curl command:
<CPD_CLUSTER_HOST>:<PORT>
- your Cloud Pak for Data cluster host and port.<PLATFORM_TOKEN>
- the user platform token.<PROVISIONED_INSTANCE_ID>
- the instance ID of your provisioned instance.<EXPIRY_TIME>
- the token expiry time in minutes.
The expiryTime
field is optional. If it is not provided, the default expiry time is 20 minutes.
This command produces the following the following JSON response:
{
"AccessToken":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b20iOnsiTW9kdWxlTmFtZSI6ImV6LWhlbG0tYXBwIiwiUm9sZSI6IkFkbWluIiwiU2VydmljZUluc3RhbmNlRGlzcGxheU5hbWUiOiJzYW1wbGUtMCIsIlNlcnZpY2VJbnN0YW5jZUlEIjoiMTU4MjUxMDY1Mzg5NCIsIlNlcnZpY2VJbnN0YW5jZVVzZXJOYW1lIjoiYWRtaW4iLCJaZW5EaXNwbGF5TmFtZSI6ImFkbWluIiwiWmVuVUlEIjoiMTAwMDMzMDk5OSIsIlplblVzZXJuYW1lIjoiYWRtaW4ifSwiZXhwIjoxNTgyNTE0NDQxLCJpYXQiOjE1ODI1MTMyNDEsImlzcyI6IklDUEQiLCJzdWIiOiJhZG1pbiIsInVpZCI6IjEwMDAzMzA5OTkifQ.FvtYQKkmIP5vguYGd7TVd-iD7Y4Z-KoTM1p-YlSCDzCzU7rnjogkOfF_0WCblUQQscliTzkV-YcjtfUxgXzObbKpu27oR1F85Z5PcBkMMhtVoxPw41Y9UeEpOy_2uYOr8aK8aJALHuG1W8VuOXoPI4oKh3cJM0M225xn0BK0_dTaVAioDVWiC8o0MDDn6uFDLEymM_U8JzZTFJbqzHUIlbmDphO4GbX28KduZvlrUVDzZ3hQPThUn-YnToLtYcKFWsdULWJHr4CCpPm5ZXGDAvjzTSonk8ktrMhHSgRV3loRhvtftXEZYfKQDGzhvAiKi7Ilv7OX85gJau_LgWv0iA",
"TokenPayload":{
"ModuleName":"mdm-app",
"Role":"DataSteward",
"ServiceInstanceDisplayName":"mdm-app-1",
"ServiceInstanceID":"1582510653894",
"ServiceInstanceUserName":"jsmith",
"ZenDisplayName":"john smith",
"ZenUID":"1000330999",
"ZenUsername":"jsmith"
}
}
The access token will be returned in the AccessToken
property of the JSON response.
Access tokens are only valid for a particular instance of IBM Match 360.
curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/token' -H 'Authorization: Bearer <PLATFORM_TOKEN> -d '{
"serviceInstanceID": "<PROVISIONED_INSTANCE_ID>",
"expiryTime:" <EXPIRY_TIME>
}'
Providing the service instance token to authorize the IBM Match 360 API
You can pass the service instance token to authorize your IBM Match 360 API calls in two ways:
- Using the Authorize feature of the API Explorer user interface.
- In the
Authorization
header of an API request.
Providing the service instance token with the Authorize feature of API Explorer
Navigate to the Swagger UI API Explorer by browsing to https://<CPD_CLUSTER_HOST>/<MDM_INSTANCE_ID>/api-model/explorer/#
Replace the <CPD_CLUSTER_HOST>
value in the above URL with your Cloud Pak for Data cluster host and replace <MDM_INSTANCE_ID>
with your service instance ID number.
In the API Explorer, complete the following steps:
- Click Authorize at the top of the page
- Enter the instance token obtained from the Obtaining a service instance token section of this page.
- Click Authorize and then click Close.
The API Explorer passes your service instance token automatically for every API invoked from the API Explorer page.
Providing the service instance token in an Authorization header of an API request
To provide the service instance token in an Authorization
header of an API request, run the following curl command:
curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/<API_PATH>' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'
Replace the following values in the curl command:
<CPD_CLUSTER_HOST>:<PORT>
- your Cloud Pak for Data cluster host and port.<API_PATH>
- the path of your desired API (Such as/mdm/model/v1/jobs
).<PLATFORM_TOKEN>
- the user platform token.
curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/<API_PATH>' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'
Methods
Get config data model
Gets the data model present in configuration space.
GET /mdm/v1/config_data_model
Response
Collection of locale, record types, relationship types, system properties definition in configuration space.
Collection of record data types.
The data type identifier of Records.
record_types
The collection of data relationship types.
Relationship Type definition.
relationship_types
Collection of data attribute types.
Response wrapper with details of attribute type.
attribute_types
Collection of system properties.
System Properties.
system_properties
The locale of the data model.
Status Code
Config data model is returned
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting config data model. An internal error occurred while attempting to get config data model.
{ "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" } ] } ] }
Replace Config Data Model
Replaces the config data model present in configuration space.
PUT /mdm/v1/config_data_model
Request
Collection of locale, record types, relationship types, system properties definition in configuration space.
Collection of record data types.
The data type identifier of Records.
record_types
The collection of data relationship types.
Relationship Type definition.
relationship_types
Collection of data attribute types.
Response wrapper with details of attribute type.
attribute_types
Collection of system properties.
System Properties.
system_properties
The locale of the data model.
Response
Collection of locale, record types, relationship types, system properties definition in configuration space.
Collection of record data types.
The data type identifier of Records.
record_types
The collection of data relationship types.
Relationship Type definition.
relationship_types
Collection of data attribute types.
Response wrapper with details of attribute type.
attribute_types
Collection of system properties.
System Properties.
system_properties
The locale of the data model.
Status Code
Config data model is replaced.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem replacing config data model. An internal error occurred while attempting to replace the config data model.
{ "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" } ] } ] }
Get matching statistics
Gets the matching statistics (such as number of entities, entity size distributions, and more.) for the specified record type.
GET /mdm/v1/match_statistics
Request
Query Parameters
Record type of match statistics
Example:
person
Entity type of match statistics
Example:
person_entity
Response
The Statistics of the match process results.
The breakdown statistics of entities generated by match process.
The standard deviation of the entity sizes.
The average of the entity sizes.
Example:
2
The variance of the entity sizes.
The maximum size of the entity.
Example:
4
The minimum size of the entity.
Example:
1
The count of the entities.
Example:
500
entity_breakdown
The size statistics of entities generated by the match process.
The size distribution statistics of entities generated by the match process.
The summary of statistics of the match process results.
The total number of entities generated by the match process.
Example:
950
The total number of data records processed by the match process.
Example:
2500
The count of entities having size of one.
Example:
300
The number of distinct sources of data records.
Example:
4
The number of data assets processed by the match process.
Example:
9
summary
The status of match process execution.
The match process execution completion date.
Example:
2021-03-16T13:04:34.000Z
Count of the comparisons made during match process.
Example:
120
Count of the comparison buckets created during match process.
Example:
9
The total time consumed to run match process.
Example:
159000
status
Status Code
Statistics retrieved
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error occurred in get resource process. Resource does not exist
Error in fetching statistics
{ "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 } }
Response
The pair offset of the pair analysis.
Example:
12
The record type of the pair analysis.
Example:
person
Tuned config of the pair analysis.
Example:
{'threshold'': 0.156,}
tuned_config
The base config of the pair analysis.
Example:
{'threshold'': 0.156,}
base_config
The id pair generation job.
Example:
b221364e-b98c-11ec-8422-0242ac120002
The id of tuning job .
Example:
b221364e-b98c-11ec-8422-0242ac120002
The entity type of the pair analysis.
Example:
person_entity
The status of the pair analysis.
Example:
Completed
Status Code
Pair analysis is fetched successfully.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
The pair analysis for the given record and entity type not found.
Error in getting Pair analysis.
No Sample Response
Add pair analysis results
Adds a new pair analysis in configuration space. This allows to store result of tuning job with thresholds
POST /mdm/v1/pair_analysis
Request
The pair offset of the pair analysis.
Example:
12
The record type of the pair analysis.
Example:
person
Tuned config of the pair analysis.
Example:
{'threshold'': 0.156,}
tuned_config
The base config of the pair analysis.
Example:
{'threshold'': 0.156,}
base_config
The id pair generation job.
Example:
b221364e-b98c-11ec-8422-0242ac120002
The id of tuning job .
Example:
b221364e-b98c-11ec-8422-0242ac120002
The entity type of the pair analysis.
Example:
person_entity
The status of the pair analysis.
Example:
Completed
Response
The pair offset of the pair analysis.
Example:
12
The record type of the pair analysis.
Example:
person
Tuned config of the pair analysis.
Example:
{'threshold'': 0.156,}
tuned_config
The base config of the pair analysis.
Example:
{'threshold'': 0.156,}
base_config
The id pair generation job.
Example:
b221364e-b98c-11ec-8422-0242ac120002
The id of tuning job .
Example:
b221364e-b98c-11ec-8422-0242ac120002
The entity type of the pair analysis.
Example:
person_entity
The status of the pair analysis.
Example:
Completed
Status Code
Pair Analysis created successfully.
Error in pair Analysis. The request you used is invalid. Please revalidate and try again.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Internal error occured in creating asset for the given Pair analysis data.
No Sample Response
Get pair analysis
Gets the pair analysis for given entity and record type.
GET /mdm/v1/pair_analysis/{record_type}/{entity_type}
Response
The pair offset of the pair analysis.
Example:
12
The record type of the pair analysis.
Example:
person
Tuned config of the pair analysis.
Example:
{'threshold'': 0.156,}
tuned_config
The base config of the pair analysis.
Example:
{'threshold'': 0.156,}
base_config
The id pair generation job.
Example:
b221364e-b98c-11ec-8422-0242ac120002
The id of tuning job .
Example:
b221364e-b98c-11ec-8422-0242ac120002
The entity type of the pair analysis.
Example:
person_entity
The status of the pair analysis.
Example:
Completed
Status Code
Pair analysis is fetched successfully.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
The pair analysis for the given record and entity type not found.
Error in getting Pair analysis.
No Sample Response
Patch pair analysis
Updates the pair analysis. Unknown attributes will be ignored
PATCH /mdm/v1/pair_analysis/{record_type}/{entity_type}
Request
Path Parameters
Record type of comparison pair
Entity type of comparison pair
The pair offset of the pair analysis.
Example:
12
The record type of the pair analysis.
Example:
person
Tuned config of the pair analysis.
Example:
{'threshold'': 0.156,}
tuned_config
The base config of the pair analysis.
Example:
{'threshold'': 0.156,}
base_config
The id pair generation job.
Example:
b221364e-b98c-11ec-8422-0242ac120002
The id of tuning job .
Example:
b221364e-b98c-11ec-8422-0242ac120002
The entity type of the pair analysis.
Example:
person_entity
The status of the pair analysis.
Example:
Completed
Response
The pair offset of the pair analysis.
Example:
12
The record type of the pair analysis.
Example:
person
Tuned config of the pair analysis.
Example:
{'threshold'': 0.156,}
tuned_config
The base config of the pair analysis.
Example:
{'threshold'': 0.156,}
base_config
The id pair generation job.
Example:
b221364e-b98c-11ec-8422-0242ac120002
The id of tuning job .
Example:
b221364e-b98c-11ec-8422-0242ac120002
The entity type of the pair analysis.
Example:
person_entity
The status of the pair analysis.
Example:
Completed
Status Code
Pair analysis was updated successfully.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
The pair analysis for the given record and entity type not found.
Error updating pair analysis.
No Sample Response
Delete comparison record pair decision
Delete the comparison record pair decision.
DELETE /mdm/v1/pair_decisions/{record_type}/{entity_type}/{record_number_1}/{record_number_2}
Get comparison record pair decision statistics
Gets the comparison record pair decision statistics.
GET /mdm/v1/pair_decisions/statistics
Response
Response wrapper with the statistics of comparison record pair decisions.
Details of statistics of comparison record pair decision.
The number of pairs which are marked as 'Maybe' by the user.
Example:
3
The total number of pairs which are reviewed by the user.
Example:
15
The false positive rate calculated considering the category and user decision on the comparison record pair.
Example:
0.6
The false negative rate calculated considering the category and user decision on the comparison record pair.
Example:
0.8
The number of true positive pairs.
Example:
1
The number of true negative pairs.
Example:
2
The number of false positive pairs.
Example:
3
The number of false negative pairs.
Example:
4
The number of pairs which are marked as 'Not-match' by the user.
Example:
6
The data type identifier of the comparison pair records.
Example:
person
The entity type identifier of the comparison pair records.
Example:
person_entity
The number of pairs which are marked as 'Matched' by the user.
Example:
6
pair_statistics
Status Code
Comparison record pair decision statistics are fetched successfullly.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error in getting configuration metadata.
No Sample Response
List comparison record pair decision
Lists the filtered comparison record pair decision.
GET /mdm/v1/pair_decisions
Request
Query Parameters
Record type of comparison pair
Entity type of comparison pair
Record identier of comparison pair
Record identier of comparison pair
Pair comparison offset
no of comparison pairs to be fetched
Response
Response wrapper with the list of comparison record pairs.
Collection of comparison pairs with details.
Status Code
Comparison record pair decision for given id is fetched successfullly.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error in getting configuration metadata.
No Sample Response
Add comparison record pair decision
Adds a new comparison record pair decision in configuration space. This allows to store user decision taken on comparison of record pairs
POST /mdm/v1/pair_decisions
Request
Request details for creating comparison record pair decision.
The identifier for the record 1 of the comparison pair.
The identifier for the record 1 of the comparison pair.
The user decision on comparison of the record pair.
The identifier for the comparison pair.
The data type identifier of the comparison pair records.
The data type identifier of the comparison pair records.
The entity type identifier of the comparison pair records.
Response
Pair and corresponding user decision details.
The last modified date of the pair decision.
Example:
2022-11-dd 13:32:12
The record number of the first record of the comparison record pair.
Example:
41001160
The record number of the second record of the comparison record pair.
Example:
41001
The decision taken by the user for the comparison record pair.
Example:
Match
The identified category of the comparison record pair.
Example:
matched
The data type identifier of the comparison pair records.
Example:
person
The id of the comparison record pair.
Example:
6096bfdf_40976432_8320
Status Code
Pair decision created successfully.
Error in pair decision. The request you used is invalid. Please revalidate and try again.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Internal error occured in creating asset for the given configuration metadata.
No Sample Response
List the process details
Lists the Configurator process details for all processes, optionally filtered by process status.
GET /mdm/v1/configuration_metadata/processes
Request
Query Parameters
Unique status param to get the processes based on it. i.e. Not-Initiated, In-progress, Complete and Error
Example:
In-progress
Response
Response wrapper with the list of Processes.
Collection of Processes with details.
Status Code
Processes retrieved.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error in getting processes.
{ "processes": [ { "record_type_label": "Person", "record_type": "person", "process_name": "match", "process_count": "0", "message": "Match completed successfully and statistics updated.", "status": "Complete" } ] }
Create process
Create the Configurator process to publish data, publish model, match and delete assets.
POST /mdm/v1/configuration_metadata/processes
Request
Process creation request details.
The name of the Process to be created.
Example:
match
The asset source details for the data asset to be published for publish_data process.
The asset source details for project data asset
API Key of the Cloud Object Storage account.
Bucket Name of data asset file in the Cloud Object Storage.
Endpoint URL of the Cloud Object Storage.
Identifier of source project or source catalog.
project
The asset source details for catalog data asset
API Key of the Cloud Object Storage account.
Bucket Name of data asset file in the Cloud Object Storage.
Endpoint URL of the Cloud Object Storage.
Identifier of source project or source catalog.
catalog
asset_source_details
Comma separated asset ids of assets to be processed by delete_assets and publish_data processes.
User identifier of the initiator of processes. This identifier will be available in the headers of the messaging queue events generated by the initiated process.
Flag to enable/disable derive operation for match process.
Flag to enable/disable force match operation.
Flag to enable/disable force derive operation.
The record type which needs to be processed for match and publish_data processes.
Example:
person
The entity type which needs to be processed for match process.
Example:
person_entity
Response
Process Status.
Optional summary of the processes.
summary
Status of the Process execution.
Additional details about the Process status.
Status Code
Process created successfully.
Error in process creation. The request you used is invalid. Please revalidate and try again.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error in getting processes.
{ "status": "In-Progress", "message": "Matching is in progress." }
{ "status": "In-progress", "message": "Publish model is initiated." }
{ "status": "In-progress", "message": "Import Snapshot is initiated." }
{ "status": "In-progress", "message": "Asset Deletion is initiated!", "summary": { "asset_id_1": "Delete-in-progress" } }
{ "message": "Bulk load of data is initiated.", "status": "In-progress" }
Get configuration metadata
Gets the configuration metadata with all assets, their mappings, loading status, matching status, and more.
GET /mdm/v1/configuration_metadata
Response
Configuration metadata details.
The catalog id from the linked WKC project.
Example:
ee1de5f6-54da-4246-95bc-7bc282151000
Last updated date of this Configuration metadata.
The date of Configuration metadata creation.
Pair analysis in configuration Metadata
The details of entities in Configuration metadata
any property
pair_analysis
The project id of the linked WKC project.
Example:
0e4bb17d-4871-40a5-b5a1-55b2866fe000
The description of the Configuration metadata.
The name of the Configuration metadata.
The identifier of this Configuration metadata.
Example:
0e4bb17d-4871-40a5-b5a1-0000000
Status Code
configuration metadata for given id is fetched successfullly.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error in getting configuration metadata.
{ "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" } ] }
Replace configuration metadata
Replaces the configuration metadata. It would replace the configuration data including asset information, matching attributes, and more.
PUT /mdm/v1/configuration_metadata
Request
Configuration metadata details.
The catalog id from the linked WKC project.
Example:
ee1de5f6-54da-4246-95bc-7bc282151000
Pair analysis in configuration Metadata
The details of entities in Configuration metadata
any property
pair_analysis
The project id of the linked WKC project.
Example:
0e4bb17d-4871-40a5-b5a1-55b2866fe000
The description of the Configuration metadata.
The name of the Configuration metadata.
Response
Configuration metadata details.
The catalog id from the linked WKC project.
Example:
ee1de5f6-54da-4246-95bc-7bc282151000
Last updated date of this Configuration metadata.
The date of Configuration metadata creation.
Pair analysis in configuration Metadata
The details of entities in Configuration metadata
any property
pair_analysis
The project id of the linked WKC project.
Example:
0e4bb17d-4871-40a5-b5a1-55b2866fe000
The description of the Configuration metadata.
The name of the Configuration metadata.
The identifier of this Configuration metadata.
Example:
0e4bb17d-4871-40a5-b5a1-0000000
Status Code
configuration metadata successfully replaced
Error in replacing configuration metadata. The request you used is invalid. Please revalidate and try again.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Internal error occured in replacing configuration metadata.
{ "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" } ] }
Update configuration metadata
Updates the configuration metadata with the information provided in the request.
PATCH /mdm/v1/configuration_metadata
Request
Configuration metadata details.
The catalog id from the linked WKC project.
Example:
ee1de5f6-54da-4246-95bc-7bc282151000
Pair analysis in configuration Metadata
The details of entities in Configuration metadata
any property
pair_analysis
The project id of the linked WKC project.
Example:
0e4bb17d-4871-40a5-b5a1-55b2866fe000
The description of the Configuration metadata.
The name of the Configuration metadata.
Response
Configuration metadata details.
The catalog id from the linked WKC project.
Example:
ee1de5f6-54da-4246-95bc-7bc282151000
Last updated date of this Configuration metadata.
The date of Configuration metadata creation.
Pair analysis in configuration Metadata
The details of entities in Configuration metadata
any property
pair_analysis
The project id of the linked WKC project.
Example:
0e4bb17d-4871-40a5-b5a1-55b2866fe000
The description of the Configuration metadata.
The name of the Configuration metadata.
The identifier of this Configuration metadata.
Example:
0e4bb17d-4871-40a5-b5a1-0000000
Status Code
configuration metadata successfully updated
Error in updating configuration metadata. The request you used is invalid. Please revalidate and try again.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Internal error occured in getting configuration metadata.
{ "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" } ] }
Get configurator process
Gets the process details for the specified process name.
GET /mdm/v1/configuration_metadata/processes/{process_name}
Request
Path Parameters
Unique process name to get the process status. i.e. publish_model, publish_data, match, delete_asset and import_snapshot
Query Parameters
Unique record type associated with the process
Example:
person
Unique entity type associated with the process
Example:
person_entity
Response
Details of the Process.
The displayable text for the record type.
The data type identifier of source records under processing.
Name of the Process.
Count of process of this process name under execution.
Status of the Process execution.
Additional details about the Process execution.
Status Code
Process retrieved.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem processing request. Please check if you have provided correct process name.
Error in getting process.
{ "record_type_label": "Person", "record_type": "person", "process_name": "match", "process_count": "0", "message": "Match completed successfully and statistics updated.", "status": "Complete" }
Replace configuration metadata asset
Replaces asset information in the configuration with the information provided in the request.
PUT /mdm/v1/configuration_metadata/assets/{asset_id}
Request
Path Parameters
Unique identifier of project asset
Request object for updating an asset.
The status of the Data Asset.
Example:
Mapped
Name of the data asset.
Example:
Person10k.csv
The date of data asset creation.
Details of Data Asset column mappings with the data model.
Response
Response wrapper with details of Data Asset Metadata.
Details of the Data Asset.
The identifier of the Data asset.
Example:
d8868c51-a96e-48ab-a4cd-0000000
The last updated date of the Data asset metadata.
Example:
'2020-06-25 11:36:18'
The status of the Data asset.
Example:
Mapped
The date of the Data asset creation.
Example:
'2020-06-25 11:36:18'
The details of Data asset column mappings to the data model.
The name of the Data asset.
Example:
person_data_records.csv
asset
Status Code
Asset replaced successfully.
Error in replacing asset. The request you used is invalid. Please revalidate and try again.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Internal error occured in replacing asset for the given configuration metadata.
{ "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" }
Add configuration metadata asset
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
Request
Request details for creating new Data Asset.
The identifier for the Data Asset.
Example:
d8868c51-a96e-48ab-a4cd-0000000
The status of the Data Asset.
Example:
Mapped
The name of the Data Asset.
Example:
Person10k.csv
The date of the Data Asset creation.
The collection of Data Asset column mappings with the data model.
Response
Response wrapper with details of Data Asset Metadata.
Details of the Data Asset.
The identifier of the Data asset.
Example:
d8868c51-a96e-48ab-a4cd-0000000
The last updated date of the Data asset metadata.
Example:
'2020-06-25 11:36:18'
The status of the Data asset.
Example:
Mapped
The date of the Data asset creation.
Example:
'2020-06-25 11:36:18'
The details of Data asset column mappings to the data model.
The name of the Data asset.
Example:
person_data_records.csv
asset
Status Code
Asset created successfully.
Error in created asset. The request you used is invalid. Please revalidate and try again.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Internal error occured in creating asset for the given configuration metadata.
{ "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" }
Response
Response wrapper with the details of the snapshot
data_model
Collection of various comparison resources used to customize comparison logic of a matching algorithm
compare_spec_resources
Collection of various map resources used in matching algorithm, like for handling equivalent values. Map resource key must be lower snake case (i.e. person_map_name_nickname)
map_resources
Collection of various set resources used in matching algorithm, like for handling anonymous values. Set resource key must be lower snake case (i.e. person_set_name_aname)
set_resources
composite_rules
snapshot_summary
Match Settings
match_settings
Collection of matching algorithms for different record types e.g. person, organization
algorithms
Status Code
Snapshot with given id is fetched successfully.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error in getting configuration metadata.
No Sample Response
Update a snapshot of model assets
- This service updates the name and description of a snapshot.
PUT /mdm/v1/snapshots/{id}
Request
Path Parameters
The unique identifier of a snapshot
Request wrapper object for snapshot summary of model assets
Additional detail about snapshot
Snapshot Name
Response
Request wrapper object for snapshot summary of model assets
Additional detail about snapshot
Snapshot Name
Status Code
The snapshot has been successfully updated.
The request cannot be processed due to user error.
The request cannot be processed due to authentication error.
The request cannot be processed due to insufficient permission error.
The request cannot be processed due to an unexpected system error.
No Sample Response
Response
Response wrapper with the details of the snapshot
data_model
Collection of various comparison resources used to customize comparison logic of a matching algorithm
compare_spec_resources
Collection of various map resources used in matching algorithm, like for handling equivalent values. Map resource key must be lower snake case (i.e. person_map_name_nickname)
map_resources
Collection of various set resources used in matching algorithm, like for handling anonymous values. Set resource key must be lower snake case (i.e. person_set_name_aname)
set_resources
composite_rules
snapshot_summary
Match Settings
match_settings
Collection of matching algorithms for different record types e.g. person, organization
algorithms
Status Code
Snapshot with given id is deleted successfully.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error in getting configuration metadata.
No Sample Response
Response
Response wrapper with the list of Snapshots.
list of snapshots
snapshots
Status Code
Snapshots are fetched successfully.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error in getting configuration metadata.
No Sample Response
Create a snapshot of config assets
- This service creates a snapshot of current config assets.
POST /mdm/v1/snapshots
Request
Contains the summary of a snapshot
Timestamp when the snapshot was created
Additional detail about snapshot
User who created the snapshot
Name of the snapshot
Snapshot identifier
Response
Contains the summary of a snapshot
Timestamp when the snapshot was created
Additional detail about snapshot
User who created the snapshot
Name of the snapshot
Snapshot identifier
Status Code
The snapshot of model assets has been successfully created.
The request cannot be processed due to user error.
The request cannot be processed due to authentication error.
The request cannot be processed due to insufficient permission error.
The request cannot be processed due to an unexpected system error.
No Sample Response
Request
Request wrapper with the details of the snapshot for comparison with current configuration
Data model of snapshot for comparison with current system's data model
data_model
Composite Rules of snapshot for comparison with current system's Composite Rules
composite_rules
Match Settings of snapshot for comparison with current system's match settings
match_settings
Algorithms from the snapshot for checking the compatibility with Model
algorithms
Response
Response wrapper with the details of the snapshot comparison with current configuration
data_model
Composite rules of configuration
composite_rules
Snapshot Summary of incoming snapshot
snapshot_summary
Match Settings of configuration
match_settings
Snapshot compatibility of data_model and algorithms
compatibility_result
Status Code
Snapshot comparison is generated and fetched successfully.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error in getting configuration metadata.
{ "data_model": { "attribute_types": { "address": { "matching_types": { "__current": [ "ADDRESS" ], "__incoming": [ "ADDRESS" ], "__change": "unchanged" }, "description": { "__current": "The address locations associated with a record.", "__incoming": "The address locations associated with a record type.", "__change": "modified" }, "label": { "__current": "Address", "__incoming": "Address", "__change": "unchanged" }, "classification": { "__current": "", "__incoming": "", "__change": "unchanged" }, "fields": { "country": { "indexed": { "__current": true, "__incoming": true, "__change": "unchanged" }, "description": { "__current": "The country of this address.", "__incoming": "The country of this address.", "__change": "unchanged" }, "label": { "__current": "Country value", "__incoming": "Country value", "__change": "unchanged" }, "classification": { "__current": "", "__incoming": "", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 4, "__change": "unchanged" }, "address_line1": { "indexed": { "__current": true, "__incoming": true, "__change": "unchanged" }, "description": { "__current": "The first line of this address.", "__incoming": "The first line of this address.", "__change": "unchanged" }, "label": { "__current": "Address line 1", "__incoming": "Address line 1", "__change": "unchanged" }, "classification": { "__current": "", "__incoming": "", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 4, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 2, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 1, "__unchanged": 4, "__change": "modified" }, "string": { "description": { "__current": "A single field primitive attribute", "__incoming": "A single field primitive attribute", "__change": "unchanged" }, "label": { "__current": "Simple attribute", "__incoming": "Simple attribute", "__change": "unchanged" }, "classification": { "__current": "", "__incoming": "", "__change": "unchanged" }, "fields": { "value": { "indexed": { "__current": true, "__incoming": true, "__change": "unchanged" }, "description": { "__current": "", "__incoming": "", "__change": "unchanged" }, "label": { "__current": "Value", "__incoming": "Value", "__change": "unchanged" }, "classification": { "__current": "", "__incoming": "", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 4, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 4, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 1, "__unchanged": 1, "__change": "modified" }, "system_properties": { "attribute_types": { "attribute_last_updated": { "settable": { "__current": true, "__incoming": true, "__change": "unchanged" }, "indexed": { "__current": false, "__incoming": false, "__change": "unchanged" }, "editable": { "__current": false, "__incoming": false, "__change": "unchanged" }, "data_type": { "__current": "Long", "__incoming": "Long", "__change": "unchanged" }, "description": { "__current": "The time an attribute was last updated", "__incoming": "The time an attribute was last updated", "__change": "unchanged" }, "label": { "__current": "Attribute last updated date", "__incoming": "Attribute last updated date", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 6, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "entity_types": { "entity_id": { "indexed": { "__current": true, "__incoming": true, "__change": "unchanged" }, "editable": { "__current": false, "__incoming": false, "__change": "unchanged" }, "data_type": { "__current": "String", "__incoming": "String", "__change": "unchanged" }, "description": { "__current": "", "__incoming": "", "__change": "unchanged" }, "label": { "__current": "Entity identifier", "__incoming": "Entity identifier", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 5, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "relationship_types": { "from_record_id": { "settable": { "__current": true, "__incoming": true, "__change": "unchanged" }, "editable": { "__current": false, "__incoming": false, "__change": "unchanged" }, "data_type": { "__current": "String", "__incoming": "String", "__change": "unchanged" }, "description": { "__current": "The record id this relationship is coming from", "__incoming": "The record id this relationship is coming from", "__change": "unchanged" }, "label": { "__current": "From record id", "__incoming": "From record id", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 5, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "version": { "__current": "v3", "__incoming": "v3", "__change": "unchanged" }, "record_types": { "collection_id": { "settable": { "__current": true, "__incoming": true, "__change": "unchanged" }, "indexed": { "__current": true, "__incoming": true, "__change": "unchanged" }, "editable": { "__current": false, "__incoming": false, "__change": "unchanged" }, "data_type": { "__current": "String", "__incoming": "String", "__change": "unchanged" }, "description": { "__current": "Optional identifier for identifying a collection of records", "__incoming": "Optional identifier for identifying a collection of records", "__change": "unchanged" }, "label": { "__current": "Collection ID", "__incoming": "Collection ID", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 6, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 5, "__change": "unchanged" }, "relationship_types": { "linkage": { "internal": { "__current": true, "__incoming": true, "__change": "unchanged" }, "label_from_source": { "__current": "Linked into", "__incoming": "Linked into", "__change": "unchanged" }, "label_from_target": { "__current": "Linked from", "__incoming": "Linked from", "__change": "unchanged" }, "directional": { "__current": true, "__incoming": true, "__change": "unchanged" }, "description": { "__current": "This is the built in linkage relationship type", "__incoming": "This is the built in linkage relationship type", "__change": "unchanged" }, "label": { "__current": "Linkage", "__incoming": "Linkage", "__change": "unchanged" }, "cardinality": { "__current": "ONE2MANY", "__incoming": "ONE2MANY", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 7, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "locale": { "__current": "en_us", "__incoming": "en_us", "__change": "unchanged" }, "record_types": { "person": { "entity_types": { "person_entity": { "default": { "__current": true, "__incoming": true, "__change": "unchanged" }, "description": { "__current": "The entity type for person records.", "__incoming": "The entity type for person records.", "__change": "unchanged" }, "label": { "__current": "Person entity", "__incoming": "Person entity", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 3, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "description": { "__current": "The record type for person records.", "__incoming": "The record type for person records.", "__change": "unchanged" }, "attributes": { "primary_residence": { "indexed": { "__current": true, "__incoming": true, "__change": "unchanged" }, "description": { "__current": "Indicates that this address is a primary residence.", "__incoming": "Indicates that this address is a primary residence.", "__change": "unchanged" }, "attribute_type": { "__current": "address", "__incoming": "address", "__change": "unchanged" }, "label": { "__current": "Primary residence", "__incoming": "Primary residence", "__change": "unchanged" }, "classification": { "__current": "", "__incoming": "", "__change": "unchanged" }, "cardinality": { "__current": "LIST", "__incoming": "LIST", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 6, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "label": { "__current": "Person", "__incoming": "Person", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 4, "__change": "unchanged" }, "organization": { "entity_types": { "organization_entity": { "default": { "__current": true, "__incoming": true, "__change": "unchanged" }, "description": { "__current": "The entity type for org records.", "__incoming": "The entity type for org records.", "__change": "unchanged" }, "label": { "__current": "Organization entity", "__incoming": "Organization entity", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 3, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "description": { "__current": "The record type for organization records.", "__incoming": "The record type for organization records.", "__change": "unchanged" }, "attributes": { "mailing_address": { "indexed": { "__current": true, "__incoming": true, "__change": "unchanged" }, "description": { "__current": "Indicates that this address is a mailing address.", "__incoming": "Indicates that this address is a mailing address.", "__change": "unchanged" }, "attribute_type": { "__current": "address", "__incoming": "address", "__change": "unchanged" }, "label": { "__current": "Mailing address", "__incoming": "Mailing address", "__change": "unchanged" }, "classification": { "__current": "", "__incoming": "", "__change": "unchanged" }, "cardinality": { "__current": "LIST", "__incoming": "LIST", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 6, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "label": { "__current": "Organization", "__incoming": "Organization", "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 4, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 2, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 1, "__unchanged": 4, "__change": "modified" }, "match_settings": { "person": { "person_entity": { "matching_thresholds": { "clerical_review_threshold": { "__current": 8, "__incoming": 8, "__change": "unchanged" }, "auto_link_threshold": { "__current": 8, "__incoming": 8, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 2, "__change": "unchanged" }, "matching_attributes": { "__current": [ { "name": "mailing_address", "data_type": "address" } ], "__incoming": [ { "name": "mailing_address", "data_type": "address" } ], "__change": "unchanged" }, "matching_fields": { "address": { "__current": [ "address_line1", "country" ], "__incoming": [ "address_line1", "country" ], "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 3, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 0, "__unchanged": 1, "__change": "unchanged" }, "__added": 0, "__removed": 0, "__modified": 1, "__unchanged": 1, "__change": "modified" }
Suggest data mappings
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
Request
Query Parameters
Record type for data mapping suggestions
Example:
person
Suggested Data Mapping Request details.
The collection of data mapping columns having key and WKC identified class.
Response
Response wrapper with details of Suggested Data Mappings.
Collection of Suggested Data Mappings for Data Asset column.
Status Code
Suggested mappings are fetched
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Unexpected error occured while getting data mappings.
{ "suggested_data_mappings": [ { "data_mapping_default_display_name": "Gender", "data_mapping_name": "gender", "classified_class": "GEN", "key": "COLUMN 1" } ] }
Get suggested matching attributes
Gets suggested matching attributes for the record type based on mappings of assets of the specified record type.
GET /mdm/v1/suggested_matching_attributes
Response
Response wrapper for attributes suggested for running match process.
Collection of attributes suggested for running match process.
Status Code
Suggested matching attributes are retrieved
Project assets are missing or in invalid state.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Error occured while getting suggested matching attributes.
{ "suggested_matching_attributes": [ { "matching_attribute_default_display_name": "Gender", "matching_attribute_name": "gender" } ] }
Initiate weight tuning job
- 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
Request
Query Parameters
Record type of match statistics
Example:
person
Entity type of match statistics
Example:
person_entity
Response
Response object for asynchronous processing of a tuning job
System generated timestamp when a job was created
System defined name of a given job e.g. weight-tuning
System generated timestamp when a job was last updated
System generated identifier of a job
Status of a job. One Of: Queued, Running, Completed, Failed, Canceled
Status Code
The weight tuning job has been successfully created.
The request cannot be processed due to user error.
The request cannot be processed due to authentication error.
The request cannot be processed due to insufficient permission error.
The request cannot be processed due to an unexpected system error.
{ "created_at": "", "image": "mdm-tuning-job", "job_name": "weight-tuning", "last_updated_at": "", "id": "2ba3ed28-00c7-42e4-9cc9-8c74bf5e4ff0", "input": {}, "status": "Running" }
Start an operation to bulk delete data from the graph
A delete can target either records or relationships in the graph. If not specified, records are targeted by default. There are four options for a delete:
- Delete by search, which removes all elements matching a search criteria. This delete type is only supported for records.
- Delete by source, which removes all elements of a specified source.
- Delete by asset, which removes all elements loaded from a particular asset or list of assets.
- Full delete, which removes all elements from the graph.
POST /mdm/v1/bulk_delete
Request
Valid object defining the bulk delete job information.
The type of delete to run.
Allowable values: [
asset
,full
,search
,source
]The data type to target for deletion.
Allowable values: [
record
,relationship
]Asset IDs for data to be deleted. Required on delete by asset.
Record source for data to be deleted. Required on delete by source targeting records.
Relationship source for data to be deleted. Required on delete by source targeting relationships.
A set of criteria for a search operation.
Response
Information about a bulk delete job.
The id for the job.
The type of job.
Possible values: [
delete
,export
,bulk_load
,reindex
]The current status of the job.
Possible values: [
not_started
,prep
,queued
,running
,succeeded
,failed
,canceled
,unknown
]The type of delete.
Possible values: [
asset
,full
,search
,source
]The timestamp of when the job started.
The timestamp of when the job completed.
The list of identifiers for the job runs or processes.
Asset IDs for delete by asset.
Record source for delete by source.
The data type to target for deletion.
Possible values: [
record
,relationship
]Relationship source for delete by source.
A set of criteria for a search operation.
Status Code
The bulk delete job was successfully started.
Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem performing bulk delete. An internal error occurred while attempting to perform the operation.
{ "job_id": "24403560707830722", "job_type": "delete", "process_ids": [ "b3ba096d-c625-4d2f-ad12-285966f61cb0" ], "start_time": "1603483531000", "status": "running", "delete_type": "source", "record_source": "MDM" }
Start a bulk load of data into the graph
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.
POST /mdm/v1/bulk_load
Request
Valid object defining the data source and parameters for the bulk load job.
Information about the source of the data to be loaded.
Information about how the source data is structured on the storage system.
The strategy for updating existing data during the bulk load job.
Allowable values: [
append
,replace
]
Response
Information about a bulk load job.
The id for the job.
The type of job.
Possible values: [
delete
,export
,bulk_load
,reindex
]The current status of the job.
Possible values: [
not_started
,prep
,queued
,running
,succeeded
,failed
,canceled
,unknown
]The current stage of the bulk load job.
Possible values: [
vertices
,edges
,not_started
,unknown
]The timestamp of when the job started.
The timestamp of when the job completed.
The list of identifiers for the job runs or processes.
The strategy for updating existing data during the bulk load job.
Possible values: [
append
,replace
]
Status Code
The bulk load job was successfully started.
Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem performing bulk load. An internal error occurred while attempting to perform the operation.
Problem performing bulk load. A bulk load process is already running.
{ "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" }
List the records associated with entity records
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
Request
Path Parameters
The unique identifier of the entity.
Query Parameters
The type of records to return in results.
The type of relationship between related records and entity member records.
The maximum number of records to return in each page of results. The maximum limit is 50.
Possible values: value ≤ 50
Default:
10
The number of records to skip before returning a page of results.
Default:
0
Record attributes from the data model to include in the results.
Possible values: contains only unique items
Examples:ViewRecord attributes from the data model to exclude from the results.
Possible values: contains only unique items
Examples:View
Response
Paged information about a set of other records related to an entity or a record.
The number of elements to skip before returning a page of results.
The maximum number of elements to return in each page of results.
The total number of elements.
A link to the first page of results.
The url for the page of results.
first
The paged list of related records.
A link to the last page of results.
The url for the page of results.
last
A link to the previous page of results.
The url for the page of results.
previous
A link to the next page of results.
The url for the page of results.
next
Status Code
The related records for the entity have been successfully retrieved.
Problem getting related records for entity. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting related records for entity. Entity with id does not exist.
Problem getting related records for entity. An internal error occurred while attempting to retrieve the records.
{ "first": { "href": "${host}/mdm/v1/entities/person_entity-53496/related_records?crn=${crn}&relationship_type=party_relationship&record_type=person&offset=0&limit=10" }, "last": { "href": "${host}/mdm/v1/entities/person_entity-53496/related_records?crn=${crn}&relationship_type=party_relationship&record_type=person&offset=0&limit=10" }, "limit": 10, "offset": 0, "total_count": 1, "related_records": [ { "attributes": { "record_id": "535354896573139473", "record_last_updated": "1603572360787", "record_source": "MDM", "usage_type": { "attribute_last_updated": "1548936483189", "value": "3" }, "usage_value": { "attribute_last_updated": "1548936483189", "value": "Retail Banking" } }, "id": "192616", "type": "record", "record_number": 192616, "type_name": "preference" } ] }
List the relationships for an entity
View a list of relationships that exist between the given entity and other nodes on the graph. This endpoint does not include internal relationships in the resulting list of relationships.
GET /mdm/v1/entities/{id}/relationships
Request
Path Parameters
The ID of the entity.
Query Parameters
The relationship types to return.
Whether to include entity record relationships to other nodes.
Default:
false
The number of relationships to skip over.
Default:
0
The number of relationships to be returned. The maximum limit is 50.
Possible values: value ≤ 50
Default:
10
Attributes from the data model to include in the results for the source vertex.
Possible values: contains only unique items
Examples:ViewAttributes from the data model to include in the results for the target vertex.
Possible values: contains only unique items
Examples:View
Response
Paged information about a collection of relationships.
The number of elements to skip before returning a page of results.
The maximum number of elements to return in each page of results.
The total number of elements.
A link to the first page of results.
The url for the page of results.
first
The collection of relationships.
A link to the last page of results.
The url for the page of results.
last
A link to the previous page of results.
The url for the page of results.
previous
A link to the next page of results.
The url for the page of results.
next
Status Code
The relationships have been successfully retrieved.
Problem getting relationships for entity. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting relationships for entity. Entity not found.
Problem getting relationships for entity. An internal error occurred while attempting to retrieve the relationships.
{ "first": { "href": "${host}/mdm/v1/entities/456/relationships?crn=${crn}&offset=0&limit=10" }, "last": { "href": "${host}/mdm/v1/entities/456/relationships?crn=${crn}&offset=0&limit=10" }, "limit": 10, "offset": 0, "relationships": [ { "attributes": { "relationship_id": "997554896611881692", "relationship_last_updated": "1548937318815", "relationship_source": "MDM", "from_record_id": "358354896586841797", "from_record_source": "MDM", "from_record_type": "preference", "to_record_id": "998254896587316451", "to_record_source": "MDM", "to_record_type": "organization" }, "id": "215tzl-5cw8-q7f9-oi7u8", "source": { "id": "4344", "type": "record", "type_name": "person" }, "target": { "id": "456", "type": "entity", "type_name": "person_entity" }, "type": "relationship", "type_name": "preference_association" } ] }
List the records linked into an entity
View a list of member records that form the entity.
GET /mdm/v1/entities/{id}/records
Request
Path Parameters
The unique identifier of the entity.
Query Parameters
The maximum number of records to return in each page of results. The maximum limit is 50.
Possible values: value ≤ 50
Default:
10
The number of records to skip before returning a page of results.
Default:
0
Record attributes from the data model to include in the results.
Possible values: contains only unique items
Examples:ViewRecord attributes from the data model to exclude from the results.
Possible values: contains only unique items
Examples:View
Response
Paged information about a collection of records.
The number of elements to skip before returning a page of results.
The maximum number of elements to return in each page of results.
A link to the first page of results.
The url for the page of results.
first
The paged collection of records.
The total number of elements.
A link to the last page of results.
The url for the page of results.
last
A link to the previous page of results.
The url for the page of results.
previous
A link to the next page of results.
The url for the page of results.
next
Status Code
The entity records have been successfully retrieved.
Problem getting records for entity. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting records for entity: Entity with id <entity_id> does not exist.
Problem getting records for entity. An internal error occurred while attempting to retrieve the records.
{ "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" } ] }
Get the composite view of an entity
View attributes for an entity in a consolidated view based on defined composite view rules from the Model APIs.
GET /mdm/v1/entities/{id}
Request
Path Parameters
The unique identifier of the entity.
Query Parameters
Record attributes from the data model to include in the results.
Possible values: contains only unique items
Examples:ViewRecord attributes from the data model to exclude from the results.
Possible values: contains only unique items
Examples:View
Response
Information and metadata about the composite view of an entity.
Information about an entity.
Supplemental information about a resource.
Status Code
The composite view has been successfully retrieved.
Problem getting composite view of entity. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting composite view of entity. Entity with id <entity_id> does not exist.
Problem getting composite view of entity. An internal error occurred while attempting to retrieve the composite view.
{ "entity": { "attributes": { "birth_date": { "attribute_last_updated": "1548936483016", "value": "1934-05-11T00:00:00.000Z" }, "entity_last_updated": "1603572360787", "gender": { "attribute_last_updated": "1548936483016", "value": "F" }, "legal_name": { "attribute_last_updated": "1548936483016", "last_name": "LEES", "given_name": "KAROLYN" }, "primary_residence": { "attribute_last_updated": "1548936483189", "address_province_state_value": "KY", "address_city": "ELLIOTTVILLE", "address_zip_postal_code": "40317", "address_line_1": "106 EAST SYCAMORE ST.", "address_record_id": "215054896528318812", "address_line_2": "Unit-701" }, "record_id": "216754896528315937", "record_source": "MDM" }, "id": "person_entity-53496", "type": "entity", "record_count": 1, "type_name": "person_entity" }, "metadata": { "href": "${host}/mdm/v1/entities/person_entity-53496?crn=${crn}", "id": "person_entity-53496", "updated_at": "2020-10-24T20:46:00.787Z" } }
Get information for an export
View detailed information about the specified export job. The process ids can be used to track the job status through the Job APIs.
GET /mdm/v1/data_exports/{export_id}
Response
Information about an export.
The id for the job.
The type of job.
Possible values: [
delete
,export
,bulk_load
,reindex
]The current status of the job.
Possible values: [
not_started
,prep
,queued
,running
,succeeded
,failed
,canceled
,unknown
]The type of data being exported.
Possible values: [
record
,entity
]The name of the export file.
Whether the export file is expired.
A set of criteria for a search operation.
The timestamp of when the job started.
The timestamp of when the job completed.
The list of identifiers for the job runs or processes.
Status Code
The export information was retrieved successfully.
Problem getting export information. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting export information. The export does not exist.
Problem getting export information. An internal error occurred while attempting to retrieve the export information.
{ "end_time": "1603483621000", "job_id": "24403560707830722", "job_type": "export", "process_ids": [ "b3ba096d-c625-4d2f-ad12-285966f61cb0" ], "start_time": "1603483531000", "status": "succeeded", "file_expired": false, "file_name": "records", "search_criteria": { "filters": [], "query": { "expressions": [ { "condition": "equal", "expressions": [], "value": "JOHN" } ], "operation": "and" }, "search_type": "record" } }
Download an export file
Download the resulting file from a completed export job if the file exists. The export files may expire after some time.
GET /mdm/v1/data_exports/{export_id}/download
Response
Status Code
The export file has been successfully retrieved.
Problem downloading export file. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem downloading export file. The export does not exist.
Problem downloading export file. The export file no longer exists.
Problem downloading export file. An internal error occurred while attempting to retrieve the export file.
Problem downloading export file. The export job is not in a successful state.
No Sample Response
List the export jobs
View a summary list of export jobs that have been requested.
GET /mdm/v1/data_exports
Request
Query Parameters
The number of exports to skip before returning a page of results.
Default:
0
The maximum number of exports to return in each page of results. The maximum limit is 50.
Possible values: value ≤ 50
Default:
10
Whether to include exports with expired files.
Default:
true
Response
Paged information about a collection of exports.
The number of elements to skip before returning a page of results.
The maximum number of elements to return in each page of results.
The total number of elements.
A link to the first page of results.
The url for the page of results.
first
The paged collection of exports.
A link to the last page of results.
The url for the page of results.
last
A link to the previous page of results.
The url for the page of results.
previous
A link to the next page of results.
The url for the page of results.
next
Status Code
The list of exports was retrieved successfully.
Problem getting list of exports. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting list of exports. An internal error occurred while attempting to retrieve the list of exports.
{ "first": { "href": "${host}/mdm/v1/data_exports?crn=${crn}&record_type=person&local=true&offset=0&limit=10" }, "last": { "href": "${host}/mdm/v1/data_exports?crn=${crn}&record_type=person&local=true&offset=0&limit=10" }, "limit": 10, "offset": 0, "exports": [ { "end_time": "1603483621000", "job_id": "24403560707830722", "job_type": "export", "process_ids": [ "b3ba096d-c625-4d2f-ad12-285966f61cb0" ], "start_time": "1603483531000", "status": "succeeded", "file_expired": false, "file_name": "records", "search_criteria": { "filters": [], "query": { "expressions": [ { "condition": "equal", "expressions": [], "value": "JOHN" } ], "operation": "and" }, "search_type": "record" } } ], "total_count": 1 }
Start an export of search results
Run a data export job to export the results of a search. Export format, search criteria, and file name are configurable in the message body. The file name must only contain alphanumeric characters, and be 64 characters or less.
The operation runs as follows:
- A compression type must be provided when a partition type of 'executor_count' is specified.
POST /mdm/v1/data_exports
Request
Query Parameters
The type of file compression used when exporting the output file. Required when a partition type of 'executor_count' is specified.
Allowable values: [
tar
,tgz
,zip
]The type of partitioning used when exporting the results.
Allowable values: [
none
,executor_count
]Default:
none
The maximum number of results to be returned. The maximum limit is 10000.
Possible values: value ≤ 10000
Valid object defining the export format and search criteria for the export job.
The type of data to export.
Allowable values: [
record
,entity
]The format of the export file.
Allowable values: [
csv
,psv
,tsv
]A set of criteria for a search operation.
The file name of the export file.
Response
Information about an export.
The id for the job.
The type of job.
Possible values: [
delete
,export
,bulk_load
,reindex
]The current status of the job.
Possible values: [
not_started
,prep
,queued
,running
,succeeded
,failed
,canceled
,unknown
]The type of data being exported.
Possible values: [
record
,entity
]The name of the export file.
Whether the export file is expired.
A set of criteria for a search operation.
The timestamp of when the job started.
The timestamp of when the job completed.
The list of identifiers for the job runs or processes.
Status Code
The export job was started successfully.
Problem starting export job. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem starting export job. An internal error occurred.
{ "job_id": "24403560707830722", "job_type": "export", "process_ids": [ "b3ba096d-c625-4d2f-ad12-285966f61cb0" ], "start_time": "1603483531000", "status": "running", "file_expired": false, "file_name": "records", "search_criteria": { "filters": [], "query": { "expressions": [ { "condition": "equal", "expressions": [], "value": "JOHN" } ], "operation": "and" }, "search_type": "record" } }
Stop a given job
Attempt to stop a running job. This operation does not rollback changes made by the job process prior to stopping the job. Full deletion of job resources may take up to a few minutes.
POST /mdm/v1/data_jobs/{job_id}/stop
Response
Information about a job.
The id for the job.
The type of job.
Possible values: [
delete
,export
,bulk_load
,reindex
]The current status of the job.
Possible values: [
not_started
,prep
,queued
,running
,succeeded
,failed
,canceled
,unknown
]The timestamp of when the job started.
The timestamp of when the job completed.
The list of identifiers for the job runs or processes.
Status Code
The job was stopped successfully.
Problem stopping job process. The process with job id <job_id> is not running.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem stopping job process. A process with job id <job_id> could not be found.
Problem stopping job process. Jobs of this type are not supported.
Problem stopping job process. An internal error occurred while attempting to perform the operation.
{ "end_time": "1620660046000", "job_id": "8785798185259674", "job_type": "bulk_load", "process_ids": [ "7155aff7-7d42-487b-85a7-8474b5efff2f", "8647d779-b13e-4f77-bda7-3ab2ca85c881" ], "start_time": "1620660025000", "status": "canceled", "load_stage": "vertices" }
List the jobs
View a list of jobs that have been run. Filter on job type or job status to get a more precise list of jobs.
GET /mdm/v1/data_jobs
Request
Query Parameters
The number of jobs to skip before returning a page of results.
Default:
0
The maximum number of jobs to return in each page of results. The maximum limit is 50.
Possible values: value ≤ 50
Default:
10
Filter by job status.
Allowable values: [
not_started
,prep
,queued
,running
,succeeded
,failed
,canceled
,unknown
]Filter by job type.
Allowable values: [
bulk_load
,delete
,export
,reindex
]
Response
Paged information about a collection of jobs.
The number of elements to skip before returning a page of results.
The maximum number of elements to return in each page of results.
The total number of elements.
A link to the first page of results.
The url for the page of results.
first
The paged collection of jobs.
A link to the last page of results.
The url for the page of results.
last
A link to the previous page of results.
The url for the page of results.
previous
A link to the next page of results.
The url for the page of results.
next
Status Code
The list of jobs was retrieved successfully.
Problem getting list of jobs. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting list of jobs. An internal error occurred while attempting to retrieve the list of jobs.
{ "first": { "href": "${host}/mdm/v1/data_jobs?crn=${CRN}&offset=0&limit=10" }, "last": { "href": "${host}/mdm/v1/data_jobs?crn=${CRN}&offset=0&limit=10" }, "limit": 10, "offset": 0, "jobs": [ { "end_time": "1620155648000", "job_id": "4839655889405511", "job_type": "bulk_load", "process_ids": [ "e7df6747-6668-4b5b-a642-70b05eadf20f", "658fde68-384c-427e-90a0-bdfd8aa02b6d" ], "start_time": "1620155442000", "status": "succeeded", "load_stage": "edges" } ], "total_count": 1 }
Response
Information about a job.
The id for the job.
The type of job.
Possible values: [
delete
,export
,bulk_load
,reindex
]The current status of the job.
Possible values: [
not_started
,prep
,queued
,running
,succeeded
,failed
,canceled
,unknown
]The timestamp of when the job started.
The timestamp of when the job completed.
The list of identifiers for the job runs or processes.
Status Code
The job status was retrieved successfully.
Problem getting job information. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting job information. Job not found.
Problem getting job information. An internal error occurred while attempting to retrieve the job information.
{ "end_time": "1620155648000", "job_id": "4839655889405511", "job_type": "bulk_load", "process_ids": [ "e7df6747-6668-4b5b-a642-70b05eadf20f", "658fde68-384c-427e-90a0-bdfd8aa02b6d" ], "start_time": "1620155442000", "status": "succeeded", "load_stage": "edges" }
Clean up job data
Delete any uploaded artifacts from the system after the job completes.
POST /mdm/v1/data_jobs/{job_id}/clean_up
Response
Status Code
The job clean up was successful.
Problem cleaing up job. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem cleaning up job. Job not found.
Problem cleaning up job. Jobs of this type are not supported.
Problem cleaning up job. The job data could not be found.
Problem cleaning up job. An internal error occurred while cleaning up the job.
Problem cleaning up job. Operation cannot be performed while job is still running.
No Sample Response
Request
Path Parameters
The ID of the record.
Query Parameters
Record attributes from the data model to include in the results.
Possible values: contains only unique items
Examples:ViewRecord attributes from the data model to exclude from the results.
Possible values: contains only unique items
Examples:View
Response
Information about a record.
Information about a record.
Supplemental information about a resource.
Status Code
The record has been successfully retrieved.
Problem getting record. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting record: Record does not exist.
Problem getting record. An internal error occurred while attempting to retrieve the record.
{ "metadata": { "href": "${host}/mdm/v1/records/40964176?crn=${crn}", "id": "40964176", "updated_at": "2020-10-23T19:49:51.442Z" }, "record": { "attributes": { "legal_name": { "attribute_last_updated": "1548936483189", "last_name": "Smith", "given_name": "Jane" }, "record_id": "12345", "record_last_updated": "1603482591442", "record_source": "MDM" }, "system_attributes": { "created_date": "1547836463189", "last_updated_user": "user", "created_user": "user", "last_updated_date": "1548936493189" }, "id": "40964176", "type": "record", "record_number": 40964176, "type_name": "person" } }
Replace attributes for a record
Replace the existing record with the new set of attributes. Any existing editable record attributes not specified in the request will be removed from the record.
PUT /mdm/v1/records/{id}
Request
Path Parameters
The ID of the record.
Valid object defining the record information to replace the existing record.
The name of the record type as defined in the data model.
The id of the element.
The list of the attributes of the element.
attributes
The list of the system attributes of the element.
system_attributes
Response
Information about a record.
Information about a record.
Supplemental information about a resource.
Status Code
The record has been successfully updated.
Problem updating record. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem updating record. Record does not exist.
Problem updating record. Record has a future timestamp.
Problem updating record. An internal error occurred while attempting to update the record.
{ "metadata": { "href": "${host}/mdm/v1/records/40964176?crn=${crn}", "id": "40964176", "updated_at": "2020-10-23T19:49:51.442Z" }, "record": { "attributes": { "legal_name": { "attribute_last_updated": "1548936483189", "last_name": "Smith", "given_name": "Jane" }, "record_id": "12345", "record_last_updated": "1603482591442", "record_source": "MDM" }, "system_attributes": { "created_date": "1547836463189", "last_updated_user": "user", "created_user": "user", "last_updated_date": "1548936493189" }, "id": "40964176", "type": "record", "record_number": 40964176, "type_name": "person" } }
Delete a record
Delete an existing record from the graph. Deleting a record automatically triggers a removal of the record from any formed entities.
DELETE /mdm/v1/records/{id}
Response
Status Code
The record was successfully deleted.
Problem deleting record. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem deleting record. Record does not exist.
Problem deleting record. An internal error occurred while attempting to delete the record.
No Sample Response
Request
Query Parameters
The number of records to skip over.
Default:
0
The number of records to be returned. The maximum limit is 50.
Possible values: value ≤ 50
Default:
10
Response
Paged information about a collection of records.
The number of elements to skip before returning a page of results.
The maximum number of elements to return in each page of results.
A link to the first page of results.
The url for the page of results.
first
The paged collection of records.
The total number of elements.
A link to the last page of results.
The url for the page of results.
last
A link to the previous page of results.
The url for the page of results.
previous
A link to the next page of results.
The url for the page of results.
next
Status Code
The records have been successfully retrieved.
Problem getting records. Input validation failed.
Problem processing request. The user is not authenticated.
Problem processing request. The user is not authorized to perform the request.
Problem getting records. An internal error occurred while attempting to retrieve the records.
{ "first": { "href": "${host}/mdm/v1/records?crn=${crn}&offset=0&limit=10" }, "last": { "href": "${host}/mdm/v1/records?crn=${crn}&offset=0&limit=10" }, "limit": 10, "offset": 0, "records": [ { "attributes": { "record_id": "1000007", "record_last_updated": "1603209081559", "record_source": "MDM", "regulation": { "regulation_value": "Safety Regulations", "attribute_last_updated": "1549006675422", "description": "The Safety Regulations provided by Company ABC", "regulation_type": "1", "url": "https://www.ibm.com" } }, "system_attributes": { "created_date": "1547836463189", "last_updated_user": "user", "created_user": "user", "last_updated_date": "1548936493189" }, "id": "151592", "type": "record", "record_number": 151592, "type_name": "process_purpose" } ] }