GeoSync cmdlets

In this section:

About GeoSync
Parameter Definitions
Generate Scripts to Configure GeoSync

About GeoSync

GeoSync setup is performed by cmdlets shipped with the personalization server. The cmdlets are automatically imported into a PowerShell session when Import-ApsInstancemodule is executed.

If the default Environment Manager install location is used, the cmdlets are here: C:\Program Files\AppSense\Environment Manager\Personalization Server\Support

Cmdlet	Description	Parameters
New-EMPSPublisher	Sets up the specified database as a publisher for GeoSync. This cmdlet operates in two modes - Live and Export. In Export mode, it exports a script which can be applied to a database to perform the operation. The script can be tailored for advanced requirements.	Common parameters: -PublisherServer -PublisherDatabase -DisplayName -Verbose -ConfigurerCredential -SecondaryReplicaServers -DatabaseMasterKeyPassword Live parameters: -ConfigurerCredential Export parameters: -ExportScript -ScriptFolder folder -Force
Remove-EMPSPublisher	Removes publisher functionality from a specified database. This cmdlet removes the publisher setup from a database, providing all subscribers have already been removed. If subscribers cannot be removed in the normal way, use the Reset-EMPSGeoSyncDatabase cmdlet. This cmdlet operates in live mode or export mode.	Common parameters: -PublisherServer -PublisherDatabase -Verbose -ConfigurerCredential PSCredential Live parameters: -ConfigurerCredential PSCredential Export parameters: -ExportScript -ScriptFolder folder -Force
Add-EMPSSubscriber	Adds a subscriber database to a publisher. In live mode both the publisher and subscriber must be accessible. In export mode three scripts are produced: The subscriber base setup script, "Subscriber-subscriberid.sql" performs the basic setup on the subscriber. It requires a certificate folder specified for the subscriber certificate(s) created to be saved. The add publisher reference script, "AddPublisherTo-subscrberid.sql" adds a reference to the publisher on the subscriber. It requires the publisher certificates(s) to be copied to a specified certificate folder on the subscriber. The add subscriber reference script, "Add-subscriberIdToPublisher.sql", adds a reference to the subscriber on the publisher. It requires the subscriber certificates(s) to be copied to a specified certificate folder on the publisher.	Common parameters: -PublisherServer -PublisherDatabase -SubscriberServer -SubscriberDatabase -ServiceCredential PSCredential -DisplayName -Verbose Live parameters: -ConfigurerCredential PSCredential The configurer credentials must be the same for both the subscriber and publisher databases. Export parameters: -ExportScript -ScriptFolder folder -Force -PublisherDisplayName
Remove-EMPSSubscriber	Removes subscriber from publisher and cleans up subscriber. In live mode both the publisher and subscriber need to be accessible. In export mode two scripts are produced: RemoveSubscriber-subscriberid.sql Remove-subscriberid.sql.	Common parameters: -PublisherServer -PublisherDatabase -SubscriberServer -SubscriberDatabase -RemoveUsers -Verbose (optional) Live parameters: -ConfigurerCredential PSCredential The configurer credentials must be the same for both subscriber and publisher databases. Export parameters: -ExportScript -ScriptFolder folder -Force
Get-EMPSSubscribers	Returns list of subscribers for a publisher. This cmdlet writes a list of objects to the output pipeline with the string properties 'ServerInstance' and 'Database'.	-PublisherServer -PublisherDatabase -ConfigurerCredential PSCredential
Reset-EMPSGeoSyncDatabase	Removes GeoSync setup from a single database where linked databases may not be available. Used to remove GeoSync information if subscribers or publisher are not available. This only runs in live mode. If -SubscriberDisplayName is specified, reference to that subscriber is removed from a publisher database. Otherwise removes all GeoSync objects from any database (publisher or subscriber).	-Server -Database -ConfigurerCredential -SubscriberDisplayName -Force
Start-EMPSBatchSync	Programmatically starts a batch sync from the specified publisher database to a specified subscriber database. Used to initiate a batch sync for any matching subscriber. This is the same as triggering a batch sync from the console. This command is asynchronous. It will return an object reflecting the status of the request but will not block until the sync has completed.	-SubscriberDisplayName -ConfigOnly
Stop-EMPSBatchSync	Stops an executing batch sync. Used to stop a running batch sync for any matching subscriber. This is the same as canceling a batch sync from the console. This command is asynchronous. It will return an object reflecting the status of the request but will not block until the cancel has completed.	-SubscriberDisplayName
Get-EMPSBatchSyncStatus	Retrieves the status of a sync. Used to return the sync status for any matching subscriber. This is the same status that is displayed in the console. It will return an object reflecting the status of the request.	-SubscriberDisplayName

Parameter Definitions

