If you can't find the product or version you're looking for, visit support.ataccama.com/downloads

REST API

The REST API provides the ability to browse data, statuses, and parameters maintained by MDM via REST interfaces. The API supports REST Maturity Level 2.

By default, the REST API uses the default server port (8051) set in MDM Server Application Properties.

The path to REST API is /api/rest and it cannot be configured. The REST API only uses basic HTTP authentication. However, you can configure a more secure authentication method, see MDM Server Application Properties, API Endpoint Required Role Configuration section.

The following sections describe the uses of the REST API.

OpenAPI Swagger

The Swagger UI allows you to see a list of available REST API endpoints and operations in a browser-based HTML interface.

Request

http://localhost:8051/swagger-ui.html

A list of available REST API endpoints and operations in Swagger

Specification is available at `http://localhost:8051/v3/api-docs`.

The Swagger is using the springdoc-openapi library (see Springdoc openAPI library) that can be configured using spring properties (see Springdoc openAPI properties).

Listing REST Endpoints

A response contains a directory of exposed services and interfaces and additional information, including the RW mode.

Request

http://localhost:8051/api/rest/

Response

{
  "name" : "REST API",
  "version" : "1.0",
  "rwmode" : "RW",
  "uris" : {
    "tasks" : "http://localhost:8051/api/rest/tasks",
    "eventHandlers" : "http://localhost:8051/api/rest/event-handlers",
    "instance" : "http://localhost:8051/api/rest/instance",
    "master" : "http://localhost:8051/api/rest/master",
    "parameters" : "http://localhost:8051/api/rest/parameters",
    "sourceSystems" : "http://localhost:8051/api/rest/source-systems",
    "statistics" : {
      "instance" : "http://localhost:8051/api/rest/statistics/instance",
      "master" : "http://localhost:8051/api/rest/statistics/master"
    },
    "interfaces" : {
      "services" : "http://localhost:8051/api/rest/interfaces/services",
      "exports" : "http://localhost:8051/api/rest/interfaces/batch/exports",
      "loads" : "http://localhost:8051/api/rest/interfaces/batch/loads",
      "consumers" : "http://localhost:8051/api/rest/interfaces/streaming/consumers"
    }
  }
}

Response status codes

The MDM REST API uses standard HTTP status codes for error and status reporting.

These codes are categorized as follows:

Category	Description
2xx	Success
3xx	Redirection: this usually indicates configuration error related to authentication, for example, OAuth flow used.
4xx	Indicates a client error, an invalid request.
5xx	Indicates a server error.

Common error codes

The following is a more detailed list of error codes that the REST API can return.

Error code	Description
400 Bad Request	The request is invalid. For example, there are required parameters missing, an error in JSON formatting, or some other error, as explained in the response.
401 Unauthorized	The client needs to authenticate to access the resource.
403 Forbidden	The client does not have permission to access the resource or perform the action in the request.
404 Not Found	An incorrect URL. This is usually an incorrect name of the entity, master view, or column.
500	A server error, for example, a configuration problem or failure during a write operation.

Error code

Description

400 Bad Request

The request is invalid. For example, there are required parameters missing, an error in JSON formatting, or some other error, as explained in the response.

401 Unauthorized

The client needs to authenticate to access the resource.

403 Forbidden

The client does not have permission to access the resource or perform the action in the request.

404 Not Found

An incorrect URL. This is usually an incorrect name of the entity, master view, or column.

500

A server error, for example, a configuration problem or failure during a write operation.

Reading Records

A GET request is used to access instance and master layer information, entity information, records or a single record.

Instance Layer

Endpoint Description

Endpoint	Description
/instance	Returns a list of entities on the instance layer.
/instance/{entity}	Returns all the records of the selected instance entity.
/instance/{entity}/metadata	Returns the metadata of the selected instance entity: columns, relationships, and ways to access a particular record.
/instance/{entity}/{id}	Returns an instance record by its `id`.
/instance/{entity}/{origin}/{sourceId}	Returns an instance record by its `origin` and `sourceId`.

/instance

Returns a list of entities on the instance layer.

/instance/{entity}

Returns all the records of the selected instance entity.

/instance/{entity}/metadata

Returns the metadata of the selected instance entity: columns, relationships, and ways to access a particular record.

/instance/{entity}/{id}

Returns an instance record by its id.

/instance/{entity}/{origin}/{sourceId}

Returns an instance record by its origin and sourceId.

Master Views

Endpoint Description

Endpoint	Description
/master	Returns a list of master views.
/master/{view}	Returns a list of entities on the selected master view.
/master/{view}/{entity}	Returns all the records of the selected master view.
/master/{view}/{entity}/metadata	Returns the metadata of the selected master entity: columns and ways to access a particular record.
/master/{view}/{entity}/{id}	Returns a master record by its `id`.
/master/{view}/{entity}/{origin}/{sourceID}	Returns a master record by the `origin` and `sourceId` of an instance record.

/master

Returns a list of master views.

/master/{view}

Returns a list of entities on the selected master view.

/master/{view}/{entity}

Returns all the records of the selected master view.

/master/{view}/{entity}/metadata

Returns the metadata of the selected master entity: columns and ways to access a particular record.

/master/{view}/{entity}/{id}

Returns a master record by its id.

/master/{view}/{entity}/{origin}/{sourceID}

Returns a master record by the origin and sourceId of an instance record.

If {origin} contains a # and is used in the URI, it must be escaped with %23.

Parameters

Results and their presentation can be customized with the following parameters:

Parameter Description

