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

== 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?)

  - Extensions:
    - provide a {{{Copy All}}} button to copy all values from the merge source
    - provide a {{{Undo}}} button to take back all changes
    - Use {{{update_next}}} for default redirection, or do we need a separate {{{merge_next}}}?
    - provide a {{{Replace}}} button to replace the original by the merge source:
      - basically just a link from {{{/xxx/yyy/25/merge?with=27}}} to {{{/xxx/yyy/27/merge?with=25}}}

== Use-Cases ==

  - Primary actor:
    - admin user / editor user

  - Merging of duplicate records in the de-duplicator
    - De-duplicator UI presents a list of possible pairs of duplicates: ''(original, duplicate)''
    - List entries are linked to the {{{merge}}} method (action button)
  - Merging of conflicting remote records in the synchronization conflict resolution UI
    - Conflict UI presents a list of conflicting updates: ''(original, conflicting update)''
    - List entries are linked to the {{{merge}}} method (action button), or {{{delete}}}

== Design ==

  - Implement {{{merge}}} as a subclass of {{{S3Method}}}
  - Implement a generic view {{{merge.html}}} ({{{_merge.html}}}) which:
    - renders the form

== Implementation ==

  - UserGuidelines/Admin/RecordMerging