Parameter	Description
-PublisherServer	Server name for publisher server. For non-default instance use server\instance format. When setting up a publisher database that is part of an availability group, this parameter should point to the primary replica.
-PublisherDatabase	Name of publisher database.
-SubscriberServer	Server name for subscriber server. For non-default instance use server\instance format.
-SubscriberDatabase	Name of subscriber database.
-DisplayName	Optional display name refers to the publisher in subscriber databases and the subscriber in publisher databases. If omitted, it defaults to the leftmost component of the server name. If this does not result in a unique name when the subscriber is set up an error is displayed.
-Verbose	Verbose output displayed - optional.
-ConfigurerCredential PSCredential	Credential to use for configuration. If omitted, the current windows credential is used. If the username contains a backslash, the credential is treated as a windows credential. Otherwise it is treated as a SQL credential.
-SecondaryReplicaServers	A comma-separated list of the database servers where the secondary replica databases are hosted. If the cmdlet detects the published database is part of an availability group, then one or more secondary replica databases should be specified.
-DatabaseMasterKeyPassword	Allows you to specify the master key password used to encrypt credentials. Without this parameter, the cmdlet will generate a random complex password. In some situations, the retention of the database master key password is vital. See GeoSync.htm
-ServiceCredential PSCredential	Credential for service access on the subscriber (used for initial batch sync). This must be an existing service account on the subscriber. If the username has a backslash it is considered to be a windows credential, otherwise a SQL credential.
-ExportScript	Specifies export mode.
-ScriptFolder folder	Optionally specify a folder that the script is written to. This may be an absolute or relative path. If the folder doesn't exist it is created - provided that its parent folder exists.
-Force	If specified, an existing script of the same name will be overwritten. When a subscriber display name or pattern is specified, prevents the cmdlet from prompting for confirmation before each subscriber is removed.
-PublisherDisplayName	Optional display name of publisher for subscriber database. This should match the display name created at the publisher end.
-Server	Server name. For non-default instances, use server\instance format.
-Database	Database name.
-SubscriberDisplayName	If specified removes subscriber(s) matching the display name from a publisher. Name may include wildcards * and ?. If not specified all GeoSync setup is removed from the database (whether publisher or subscriber).
-ConfigOnly	Will initiate a configuration only sync.

Generate scripts to configure GeoSync

The GeoSync cmdlets can be used to generate SQL scripts for setting up and tearing down GeoSync. This is useful if the user does not have enough privileges to modify the respective databases. Instead the scripts can be passed to a database administrator to be executed.

Export mode is available by specifying the -ExportScript parameter with the cmdlets New-EMPSPublisher, Add-EMPSSubscriber, Remove-EMPSSubscriber, and Remove-EMPSPublisher. The other cmdlets do not have an export feature.

The cmdlets are loaded by executing Import-Apsinstancemodule. This may produce a warning if the user is not an administrator but it doesn’t affect the script generation.

New-EMPSPublisher

If -ExportScript is specified, -ConfigurerCredential is not used and additional parameters are available:

-ScriptFolder specifies a folder where the script is written - if omitted a script is written to the current folder
-Force tells the cmdlet to overwrite a script with the same name if it exists.

The script produced is named Publisher-<server>-<instance>-<database>.sql. This script can be run using sqlcmd against the publisher database. If SQL Server Management Studio is used, the query window used must be in sqlcmd mode.

Unlike running the cmdlet ‘live’, no checks are made to see if the database has already been set up.

Add-EMPSSubscriber

If -ExportScript is specified, -ConfigureCredential is not used and -ScriptFolder and -Force are available as for New-EMPSPublisher. The -ServiceCredential must be specified. Add-EMPSSubscriber produces three scripts:

Subscriber-<server>-<instance>-<database>.sql - This script should be run first against the subscriber database to do the base setup. Server/instance/database refer to the subscriber
Add-<server>-<instance>-<database>ToPublisher.sql - Run on the publisher server to add a reference to the subscriber.
AddPublisherTo<server>-<instance>-<database>.sql - Run on the subscriber server to add a reference to the publisher.

Remove-EMPSSubscriber

Similar to Add-EMPSSubscriber in ExportScript mode, but -ServiceCredential is not required. Two scripts are produced:

Remove-<server>-<instance>-<database>FromPublisher.sql - Run on the publisher server to remove the reference to the subscriber.
RemoveSubscriber<server>-<instance>-<database>.sql - Run on the subscriber server to remove publisher reference and remove the base setup.

Remove-EMPSPublisher

As above, -ExportScript comes with -Force and -ScriptFolder and -ConfigurerCredential is not relevant. Produces a single script:

RemovePublisher-<server>-<instance>-<database>FromPublisher.sql - Run on the publisher server to remove the publisher and revert the database to a standard personalization database.