MDM Time Machine

author
Talend Documentation Team
EnrichVersion
6.4
6.3
6.2
6.1
EnrichProdName
Talend Data Fabric
Talend MDM Platform
task
Data Governance > Retrieving data
EnrichPlatform
Talend MDM Server

MDM Time Machine

MDM time machine is a newly introduced REST interface, which can be used to retrieve a snapshot of a specific MDM record and navigate through the record history. MDM time machine REST is an enterprise-only feature. If you use it on community editions, a 404 HTTP error will occur.
Environment

Talend MDM v5.6 or higher.

Introduction

MDM time machine relies on the journal (update reports) created each time an update is performed on an MDM record. You may already see the time machine in action when you navigate to the previous or next log file in the journal.

The REST interface uses the same concepts but with a more program-friendly way that can be easily invoked from a Talend job.

Since Release 6.0, the REST calls use a different format. You need to choose the correct format according to the product version you are using.

Known limitations

Currently, all history browsing operations in MDM have one known limitation: since a created record is not saved in the journal, MDM cannot browse changes when one of the events is a delete event, which may be from a "send to trash" or a "physical" delete operation.

However, this limitation is consistent with the “Journal” web application.

REST calls for MDM time machine

The following illustrates how to make MDM time machine REST calls with several examples:

  • Getting the latest version of a specific record
  • Getting the version of a specific record at a given date time
  • Scenario for understanding the “datetime” parameter in a REST call
  • Moving back and forth in the record history
  • Scenario for understanding the “swing” parameter
  • Using the metadata information
Get ting the latest version of a specific record

To get the latest version of a specific record, use a REST call in the following format:

GET

Where "container_name" and "type_name" must be respectively changed to the container name you wish to query and the entity type name. The "id" parameter should be replaced with the id of the MDM record instance you wish to retrieve.

For an entity type with a composite key, use the "." (dot) separator in the declaration order in the entity type. For example, if you have (age, name) as the key, you may use "10.John" as the “id” for the REST call.

For example, in Talend MDM v5.6, to get the latest version of the Store instance with id 12 in the TMDM-6892 container, use the REST call as follows:

http://localhost:8080/datamanager/services/data/TMDM-6892/Store/12

The HTTP answer contains the XML record you wish to retrieve.

All HTTP calls must be authenticated using an MDM user allowed to access the entity type.

Get ting the version of a specific record at a given date time

To get the version of a specific record at a specific date time, use a REST call in the following formats:

GET

The additional parameter "datetime" indicates to MDM where it should position in the record history. This URL returns the record as it was on the specified date time rather than a change occurred at the specified "datetime".

The "datetime" can be either a long value (the difference, measured in milliseconds, between time and midnight, January 1, 1970 UTC) or a date time as specified in the XML specification.

For example, in Talend MDM v5.6, if you use this REST call:

http://localhost:8080/datamanager/services/data/TMDM-6892/Store/12?datetime=2014-02-27T17:00:00 ,

it will return the Store instance in the TMDM-6892 container with id 12 as it was on February 27, 2014.

To get a better understanding of the “datetime” parameter, go to the section Scenario for understanding the “datetime” parameter in a REST call .

Scenario for u nderstanding the datetime parameter in a REST call

The following introduces a scenario to better explain the “datetime” parameter of a REST call in Talend MDM v5.6.

For example, a record was created with the following content at 2014-03-05T17:40:00:

<entity>

<id>1</id>

<value>value1</value>

</entity>

Then, at 2014-03-05T17:45:00, the record was modified for the first time as follows:

<entity>

<id>1</id>

<value>value2</value>

</entity>

Finally, at 2014-03-05T17:50:00, the record was modified once again:

<entity>

<id>1</id>

<value>value3</value>

</entity>

If you call http://localhost:8080/datamanager/services/data/DataBrowser/Entity/1?datetime=2014-03-05T17:40:00 , it returns how the record was at 17:40:00, as shown below:

<entity>

<id>1</id>

<value>value1</value>

</entity>

Now if you call http://localhost:8080/datamanager/services/data/DataBrowser/Entity/1?datetime=2014-03-05T17:42:30 , it returns how the record was at 17:42:30, the same as it was at 17:40:00, as shown below:

<entity>

<id>1</id>

<value>value1</value>

</entity>

Note that the next modification on the record occurred 2 minutes and 30 seconds later at 17:45:00.

Mov ing back and forth in the record history

You can set your position in the record history, and use the "swing" parameter to move back and forth from this history point:

GET

The value of the "swing" parameter must be one of the following:

  • closest: default behavior if “swing” is unspecified.
  • before: moving to the previous version of the record.
  • after: moving to the next version of the record.

For "before" and "after", if there is no state (for example, you are at the first state or the last one), MDM returns a result the same as that for "closest".

Here is one example in Talend MDM v5.6:

http://localhost:8080/datamanager/services/data/TMDM-6892/Store/12?datetime=2014-02-27T17:00:00&swing=before

If you position on the date when the record was created and use "swing=before" in a REST call, the service returns no content. This can be seen as "before the record was created, nothing existed for the id".

Scenario for understanding the “swing” parameter

Here, we reuse the example from the previous section on the scenario for understanding the "datetime" parameter.

The "swing" parameter allows you to move back and forth in user changes.

For the REST call http://localhost:8080/datamanager/services/data/DataBrowser/Entity/1?datetime=2014-03-05T17:42:30?swing=after , you will get:

<entity>

<id>1</id>

<value>value2</value>

</entity>

This is because the next change after 17:42:30 is the change that changed "value1" to "value2".

For the REST call http://localhost:8080/datamanager/services/data/DataBrowser/Entity/1?datetime=2014-03-05T17:42:30?swing=before , you will get:

<entity>

<id>1</id>

<value>value1</value>

</entity>
Using the metadata information

MDM also returns all standard available metadata in the result.

For example, calling GET on the following URL http://localhost:8080/datamanager/services/data/Customer/Customer/4b1f7d9c-4fda-4a39-bbab-d20506c0af10?datetime=1396361244000 in Talend MDM v5.6 returns the following data:

<Customer xmlns:metadata="http://www.talend.com/mdm/metadata">

    <metadata:timestamp>1396361240263</metadata:timestamp>

    <metadata:task_id>4b1f7d9c-4fda-4a39-bbab-d20506c0af10</metadata:task_id>

    <MDM_Id>4b1f7d9c-4fda-4a39-bbab-d20506c0af10</MDM_Id>

    <source_id>99</source_id>

    <account_num>999</account_num>

    <lname>CarbonCarboneCarbone</lname>

    <fname>Cedric</fname>

    <address1>9rue Pag&#203;s</address1>

    <city>Suresnes</city>

    <state_province>FR</state_province>

    <postal_code>92150</postal_code>

    <country>France</country>

    <customer_region_id>1</customer_region_id>

    <marital_status>unknown</marital_status>

    <yearly_income>0</yearly_income>

    <gender>M</gender>

    <total_children>1</total_children>

    <num_children_at_home>1</num_children_at_home>

    <education>Master</education>

    <member_card>GOLD</member_card>

    <occupation>CTO</occupation>

    <houseowner>TRUE</houseowner>

    <fullname>C&#233;dricCarbone</fullname>

</Customer>

You can first notice the timestamp in the returned document and the URL does not match (139636124 0263 != 139636124 4000 ). This is expected since it returns the time of the last modification, and at t = 139636124 4000 the last modification that occurred on the record was at time t = 139636124 0263 .