powershell administrator guide -...

2.1Quest® MigratorFOR SAMETIME

PowerShell Administrator Guide

© 2013 Quest Software, Inc. ALL RIGHTS RESERVED.This guide contains proprietary information protected by copyright. The software described in this guide is furnished under a software license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of the applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording for any purpose other than the purchaser's personal use without the written permission of Quest Software, Inc.

If you have any questions regarding your potential use of this material, contact:

Quest Software World HeadquartersLEGAL Dept5 Polaris WayAliso Viejo, CA 92656 USAwww.quest.comemail: [email protected]

Refer to our Web site for regional and international office information.

TRADEMARKSQuest, Quest Software, the Quest Software logo, and Spotlight are trademarks and registered trademarks of Quest Software, Inc. For a complete list of Quest Software's trademarks, please see http://www.quest.com/legal/trademark-information.aspx. All other trademarks and registered trademarks used in this guide are property of their respective owners.

DisclaimerThe information in this document is provided in connection with Quest products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Quest products. EXCEPT AS SET FORTH IN QUEST'S TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, QUEST ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL QUEST BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF QUEST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Quest makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Quest does not make any commitment to update the information contained in this document.

Third Party ContributionsMigrator for Sametime 2.1 contains some third party components (listed below). Copies of their licenses may be found on our website at http://www.quest.com/legal/third-party-licenses.aspx.

Quest Migrator for Sametime PowerShell Administrator GuideUpdated - September 2013Software Version - 2.1

Documentation ID 263

COMPONENT LICENSE OR ACKNOWLEDGEMENT

Zlib zlib 1.2.3

http://www.quest.com/

mailto:[email protected]

http://www.quest.com/legal/third-party-licenses.aspx

http://www.quest.com/legal/trademark-information.aspx

http://www.quest.com/legal/trademark-information.aspx

CONTENTS

ABOUT THIS GUIDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IV

CHAPTER 1INTRODUCING THE QUEST® MIGRATOR FOR SAMETIME SHELL . . . . 5

ABOUT MICROSOFT WINDOWS POWERSHELL . . . . . . . . . . . . . . 6INSTALLING MICROSOFT WINDOWS POWERSHELL . . . . . . . . 6

WINDOWS POWERSHELL CMDLETS. . . . . . . . . . . . . . . . . . 6

GETTING HELP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

ABOUT MIGRATOR FOR SAMETIME . . . . . . . . . . . . . . . . . . . . 7INSTALLING MIGRATOR FOR SAMETIME . . . . . . . . . . . . . . . 8

OPENING MIGRATOR FOR SAMETIME SHELL . . . . . . . . . . . . 8

CHAPTER 2POWERGUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

ABOUT POWERGUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10USING POWERGUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

ENTERING VALUES TO PARAMETERS . . . . . . . . . . . . . . . . .11

CUSTOMIZING ACTIONS . . . . . . . . . . . . . . . . . . . . . . . .11

FINDING ERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

CHAPTER 3MIGRATOR FOR SAMETIME SHELL CMDLETS . . . . . . . . . . . . . . . . 13

ABOUT MIGRATOR FOR SAMETIME CMDLETS . . . . . . . . . . . . . . .14MIGRATOR FOR SAMETIME CMDLETS. . . . . . . . . . . . . . . . . . . .14

NEW-QMSTPROJECT . . . . . . . . . . . . . . . . . . . . . . . . . .15

UPDATE-QMSTPROJECT . . . . . . . . . . . . . . . . . . . . . . . .16

GET-QMSTPROJECT. . . . . . . . . . . . . . . . . . . . . . . . . . .18

REMOVE-QMSTPROJECT . . . . . . . . . . . . . . . . . . . . . . . .18

SET-QMSTUSERMAPPING . . . . . . . . . . . . . . . . . . . . . . .19

CLEAR-QMSTUSERMAPPING . . . . . . . . . . . . . . . . . . . . . .21

GET-QMSTOCSPOOL . . . . . . . . . . . . . . . . . . . . . . . . . .22

ENABLE-QMSTUSER . . . . . . . . . . . . . . . . . . . . . . . . . .23

ADD-QMSTCONTACTLIST . . . . . . . . . . . . . . . . . . . . . . .25

MOVE-QMSTCONTACTLIST . . . . . . . . . . . . . . . . . . . . . .28

iii

Quest Migrator for Sametime

IMPORT-QMSTMESSAGELOG . . . . . . . . . . . . . . . . . . . . .29

EXPORT-QMSTMESSAGELOG . . . . . . . . . . . . . . . . . . . . .30

CONVERTFROM-QMSTXML . . . . . . . . . . . . . . . . . . . . . . .31

CONVERTTO-QMSTXML . . . . . . . . . . . . . . . . . . . . . . . .32

SHOW-QMSTLICENSE . . . . . . . . . . . . . . . . . . . . . . . . .33

UPDATE-QMSTLICENSE. . . . . . . . . . . . . . . . . . . . . . . . .33

COMMON PARAMETERS . . . . . . . . . . . . . . . . . . . . . . . . .34

CHAPTER 4POWERSHELL SAMPLE SCRIPTS . . . . . . . . . . . . . . . . . . . . . . . . 37

ABOUT SAMPLE SCRIPTS. . . . . . . . . . . . . . . . . . . . . . . . . . .38LIST OF SAMPLE SCRIPTS . . . . . . . . . . . . . . . . . . . . . . .38

ABOUT QUEST SOFTWARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

CONTACTING QUEST SOFTWARE . . . . . . . . . . . . . . . . . . . . . .41CONTACTING QUEST SUPPORT . . . . . . . . . . . . . . . . . . . . . . .41

About This GuideThis document has been prepared to assist you in becoming familiar with the Quest® Migrator for Sametime. The PowerShell Administrator Guide contains the information required to launch and use Migrator for Sametime. It is intended for network administrators, consultants, analysts, and any other IT professionals using the product.