Parameter	Description
columns	Comma-separated list of columns that should be returned (by default all columns are returned).
offset	Used for paging. Offsets the first returned record, starts at 0.
page	Used for paging. Alternative to offset - returns nth page, that is, offset=page*count, starts at 0.
count	When used alone or with `offset`, limits the number of records returned. When used with `page`, defines the page size.
sort	Name of column to sort records by, optionally suffixed with `:ASC` or `:DESC` (default ordering is ASC)
<column_name>=<value>	Filters by the exact value of the column with wildcard support; multiple values of one column are supported: separate them by a comma.
preload=<relationship1>,<relationship2>	Lists related records according to the provided relationships.

columns

Comma-separated list of columns that should be returned (by default all columns are returned).

offset

Used for paging. Offsets the first returned record, starts at 0.

page

Used for paging. Alternative to offset - returns nth page, that is, offset=page*count, starts at 0.

count

When used alone or with offset, limits the number of records returned. When used with page, defines the page size.

sort

Name of column to sort records by, optionally suffixed with :ASC or :DESC (default ordering is ASC)

<column_name>=<value>

Filters by the exact value of the column with wildcard support; multiple values of one column are supported: separate them by a comma.

preload=<relationship1>,<relationship2>

Lists related records according to the provided relationships.

Requests with parameters

GET /instance/{entity}?offset=2&count=5
GET /instance/{entity}?columns=src_first_name,src_sin&src_first_name=Joh*&sort=std_birth_date:DESC

GET /master/{view}/{entity}?offset=2&count=5
GET /master/{view}/{entity}?columns=cmo_first_name,cmo_sin&cmo_first_name=Joh*&sort=cmo_birthdate:DESC
GET /instance/{entity}?preload=contacts,addresses
// advanced preload examples
GET /master/masters/party/1020?preload=addresses.instances,contacts
GET /master/masters/party/1020?preload=addresses(cmo_type=Residential,cmo_state=US)

Sample GET Requests and Responses

Request on the Instance Layer

GET /instance/party/1007

Response

{
    "type": "party",
    "metadata":
    {
        "id": 1007,
        "origin": "crm#customer#party",
        "sourceSystem": "crm",
        "active": true,
        "sourceTimestamp": "2015-07-23T14:14:04Z",
        "creationDate": "2017-09-08T15:39:59Z",
        "lastUpdateDate": "2017-09-08T15:40:03Z",
        "lastSourceUpdateDate": "2017-09-08T15:40:03Z",
        "activationDate": "2017-09-08T15:39:59Z",
        "creationTid": 1002,
        "lastUpdateTid": 2814,
        "lastSourceUpdateTid": 2814,
        "activationTid": 1002
    },
    "attributes":
    {
        "source_id": "1001",
        "master_id": 1238,
        "propose_id": 1273,
        "src_first_name": "DR. JOHN",
        ...
    },
    ...
}

Request on a Master View

GET /master/masters/party/1235

Response

{
    "type": "party",
    "metadata": {
        "id": 1235,
        "active": true,
        "creationDate": "2017-09-08T15:39:59Z",
        "lastUpdateDate": "2017-09-08T15:39:59Z",
        "activationDate": "2017-09-08T15:39:59Z",
        "creationTid": 1002,
        "lastUpdateTid": 1002,
        "activationTid": 1002
    },
    "attributes": {
        "cmo_type": "P",
        "cmo_first_name": "John",
       ...
    }
}

Identify

The 'Identify' service answers the question, "is this record similar to any record stored in the hub?". Input is in the form of the instance entity, while similarity is defined by the matching rules of this entity. Output is either matching information and master record or nothing.

The service accepts POST requests at endpoint /master/{view}/{entity}/identify with the following structure:

Identify request

POST /master/masters/party/identify
{
    "sourceSystem" : "life",
    "record" : {
        "attributes" : {
            "src_first_name" : "Anto",
            "src_last_name" : "Lese",
            "src_sin" : "387958572"
        },
        "relationships" : [{
            "contacts" : [{
                "attributes": {
                    "src_type" : "PHONE",
                    "src_value" : "416-206-1234"
                }
            },
            {
                "attributes": {
                    "src_type" : "EMAIL",
                    "src_value" : "alese@aol.com"
                }
            }]
        }]
    }
}

As an input, the service gets:

one record of the instance entity - attributes of origin SOURCE
(optional) records of related entities - attributes of origin SOURCE

The service cleanses input data and tries to match the record to records in the hub using matching rules. If the input record is matched to a master group, a master record is returned. For example, the response if the record is matched is:

Identify Response

{
    "matchMetadata" : {
        "matchRelatedId" : 1007,
        "matchQuality" : 0.0,
        "matchRuleName" : "name+sin"
    },
    "record" : {
        "type" : "party",
        "metadata" : {
            "id" : 1030
            // more metadata
        },
        "attributes" : {
            "cmo_name" : "John",
            // more attributes
        }
    }
}

If matching has proposals enabled, proposals are returned as well. It is possible to have only proposals in response (record matches only using proposal rules).

Identify Response

{
    "matchMetadata" : { /* ... */ },
    "record" : { /* ... */ },
    "proposals" : [ {
        "matchMetadata" : {
            "matchRelatedId" : 1007,
            "matchQuality" : 0.0,
            "matchRuleName" : "name+sin"
        },
        "record" : {
            "type" : "party",
            "metadata" : {
                "id" : 1030
                // more metadata
            },
            "attributes" : {
                "cmo_name" : "John",
                // more attributes
            }
        }
    },
    // more proposals

    ]
}

