How to perform mass partial update on MDM data records through the REST API

author
Talend Documentation Team
EnrichVersion
6.4
EnrichProdName
Talend MDM Platform
Talend Data Fabric
task
Data Governance > Consolidating data
EnrichPlatform
Talend MDM Server

How to perform mass partial update on MDM data records through the REST API

In Talend MDM, instead of updating data records one by one, you may need to update one or more fields of multiple data records that pertain to an entity in one go.

Now an MDM REST interface is available to allow you to perform the partial update of records in one bulk operation through the REST API.

This article applies to all Talend Platform products with MDM 6.3.1 and above.

REST API for mass partial update

Perform partial update of many records that pertain to one entity in one single bulk operation.

Note that the mass partial update operation will not invoke the Before-Saving process.

Request

PATCH /services/rest/data/{containerName}/{entity}/bulk

Request URL

http://{serverurl}/talendmdm/services/rest/data/{containerName}/{entity}/bulk

Query Parameters

  • containerName: This is a String value which specifies the name of the data container where you want to perform the mass partial update.
  • entity: This is a String value which represents the entity on which you want to perform the mass partial update.

Headers

  • Content-Type: application/xml
  • Authorization: Basic Authentication scheme

Request Body

An XML representation of records that will be used to update the existing data records partially.

Each record contains:

  • one or more primary key fields with values, which are mandatory because they will be used to specify the record you want to update,
  • an arbitrary number of other fields, with values which will be used to update the existing ones.

Example:

<records>
  <Product>
    <Id>1</Id>
    <Name>New Name</Name>
    <Price>30</Price>
  </Product>
  <Product>
    <Id>2</Id>
    <Name>New Name2</Name>
  </Product>
</records>

Response Body

No content.

Response Code

  • 200 OK: Indicates that all specified records are updated successfully.
  • 403 FORBIDDEN: Indicates that users do not have read or write access to the specified container or entity.
  • 400 Bad Request: Indicates that the mass partial update operation failed. Possible reasons are:
    • The container name specified in the request URL is different from the entity provided in the request body.
    • There is no primary key field in the request body.
    • There is no primary key value in the request body.
    • One or more specified records in the request body do not exist.
    • The value is missing for one or more mandatory fields in the request body.
    • Invalid data records exist in the request body.
Attention: If you do not have write access to the specified field(s), the mass partial update operation will continue to process other fields without throwing any exceptions. However, you can read the error message in the MDM log file. For example, User 'user' is not allowed to perform following operation(s): update field 'Description' of type 'Product'.

Examples: Partially updating simple type fields or multi-occurrence fields of multiple data records through the REST API

These examples show how to provide the correct request body to update partially simple type fields or multi-occurrence fields of multiple data records successfully through the REST API.

In these examples, the data records to be updated pertain to the Product entity in the Product data model of the MDM demo project, as shown below.

<Product>
  <Id>1</Id>
  <Name>Book</Name>
  <Description>Harry</Description>
  <Features>
    <Sizes/>
    <Colors/>
  </Features>
  <Price>10.00</Price>
  <Stores/>
</Product>
<Product>
  <Id>2</Id>
  <Name>Book</Name>
  <Description>Harry Potter</Description>
  <Features>
    <Sizes/>
    <Colors/>
  </Features>
  <Price>20.00</Price>
  <Stores/>
</Product>
<Product>
  <Id>3</Id>
  <Name>Book</Name>
  <Description>Harry Potter Series</Description>
  <Features>
    <Sizes>
      <Size>Large</Size>
      <Size>X-Large</Size>
    </Sizes>
    <Colors>
      <Color>Light Pink</Color>
    </Colors>
  </Features>
  <Price>30.00</Price>
  <Stores/>
</Product>

Before you perform a partial update, check that:

  • The Talend MDM Server is up and running.
  • The MDM demo project has been imported and deployed to the Talend MDM Server.
  • The above-mentioned data records already exist.

Partially updating simple type fields of multiple data records

Request body

To update the values of simple type fields (Name, Description and Price in this example) in the three Product data records, send the following update information in the request body:

<records>
  <Product>
    <Id>1</Id>
    <Name>The first book</Name>
    <Description>Harry Potter and the Philosopher’s Stone</Description>
    <Price>111</Price>
  </Product>
  <Product>
    <Id>2</Id>
    <Name>The second book</Name>
    <Description>Harry Potter and the Chamber of Secrets</Description>
    <Price>222</Price>
  </Product>
  <Product>
    <Id>3</Id>
    <Name>The third book</Name>
    <Description>Harry Potter and the Prisoner of Azkaban</Description>
    <Price>333</Price>
  </Product>
</records>

Results

After the successful mass partial update, the updated records should look like the following:

<Product>
  <Id>1</Id>
  <Name>The first book</Name>
  <Description>Harry Potter and the Philosopher’s Stone</Description>
  <Features>
    <Sizes/>
    <Colors/>
  </Features>
  <Price>111.00</Price>
  <Stores/>
