[[TOC]]
= !BluePrint: Record Merger =

== Introduction ==

There are several occasions where records need to be merged manually, e.g.:

  - De-duplication
  - Synchronization conflict resolution

== Description ==

The idea is to implement a generic {{{merge}}} method for the [wiki:S3XRC/RESTfulAPI RESTful API], which responds to URLs like:

{{{
/xxx/yyyyyy/25/merge?with=27
}}}

  - merge record 27 (='''merge source''') into record 25 (='''original record''')

Additionally, the low-level API could also accept a {{{Storage}}} of fields from the caller instead of another record.

== Requirements ==
[[Image(merge.png)]]
  - GET {{{merge}}} returns a form like above:
    - the {{{merge}}} form behaves basically like a normal {{{update}}} form:
      - the user can edit the original record
      - the user can click on {{{<<copy}}} to copy values from the merge source

  - POST {{{merge}}} does:
    - update the original record with the data of the form
    - update all links to the merge source into links to the original record
    - mark the merge source deleted (or delete it, if no deletion status)
    - audit {{{update}}}

  - PUT {{{merge}}} does:
    - respond with "invalid method" (HTTP/405)

  - DELETE {{{merge}}} does:
    - respond with "invalid method" (HTTP/405)

  - Errors:
    - original record does not exist => HTTP/404 Not Found
    - merge source does not exist => HTTP/404 Not Found (or redirect to update?)


== Use-Cases ==

  - Primary actor:
    - admin user / editor user

  - Merging of duplicate records in the de-duplicator
  - Merging of conflicting remote records in the synchronization conflict resolution UI

== Design ==

  - Implement {{{merge}}} as a method in S3Resource, which:
    - generates the {{{merge}}} form from either another record in the same resource or a Storage of fields
    - processes the form upon POST
  - Implement {{{merge}}} as a method in S3CRUDHandler, which:
    - parses the URL query variable {{{with}}}
    - calls the S3Resource.merge method appropriately

== Implementation ==

  - not yet implemented, scheduled for [wiki:S3XRC/FeatureRoadmap S3XRC 2.3]

----
BluePrints