iv

1

Introducing the Quest® Migrator for Sametime Shell

• About Microsoft Windows PowerShell

• About Migrator for Sametime


About Microsoft Windows PowerShellMicrosoft Windows PowerShell is a Windows command-line shell and scripting language designed specifically for system administrators and built on top of the Microsoft .NET Framework. Windows PowerShell can be installed on Windows XP, Windows Vista, and Windows Server 2003, and is included with Windows 7 and Windows Server 2008.

Installing Microsoft Windows PowerShell

For information on how to download and install Microsoft Windows PowerShell, see Microsoft Knowledge Base article 926139, Windows PowerShell 1.0 English Language Installation Packages for Windows Server 2003 and for Windows XP, http://support.microsoft.com/?kbid=926139.

Windows PowerShell Cmdlets

Windows PowerShell uses cmdlets: simple, single-function commands that manipulate objects and are designed to be used in combination with other cmdlets. Quest Migrator for Sametime comes with Windows PowerShell cmdlets that you can use to create and manage migration jobs.

If you already had Windows PowerShell installed on your computer before you installed Quest Migrator for Sametime, then the Quest Migrator for Sametime Windows PowerShell cmdlets were automatically installed and registered with Windows PowerShell when you installed Quest Migrator for Sametime. This means that you are ready to start using the Quest Migrator for Sametime cmdlets in Windows PowerShell.

Getting Help

Windows PowerShell help cmdlets assist you in finding the appropriate information to accomplish your task. The following table provides some examples of how to use the Get-Help and Get-Command cmdlets to access the help information that is available for each cmdlet in Migrator for Sametime Shell.

COMMAND DESCRIPTION

Get-Help Presents basic instructions on how to use the help system in Windows PowerShell, including Help for Migrator for Sametime Shell.

6

http://support.microsoft.com/?kbid=926139

Introducing the Quest® Migrator for Sametime Shell

About Migrator for Sametime IBM Lotus Sametime is used by Lotus Notes customers who require full collaboration from the Notes messaging platform.

Migrator for Sametime is an application designed to move users from a Notes Sametime environment to Microsoft Office Communications Server (OCS) 2007 or OCS 2007 R2, or Microsoft Lync Server 2010 or 2013. The following Notes Sametime products are supported:

• IBM Lotus Domino 6.5, 7.x, 8.0, or 8.5.2

• IBM Lotus Sametime 6.5, 7.5, 8.0, 8.0.2, 8.5.1 or 8.5.2

• IBM Lotus Notes 6.5, 7.0, 8.0, or 8.5.2

Get-Help <Cmdlet> Presents the help information for that cmdlet. For example, to retrieve the help information for the New-QmstProject cmdlet, use the following command:

• Get-Help New-QmstProject

Get-Command Lists all the cmdlets that are available to the shell. You can use the Get-Command cmdlet with the Format-List or Format-Table cmdlet to provide a more readable display.

For example, use Get-Command | Format-List to display the output in a list format.

Get-Command <Cmdlet> Presents information about the parameters and other components of that cmdlet. The <Cmdlet> entry allows for wildcard character expansion. For example, to retrieve information about the cmdlets with the names ending in Member, you can use the following command:

• Get-Command *Member

Get-Command -Noun <CmdletNoun>

Lists all the cmdlets with the names that include the specified noun. <CmdletNoun> allows for wildcard character expansion. Thus, you can use the following command to list all the cmdlets provided by Migrator for Sametime Shell:

• Get-Command -Noun QA*

COMMAND DESCRIPTION

7


Microsoft offers OCS/Lync Server to support unified communication throughout its technology. If you are migrating from Sametime to OCS/Lync Server, you can use Migrator for Sametime to offer a more direct transition where functionality will not be lost when transitioning to a new platform.

Migrator for Sametime allows administrators complete control over the entire migration, and have up-to-the-minute status on the migration progress.

When you migrate a Sametime user to OCS/Lync Server, you can also migrate a user’s buddy list. This lets you retain the users’ contacts. The user and the buddy list will be enabled in OCS/Lync Server, so the user can communicate with their contacts via Microsoft Office Communicator/Lync Client.

Installing Migrator for SametimeFor a list of installation requirements, see the Quest Migrator for Sametime Quick Start Guide.

Opening Migrator for Sametime ShellUse one of the following procedures to load the Migrator for Sametime Shell snap-in into Windows PowerShell. If you do not load the Migrator for Sametime Shell snap-in before you run a command (cmdlet) provided by that snap-in, you will receive an error.

To open Migrator for Sametime Shell from the Programs menu

• Select Start | Programs | Quest Software | Migrator for Sametime | Migrator for Sametime Shell.

To add the Migrator for Sametime Shell snap-in from Windows PowerShell

1. Select Start | Programs | Windows PowerShell 1.0 | Windows PowerShell.

2. At the Windows PowerShell prompt, enter the following command:

Add-PSSnapin Quest.Migrator.SametimetoOCS

Upon the shell start, the console displays a message stating that a certain file published by Quest Software is not trusted on your system. This security message indicates that the certificate the file is digitally signed with is not trusted on your computer, so the console requires you to enable trust for the certificate issuer before the file can be run. Press either R (Run once) or A (Always run). To prevent this message from appearing in the future, it is advisable to choose the second option (A).

8

2

PowerGUI

• About PowerGUI

• Using PowerGUI


About PowerGUIPowerGUI is an extensible graphical administrative console for managing systems based on Windows PowerShell. These include Windows OS (XP, 2003, Vista), Exchange 2007, Operations Manager 2007, and other new systems from Microsoft. This tool provides the rich capabilities of Windows PowerShell in a familiar and intuitive GUI console.

For more information about PowerGUI, go to www.powergui.org.

For information on installing PowerGUI, see the Quest Migrator for Sametime Quick Start Guide.

