Merge-CsLegacyTopology

 

Topic Last Modified: 2012-03-23

Merge-CsLegacyTopology enables you to migrate topology information from Microsoft Office Communications Server 2007 R2 or Microsoft Office Communications Server 2007 to Microsoft Lync Server 2010. This helps provide interoperability between Lync Server 2010 and earlier versions of the software.

Syntax

Merge-CsLegacyTopology -TopologyXmlFileName <String> [-UserInputFileName <String>] [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-Report <String>] [-WhatIf [<SwitchParameter>]]

Merge-CsLegacyTopology -Reserved <PSObject> [-UserInputFileName <String>] [-Confirm [<SwitchParameter>]] [-Force <SwitchParameter>] [-Report <String>] [-WhatIf [<SwitchParameter>]]

Detailed Description

The Merge-CsLegacyTopology cmdlet is the first tool to use when migrating from an earlier version of Office Communications Server (either Office Communications Server 2007 R2 or Office Communications Server 2007) to Lync Server 2010. Merge-CsLegacyTopology is used to migrate trusted service entries and topology information for the following components: domains, user services, Registrar, Mediation Server, and Edge Server. In addition, the cmdlet migrates trusted service entries for the Conferencing Attendant application; Communicator Web Access; and conferencing directories. (A trusted service entry is an Active Directory record that represents a server trusted by Lync Server.) Merging the topology information enables users homed on Lync Server to communicate with users homed on Communications Server 2007 or Communications Server 2007 R2.

Before you can run Merge-CsLegacyTopology, you must first install the Windows Management Instrumentation (WMI) Backward Compatibility interfaces package; this application is installed by running OCSWMIBC.msi. (OCSWMIBC.msi can be found on the installation DVD in the Setup.) After installing the Compatibility interfaces package, Merge-CsLegacyTopology can then be called. Merge-CsLegacyTopology will use WMI to read legacy data from the earlier version of Office Communications Server; it will then take the retrieved data and create corresponding objects in Lync Server. For example, for each SIP domain found in your installation of Office Communications Server, a corresponding SIP domain will be created in your new installation of Lync Server.

After running Merge-CsLegacyTopology, you should then run the cmdlets Import-CsLegacyConfiguration and Import-CsLegacyConferenceDirectory.

The Merge-CsLegacyTopology cmdlet needs to be run at least twice: once at the start of a migration (in order to introduce the Communications Server 2007 or Communications Server 2007 R2 topology), and once at the end of migration, when the previous Office Communications Server environment has been decommissioned. You will also need to run the cmdlet any time you make a change to your legacy Office Communications Server environment. For example, if you add a Mediation Server to or decommission a pool from your Office Communications Server topology, you will need to re-run Merge-CsLegacyTopology in order to import the modified topology.

The cmdlets Import-CsLegacyConfiguration and Import-CsLegacyConferenceDirectory depend on values configured by Merge-CsLegacyTopology. That means that you might receive error messages from either Import-CsLegacyConfiguration or Import-CsLegacyConferenceDirectory that instruct you to run Merge-CsLegacyTopology as a possible solution to the problem that just occurred. If you do not re-run Merge-CsLegacyTopology, then additional errors can occur, especially if an item is removed from the Office Communications Server environment while it is still in use by Lync Server.

If you need to merge Edge Servers from a previous installation of Office Communications Server you must first create a custom XML file that contains your Edge Server; you must create the file yourself because Edge Server settings are not stored in Active Directory, and, as a result, cannot be retrieved by Merge-CsLegacyTopology. After you have created this XML file (see the Microsoft Lync Server 2010 Deployment Guide for information on how to create this file) you must include the path to that file and the UserInputFileName parameter when running Merge-CsLegacyTopology. If you do not do this no Edge Servers will be included in your merged topology.

Who can run this cmdlet: By default, members of the following groups are authorized to run the Merge-CsLegacyTopology cmdlet locally: RTCUniversalServerAdmins. To return a list of all the role-based access control (RBAC) roles this cmdlet has been assigned to (including any custom RBAC roles you have created yourself), run the following command from the Windows PowerShell prompt:

Get-CsAdminRole | Where-Object {$_.Cmdlets –match "Merge-CsLegacyTopology"}

Parameters

Parameter Required Type Description

TopologyXmlFileName

Required

String

Path to the output file to be created when Merge-CsLegacyTopology is run. Note that this file differs from the file specified using the Report parameter; the latter file is used for recording error information while the Topology XML file contains your newly created Lync Server topology. This file will later be used to publish the new topology.

If the specified file already exists, it will be overwritten when you run Merge-CsLegacyTopology.

UserInputFileName

Optional

String

Path to the XML file used to import Edge Server data from an earlier version of Office Communications Server. This XML file (which you must create following the guidelines detailed in the Lync Server 2010 Deployment Guide) is required because Edge Server settings are not stored in Active Directory Domain Services (AD DS). If you do not need to import Edge Server information, then this parameter can be omitted.

If this parameter is not used, remote and external access features (including federation) might not function as expected in an environment running both Communications Server 2007 R2 or Communications Server 2007 R2 and Lync Server.

Force

Optional

Switch Parameter

Suppresses the display of any non-fatal error message that might occur when running the command.

Report

Optional

String

Enables you to specify a file path for the log file created when the cmdlet runs. For example: -Report "C:\Logs\MergeTopology.html"

Reserved

Optional

PS topology object

Enables you to merge the topology using a topology object instead of a topology XML file.

WhatIf

Optional

Switch Parameter

Describes what would happen if you executed the command without actually executing the command.

Confirm

Optional

Switch Parameter

Prompts you for confirmation before executing the command.

Input Types

None. Merge-CsLegacyTopology does not accept pipelined input.

Return Types

Merge-CsLegacyTopology does not return any objects or values.

Example

-------------------------- Example 1 ------------------------

Merge-CsLegacyTopology -TopologyXmlFileName C:\New_Topology.xml

The command shown in Example 1 merges topology information and trusted service entries from Communications Server 2007 R2 or Communications Server 2007 with a new installation of Lync Server. The required parameter TopologyXmlFileName is used to indicate the path to the output file generated when you run Merge-CsLegacyTopology.

-------------------------- Example 2 ------------------------

Merge-CsLegacyTopology -TopologyXmlFileName C:\New_Topology.xml -UserInputFileName C:\EdgeServers.xml

Example 2 is a variation of the command used in Example 1. In Example 2, however, the UserInputFileName parameter is included in order to merge Edge Server information into the topology. The parameter value C:\EdgeServers.xml points to a custom XML file containing Edge Server information for Office Communications Server.