If there are too many proposals (more than the runtime parameter nme.services.range.maxCount, default 100), proposals are returned in a short format:

Identify Response

{
    "matchMetadata" : { /* filled */ },
    "record" : { /* */ },
    "proposals" : [ {
        "masterId" : 1012,
        "matchRelatedId" : 1007,
        "matchQuality" : 0.0,
        "matchRuleName" : "name+sin"
    }
    // more proposals
    ]
}

Search

This services allows you to search for records by attributes and values using a POST request. For example, the following request searches for records with src_name values John or Paul and a std_Age value 42:

Search request

POST /instance/party/search
{
"src_name" : ["John","Paul"],
"std_age" : 42
}

The request supports the following parameters:

Parameter Description

Parameter	Description
offset	Used for paging. Offsets the first returned record, starts at 0.
count	When used alone or with `offset`, limits the number of records returned.

offset

Used for paging. Offsets the first returned record, starts at 0.

count

When used alone or with offset, limits the number of records returned.

Reading Historical Records

It is possible to get historical values of a record with a GET request.

Endpoint Description

Endpoint	Description
/history	Returns the list of all historized entities.
/instance/{entity}/history/metadata	Returns the list of columns stored in the historized instance entity as configured in `nme-history.xml`. See History Plugin for more information.
/instance/{entity}/{id}/history	Returns historical instance records by the record id. /instance/{entity}/{origin}/{source_id}/history
Returns historical instance records by origin and the record id.	/master/{view}/{entity}/{id}/history
Returns historical master records by the record id.	/master/{view}/{entity}/history/metadata

/history

Returns the list of all historized entities.

/instance/{entity}/history/metadata

Returns the list of columns stored in the historized instance entity as configured in nme-history.xml. See History Plugin for more information.

/instance/{entity}/{id}/history

Returns historical instance records by the record id.

/instance/{entity}/{origin}/{source_id}/history

Returns historical instance records by origin and the record id.

/master/{view}/{entity}/{id}/history

Returns historical master records by the record id.

/master/{view}/{entity}/history/metadata

Setting the Timeframe

It is possible to limit the number of results by specifying the from, to, or at parameters in the request. The from and to parameters can be combined or used separately.

History Request

/master/masters/party/1734/history?from=2017-08-16T11:15:55Z&to=2017-08-25T11:15:55Z

History Response

[ {
  "type" : "partymasters",
  "metadata" : {
    "id" : 1734,
    "validFrom" : "2017-08-21T14:47:02Z",
    "validTo" : "2017-08-24T14:48:11Z",
    "active" : true
  },
  "attributes" : {
    "cmo_type" : "P",
    "cmo_first_name" : "John",
    "cmo_last_name" : "Smith",
    "cmo_gender" : "M",
    "cmo_birth_date" : "1978-11-16T00:00:00Z",
    "cmo_sin" : "95242433",
    "dq_indicator" : 100000,
    "dq_indicator_name" : "medium",
    "group_size" : 2,
    "published_by" : "admin"
  }
}, {
  "type" : "partymasters",
  "metadata" : {
    "id" : 1734,
    "validFrom" : "2017-08-16T14:37:15Z",
    "validTo" : "2017-08-21T14:47:02Z",
    "active" : true
  },
  "attributes" : {
    "cmo_type" : "P",
    "cmo_first_name" : "J",
    "cmo_last_name" : "Smith",
    "cmo_birth_date" : "1978-11-16T00:00:00Z",
    "cmo_sin" : "95242433",
    "dq_indicator" : 111003,
    "dq_indicator_name" : "medium",
    "group_size" : 1,
    "published_by" : "multiload"
  }
} ]

Modifying Records

Mapping of HTTP methods to change type is as usual in REST:

Insert via POST
Update via PUT
Deactivation via DELETE

However MDM can automatically adjust between create and update depending on whether the record is present in the MDM repository, that is, an attempt to update (PUT) a non-existing record is automatically changed to an insert operation (POST), and vice versa.

Record Identification in Requests

Records are identified by their id or a combination of origin and source_id (for instance records only). This identification can be sent in the URI or in the request body.

Record ID Sent in the Request URI

PUT /instance/{entity}/{id}
POST /instance/{entity}/{origin}/{sourceId}
PUT/POST /api/rest/master/{entity}/{id}

If {origin} contains a # and is used in the URI, it must be escaped with %23.

Record ID Sent in the Request Body

POST /instance/{entity}
{
    "origin" : "crm#customer#party",
    "source_id" : "cdr48"
}

All combinations of POST/PUT/DELETE and identification are supported to provide maximum integration flexibility. The only forbidden variant is sending id when creating a new record (MDM generates its own ids).

POST Request Example

Instance Layer

Insert via a POST Request

POST /instance/party
{
    "origin" : "crm#customer#party",
    "source_id" : "cdr48",
    "source_timestamp" : "2015-07-23T14:14:04Z",
    "attributes" : {
        "src_first_name" : "Johny",
        "src_sin" : "547-954-624"
    }
}

Response

{
    "result": "ok",
    "records": {
        "entity": {
            "id": 4051,
            "origin": "crm#customer#party",
            "source_id": "cdr48-ase",
            "action": "INSERT"
        }
    }
}

Insert with relationships via a POST Request

