Attunity RepliWeb PowerShell API Developer's Guide

Attunity RepliWeb PowerShell API Developer's Guide - Page 1

This is only a preview of the document.

Download original document to view more pages

Download

1 of 101

Attunity RepliWeb PowerShell API Developer?s Guide


Related documents


Attunity RepliWeb PowerShell API Developer's Guide Transcripts

  
 
 
 
 
 
 
Attunity RepliWeb 
PowerShell API 
Developer’s Guide 
 
Software Version 5.2 
 
 
 
 
 
 
June 25, 2012 
 
 
RepliWeb, Inc., 6441 Lyons Road, Coconut Creek, FL 33073 
Tel: (954) 946-2274, Fax: (954) 337-6424 
E-mail: info@repliweb.com, Support: http://support.repliweb.com   
 
  
 
Attunity RepliWeb PowerShell API Developer's Guide  
 
ii 
 
 
 
 
 
 
 
 
 
© 2012 Attunity Ltd. All rights reserved. 
 
The information in this manual has been compiled with care, but Attunity Ltd. makes no warranties 
as to its accuracy or completeness. The software described herein may be changed or enhanced 
from time to time. This information does not constitute a commitment or representation by Attunity 
and is subject to change without notice. The software described in this document is furnished under 
license and may be used and/or copied only in accordance with the terms of this license and the End 
User License Agreement. 
 
No part of this manual may be reproduced or transmitted, in any form, by any means (electronic, 
photocopying, recording or otherwise) without the express written consent of Attunity Ltd. 
 
Windows, Windows XP and Windows Vista are trademarks of Microsoft Corporation in the US 
and/or other countries. UNIX is a registered trademark of Bell Laboratories licensed to X/OPEN. 
 
Any other product or company names referred to in this document may be the trademarks of their 
respective owners. 
 
Please direct correspondence or inquiries to: 
RepliWeb, Inc. 
6441 Lyons Road 
Coconut Creek, Florida 33073 
USA 
 
Telephone: (954) 946-2274 
Fax:  (954) 337-6424 
 
Sales & General Information: info@repliweb.com 
Documentation: docs@repliweb.com 
Technical Support: http://support.repliweb.com 
Website: http://www.repliweb.com 
 
 
  
 
Attunity RepliWeb PowerShell API Developer's Guide  
 
iii 
 
Table of Contents 
 
1. Introduction ................................................................................................................................... 1 
Requirements ......................................................................................................................................................... 1 
2. Installation Guidelines .................................................................................................................... 2 
Installing R-1 on Environment with PowerShell ..................................................................................................... 2 
Installing R-1 on Environment without PowerShell................................................................................................ 2 
Installing PowerShell on Environment with R-1 ..................................................................................................... 2 
3. R-1 Snap-in..................................................................................................................................... 3 
Manually Adding R-1 Snap-in ................................................................................................................................. 3 
Automating the R-1 Snap-in Process ...................................................................................................................... 3 
4. Handling Escape Characters ............................................................................................................ 4 
5. Objects .......................................................................................................................................... 5 
R1Session................................................................................................................................................................ 6 
R1Session Properties ....................................................................................................................................... 6 
R1Session Methods ......................................................................................................................................... 7 
R1Job .................................................................................................................................................................... 13 
R1Job Properties ........................................................................................................................................... 14 
R1Job Methods.............................................................................................................................................. 15 
ReplicationJob ............................................................................................................................................... 21 
DistributionJob .............................................................................................................................................. 25 
MsiJob ........................................................................................................................................................... 29 
MsiDistributionJob ........................................................................................................................................ 32 
ReplicationRollbackJob.................................................................................................................................. 35 
DistributionRollbackJob ................................................................................................................................ 36 
QueryFilter ........................................................................................................................................................... 37 
QueryFilter Properties ................................................................................................................................... 37 
QueryFilter Methods ..................................................................................................................................... 38 
R1JobInfo .............................................................................................................................................................. 41 
ReplicationInfo Properties ............................................................................................................................ 42 
DistributionInfo Properties ........................................................................................................................... 59 
MsiInfo Properties ......................................................................................................................................... 66 
 
