NAME

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

RT VERSION

Works with RT 4.0, 4.2, 4.4, 5.0, 6.0.

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.

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 <user1@example.com> from primary_user <primary@example.com>"
        },
        {
            "id": 124,
            "name": "user2",
            "message": "Unmerged user2 <user2@example.com> from primary_user <primary@example.com>"
        }
    ],
    "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 <user1@example.com> from primary_user <primary@example.com>",
    "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"
}

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

If you are using RT 4.2 or greater, add this line:

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

For RT 4.0, add this line:

Set(@Plugins, qw(RT::Extension::MergeUsers));

or add RT::Extension::MergeUsers to your existing @Plugins line.

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:

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.
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.

AUTHOR

Best Practical Solutions, LLC <modules@bestpractical.com>

BUGS

All bugs should be reported via email to

L<bug-RT-Extension-MergeUsers@rt.cpan.org|mailto:bug-RT-Extension-MergeUsers@rt.cpan.org>

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 is free software, licensed under:

The GNU General Public License, Version 2, June 1991

To install RT::Extension::MergeUsers, copy and paste the appropriate command in to your terminal.

cpanm

cpanm RT::Extension::MergeUsers

CPAN shell

perl -MCPAN -e shell
install RT::Extension::MergeUsers

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

RT VERSION

DESCRIPTION

REST2 API

Authentication and Permissions

POST /user/{id}/merge

POST /user/{id}/unmerge

INSTALLATION

UPGRADING

UTILITIES

rt-clean-merged-users

rt-merge-users

CAVEATS

RT::Shredder and Merged Users

rt-serializer

AUTHOR

BUGS

LICENSE AND COPYRIGHT

Module Install Instructions