The Rest Merge API allows to schedule merge jobs.

Schedule Merge Job
Workflow Callback
- Workflow Callback (since 10.0)
- Workflow Callback Example
Examples
- Schedule merge of the full "Apparel" catalog

Schedule Merge Job

Schedules a merge.

URL Pattern	`/manage/merge`
Method	`POST`
Content types	`application/json`
Media types	`application/json`
Result	The job object of the scheduled merge job

Query Parameters

Parameter	Required	Default	Datatype	Parameter description
`updateAssortment`	`false`	`false`	`Boolean`	If `updateAssortment` is set, corresponding assortment will be updated (which can be time consuming) before performing merge.
`workflowServiceEndpoint`	`no`		`String`	Informatica BPM callback parameter. Defines the name of the service endpoint which must be available in an attached Informatica BPM instance.
`workflowCorrelationId`	`no`		`String`	Informatica BPM callback parameter. An arbitrary id which is used by the Informatica BPM workflow to identify the correct workflow process.
`workflowCommunicationMode`	`no`	REST	`REST/QUEUE`	Informatica BPM callback parameter. Defines the communication mode which can be using JMS message queue and REST communication.
`workflowQueueId`	`no`	`First trigger queue id in server.properties`	`String`	Informatica BPM callback parameter. An queue id defined in the server properties in the message queue section which is used as response queue

Content

The content has to be a MergeProfile JSON object which includes the properties listed below.

Field	Required	Default	Datatype	Parameter description
`rootEntity`	no	"Article"	`String`	The identifier of the root entity this merge profile refers to. At the moment only the "Article" entity is supported - so this parameter is optional.
`catalog`	either catalog or entityReportQuery is mandatory!		`ENTITY_ITEM`	The supplier catalog to be merged from. If no assortment is given, all objects of the specified rootEntity will be merged from this catalog
`assortment`	`no`		`ENTITY_ITEM`	Optional assortment to be merged
entityReportQuery	no		`EntityReportQuery`	An entity report query which allows to use the available reports like 'byCatalog', 'byItems'... (Since 8.0.03)
entityReportQueryExecution	no	DEFERRED	`IMMEDIATE or DEFERRED`	Defines when the content of the entity report query is resolved: at the moment of calling the rest method or when the merge job runs. If set to DEFERRED, the report is executed when the merge job begins to run. (Since 8.0.03)
`executionDate`	`no`	`now`	`DATETIME`	Date and time when the merge should be started.
`defaultAction`	`no`	`"SUPPLEMENT"`	`String`	Default merge mode for all fields in case the corresponding supplier catalog has no persisted merge profile. "SUPPLEMENT", "OVERWRITE", "CLEAN_COPY", "NO_MERGE" This parameter doubles as the default action for the entityQualification parameter object. There is a priority order for the merge actions! Highest priority has the `entityQualification` parameter. In case this one is given, then this is how the merge is going to be performed. If this parameter is not given, the merge will be done as defined in the merge settings of the supplier catalog! The merge settings of the supplier catalog can be adjusted in the desktop client only. Last priority has the `defaultAction` parameter. In case the `entityQualification` is omitted and there are no supplier catalog merge settings, then all fields and entities will be merged according to this `defaultAction` parameter. Finally, in case this one is also not there, a SUPPLEMENT merge is performed.
entityQualification	no		`EntityQualification`	Optional parameter to fine grain the merge actions down to the field level. Provides also the ability to filter based on qualifications (like: merge only the short description in English). See also special chapter below.

Entity Report Query

The items to be merged can be defined in two different ways. You can either specify the supplier catalog and optionally an assortment, or a more sophisticated entityReportQuery. The entity report query option provides a fine grained way to define even single items. For this you can use all available entity reports of the system. What reports are available can differ from Product 360 to Product 360 installation and therefore are documented by the Service API itself. The documentation can be obtained using the List Info API.

Using byCatalog report query

POST /rest/V1.0/manage/merge

{
 "entityReportQuery": {
  "identifier": "byCatalog",
  "entityIdentifier": "Article",
  "parameterList": [{
   "key": "catalog",
   "value": "'Apparel'"
  }]
 }
}

Using byItems report query

Note: the items must have the same container, it is not possible to specify items from multiple catalogs

POST /rest/V1.0/manage/merge

{
 "entityReportQuery": {
  "identifier": "byItems",
  "entityIdentifier": "Article",
  "parameterList": [{
   "key": "items",
   "value": "'Article1'@'CatalogIdentifier',123@1000"
  }]
 }
}