Attunity RepliWeb PowerShell API Developer's Guide Table of Contents 
 
iv 
 
MsiDistributionInfo Properties...................................................................................................................... 72 
ReplicationRollbackInfo Properties ............................................................................................................... 78 
DistributionRollbackInfo Properties .............................................................................................................. 84 
A - Exit Messages ............................................................................................................................. 90 
Replication Exit Messages .................................................................................................................................... 90 
Distribution Exit Messages ................................................................................................................................... 93 
B - Examples .................................................................................................................................... 95 
C - MSI Configuration XML ................................................................................................................ 97 
 
 
  
 
Attunity RepliWeb PowerShell API Developer's Guide  
 
1 
 
1. Introduction 
This document describes the R-1 PowerShell API. It provides detailed explanations of the R-1 
objects, methods, and properties required to operate and control R-1 functionality and obtain 
information regarding R-1 jobs using PowerShell. 
 
PowerShell is an easy-to-use object-oriented command-line shell and scripting language designed to 
provide IT professionals with greater system control, operation capabilities, and automation. 
Requirements 
You must have the following resources to use PowerShell on R-1: 
 R-1 v4.1 (or later) Deployment Console 
 Deployment computer with Microsoft .NET Framework (version 2.0 or later) installed 
 PowerShell (version 1.0 or later) 
 
  
 
Attunity RepliWeb PowerShell API Developer's Guide  
 
2 
 
2. Installation Guidelines 
Please refer to the relevant scenario below for installation guidelines.  
 
Installing R-1 on Environment with PowerShell 
When installing R-1 on PowerShell-installed environments, the following automatic PowerShell-
related processes take place: 
 R-1 installation copies relevant PowerShell DLLs to ~\RepliWeb\R1\API\PowerShell 
 R-1 installation performs PowerShell DLL registration 
Installing R-1 on Environment without PowerShell 
When installing R-1 on environments that do not include PowerShell, R-1 will copy relevant 
PowerShell DLLs to ~\RepliWeb\R1\API\PowerShell. However, since PowerShell is not 
installed, R-1 will not perform PowerShell DLL registration. 
Installing PowerShell on Environment with R-1 
After installing PowerShell on R-1-installed environments, you must manually register the 
PowerShell DLLs. 
 
This can be done using cmd or PowerShell. You can redirect the output to a file by using  
” > filename.log” at the end of the command. 
 
In order to use these DLLs, register the R-1 snap-in by running the following .NET installation utility: 
 %windir%\Microsoft.NET\Framework\v2.0.50727\installutil.exe 
~\Repliweb\R1\API\PowerShell\ps4r1.dll 
  
 
Attunity RepliWeb PowerShell API Developer's Guide  
 
3 
 
3. R-1 Snap-in 
When opening a new PowerShell instance, use the Add-PSSnapin cmdlet to add the required R-1 
snap-in. R-1 snap-in adds the R1Session cmdlet into your PowerShell session. 
 
On each new PowerShell session, manually run the add-pssnapin r1_ps_api command. 
Manually Adding R-1 Snap-in 
When opening a new PowerShell instance, you must use the Add-PSSnapin r1_ps_api 
cmdlet to add the required R-1 snap-in. R-1 snap-in adds the Get-R1Session cmdlet into your 
PowerShell session. 
 
For help on the usage of Get-R1Session, type the command: Get-Help GetR1Session. 
Automating the R-1 Snap-in Process 
You may customize your profile to run the “add-pssnapin r1_ps_api” command 
automatically at the start of each new PowerShell session, as follows: 
 
