9.5 Copying Relationships

This section includes the following information:

9.5.1 Terminology

To enable you to understand the terminology used while describing the Copying Relationships procedure, all the commonly used terms are detailed in the following list:

Assignments: Includes both bundle and policy assignments.
Relationships: Includes both assignments and group memberships
Selected or Source Device: The device with the set of assignments and group memberships that need to be copied to other devices. The selected source object can only be a device and not a folder or group.
Target objects: The objects on which the assignments or memberships will be applied from the source device. The Target objects can only be devices, device folders, device groups or a combination of these objects.
Continue on Failure: Indicates that the operation should continue even when a copy relationships operation fails.
Terminate on Failure: Indicates that the operation should be terminated when the copy relationship operation fails.

9.5.2 Overview

As part of copying relationships, you can copy bundle assignments, policy assignments or group memberships from a selected device to target objects which includes devices, folders or groups. After the Copy Relationships operation is completed, the target object will have the assignments or memberships of the selected source device.To understand how Copy Relationships works, consider a scenario in which the selected source device S has a bundle assignment B, a policy assignment P and it belongs to a group G. You want to copy all these relationships from the selected device S to the target device T, which does not have any existing assignments and does not belong to any group. After the Copy Relationship operation is completed, the target device T will have the bundle assignment B, the policy assignment P and it will be part of group G.

9.5.3 Procedure

To perform the Copy Relationships operation:

In ZENworks Control Center, click the Devices tab.
In the Devices page, select the check box next to a device whose relationships you want to copy.

For the Copy Relationships operation, you need to select a device that has existing relationships to copy, else, the following error message is displayed:
```
The selected target object has no relationships to perform copy operation
```
Click Action > Copy Relationships.
Select the required bundles, policies, and groups that you want to copy.
Click Next.
In the Select Target Objects page, select the devices, folders, or groups to which you want to copy the relationships. If you select a folder or a group, the relationships, by default, are copied only to the objects within the folder or the group.

For more information, see Section 9.5.6, Selecting the Target Object
Select Continue on Failure to continue with the operation even if some relationships fail to get copied to the target objects.

For more information on this option, see Section 9.5.5, Handling Failures.
Select the relevant Direct Assignment Options to copy relationships when the target devices are members of a folder or members of a group. The options include:
1. Copy selected assignments to members of the target groups: If you select this option, the relationships will be copied to the devices within the selected target groups.
2. Copy selected assignments to objects inside the target folder: If you select this option, the relationships will be copied to the devices within the selected target folders. The assignments will not be copied to the sub folders and their contents.
3. Copy selected assignments to objects inside the target folders and its subfolders: If you this option, the relationships will be copied to the devices within the sub-folders of the selected target folders.
NOTE:For more information on these options, see Section 9.5.6, Selecting the Target Object.
(Applicable only for assignments and not groups) Select the relevant Conflict Resolution Options to resolve the conflicts that might arise due to a conflict between the existing assignments of the target device and that of the selected device. The options include:
1. Retain the conflicting assignments on the target devices: If you select this option, the existing assignments of the target device that are in conflict with the selected assignments of the source device, will be retained and the conflicted source assignments will not be copied on the target device.
2. Delete all existing assignments on the target devices: If you select this option, the existing assignments of the target device will be deleted and the selected assignments of the source device will be copied to the target devices.
3. Replace the conflicting assignments on the target devices: If you select this option, the existing assignments of the target device that are in conflict with the selected assignments of the source device, will be replaced with the source assignments.
NOTE:For more information on the Conflict Resolution options, see Section 9.5.7, Resolving Conflicts.
Group Membership Options allow you to:
- Add objects inside the target folders and their subfolders as members of the selected groups: If the target objects have groups, then all the members of the groups will be added to the selected group and if the target devices have folders, then all the devices within the folders will be added to the selected group, recursively.
- Delete all existing group memberships of the target devices: Deletes all the group memberships of the target devices.
  
  For more information on the group membership options, see Section 9.5.8, Copying Groups.
