citrix gotoprovisioningapi powershell integration · citrix gotoprovisioningapi powershell...
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
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
Change properties and licenses of user ........................................................................................ 10
Delete a user.................................................................................................................................. 11
Create a user ................................................................................................................................. 11
The CitrixGotoUserAPI CmdLet source .................................................................................................. 12
Structure of project ........................................................................................................................... 12
Using the CitrixGotoUserAPI CmdLet
PowerShell The easiest way to start with PowerShell is to use the PowerShell Integrated Scripting Environment
(ISE). Select start menu type ‘power’ and start the PowerShell ISE.
The shell contains the Shell, an editor and a list of loaded cmdLet’s.
Load the module In the shell, navigate into the directory with the cmdLet AND the supporting JSON dll inside, i.e.
c:\tmp .
PS V:\> cd C:\Tmp
Import the CitrixGotoUserAPI.dll with the command ‘import-module .\CitrixGotoUserAPI.dll’
PS C:\Tmp> import-Module .\CitrixGotoUserAPI.dll
After this the cmdLet should be available. If you press the ‘Refresh’ button on commands tab, then
select the module ‘CitrixGotoUserAPI’, you should see the commands associated with that module.
or
First try Now let’s give the new commands a try. Try to login to API with the command ‘Get-
CitrixGoToUserAPI’. The easiest way to do this is to use the trial possibility of commands tab.
Select the command, enter your GoToMeeting admin account user, your password and press ‘Run’
button. If you prefer to type the commands, you will be glad to know that ISE has a great auto
completion.
After this you should see the resulting Connection Object properties.
Now let’s query for your user properties:
$Connection = Get-CitrixGoToUserAPI -AdminUser YourAdminUser -Password YourPassword
You need the connection Object for each command that gets or modifies data on API.
Get-UserByMail $Connection $Connection.Configuration.User
Get the user object for your own user. ($Connection.Configuration.User contains your email address.)
Command reference for the CitrixGotoUserAPI CmdLet
Data Objects The CitrixGotoUserAPI CmdLet brings 3 data objects.
GotoUserProvisioningAPI connection object
The connection object contains all the information required to use the Provisioning API.
AccessToken : 7su2*******************GnEnX Platform : GLOBAL IsLegacyPlatform : False User : Password : * Url : https://api.citrixonline.com Configuration : CitrixGotoUserAPI.RestConfiguration ProxyConfiguration : IsConnected : True
GotoUser data object
This object contains all the user properties returned from API. In addition it has 3 local properties.
1. ID is a read-only wrapper for organizerkey .
2. Products - a list of product names (as strings) for JSON compatibility. The setter initializes
the ProductList and LicencseList properties
3. ProductList – a list of product names (as enum values)
4. LicenseList – a list of licenses (as enum values)
ID : 5758378037920123398 products : {G2W, G2M} organizerkey : 5758378037920123398 groupkey : 0 email : [email protected] firstname : s_name0549 lastname : Test_RH0549 groupname : Testgruppe1 status : active maxnumattendeesallowed : 26 ProductList : {G2W, G2M} LicenseList : {G2W}
GotoUserList list object
The .ToString() function of the object offers compact presentation of users in the list. The list object
supports some filter functions, used by the Get-Filtered commands.
PS C:\tmp> Write-Host $G2TUsers User: 1918303991098535429 -> [email protected] (Test_RH0464, s_name0464) [G2T,G2W,G2M] State:active User: 1893638648912893 … 6197 -> [email protected] (FN0009, LN0009) [G2T,G2W,G2M] State:active User: 2872692178635714310 -> test_rh1123.s_name11 [email protected] (Test_RH1123, s_name1123) [G2T,G2W,G2M,OPENVOICE] State:active PS C:\tmp> $G2TUsers 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} … 6 Additional user listings … ID : 2872692178635714310 products : {G2T, G2W, G2M, OPENVOICE} organizerkey : 2872692178635714310 groupkey : 0 email : [email protected] firstname : s_name1123 lastname : Test_RH1123 groupname : Testgruppe1 status : active maxnumattendeesallowed : 26 ProductList : {G2T, G2W, G2M, OPENVOICE} LicenseList : {G2T, G2W, OPENVOICE} PS C:\tmp> $G2TUsers.ToString() User: 1918303991098535429 -> [email protected] (Test_RH0464, s_name0464) [G2T,G2W,G2M] State:active User: 2603607600619016197 -> [email protected] (FN0009, LN0009) [G2T,G2W,G2M] State:active … 5 Additional user listings … User: 2872692178635714310 -> [email protected] (Test_RH1123, s_name1123) [G2T,G2W,G2M,OPENVOICE] State:active
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
lastname : Test_RH0464 groupname : Testgruppe1 status : active maxnumattendeesallowed : 26 ProductList : {G2T, G2W, G2M, OPENVOICE} LicenseList : {G2T, G2W, OPENVOICE} And rename the user PS C:\Tmp> Set-UserName $Connection $PlayUser.ID "Hubert" "Someone" PS C:\Tmp> Get-User $Connection $PlayUser.ID ID : 1918303991098535429 products : {G2T, G2W, G2M, OPENVOICE} organizerkey : 1918303991098535429 groupkey : 0 email : [email protected] firstname : Hubert lastname : Someone groupname : Testgruppe1 status : active maxnumattendeesallowed : 26 ProductList : {G2T, G2W, G2M, OPENVOICE} LicenseList : {G2T, G2W, OPENVOICE} PS C:\tmp>
Delete a user PS C:\Tmp> Remove-User $Connection $PlayUser.ID PS C:\Tmp> Get-User $Connection $PlayUser.ID Get-User : The remote server returned an error: (404) Not Found. At line:1 char:1 + Get-User $Connection $PlayUser.ID + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : NotSpecified: (:String) [Get-User], GotoAPIException + FullyQualifiedErrorId : GetUser,CitrixGotoUserAPI.GetUser PS C:\Tmp>
Create a user PS C:\Tmp> Add-User $Connection $PlayUser.email G2T $PlayUser.firstname $PlayUser.lastname 6152222013362350597 PS C:\Tmp> Get-UserByMail $Connection $PlayUser.email ID : 6152222013362350597 products : {G2T, G2M} organizerkey : 6152222013362350597 groupkey : 0 email : [email protected] firstname : Test_RH0464 lastname : s_name0464 groupname : NA status : active maxnumattendeesallowed : 26 ProductList : {G2T, G2M} LicenseList : {G2T} PS C:\Tmp>
This was our trip through the lake of managing the GoTo products of your users. I don’t offer this trip
as a script file because you get more experience if you do this in the shell step by step. But – please
feel free to write your own scripts – it’s very easy.
The CitrixGotoUserAPI CmdLet source The CitrixGotoUserAPI CmdLet is a Snap-In module for PowerShell 3.0.
1. For an introduction on how to build PowerShell Snap-Ins please see:
http://blogs.msdn.com/b/saveenr/archive/2010/03/08/how-to-create-a-powershell-2-0-
module-and-cmdlet-with-visual-studio-2010-screencast-included.aspx
2. For documentation on how to work with GoTo Product API see:
https://developer.citrixonline.com/api/gotomeeting-rest-api/ for the organizer commands.
This project uses the 3rd party library to handle JSON form Newtonsoft:
http://james.newtonking.com/json
The project requires .Net 4.0 and PowerShell 3.0.
The project is built with Visual Studio 2012 SP1. Please open the ‘CitrixGotoProductsUserAPI.sln’ in
the CitrixGotoProductsUserAPI folder. The code is C#
The project also contains the test script TestScript.ps1, the init.ps1 and the batch job.
StartPowerShellISE.cmd. All three files will be copied to the binary folder to be used there. You have
to customize the PowerShell scripts with your accounts if you want use them.
In a binary context you can start the PowerShell ISE with the batch job. It starts the init.ps1 to start
the shell in a working state for experiments with the Provisioning API.
Structure of project The Project contains 3 code files:
1. GotoUser.cs
This file contains the GotoUser data class and the GotoUserList class. Both classes are
directly used in PowerShell. For deserializing from JSON to classes see the link at the top of
this file on the GotoUser class.
2. GotoProductAPI.cs
This file contains the GotoUserProvisioningAPI class and the configuration objects for this
class. The GotoUserProvisioningAPI class contains all functions to connect to the API and
deliver the requested objects. The class has no error handling – the consumer has to take
care of error handling. In the case of PowerShell, the console displays the exception
information in red and the information goes to the error stream.
The API Class and the Data classes can be used in each .Net project to use the Provisioning
API. These classes don’t contain special PowerShell code.
3. GotoUserAPICmdlet.cs
This file contains a separate class for each PowerShell command. These command classes are
wrappers for the GotoUserProvisioningAPI object with its functionality. These commands
make it very easy for the user to use the API. The PowerShell Integrated Scripting
Environment analyzes the structure and presents this to the user. Feel free to improve the
functionality to suit your needs.
If you start the project – the project starts the PowerShell with the TestScript.ps1. That’s my test
environment. It’s possible to debug the C# code in the debug mode.