## p4add-group
## aaron bockelie

<#
	.SYNOPSIS
	Creates a new group in AD and the Depot, then syncronizes the membership.
	.DESCRIPTION
	Creating a group in an AD integrated perforce depot does not require these additional groups. However, it is time consuming to maintain two group sets inside and outside of Perforce. This command suppliments the p4 group command by creating the group in Actite Directory as well as the depot. 
	.EXAMPLE
	This is the minimum required parameters needed to create a group:
	[PS] p4add-group -group groupname -users user.name
	Note that not supplying information for integer attributes will result in values of unset or zero, except for timeout which will default to 43200 seconds. Define the value timeout to override the default.
	.EXAMPLE
	This example adds multiple users to the group. Seperate usernames with a comma:
	[PS] p4add-group -group groupname -users user.name,another.user,onemore.user
	.EXAMPLE
	It is possible to define all attirbutes of the group:
	[PS] p4add-group -group groupname -maxresults 1000 -maxscanrows 1000 -maxlocktime 50000 -timeout 1000 -subgroups group1,group2,group3 -owners username1,username2,username3 -users username1,username2,username3, username4
	.PARAMETER group
	The name of the group
	.PARAMETER maxresults
	Limits the rows (unless 'unlimited' or 'unset') any one operation can return to the client.
	.PARAMETER maxscanrows
	Limits the rows (unless 'unlimited' or 'unset') any one operation can scan from any one database table.
	.PARAMETER maxlocktime
	Limits the time (in milliseconds, unless 'unlimited' or 'unset') any one operation can lock any database table when scanning data.
	.PARAMETER timeout
	A time (in seconds, unless 'unlimited' or 'unset') which determines how long a 'p4 login' session ticket remains valid (default is 12 hours).
	.PARAMETER subgroups
	Other groups automatically included in this group.
	.PARAMETER owners
	Users allowed to change this group without requiring super access permission.
	.PARAMETER users
	The users in the group.
	.FUNCTIONALITY
	Use this function to add define a new group in the Perforce depot.
#>