{
    "origin" : "PAS#policyrole#party",
    "source_id" : "6776",
    "source_timestamp" : "2019-03-27T00:00:00Z",
    "attributes" : {
        "src_name_first" : "LINDA",
        "src_name_last" : "CORRIE",
        "src_name_middle" : "",
        "src_gender" : "Female",
        "src_date_of_birth" : ""
    },
    "relationships": {
        "contact": [{
            "source_id":"670",
            "origin":"PAS#policyrole#contact",
            "attributes": {
                "party_source_id" : "671",
                "src_value": "5354856",
                "src_type" : "Home Phone"
            }
        }
        ]
    }
}

When inserting a record with relationships via a POST request, you will need to modify Parent Role / Child Role in the MDM Logical Model according to what is defined in your request. Alternatively, if you have no Parent or Child Role defined in the model, use rev_party_has_contact in place of contact in the request.

Master Layer

Insert via a POST request

POST http://localhost:8051/api/rest/master/masters/party
{
   "attributes": {
      "cmo_first_name": "rest3",
      "cmo_sin": "12345"
   },
   "relationships": {
       "addresses":  [{
           "attributes":{
               "cmo_street": "ab1",
               "cmo_city": "cd1"
           }
       },
       {
           "attributes":{
               "cmo_street": "ab2",
               "cmo_city": "cd2"
           }
       }]
   }
}

Response

{
   "result": "ok",
   "records": {
       "id": 302003,
       "recordChange": "INSERT",
       "relationships": {
           "addresses": [
               {
                   "id": 302004,
                   "recordChange": "INSERT"
               },
               {
                   "id": 302005,
                   "recordChange": "INSERT"
               }
           ]
       }
   }
}

PUT Request Example

Instance Layer

Update via a PUT Request

PUT /instance/party/crm%23customer%23party/1001
{
    "source_timestamp" : "2015-07-23T14:14:04Z",
    "attributes": {
        "src_first_name": "Dr. John",
        "src_sin": "764-785-685"
    },
    "relationships": {
        "id_documents": [{
            "source_id":"pass-94515",
            "origin":"crm#customer#id_document",
            "attributes": {
                "src_type" : "passport",
                "src_value" : "489465498",
                "party_source_id" : "1001"
            }
        }]
    }
}

The central entity was updated, related entities were ignored since the data in the request was the same as before.

Response

{
    "result": "ok",
    "records": {
        "entity": {
            "action": "UPDATED",
            "id": 17603215,
            "origin": "crm#customer#party",
            "source_id": "12121212"
        },
        "relationships": {
            "id_documents": {
                "entity": {
                    "action": "NONE",
                    "id": 2207,
                    "origin": "crm#customer#id_document",
                    "source_id": "100_id_card_1"
                }
            }
        }
    }
}

Master Layer

Update via a PUT Request

PUT \http://localhost:8051/api/rest/master/masters/party/302003
{

   "attributes": {
      "cmo_first_name": "rest81",
      "cmo_sin": "12"
   }
}

Response

{
   "result": "ok",
   "records": {
       "id": 302003,
       "recordChange": "UPDATE"
   }
}

DELETE Request Example

Instance Layer

Record Deactivation via a DELETE Request

DELETE http://localhost:8051/api/rest/instance/party/17603215
<empty-body>

Response

{
    "result": "ok",
    "records": {
        "entity": {
            "id": 20003264,
            "origin": "crm#customer#id_document",
            "source_id": "100_id_card_1666"
            "action": "DEACTIVATED",
        }
    }
}

Master Layer

It is only possible to delete authored master records via the API. The DELETE request for these records causes an actual delete rather than a record deactivation (logical delete). For more information see Batch Interface, section Deletion Strategy.

Record Deletion via a DELETE Request

DELETE http://localhost:8051/api/rest/master/masters/party/302003
<empty-body>

Response

{
   "result": "ok",
   "records": {
       "id": 302003,
       "recordChange": "DELETE"
   }
}

Override Interfaces

Instance Records

Requests on the instance layer use the following parameters for record identification.

Parameter Description

Parameter	Description
`{entity}`	Instance table name as defined in the model.
`{id}`	ID of the record.

{entity}

Instance table name as defined in the model.

{id}

ID of the record.

You can use attributeName either in the URI or in the request body to specify one or more attributes involved in the request.

Listing Record Overrides

Use the following request to get the original value of the attribute before an override has been set. The request body is empty.

Request

GET /instance/{entity}/{id}/override/{attributeName}

Response

{
  "recordType": "instance",
  "entityType": "party",
  "recordId": 1982,
  "overrides": [
    {
      "attributeName": "src_first_name",
      "value": "John"
    }
  ]
}

Use the following request to get the list of all attributes with overrides and their values before the override has been set. The request body is empty.

Request

GET /instance/{entity}/{id}/override

Response

{
  "recordType": "instance",
  "entityType": "party",
  "recordId": 1982,
  "overrides": [
    {
      "attributeName": "src_first_name",
      "value": "John"
    },
    {
      "attributeName": "src_last_name",
      "value": "Smith"
    }
  ]
}

Setting Overrides

Use the following request to set an override on a particular attribute. Specify value in the request body. The response is empty.

Request

PUT /instance/{entity}/{id}/override/{attributeName}
{"value": "John"}

Use the following request to set overrides on several attributes. Specify both the attributeName and value in the request body. The response is empty.

Request

PUT /instance/{entity}/{id}/override
{
  "overrides": [
    {
      "attributeName": "src_first_name",
      "value": "John"
    },
    {
      "attributeName": "src_last_name",
      "value": "Smith"
    }
  ]
}

Deleting Overrides

Use the following request to delete an override on a particular attribute. Both the request and response body are empty.