Using bySearch report query

Note: the items must have the same container, it is not possible to specify items from multiple catalogs

POST /rest/V1.0/manage/merge

{  
  "entityReportQuery":{   
    "identifier":"bySearch",  
    "entityIdentifier":"Article",
    "parameterList":[ 
        {        
          "key":"query",  
          "value":"Article.EAN in ( \"1234\" , \"1235\" )" 
        } ,
        {
          "key":"catalog",  
          "value":"'TestCatalog'" 
        }
     ]  
} 

Merge Actions

Mode	Description	Field	Supplier Item	Master Item (Before)	Master Item (After)
NO_MERGE	This is probably the easiest one. If this action is defined, no merge will be performed for the entity or field	`Description (en)`	"My Changed English Value"	"My English Value"	"My English Value"
SUPPLEMENT	A field or entity is only merged in case the master item has not already an object/value for this entity or field	`Description (en)`	"My Changed English Value"	"My English Value"	"My English Value"
SUPPLEMENT		`Description (en)`	"My Changed English Value"		"My Changed English Value"
OVERWRITE	A field or entity is always merged, in case the master catalog already has a value for this field, the value is overwritten	`Description (en)`	"My Changed English Value"	"My English Value"	"My Changed English Value"
CLEAN_COPY	Similar to OVERWRITE for fields, but in case of entities is also deletes sub-entities which do not exist in the supplier item The example shows that the master item has a value for German and English, but after the clean copy merge, only the value from the supplier item survives.	`Description (en)`	"My Changed English Value"	"My English Value"	"My Changed English Value"
CLEAN_COPY		`Description (de)`		"Mein Deutscher Wert"

EntityQualification

The EntityQualification parameter is supported with version 8.0.6.01 and following only.

The EntityQualification is a complex data structure which defines how exactly each field of each sub-entity should be merged. The EntityQualification structure is recursive, thus, it has children which have the same structure.

It is required to qualify the whole path to the desired subentity. The qualification has to include the root entity.

On each level you can define a defaultAction which sets the action for this entity and it's fields and all sub-entities which are not explicitly part of the EntityQualification. So, you only need to specify EntityQualification objects and their fieldActions in case they differ from the corresponding defaultAction.

Each EntityQualification defines the identifier of the entity, the defaultAction, optional qualificationFilters (like, only for a certain language), the fieldActions (in case they are different than the defaultAction) and the children (in case they have a different actions as the defaultAction).

Attribute	Datatype	Description
`entity`	`String`	the unique identifier of the entity / sub-entity. See the Meta API for details on the possible entities.
`defaultAction`	`String`	one of the Merge Actions (`NO_MERGE, SUPPLEMENT, OVERWRITE, CLEAN_COPY`)
`qualificationFilters`	`String[]`	With the `qualificationFilters` array you can limit this EntityQualification so it only applies for a subset (just a specific language for example) The `qualificationFilters` is an array of qualification settings. A qualification setting is a qualification name followed by a comma-separated list of values which is put into parentheses . The qualification name is defined in the repository and is included in the Meta-API. Example for German language: "qualificationFilters" : [ "language(DE)" ] The syntax is quite similar to the List API for sub-entities.
`fieldActions`	`FieldAction[]`	Array of `FieldAction` elements. Each `FieldAction` holds the `fieldIdentifier` of a field and an `fieldAction`. In case a field is not part of this array, it's treated like defined in the `defaultAction`.
`children`	`EntityQualification[]`	optional array of `EntityQualification` elements to define the sub-entities. If omitted, the sub-entities will be merged like this entity

Example

The following example defines as default "NO_MERGE" which means, that by default, nothing should be merged. It really depends on the use case what to pick as default. Usually the default should be whatever the most fields/children have, so you don't need to specify too much.

So in this example we only want to merge the German (=language(DE)) Name (=ArticleLang.Name) of an item and the English (=language(EN)) Description (=ArticleLang.Description). In order to be able to have different settings based on the qualification or the entity, you can specify an EntityQualification multiple times. However, you must make sure that the qualification values do not overlap (otherwise the result of the merge for this will not be predictable).

All Fields of the ArticleLang entity in SUPPLEMENT mode, but the Name in OVERWRITE

 "entityQualification": {
    "entity": "Article",
    "defaultAction": "NO_MERGE",
    "children": [
        {
            "entity": "ArticleLang",
            "defaultAction": "NO_MERGE",
            "qualificationFilters": [
                "language(DE)"
            ],
            "fieldActions": [
                {
                    "fieldIdentifier": "ArticleLang.DescriptionShort",
                    "fieldAction": "OVERWRITE"
                }
            ]
        },
        {
            "entity": "ArticleLang",
            "defaultAction": "NO_MERGE",
            "qualificationFilters": [
                "language(EN)"
            ],
            "fieldActions": [
                {
                    "fieldIdentifier": "ArticleLang.DescriptionLong",
                    "fieldAction": "OVERWRITE"
                }
            ]
        }
    ]
}

Result

An object reference to the merge job.

Field	Data type	Description
id	Integer	The job ID
label	String	The label of the job

Workflow Callback

If a merge job is scheduled with a workflowServiceEndpoint parameter, a callback is given to the Informatica BPM server.

This call will include data about the job itself as well as reports about the merge result. With help of the id of the report information it is even possible to retrieve the merged items (using the List API) .

Workflow Callback (since 10.0)

It is possible to add the query parameters workflowQueueServiceEndpoint and workflowQueueId and workflowCommunicationMode which allows to specify that the response is send via the message queue. The workflowServiceEndpoint is send back as JMS property P360TargetService which allows BPM to call workflow endpoints. The workflowQueueId parameter specifies a queue configured in the server.properties with syntax "queue.[queueId].name".

Workflow Callback Example

An example callback body to the service endpoint of Informatica BPM if a workflow service endpoint parameter has been specified.

Workflow Callback Example XML

<jobFinished>
 <jobId>35</jobId>
 <stateIdentifier>finished.info</stateIdentifier>
 <stateLabel>Beendet</stateLabel>
 <reportResults>
  <entry key="TOTAL">
   <reportResult>
    <id>2557</id><!-- With help of this reportid and the byReportId report of the list API you can retrieve all items related to this report result -->
    <dataSource>PCM_MASTER</dataSource>
    <type>1</type>
    <purpose>3</purpose>
    <resultTableName>ReportStore0</resultTableName>
    <count>2</count>
    <entityIdentifier>Article</entityIdentifier>
   </reportResult>
  </entry>
  <entry key="UNMODIFIED"/>
  <entry key="NEW">
   <reportResult>
    <id>2558</id>
    <dataSource>PCM_MASTER</dataSource>
    <type>1</type>
    <purpose>3</purpose>
    <resultTableName>ReportStore1</resultTableName>
    <count>2</count>
    <entityIdentifier>Article</entityIdentifier>
   </reportResult>
  </entry>
  <entry key="UPDATED"/>
  <entry key="NEW_AND_UPDATED">
   <reportResult>
    <id>2559</id>
    <dataSource>PCM_MASTER</dataSource>
    <type>1</type>
    <purpose>3</purpose>
    <resultTableName>ReportStore2</resultTableName>
    <count>2</count>
    <entityIdentifier>Article</entityIdentifier>
   </reportResult>
  </entry>
  <entry key="FILTERED_BY_DQ"/>
  <entry key="FILTERED_BY_PRODUCT_FINDER"/>
 </reportResults>
</jobFinished>

Examples

Schedule merge of the full "Apparel" catalog

Java Client API: Merge full

    MergeProfile mergeProfile = new MergeProfile();
    mergeProfile.setCatalog( EntityItemReferenceFactory.createByIdentifier( "Apparel" ) );
    mergeProfile.setDefaultAction( "OVERWRITE" ); 
 
    MergeRequest mergeRequest = getRestClient().createMergeRequest();
    EntityItemReference mergeJobReference = mergeRequest.scheduleMergeJob( mergeProfile );

Merge Profile: Full Apparel catalog with OVERWRITE action for everything

  "catalog" : {
    "id" : "Apparel"
  },
  "rootEntity" : "Article",
  "defaultAction" : "OVERWRITE"

Merge Profile: Full Apparell Catalog, but only the Long Description in English

{
  "rootEntity" : "Article",
  "catalog" : {
    "id" : "Apparel"
  },
  "defaultAction" : "NO_MERGE",
  "entityQualification" : {
    "entity" : "Article",
    "defaultAction" : "NO_MERGE",
    "children" : [ {
      "entity" : "ArticleLang",
      "defaultAction" : "NO_MERGE",
      "qualificationFilters" : [ "language(EN)" ],
      "fieldActions" : [ {
        "fieldIdentifier" : "ArticleLang.DescriptionLong",
        "fieldAction" : "OVERWRITE"
      } ]
    }
  }
}