Rehoming

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. It should not be too large of a value.

Table 1 describes what happens when you rehome device, subscription, and group objects

Note: 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 will have the same values as they did before rehoming.

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 will fail because User 3 is the owner of Sub4, which is outside the rehome set. If Sub4 is added as a member of Group1, the operation will succeed.
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 will fail 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 will succeed 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 will fail. 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 will succeed. The rehome object set is Sub1 (member of Group1), User1 (owner of Sub1).
When rehoming User1, the operation will fail. 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 will succeed.
Remember, when rehoming a user, all subscribers and groups the user owns will be rehomed. When rehoming a subscription or a group, the owner will be rehomed. When rehoming a group, the group owner and all member subscriptions will be rehomed. User2 will be 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 will fail 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 Rehoming Error Responses.

Note: MATRIXX recommends using the REST rehoming APIs because the REST services manage the rehoming process whereas the Java rehoming process requires multiple steps.

REST Rehoming APIs

The following APIs rehome devices, groups, and subscriptions.

PUT /device/{query:.+}/rehome/{destination}
PUT /group/{query:.+}/rehome/{destination}
PUT /subscription/{query:.+}/rehome/{destination}
PUT /user/{query:.+}/rehome/{destination}

In addition to the rehoming APIs, the REST subDomains service returns a list of configured sub-domains. For more information, see the REST service APIs.

Java Rehoming Process

The rehoming process involves the following steps:

Start the rehoming process on the source engine using one of the following APIs.
- MtxRequestSubscriberRehomePrepare
- MtxRequestGroupRehomePrepare
- MtxRequestDeviceRehomePrepare
- MtxRequestUserRehomePrepare
For example, call MtxRequestObjectRehomePrepare (where Object is Subscriber, Group, User, or Device) to do the following:
- Collect all Object-related objects.
- Quarantine all objects.
  Routing information associated with quarantined objects is removed from the routing cache.
- Return Object information.
  All Object information is returned in MtxResponseRehome.
Create the Object on the target engine.
Call MtxRequestDatabaseRehome to do the following:
- Use the MtxResponseRehome information from the source engine and create the objects on the target engine.
  Note: When rehoming to the target sub-domain, the routing cache is updated to reflect the changes.
Clean up the information on the source engine.
Call MtxRequestDatabaseRehomeCommit to do the following:
- Delete the quarantined objects on the source engine.

Important: Do not call MtxRequestDatabaseRehomeCommit until you have confirmed that the rehomed objects were created on the target engine.

If rehoming is unsuccessful, call MtxRequestDatabaseRehomeRollback to do the following:

Re-associate routing information with quarantined objects in the routing cache.
Remove all objects from quarantine on the source engine.
Commit the changes to the Subscriber database.

Rehoming Error Responses

Table 2 lists the ResultText included in the response if you try to rehome an object that does not comply with the documented restrictions. The ResultText includes the object ID (OID), represented here as #:#:#:# (for example, OID=1:3:5:7).

Table 2. Rehoming Error Responses
Object	Restriction	ResultText
Subscriber	The subscription is a member of a group.	Subscriber with OID=#:#:#:# may not be rehomed because it is an member of a group.
	The subscription is an administrator of a group.	Subscriber with OID=#:#:#:# may not be rehomed because it is an administrator of a group.
	All users that have a relationship with the subscription must be in the set of objects to rehome.	Subscriber #:#:#:# has relationship with user #:#:#:#, which is not part of rehome object set.
Group	The group is a member of another group.	Group with OID=#:#:#:# may not be rehomed because it is a member of another group.
	The group has sub-groups.	Group with OID=#:#:#:# may not be rehomed because it has sub-groups.
	The group has more than 10 subscriptions or administrators.	Group with OID=#:#:#:# may not be rehomed because it has more than the allowed number of subscribers/admins.
	All users that have a relationship with the group must be in the set of objects to rehome.	Group #:#:#:# has relationship with user #:#:#:#, which is not part of rehome object set.
	The group can not be a subgroup of another group.
	The group cannot have a subgroup.
	A group administrator must be a member of the group.
Device	The device belongs to a subscription.	Device with OID=#:#:#:# may not be rehomed because it belongs to a subscriber.
User	All groups that have a relationship with the user must be in the set of objects to rehome.	User #:#:#:# has relationship with group #:#:#:#, which is not part of rehome object set.
User	All subscriptions that have a relationship with the user must be in the set of objects to rehome.	User #:#:#:# has relationship with subscriber #:#:#:#, which is not part of rehome object set.