Using PowerGUIWhen you open PowerGUI and select the Migrator for Sametime PowerPack, you can use the Actions pane to perform such functions as creating a migration project, mapping Sametime users, enabling users in OCS/Lync Server, and migrating buddy lists. You can also export your results to an XML, CSV, or HTML file.

10

http://www.powergui.org

PowerGUI

Entering Values to Parameters

When you select an action in the Actions pane, the Action’s parameters dialog box opens so you can enter values for each parameter.

Customizing Actions

You can right-click an action in the Actions pane and select Properties to customize the action.

11


You can customize the script to change the name of the command, add prompts for other parameters in the command, and display the configuration properties of the action.

Finding Errors

The Messages pane at the bottom of the PowerGUI dialog box details any errors that have occurred while you performing an action or adding a value in each parameter.

12

3

Migrator for Sametime Shell Cmdlets

• About Migrator for Sametime Cmdlets

• Migrator for Sametime Cmdlets


About Migrator for Sametime Cmdlets

The Migrator for Sametime Shell command-line tools (cmdlets), like all the Windows PowerShell cmdlets, are designed to deal with objects—structured information that is more than just a string of characters appearing on the screen. The cmdlets do not use text as the basis for interaction with the system, but use an object model that is based on the Microsoft .NET platform. In contrast to traditional, text-based commands, the cmdlets do not require the use of text-processing tools to extract specific information. Rather, you can access portions of the data directly by using standard Windows PowerShell object manipulation commands.

Migrator for Sametime CmdletsThe Migrator for Sametime cmdlets include:

• “New-QmstProject” on page 15

• “Update-QmstProject” on page 16

• “Get-QmstProject” on page 18

• “Remove-QmstProject” on page 18

• “Set-QmstUserMapping” on page 19

• “Clear-QmstUserMapping” on page 21

• “Get-QmstOcsPool” on page 22

• “Enable-QmstUser” on page 23

• “Add-QmstContactList” on page 25

• “Move-QmstContactList” on page 28

• “Import-QmstMessageLog” on page 29

• “Export-QmstMessageLog” on page 30

• “ConvertFrom-QmstXml” on page 31

• “ConvertTo-QmstXml” on page 32

• “Show-QmstLicense” on page 33

• “Update-QmstLicense” on page 33

14


New-QmstProjectThe New-QmstProject cmdlet lets you create a new Migrator for Sametime project.

Syntax

New-QmstProject [-ProjectName] <String> [-ADForestName] <String> [-LotusNotesIdPath] <String> [-LotusNotesPassword] <SecureString> [-DominoServerNames <String[]>] [-SyncDb]

Parameters

Examples

Create new migration project: This creates a new migration project called “Finance Department Migration” with the AD forest, YourCompany.com, where your OCS/Lync Server is installed. The Lotus Notes ID Path and Lotus Notes Password are the location and account and password that has privileges to access the Domino servers. The NSF file, names.nsf, is located in the your-dom Domino server.

PARAMETER DESCRIPTION

ProjectName Specifies the name of the Migration Project.

ADForestName Specifies the location of your Active Directory forest where OCS/Lync Server is installed.

LotusNotesIDPath Specifies the ID file that has privileges to access your Domino servers.

LotusNotesPassword Specifies the password for the specified Notes ID File. Must be a plain text secure string.

For example, PS C:\> $password = Read-Host -asSecureString

DominoServerNames Lets you select a Domino Server to enumerate users and their properties.

You can specify either a full path to an .NSF file or the name of a remote server with the name of the .NSF file name.

For example, -DominoServerNames “c:\domino\names.nsf” or –DominoServerNames “MyDominoServer (Names.nsf)”

SyncDb See “Common Parameters” on page 34.

15


C:\PS>C:\PS>$password = Read-Host -asSecureString

C:\PS>New-QmstProject -ProjectName "Finance Department Migration" -ADForestName YourCompany.com -LotusNotesIdPath "C:\share\Admin id files\admin.id" -LotusNotesPassword $password -DominoServerNames "your-dom(names.nsf)"

Create new migration project with SyncDb switch: This example adds a local nsf file to the project and synchronizes the project with the Migrator for Sametime Database so that it can be viewed in the Migrator for Sametime Console.

C:\PS>$password = Read-Host -asSecureString

C:\PS>New-QmstProject -ProjectName "Finance Department Migration" -ADForestName YourCompany.com -LotusNotesIdPath " C:\share\Admin id files\admin.id" -LotusNotesPassword $password -DominoServerNames ‘c:\nsfFileBackup\Names.nsf’ -SyncDb

Update-QmstProjectThe Update-QmstProject lets you make changes to your existing project.

Syntax

Update-QmstProject [-InputObject] <QmstProject> [-ProjectName <String>] [-ADForestName <String>] [-LotusNotesIdPath <String>] [-LotusNotesPassword <SecureString>] [-RemoveDominoServerNames <String[]>] [-AddDominoServerNames <String[]>] [-SyncDb]

Parameters


InputObject See “Common Parameters” on page 34.

ProjectName Specifies the name of the Migration Project.

ADForestName Specifies the location of your Active Directory forest where OCS/Lync Server is installed.

LotusNotesIdPath Specifies the ID file that has privileges to access your Domino servers.

LotusNotesPassword Specifies the password for the specified Notes ID File. Must be a plain text secure string.

16


Examples

Update project name: This example lets you update the project name.

$updatedProject = get-content c:\qmstProject.xml | ConvertFrom-QmstXml | Update-QmstProject -ProjectName UpdatedTestProjectNameIn this example, the file c:\qmstProject.xml contains the previously saved QmstProject using ConvertTo-QmstXml.

Update AD location: In this example, the file c:\qmstProject.xml contains the previously saved QmstProject using ConvertTo-QmstXml. This example lets you update the Active Directory forest location.

