IPS PowerShell module (Automation cmdlets)
The IPS PowerShell module provides a set of cmdlets that can be used to perform administrative tasks for a PlanningSpace deployment. You can include the cmdlets in PowerShell scripts to automate tasks.
The module requires at minimum version 3.0 of PowerShell.
(Note for using PowerShell scripts for IPS administration: PowerShell has an ExecutionPolicy setting which is by default set to 'Restricted', which prevents all scripts from running. To use scripts for administration will require setting the ExecutionPolicy to 'RemoteSigned' (as generally recommended by Microsoft) or 'Unrestricted'.)
Installation: IPS Server
The module is installed automatically as part of the IPS Server installation. The files are installed in the 'Palantir' programs folder, for example 'C:\Program Files\Palantir\PalantirIPS 16.4\Powershell', and the Windows environment variable '$env:PSmodulepath' is modified to include this folder. You do not need to do any further installation if you are using the module on an IPS Server machine.
You can test that the module is installed correctly with the following PowerShell command:
PS> Get-Command -Module Palantir.IPS.Manager.Automation
You should see a listing of all of the cmdlets.
Download the module
The module can be downloaded as a ZIP file from the Aucerna Client Portal website at https://clients.aucerna.com/products/downloads: click the 'PlanningSpace' button and then click the 'PowerShell Module' download link. (Access to this site requires a user account: follow the instructions provided at the site if you need to register.)
Manual installation
The installation ZIP file contains two help files (README.txt and INSTALL.txt) and the folder 'Palantir.IPS.Manager.Automation' which contains all of the IPS PowerShell module files.
The folder needs to be installed at some place in your computer's PowerShell lookup path. Your 'PSModulePath' variable for PowerShell should look something like this, by default:
PS> $env:PSmodulepath
C:\Users\{USERNAME}\Documents\WindowsPowerShell\Modules;C:\Program
Files\WindowsPowerShell\Modules;C:\Windows\system32\WindowsPowerShell\v1.0\Modules
If you are non-Administrator user, copy the 'Palantir.IPS.Manager.Automation' folder into your own folder 'Documents\WindowsPowerShell\Modules':
- Create a folder 'C:\Users\{USERNAME}\Documents\WindowsPowerShell\Modules' (if it does not exist).
- Paste in a copy of the folder 'Palantir.IPS.Manager.Automation'.
If you are an Administrator user, you can make the module available to all users of a machine by adding the 'Palantir.IPS.Manager.Automation' folder to 'C:\Program Files\WindowsPowerShell\Modules'.
You can test that the module is installed correctly with the following PowerShell command:
PS> Get-Command -Module Palantir.IPS.Manager.Automation
You should see a listing of all of the cmdlets.
Using the cmdlets
All of the cmdlets, except for 'Test-Server', require a server login with 'Connect-IPSManager'. For example:
PS> Connect-IPSManager https://ips.mycompany.com
IsSuccess : True
Errors :
Url : https://ips.mycompany.com
ServerVersion : 16.3.206.121
UserName : MYCOMPANY\ipsadmin
IsMemberOfAdminGroup : True
IsServerLicensed : True
The authentication of your connection is based on the Windows user account that executes the 'Connect-IPSManager' command. The account must be a member of the IPS Administrators Group. (See Using IPS Manager.)
You should disconnect from the server when the connection is no longer required:
PS> Disconnect-IpsManager
Note on connection to an IPS server cluster: When you connect to a cluster of server machines, you have the option to connect via the load balancer, which will automatically select a server machine to connect to, or to connect directly to a specific server machine. There are a few cmdlets intended for use with specific servers, when adding or removing machines to/from a cluster, or changing the primary server machine: Get-IsPartOfCluster, Get-IsPrimaryServer, Join-ClusterAsPrimaryServer, and Join-ClusterAsSecondaryServer.
For explanation of the settings that are covered by the cmdlets, see IPS Server configuration, Licensing and Applications settings.
Using the module help information
The cmdlets follow the standard PowerShell 'verb-noun' convention.
The module contains comprehensive help information for all of the cmdlets. Use the table of cmdlets below to look up a cmdlet name and then access the help information with 'Get-Help'. For example:
PS> Get-Help Get-TenantClusterTempFolder -full
You can use the Windows Powershell ISE tool to explore the contents of the module: open the Command add-on and in the 'Module' selection box select 'Palantir.IPS.Manager.Automation'.
Cmdlet listing for Palantir.IPS.Manager.Automation
This table is correct for IPS Server version 16.4.
For explanation of the settings that are covered by the cmdlets, see IPS Server configuration, Licensing and Applications settings.
| Cmdlet name | Description |
|---|---|
| Add-ApplicationAccess | Gives the specified tenant access to the specified application group. |
| Add-Tenant | Adds a new tenant to the current IPS server. |
| Clear-UserSession | Removes user sessions. The tenant must be specified if the license server is in PerTenant mode. If the license server is in CentralizedPool mode, all user sessions will be removed. |
| Connect-IpsManager | Connects to a running instance of IPS Manager. Connection will be granted if the current Windows user is a member of the IPS Administrators Group. Except for the Test-Server cmdlet, all other cmdlets require the Connect-IpsManager cmdlet to be called first. |
| Disable-Tenant | Disables the specified tenant. |
| Disconnect-IpsManager | Disconnects from the current IPS Manager session and removes all PowerShell session variables associated with it. |
| Enable-Tenant | Enables the specified tenant. |
| Get-Application | Retrieves a list of the PlanningSpace and SUITE cx applications deployed in the current IPS server. |
| Get-ApplicationCachePort | Retrieves the Distributed Cache Port setting for the specified application. Value 0 means the application does not use this type of port. |
| Get-ApplicationClientSetting | Retrieves the specified application client setting for the specified tenant. |
| Get-ApplicationEventLogLevel | Retrieves the Event Log Level setting for the specified application (which applies to all server machines and all tenants). |
| Get-ApplicationGroup | Retrieves a list of application groups for the current IPS server. |
| Get-ApplicationMainLogLevel | Retrieves the Main Log Level setting for the specified application (which applies to all server machines and all tenants). |
| Get-ApplicationProcessingPort | Retrieves the Distributed Processing Port setting for the specified application. Value 0 means the application does not use this type of port. |
| Get-ApplicationProcessorAffinity | Retrieves a list of processors that are bound to the specified application process on the specified server (e.g. a returned list '1,3,4' means that CPU1, CPU3, and CPU4 are bound to the application process). |
| Get-ApplicationServiceSetting | Retrieves the specified Service, Server or Tenant setting for the specified application (a server name or tenant name must be specified as required). |
| Get-AuthorizedClusterGroup | Retrieves the authorized cluster group setting for the current IPS server. |
| Get-ClusterPort | Retrieves the Cluster Port setting for the current IPS server. |
| Get-EventLogLevel | Retrieves the Event Log Level setting for the current IPS server. |
| Get-GenerateMemoryDump | Retrieves the Boolean value of this diagnostics setting. If set to True, a memory dump file will be written when an unhandled exception occurs on a server machine. |
| Get-IpsServerLicense | Retrieves a list with details for all the current server licenses in the IPS Server. Revoked licenses are excluded. |
| Get-IsPartOfCluster | Checks if the current server is part of an IPS server cluster. |
| Get-IsPrimaryServer | Checks if the current server is the primary server of an IPS cluster. |
| Get-LicenseServerUrl | Retrieves the base URL of the license server. If the license server is in PerTenant mode, the tenant must be specified. |
| Get-LicensingMode | Retrieves the product licensing mode of the server ('CentralizedPool' or 'PerTenant'). |
| Get-MailSettings | Retrieves the Mail and SMTP settings for the current IPS server. |
| Get-MainLogLevel | Retrieves the Main Log Level setting for the current IPS server. |
| Get-MaxWorkerUsage | Retrieves the setting for the maximum number of worker processes allowed for the specified server machine and specified processing category (use cmdlet Get-ProcessingCategoryList to get the category names). |
| Get-MonitorPort | Retrieves the Monitor Port setting for the current IPS server. |
| Get-PeriodicTaskPoolSize | Retrieves the current value of Periodic Tasks Pool Size for the specified server machine. |
| Get-ProcessingCategoryList | Retrieves the list of processing categories for the current IPS server. |
| Get-ProcessorAffinity | Retrieves a list of the processors in the specified server machine that are currently allocated for use by IPS Worker processes in the specified category (use cmdlet Get-ProcessingCategoryList to get the category names). |
| Get-ProcessorList | Retrieves a list of the processors in the specified server machine that are available to be used by IPS Workers. (To get or set the processor affinity settings, use the Get-ProcessorAffinity or Set-ProcessorAffinity cmdlet.) |
| Get-ProductLicense | Retrieves a list of all the current product licenses in the license server. If the license server is in PerTenant mode, the tenant must be specified. Revoked licenses will be excluded. |
| Get-ProxySetting | Retrieves the proxy setting for the license server, and the license forward address if it is set. If the license server is in PerTenant mode, the tenant must be specified. |
| Get-ServerAddress | Retrieves the service address setting of the current IPS server. |
| Get-ServerList | Retrieves the list of servers in the current IPS server cluster. For a standalone server this will return a list of one. |
| Get-ServerSetting | Retrieves the value of the specified Server setting (both the Category and Name must be specified), for the specified server machine. (Only the 'Advanced' settings are handled by this cmdlet.) |
| Get-ServerTaskPoolSize | Retrieves the current value of Server Tasks Pool Size for the specified server machine. |
| Get-ServiceCertificate | Retrieves the service certificate settings for the current IPS server. |
| Get-ServiceSetting | Retrieves the value of the specified Service setting (both the Category and Name must be specified). |
| Get-ShowTenantsOnRootPage | Retrieves the Boolean value of the setting that controls whether a list of tenant names is shown in the tenant web login screen. |
| Get-Tenant | Retrieves a list of tenants in the current IPS server. |
| Get-TenantApplication | Retrieves a list of application groups which the specified tenant has access to. |
| Get-TenantClusterTempFolder | Retrieves the cluster shared temp folder location for the specified tenant. |
| Get-TenantDataSource | Retrieves the data source (tenant database) information for the specified tenant. |
| Get-TenantSAML2IdentityProvider | Gets the SAML2 identity provider of the specified tenant. |
| Get-TenantTokenLifetime | Gets the token lifetime of the specified tenant. |
| Get-UserSession | Retrieves a list of current user sessions from the license server. If the license server is in PerTenant mode, the tenant must be specified. |
| Get-WebServerPort | Retrieves the web server port setting for the current IPS server. |
| Get-WorkerCount | Retrieves the setting for the maximum number of concurrent workers allowed on the specified server machine. |
| Import-IpsServerLicense | Imports an IPS server license from an XML file at the specified location. |
| Import-ProductLicense | Imports a product license from an XML file at the specified location. If the license is for a particular tenant, the tenant name must be specified. |
| Join-ClusterAsPrimaryServer | Configures an IPS cluster to add the connected IPS server machine as the cluster's primary server. |
| Join-ClusterAsSecondaryServer | Configures an IPS cluster to add the connected IPS server machine as a secondary server. |
| Remove-ApplicationAccess | Removes the specified tenant's access to the specified application group. |
| Remove-ProductLicense | Removes a product license from the license server, using the specified license ID. Removing a license cannot be undone, and the license cannot be re-imported from an XML file that was already used. |
| Remove-Tenant | Removes the specified tenant from the current IPS server. |
| Remove-UserSession | Removes a user session from the license server, using the specified Session ID. If the license server is in PerTenant mode, the tenant must be specified. |
| Reset-ApplicationClientSetting | Resets the specified application client setting to its default value, for the specified tenant. |
| Reset-ApplicationServiceSetting | Resets to the default value for the specified Service, Server or Tenant setting for the specified application (a server name or tenant name must be specified as required). |
| Reset-ServerSetting | Resets the specified Server setting to its default value (both the Category and Name must be specified), for the specified server machine. (Only the 'Advanced' settings are handled by this cmdlet.) |
| Reset-ServiceSetting | Resets the specified Service setting to its default value (both the Category and Name must be specified). |
| Restart-Application | Restarts the specified application in the IPS Server. |
| Set-ApplicationCachePort | Sets the Distributed Cache Port number for the specified application. |
| Set-ApplicationClientSetting | Sets the value of the specified application client setting for the specified tenant. It can also be used to change the scope of the setting (Tenant or User). |
| Set-ApplicationEventLogLevel | Sets the Event Log Level setting for the specified application (which applies to all server machines and all tenants). |
| Set-ApplicationMainLogLevel | Sets the Main Log Level setting for the specified application (which applies to all server machines and all tenants). |
| Set-ApplicationProcessingPort | Sets the Distributed Processing Port number for the specified application. |
| Set-ApplicationProcessorAffinity | Allocates or de-allocates a processor to or from the specified application process on the specified server, e.g. the ProcessorList input '1,3,4' means that CPU1, CPU3, and CPU4 will be bound to the application process. Any processor not included in the ProcessorList input will be de-allocated. |
| Set-ApplicationServiceSetting | Sets the value of the specified Service, Server or Tenant setting for the specified application (a server name or tenant name must be specified as required). |
| Set-AuthorizedClusterGroup | Sets the authorized cluster group for the current IPS server. |
| Set-ClusterPort | Sets the Cluster Port number for the current IPS server. |
| Set-EventLogLevel | Sets the Event Log Level for the current IPS server. |
| Set-GenerateMemoryDump | Sets the Boolean value of the Generate Memory Dump diagnostics setting. If set to true, a memory dump file will be written when an unhandled exception occurs on a server machine. |
| Set-LicensingMode | Sets the product licensing mode of the server. The valid modes are CentralizedPool and PerTenant. |
| Set-MailSettings | Sets the Mail and SMTP settings for the current IPS server. |
| Set-MainLogLevel | Sets the Main Log Level setting for the current IPS server. |
| Set-MaxWorkerUsage | Sets the maximum number of worker processes allowed for the specified server machine and specified processing category (use cmdlet Get-ProcessingCategoryList to get the category names). |
| Set-MonitorPort | Sets the Monitor Port number for the current IPS server. |
| Set-PeriodicTaskPoolSize | Sets the value of Periodic Tasks Pool Size for the specified server machine. |
| Set-ProcessorAffinity | Sets which processors in the specified server machine should be allocated for use by IPS Worker processes in the specified category (use cmdlet Get-ProcessingCategoryList to get the category names). To de-allocate a processor, do not include it in ProcessorsList. |
| Set-ProxySetting | Changes the proxy setting for the product license server. If IsInProxyMode is set to True (1) then a license ForwardAddress must be specified. If the license server is in PerTenant mode, the tenant must be specified. |
| Set-ServerAddress | Sets the service address setting of the current IPS server. |
| Set-ServerSetting | Sets the value of the specified Server setting (both the Category and Name must be specified), for the specified server machine. (Only the Advanced settings are handled by this cmdlet.) |
| Set-ServerTaskPoolSize | Sets the value of Server Tasks Pool Size for the specified server machine. |
| Set-ServiceCertificate | Sets the service certificate configuration for the current IPS server. |
| Set-ServiceSetting | Sets the value of the specified Service setting (both the Category and Name must be specified). |
| Set-ShowTenantsOnRootPage | Sets the Boolean value that controls whether a list of tenant names is shown in the tenant web login screen. |
| Set-TenantClusterTempFolder | Sets the cluster shared temp folder location for the specified tenant. To use this cmdlet, the data source (tenant database) must be set first. All IPS and SQL server machines must have access rights to the share location. |
| Set-TenantDataSource | Sets the data source (tenant database) for the specified tenant. |
| Set-TenantSAML2IdentityProvider | Sets the SAML2 identity provider of the specified tenant. |
| Set-TenantTokenLifetime | Sets the token lifetime of the specified tenant. |
| Set-WorkerCount | Sets the maximum number of concurrent workers allowed on the specified server machine. |
| Test-Server | Performs tests to check if the applications hosted in the specified IPS server are accessible. This cmdlet does not require Connect-IpsManager to be called first. |
| Use-Http | Configures the current IPS server to use HTTP. |
| Use-SecureHttp | Configures the current IPS server to use secure HTTP (HTTPS). |