It would be great if PeopleSoft released a PowerShell module that would natively interact with its component pieces. Unfortunately, the best we have is psadmin.exe.
In an attempt to slowly integrate the wonders of PowerShell with PeopleSoft, I have created a PowerShell module which provides the same functionality as psadmin.exe, and a little bit more. Most of this is accomplished through calls to psadmin.exe, but the PowerShell module makes interacting with the command line interface much simpler.
The PeopleSoft PowerShell Module can:
- Start and stop any application server, process scheduler, web server, or search server domains
- List the status of a particular domain
- Create or import a domain configuration.
- Re-configure a domain
- Read and set values from a domain configuration file
And much more!
Below I will explain the benefits of this module, how it works, and how I have used it.
Benefits
The PeopleSoft PowerShell Module makes scripting PeopleSoft server actions much easier.
Some benefits include:
- Built-in help system
- Input validation
- Returns .NET objects
- Easier to use commands
Built-in Help System
Each cmdlet in this module includes an extensive help document. The help explains the function of each cmdlet, the available arguments, and examples of the cmdlet.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 |
PS> Get-Help Start-PsftDomain -Full NAME Start-PsftDomain SYNOPSIS Starts the PeopleSoft Application Server. SYNTAX Start-PsftDomain [-PS_HOME] <String> [-PS_CFG_HOME] <String> [-ServerType] <Object> [-Domain] <String> [[-Parallel]] [-WhatIf] [-Confirm] [<CommonParameters>] DESCRIPTION Use this command to start the PeopleSoft Application Server for a specific domain. The domain will boot in serial by default. PARAMETERS -PS_HOME <String> The full path to the PS_HOME directory for this domain. Required? true Position? 1 Default value Accept pipeline input? true (ByPropertyName) Accept wildcard characters? false -PS_CFG_HOME <String> The full path to the PS_CFG_HOME directory for this domain. Required? true Position? 2 Default value Accept pipeline input? true (ByPropertyName) Accept wildcard characters? false -ServerType <Object> The type of server on which to perform the action. Required? true Position? 3 Default value Accept pipeline input? true (ByPropertyName) Accept wildcard characters? false -Domain <String> The name of the domain on which to perform the action. Required? true Position? 4 Default value Accept pipeline input? true (ByPropertyName) Accept wildcard characters? false -Parallel [<SwitchParameter>] If specified, will start the domain in parallel boot mode. Required? false Position? 5 Default value False Accept pipeline input? true (ByPropertyName) Accept wildcard characters? false -WhatIf [<SwitchParameter>] Required? false Position? named Default value Accept pipeline input? false Accept wildcard characters? false -Confirm [<SwitchParameter>] Required? false Position? named Default value Accept pipeline input? false Accept wildcard characters? false <CommonParameters> This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). INPUTS OUTPUTS NOTES File Name : Start-PsftDomain.ps1 Author : Scott Kearney - kearney.scott@spcollege.edu Requires : PowerShell V3 -------------------------- EXAMPLE 1 -------------------------- C:\PS>Start-PsftDomain -PS_HOME C:\psoft\PS_HOME -PS_CFG_HOME C:\psoft\PS_CFG_HOME -ServerType AppServer -Domain DOMAIN1 Starts the domain named DOMAIN1. -------------------------- EXAMPLE 2 -------------------------- C:\PS>Start-PsftDomain C:\psoft\PS_HOME C:\psoft\PS_CFG_HOME DOMAIN1 -Parallel Starts the domain named DOMAIN1 in parallel boot more. |
Input Validation
Each argument is logically validated (as best as possible) to ensure that the input makes sense. Trying to start a domain that doesn’t exist? The cmdlet will stop and alert you.
Returns .NET Objects
Many of the cmdlets will actually parse the output from psadmin.exe and create real objects that can then be piped to other PowerShell cmdlets. For example, listing all of the processes with a “Load Done” of more than 1000:
|
1 |
PS> Get-PsftStatus -PS_HOME $PS_HOME -PS_CFG_HOME $PS_CFG_HOME -ServerType AppServer -Domain $Domain -Target Server | Where LoadDone -gt 1000 | Format-Table |
Easier to Use Commands
Rather than having to remember whether to use -p or -c, or having to remember if it’s cstatus or sstatus, the arguments in this module include fully-spelled-out words. This, along with the help system, makes using the commands much easier.
How It Works
The PeopleSoft PowerShell Module, as mentioned earlier, is basically just a bunch of calls to psadmin.exe. However, it’s really the PowerShell code before and after these calls that makes this module worthwhile.
Many of the cmdlets will help transform English-language input into psadmin.exe’s arguments. For example, -Target Server will translate into sstatus. They also help navigate some of the more tricky operations, like creating a new domain. Instead of having to carefully craft a slash-separated string of arguments, you can individually input the arguments, and only the arguments you wish to specify. The cmdlet will determine how to fill in the rest.
The cmdlets will also try to parse any output from psadmin.exe and create .NET objects. Usually this involves substring-ing each relevant line into a member of the object. Some cmdlets will also work with the .cfg files and return objects representing these files. Whenever possible, output is parsed into an object.
The cmdlets have a modicum of error handling also. If, despite our best efforts, the cmdlet run generates an error, the cmdlet will attempt to catch the error and print a PowerShell-friendly error message (with resolution steps if possible).
How To Use This Module
This module functions much like any other PowerShell module.
To begin, you must import the module. Because of the way psadmin.exe works, you will achieve the best results of you run the PowerShell cmdlets in a elevated command prompt. If you attempt to import the module, and you are not in an administrative prompt, you will be warned.
|
1 |
Import-Module PeopleSoft |
You will receive this warning if you try to import the module in a non-elevated prompt.
Once the module is imported, cmdlets can be run. To list the available cmdlets, run Get-Command.
|
1 |
Get-Command -Module PeopleSoft |
Most of the cmdlets in this module require the PS_HOME, PS_CFG_HOME, and Domain arguments. These three together tell psadmin.exe where your environment is located.
When calling the cmdlets, you have a few options.
You can include the required parameters inline:
|
1 |
Start-PsftDomain -PS_HOME C:\psft -PS_CFG_HOME C:\psft_cfg -ServerType AppServer -Domain PSDMO |
You can set up variables for these also:
|
1 2 3 4 5 |
$PS_HOME = "C:\psft" $PS_CFG_HOME = "C:\psft_cfg" $Domain = "PSDMO" Start-PsftDomain -PS_HOME $PS_HOME -PS_CFG_HOME $PS_CFG_HOME -ServerType AppServer -Domain $Domain |
These cmdlets also accept values from the pipeline by name, so you can create an object and pipe that object to the cmdlet.
|
1 2 3 4 5 6 7 |
$PeopleSoftValues = @{ "PS_HOME" = "C:\psft"; "PS_CFG_HOME" = "C:\psft_cfg"; "Domain" = "PSDMO"; } | ConvertTo-Json | ConvertFrom-Json $PeopleSoftValues | Start-PsftDomain -ServerType AppServer |
Finally, you can use the built-in PowerShell variable $PSDefaultParameterValues to set default values for all of these cmdlets:
|
1 2 3 4 5 |
$PSDefaultParameterValues.Add("*-Psft*:PS_HOME","C:\psft") $PSDefaultParameterValues.Add("*-Psft*:PS_CFG_HOME","C:\psft_cfg") $PSDefaultParameterValues.Add("*-Psft*:Domain","PSDMO") Start-PsftDomain -ServerType AppServer |
The benefit of the last two is that in subsequent cmdlets, you will have less to write when you execute future cmdlets.
Conclusion
This module is still a work in progress. I have tried my best to make it as complete as possible, but there are improvements I would like to make.
If you think this module might be useful, I would encourage you to give it a try in your development environment first. Get comfortable with it, make sure it will fit your environment, and make sure you understand what you can do with it. The module was written to be compatible with the 8.53 PeopleTools, but will likely be compatible with many other versions as well.
If you encounter any problems, I welcome your feedback. Please comment below or send me an email.
If you find this module useful, I would also appreciate hearing from you.
Hopefully this module will bring us one step closer to a more PowerShell-friendly PeopleSoft!
Download
The source is hosted on CodePlex here: PeopleSoft PowerShell Module.
You can download the latest version of the module at the link below.
Hey Scott:
I am very anxious to try out your Peoplesoft tools. Something like this is long overdue and I can see it being a huge benefit to those in our team.
Unfortunately, I am a Powershell novice and was in the process of “exploring” Powershell when I found your page. Out of the box, I am having issues when trying to do the Import-Module Peoplesoft and I am unsure how to proceed/troubleshoot. Any guidance from you or any of your Powershell guru followers would be greatly appreciated. The error is:
PS C:\temp> Import-Module Peoplesoft
Import-Module : The ‘C:\Windows\system32\WindowsPowerShell\v1.0\Modules\Peoplesoft\Peoplesoft.psd1’ module cannot be im
ported because its manifest contains one or more members that are not valid. The valid manifest members are (‘ModuleToP
rocess’, ‘NestedModules’, ‘GUID’, ‘Author’, ‘CompanyName’, ‘Copyright’, ‘ModuleVersion’, ‘Description’, ‘PowerShellVers
ion’, ‘PowerShellHostName’, ‘PowerShellHostVersion’, ‘CLRVersion’, ‘DotNetFrameworkVersion’, ‘ProcessorArchitecture’, ‘
RequiredModules’, ‘TypesToProcess’, ‘FormatsToProcess’, ‘ScriptsToProcess’, ‘PrivateData’, ‘RequiredAssemblies’, ‘Modul
eList’, ‘FileList’, ‘FunctionsToExport’, ‘VariablesToExport’, ‘AliasesToExport’, ‘CmdletsToExport’). Remove the members
that are not valid (‘RootModule’), then try to import the module again.
At line:1 char:14
+ Import-Module <<<< Peoplesoft
+ CategoryInfo : InvalidData: (C:\Windows\syst…Peoplesoft.psd1:String) [Import-Module], InvalidOperatio
nException
+ FullyQualifiedErrorId : Modules_InvalidManifestMember,Microsoft.PowerShell.Commands.ImportModuleCommand
It looks you might be running an older version or PowerShell, likely on Windows 7 or Server 2008/R2. There is a property in the module manifest, RootModule, that is not compatible. I will update the module shortly with a fix that should address this issue. In the meantime, if you’re feeling brave, you could open PeopleSoft.psd1 and remove the line beginning with RootModule. That should get you back in business.
Let me know how it goes.
You are absolutley correct….Windows 7.
I removed the line you suggested and gpt the following:
PS C:\Windows\system32> import-module peoplesoft
Import-Module : The module manifest ‘C:\Windows\system32\WindowsPowerShell\v1.0\Modules\peoplesoft\peoplesoft.psd1’ cou
ld not be processed because it is not a valid PowerShell restricted language file. Please remove the elements that are
not permitted by the restricted language: The string starting:
At C:\Windows\system32\WindowsPowerShell\v1.0\Modules\peoplesoft\peoplesoft.psd1:183 char:54
+ # D e f a u l t C o m m a n d P r e f i x = ‘ <<<< '
is missing the terminator: '.
At C:\Windows\system32\WindowsPowerShell\v1.0\Modules\peoplesoft\peoplesoft.psd1:191 char:2
+ <<<<
At line:1 char:14
+ import-module <<<< peoplesoft
+ CategoryInfo : ResourceUnavailable: (C:\Windows\syst…peoplesoft.psd1:String) [Import-Module], Missing
MemberException
+ FullyQualifiedErrorId : Modules_InvalidManifest,Microsoft.PowerShell.Commands.ImportModuleCommand
I continued down that path of removing the elements not permitted for several iterations before I decided to stop. Not certain what the impact my continued removal would have on the functionality of the tool.
Thanks for your help on this. Apologies for not being proficient in Powershell to troubleshoot thi myself.
After some thought, I have updated the compatibility for this module to PowerShell v.3.0. I have not tested the module on PowerShell v.2.0, and until I have time to test, I cannot verify that everything will work as expected. In the meantime, you do have the option to upgrade your PowerShell environment to version 3.0 (or 4.0, or the 5.0 preview – see http://technet.microsoft.com/en-us/library/hh857339.aspx). It is easy to do and worthwhile. See this article for instructions: http://technet.microsoft.com/en-us/library/hh847837.aspx.
I am sorry that my only solution is to upgrade, but for now that is the best I can do. I will work on testing the module in version 2.0 and see if it is feasible to backport the code.
Thanks for your feedback – I truly appreciate it!
Scott, thanks for all your help and for sharing so openly. I upgraded to version 3 and all is good.
The next adventure for me is to adapt and learn from what you have built to now try to manage a mixed Windows/Linux environment using similar tools. We have 130 servers in our various development/QA/stage/production environments so it is very much needed.
Thanks again!
Very nice collection of utilities! I guess i’ve been reinventing the wheel for a while too trying to come up with a set of my own. One thing i didn’t see in your utilities is a possibility to run domain administration tasks on a remote machine or using a certain user credentials. I am curious if you ever encountered a solution of how to administer an app server or process scheduler domain on a remote server either via Invoke-Command or have -ComputerName and -Credential type arguments on each of the utilities.
Thanks,
Andy
Very nice! Thank you for saving me from reinventing the wheel.
One edit I had to do was in Start-PsftDomain.ps1 within switch ($ServerType) where you had $PS_HOME, I changed to $PS_CFG_HOME for the path to the *.ubb files.