$updatedProject = get-content c:\qmstProject.xml | ConvertFrom-QmstXml | Update-QmstProject -adforestname updated.domain.name.corp

Update project name, AD forest name, Lotus Notes ID path and Lotus Notes password, and remove current Domino Server and add a new Domino Server: This example lets you update the project name, Active Directory forest name, Lotus Notes ID path, and Lotus Notes password (secure string). It also removes the current Domino servers and adds a new one.

RemoveDominoServerNames Lets you remove an existing Domino server from the project.


For example, -RemoveDominoServerNames “c:\domino\names.nsf”

or –RemoveDominoServerNames “MyDominoServer(Names.nsf)”

AddDominoServerNames Lets you add a new Domino server to enumerate users and their properties.


For example, -AddDominoServerNames “c:\domino\names.nsf”

or –AddDominoServerNames “MyDominoServer(Names.nsf)”



17


$updatedProject = Update-QmstProject -inputobject $AValidQmstProject -projectname "UpdatedProjectName" -adforestname updated.domain.name.corp -lotusnotesidpath $validLotusNotesIdPath -lotusnotespassword $goodPassword -removeDominoServerNames "oldDominoServer(names.nsf)" -addDominoServerNames "newDominoServer(names.nsf)" –SyncDb

Get-QmstProjectThe Get-QmstProject cmdlet retrieves projects stored in the Migrator for Sametime database. To store a project in the database, use the SyncDb parameter in New-QmstProject or Update-QmstProject, or use the Migrator for Sametime Management Console to create projects.

Syntax

Get-QmstProject [[-InputObject] <String>]

Parameters

Examples

Get all projects: This example returns all projects stored in the database.

Get-QmstProject

Get specific projects: This example returns the project named “Finance Migration.”

Get-QmstProject –InputObject “Finance Migration”

Get Finance Project using wildcards: This example returns all migration projects with a project name starting with the word “Finance.”

Get-QmstProject Finance*

Remove-QmstProjectThe Remove-QmstProject cmdlet lets you delete the Qmst project stored in the database. When the project is deleted successfully, the Remove-QmstProject cmdlet returns the QmstProject that was deleted from the Migrator For Sametime database.


InputObject Specifies the name of a specific project to retrieve, or a wildcard expression to match one or more projects.

18


Syntax

Remove-QmstProject [-InputObject <QmstProject>]

Parameters

Examples

Deleting projects from the database: This example will delete myFrameworkProjects from the Migrator for Sametime database.

$myFrameworkProjects = Get-QmstProject

$myFrameworkProjects[0] | Remove-QmstProject

Set-QmstUserMappingThe Set-QmstUserMapping lets you map the Sametime users to Active Directory (AD) by using attribute matching or a Notes Migrator for Exchange database. This cmdlet also lets you manually map a single user to the matching Active Directory user.

Syntax

Set-QmstUserMapping -InputObject <QmstProject> -SearchDomains <String[]> -DominoAttributeName <String> -ADAttributeName <String> [-UserFilter <String[]>] [-OverwriteExistingMappings] [-SyncDb] [-MessageLog <String>]

Set-QmstUserMapping -InputObject <QmstProject> -SearchDomains <String[]> -NotesMigratorForExchangeDatabase <String> [-UserFilter <String[]>] [-OverwriteExistingMappings] [-SyncDb] [-MessageLog <String>]

Set-QmstUserMapping -InputObject <QmstProject> [-UserFilter <String[]>] -DominoUserDn <String> -ActiveDirectoryDn <String> [-SyncDb] [-MessageLog <String>]



19


Parameters



Note: When this parameter is specified, all users will be mapped to Active Directory.

SearchDomains Lets you enter domains to search in your AD forest.

Multiple domains can be specified delimited by commas. The domains will be searched in the order specified until a match is found.

DominoAttributeName Lets you map users from a specified Domino attribute to a matching Active Directory attribute (that you will specify in the ActiveDirectoryAttributeName parameter).

ADAttributeName Lets you specify a Active Directory attribute that matches the Domino attribute specified in the DominoAttributeName parameter.

UserFilter Note: See “Common Parameters” on page 34.

OverwriteExistingMappings Lets you overwrite mapping if mapping already exists.


MessageLog See “Common Parameters” on page 34.

NotesMigratorforExchangeDatabase

Lets you map users by entering a Notes Migrator for Exchange SQL database.

Notes Migrator for Exchange migrates user accounts, users' email, calendars, tasks, and personal address books to the users' new mailboxes on the Exchange/Exchange Online server. If you have previously migrated users to an Exchange organization in your target Active Directory forest, the data collected during the migration can be reused to map users.

For more information on Notes Migrator for Exchange, see http://www.quest.com/notes-migrator-for-exchange.

DominoUserDN Lets you specify the distinguished name (DN) of the Domino user.

ActiveDirectoryDN Lets you specify the DN of the matching Active Directory.

20

http://www.quest.com/notes-migrator-for-exchange


Examples

Map all users in the project using attribute matching: This example performs a mapping of all users previously exported. Each Domino user’s ShortName attribute is queried against the Active Directory Domain “somedomain.com” to find a user with a matching sAMAccountName attribute.

C:\PS>Set-QmstUserMapping -InputObject $project -SearchDomains somedomain.com -DominoAttributeName "ShortName" -ADAttributeName "sAMAccountName"

Create a new user mapping using Notes Migrator for Exchange: This example performs a mapping against all exported users specifying a Notes Migrator for Exchange database server which contains user mappings from a previous Notes Migration.

$mappingResult = Set-QmstUserMapping -InputObject $project -SearchDomains somedomain.com c:\projectfile.xml –NotesMigratorForExchangeDatabase NMEServer\SQLEXPRESS

Create a new User mapping for one user only: This example sets the mapping for a single user.