NOTE:
- If the target group B has b1, b2, and b3 as members and if the selected source device is a part of group A. You cannot add group B to group A. However you can add b1, b2 and b3 as members of group A.
- If a target folder has a group inside it, the group will not be considered for copy relationships. If you want to copy relationship to that group, it needs to be included explicitly as a target. This is to avoid accidentally making assignments to unintended devices.
- If the selected device is not a member of any group, the Group Membership Option will not be available on this page.
Click Next to display the Summary page. In the Summary page, review the information, if required, use the Back button to make changes to the configured settings, else Click Finish. The Copy Relationships operation is performed and the results are displayed.

9.5.4 Understanding the Results

The Copy Relationships Results page confirms the completion of the Copy Relationship operation and displays the relevant results:

Success: Indicates that all the copy relationship operations were completed successfully.
Partial Success: Indicates that only some of the copy relationship operations were completed successfully and the rest failed.
Failure: Indicates that all the copy relationship operations failed.

This page displays the following information for each Copy Relationships operation that was performed on the target devices. Review the information and then click OK.

NOTE:To export the results of the copy relationships operation as a CSV file, click Export as CSV. For more information on this option, see Section 9.5.9, Exporting the Copy Relationship Results as a CSV File.

Bundle Assignments pane: Provides the following information:
- Bundle: The name of the bundle that was selected on the source device.
- Device: The target device to which the bundle was copied.
- Operation: Status of the Copy Relationships operation. The status information is displayed using the following icons:
  - : Indicates that the bundle is assigned to the target device.
  - : Indicates that the bundle is unassigned from the target device.
  - : Indicates that the Copy Relationships operation could not be completed due to an error.
- Details: Displays information related to the status of the Copy Relationships operation. If there was an error, additional details related to the error are displayed.
Policy Assignments pane: Provides the following information:
- Policy: The name of the policy that was selected on the source device.
- Device: The target device to which the policy was copied.
- Operation: Status of the Copy Relationships operation. The status information is displayed using the following icons:
  - : Indicates that the policy is assigned to the target device.
  - : Indicates that the policy is un-assigned from the target device.
  - : Indicates that the Copy Relationships operation could not be completed due to an error.
- Details: Displays information related to the status of the Copy Relationships operation. If there was an error, additional details related to the error are displayed.
Group Memberships pane: Provides the following information:
- Group: The name of the group to which the target devices are added.
- Member: The target devices that are added as members to the selected group.
- Operation: Status of the Copy Relationships operation. The status information is displayed using the following icons:
  - : Indicates that the target devices are added to the selected group.
  - : Indicates that the target devices are removed from the selected group.
  - : Indicates that the Copy Relationships operation could not be completed due to an error.
- Details: Displays information related to the status of the Copy Relationships operation. If there was an error, additional details related to the error are displayed. If the error is a “Dependency Error”, it indicates that the Continue on failure option was not selected and that the operation has failed because you do not have rights on some objects. For more information, see Section 9.5.9, Exporting the Copy Relationship Results as a CSV File

9.5.5 Handling Failures

As part of the Copy Relationships operation, when bundles and policies cannot be assigned or unassigned and when group memberships cannot be added or removed from the target objects, it is considered as a failure of the operation. This section provides more information on:

Reasons for Failures

Reasons for the failure of the Copy Relationships operation include administrator having inadequate rights to the involved objects, database related issues, and missing objects. Hence, to minimize failures, it is useful to first understand the following:

Required Rights

To perform the Copy Relationships operation, you need the following rights on the objects involved in the procedure:

For assignments: You need the Assign Bundles and Assign Policies rights on the target objects to successfully copy bundle or policy assignments respectively
For groups: You need the Modify Group Membership rights on all the objects involved in the Copy Relationships procedure. Consider a scenario in which the source device is part of group SG1, and the target device is part of group TG1, and you have selected the Delete all existing group memberships of the target devices option with the expectation that the target device will be added to SG1 and removed from TG1. In this case, you need the Modify Group Membership right on the target device (to add the device to another group), TG1 (to remove the device from this group) and SG1 (to add the device to this group). As rights cannot be given to the individual device, it should be given to the folder that contains the device.

NOTE:If you do not have the required rights on all the involved objects, the Copy Relationships operation will fail.

Transaction Boundary

The Transaction Boundary is defined with respect to the target object and the relationship type that is being copied.

While copying bundles or policies to a target folder, if the assignment is made to the folder, the number of transactions is two. This includes the bundles to target folder assignment and the policies to the target folder assignment. If you only copy the bundles, then the number of transactions is one.