Request

DELETE /instance/{entity}/{id}/override/{attributeName}

Use the following request to delete all overrides currently set on a record. Both the request and response body are empty.

Request

DELETE /instance/{entity}/{id}/override

Master Records

Requests on the master layer use the following parameters for record identification.

Parameter Description

Parameter	Description
`{view}`	Name of the master layer/view
`{entity}`	Instance table name as defined in the model.
`{id}`	ID of the record.

{view}

Name of the master layer/view

{entity}

Instance table name as defined in the model.

{id}

ID of the record.

You can use attributeName either in the URI or in the request body to specify one or more attributes involved in the request.

Listing Record Overrides

Use the following request to get the original value of the attribute before an override has been set. The request body is empty.

Request

GET /master/{viewName}/{entity}/{id}/override/{attributeName}

Response

{
  "recordType": "master",
  "entityType": "party",
  "recordId": 1982,
  "overrides": [
    {
      "attributeName": "cmo_first_name",
      "value": "John"
    }
  ],
  "viewName": "masters",
}

Use the following request to get the list of all attributes with overrides and their values before the override has been set. The request body is empty.

Request

GET /master/{viewName}/{entity}/{id}/override

Response

{
  "recordType": "master",
  "entityType": "party",
  "recordId": 1982,
  "overrides": [
    {
      "attributeName": "cmo_first_name",
      "value": "John"
    },
    {
      "attributeName": "cmo_last_name",
      "value": "Smith"
    }
  ],
  "viewName": "masters",
}

Setting Overrides

Use the following request to set overrides on one or several attributes. Specify both the attributeName and value in the request body. The response is empty.

Request

PUT /master/{viewName}/{entity}/{id}/override
{
  "overrides": [
    {
      "attributeName": "cmo_first_name",
      "value": "John"
    },
    {
      "attributeName": "cmo_last_name",
      "value": "Smith"
    }
  ]
}

Deleting Overrides

Use the following request to delete an override on a particular attribute. Both the request and response body are empty.

Request

DELETE /master/{viewName}/{entity}/{id}/override/{attributeName}

Use the following request to delete all overrides currently set on a record. Both the request and response body are empty.

Request

DELETE /master/{viewName}/{entity}/{id}/override

Task Management

Single Task Operations

Assign Task

Use the following request to assign a task to a group of team members or one team member:

Request

POST /api/rest/v2/tasks/{id}/assign

The request supports the following parameters:

Parameter	Required	Description
id	Yes	Task identifier.
user	No	Name of a new user assignee.
group	No	Name of a new group assignee.

Parameter

Required

Description

Yes

Task identifier.

user

Name of a new user assignee.

group

Name of a new group assignee.

Response

{
  "id": 17,
  "status": "NEW",
  "name": "Resolve DQ issues",
  "userAssignee": "jane.smith",
  "groupAssignee": "MDM_viewer",
  "workflowName": "consolidation",
  "workflowStep": "draft",
  "entityId": "contact.master.masters",
  "created": "2022-12-09T17:56:23.359Z",
  "createdBy": "jane.smith",
  "lastEdited": "2023-08-03T06:32:51.538Z",
  "lastEditedBy": "admin",
  "type": "RECORD_CHANGE",
  "severity": "LOW",
  "automationDefinitionId": null,
  "description": "Click on record edit to fix DQ issues.",
  "records": [
    {
      "id": 76628,
      "entityId": "contact.master.masters"
    },
    {
      "id": 76684,
      "entityId": "contact.master.masters"
    }
  ]
}

Get Task Detail

Use the following request to get task detail information (without comments and history):

Request

GET /api/rest/v2/tasks/{id}

The request uses the following parameter:

Parameter	Required	Description
id	Yes	Task identifier.

Parameter

Required

Description

Yes

Task identifier.

Response

{
  "id": 19,
  "status": "IN_PROGRESS",
  "name": "Missing PIDs",
  "userAssignee": "rachel.adams",
  "groupAssignee": "MDM_user",
  "workflowName": "consolidation",
  "workflowStep": "draft",
  "entityId": "party.master.masters",
  "created": "2022-12-09T17:58:33.517Z",
  "createdBy": "jane.smith",
  "lastEdited": "2023-08-02T19:28:46.761Z",
  "lastEditedBy": "admin",
  "type": "RECORD_CHANGE",
  "severity": "LOW",
  "automationDefinitionId": null,
  "description": "Click on record edit to start fixing DQ issues. You can also perform any other actions: add missing related data, activate or deactivate record, or split an instance from the master record.",
  "records": [
    {
      "id": 76083,
      "entityId": "party.master.masters"
    },
    {
      "id": 76080,
      "entityId": "party.master.masters"
    },
    {
      "id": 76078,
      "entityId": "party.master.masters"
    }
  ]
}

Get Task History

Use the following request to get history for a specific task:

Request

GET /api/rest/v2/tasks/{id}/history

The request uses the following parameter:

Parameter	Required	Description
id	Yes	Task identifier.

Parameter

Required

Description

Yes

Task identifier.

Response

{
  "history": [
    {
      "userName": "jane.smith",
      "timeStep": "2022-12-09T16:55:45.897Z",
      "action": "CREATE",
      "step": null,
      "reassign": null,
      "comment": null,
      "migrationResult": null,
      "automatedTaskConfigId": null
    },
    {
      "userName": "john.taylor",
      "timeStep": "2022-12-09T17:08:29.717Z",
      "action": "CREATE_DRAFT",
      "step": null,
      "reassign": null,
      "comment": "ID: 8",
      "migrationResult": null,
      "automatedTaskConfigId": null
    }
  ]
}

