Working With User Properties

#Depreciated Yeah, sorry. So this was rubbish. I've left it in for version 0.0.9.0, but I'll be taking it out in v0.1.0.0. Instead, look for cmdlets that end in *Obj - these will create the objects you need when a Cmdlet requires a complex object instead of just a single set of parameters. Uh, I'll write something up on that soon. If not, find me and yell at me.

#User Properties One of the newest features of gShell is the option to work with what I call 'additional properties'. These properties differ from regular user properties mostly in ways that will hopefully not be too apparent to you. However, they certainly require a bit more knowledge to use appropriately.

###How to Use it? Since getting the User Properties is pretty self explanatory, I'll focus here on creating and updating properties.

The high-level overview is:

• You can use [[Set-GAUser]] to update a user's additional properties by supplying a GAUserPropertyCollection for the -PropertyCollection parameter.
• A GAUserPropertyCollection can hold all 7 types of the additional properties, and multiple instances of each type.
  • A blank GAUserPropertyCollection can be created with [[New-GAUserPropertyCollection]]
• A single instance of one of these property types is a GAUserProperty object.
  • A blank GAUserProperty can be created with [[New-GAUserProperty]].

###Creating a User Property

To create a new User Property, you use the [[New-GAUserProperty]] cmdlet. Please keep in mind this only returns a new object, and doesn't update anything on the server! As such, you're best off throwing this in a variable.

When creating the object, you really need to make your first parameter the -PropertyType. Depending on what you choose for this parameter, other context-specific parameters will become available. For instance, if you choose 'Im' then you will see the Protocol parameter, but 'Address' shows a CountryCode. Each one of these property types will also return a different, specific object type.

An example of creating a Phone property:

$Phone = New-GAUserProperty -PropertyType phone -Type callback -Value "867-5309"

###Adding to the Collections

The collections have methods on them which allow easy adding of any GAUserProperty type object. Given a collection $UPC and a property $Phone, you can do the following:

$UPC.Add($Phone)

Or, if you want to not set it to a variable first you can create it directly in the method (note the double parenthesis - one set is for the method, the other is to enclose the Cmdlet to be sure it executes fully before going in to the method):

$UPC.Add( (New-GAUserProperty -PropertyType phone -Type callback -Value "867-5309") )

###Updating the User

Once you have the GAUserPropertyCollection all set up, you need to update the user with it. You can easily do this by passing it through the [[Set-GAUser]] cmdlet using the -PropertyCollection parameter:

Set-GAUser MyUser -PropertyCollection $UPC

Important! If you want to update or add only one User Property, you MUST first retrieve the collection of all types of that property and work with the set of properties as a whole.

For instance, if you have a user with three Im properties already saved and you want to update the third one, you must first retrieve all three Im properties, make the desired changes and then put all three Im properties back in to a collection to pass to Set-GAUser. If you do not, Google will only save the one that you provided in the collection and all other Im type properties will be lost.

Note: If any property types in the collection are null (empty), they will be ignored. If you want to delete any of these 7 properties, you'll need to use the separate [[Remove-GAUserProperty]] cmdlet.

Note: At this time, there is a bug in the underlying API that prevents full removal of any of these 7 types. Please see the Remove-GAUserProperty information for more details.

###Can this be better? I'm sure that I didn't set this up to work in the most efficient way. As such, I'm open to ideas on how to improve this workflow - as long as it makes sense and doesn't mess up the main concepts of how gShell and PowerShell work.

###Future things

I plan on setting it up so that you can pipe a user to New-GAUserPropertyCollection at some point, or even to one of the other New-GAUserProperty cmdlet variations, but for now that's not the case. I also plan on making it easier to get the existing properties from a user and updating them and pushing them back. Finally, I think it might be nice to round out these Cmdlets with a Set-GAUserProperty cmdlet, but for now it doesn't exist since you can use Set-GAUser.

###Under the Hood To give some background on why this had to be created the way it was. Most properties for a user are one-to-one, meaning that you have one place to put that information and that's it. There is one place for a first name, and one place for a last name. You can't have multiple last names.

With these additional properties, you can have more than one of them, or none at all. The problem is that Google stores this information all as one blob of information. Let's take the Addresses as an example. When you create a user by hand through the admin console, you have the option to create it with some 'additional properties.' Here you can specify an address.

With gShell and other API programs, you can go more in to detail with the Address, and add more. So, let's say you create five total. Instead of keeping them separate, Google holds all of them together, like a bunch of papers in a briefcase. If you want to get that information back out, you don't get the individual papers - you get the whole briefcase.

If you want to remove a paper from that briefcase, you don't just ask the person holding the briefcase to find the paper named 'x' and remove it, like you would an alias. You are given the whole briefcase, and it's up to you to find the paper, remove that paper and put all the other papers back, put them back in the briefcase the way it was and hand it back.

So what! you say. And, indeed you should. gShell does most of this for you. The reason I mention it is because it's a wiki, and I'm allowed to be long-winded! But also to help illustrate why this is separate and more complex than the other standard properties.