If you copy bundles and policies to the members of a target folder, then the number of transactions is 2 times (one for bundles and one for policies) the number of members inside the target folder. If the target folder has devices A, B, C, then the number of transactions will be 6.

Transaction Boundary can be further explained with the following example:

Example

Scenario: The target folder has devices D1, D2 and a sub folder SF1. The sub folder SF1 contains three devices SFD1, SFD2, and SFD3.
Transaction Boundary Calculation:
- If the bundle assignment is made to the parent folder F, then the number of transactions is 1.
  
  NOTE:Bundle assignments can include one or more bundles.
- If the bundle assignment is made to the members of the parent folder F, then the number of transactions is 2, which includes the assignments to devices D1 and D2.
- If the assignment is made recursively to all the members of the parent folder F, then the number of transactions is 5, which includes the assignments to devices D1, D2, SFD1, SFD2, and SFD3.
  
  If policies are also copied, the number of transactions are doubled.

Operation Modes

Copy Relationships can be performed in the following two modes:

Terminate on Failure

The Copy Relationship operation will be performed in transactions. A transaction will succeed ONLY if you have rights on all the objects involved in the transaction boundary. In case you do not have rights on any of the objects involved in a transaction boundary, the complete transaction will fail.

For example, if you try to copy 10 bundles and 5 policies to a target T1, and you do not have rights on one bundle. In this case, the entire bundle assignment will be fail. However, the entire policy assignment will succeed. This is the default behavior.

Continue on Failure

If you do not have rights on all the objects, the operations related to the objects on which you have rights, will succeed. The remaining will fail. For example, if you try copying 10 bundles and 5 policies to a target T1, and you do not have rights on one bundle. When this option is selected, the 9 bundles will be assigned to the target and all the policies will be assigned to the target. Only one bundle assignment will fail.

9.5.6 Selecting the Target Object

The target object can be a device or a group or a folder. When the target is a device, the steps are straight forward. However, if the target is a group or a folder, when you copy the assignments, there are multiple options to determine to which object the assignment has to be made:

When the Target is a Folder

When the target is a folder, you can chose to make the assignments to only the devices within the target folder or you can choose to make the assignments to the devices within the target folder and its sub folders as well. Consider the following scenario for additional clarity on these options:

Scenario: The target folder F contains a device T1, and a sub folder SF1, which contains a device T2.

Copy selected assignments to objects inside the target folder: All the members of the target folder will get the selected assignments as direct assignments. This procedure will not be done recursively. Based on the scenario above, if this option is selected, the assignment will be made to the device T1 within the target folder and not to the device T2 within its sub folder.
Copy selected assignments to objects inside the target folders and its subfolders: All the devices within the target folder and its sub folders will get the assignment. Based on the above scenario, if this option is selected, the assignment will be made to devices T1 and T2.
If neither of the above two options are selected, then, by default, the assignment will be made to the target folder and all the members of the folder will get the assignment as inherited assignments. Based on the above scenario, the devices T1 and T2 will receive the assignments as inherited assignments.

When the Target is a Group

If the target is a group, then the assignments can be made using the following options:

Copy selected assignments to members of the target groups: The assignment will be copied to all the members of the target group.
If the above option is not selected, then, by default, the assignment will be made to the group. All the members of the group will get the assignments as inherited assignments.

NOTE:A device group can ONLY contain devices. Folders and groups cannot be a part of device groups.

9.5.7 Resolving Conflicts

When the target device has relationships that are also present on the source device, a conflict might arise. Using the Conflict Resolution Options, you can resolves these conflicts. To understand these option better, consider the following scenario: Bundles B1, B2, and B3 are assigned to the Target device and B3 has a weekly launch schedule. Bundle B3, having a daily launch schedule, and bundle B4 are assigned to the source device. As bundle B3 exists on the source and the target devices, it will cause a conflict. To resolve the conflict you can use one of the following options:

Delete existing assignments on the target devices

If this option is selected, all the assignments on the target device will be deleted and the selected source assignments will be copied to the target device. Based on the scenario described above, bundles B1 and B2 and B3 (Weekly Schedule) will be removed from the target device, and B3 (Daily Schedule) and B4 will be assigned to the target device. Hence, the final assignment list will include B3 (Daily Schedule) and B4. The bundle assignment, B1 and B2, will be removed. This option is only applicable for assignments.

