Rehoming

Rehoming is the process of moving a user, group, device, or subscription from one sub-domain to a different sub-domain in a multi-domain platform.

The maximum number of subscriptions (not users) in a rehome object set that can be rehomed is 10 by default. You can change this value with the subman_maximum_membership_rehome_size property. For example, if you are rehoming a user, the total number of subscriptions owned by the user plus the total number of all subscriptions in groups owned by the user that can be rehomed cannot be greater than the value specified by subman_maximum_membership_rehome_size.

Important: The maximum membership rehome size should be determined by the maximum size of all objects and the buffer size.

Rehoming Devices, Subscriptions, and Groups describes what happens when you rehome device, subscription, and group objects. Objects can be moved only between MATRIXX environments that have the same pricing and configuration. After rehoming an object, the object OID and all balances and meters have the same values as they did before rehoming.

The answer to the create_config.info question Can subscribers for this tenant be rehomed to this subdomain (y/n)? must be y to rehome subscribers for a specific tenant.

Table 1. Rehoming Devices, Subscriptions, and Groups
Object	Description
Device	The rehome object set includes the device. The device cannot belong to any subscriptions.
Subscription	The rehome object set includes the subscription, all devices owned by the subscription, and the user who is the owner of the subscription. The subscription cannot be a member of any group. The subscription can have multiple relationships with other users, but only one owner. If you rehome a subscription and the owner of that subscription is the owner of other subscriptions, the process will fail.
Group	The rehome object set includes the group, the user who is the owner of the group, all group members (including all rehome object sets for each member). The group cannot be a subgroup or have any subgroups.

Consider the following examples (a Sub is a subscription):

Example 1:
- Group1 has members Sub1, Sub2, Sub3.
- User1 is the owner of Group1.
- User2 is owner of Sub2.
When rehoming Group1, User1, User2, Group1, Sub1, Sub2 and Sub3 are rehomed.
Example 2:
- Group1 has members Sub1, Sub2, Sub3.
- User1 is the owner of Group1.
- User2 is the owner of Sub2.
- User3 has an admin role with Group1 and an owner role with Sub4.
When rehoming Group1, the operation fails because User3 is the owner of Sub4, which is outside the rehome set. If Sub4 is added as a member of Group1, the operation succeeds.
Example 3:
- Group1 has members Sub1, Sub2, Sub3.
- User1 is the owner of Group1.
- User2 is the owner of Sub2.
- User3 has an observer role with Sub3.
When rehoming Group1, the operation fails because Sub3 has a relationship with User3 which is outside of the rehome object set.
Example 4:
- Group1 has members Sub1, Sub2, Sub3.
- User1 is the owner of Group1.
- User2 is the owner of Sub2 and has an observer role with Sub3.
When rehoming Group1, the operation succeeds because Sub3 has a relationship with User2 which is part of the rehome object set. No object is outside of the rehome object set.

When you rehome a user with the owner role, the rehome object set includes the user, all subscriptions and groups which the user owns (including all rehome object sets for those subscriptions and groups). If any object in the rehome object set has a relationship with an object that is outside of the rehome object set, the operation fails. When you rehome an owner, all the owner's associated subscriptions are rehomed.

Note: When you rehome an owner of a group, all that group's subscriptions are rehomed.

Consider the following examples:

Example 1:
- User1 is the owner of Sub1 and the admin of Group1.
- Sub1 is a member of Group1.
When rehoming Group1, the operation succeeds. The rehome object set is Sub1 (member of Group1), User1 (owner of Sub1).
When rehoming User1, the operation fails. The rehome object set is Sub1 (owned by User1). Group1 is not part of the rehome object set, but Sub1 and User1 have a relationship with Group1.
Example 2:
- User1 is the owner of Sub1, Group1, and Group2.
- Sub2 and Sub3 are members of Group1.
- User2 is the owner of Sub2 and has an admin role with Group1.
When rehoming User1, the operation succeeds.
Attention: When rehoming a user, all subscriptions and groups the user owns are rehomed. When rehoming a subscription or a group, the owner is rehomed. When rehoming a group, the group owner and all member subscriptions is rehomed. User2 is rehomed because sub2 is rehomed. However, if User2 was the admin of Group1, but not the owner of Sub2, the rehome would fail.
Example 3:
- User1 is the owner of Sub1 and Group1.
- Sub2 and Sub3 are members of Group1.
- User2 is the owner of Sub2 and has an admin role with Group2.
When rehoming User1, the operation fails because Group2 is outside the rehome object set.

Attempting to rehome an object that does not comply with these restrictions results in a response with ResultCode 33 (PERMISSION_DENIED). For more information about error responses, see the discussion about rehoming error responses.

Note: MATRIXX Support recommends using the REST rehoming APIs because the REST services manage the rehoming process whereas the Java rehoming process requires multiple steps. For more information, see the discussion about rehoming REST APIs.