Note: Prior to performing this procedure, make sure the My Documents\WindowsPowerShell folder 
exists, otherwise create it.  
To automate the R-1 Snap-in process: 
1.     Access the My Documents\WindowsPowerShell folder. 
2.     Locate the profile.ps1 file, if it does not exist, create it. 
3.     In the profile.ps1 file, type “add-pssnapin r1_ps_api” and save the file.  
Add-pssnapin r1_ps_api will run automatically whenever you open a new 
PowerShell session. 
  
 
Attunity RepliWeb PowerShell API Developer's Guide  
 
4 
 
4. Handling Escape 
Characters 
When creating a command string using R-1 PowerShell, please take the following into consideration: 
 Precede any special character ($()*+.[]?\/^{}|" etc.) with a backquote (`). 
For example, -edge_password=`"`@aB2q`$WiM`" 
 Enclose in quotation marks ("") any qualifier value that contains spaces.  
For example, -name=`"My First Job`" 
 Use double backslashes (\\) when specifying paths which are enclosed in quotation marks 
(""). For example, -target_dir=`"C:\\my directory`" 
  
 
Attunity RepliWeb PowerShell API Developer's Guide  
 
5 
 
5. Objects 
This chapter provides low-level details of the R-1 objects used on the PowerShell platform, including 
methods, properties, syntax definitions and code samples for each method. 
 
Note: When running the code directly on PowerShell, each command should be ended in the same 
line. From script files, it is possible to run commands in blocks. 
 
The following R-1 objects are available: 
 R1Session 
 R1Job 
o Replication Job 
o Distribution Job 
o Replication Rollback Job 
o Distribution Rollback Job 
 QueryFilter 
 R1JobInfo 
 
Attunity RepliWeb PowerShell API Developer's Guide Objects 
 
6 
 
R1Session 
This is the first object presented to you whenever you start a RepliWeb PowerShell session. Use 
R1Session to connect and submit requests to R-1.  
 
This object is loaded by running the Get-R1Session cmdlet, and includes the following 
properties and methods: 
 
R1Session Properties 
Note: These properties may be set by the user, or retrieved at a later time. 
 
Type Name Description Valid Values 
String  Center 
The name or IP of the Center 
being accessed. 
IP address / computer 
name 
String  Domain 
The valid domain name for the 
user-specified account.  
Domain name 
String  Password 
The password for the user-
specified account. 
 
Integer  Port 
The port for Console-Center 
communication. 
 
QueryFilter QueryFilter 
The query parameter settings 
before retrieving the job list. 
 
String  ScrambledPassword 
The valid scrambled password 
for the user-specified account.  
Use the 
ScramblePassword 
method 
Boolean  SSL 
Indicates if the connection is 
through SSL. 
 
String  UserName 
Username that connects to the 
Center. 
 
Enum Views View Display view for the jobs list.  
Flat 
Hierarchy 
 
 
Attunity RepliWeb PowerShell API Developer's Guide Objects 
 
7 
 
R1Session Methods 
Return Values Name Description 
Boolean Connect 
Starts a session on the Center. 
You can connect in three ways: 
Connect() 
Connect(ConnectInfo) 
cmdlet qualifiers 
Void Disconnect 
Terminates a PowerShell session by logging it off from 
the R-1 server. 
R1Job[] GetJobList 
Retrieves all of the jobs, according to QueryFilter, 
from the R1Session database. 
String ScramblePassword Returns encrypted passwords for greater security. 
Void SetDeploymentMode 
Allows granting specific users with access and 
permissions to jobs. 
If the user is in the job’s authorized users/groups list,  
The user can view, monitor and control jobs if the user 
is included in the jobs’ authorized users/groups list. 
Void SetView 
Displays the required jobs according to the 
QueryFilter settings in one of two modes. 
R1Job Submit Submits a new job. 
R1Job DeploymentSubmit Submits a new MSI Deployment job. 
Void Purge Purges jobs in the specified states. 
Connect  
You may connect to the R-1 server in three ways, as follows: 
Using Connect() 
Remarks 
Before invoking a Connect() call, set: Center, UserName, and either Password or 
ScrambledPassword. 
Syntax  
R1Session.Connect() 
 
Attunity RepliWeb PowerShell API Developer's Guide Objects 
 
8 
 
Example 
Starts an R-1 session after setting the session’s properties: 
$R1Session = Get-R1Session 
$pass = $R1Session.ScramblePassword(“plain text password”) 
$R1Session.Center = "localhost" 
$R1Session.User = "Administrator1" 
$R1Session.ScrambledPassword = $pass  
$R1Session.Domain = "Domain1" 
$R1Session.Connect() 
 
Using Connect(ConnectInfo) 
Syntax  
R1Session.Connect( String center,  
String user,  
String password,  
String domain,  
String ScrambledPassword,  
Boolean useSSl,  
Int32 port ) } 
Parameters 
 String Center – The name or IP of the Center being accessed. 
 String User - The username that connects to the Center. 
 String Password - The password for the user-specified account. 
 String Domain - The valid domain name for the user-specified account. 
 String ScrambledPassword - The valid scrambled password for the user-specified 
