Adds Helix event endpoints

verkadaModule/Public/Add-VerkadaHelixEvent.ps1

@@ -35,9 +35,13 @@ function Add-VerkadaHelixEvent{
 		[Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
 		[ValidatePattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$')]
 		[String]$event_type_uid,
-		#The the epoch time of the event
-		[Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
+		#The the timestamp of the event
+		[Parameter(ValueFromPipelineByPropertyName = $true)]
 		[datetime]$timeStamp,
+		#The the epoch time of the event in milliseconds
+		[Parameter(ValueFromPipelineByPropertyName = $true)]
+		[Alias("time_ms")]
+		[Int64]$epoch_time,
 		#The parameters to be submitted for the event
 		[Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
 		[object]$attributes,
@@ -65,7 +69,13 @@ function Add-VerkadaHelixEvent{
 	} #end begin
 
 	process {
-		$epoch_time = (New-TimeSpan -Start (Get-Date "01/01/1970") -End $timeStamp.ToUniversalTime()).TotalMilliseconds
+		if ($PSBoundParameters.ContainsKey('epoch_time')){
+
+		} elseif ($PSBoundParameters.ContainsKey('timeStamp')){
+			$epoch_time = (New-TimeSpan -Start (Get-Date "01/01/1970") -End $timeStamp.ToUniversalTime()).TotalMilliseconds
+		} else {
+			throw "timestamp or epoch_time (time_ms) are required"
+		}
 		$body_params = @{
 			'camera_id'				= $camera_id
 			'event_type_uid'	= $event_type_uid

verkadaModule/Public/Find-VerkadaHelixEvent.ps1

@@ -0,0 +1,146 @@
+function Find-VerkadaHelixEvent{
+	<#
+		.SYNOPSIS
+		Finds Helix event using https://apidocs.verkada.com/reference/postvideotaggingeventsearchviewv1
+
+		.DESCRIPTION
+		This method can be used to search for either a single or multiple Helix Events that have already been posted to Command. In the return message, the users will be able to see the corresponding attribute keys and attribute values for those specific Helix Events.
+
+		The only required parameters to search for Helix Events is a Verkada API Token with Helix permissions. Users will be returned a complete list of all Helix Events that are currently available in Command. Users can further narrow down their search by adding:
+
+		Camera ID: returns all Helix Events linked to that specific camera or list of cameras.
+		Event Type UID: returns all Helix Events that share that specific Event Type UID.
+		Start and End Times: returns all Helix Events that have occurred during that time range.
+		Attributes Keys and Values: returns all Helix Events that have attributes keys and values matching the user's entered parameters.
+		The org_id and reqired token can be directly submitted as parameters, but is much easier to use Connect-Verkada to cache this information ahead of time and for subsequent commands.
+
+		.LINK
+		https://github.com/bepsoccer/verkadaModule/blob/master/docs/function-documentation/Find-VerkadaHelixEvent.md
+
+		.EXAMPLE
+		Find-VerkadaHelixEvent -camera_id 6b8731d7-d991-4206-ba71-b5446fa617fc
+		This will get the helix events for camera_id 6b8731d7-d991-4206-ba71-b5446fa617fc. The org_id and token will be populated from the cached created by Connect-Verkada.
+
+		.EXAMPLE
+		Find-VerkadaHelixEvent -event_type_uid cf918b16-26cd-4c01-a672-5a91b79311e1 -startTimeStamp '1/1/2025 08:35:00 -06' -endTimeStamp '1/7/2025 17:00:00 -06' -org_id '7cd47706-f51b-4419-8675-3b9f0ce7c12d' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		This will find the helix events for from Jan 1, 2025 at 8:35 AM CST to Jan 7, 2025 at 5:00 APM CST for the sepcified event ID. The org_id and token are submitted as parameters in the call.
+	#>
+	[CmdletBinding(PositionalBinding = $true)]
+	[Alias("Find-VrkdaHlxEvt","fd-VrkdaHlxEvt")]
+	param (
+		#The UUID of the organization the user belongs to
+		[Parameter(ValueFromPipelineByPropertyName = $true)]
+		[ValidateNotNullOrEmpty()]
+		[ValidatePattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$')]
+		[String]$org_id = $Global:verkadaConnection.org_id,
+		#The UUID of the camera who's name is being changed
+		[Parameter()]
+		[ValidatePattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$')]
+		[Alias("cameraId","cameraIds","camera_id")]
+		[String[]]$camera_ids,
+		#The UID of the event type to be used when creating the event
+		[Parameter()]
+		[ValidatePattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$')]
+		[String]$event_type_uid,
+		#The the start timestamp of the events being serached
+		[Parameter()]
+		[datetime]$startTimeStamp,
+		#The the epoch start time of the events being serached in milliseconds
+		[Parameter()]
+		[Alias("start_time_ms")]
+		[Int64]$start_epoch_time,
+		#The the end timestamp of the events being serached
+		[Parameter()]
+		[datetime]$endTimeStamp,
+		#The the epoch end time of the events being serached in milliseconds
+		[Parameter()]
+		[Alias("end_time_ms")]
+		[Int64]$end_epoch_time,
+		#The attribute filters to be used in the search query
+		[Parameter()]
+		[object[]]$attribute_filters,
+		#The keyword/s to be used in the search query
+		[Parameter()]
+		[Alias("keyword")]
+		[string[]]$keywords,
+		#Boolean if the event should be flagged
+		[bool]$flagged=$false,
+		#The public API token obatined via the Login endpoint to be used for calls that hit the public API gateway
+		[Parameter()]
+		[ValidateNotNullOrEmpty()]
+		[String]$x_verkada_auth_api = $Global:verkadaConnection.x_verkada_auth_api,
+		#The region of the public API to be used
+		[Parameter()]
+		[ValidateSet('api','api.eu','api.au')]
+		[String]$region='api',
+		#Switch to write errors to file
+		[Parameter()]
+		[switch]$errorsToFile
+	)
+
+	begin {
+		$url = "https://$($region).verkada.com/cameras/v1/video_tagging/event/search"
+		#parameter validation
+		if ([string]::IsNullOrEmpty($org_id)) {throw "org_id is missing but is required!"}
+		if ([string]::IsNullOrEmpty($x_verkada_auth_api)) {throw "x_verkada_auth_api is missing but is required!"}
+		$myErrors = @()
+	} #end begin
+
+	process {
+		if (!($PSBoundParameters.ContainsKey('start_epoch_time')) -and $PSBoundParameters.ContainsKey('startTimeStamp')){
+			$start_epoch_time = (New-TimeSpan -Start (Get-Date "01/01/1970") -End $startTimeStamp.ToUniversalTime()).TotalMilliseconds
+		}
+		if (!($PSBoundParameters.ContainsKey('end_epoch_time')) -and $PSBoundParameters.ContainsKey('endTimeStamp')){
+			$end_epoch_time = (New-TimeSpan -Start (Get-Date "01/01/1970") -End $endTimeStamp.ToUniversalTime()).TotalMilliseconds
+		}
+
+		$body_params = @{
+			'flagged'	= $flagged
+		}
+
+		$query_params = @{}
+
+		#add any of the optional query parameters to the body
+		if (!([string]::IsNullOrEmpty($keywords))){$body_params.keywords = $keywords}
+		if ($PSBoundParameters.ContainsKey('start_epoch_time') -or $PSBoundParameters.ContainsKey('startTimeStamp')){
+			$body_params.start_time_ms = $start_epoch_time
+		}
+		if ($PSBoundParameters.ContainsKey('end_epoch_time') -or $PSBoundParameters.ContainsKey('endTimeStamp')){
+			$body_params.end_time_ms = $end_epoch_time
+		}
+		if (!([string]::IsNullOrEmpty($camera_ids))){$body_params.camera_ids = $camera_ids}
+		if (!([string]::IsNullOrEmpty($event_type_uid))){$body_params.event_type_uid = $event_type_uid}
+		if ($PSBoundParameters.ContainsKey('attribute_filters')){$body_params.attribute_filters = $attribute_filters}
+
+		try {
+			$response = Invoke-VerkadaRestMethod $url $org_id $x_verkada_auth_api $query_params -body_params $body_params -pagination -propertyName events -page_size 100 -method POST 
+			return $response
+		}
+		catch [Microsoft.PowerShell.Commands.HttpResponseException] {
+			$err = $_.ErrorDetails | ConvertFrom-Json
+			$errorMes = $_ | Convertto-Json -WarningAction SilentlyContinue
+			$err | Add-Member -NotePropertyName StatusCode -NotePropertyValue (($errorMes | ConvertFrom-Json -Depth 100 -WarningAction SilentlyContinue).Exception.Response.StatusCode) -Force
+			$msg = "$($err.StatusCode) - $($err.message)"
+			$msg += ": $(($query_params + $body_params) | ConvertTo-Json -Compress)"
+			Write-Error $msg
+			$myErrors += $msg
+			$msg = $null
+		}
+		catch [VerkadaRestMethodException] {
+			$msg = $_.ToString()
+			$msg += ": $(($query_params + $body_params) | ConvertTo-Json -Compress)"
+			Write-Error $msg
+			$myErrors += $msg
+			$msg = $null
+		}
+	} #end process
+
+	end {
+		if ($errorsToFile.IsPresent){
+			if (![string]::IsNullOrEmpty($myErrors)){
+				Get-Date | Out-File ./errors.txt -Append
+				$myErrors | Out-File ./errors.txt -Append
+			}
+		}
+	} #end end
+} #end function

verkadaModule/Public/Get-VerkadaHelixEvent.ps1

@@ -0,0 +1,113 @@
+function Get-VerkadaHelixEvent{
+	<#
+		.SYNOPSIS
+		Gets a specific Helix event using https://apidocs.verkada.com/reference/getvideotaggingeventviewv1
+
+		.DESCRIPTION
+		This method can be used to retrieve a Helix Event that has already been posted to Command. In the return message, the users will be able to see the corresponding attribute values for that unique event. To successfully retrieve a Helix Event, users will need to input the associated Camera ID, API Token with Helix permissions, Event Type UID, and the exact event epoch time in milliseconds.
+		The org_id and reqired token can be directly submitted as parameters, but is much easier to use Connect-Verkada to cache this information ahead of time and for subsequent commands.
+
+		.LINK
+		https://github.com/bepsoccer/verkadaModule/blob/master/docs/function-documentation/Get-VerkadaHelixEvent.md
+
+		.EXAMPLE
+		Get-VerkadaHelixEvent -camera_id 6b8731d7-d991-4206-ba71-b5446fa617fc -event_type_uid cf918b16-26cd-4c01-a672-5a91b79311e1 -timeStamp '1/1/2025 08:35:00 -06'
+		This will get the helix event for Jan 1, 2025 at 8:35 AM CST for the sepcified camera, and event ID. The org_id and token will be populated from the cached created by Connect-Verkada.
+
+		.EXAMPLE
+		Get-VerkadaHelixEvent -camera_id 6b8731d7-d991-4206-ba71-b5446fa617fc -event_type_uid cf918b16-26cd-4c01-a672-5a91b79311e1 -timeStamp '1/1/2025 08:35:00 -06' -org_id '7cd47706-f51b-4419-8675-3b9f0ce7c12d' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		This will get the helix event for Jan 1, 2025 at 8:35 AM CST for the sepcified camera, and event ID. The org_id and token are submitted as parameters in the call.
+	#>
+	[CmdletBinding(PositionalBinding = $true)]
+	[Alias("Get-VrkdaHlxEvt","g-VrkdaHlxEvt")]
+	param (
+		#The UUID of the organization the user belongs to
+		[Parameter(ValueFromPipelineByPropertyName = $true)]
+		[ValidateNotNullOrEmpty()]
+		[ValidatePattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$')]
+		[String]$org_id = $Global:verkadaConnection.org_id,
+		#The UUID of the camera who's name is being changed
+		[Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
+		[ValidatePattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$')]
+		[Alias("cameraId")]
+		[String]$camera_id,
+		#The UID of the event type to be used when creating the event
+		[Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
+		[ValidatePattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$')]
+		[String]$event_type_uid,
+		#The the timestamp of the event
+		[Parameter(ValueFromPipelineByPropertyName = $true)]
+		[datetime]$timeStamp,
+		#The the epoch time of the event in milliseconds
+		[Parameter(ValueFromPipelineByPropertyName = $true)]
+		[Alias("time_ms")]
+		[Int64]$epoch_time,
+		#The public API token obatined via the Login endpoint to be used for calls that hit the public API gateway
+		[Parameter()]
+		[ValidateNotNullOrEmpty()]
+		[String]$x_verkada_auth_api = $Global:verkadaConnection.x_verkada_auth_api,
+		#The region of the public API to be used
+		[Parameter()]
+		[ValidateSet('api','api.eu','api.au')]
+		[String]$region='api',
+		#Switch to write errors to file
+		[Parameter()]
+		[switch]$errorsToFile
+	)
+
+	begin {
+		$url = "https://$($region).verkada.com/cameras/v1/video_tagging/event"
+		#parameter validation
+		if ([string]::IsNullOrEmpty($org_id)) {throw "org_id is missing but is required!"}
+		if ([string]::IsNullOrEmpty($x_verkada_auth_api)) {throw "x_verkada_auth_api is missing but is required!"}
+		$myErrors = @()
+	} #end begin
+
+	process {
+		if ($PSBoundParameters.ContainsKey('epoch_time')){
+
+		} elseif ($PSBoundParameters.ContainsKey('timeStamp')){
+			$epoch_time = (New-TimeSpan -Start (Get-Date "01/01/1970") -End $timeStamp.ToUniversalTime()).TotalMilliseconds
+		} else {
+			throw "timestamp or epoch_time (time_ms) are required"
+		}
+		$body_params = @{}
+
+		$query_params = @{
+			'camera_id'				= $camera_id
+			'event_type_uid'	= $event_type_uid
+			'time_ms'					= $epoch_time
+		}
+
+		try {
+			$response = Invoke-VerkadaRestMethod $url $org_id $x_verkada_auth_api $query_params -body_params $body_params -method GET
+			return $response
+		}
+		catch [Microsoft.PowerShell.Commands.HttpResponseException] {
+			$err = $_.ErrorDetails | ConvertFrom-Json
+			$errorMes = $_ | Convertto-Json -WarningAction SilentlyContinue
+			$err | Add-Member -NotePropertyName StatusCode -NotePropertyValue (($errorMes | ConvertFrom-Json -Depth 100 -WarningAction SilentlyContinue).Exception.Response.StatusCode) -Force
+			$msg = "$($err.StatusCode) - $($err.message)"
+			$msg += ": $(($query_params + $body_params) | ConvertTo-Json -Compress)"
+			Write-Error $msg
+			$myErrors += $msg
+			$msg = $null
+		}
+		catch [VerkadaRestMethodException] {
+			$msg = $_.ToString()
+			$msg += ": $(($query_params + $body_params) | ConvertTo-Json -Compress)"
+			Write-Error $msg
+			$myErrors += $msg
+			$msg = $null
+		}
+	} #end process
+
+	end {
+		if ($errorsToFile.IsPresent){
+			if (![string]::IsNullOrEmpty($myErrors)){
+				Get-Date | Out-File ./errors.txt -Append
+				$myErrors | Out-File ./errors.txt -Append
+			}
+		}
+	} #end end
+} #end function