Replace existing assignments on the target devices

If this option is selected, the existing assignments on the target device T that are not in conflict with assignments on the source device, will be retained and the assignments that are in conflict with the assignments on the source device will get replaced with the source assignments. Based on the scenario described above, bundle B3 (Weekly Schedule) will be replaced by bundle B3 (Daily Schedule), bundles B1 and B2 will be retained and. bundle B4 will be added. This option is only applicable for assignments.

Retain the conflicting assignments on the target devices

If this option is selected, all the assignments on the target device will be retained and only the bundles from the source device that are not in conflict with the bundles on the target device, will get assigned to the target device. Based on the scenario described above, B1, B2 and B3 (Weekly Schedule) will be retained on the target device and B4 will be assigned to the target device. However B3 (Daily Schedule) will not be assigned to the target device as this bundle is in conflict with B3 (Weekly Schedule), which is already assigned to the target device. Hence, the final assignment list will include B1, B2, B3 (Weekly Schedule) and B4.

9.5.8 Copying Groups

For more clarity on the Copying Group options, consider the following two scenarios:

Scenario 1: The selected source device S is a member of group G and the target device T is a member of a group G1.
Scenario 2: The selected source device S is a member of Group G and the target device T is a member of group G and G1.

Based on the above scenarios, you can use the following conflict resolution options:

Delete all existing group memberships of the target devices: If this option is selected:
- In Scenario 1: As the target device T is part of group G1, at the end of the Copy Relationships operation, the target device T will be a part of group G. The group membership of this device from group G1 will be removed.
- In Scenario 2: At the end of the Copy Relationships operation, the target device will only be part of Group G. G1 will be removed and, as the device is already part of G, it will be skipped.
Default Behavior (if the above option is not selected):
- In Scenario 1: The target device will be part of both groups G and G1. The displayed result will indicate that G is an added group assignment.
- In Scenario 2: The target device will be part of both groups, G and G1. The displayed result will indicate that G is an unchanged group assignment.

9.5.9 Exporting the Copy Relationship Results as a CSV File

The results of Copy Relationships operation can be exported as a CSV file from the Results page. The CSV file includes the following fields:

Assignment Type: The assignment type that is copied from the source to the target object. Indicates if the assignment is a Bundle, Policy, or Group.
Assignment Object: The name of the assignment of the source device that is getting assigned to the target device. Indicates the name of the bundle, policy or group.
Device: The target device that is receiving the selected source assignment.
Source Object GUID: The GUID of the selected source object.
Target Object GUID: The GUID of the target object.
Operation: The status of the assignment. Indicates if the assignment to the target device got Assigned, Unassigned or it Failed.
Error Message: In case of any failures, the reason for the failure will be displayed in this field. If a “Dependency Error” is displayed, it indicates that the Continue on failure option was not selected and that the operation has failed because you do not have rights on some objects.

Consider a scenario in which the source device S has bundle assignments SB1 and SB2 and target device T doesn't have any assignments. The administrator has rights only on bundle SB1. When the Copy Relationships operation is performed without selecting the Configure on Failure option, assignment SB2 fails with an Insufficient Rights error, and assignment SB1 fails with a Dependency error because another assignment failed in the transaction. For more information on transactions, see Transaction Boundary.Consider another scenario related to groups. The source device S is a part of group SG1 and the target device T is a part of groups TG1 and TG2. The administrator does not have rights on device TG2 and the administrator has chosen the Delete existing group membership option. When the Copy Relationships operation is performed, the removal of device T from the group TG2 will fail with the Insufficient Rights error and, the addition of device T to group SG1, and removal of device T from group TG1 will fail with the Dependency error. So, the Dependency errors are not due to insufficient rights. They occur due to the failure of some other operation within the transaction. Hence, if the administrator wants to correct the problems by reviewing the results, the administrator should resolve errors other than the Dependency errors.

9.5.10 Using zman to Copy Relationships

The Copy Relationships operation can be performed using zman commands as well. For more information, see the zman wcr and zman scr commands in the ZENworks Command Line Utilities Reference.