Get Task Comments

Use the following request to get comments for a specific task:

Request

GET /api/rest/v2/tasks/{id}/comments

The request uses the following parameter:

Parameter	Required	Description
id	Yes	Task identifier.

Parameter

Required

Description

Yes

Task identifier.

Response

{
  "comments": [
    {
      "userName": "jane.smith",
      "timeStep": "2022-12-09T16:52:06.904Z",
      "comment": "I think we need to get back to the product team to see how we can improve their data before they reach us"
    }
  ]
}

Add Task Comment

Use the following request to add comments for a specific task:

Request

POST /api/rest/v2/tasks/{id}/comments

The request uses the following parameter:

Parameter	Required	Description
id	Yes	Task identifier.

Parameter

Required

Description

Yes

Task identifier.

Sample request

POST /api/rest/v2/tasks/{id}/comments

Could you take a look at it, John?

Response

{
  "comments": [
    {
      "userName": "jane.smith",
      "timeStep": "2023-08-03T06:15:48.127Z",
      "comment": "Could you take a look at it, John?"
    }
  ]
}

Delete Task

Use the following request to delete a specific task. The response is empty.

Request

DELETE /api/rest/v2/tasks/{id}

The request uses the following parameter:

Parameter	Required	Description
id	Yes	Task identifier.

Parameter

Required

Description

Yes

Task identifier.

Bulk Task Operations

Create Multiple Tasks

Use the following request to create multiple tasks:

Request

POST /api/rest/v2/tasks

Sample request

POST /api/rest/v2/tasks
[
  {
    "type": "RECORD_CHANGE",
    "name": "Missing PIDs",
    "description": "Click on record edit to start fixing DQ issues.",
    "records": [
      {
        "id": 56787,
        "entityId": "party.master.masters"
      }
    ],
    "workflowName": "consolidation",
    "workflowStep": "draft",
    "userAssignee": "admin",
    "groupAssignee": "MDM_user",
    "severity": "LOW"
  }
]

Response

{
  "createdTaskIds": [
    36
  ]
}

Update Multiple Tasks

Use the following request to update multiple tasks:

Request

PATCH /api/rest/v2/tasks

Sample request

PATCH /api/rest/v2/tasks
[
  {
    "taskId": 16,
    "userAssignee": "jane.smith",
    "groupAssignee": "MDM_viewer",
    "severity": "LOW"
  },
  {
    "taskId": 15,
    "name": "Matching issue (address)"
  }
]

Response

{
  "tasks": [
    {
      "id": 16,
      "status": "IN_PROGRESS",
      "name": "Matching issue",
      "userAssignee": "jane.smith",
      "groupAssignee": "MDM_viewer",
      "workflowName": "consolidation",
      "workflowStep": "draft",
      "entityId": "party_proposal_k.match_proposal",
      "created": "2022-12-09T17:55:45.897Z",
      "createdBy": "jane.smith",
      "lastEdited": "2023-08-04T09:56:32.002Z",
      "lastEditedBy": "admin",
      "type": "MATCHING_PROPOSAL",
      "severity": "LOW",
      "automationDefinitionId": null,
      "description": "Fix this matching issue",
      "records": [
        {
          "id": 76108,
          "entityId": "party_proposal_k.match_proposal"
        },
        {
          "id": 76107,
          "entityId": "party_proposal_k.match_proposal"
        }
      ]
    },
    {
      "id": 15,
      "status": "IN_PROGRESS",
      "name": "Matching issue (address)",
      "userAssignee": "jane.smith",
      "groupAssignee": "MDM_viewer",
      "workflowName": "consolidation",
      "workflowStep": "draft",
      "entityId": "party_proposal_k.match_proposal",
      "created": "2022-12-09T17:53:34.651Z",
      "createdBy": "jane.smith",
      "lastEdited": "2023-08-04T09:56:32.002Z",
      "lastEditedBy": "admin",
      "type": "MATCHING_PROPOSAL",
      "severity": "LOW",
      "automationDefinitionId": null,
      "description": "Different addresses",
      "records": [
        {
          "id": 76111,
          "entityId": "party_proposal_k.match_proposal"
        },
        {
          "id": 76113,
          "entityId": "party_proposal_k.match_proposal"
        }
      ]
    }
  ]
}

Get Tasks

Use the following request to get tasks detail information (without comments and history):

Request

GET /api/rest/v2/tasks

The request supports the following parameters:

Parameter Required Description

Parameter	Required	Description
active	Yes	Set to `true` to return active tasks, `false` to return closed tasks. Default value is `true`.
createdAfter	No	Filters tasks created after specified date (for example, `2022-12-09T16:27:40.359Z`, `2011-12-03`).
createdBefore	No	Filters tasks created before specified date (for example, `2022-12-09T16:27:40.359Z`, `2011-12-03`).
updatedAfter	No	Filters tasks updated after specified date (for example, `2022-12-09T16:27:40.359Z`, `2011-12-03`).
updatedBefore	No	Filters tasks updated before specified date (for example, `2022-12-09T16:27:40.359Z`, `2011-12-03`).
offset	No	Used for pagination. Defines how many items are skipped before returning results.
page	No	Used for pagination. Specifies the number of the page to return. The number of records on each page is defined by `count`.
count	No	Specifies the number of records included in the response.

active

Yes

Set to true to return active tasks, false to return closed tasks. Default value is true.

createdAfter

