Citrix GotoProvisioningAPI PowerShell integration This sample illustrates GoTo Products Provisioning API integration with C# in .Net projects. It also shows how to use the PowerShell to manage your GoTo Products – GoToMeeting, GoToWebinar, GoToTraining and OpenVoice. The first part of this document explains how to use the ready compiled cmdLet in a Win7 PowerShell 3 environment for some typical tasks. The second part explains how to compile and modify the PowerShell cmdLet. Using the CitrixGotoUserAPI CmdLet ...................................................................................................... 2 PowerShell ........................................................................................................................................... 2 Load the module.................................................................................................................................. 2 First try ................................................................................................................................................ 4 Command reference for the CitrixGotoUserAPI CmdLet ........................................................................ 5 Data Objects ........................................................................................................................................ 5 GotoUserProvisioningAPI connection object .................................................................................. 5 GotoUser data object ..................................................................................................................... 5 GotoUserList list object ................................................................................................................... 6 Commands........................................................................................................................................... 6 Platforms ......................................................................................................................................... 6 Initiate API Connection .................................................................................................................... 7 Get List of Users............................................................................................................................... 7 Get/Create/Delete Users ................................................................................................................. 7 Set user properties and user state ............................................................................................. 7 Modify the Licenses of user (not supported on Classic platform) .............................................. 7 User list filter commands ................................................................................................................ 7 Filtered by enumerations of GotoUser object: ........................................................................... 8 Filtered by text properties:.......................................................................................................... 8 Filtered by numeric properties:................................................................................................... 8 Special user list commands: ........................................................................................................ 8 A tour through user provisioning ............................................................................................................ 8 Prerequisites........................................................................................................................................ 8 Get the list and extract the interesting users...................................................................................... 9 Suspend all users of a list .............................................................................................................. 10
12
Embed
Citrix GotoProvisioningAPI PowerShell integration · Citrix GotoProvisioningAPI PowerShell integration This sample illustrates GoTo Products Provisioning API integration with C# in
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Citrix GotoProvisioningAPI PowerShell integration
This sample illustrates GoTo Products Provisioning API integration with C# in .Net projects. It also
shows how to use the PowerShell to manage your GoTo Products – GoToMeeting, GoToWebinar,
GoToTraining and OpenVoice.
The first part of this document explains how to use the ready compiled cmdLet in a Win7 PowerShell
3 environment for some typical tasks.
The second part explains how to compile and modify the PowerShell cmdLet.
Using the CitrixGotoUserAPI CmdLet ...................................................................................................... 2
Load the module.................................................................................................................................. 2
First try ................................................................................................................................................ 4
Command reference for the CitrixGotoUserAPI CmdLet ........................................................................ 5
Data Objects ........................................................................................................................................ 5
Commands To see the list of parameters for the command, select the command from the command list
PowerShell ISE.
Platforms
The list of available commands depends on your account type. The account (or platform) type is
displayed when you print the Connection object (‘GLOBAL’ or ‘CLASSIC). Some commands are not
supported on the Classic platform, which will be noted on the command descriptions below.
Add-User – Attention this command has restrictions. You can only create the user. It’s not
possible to set the first and last name. It’s later not possible to change the product
assignment with API.
Set-UserName
Add-GotoLicence
Remove-GotoLicences
Set-GotoLicences
Initiate API Connection
Get-CitrixGoToUserAPI:
You get with a valid Goto user with admin rights and password a GotoUserProvisioningAPI
Object to use with other commands that need the ‘Connection’ parameter. If you copy the
‘AccessToken‘ parameter, you have the possibility to use the Get-CitrixGoToUserAPIByToken
command to create Connection objects without using explicit passwords.
Get-CitrixGoToUserAPIByToken: If you have a valid ‘AccessToken’ you can create the
GotoUserProvisioningAPI Object with this command. The access tokens are valid for ~1 year.
You must specify the platform parameter when you use this command, in order to get the
correct Connection object and make sure the commands you use afterwards are supported.
Get List of Users
Get-UserList: Get an ‘GotoUserList’ object with all your users. You can filter the result list
with filter commands.
Get/Create/Delete Users
Get-UserByMail: If the user mail address is available you can get the complete user
description with this command.
Get-User: If the user ID (organizerkey) is known (i.e. you got it from user list), you can get
the user description.
Add-User: Create a new Goto user with at least one license. The mail address has to be
unique for the whole GoTo System!
Remove-User: Delete the user on the GoTo System. The user is identified with his ID.
Set user properties and user state
Set-UserToSuspended: Deactivate the user. All licenses go back to the license pool. All stored
data of user are preserved.
Set-UserToActive: The user gets the licenses back he had, and gets access to his stored data.
Set-UserName (not supported on Classic platform): Change first and/or last name.
Modify the Licenses of user (not supported on Classic platform)
The API has no possibility to remove licenses. But there is a workaround. If you suspend the user he
loses all his licenses. And then it’s possible to add new licenses. These commands help you handle
licenses more easily.
Add-GotoLicence: Add a license to user. Attention: if user has an included product – like G2M
in G2W, the included product license will not be freed! You have to take care of this.
Remove-GotoLicences : Suspend the user to free all licenses.
Set-GotoLicences: Set a list of licenses for the user. This command takes care that the user
has only the assigned licenses.
User list filter commands
These commands offer you the possibility to filter the users by different criteria. You can implement
the AND operator by using the command on a filtered list, and implement the OR operator by the
Join-UserLists command. All filter commands support the optional Inverse parameter to implement
the NOT operator.
Filtered by enumerations of GotoUser object:
Get-FilteredUserListUserListByProduct: Looks if the ProductList array contains the product
(G2M, G2W, G2T, OPENVOICE).
Get-FilteredUserListUserListByLicense: Looks if the LicenseList array contains the product.
Get-FilteredUserListByStatus: filters by one of the 3 possible states of user (active,
suspended, Invited).
Filtered by text properties:
For the Text properties we have extended search possibilities. The search string can start or end with
a ‘*’. This means the value to search for ends or start with the string part, i.e, “Test*” delivers “Test”,
“Test123” and so on. There is also the possibility to use regular expressions. If the search string starts
with “REGEX:” the following part will be used as regular expression to the text property.
Get-FilteredUserListByLastName
Get-FilteredUserListByFirstName
Get-FilteredUserListByEmail
Get-FilteredUserListByGroupName
Filtered by numeric properties:
Numeric values can only be filtered by exact match.
Get-FilteredUserListByMaximumAttendeesAllowed
Get-FilteredUserListByGroupKey
Special user list commands:
Join-UserLists: Delivers a new joined user list. (As OR operator)
A tour through user provisioning The following samples are a tour through the usage of the PowerShell commands of Citrix
Provisioning API. The results of the command are specific to my (test) account – but you should have
the possibility to get very similar results.
Prerequisites 1. You need an account with administrative rights. This account needs to have the possibility to
manage (create/delete) additional accounts. You need unused licenses to play with the
commands.
2. It is best to have a test account for this – the users you creates, deletes or change the
licenses will get every time an email notification.
3. AND it’s dangerous if the accounts are used in real life, and are needed.
4. Open the PowerShell ISE as described in chapter ‘PowerShell’
5. Load the CitrixGotoUserAPI CmdLet module as described in chapter ‘Load the module’
6. Get the connection object as described in chapter ‘First try’
I expect that you have an open shell, loaded CitrixGotoUserAPI CmdLet, got a connection object in a
variable $Connection.
If this is done – let’s start ….
Get the list and extract the interesting users Get the list of all users – and store it in $AllUsers PS C:\tmp> $AllUsers = Get-UserList $Connection PS C:\tmp> $AllUsers.count 2149 We have in the Userlist $AllUsers 2149 Users! (for my Account) We want to select the users with G2W licenses. PS C:\tmp> $AllG2WUsers = Get-FilteredUserListUserListByLicense $AllUsers G2W PS C:\tmp> $AllG2WUsers.Count 1995 We have 1995 user with G2W licenses Now we want know which are test users – I use for this the domain jedix.com PS C:\tmp> $G2W_JEDIX_Users = Get-FilteredUserListByEmail $AllG2WUsers "*@jedix.com" PS C:\tmp> $G2W_JEDIX_Users.count 178 PS C:\tmp> $G2W_JEDIX_Users[0] ID : 2416081495841167366 products : {G2W, G2M} organizerkey : 2416081495841167366 groupkey : 0 email : [email protected] firstname : LN0021 lastname : FN0021 groupname : NA status : active maxnumattendeesallowed : 26 ProductList : {G2W, G2M} LicenseList : {G2W} But maybe 178 users are too much … Let’s look for G2T Licenses – there I have less PS C:\tmp> $G2TUsers = Get-FilteredUserListUserListByLicense $AllUsers G2T PS C:\tmp> $G2TUsers.count 8 That’s better – we have only 8 G2T Licenses And which users have we in jedix domain in range 0 to 100 ? PS C:\Tmp> $TempUsers = Get-FilteredUserListByEmail $AllUsers "REGEX:ln00[0-9]*@jedix.com" PS C:\Tmp> $TempUsers.count 98 Hmm, ok we miss 2 of them. Ohh – and want know how much real users I have – test users come from domains hh.zz (first users without working addresses -> bad) and from jedix.com PS C:\Tmp> (Get-FilteredUserListByEmail (Get-FilteredUserListByEmail $AllUsers "*@hh.zz" 1) "*@jedix.com" 1).count 6 PS C:\Tmp> (Get-FilteredUserListByEmail (Get-FilteredUserListByEmail $AllUsers "*@hh.zz" 1) "*@jedix.com" 1).ToString() User: 9201202932201148933 -> [email protected] (Test_RH1339, s_name1339) [G2W,G2M] State:active User: 8710299581630739205 -> [email protected] (Hahner, Robert) [G2M] State:active User: 8827265624664296965 -> [email protected] (Test_RH1341, s_name1341) [G2W,G2M] State:active User: 8768224050731168773 -> [email protected] (yyyy, yyyyy) [G2W,G2M,OPENVOICE] State:active User: 3041410038408019974 -> [email protected] (Hahner, Robert) [G2M,OPENVOICE] State:active User: 6090525113802979077 -> [email protected] (User, A) [G2M] State:active Ok, that’s not so much. PS C:\tmp>
Suspend all users of a list With the ForEach-Object command we iterate through each of these 8 G2T users – and suspend the user. PS C:\tmp> $G2TUsers | ForEach-Object {Set-UserToSuspended $Connection $_.ID} Check if the first G2T user is suspended PS C:\tmp> Get-User $Connection $G2TUsers[0].ID ID : 1918303991098535429 products : {} organizerkey : 1918303991098535429 groupkey : 0 email : [email protected] firstname : s_name0464 lastname : Test_RH0464 groupname : Testgruppe1 status : suspended maxnumattendeesallowed : 26 ProductList : {} LicenseList : {}
Change properties and licenses of user Select one user to play with and print start state PS C:\tmp> $PlayUser = $G2TUsers[0] PS C:\tmp> $PlayUser ID : 1918303991098535429 products : {G2T, G2W, G2M} organizerkey : 1918303991098535429 groupkey : 0 email : [email protected] firstname : s_name0464 lastname : Test_RH0464 groupname : Testgruppe1 status : active maxnumattendeesallowed : 26 ProductList : {G2T, G2W, G2M} LicenseList : {G2T, G2W} Create the array with products (G2W + G2T) PS C:\tmp> [CitrixGotoUserAPI.GotoUser+GotoProducts[]] $ProductArray = [CitrixGotoUserAPI.GotoUser+GotoProducts]::G2W, [CitrixGotoUserAPI.GotoUser+GotoProducts]::G2T Assign the products to user and get new state for user (It’s easier to use the product array of an existing user as a prototype) PS C:\tmp> Set-GotoLicences $Connection $PlayUser.ID $ProductArray PS C:\tmp> Get-User $Connection $PlayUser.ID ID : 1918303991098535429 products : {G2T, G2W, G2M} organizerkey : 1918303991098535429 groupkey : 0 email : [email protected] firstname : s_name0464 lastname : Test_RH0464 groupname : Testgruppe1 status : active maxnumattendeesallowed : 26 ProductList : {G2T, G2W, G2M} LicenseList : {G2T, G2W} Add also the Openvoice product and print new state PS C:\tmp> Add-GotoLicence $Connection $PlayUser.ID OPENVOICE PS C:\tmp> Get-User $Connection $PlayUser.ID ID : 1918303991098535429 products : {G2T, G2W, G2M, OPENVOICE} organizerkey : 1918303991098535429 groupkey : 0 email : [email protected] firstname : s_name0464