$project | Set-QmstUserMapping –DominoUserDn ‘cn=Test user/OU=YourCompany’ –ActiveDirectoryDn ‘CN=TestUserInAD,CN=Users,DC=ADDomain,DC=Company,DC=COM’

Clear-QmstUserMappingClear-QmstUserMapping lets you clear a user mapping for one or more users if you wish to reset the user to the initial "Mapping: Not mapped" status.

Syntax

Clear-QmstUserMapping -InputObject <QmstProject>[[-DominoServerName] <String>] [[-UserFilter] <String[]>] [-SyncDb]

Parameters



DominoServerName Lets you specify the Domino server name for users whose mappings should be cleared. Note: This parameter is optional. When specified, only the users under the specified Domino server will have their mapping cleared.

21


Examples

Clear all user mappings from existing mapping and synchronize the results to the database: This example clears all current user mappings and synchronizes the results to the database. $project represents the migration project. The user mappings previously saved to the database will be deleted.

C:\PS>$project | Clear-QmstUserMapping -SyncDb

Clear user mapping for a specific server: This example clears all mappings for users under a specified server name will be cleared.

C:\PS>$project | Clear-QmstUserMapping –DominoServerName “MyDomino(names.nsf)”

Clear user mapping for specific users: This example returns a user mapping result with mappings deleted for the specified users.

C:\PS>$project | Clear-QmstUserMapping –DominoUserNames “CN=John Doe/O=Org”,”CN=Jane Doe/O=Org”

Get-QmstOcsPoolThe Get-QmstOcsPool cmdlet retrieves the Pool information required for Enable-QmstUser.

Syntax

Get-QmstOcsPool [[-InputObject] <String>][-LyncTarget -LyncPoolFqdn <String>]

Parameters

UserFilter See “Common Parameters” on page 34.



InputObject Lets you set the input for the name of the Active Directory domain to search for OCS/Lync Server Pools.

Note: If this parameter is omitted, the cmdlet will retrieve the OCS/Lync Server Pools for the domain where the user is currently logged in.


22


Examples

Get OCS pools for the current domain: This example lets you retrieve OCS/Lync Server Pools for the current domain.

Get-QmstOcsPool

Get OCS pools for a specific Active Directory domain: This example retrieves OCS/Lync Server Pools for a specific Active Directory domain.

Get-QmstOcsPool –InputObject “mydomain”

Enable-QmstUserThe Enable-QmstUser cmdlet lets you configure users in OCS/Lync Server.

Syntax

Enable-QmstUser -InputObject <QmstProject> [-OcsPoolDn <String>] -SIPAddressFormat <String> [-SIPDomain <String>] [-EnableOptions <String[]>] [-DisableOptions <String[]>] [-UserFilter <String[]>] [-OverwriteExistingOptions] [-SyncDb] [-MessageLog <String>] [-LyncTarget -LyncTargetFqdn <String> -LyncTargetPoolFqdn <String>]

Parameters

LyncTarget Indicates a Microsoft Lync Server migration.

LyncPoolFqdn Specifies the Lync Server Pool FQDN where Remote PowerShell is enabled. (Required for a Lync Server migration.)



OcsPoolDN Lets you specify the distinguished name (DN) for the OCS pool based on the AD domain specified in Get-QmstOcsPool cmdlet. Note that this should only be specified for an OCS migration. For a Lync Server migration use LyncTargetPoolFqdn.


23


SIPAddressFormat Lets you specify a SIP Address format to migrate the users to OCS/Lync Server.

Valid values are:

• Email — the user’s email will be their SIP address

• Upn — The user’s User Principal name will be their SIP address

• First.last — The user’s SIP address will be of the form <firstname>.<lastName>@<sipDomain>

• Sam — the user’s SIP address will be of the form <sAMAccountName>@<SipDomain>

SIPDomain Must be specified if SIPAddressFormat is first.last or sam.

Note: See the SIPAddressFormat parameter for more information on first.last or sam.

EnableOptions Specifies the OCS/Lync Server settings which should be enabled. Multiple values are separated by commas. The following value can be specified for both OCS and Lync Server:

• “users” — Enable Users (Enhanced Presence)

The following values can be specified for OCS only:

• “im” — Public IM connectivity

• "archiving” — Archive internal IM conversations

• “voice” — Enterprise Voice

• “federation” — Federation

• “remote” — Remote user access

• “archivefed” — Archive federated IM conversations

DisableOptions Specifies the OCS/Lync Server settings which should be explicitly disabled. See the EnableOptions parameter for valid values.


OverwriteExistingOptions Lets you overwrite a mapping if the user is already enabled in OCS/Lync Server.






24


Examples

Enable users with email address: This example retrieves the pool information for the current domain. Next, Enable-QmstUser is run against the current project. The user's email address will be their SIP address and Enhanced Presence, Archive internal IM conversations, and Public IM connectivity will be enabled.

PS C:\> $pool = Get-QmstOcsPool

PS C:\> $currentProject | Enable-QmstUser -OcsPoolDn $pool.DistinguishedName -SIPAddressFormat email -EnableOptions users,archiving,im

Enable users and disable OCS options: This example retrieves the pool information for the current domain. Next, Enable-QmstUser is run against the current project. The SIP address format used will be <sAMAccountName>@ division.company.com. The users will have Enhanced presence enabled, but Public IM connectivity and Archive internal IM conversations will be disabled. Also, if a user has already been enabled in OCS/Lync Server, their account will be overwritten with this new information.

PS C:\> $pool = Get-QmstOcsPool

PS C:\> $currentProject | Enable-QmstUser -OcsPoolDn $pool.DistinguishedName -SIPAddressFormat sam -SIPDomain division.company.com -EnableOptions users -DisableOptions im,archiving -OverwriteExistingOptions

Add-QmstContactListThe Add-QmstContactList cmdlet creates the buddy list for the selected users, and identifies which users, if any, that may have migration issues.

Syntax

