From 6779b7635c47e2c744f937f9a344f49ad095f0c6 Mon Sep 17 00:00:00 2001 From: Brad Parker Date: Mon, 20 Oct 2025 20:06:33 -0400 Subject: [PATCH 1/2] Adds Add-VerkadaHelixEvent function Adds a new function, Add-VerkadaHelixEvent, to allow users to generate Helix events in Command. The function takes parameters such as camera ID, event type UID, timestamp, and attributes to create the event. It leverages the Verkada API to post the event data. The function also includes error handling and logging capabilities. Updates the module manifest to include the new function and aliases. closes #261 --- .../Public/Add-VerkadaHelixEvent.ps1 | 110 ++++++++++++++++++ verkadaModule/verkadaModule.psd1 | 23 ++-- 2 files changed, 122 insertions(+), 11 deletions(-) create mode 100644 verkadaModule/Public/Add-VerkadaHelixEvent.ps1 diff --git a/verkadaModule/Public/Add-VerkadaHelixEvent.ps1 b/verkadaModule/Public/Add-VerkadaHelixEvent.ps1 new file mode 100644 index 0000000..e77423e --- /dev/null +++ b/verkadaModule/Public/Add-VerkadaHelixEvent.ps1 @@ -0,0 +1,110 @@ +function Add-VerkadaHelixEvent{ + <# + .SYNOPSIS + Creates a Helix event in Commadn using https://apidocs.verkada.com/reference/postvideotaggingeventviewv1 + + .DESCRIPTION + This method can be used to generate a Helix Event in Command. Users will be able to specify the attribute values for each attribute key that was previously defined in the Event Type creation process. To successfully create 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 timestamp 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/Add-VerkadaHelixEvent.md + + .EXAMPLE + Add-VerkadaHelixEvent -camera_id 6b8731d7-d991-4206-ba71-b5446fa617fc -event_type_uid cf918b16-26cd-4c01-a672-5a91b79311e1 -timeStamp (get-date) -attributes $attributes + This will add a new helix event for the current time for the sepcified camera, event ID, and submitted attributes. The org_id and token will be populated from the cached created by Connect-Verkada. + + .EXAMPLE + Add-VerkadaHelixEvent -camera_id 6b8731d7-d991-4206-ba71-b5446fa617fc -event_type_uid cf918b16-26cd-4c01-a672-5a91b79311e1 -timeStamp '1/1/2025 08:35:00 -06' -attributes $attributes -org_id '7cd47706-f51b-4419-8675-3b9f0ce7c12d' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token' + This will add a new helix event for Jan 1, 2025 at 8:35 AM CST for the sepcified camera, event ID, and submitted attributes. The org_id and token are submitted as parameters in the call. + #> + [CmdletBinding(PositionalBinding = $true)] + [Alias("Add-VrkdaHlxEvt","a-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 epoch time of the event + [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] + [datetime]$timeStamp, + #The parameters to be submitted for the event + [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] + [object]$attributes, + #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" + #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 { + $epoch_time = (New-TimeSpan -Start (Get-Date "01/01/1970") -End $timeStamp.ToUniversalTime()).TotalMilliseconds + $body_params = @{ + 'camera_id' = $camera_id + 'event_type_uid' = $event_type_uid + 'time_ms' = $epoch_time + 'attributes' = $attributes + 'flagged' = $flagged + } + + $query_params = @{} + + try { + Invoke-VerkadaRestMethod $url $org_id $x_verkada_auth_api $query_params -body_params $body_params -method POST + return "Event created successfully" + } + 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 \ No newline at end of file diff --git a/verkadaModule/verkadaModule.psd1 b/verkadaModule/verkadaModule.psd1 index 6fd1270..97f1e33 100644 --- a/verkadaModule/verkadaModule.psd1 +++ b/verkadaModule/verkadaModule.psd1 @@ -3,7 +3,7 @@ # # Generated by: Verkada SE Community # -# Generated on: 09/30/2025 +# Generated on: 10/19/2025 # @{ @@ -72,9 +72,9 @@ PowerShellVersion = '6.1' FunctionsToExport = 'Add-VerkadaAccessGroup', 'Add-VerkadaAccessSiteAdmin', 'Add-VerkadaAccessUserCard', 'Add-VerkadaAccessUserLicensePlate', 'Add-VerkadaCamera', 'Add-VerkadaCommandSite', - 'Add-VerkadaCommandUser', 'Add-VerkadaLicensePlateOfInterest', - 'Add-VerkadaWorkplaceEmployee', 'Connect-Verkada', - 'Disable-VerkadaAccessUserCard', + 'Add-VerkadaCommandUser', 'Add-VerkadaHelixEvent', + 'Add-VerkadaLicensePlateOfInterest', 'Add-VerkadaWorkplaceEmployee', + 'Connect-Verkada', 'Disable-VerkadaAccessUserCard', 'Disable-VerkadaAccessUserLicensePlate', 'Disconnect-Verkada', 'Enable-VerkadaAccessUserCard', 'Enable-VerkadaAccessUserLicensePlate', 'Find-VerkadaCommandUser', @@ -130,13 +130,14 @@ CmdletsToExport = @() # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. AliasesToExport = 'a-VrkdaAcGrp', 'Add-VrkdaAcGrp', 'a-VrkdaAcUsrCrd', 'Add-VrkdaAcUsrCrd', 'a-VrkdaAcUsrLPR', 'Add-VrkdaAcUsrLPR', - 'a-VrkdaCmdUsr', 'Add-VrkdaCmdUsr', 'Add-VerkadaLPoI', 'a-VrkdaWrkEmp', - 'Add-VrkdaWrkEmp', 'd-VrkdaAcUsrCrd', 'Disable-VrkdaAcUsrCrd', - 'd-VrkdaAcUsrLPR', 'Disable-VrkdaAcUsrLPR', 'e-VrkdaAcUsrCrd', - 'Enable-VrkdaAcUsrCrd', 'e-VrkdaAcUsrLPR', 'Enable-VrkdaAcUsrLPR', - 'otp', 'Get-VrkdaAcEvnts', 'gt-VrkdaAcEvnts', 'Get-VrkdaAcGrp', - 'gt-VrkdaAcGrp', 'Get-VrkdaAcUsr', 'gt-VrkdaAcUsr', - 'ep-VrkdaAcUsrPrflPic', 'Export-VerkadaAccessUserProfilePicture', + 'a-VrkdaCmdUsr', 'Add-VrkdaCmdUsr', 'a-VrkdaHlxEvt', 'Add-VrkdaHlxEvt', + 'Add-VerkadaLPoI', 'a-VrkdaWrkEmp', 'Add-VrkdaWrkEmp', + 'd-VrkdaAcUsrCrd', 'Disable-VrkdaAcUsrCrd', 'd-VrkdaAcUsrLPR', + 'Disable-VrkdaAcUsrLPR', 'e-VrkdaAcUsrCrd', 'Enable-VrkdaAcUsrCrd', + 'e-VrkdaAcUsrLPR', 'Enable-VrkdaAcUsrLPR', 'otp', 'Get-VrkdaAcEvnts', + 'gt-VrkdaAcEvnts', 'Get-VrkdaAcGrp', 'gt-VrkdaAcGrp', 'Get-VrkdaAcUsr', + 'gt-VrkdaAcUsr', 'ep-VrkdaAcUsrPrflPic', + 'Export-VerkadaAccessUserProfilePicture', 'Export-VrkdaAcUsrPrflPic', 'g-VrkdaAcUsrPrflPic', 'Get-VrkdaAcUsrPrflPic', 'g-VrkdAlrmDevs', 'Get-VrkdAlrmDevs', 'Get-VerkadaCameraSite', 'Get-VrkdaCmdUsr', 'gt-VrkdaCmdUsr', From f280452e921f9b7e25087abcf8f3fa97209a2a5e Mon Sep 17 00:00:00 2001 From: bepsoccer <26012546+bepsoccer@users.noreply.github.com> Date: Tue, 21 Oct 2025 00:15:25 +0000 Subject: [PATCH 2/2] Bumping release to 0.9.8 --- .../Add-VerkadaHelixEvent.md | 205 ++++++++++++++++++ docs/reference.md | 1 + verkadaModule/verkadaModule.psd1 | 4 +- 3 files changed, 208 insertions(+), 2 deletions(-) create mode 100644 docs/function-documentation/Add-VerkadaHelixEvent.md diff --git a/docs/function-documentation/Add-VerkadaHelixEvent.md b/docs/function-documentation/Add-VerkadaHelixEvent.md new file mode 100644 index 0000000..47e180c --- /dev/null +++ b/docs/function-documentation/Add-VerkadaHelixEvent.md @@ -0,0 +1,205 @@ +--- +external help file: verkadaModule-help.xml +Module Name: verkadaModule +online version: https://github.com/bepsoccer/verkadaModule/blob/master/docs/function-documentation/Add-VerkadaHelixEvent.md +schema: 2.0.0 +--- + +# Add-VerkadaHelixEvent + +## SYNOPSIS +Creates a Helix event in Commadn using https://apidocs.verkada.com/reference/postvideotaggingeventviewv1 + +## SYNTAX + +``` +Add-VerkadaHelixEvent [[-org_id] ] [-camera_id] [-event_type_uid] + [-timeStamp] [-attributes] [[-flagged] ] [[-x_verkada_auth_api] ] + [[-region] ] [-errorsToFile] [-ProgressAction ] [] +``` + +## DESCRIPTION +This method can be used to generate a Helix Event in Command. +Users will be able to specify the attribute values for each attribute key that was previously defined in the Event Type creation process. +To successfully create 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 timestamp 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. + +## EXAMPLES + +### EXAMPLE 1 +``` +Add-VerkadaHelixEvent -camera_id 6b8731d7-d991-4206-ba71-b5446fa617fc -event_type_uid cf918b16-26cd-4c01-a672-5a91b79311e1 -timeStamp (get-date) -attributes $attributes +This will add a new helix event for the current time for the sepcified camera, event ID, and submitted attributes. The org_id and token will be populated from the cached created by Connect-Verkada. +``` + +### EXAMPLE 2 +``` +Add-VerkadaHelixEvent -camera_id 6b8731d7-d991-4206-ba71-b5446fa617fc -event_type_uid cf918b16-26cd-4c01-a672-5a91b79311e1 -timeStamp '1/1/2025 08:35:00 -06' -attributes $attributes -org_id '7cd47706-f51b-4419-8675-3b9f0ce7c12d' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token' +This will add a new helix event for Jan 1, 2025 at 8:35 AM CST for the sepcified camera, event ID, and submitted attributes. The org_id and token are submitted as parameters in the call. +``` + +## PARAMETERS + +### -org_id +The UUID of the organization the user belongs to + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: $Global:verkadaConnection.org_id +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -camera_id +The UUID of the camera who's name is being changed + +```yaml +Type: String +Parameter Sets: (All) +Aliases: cameraId + +Required: True +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -event_type_uid +The UID of the event type to be used when creating the event + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 3 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -timeStamp +The the epoch time of the event + +```yaml +Type: DateTime +Parameter Sets: (All) +Aliases: + +Required: True +Position: 4 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -attributes +The parameters to be submitted for the event + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: True +Position: 5 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -flagged +Boolean if the event should be flagged + +```yaml +Type: Boolean +Parameter Sets: (All) +Aliases: + +Required: False +Position: 6 +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -x_verkada_auth_api +The public API token obatined via the Login endpoint to be used for calls that hit the public API gateway + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 7 +Default value: $Global:verkadaConnection.x_verkada_auth_api +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -region +The region of the public API to be used + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 8 +Default value: Api +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -errorsToFile +Switch to write errors to file + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[https://github.com/bepsoccer/verkadaModule/blob/master/docs/function-documentation/Add-VerkadaHelixEvent.md](https://github.com/bepsoccer/verkadaModule/blob/master/docs/function-documentation/Add-VerkadaHelixEvent.md) + diff --git a/docs/reference.md b/docs/reference.md index e9ee569..6d40053 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -7,6 +7,7 @@ * [Add-VerkadaCamera](function-documentation/Add-VerkadaCamera.md) * [Add-VerkadaCommandSite](function-documentation/Add-VerkadaCommandSite.md) * [Add-VerkadaCommandUser](function-documentation/Add-VerkadaCommandUser.md) +* [Add-VerkadaHelixEvent](function-documentation/Add-VerkadaHelixEvent.md) * [Add-VerkadaLicensePlateOfInterest](function-documentation/Add-VerkadaLicensePlateOfInterest.md) * [Add-VerkadaWorkplaceEmployee](function-documentation/Add-VerkadaWorkplaceEmployee.md) * [Connect-Verkada](function-documentation/Connect-Verkada.md) diff --git a/verkadaModule/verkadaModule.psd1 b/verkadaModule/verkadaModule.psd1 index 97f1e33..d7de101 100644 --- a/verkadaModule/verkadaModule.psd1 +++ b/verkadaModule/verkadaModule.psd1 @@ -3,7 +3,7 @@ # # Generated by: Verkada SE Community # -# Generated on: 10/19/2025 +# Generated on: 10/21/2025 # @{ @@ -12,7 +12,7 @@ RootModule = 'verkadaModule.psm1' # Version number of this module. -ModuleVersion = '0.9.7' +ModuleVersion = '0.9.8' # Supported PSEditions CompatiblePSEditions = 'Desktop', 'Core'