NAME
    RT::Extension::MergeUsers - Merges two users into the same effective
    user

RT VERSION
    Works with RT 5.0 (5.0.8 and newer), RT 6.0. For RT 4.0, 4.2, 4.4, 5.0
    (up to 5.0.7) download version 1.11.

DESCRIPTION
    This RT extension adds a "Merge Users" box to the User Administration
    page, which allows you to merge the user you are currently viewing with
    another user on your RT instance.

    It also adds "MergeInto" and "UnMerge" functions to the RT::User class,
    which allow you to programmatically accomplish the same thing from your
    code.

    It also provides a version of CanonicalizeEmailAddress, which means that
    all e-mail sent from secondary users is displayed as coming from the
    primary user.

INSTALLATION
    Be sure to also read "UPGRADING" if you are upgrading.

    perl Makefile.PL
    make
    make install
        May need root permissions

    Edit your /opt/rt6/etc/RT_SiteConfig.pm
        Add this line:

            Plugin('RT::Extension::MergeUsers');

    Clear your mason cache
            rm -rf /opt/rt6/var/mason_data/obj

    Restart your webserver

UPGRADING
    If you are upgrading from 0.03_01 or earlier, you must run
    bin/rt-update-merged-users. This script will create MergedUsers
    Attributes so RT can know when you're looking at a user that other users
    have been merged into. If you don't run this script, you'll have issues
    unmerging users. It can be safely run multiple times, it will only
    create Attributes as needed.

UTILITIES
  rt-clean-merged-users
    When a user with another user merged into it is shredded, the attributes
    on that user are also shredded, but the merged user will remain, along
    with attributes that may point to the now missing user id. This script
    cleans up attributes if the merged-into user record is now gone. These
    users will then be converted back to regular unmerged users.

  rt-merge-users
    A command-line tool to merge one user into another

CAVEATS
  RT::Shredder and Merged Users
    Merging a user effectively makes it impossible to load the merged user
    directly. Attempting to access the old user resolves to the merged-into
    user. Because of this, MergeUsers has some extra code to help
    RT::Shredder clean up these merged records to avoid leaving merged user
    records in the DB while removing the user they were merged into.

    When running RT::Shredder on a user record with other users merged into
    it, the merged users are Unmerged before the initial user record is
    shredded. There are two options to handle these newly unmerged users:

    1.  Re-run your shredder command with the same or similar options. The
        unmerged user records will now be accessible and, depending on your
        shredder options, they will likely be shredded on the second run. If
        you have multiple layers of merged users, you may need to run
        shredder multiple times.

    2.  MergeUsers will log the unmerged users at the info level so you can
        pull the user ids from the log and shred them manually. This is most
        likely to be useful if you are shredding one specific user (and all
        merged accounts).

  rt-serializer
    MergeUsers is not compatible with rt-seralizer, you need to disable the
    extension before running rt-serializer.

  Single level of merged users
    A user can only be merged into a single user.

    A user can have multiple users merged into themselves.

    A user that has been merged into one user cannot be merged into a
    different user. You must first unmerge the user and then merge them into
    the different user.

    A user that has one or more users merged into themselves cannot be
    merged into another user. You must first unmerge all the merged users
    and then merge them all into the other user. Previous versions would
    allow multiple levels of merging when calling MergeInto from a command
    line script but some searching functionality does not work correctly in
    such cases and so it has been disallowed.

REST2 API
    RT::Extension::MergeUsers provides REST2 API endpoints for
    programmatically merging and unmerging users.

  Authentication and Permissions
    All REST2 endpoints require authentication and the AdminUsers right on
    the system object.

  POST /user/{id}/merge
    Merge a user into another user. The user specified in the URL path will
    be merged into the user specified in the request body.

    Request Format:

    Content-Type: application/json

        {
            "User": "target_user_id_or_name"
        }

    The User field is required and can be either a user ID or username.

    Response Format (Success):

        {
            "message": "Merged users successfully",
            "merged_user": {
                "id": 123,
                "name": "user1"
            },
            "target_user": {
                "id": 456,
                "name": "user2"
            }
        }

    Example:

        curl -X POST https://rt.example.com/REST/2.0/user/123/merge \
             -H "Authorization: token YOUR_TOKEN" \
             -H "Content-Type: application/json" \
             -d '{"User": "456"}'

  POST /user/{id}/unmerge
    Unmerge users that have been merged into the specified user. This
    endpoint supports two modes of operation:

    *   Unmerge all merged users (default)

        When called with an empty JSON body or no User parameter, this will
        unmerge ALL users that have been merged into the specified user.

        Request Format:

        Content-Type: application/json

            {}

        Response Format (Success):

            {
                "message": "Unmerged 2 user(s) from primary_user",
                "unmerged_users": [
                    {
                        "id": 123,
                        "name": "user1",
                        "message": "Unmerged user1 <[email protected]> from primary_user <[email protected]>"
                    },
                    {
                        "id": 124,
                        "name": "user2",
                        "message": "Unmerged user2 <[email protected]> from primary_user <[email protected]>"
                    }
                ],
                "primary_user": {
                    "id": 456,
                    "name": "primary_user"
                }
            }

        Example:

            curl -X POST https://rt.example.com/REST/2.0/user/456/unmerge \
                 -H "Authorization: token YOUR_TOKEN" \
                 -H "Content-Type: application/json" \
                 -d '{}'

    *   Unmerge a specific user

        When called with a User parameter, this will unmerge only the
        specified secondary user from the primary user.

        Request Format:

        Content-Type: application/json

            {
                "User": "secondary_user_id_or_name"
            }

        The User field can be either a user ID or username.

        Response Format (Success):

            {
                "message": "Unmerged user1 <[email protected]> from primary_user <[email protected]>",
                "unmerged_user": {
                    "id": 123,
                    "name": "user1"
                },
                "from_primary_user": {
                    "id": 456,
                    "name": "primary_user"
                }
            }

        Example:

            curl -X POST https://rt.example.com/REST/2.0/user/456/unmerge \
                 -H "Authorization: token YOUR_TOKEN" \
                 -H "Content-Type: application/json" \
                 -d '{"User": "123"}'

    Error Responses:

    All endpoints return appropriate HTTP status codes and JSON error
    messages:

    *   400 Bad Request - Invalid parameters or merge/unmerge operation
        failed

    *   403 Forbidden - User lacks AdminUsers permission

    Example error response:

        {
            "message": "User is a required field"
        }

AUTHOR
    Best Practical Solutions, LLC <[email protected]>

BUGS
    All bugs should be reported via email to

        L<[email protected]|mailto:[email protected]>

    or via the web at

        L<rt.cpan.org|http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Extension-MergeUsers>.

LICENSE AND COPYRIGHT
    This software is Copyright (c) 2014-2026 by Best Practical Solutions

    This is free software, licensed under:

      The GNU General Public License, Version 2, June 1991