Add-QmstContactList -InputObject <QmstProject> [-SameTimeServerName] <String> [-NestedGroupOption] <String> [-LongContactGroupNamesOption] <String> [-UserContactLimit] <Int32> [-ExceededContactLimitOption] <String> [-IncludeDomains <String[]>] [-ExcludeDomains <String[]>] [-ExcludeAllExternalContacts] [-UserFilter <String []>] [-SyncDb] [-MessageLog <String>] [-LyncTarget -LyncPoolFqdn <String>]

LyncTargetPoolFqdn Lets you specify the fqdn of the Lync Server pool you are migrating users to. Must be specified for a Lync Server migration. For an OCS migration use OcsPoolDn.


25


Parameters



SametimeServerName Lets you enter the name of the Sametime server to include in the assessment.

NestedGroupOption Lets you set nested groups to become a flat list of top-level groups in OCS/Lync Server, or merged under top-level groups. Valid options are "flatten" and "merge".

LongContactGroupNamesOption Contact names in OCS/Lync Server are limited to 60 characters. If you have contact group names that exceed 60 characters, you can select to either not migrate the buddy list (an error is returned), or truncate the contact names and continue with the pre-assessment (a warning is returned).

Valid options are "truncate" and "error".

Note: If you choose to merge the nested groups, the contact group names may exceed 60 characters.

UserContactLimit Lets you specify the maximum number of contacts that will be migrated.

ExceededContactLimitOption Lets you specify what action to take if the user contact list exceeds that number set in the UserContactList parameter.

Valid options are:

• "error" - an error is returned

• "limit" - the number of contacts specified in UserContactLimit will be moved; others will be discarded

IncludeDomains Lets you specify which external SIP domains to include in the migration. Only contacts with the specified SIP domains will be migrated.

Note: If none of the following parameters are specified: IncludeDomains, ExcludeDomains, or ExcludeAllExternalContacts, then all external contacts will be migrated.

26


Examples

Perform an assessment and return list of users with migration errors with nested groups flattened: This example adds contact lists from the your Sametime Domino server and flattens any nested groups. Also, long contact groups will be truncated, and at most 100 buddies will be permitted for migration, otherwise an error will be returned.

C:\PS> Add-QmstContactList -InputObject $project -SameTimeServerName your-sametime -NestedGroupOption flatten -LongContactGroupNamesOption truncate -UserContactLimit 100 -ExceededContactLimitOption error

Perform an assessment and return list of users with migration errors with nested groups flattened; include "google.com,live.com" SIP domains: This example is similar to Example 1, except it specifies the IncludeDomains option to include only the external contacts with the domains specified in the parameter list.

C:\PS>Add-QmstContactList -InputObject $project -SameTimeServerName your-sametime -NestedGroupOption flatten -LongContactGroupNamesOption truncate -UserContactLimit 100 -ExceededContactLimitOption error -IncludeDomains google.com,live.com

ExcludeDomains Lets you exclude specific external SIP domains when migrating contacts. External contacts with the specified SIP domains will not be migrated.


ExcludeAllExternalContacts Lets you not migrate any external contacts.








27


Perform an assessment and return list of users with migration errors with nested groups flattened; exclude "google.com,live.com" SIP domains: This example is similar to Example 2, except it specifies the ExcludeDomains option to exclude all of the external contacts with the domains specified in the parameter list.

C:\PS> Add-QmstContactList -InputObject $project -SameTimeServerName your-sametime -NestedGroupOption flatten -LongContactGroupNamesOption truncate -UserContactLimit 100 -ExceededContactLimitOption error -ExcludeDomains google.com,live.com

Move-QmstContactListThe Move-QmstContactList lets you write all contact lists generated by Add-QmstContactList to the back-end OCS/Lync Server database or an xml file.

Syntax

Move-QmstContactList [-InputObject] <QmstProject> [-WriteMethod] <String> [-OutputDirectory <String>] [-UserFilter <String[]>] [-DeleteExistingContacts] [-RemoteCredentials <PSCredentials>] [-SyncDb] [-MessageLog <String>] [-LyncTarget -LyncPoolFqdn <String>]

Parameters



WriteMethod Lets you specify one of the following values:

• WMI - contact lists are written to the OCS database using WMI classes. This option is not available for Lync servers.

• Database – contact lists will be written directly into the OCS/Lync Server Back-end Database

• File – contact lists will be written to XML files which can later be imported into the Back-end database using dbimpexp.exe

OutputDirectory Specifies the output directory to use if the WriteMethod is set to “file”. If not specified, the output files will be saved to the current directory.


DeleteExistingContacts If specified, all users’ contacts will be deleted prior to migrating new contacts. This only applies if WriteMethod is set to “database”.

28


Examples

Write all contact lists to the back-end database: This example writes all contact lists to the back end database corresponding to each user’s pool. If the user had any contacts previous to this call, they would be deleted prior to importing the new contacts. "$project represents a QmstProject with contact lists added by "Add-QmstContactList.

C:\PS>$project | Move-QmstContactList –WriteMethod database -DeleteExistingContacts

Write all contact lists to XML files: This example writes all contact lists to XML files which can be used by dbimpexp.exe to import the contacts into the database. The files will be placed in the directory c:\import.

C:\PS>$project | Move-QmstContactList –WriteMethod file –OutputDirectory c:\import\

Import-QmstMessageLogThe Import-QmstMessageLog lets you save message logs for a specific project to the database. The message logs are specified from the following cmdlets:

• Add-QmstContactList

• Move-QmstContactList

• Enable-QmstUser

• Set-QmstUserMapping

Syntax

Import-QmstMessageLog [[–Path] <String>] [-PassThru]

RemoteCredentials Lets you specify alternate credentials to connect to the WMI.






29


Parameters

Examples

Import the log file to the database: This example runs the mapping task, and gathers message logs to the path C:\Mapping.csv. You can then insert the Mapping.csv file to the database.