Function p4add-group
{param([Parameter(Mandatory=$true)]$group,$maxresults,$maxscanrows,$maxlocktime,$timeout,$passwordtimeout,[array]$subgroups,[array]$owners,[array]$users,[switch]$silent)

$servercheck = p4get-server #get the servercheck
if ($servercheck.pingsuccess.equals($true))
{
	$checkgroup = p4get-group $group
	
	if (!$checkgroup.owners -or !$checkgroup.subgroups -or !$checkgroup.users)
	{
		write-warning ("Assuming group " + $group + " is an Active Directory object only.")
	}
	$fqgroup = $null
	if (!$users -and !$subgroups)
	{
	write-error "No users or subgroups were specified. You must specify at least one user or subgroup. Use an array for multiple objects." -category InvalidData
	}
	else
	{
		$container = "p4" + $servercheck.server #build the root container name. There should only be one OU in the entire enterprise named this. if not , sucks to be you.
		try
		{
			$ou = get-qadobject -type 'organizationalUnit' $container #yoink the OU and store in $ou
		}
		catch
		{
			throw "Cannot obtain valid DN of Perforce authentication root group: " + $container
		}
		try
		{
			$fqgroup = get-qadgroup -samaccountname $group #check to see if active directory group already exists. This case is used when we are adding a new authgroup to the depot, because the authgroup doesn't reside in the same ou as the regular depot groups.
			if (!$fqgroup)
			{
				new-qadgroup -parentcontainer $ou.dn -name $group -samaccountname $group #create a new group under the ou.
			}
		}
		catch
		{
			throw "Unable to create Active Directory group `'CN=" + $group + "," + $ou.dn + "`'"
		}
	}
	if (!$fqgroup) #if we created a group instead of fetching a valid group, go ahead and validate group from AD.
	{
		$fqgroup = get-qadgroup -samaccountname $group #get a validated group object
	}
	if ($fqgroup -ne $null) #if validated group object is not null
	{
		$fqusers = New-Object System.Collections.ArrayList #these will not be the full object(s) in array, but a samaccountname that has been validated.
		$fqsubgroups = New-Object System.Collections.ArrayList #these will not be the full object(s) in array, but a samaccountname that has been validated.
		$fqowners = New-Object System.Collections.ArrayList #these will not be the full object(s) in array, but a samaccountname that has been validated.
		$i=0
		$userscount = $users.count
		foreach ($user in $users) #for each user in the raw unvalidated user list
		{	
			write-progress -id 101 -parentid 100 -activity "Validating users" -status "Validating user $user" -percentcomplete (($i/$userscount)*100)
			$fquser = $null
			$fquser = get-qaduser -samaccountname $user #get a qualified user object
			if ($fquser) #if the resulting object is not null
			{
				add-qadgroupmember $fqgroup $fquser >$null #add the validated user to the group.
				[void]$fqusers.add($fquser.samaccountname) #add the validated user samaccountname to the fqusers array.
			}
			else
			{
				$message = "User object `'" + $user + "`' not found in Active Directory. Not adding to new p4 group."
			}
			$i++
		}
		write-progress -id 101 -completed -activity "Complete." -status "Complete."
		foreach ($owner in $owners) #for each owner in the raw unvalidated owner list
		{
			if (p4get-authgroups | ?{$_.name -eq $group}) #if the group we are working on is considered an authentication group, select an account owner.
			{
				$supers = p4get-protect | ?{$_ -match "super user"}
				if ($supers.count -lt 2)
				{
					[void]$fqowners.add($supers.split(" ")[2])
				}
				else
				{
					write-warning "More than one direct super administrator account found. Selecting first account for group owner."
					[void]$fqowners.add($supers[0].split(" ")[2])
				}
			}
			$fqowner = $null
			$fqowner = get-qaduser -samaccountname $owner #validate a fqowner account
			if ($fqowner) #if an account is valid
			{
				[void]$fqowners.add($fqowner.samaccountname) #add into the owners array
			}
			else
			{
				$message = "Owner object `'" + $owner + "`' not found in Active Directory. Not adding to new p4 group."
			}
		}
		foreach ($subgroup in $subgroups) #for each subgroup in the raw unvalidated subgroup list
		{
			$fqsubgroup = $null
			$fqsubgroup = get-qadgroup -samaccountname $subgroup #validate the requested subgroup in AD
			if ($fqsubgroup -ne $null) #if the group actually exists
			{
				add-qadgroupmember $fqgroup $fqsubgroup >$null #add it to the new group we created.
				[void]$fqsubgroups.add($fqsubgroup.samaccountname) #add the validated subgroup samaccountname to the fqsubgroups array.
			}
			else
			{
				$message = "SubGroup object `'" + $subgroup + "`' not found in Active Directory. Not adding to new p4 group."
			}
		}
	}
	else
	{
		throw "Active Directory group `'CN=" + $group + "," + $ou.dn + "`'" + " did not get created. Cannot continue."
	}
	if ($timeout -eq $null)
	{
		$message = "Timeout value not specified. Defaulting to 43200 seconds (12 hours). Specify a timeout `'-timeout`' during group creation."
		write-warning $message
		$timeout = 43200
	}
	write-progress -id 101 -parentid 100 -activity "Submitting groupspec" -status "Waiting for Perforce" -percentcomplete 100
	$file = p4add-groupspec -group $fqgroup.samaccountname -users $fqusers -subgroups $fqsubgroups -owners $fqowners -maxresults $maxresults -maxscanrows $maxscanrows -maxlocktime $maxlocktime -timeout $timeout -passwordtimeout $passwordtimeout
	$result = $file | p4 group -i
}
else
{
	write-error "Unable to contact Perforce server." -category OperationTimeout
}
if ($silent -eq $false) #if silent is false, send result.
{
	$result
}
write-progress -id 101 -completed -activity "Complete." -status "Complete."
}