</Product>
<Product>
  <Id>2</Id>
  <Name>The second book</Name>
  <Description>Harry Potter and the Chamber of Secrets</Description>
  <Features>
    <Sizes/>
    <Colors/>
  </Features>
  <Price>222.00</Price>
  <Stores/>
</Product>
<Product>
  <Id>3</Id>
    <Name>The third book</Name>
    <Description>Harry Potter and the Prisoner of Azkaban</Description>
    <Features>
    <Sizes>
      <Size>Large</Size>
      <Size>X-Large</Size>
    </Sizes>
    <Colors>
      <Color>Light Pink</Color>
    </Colors>
  </Features>
  <Price>333.00</Price>
  <Stores/>
</Product>

Partially updating multi-occurrence fields of multiple data records

Request body

To update the values of multi-occurrence fields (Size and Color in this example) in two Product data records of Id 1 and Id 2, send the following update information in the request body:

<records>
  <Product>
    <Id>1</Id>
    <Features>
      <Sizes>
        <Size>Small</Size>
        <Size>Medium</Size>
      </Sizes>
      <Colors>
        <Color>White</Color>
        <Color>Light Blue</Color>
      </Colors>
    </Features>
  </Product>
  <Product>
    <Id>2</Id>
    <Features>
      <Sizes>
        <Size>Small</Size>
      </Sizes>
      <Colors>
        <Color>Lemon</Color>
      </Colors>
    </Features>
  </Product>
</records>

Results

After the successful mass partial update, the updated records should look like the following:

<Product>
  <Id>1</Id>
  <Name>Book</Name>
  <Description>Harry</Description>
  <Features>
    <Sizes>
      <Size>Small</Size>
      <Size>Medium</Size>
    </Sizes>
    <Colors>
      <Color>White</Color>
      <Color>Light Blue</Color>
    </Colors>
  </Features>
  <Price>10.00</Price>
  <Stores/>
</Product>
<Product>
  <Id>2</Id>
  <Name>Book</Name>
  <Description>Harry Potter</Description>
  <Features>
    <Sizes>
      <Size>Small</Size>
    </Sizes>
    <Colors>
      <Color>Lemon</Color>
    </Colors>
  </Features>
  <Price>20.00</Price>
  <Stores/>
</Product>

Examples: Clearing the values of a multi-occurrence field through the REST API

These examples show how to provide the correct request body to clear the values of a multi-occurrence field successfully through the REST API.

In these examples, the following data record will be updated:

<Company>
  <CompanyId>DStar</CompanyId>
  <Subsidiaries>S_Beijing</Subsidiaries>
  <Subsidiaries>S_Shanghai</Subsidiaries>
  <Branches>
    <Office1>Large</Office1>
    <Office2>Medium</Office2>
    <Office3>Small</Office3>
  </Branches>
</Company>

Clearing the values of a multi-occurrence simple type field

Request body

To clear the values of a multi-occurrence simple type field ("Subsidiaries" in this example) in the Company record with CompanyId of DStar, send the following update information in the request body:

<records>
  <Company>
    <CompanyId>DStar</CompanyId>
    <Subsidiaries></Subsidiaries> 
  </Company>
</records>

Result

After the successful mass partial update, the updated record should look like the following:

<Company>
  <CompanyId>DStar</CompanyId>
  <Branches>
    <Office1>Large</Office1>
    <Office2>Medium</Office2>
    <Office3>Small</Office3>
  </Branches>
</Company>

Clearing the values of an entire multi-occurrence complex type field

To clear the values of an entire multi-occurrence complex type field, you must specify the type element structure in the update information.

Request body

To clear the values of a multi-occurrence complex type field ("Branches" in this example) in the Company record with CompanyId "DStar", send the following update information in the request body:

<records>
  <Company>
    <CompanyId>DStar</CompanyId>
    <Branches>
      <Office1></Office1>
      <Office2></Office2>
      <Office3></Office3>
    </Branches>
  </Company>
</records>

Result

After the successful mass partial update, the updated record should look like the following:

<Company>
  <CompanyId>DStar</CompanyId>
  <Subsidiaries>S_Beijing</Subsidiaries>
  <Subsidiaries>S_Shanghai</Subsidiaries>
</Company>

Clearing the value of a specific element in a multi-occurrence complex type field

Request body

To clear the value of a specific element in a multi-occurrence complex type field (element "Office2" of field "Branches" in this example) of the Company record with CompanyId "DStar", send the following update information in the request body:

<records>
  <Company>
    <CompanyId>DStar</CompanyId>
    <Branches>
      <Office2></Office2>
    </Branches>
  </Company>
</records>

Result

After the successful mass partial update, the updated record should look like the following:

<Company>
  <CompanyId>DStar</CompanyId>
  <Subsidiaries>S_Beijing</Subsidiaries>
  <Subsidiaries>S_Shanghai</Subsidiaries>
  <Branches>
    <Office1>Large</Office1>
    <Office3>Small</Office3>
  </Branches>
</Company>