account. 
 Boolean SSL - Indicates if the connection is through SSL. 
 Int32 Port - The port for Console-Center communication. 
Example 
Starts an R-1 session by including the relevant parameters in the connect call: 
$R1session = Get-R1Session 
$R1Session.Connect( "localhost",  "Administrator1",  "Password1", 
"", "", $false , "2837" ) 
 
 
Attunity RepliWeb PowerShell API Developer's Guide Objects 
 
9 
 
Using cmdlet qualifiers 
Syntax  
Get-R1Session  
-Center [Center IP]  
-User [User]  
-Password [Password]  
–Domain [Center domain]  
–ScrambledPassword [Scrambled Password]  
–UseSSL [$true/$false] 
–port [Center port]  
Example  
Starts an R-1 session by requesting the user’s credentials during runtime: 
$cred = Get-Credential 
$R1Session = Get-R1Session -Center [localhost] -credential $cred  
Disconnect  
Syntax  
R1Session.Disconnect() 
GetJobList  
Remarks 
The History and ChildJobs properties become available when 
QueryFilter.IncludeHistoryJobs is set to ”true”. 
Syntax  
R1Session.GetJobList() 
Example  
Resets the QueryFilter settings and returns scheduled Distribution jobs: 
$R1Session.QueryFilter.Reset() 
$jobs = $R1Session.GetJobList() 
$dist = $jobs | where{ $_.Type -match "DIST" –and $_.state –match 
“sched” } 
 
Attunity RepliWeb PowerShell API Developer's Guide Objects 
 
10 
 
ScramblePassword  
Syntax  
R1Session.ScramblePassword( string plain_text_password ) 
Example  
Set a scrambled password in the session: 
$scramble = $session.ScramblePassword( “my password” ) 
$R1Session.ScrambledPassword = $scramble 
SetDeploymentMode  
After setting DeploymentMode, use the GetJobList method to retrieve the jobs that can be 
accessed by the user who was set through the SetDeploymentMode method. 
Remarks 
SetDeploymnetMode may be called for only one user at a time. 
Syntax  
R1Session.SetDeploymentMode( Boolean UseDeploymentMode,  
  string UserName,  
  string Domain ) 
Parameters 
 UseDeploymentMode - Indicates to use deployment mode. This parameter must 
be used in conjunction with UserName and domain. 
 UserName - Indicates the name of the Deployment user. 
 Domain - When UserName is part of a Windows domain, this qualifier must be 
added. If UserName is not part of a Windows domain (i.e. a UNIX user, or a local 
user on a Windows machine), this qualifier can be omitted. 
Example 
Sets Deployment Mode to User1 and Domain1: 
$R1Session.SetDeploymentMode( $true, “User1”, “Domain1” ) 

© 2016 - 2017 Docmia. All rights reserved.