XPhone Connect Server login

To start a PowerShell session, the user must authenticate himself on the XPhone Connect Server. The login dialog appears automatically after entering the first command. The required access data corresponds to that of the XPhone Connect Server administration portal. Once entered, the login information is retained until the PowerShell console is closed or a timeout (20 minutes) occurs.

Hint

The specified user must be XPhone Connect System Administrator.

Use commands and parameters

General command structure

All commands of the XPhone Connect Powershell extension start with the prefix Xp. You can switch through the available commands by entering Get-Xp, for example, and then pressing the tab key without having to type them in completely each time (Auto Completion).

Command pipeline

The pipeline allows you to quickly and easily pass results from one command to the next without having to cache the previous result.

The following commands are first entered manually one after the other. The result of a command is used as the input for the following command:

>$locations = Get-XpLocations;
>$confGroups = Get-XpConfigGroups -Locations $locations;
>$clientTemplates = Get-XpClientTemplates $confGroups;

This expression can be shortened using the pipeline as follows:

>Get-XpLocations | Get-XpConfigGroups | Get-XpClientTemplates

The result of Get-XpLocations is immediately used as a parameter of Get-XpConfigGroups. The result of Get-XpConfigGroups is in turn used as a parameter of Get-XpClientTemplates.

If you want to explicitly address the object passed through the pipeline, use $_:

>Get-XpUsers | foreach{$_.Department = „Entwicklung“;$_}

Command syntax with parameters

Commands are often supplemented by parameters - required or optional. The syntax of a command with parameters is noted as follows:

>Befehl -Parametername <Parametertyp[]> [-Parametername <Parametertyp[]>]

Example:

>Get-XpConfigGroups -LocationNames <String[]> [-ConfigGroupNames <String[]>]

Parameter name

Parameters can be addressed either explicitly via their name or implicitly via their position. Parameters are most frequently set depending on their position. The order in which the parameters are specified in the “Syntax” area reflects their position in the command. This is only possible if the parameter name is specified in square brackets “[]”. This indicates that the parameter name is optional and that the parameter can also be recognized by its position:

>Get-XpLocations "Hauptstandort"

“Main location” is inserted at position 1, thus in this case as a value for the -LocationNames parameter.

Equivalent to this would be the explicit specification:

>Get-XpLocations -LocationNames "Hauptstandort"

To additionally filter by the configuration group names, the parameter -ConfigGroupNames must be specified with:

>Get-XpConfigGroups "Hauptstandort" -ConfigGroupNames "Konfigurationsgruppe123"

“ConfigurationGroup123” cannot be recognized by its position (recognizable by the missing square brackets in the syntax description), so the parameter name -ConfigGroupNames must be specified explicitly.

Parameter type

The parameter type specifies what kind of data can be passed to the command.

In this case the type is String, i.e. text.

List of parameter values

If there are square brackets [] behind a parameter type, a list of parameter values can be specified, the individual parameter values are to be separated by commas:

>Get-XpConfigGroups -LocationNames "Hauptstandort","Nebenstandort"

The possible options for calling the Get-XpConfigGroups command compared:

-LocationNames <String[]> [[-ConfiggroupNames] <String[]>]

Execution with explicit specification of all parameters:

>Get-XpConfigGroups -LocationNames „Hauptstandort" -ConfigGroupNames „KonfigGruppe1"

Implicit specification of -LocationNames:

>Get-XpConfigGroups "Hauptstandort" -ConfigGroupNames "KonfigGruppe1"

Implicit specification of -LocationNames with a list of locations:

>Get-XpConfigGroups -LocationNames "Hauptstandort","Nebenstandort" -ConfigGroupNames *

Display properties of objects

Some commands, such as Get-XpLocations, do not show all their properties for clarity. On the other hand, commands such as Get-XpClientTemplates show all their properties, so the output may become cluttered.

The command Select-Object can be used to format the output of object properties - i.e. to hide or display properties. A list of properties to be displayed is passed as a parameter.

Show all properties

The command parameter * stands for all properties.

Show all properties of the object CFGBranch, which is output as a result of the command Get-XpLocations:

>Get-XpLocations | Select-Object *

Show specific properties

The list of properties to be displayed is passed as a parameter, the properties are separated by commas.

Show a list of all client templates (sites) from all default configuration groups, but only the following object properties:

LocationName (Name of the location)
ConfigurationGroupName (name of the configuration group)
TeamviewPanelActive (Team panel active/inactive status)

>Get-XpLocations | Get-XpConfigGroups | Get-XpClientTemplates | Select-Object LocationName,ConfigurationGroupName,TeamviewPanelActive

Show help

If you want to know what properties the command has and not the object or objects, query that with Get-Help:

PS C:\Users\Administrator> Get-Help Get-XpUsers -Parameter *

-Timeout <int>
    WCF Operation Timeout in Minutes. Default = 1

    Required?                    false
    Position?                    Named
    Accept pipeline input?       false
    Parameter set name           (All)
    Aliases                      None
    Dynamic?                     false


-UserNames <string[]>
    Search pattern for users

    Required?                    false
    Position?                    0
    Accept pipeline input?       true (ByValue, ByPropertyName)
    Parameter set name           (All)
    Aliases                      None
    Dynamic?                     false

Filter objects

In some cases, the parameters of the commands are not sufficient to limit the result set sufficiently. A more specific selection can then be made with the Where-Object (alias Where) command.

All users whose department is called “Software Development”:

>Get-XpUsers | Where{$_.Department -eq „Software Development“}

Where -eq stands for equal. This means that the Department property is checked for equality with the Software Development string. You can also use -ne for not equal (unequal) or -match (contains), for example.

All users whose department is not “Software Development”:

>Get-XpUsers | Where{$_.Department -ne „Software Development“}

All users whose department contains Software, for example Software Development or also Software Marketing:

>Get-XpUsers | Where{$_.Department -Match „Software“}

Hint

Upper and lower case must be taken into account in the comparison values (software != software)!

Have you found a mistake on this page?

Or is something not formulated well or too vague? Then we look forward to receiving an e-mail, preferably with a suggestion for improvement, to doku@c4b.de. Thank you very much!