Attunity RepliWeb PowerShell API Developer s Guide - PDF

Please download to get full document.

View again

of 101
All materials on our website are shared by users. If you have any questions about copyright issues, please report us to resolve them. We are always happy to assist you.
Information Report

Press Releases


Views: 152 | Pages: 101

Extension: PDF | Download: 4

Related documents
Attunity RepliWeb PowerShell API Developer s Guide Software Version 5.2 June 25, 2012 RepliWeb, Inc., 6441 Lyons Road, Coconut Creek, FL Tel: (954) , Fax: (954)
Attunity RepliWeb PowerShell API Developer s Guide Software Version 5.2 June 25, 2012 RepliWeb, Inc., 6441 Lyons Road, Coconut Creek, FL Tel: (954) , Fax: (954) Support: 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 Lyons Road Coconut Creek, Florida USA Telephone: (954) Fax: (954) Sales & General Information: Documentation: Technical Support: Website: ii Table of Contents 1. Introduction... 1 Requirements 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 R-1 Snap-in... 3 Manually Adding R-1 Snap-in... 3 Automating the R-1 Snap-in Process Handling Escape Characters s... 5 R1Session... 6 R1Session Properties... 6 R1Session Methods... 7 R1Job R1Job Properties R1Job Methods ReplicationJob DistributionJob MsiJob MsiDistributionJob ReplicationRollbackJob DistributionRollbackJob QueryFilter QueryFilter Properties QueryFilter Methods R1JobInfo ReplicationInfo Properties DistributionInfo Properties MsiInfo Properties iii Table of Contents MsiDistributionInfo Properties ReplicationRollbackInfo Properties DistributionRollbackInfo Properties A - Exit Messages Replication Exit Messages Distribution Exit Messages B - Examples C - MSI Configuration XML iv 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) 1 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 PowerShellrelated 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 installation utility: %windir%\\framework\v \installutil.exe ~\Repliweb\R1\API\PowerShell\ps4r1.dll 2 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. 3 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, 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` 4 5. s 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 o o o QueryFilter R1JobInfo Replication Job Distribution Job Replication Rollback Job Distribution Rollback Job 5 s 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 Center The name or IP of the Center being accessed. IP address / computer name Domain The valid domain name for the user-specified account. Domain name Password The password for the userspecified account. Integer Port The port for Console-Center communication. QueryFilter QueryFilter The query parameter settings before retrieving the job list. ScrambledPassword The valid scrambled password for the user-specified account. Use the ScramblePassword method SSL Indicates if the connection is through SSL. UserName Username that connects to the Center. Enum Views View Display view for the jobs list. Flat Hierarchy 6 s R1Session Methods Return Values Name Description Void R1Job[] Connect Disconnect GetJobList Starts a session on the Center. You can connect in three ways: Connect() Connect(ConnectInfo) cmdlet qualifiers Terminates a PowerShell session by logging it off from the R-1 server. Retrieves all of the jobs, according to QueryFilter, from the R1Session database. ScramblePassword Returns encrypted passwords for greater security. Void Void SetDeploymentMode SetView 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. 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. 7 Syntax R1Session.Connect() s 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( center, user, password, domain, ScrambledPassword, usessl, port ) } Parameters Center The name or IP of the Center being accessed. User - The username that connects to the Center. Password - The password for the user-specified account. Domain - The valid domain name for the user-specified account. ScrambledPassword - The valid scrambled password for the user-specified account. SSL - Indicates if the connection is through SSL. 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 ) 8 s 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 } 9 s 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( 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 ) 10 s Disables Deployment Mode: $R1Session.SetDeploymentMode( $false, $null, $null ) SetView Remarks The parameters are case-insensitive. In order to view spawned jobs as well, in the QueryFilter object, set the IncludeHistoryJobs and IncludeChildJobs fields to True. Syntax R1Session.SetView(string view) Parameters Flat - Retrieves all existing jobs on the server Hierarchy - Retrieves only scheduled jobs and individual (jobs with no ParentID value) jobs Example Sets view to Flat mode: $R1Session.Setview( flat ) Sets view to Hierarchy mode and retrieves scheduled job execution history: $R1Session.Setview( hierarchy ) $R1Session.QueryFilter.IncludeHistoryJobs = $true $R1Session.QueryFilter.JobState = R1_API_SCHEDULER_JOB $sched = $session.getjoblist() Submit Remarks For more information, refer to the Submit Qualifiers section in the R-1 User Guide. 11 Syntax R1Session.Submit( Submit_CLI_qualifiers) s Example Submits a Replication job: $qual = name=replication -edge=edge_addr user=username -edge_password=secret -type=replication -source_dir=c:\source -target_directory=c:\target $R1Session.Submit($qual) DeploymentSubmit Remarks For more information, refer to the Deployment_Submit Command section in the R-1 User Guide. Syntax R1Session.DeploymentSubmit( DeploymentSubmit_CLI_qualifiers) Example Installs MSI file ABC.msi with installation-related files and parameters: $qual = name=msi_job -edge=edge_name user=username -edge_password=password -type=replication msi_action=install msi_list=` `[c:\\abc.msi,,true,c:\\file1.dll;c:\\file2.txt,true, param1=value param2=value,true`]` $R1Session.DeploymentSubmit($qual) Purge Syntax R1Session.Purge ( Purge_CLI_Qualifiers) Example Purges completed jobs without confirmation: R1Session.Purge( -state=completed -noconfirm ) 12 s R1Job Replication through R-1 is handled by jobs. Each job type is responsible for a different deployment process. R1Job is an abstract object that comprises the attributes and functions (members) shared by the different R-1 job types. Each job type includes its own set of properties and methods, and inherits a set of generic ones from the R1Job object. Properties R1Job Methods Replication Properties Methods MSI Deployment Properties Methods Replication Rollback Properties Methods Distribution Properties Methods MSI Deployment Distribution Properties Methods Distribution Rollback Properties Methods Each job type includes its own specific set of methods and properties and inherits a shared set of general properties and methods from the R1Job object. For the job-specific properties and methods, refer to the relevant job: Replication Job Distribution Job MSI Deployment Job MSI Deployment Distribution Job Replication Rollback Job Distribution Rollback Job 13 s R1Job Properties Type Name Description Valid Values Center Center IP or name. Description Job description, as entered by the user. DateTime EndTime Job s end time. ExistingReports Job status reports. DateTime object containing the jobsubmitted timestamp. general transfer pre_center pre_edge post_center post_edge deleted_files excluded_files rollback_recorder rollback_reloader mb_transfer edge_general sharepoint_transfer solution_deployment_transfer Integer Id Unique systemgenerated job ID. Name Job name, as entered by the user or inherited from the parent job. Scheduling Scheduling Properties related to the scheduling of Replication and Distribution jobs R1_API_SUBMITTED R1_API_INITIALIZING R1_API_RUNNING R1_API_COMPLETED_SUCCES S Enum R1_JOB_STAT ES State Current job state. For example, Aborted or Completed. R1_API_COMPLETED_ERROR R1_API_INTERUPTTED R1_API_ABORTED R1_API_SCHEDULER_JOB R1_API_HOLD_RECOVERING R1_API_WAIT_FOR_CONFIRM R1_API_HOLD 14 s Type Name Description Valid Values Note: For R1_API_HOLD, API_SCHED_HOLD_MODE indicates the reason for holding the job, as follows: 1 Execution 2 - Priority 3 Administrative SystemMessage Job-specific messages that are generated by R-1 while the job is running. List of user-created job tags. TagsList Note: Tags are separated by a ;. R1_DISTRIBUTION, Enum R1_OPERATIO N_TYPES Type Job s type. R1_EDGE, R1_REPLICATION, R1_DISTRIBUTION_ROLLBACK, R1_EDGE_ROLLBACK, R1_REPLICATION_ROLLBACK R1Job Methods Return Values Name Description R1Job Abort Aborts the job. R1Job Confirm Confirms the job. void Delete Deletes the job array GetExistingReports Gets the list of the job s available reports. array or void R1Job GetReport Hold Generates the job s report. You may use Hold in two ways: Hold - Puts a job on hold indefinitely. Hold(DateTime time) - Puts a job on hold until the specified date and time. 15 s Return Values Name Description (XML) Preview Returns the job s comparative snapshot for the user to review and edit before confirming the job using the Confirm method. R1Job Refresh Gets the job s updated state and info. R1Job Resume Reactivates a job that is on hold. Abort Syntax R1Job.Abort() Example Aborts all scheduled jobs: $R1Session.QueryFilter.JobState = R1_API_SCHEDULER_JOB $jobs = $session.getjoblist() foreach( $R1Job in $jobs ){ $R1Job.Abort() } Confirm You may confirm and activate a new job in two ways, as follows: Using Connect Syntax Syntax R1Job.Confirm() Example Confirms all jobs that are pending confirmation in R-1: $R1Job = $session.getjoblist() $waitlist = $R1Job where{ $_.State -match CONFIRM } foreach ( $Job in $waitlist ) { $Job.Confirm() } Using Confirm( ComparativeSnapshotXML) Syntax R1Job.Confirm( ComparativeSnapshotXML) 16 s Example Confirms all jobs pending Edge: $jobs = $session.getjoblist() $waitlist = $jobs where{ $_.State -match CONFIRM } foreach ( $job in $waitlist ) { [xml]$preview = $job.preview() $edge = $Preview.RootConfirmation.EdgeName If ( $edge.equals( ) ) { echo Confirming job: $ $job.confirm( $Preview.Get_outerXML() ) } } Delete Syntax R1Job.Delete() Example Removes all jobs that completed successfully: $R1Session.QueryFilter.JobState = R1_API_COMPLETED_SUCCESS $jobcompletedsuccessfully = $R1session.GetJobList() foreach( $index in $jobcompletedsuccessfully){$index.delete()} GetExistingReports Syntax R1Job.GetExistingReports() Example Retrieves a list of report types available for a job: $ExistingReport = $job.getexistingreports() GetReport Remarks Use the GetExistingReports return values as parameters in GetReport. Only reports that are returned by GetExistingReports method can be viewed. 17 s Syntax R1Job.GetReport(string ReportType, string FileNamePath, OpenNotepad) Parameters ReportType Taken from GetExistingReports. FileNamePath Relative or absolute path, file name must be included. OpenNotepad Indicates if to open Windows Notepad with the returned report. Example Retrieves the job s General report, and opens a notepad file: $R1Job.GetReport( general , d:\reports\report.txt , $true ) Retrieves the job s General report and stores it in a variable: $jobreport = $R1Job.GetReport( general , $false ) Hold You may put a job on hold in two ways, as follows: Using Hold() Syntax R1Job.Hold() Example Holds all scheduled jobs: $R1Session.QueryFilter.JobState = R1_API_SCHEDULER_JOB $jobs = $R1session.GetJobList() foreach( $R1Job in $jobs ){ $R1Job.Hold() } Using Hold(DateTime time) Syntax R1Job.Hold(DateTime time) 18 Parameters s DateTime Time Example Holds a job for 10 days: $scheduledjobs = $R1session.GetJobList() where{ $_.state -match 'schedule' } $time = Get-Date $time = $time.adddays( 10 ) foreach($r1job in $scheduledjobs ){ $R1Job.Hold($time ) } Preview Syntax R1Job.Preview() Example Displays all Edges that are pending confirmation: [xml]$preview = $job.preview() echo $Preview.RootConfirmation.EdgeName Refresh Syntax R1Job.Refresh() Example Queries the current job s state, aborts, refreshes, and then queries the job s new state: if( $R1Job.state match schedule ) { $job.abort() $job = $job.refresh() write-output $R1Job.State } 19 s Resume Syntax R1Job.Resume() Example Resumes held jobs: $R1Session.QueryFilter.JobState = R1_API_HOLD $jobs = $session.getjoblist() foreach($r1job in $jobs ){ $R1Job.Resume() } 20 s ReplicationJob Replication includes the following properties and methods. ReplicationJob Properties Type Name Description Valid Values Enum RDS_JOB_DIRECTI ON Direction Job s replication direction, Upload or Download. RDS_API_DOWNLOAD, RDS_API_UPLOAD Edge Edge IP or name. ParentID Unique ID of the job that spawned this job. GroupID Unique ID of the group this job belongs to. NONE Enum HOLD_MODES HoldMode Indicates if a job is on hold. EXECUTION_TIMEFRAME PRIORITY ADMINISTRATIVE WAIT_FOR_COMMIT Dat
We Need Your Support
Thank you for visiting our website and your interest in our free products and services. We are nonprofit website to share and download documents. To the running of this website, we need your help to support us.

Thanks to everyone for your continued support.

No, Thanks

We need your sign to support Project to invent "SMART AND CONTROLLABLE REFLECTIVE BALLOONS" to cover the Sun and Save Our Earth.

More details...

Sign Now!

We are very appreciated for your Prompt Action!