$divisionMigration | Set-QmstUserMapping -SearchDomains finance.division.company.com -DominoAttributeName shortname -ADAttributeName samaccountname -MessageLog C:\Mapping.csv

Import-QmstMessageLog –Path C:\Mapping.csv

Export-QmstMessageLog

The Export-QmstMessageLog lets you export message logs from the database. The message logs are specified from the following cmdlets:

• Add-QmstContactList

• Move-QmstContactList

• Enable-QmstUser

• Set-QmstUserMapping


Path Lets you specify the task message log path.

PassThru Lets you indicate whether the cmdlet passes an output object through the pipeline.

EXAMPLE EXAMPLE COMMAND EXAMPLE DESCRIPTION

Import the log file to the database

$divisionMigration | Set-QmstUserMapping -SearchDomains finance.division.company.com -DominoAttributeName shortname -ADAttributeName samaccountname -MessageLog C:\Mapping.csv

Import-QmstMessageLog –Path C:\Mapping.csv

This example runs the mapping task, and gathers message logs to the path C:\Mapping.csv. You can then insert the Mapping.csv file to the database.

30


Syntax

Export-QmstMessageLog [–InputObject <QmstProject>] [[-Path] <String>]

Parameters

Examples

Export stored message logs to output path: This example runs the mapping tasks, then synchronizes the database with a project. Then you can export all stored message logs to the output path "MyProjectLogs.csv".

$divisionMigration | Set-QmstUserMapping -SearchDomains finance.division.company.com -DominoAttributeName shortname -ADAttributeName samaccountname –SyncDb

$divisionMigration | Export-QmstMessageLog –Path MyProjectLogs.csv

ConvertFrom-QmstXmlThe ConvertFrom-QmstXml cmdlet lets you reload an object from the XML file created in the ConvertTo-QmstXml cmdlet.

Syntax

ConvertFrom-QmstXml [-InputObject] <String> [-Path <String>]

Parameters



Path Lets you specify the task message log path.


InputObject Indicates any object that you want to converted from an XML string.

Path Lets you specify the path from which to load the Migrator For Sametime Object.

31


Examples

Convert project name from an XML file for later retrieval: In this example, the file “myproject.xml” contains a project saved with ConvertTo-QmstXml. This is loaded using get-content and the result stored in $projectXml. To recreate the project use ConvertFrom-QmstXml passing in the $projectXml variable as the input object. This can be used with other Qmst cmdlets.

C:\PS>$projectXml = get-content “myproject.xml”

C:\PS>$myProject = ConvertFrom-QmstXml –InputObject $projectXml

ConvertTo-QmstXmlThe ConvertTo-QmstXml cmdlet lets you generate an XML string that represents the object. This cmdlet converts any output object to an XML string, and then can be piped to an XML file.

This cmdlet does not accept pipeline input.

Syntax

ConvertTo-QmstXml [-InputObject] <Object> [[-Path] <String>]

Parameters

Examples

Convert project name to an XML file for later retrieval: In this example, a new QmstProject is created and assigned to the variable $myProject. The project is converted to a String containing a XML representation which is stored in the variable $projectXml. This String is then piped to set-content to save the content to the file “myproject.xml” for later retrieval.

C:\PS>$password = Read-Host -asSecureString

C:\PS>$myProject = New-QmstProject -ProjectName "Finance Department Migration" -ADForestName YourCompany.com -LotusNotesIdPath " C:\share\Admin id files\admin.id" -LotusNotesPassword $password -DominoServerName "your-dom",names.nsf


InputObject Indicates any object that you want to converted to an XML string.

Path Lets you specify the path to save the Migrator For Sametime object.

32


C:\PS>$projectXml = ConvertTo-QmstXml –InputObject $myProject

C:\PS>$projectXml | set-content “myproject.xml”

Show-QmstLicenseThe Show-QmstLicense lets you view your license key. No parameters are required for this cmdlet. The cmdlet will display a window showing your license details.

Syntax

Show-QmstLicense

Parameters

This cmdlet requires no parameters.

Examples

View current license: This example shows a dialog box displaying your current license details.

C:\PS>Show-QmstLicense

Update-QmstLicenseThe Update-QmstLicense cmdlet lets you update your license key from either the trial license or a license from a previous version, by using the filename in the current directory or the full path.

Syntax

Update-QmstLicense -InputObject <String>

Parameters


InputObject Full path to the license.asc file that is to be applied.

33


Examples

Using the filename in the current directory: This example updates the license file “MigratorForSametime.asc” in the current directory.

Update-QmstLicense MigratorForSametime.asc

Using the full path: Updates the license file using a fully qualified path.

Update-QmstLicense C:\MigratorForSametime.asc

Common ParametersThe following are common parameters used among some of the cmdlets.

• UserFilter• SyncDb• MessageLog• InputObject

UserFilter

Some cmdlets have a UserFilter parameter which lets you run tasks only against a subset of the users found in the Migration project. Otherwise, tasks will run against all users in the migration project.

Sample Script Syntax

These examples showhow to use the UserFilter parameter with some cmdlets.

• UserFilter parameter with Select-Object cmdlet

$userFilter = $project.DominoServers | Select-Object -ExpandProperty DominoUsers | Select-Object -First 1000 | ForEach-Object { $_.DominoDn }

This sample script uses the Select-Object cmdlet to construct a user filter for the QmstProject stored in the $project variable. The example will select the first 1000 users in the project.

• UserFilter parameter with Where-Object cmdlet

$userFilter = $project.DominoServers | Select-Object -ExpandProperty DominoUsers | Where-Object { $_.Location -like 'new york'} | ForEach-Object { $_.DominoDn }

This sample uses the Where-Object cmdlet to construct a user filter for the QmstProject stored in the $project variable. The example selects all users whose Location property in Domino is set to "New York".

34


• Saving the UserFilter parameter to a file