Filters tasks created after specified date (for example, 2022-12-09T16:27:40.359Z, 2011-12-03).

createdBefore

Filters tasks created before specified date (for example, 2022-12-09T16:27:40.359Z, 2011-12-03).

updatedAfter

Filters tasks updated after specified date (for example, 2022-12-09T16:27:40.359Z, 2011-12-03).

updatedBefore

Filters tasks updated before specified date (for example, 2022-12-09T16:27:40.359Z, 2011-12-03).

offset

Used for pagination. Defines how many items are skipped before returning results.

page

Used for pagination. Specifies the number of the page to return. The number of records on each page is defined by count.

count

Specifies the number of records included in the response.

Response

{
  "tasks": [
    {
      "id": 19,
      "status": "IN_PROGRESS",
      "name": "Missing PIDs",
      "userAssignee": "rachel.adams",
      "groupAssignee": "MDM_user",
      "workflowName": "consolidation",
      "workflowStep": "draft",
      "entityId": "party.master.masters",
      "created": "2022-12-09T17:58:33.517Z",
      "createdBy": "jane.smith",
      "lastEdited": "2023-08-02T19:28:46.761Z",
      "lastEditedBy": "admin",
      "type": "RECORD_CHANGE",
      "severity": "LOW",
      "automationDefinitionId": null,
      "description": "Click on record edit to start fixing DQ issues. You can also perform any other actions: add missing related data, activate or deactivate record, or split an instance from the master record.",
      "records": [
        {
          "id": 76083,
          "entityId": "party.master.masters"
        },
        {
          "id": 76080,
          "entityId": "party.master.masters"
        },
        {
          "id": 76078,
          "entityId": "party.master.masters"
        }
      ]
    },
    {
      "id": 20,
      "status": "NEW",
      "name": "We need to fix this NPI!",
      "userAssignee": null,
      "groupAssignee": "MDM_user",
      "workflowName": null,
      "workflowStep": null,
      "entityId": "facility.master.provider",
      "created": "2022-12-09T18:06:35.521Z",
      "createdBy": "john.taylor",
      "lastEdited": "2022-12-09T18:06:35.521Z",
      "lastEditedBy": "john.taylor",
      "type": "RECORD_CHANGE",
      "severity": "HIGH",
      "automationDefinitionId": null,
      "description": "Click on record edit to fix DQ issues.",
      "records": [
        {
          "id": 81540,
          "entityId": "facility.master.provider"
        }
      ]
    },
    {
      "id": 21,
      "status": "NEW",
      "name": "New record - Mark Dough",
      "userAssignee": null,
      "groupAssignee": "MDM_user",
      "workflowName": null,
      "workflowStep": null,
      "entityId": "party.master.masters",
      "created": "2022-12-09T18:12:08.253Z",
      "createdBy": "john.taylor",
      "lastEdited": "2022-12-09T18:12:08.253Z",
      "lastEditedBy": "john.taylor",
      "type": "CREATE",
      "severity": "LOW",
      "automationDefinitionId": null,
      "description": "Mark Dough, born 1973-09-16. I will just write down what I know",
      "records": []
    }
  ]
}

Get Tasks for Specific Record

Use the following request to get tasks for a specific record:

Request

GET /api/rest/v2/tasks/record/{recordId}

The request supports the following parameters:

Parameter	Required	Description
recordId	Yes	Record identifier.
entityId	No	Entity identifier.

Parameter

Required

Description

recordId

Yes

Record identifier.

entityId

Entity identifier.

Response

{
  "tasks": [
    {
      "id": 19,
      "status": "IN_PROGRESS",
      "name": "Missing PIDs",
      "userAssignee": "rachel.adams",
      "groupAssignee": "MDM_user",
      "workflowName": "consolidation",
      "workflowStep": "draft",
      "entityId": "party.master.masters",
      "created": "2022-12-09T17:58:33.517Z",
      "createdBy": "jane.smith",
      "lastEdited": "2023-08-02T19:28:46.761Z",
      "lastEditedBy": "admin",
      "type": "RECORD_CHANGE",
      "severity": "LOW",
      "automationDefinitionId": null,
      "description": "Click on record edit to start fixing DQ issues. You can also perform any other actions: add missing related data, activate or deactivate record, or split an instance from the master record.",
      "records": []
    },
    {
      "id": 33,
      "status": "NEW",
      "name": "Issue with PID on personal record",
      "userAssignee": "",
      "groupAssignee": "MDM_user",
      "workflowName": "consolidation",
      "workflowStep": "draft",
      "entityId": "party.master.masters",
      "created": "2023-03-20T22:27:56.395Z",
      "createdBy": "admin",
      "lastEdited": "2023-03-20T22:27:56.395Z",
      "lastEditedBy": "admin",
      "type": "RECORD_CHANGE",
      "severity": "INTERMEDIATE",
      "automationDefinitionId": 1,
      "description": "Missing or invalid PID",
      "records": []
    }
  ]
}

Task Workflow

Move Task to a New State

Use the following request to move a task to a new workflow state:

Request

POST /api/rest/v2/tasks/{id}/move/{transition}

The request supports the following parameters:

Parameter	Required	Description
id	Yes	Task identifier.
transition	Yes	Name of the transition.

Parameter

Required

Description

Yes

Task identifier.

transition

Yes

Name of the transition.

Response