$userFilter | Set-Content c:\userFilter.txt

This sample script uses the Set-Content cmdlet to allow you to save the user filter parameter to a file for use at a later time.

• Retrieving the UserFilter parameter from a file

[String[]]$userFilter = Get-Content C:\userFilter.txt

This sample script uses the Get-Content cmdlet to allow you to retrieve the user filter parameter from a file for use at a later time.

SyncDb

The SyncDb parameter lets you synchronize the command result with the Migrator for Sametime database so a matching task is created in the Migrator for Sametime Management Console. This parameter is optional.

Once you perform a task using a cmdlet, the task is created in the Console with the same attributes.

MessageLog

The MessageLog parameter lets you specify a file to save additional task messages in CSV format. The file can later be used by Import-Csv to generate reports, or uploaded to the Migrator for Sametime database using the Import-QmstMessageLog cmdlet.

InputObject

The InputObject parameter allows you set the QmstProject, identified by ProjectName, as a variable. The following cmdlets use InputObject as QmstProject:

• Add-QmstContactList• Clear-QmstUserMapping• Enable-QmstUser• Export-QmstMessageLog• Get-QmstProject• Move-QmstContactList• Remove-QmstProject• Set-QmstUserMapping• Update-QmstProject

35


This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

36

4

PowerShell Sample Scripts

• About Sample Scripts

• List of Sample Scripts


About Sample ScriptsMigrator for Sametime includes sample scripts which can be used to report on the status of the migration (QmstProject object) using Microsoft Excel. The reports are displayed in Microsoft Excel in table and graph formats.

You can also use sample scripts to run a full migration and set the UserFilter parameter.

To open the PowerShell sample scripts

• Click Start | Programs | Quest Software | Migrator for Sametime | PowerShell Sample Scripts.

List of Sample ScriptsYou can use PowerShell sample scripts to generate the following:

• Buddy List Assessment Report• Migration Errors Report• Run Mapping Report• Run Project Status Report• Full Migration• Full Migration with Menu

Buddy List Assessment Report

Description

The Buddy List Assessment Report can be generated from a QmstProject from the script CreateBuddyListAssessmentReport.ps1 and calling the CreateBuddyListAssessmentReport function:

This will generate:

• A table showing all users with nested groups• A table showing all users with more than the allowed number of

contacts (specified in Add-QmstContactList)• All user Error and warnings• A chart showing the number of users with too many contacts


$taskMessages = Import-Csv -Path <path to MessageLog file>

CreateBuddyListAssessmentReport.ps1 <QmstProject> $taskMessages

38

PowerShell Sample Scripts

Migration Errors Report

Description

The Errors and Warnings report can be generated from a QmstProject from the script CreateErrorsAndWarningsReport.ps1 and calling the CreateErrorAndWarningsReport function.

This will generate a table listing all of the users with an error status and any error messages for the user.



CreateMigrationErrorsReport.ps1 <QmstProject> $taskMessages

Run Mapping Report

Description

The Run Mapping Report can be generated from a QmstProject from the script RunMappingReport.ps1 and calling the RunMappingReport function. This report depends on the output from the Set-QmstUserMapping cmdlet.

This will show a list of users that are either mapped or not mapped to Active Directory.



RunMappingReport.ps1 <QmstProject> $taskMessages

Run Project Status Report

Description

The Run Project Status Report can be generated from a QmstProject from the script RunProjectStatusReport.ps1 and calling the RunProjectStatus function.

This will generate a report showing the status of the project migration including total number of users, number of users enabled in OCS/Lync Server, number of users not started, number of users assessed, number of users mapped, and number of users fully migrated.


RunProjectStatusReport.ps1 <QmstProject> $taskMessages

39


Full Migration

Description

The Full Migration script calls each key component to run a full migration from Sametime to OCS/Lync Server for all users in the organization.

You can use this script as an example of how to run a full migration using Migrator for Sametime cmdlets.


.\FullMigrationSample.ps1

Full Migration with Menu

Description

This Full Migration with Menu script lets you perform the Migrator for Sametime migration workflow in Powershell using a console-based menu system.

You can use this script to create a project or load a project from file or database.

You can access menu items provided for all of the migration tasks exposed in Powershell:

• Mapping (Set-QmstUserMapping)

• Enabling Users in OCS/Lync Server (Enable-QmstUser)

• Adding users' contact lists (Add-QmstContactList)

• Migrating users’ contact lists to their target OCS/Lync Server pool (Move-QmstContactList)


.\FullMigrationSampleWithMenu.ps1

This script does not save any state information and does not support pausing the migration or resuming the migration at a later time.

40

About Quest Software

Quest Software simplifies and reduces the cost of managing IT for more than 100,000 customers worldwide. Our innovative solutions make solving the toughest IT management problems easier, enabling customers to save time and money across physical, virtual and cloud environments. For more information about Quest go to www.quest.com.

Contacting Quest Software

Refer to our Web site for regional and international office information.

Contacting Quest SupportQuest Support is available to customers who have a trial version of a Quest product or who have purchased a Quest product and have a valid maintenance contract. Quest Support provides unlimited 24x7 access to SupportLink, our self-service portal. Visit SupportLink at http://support.quest.com/.

From SupportLink, you can do the following:

• Retrieve thousands of solutions from our online Knowledgebase

• Download the latest releases and service packs

• Create, update and review Support cases

View the Global Support Guide for a detailed explanation of support programs, online services, contact information, policies and procedures. The guide is available at: http://support.quest.com.

Email [email protected]

Mail Quest Software, Inc.World Headquarters5 Polaris WayAliso Viejo, CA 92656USA

Web site www.quest.com

41

mailto:[email protected]

http://www.quest.com

http://support.quest.com/

http://support.quest.com/pdfs/Global Support Guide.pdf

http://www.quest.com


42

powershell administrator guide -...

Documents