{
  "id": 19,
  "status": "IN_PROGRESS",
  "name": "Missing PIDs",
  "userAssignee": null,
  "groupAssignee": "MDM_user",
  "workflowName": "consolidation",
  "workflowStep": "waiting_for_publish",
  "entityId": "party.master.masters",
  "created": "2022-12-09T17:58:33.517Z",
  "createdBy": "jane.smith",
  "lastEdited": "2023-08-04T10:29:46.101Z",
  "lastEditedBy": "admin",
  "type": "RECORD_CHANGE",
  "severity": "LOW",
  "automationDefinitionId": null,
  "description": "Fix DQ issues.",
  "records": [
    {
      "id": 76083,
      "entityId": "party.master.masters"
    },
    {
      "id": 76080,
      "entityId": "party.master.masters"
    },
    {
      "id": 76078,
      "entityId": "party.master.masters"
    }
  ]
}

Discard Task

Use the following request to discard a specific task (for more information about discarding tasks, see Resolving Tasks, section Discard Task). The response is empty.

Request

POST /api/rest/v2/tasks/{id}/discard

The request uses the following parameter:

Parameter	Required	Description
id	Yes	Task identifier.

Parameter

Required

Description

Yes

Task identifier.

Sample request

POST /api/rest/v2/tasks/{id}/discard

Task discarded comment

Stream Consumers

Use the following request to start a stream consumer <crm_stream_name>.

Request

POST /api/rest/interfaces/streaming/consumers/<crm_stream_name>/start

Use the following request to stop a stream consumer <crm_stream_name>.

Request

POST /api/rest/interfaces/streaming/consumers/<crm_stream_name>/stop

Use the following request to start all stream consumers.

Request

POST /api/rest/interfaces/streaming/consumers/start

Use the following request to stop all stream consumers.

Request

POST /api/rest/interfaces/streaming/consumers/stop

Purge

Use the following request to initiate a housekeeping procedure. Completely purges all records with eng_existing=0 and deletion_tid < TREF in the _EXPORT_REG table, which means that the operation does not purge records until the information about logical deletion is provided in incremental exports that these records are part of. It is also possible to provide the names of incremental exports that should be ignored as the request body.

Request

POST /api/rest/purge/
{"ignored": ["string"]}

The operation is visible in the ONE Runtime Server Admin under MD Process Monitoring > Execution Status (see MD Process Monitoring).

Persistence

Use the following request to drop indices in VLDB persistences. If some indices were created/deleted manually by a user, the operation will fail.

Request

DELETE /api/rest/persistence/indices

Use the following request to create indices in VLDB persistences. If some indices were created/deleted manually by a user, the operation will fail.

Request

POST /api/rest/persistence/indices

Use the following request to start the LTC (transaction garbage collector) for all VLDB persistences.

Request

POST /api/rest/persistence/triggerLtc

Use the following request to start the LTC for the VLDB persistence {name}.

Request

POST /api/rest/persistence/{name}/triggerLtc

System Parameters

Prints out the currently set runtime parameters (see Runtime Parameters).

http://localhost:9090/api/rest/parameters

Source Systems

List the source systems and information about them.

/source-systems
/source-systems/{name}

Tasks (System Tasks)

Provides information about active and finished system tasks, identical to what is provided under MD Process Monitoring > Execution Status (see MD Process Monitoring) in the ONE Runtime Server Admin. Query parameters offset and count are not compulsory; if they are not present, default values are used instead.

/tasks
/tasks?offset=0&count=5
/tasks/active
/tasks/active?offset=0&count=5
/tasks/finished
/tasks/finished?offset=0&count=5
/tasks/task/{id}

Event Handlers

Provides information about the event handlers, identical to what is provided under MD Process Monitoring > Execution Status (see MD Process Monitoring) in the ONE Runtime Server Admin. Query parameters offset and count are not compulsory; if they are not present, default values are used instead.

/event-handlers
/event-handlers?offset=0&count=5
/event-handlers/finished
/event-handlers/finished?offset=0&count=5
/event-handlers/finished/{id}

Statistics

Shows various statistics regarding instance types, instance records, master views, and their records. The information is identical to what is provided under MD Process Monitoring > Data Statistics (see MD Process Monitoring) in the ONE Runtime Server Admin.

/statistics/instance
/statistics/master

Draft Migration

Use the following request to migrate drafts to tasks when upgrading to the version 14.2.0.

Request

POST /api/rest/drafts/migration

The request supports the following parameters:

Parameter Description

Parameter	Description
`history`	If `history=true`, the history draft table is migrated. The default value is `false`.
`delete`	If `delete=true`, the old drafts are deleted after successful migration. The default value is `false`.

history

If history=true, the history draft table is migrated. The default value is false.

delete

If delete=true, the old drafts are deleted after successful migration. The default value is false.

Use the following request to delete old drafts when they are successfully migrated to tasks.

Request

DELETE /api/rest/drafts/migration

The request uses the following parameter:

Parameter Description

Parameter	Description
`history`	If `history=true`, the history drafts are deleted. The default value is `false`.

history

If history=true, the history drafts are deleted. The default value is false.

Other Interfaces

The endpoints indicated below show interfaces which provide information about MDM configuration.

Services: Shows a list of deployed native SOAP services and their endpoints.
Batch exports and Batch loads: Show a list of batch operations and loads which are unavailable.
Streaming consumers: Shows a list of streaming consumers which are configured, get name and status.
Operation plan: Shows the MDM engine’s order of executing different consolidation sub-tasks when loading/processing data (that is, cleansing, matching and merging of specific entities).

/interfaces/services
/interfaces/batch/exports
/interfaces/batch/loads
/interfaces/streaming/consumers
/operation-plan

Was this page useful?