diff --git a/Docs/Get-HuduFlagTypes.md b/Docs/Get-HuduFlagTypes.md new file mode 100644 index 0000000..e3ea481 --- /dev/null +++ b/Docs/Get-HuduFlagTypes.md @@ -0,0 +1,142 @@ +--- +external help file: HuduAPI-help.xml +Module Name: HuduAPI +online version: +schema: 2.0.0 +--- + +# Get-HuduFlagTypes + +## SYNOPSIS +Gets Flag Types from Hudu. + +## SYNTAX + +### List (Default) +``` +Get-HuduFlagTypes [-Name ] [-Color ] [-Slug ] [-ProgressAction ] + [] +``` + +### ById +``` +Get-HuduFlagTypes [-Id ] [-Color ] [-Slug ] [-ProgressAction ] + [] +``` + +## DESCRIPTION +Retrieves Flag Types by ID or lists Flag Types with optional filtering. +When listing, +filters match exact values for name/color/slug when provided. +Results are paginated. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-HuduFlagTypes +# List all flag types +``` + +### EXAMPLE 2 +``` +Get-HuduFlagTypes -Name "Security Risk" +# Find the "Security Risk" flag type +``` + +### EXAMPLE 3 +``` +Get-HuduFlagTypes -Id 12 +# Get a specific flag type by ID +``` + +## PARAMETERS + +### -Id +Return a single Flag Type by ID. + +```yaml +Type: Int32 +Parameter Sets: ById +Aliases: FlagTypeId, flag_type_id + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +Filter by exact Flag Type name. + +```yaml +Type: String +Parameter Sets: List +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Color +Filter by exact color value (canonicalized to Hudu). + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Slug +Filter by exact slug value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +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 +API Endpoints: +- GET /api/v1/flag_types +- GET /api/v1/flag_types/{id} + +## RELATED LINKS diff --git a/Docs/Get-HuduFlags.md b/Docs/Get-HuduFlags.md new file mode 100644 index 0000000..8de5c7c --- /dev/null +++ b/Docs/Get-HuduFlags.md @@ -0,0 +1,162 @@ +--- +external help file: HuduAPI-help.xml +Module Name: HuduAPI +online version: +schema: 2.0.0 +--- + +# Get-HuduFlags + +## SYNOPSIS +Gets Flags from Hudu. + +## SYNTAX + +### List (Default) +``` +Get-HuduFlags [-FlagTypeId ] [-flagable_type ] [-flagable_id ] [-Description ] + [-ProgressAction ] [] +``` + +### ById +``` +Get-HuduFlags [-Id ] [-Description ] [-ProgressAction ] [] +``` + +## DESCRIPTION +Retrieves a single Flag by ID, or lists Flags with optional filtering by flag type, +target object type/id, and description. +Results are paginated when listing. + +## EXAMPLES + +### EXAMPLE 1 +``` +Get-HuduFlags +# List all flags (paginated) +``` + +### EXAMPLE 2 +``` +Get-HuduFlags -FlagTypeId 5 +# List all flags using flag type 5 +``` + +### EXAMPLE 3 +``` +Get-HuduFlags -flagable_type Company -flagable_id 123 +# List all flags attached to company 123 +``` + +### EXAMPLE 4 +``` +Get-HuduFlags -Id 77 +# Get a single flag by ID +``` + +## PARAMETERS + +### -Id +Return a single Flag by ID. + +```yaml +Type: Int32 +Parameter Sets: ById +Aliases: FlagId, flag_id + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FlagTypeId +Filter flags by Flag Type ID. + +```yaml +Type: Int32 +Parameter Sets: List +Aliases: Flag_Type_ID, FlagType_ID, Flag_TypeId + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -flagable_type +Filter by the target object type the flag is attached to (e.g., Company, Asset). +This value is normalized to Hudu's canonical flagable_type. + +```yaml +Type: String +Parameter Sets: List +Aliases: flagabletype, flaggable_type, flaggabletype, Flag_type, FlagType + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -flagable_id +Filter by the target object ID the flag is attached to. + +```yaml +Type: Int32 +Parameter Sets: List +Aliases: FlaggableId, flaggable_id, flagableid + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Description +Filter by description text (exact match behavior depends on API; treat as an exact filter unless documented otherwise). + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +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 +API Endpoints: +- GET /api/v1/flags +- GET /api/v1/flags/{id} + +## RELATED LINKS diff --git a/Docs/New-HuduFlag.md b/Docs/New-HuduFlag.md new file mode 100644 index 0000000..23d997c --- /dev/null +++ b/Docs/New-HuduFlag.md @@ -0,0 +1,163 @@ +--- +external help file: HuduAPI-help.xml +Module Name: HuduAPI +online version: +schema: 2.0.0 +--- + +# New-HuduFlag + +## SYNOPSIS +Creates a Flag on a Hudu object (asset, website, article, etc.). + +## SYNTAX + +``` +New-HuduFlag [-FlagTypeId] [[-Description] ] [-Flagable_Type] [-flagable_id] + [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +Creates a new Flag record in Hudu by associating a Flag Type with a specific object +(e.g., a Company, Asset, Network, VLAN). +Use FlagTypeId to choose the flag style/color, +and Flagable_Type + Flagable_Id to point at the target object. + +## EXAMPLES + +### EXAMPLE 1 +``` +# Flag company 123 with flag type 5 +New-HuduFlag -FlagTypeId 5 -Flagable_Type Company -flagable_id 123 -Description "Contract renewal due" +``` + +### EXAMPLE 2 +``` +# Flag asset 88 with flag type 2 +New-HuduFlag -FlagTypeId 2 -Flagable_Type Asset -flagable_id 88 +``` + +## PARAMETERS + +### -FlagTypeId +The ID of the Flag Type to apply. +Use Get-HuduFlagTypes to discover IDs. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Description +Optional note shown on the flag. +Useful for context like "Needs review" or "Decommission pending". + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Flagable_Type +The type of object to attach the flag to (e.g., Company, Asset, Website, Network). +This value is normalized to Hudu's canonical flagable_type before the request is sent. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: flaggabletype, flaggable_type, flagabletype, Flag_type, FlagType + +Required: True +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -flagable_id +The ID of the target object (matching Flagable_Type). +For example, a Company ID if Flagable_Type is Company. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: FlaggableId, flaggable_id, flagableid + +Required: True +Position: 4 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +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 +API Endpoint: POST /api/v1/flags +Requires Hudu API access configured for Invoke-HuduRequest. + +## RELATED LINKS diff --git a/Docs/New-HuduFlagType.md b/Docs/New-HuduFlagType.md new file mode 100644 index 0000000..5fc7369 --- /dev/null +++ b/Docs/New-HuduFlagType.md @@ -0,0 +1,120 @@ +--- +external help file: HuduAPI-help.xml +Module Name: HuduAPI +online version: +schema: 2.0.0 +--- + +# New-HuduFlagType + +## SYNOPSIS +Creates a new Flag Type. + +## SYNTAX + +``` +New-HuduFlagType [-Name] [[-Color] ] [-ProgressAction ] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION +Creates a Flag Type (name + color) that can be applied to objects via New-HuduFlag. +Flag Types are reusable and are referenced by ID (flag_type_id) when creating Flags. + +## EXAMPLES + +### EXAMPLE 1 +``` +New-HuduFlagType -Name "Security Risk" -Color Red +``` + +## PARAMETERS + +### -Name +Display name for the Flag Type (e.g., "Needs Review", "Security Risk", "Onboarding"). + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Color +Color name (canonicalized to Hudu). +Controls the UI color used when displaying the flag. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +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 +API Endpoint: POST /api/v1/flag_types + +## RELATED LINKS diff --git a/Docs/Remove-HuduFlag.md b/Docs/Remove-HuduFlag.md new file mode 100644 index 0000000..f3e1ff5 --- /dev/null +++ b/Docs/Remove-HuduFlag.md @@ -0,0 +1,109 @@ +--- +external help file: HuduAPI-help.xml +Module Name: HuduAPI +online version: +schema: 2.0.0 +--- + +# Remove-HuduFlag + +## SYNOPSIS +Deletes a Flag. + +## SYNTAX + +``` +Remove-HuduFlag [-Id] [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +Deletes a Flag by ID. +This is destructive and cannot be undone (unless Hudu provides recovery). +Supports ShouldProcess for -WhatIf / -Confirm. + +## EXAMPLES + +### EXAMPLE 1 +``` +Remove-HuduFlag -Id 77 +``` + +### EXAMPLE 2 +``` +Get-HuduFlags -flagable_type Company -flagable_id 123 | Remove-HuduFlag -WhatIf +``` + +## PARAMETERS + +### -Id +The Flag ID to delete. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: FlagId + +Required: True +Position: 1 +Default value: 0 +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +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 +API Endpoint: DELETE /api/v1/flags/{id} + +## RELATED LINKS diff --git a/Docs/Remove-HuduFlagType.md b/Docs/Remove-HuduFlagType.md new file mode 100644 index 0000000..02ed931 --- /dev/null +++ b/Docs/Remove-HuduFlagType.md @@ -0,0 +1,110 @@ +--- +external help file: HuduAPI-help.xml +Module Name: HuduAPI +online version: +schema: 2.0.0 +--- + +# Remove-HuduFlagType + +## SYNOPSIS +Deletes a Flag Type. + +## SYNTAX + +``` +Remove-HuduFlagType [-Id] [-ProgressAction ] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION +Deletes a Flag Type by ID. +This may fail if the Flag Type is in use by existing Flags. +Supports ShouldProcess for -WhatIf / -Confirm. + +## EXAMPLES + +### EXAMPLE 1 +``` +Remove-HuduFlagType -Id 12 +``` + +### EXAMPLE 2 +``` +Remove-HuduFlagType -Id 12 -WhatIf +``` + +## PARAMETERS + +### -Id +The Flag Type ID to delete. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: FlagTypeId + +Required: True +Position: 1 +Default value: 0 +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +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 +API Endpoint: DELETE /api/v1/flag_types/{id} + +## RELATED LINKS diff --git a/Docs/Set-HuduFlag.md b/Docs/Set-HuduFlag.md new file mode 100644 index 0000000..d3b4da6 --- /dev/null +++ b/Docs/Set-HuduFlag.md @@ -0,0 +1,169 @@ +--- +external help file: HuduAPI-help.xml +Module Name: HuduAPI +online version: +schema: 2.0.0 +--- + +# Set-HuduFlag + +## SYNOPSIS +Update a flag + +## SYNTAX + +``` +Set-HuduFlag [-Id] [[-FlagTypeId] ] [[-Description] ] [[-Flagable_Type] ] + [[-flagable_id] ] [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +Uses Hudu API to update a Flag. +If updating the flagable association, +flagable_type must be valid and the record must exist. + +## EXAMPLES + +### EXAMPLE 1 +``` +Set-HuduFlag -Id 10 -Description "Updated flag description" -FlagTypeId 2 +``` + +### EXAMPLE 2 +``` +Set-HuduFlag -Id 10 -flagable_type Asset -flagable_id 123 +``` + +## PARAMETERS + +### -Id +ID of the flag to update + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: FlagId, flag_id + +Required: True +Position: 1 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FlagTypeId +Updated flag type ID + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: flag_type_id, flagType_Id + +Required: False +Position: 2 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Description +Updated description + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Flagable_Type +Updated flagable type (Asset, Website, Article, AssetPassword, Company, Procedure, RackStorage, Network, IpAddress, Vlan, VlanZone) + +```yaml +Type: String +Parameter Sets: (All) +Aliases: flaggabletype, flaggable_type, flagabletype, Flag_type, FlagType + +Required: False +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -flagable_id +Updated flagable record ID + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: FlaggableId, flaggable_id, flagableid + +Required: False +Position: 5 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +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 diff --git a/Docs/Set-HuduFlagType.md b/Docs/Set-HuduFlagType.md new file mode 100644 index 0000000..0d22456 --- /dev/null +++ b/Docs/Set-HuduFlagType.md @@ -0,0 +1,133 @@ +--- +external help file: HuduAPI-help.xml +Module Name: HuduAPI +online version: +schema: 2.0.0 +--- + +# Set-HuduFlagType + +## SYNOPSIS +Update a flag type + +## SYNTAX + +``` +Set-HuduFlagType [-Id] [[-Name] ] [[-Color] ] [-ProgressAction ] + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +Uses Hudu API to update a Flag Type + +## EXAMPLES + +### EXAMPLE 1 +``` +Set-HuduFlagType -Id 1 -Name "Updated Flag Type" -Color "Green" +``` + +## PARAMETERS + +### -Id +ID of the flag type to update + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name +Updated name + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Color +Human friendly color name. +Valid colors are: Red, Blue, Green, Yellow, Purple, Orange, LightPink, LightBlue, LightGreen, LightPurple, LightOrange, LightYellow, White, Grey + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +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 diff --git a/HuduAPI/HuduAPI.psd1 b/HuduAPI/HuduAPI.psd1 index 6be89e1..7ab6f43 100644 --- a/HuduAPI/HuduAPI.psd1 +++ b/HuduAPI/HuduAPI.psd1 @@ -83,6 +83,8 @@ 'Get-HuduCompanyFolders', 'Get-HuduFolderCleanName', 'Get-HuduExpirations', + 'Get-HuduFlags', + 'Get-HuduFlagTypes', 'Get-HuduFolderMap', 'Get-HuduFolders', 'Get-HuduGroups', @@ -118,6 +120,8 @@ 'New-HuduBaseURL', 'New-HuduCompany', 'New-HuduCustomHeaders', + 'New-HuduFlag', + 'New-HuduFlagType', 'New-HuduFolder', 'New-HuduIPAddress', 'New-HuduList', @@ -144,6 +148,8 @@ 'Remove-HuduBaseURL', 'Remove-HuduCompany', 'Remove-HuduCustomHeaders', + 'Remove-HuduFlag', + 'Remove-HuduFlagType', 'Remove-HuduIPAddress', 'Remove-HuduList', 'Remove-HuduMagicDash', @@ -169,6 +175,8 @@ 'Set-HuduAssetLayoutField', 'Set-HuduCompany', 'Set-HuduCompanyArchive', + 'Set-HuduFlag', + 'Set-HuduFlagType', 'Set-HuduFolder', 'Set-HuduIntegrationMatcher', 'Set-HuduIPAddress', diff --git a/HuduAPI/Private/Set-ColorFromCanonical.ps1 b/HuduAPI/Private/Set-ColorFromCanonical.ps1 new file mode 100644 index 0000000..af1b67a --- /dev/null +++ b/HuduAPI/Private/Set-ColorFromCanonical.ps1 @@ -0,0 +1,50 @@ + +Function Set-ColorFromCanonical { + param ( + [string] $inputData + ) + if ([string]::IsNullOrWhiteSpace($inputData)) { return $null } + if (-not $(get-variable -name 'script:ColorLookup' -scope 'script' -erroraction silentlycontinue)) { + $script:ColorMap = [ordered]@{ # German, French, Italian, Spanish + Red = @('red','crimson','scarlet', 'rot','karminrot','scharlachrot','rouge','cramoisi','écarlate', 'rosso','cremisi','scarlatto', 'rojo','carmesí','escarlata') + Blue = @('blue','navy', 'blau','marineblau', 'bleu','bleu marine', 'blu','blu navy', 'azul','azul marino') + Green = @('green','lime', 'grün','limettengrün', 'vert','vert citron', 'verde','verde lime', 'verde','verde lima') + Yellow = @('yellow','gold', 'gelb','gold', 'jaune','or', 'giallo','oro', 'amarillo','oro') + Purple = @('purple','violet', 'lila','violett', 'violet','pourpre', 'viola','porpora', 'púrpura','violeta') + Orange = @('orange', 'orange', 'orange', 'arancione', 'naranja') + LightPink = @('light pink','pink','baby pink', 'hellrosa','rosa', 'rose clair','rose', 'rosa chiaro','rosa', 'rosa claro','rosa') + LightBlue = @('light blue','baby blue','sky blue', 'hellblau','babyblau','himmelblau', 'bleu clair','bleu ciel', 'azzurro','blu chiaro', 'azul claro','celeste') + LightGreen = @('light green','mint', 'hellgrün','mintgrün', 'vert clair','menthe', 'verde chiaro','menta', 'verde claro','menta') + LightPurple = @('light purple','lavender', 'helllila','lavendel', 'violet clair','lavande', 'viola chiaro','lavanda', 'morado claro','lavanda') + LightOrange = @('light orange','peach', 'hellorange','pfirsich', 'orange clair','pêche', 'arancione chiaro','pesca', 'naranja claro','melocotón') + LightYellow = @('light yellow','cream', 'hellgelb','creme', 'jaune clair','crème', 'giallo chiaro','crema', 'amarillo claro','crema') + White = @('white', 'weiß', 'blanc', 'bianco', 'blanco') + Grey = @('grey','gray','silver', 'grau','silber', 'gris','argent', 'grigio','argento', 'gris','plateado') + } + + + $script:ColorLookup = @{} + foreach ($canonical in $script:ColorMap.Keys) { + $all = @($canonical) + $script:ColorMap[$canonical] + foreach ($v in $all) { + if (-not $v) { continue } + + $k = $v.ToLowerInvariant() + $k = $k -replace '[-\s]+','_' # normalize separators + $script:ColorLookup[$k] = $canonical + } + } + } + + $raw = ([string]$inputData).Trim() + if ($raw.Length -eq 0) { return $raw } + + $key = $raw.ToLowerInvariant() -replace '[-\s]+','_' + + if ($script:ColorLookup.ContainsKey($key)) { + return $script:ColorLookup[$key] + } + + $allowed = ($script:ColorMap.Keys -join ', ') + throw "Invalid color '$raw'. Allowed values: $allowed" +} \ No newline at end of file diff --git a/HuduAPI/Private/Set-FlagableFromCanonical.ps1 b/HuduAPI/Private/Set-FlagableFromCanonical.ps1 new file mode 100644 index 0000000..4722828 --- /dev/null +++ b/HuduAPI/Private/Set-FlagableFromCanonical.ps1 @@ -0,0 +1,44 @@ +function Set-FlagableFromCanonical { + param ([string]$inputData) + if ([string]::IsNullOrWhiteSpace($inputData)) { return $null } + + if (-not $(get-variable -name 'script:FlaggableTypeLookup' -scope 'script' -erroraction silentlycontinue)) { + $script:FlaggableTypeMap = [ordered]@{ # German, French, Italian, Spanish + Asset = @('asset','assets', 'anlage','objekt', 'actif', 'bene', 'activo') + Website = @('website', 'webseite', 'site', 'sito', 'sitio') + Article = @('article','articles','kb','knowledgebase', 'artikel', 'article', 'articolo', 'artículo') + AssetPassword = @('assetpassword','asset_password','password', 'passwort', 'motdepasse', 'password', 'contraseña') + Company = @('company','companies', 'firma', 'entreprise', 'azienda', 'empresa') + Procedure = @('procedure','process', 'verfahren', 'procédure', 'procedura', 'procedimiento') + RackStorage = @('rackstorage','rack_storage','rack','rackstorages', 'rack', 'armoire') + Network = @('network', 'netzwerk', 'réseau', 'rete', 'red') + IpAddress = @('ipaddress','ip_address','ip', 'ipadresse', 'adresseip', 'indirizzoip', 'direccionip') + Vlan = @('vlan','vlans', 'vlan') + VlanZone = @('vlanzone','vlan_zone','zone', 'zonevlan') + } + $script:FlaggableTypeLookup = @{} + foreach ($canonical in $script:FlaggableTypeMap.Keys) { + # include canonical itself as accepted input + $all = @($canonical) + $script:FlaggableTypeMap[$canonical] + + foreach ($v in $all) { + if ([string]::IsNullOrWhiteSpace($v)) { continue } + $k = ($v -as [string]).Trim().ToLowerInvariant() + $k = $k -replace '[-\s]+','_' # treat dashes/spaces like underscores + $script:FlaggableTypeLookup[$k] = $canonical + } + } + } + + $raw = ([string]$inputData).Trim() + if ($raw.Length -eq 0) { return $raw } + + $k = $raw.ToLowerInvariant() -replace '[-\s]+','_' + + $lookup = $script:FlaggableTypeLookup + if ($lookup.ContainsKey($k)) { + return $lookup[$k] + } + $allowed = ($script:FlaggableTypeMap.Keys -join ', ') + throw "Invalid flaggable type '$raw'. Allowed: $allowed" +} diff --git a/HuduAPI/Public/Get-HuduFlagTypes.ps1 b/HuduAPI/Public/Get-HuduFlagTypes.ps1 new file mode 100644 index 0000000..e050a47 --- /dev/null +++ b/HuduAPI/Public/Get-HuduFlagTypes.ps1 @@ -0,0 +1,79 @@ + +function Get-HuduFlagTypes { +<# +.SYNOPSIS +Gets Flag Types from Hudu. + +.DESCRIPTION +Retrieves Flag Types by ID or lists Flag Types with optional filtering. When listing, +filters match exact values for name/color/slug when provided. Results are paginated. + +.PARAMETER Id +Return a single Flag Type by ID. + +.PARAMETER Name +Filter by exact Flag Type name. + +.PARAMETER Color +Filter by exact color value (canonicalized to Hudu). + +.PARAMETER Slug +Filter by exact slug value. + +.EXAMPLE +Get-HuduFlagTypes +# List all flag types + +.EXAMPLE +Get-HuduFlagTypes -Name "Security Risk" +# Find the "Security Risk" flag type + +.EXAMPLE +Get-HuduFlagTypes -Id 12 +# Get a specific flag type by ID + +.NOTES +API Endpoints: +- GET /api/v1/flag_types +- GET /api/v1/flag_types/{id} +#> + + [CmdletBinding(DefaultParameterSetName = 'List')] + param( + [Parameter(ParameterSetName = 'ById')] + [Alias('FlagTypeId','flag_type_id')] + [int]$Id, + + [Parameter(ParameterSetName = 'List')] + [string]$Name, + + [Parameter()] + [ValidateSet('red', 'crimson', 'scarlet', 'rot', 'karminrot', 'scharlachrot', 'rouge', 'cramoisi', 'écarlate', 'rosso', 'cremisi', 'scarlatto', 'rojo', 'carmesí', 'escarlata', 'blue', 'navy', 'blau', 'marineblau', 'bleu', 'bleu marine', 'blu', 'blu navy', 'azul', 'azul marino', 'green', 'lime', 'grün', 'limettengrün', 'vert', 'vert citron', 'verde', 'verde lime', 'verde lima', 'yellow', 'gold', 'gelb', 'jaune', 'or', 'giallo', 'oro', 'amarillo', 'purple', 'violet', 'lila', 'violett', 'pourpre', 'viola', 'porpora', 'púrpura', 'violeta', 'orange', 'arancione', 'naranja', 'light pink', 'pink', 'baby pink', 'hellrosa', 'rosa', 'rose clair', 'rose', 'rosa chiaro', 'rosa claro', 'light blue', 'baby blue', 'sky blue', 'hellblau', 'babyblau', 'himmelblau', 'bleu clair', 'bleu ciel', 'azzurro', 'blu chiaro', 'azul claro', 'celeste', 'light green', 'mint', 'hellgrün', 'mintgrün', 'vert clair', 'menthe', 'verde chiaro', 'menta', 'verde claro', 'light purple', 'lavender', 'helllila', 'lavendel', 'violet clair', 'lavande', 'viola chiaro', 'lavanda', 'morado claro', 'light orange', 'peach', 'hellorange', 'pfirsich', 'orange clair', 'pêche', 'arancione chiaro', 'pesca', 'naranja claro', 'melocotón', 'light yellow', 'cream', 'hellgelb', 'creme', 'jaune clair', 'crème', 'giallo chiaro', 'crema', 'amarillo claro', 'white', 'weiß', 'blanc', 'bianco', 'blanco', 'grey', 'gray', 'silver', 'grau', 'silber', 'gris', 'argent', 'grigio', 'argento', 'plateado', 'lightpink', 'lightblue', 'lightgreen', 'lightpurple', 'lightorange', 'lightyellow',IgnoreCase = $true)] + [string]$Color, + + [string]$Slug + ) + + process { + if ($PSCmdlet.ParameterSetName -eq 'ById') { + $resp = Invoke-HuduRequest -Method GET -Resource "/api/v1/flag_types/$Id" + return ($resp.flag_type ?? $resp) + } + + $params = @{} + if ($PSBoundParameters.ContainsKey('Name')) { $params.name = $Name } + if ($PSBoundParameters.ContainsKey('Color')) { + $params.color = $(Set-ColorFromCanonical -inputData $Color) + } + if ($PSBoundParameters.ContainsKey('Slug')) { $params.slug = $Slug } + $params.page = 1 + $params.page_size = 1000 + $req = @{ + Method = 'GET' + Resource = "/api/v1/flag_types" + Params = $params + } + + Invoke-HuduRequestPaginated -HuduRequest $req -Property 'flag_types' + } +} diff --git a/HuduAPI/Public/Get-HuduFlags.ps1 b/HuduAPI/Public/Get-HuduFlags.ps1 new file mode 100644 index 0000000..a5f0b5f --- /dev/null +++ b/HuduAPI/Public/Get-HuduFlags.ps1 @@ -0,0 +1,94 @@ +function Get-HuduFlags { +<# +.SYNOPSIS +Gets Flags from Hudu. + +.DESCRIPTION +Retrieves a single Flag by ID, or lists Flags with optional filtering by flag type, +target object type/id, and description. Results are paginated when listing. + +.PARAMETER Id +Return a single Flag by ID. + +.PARAMETER FlagTypeId +Filter flags by Flag Type ID. + +.PARAMETER flagable_type +Filter by the target object type the flag is attached to (e.g., Company, Asset). +This value is normalized to Hudu's canonical flagable_type. + +.PARAMETER flagable_id +Filter by the target object ID the flag is attached to. + +.PARAMETER Description +Filter by description text (exact match behavior depends on API; treat as an exact filter unless documented otherwise). + +.EXAMPLE +Get-HuduFlags +# List all flags (paginated) + +.EXAMPLE +Get-HuduFlags -FlagTypeId 5 +# List all flags using flag type 5 + +.EXAMPLE +Get-HuduFlags -flagable_type Company -flagable_id 123 +# List all flags attached to company 123 + +.EXAMPLE +Get-HuduFlags -Id 77 +# Get a single flag by ID + +.NOTES +API Endpoints: +- GET /api/v1/flags +- GET /api/v1/flags/{id} +#> + + [CmdletBinding(DefaultParameterSetName = 'List')] + param( + [Parameter(ParameterSetName = 'ById')] + [Alias('FlagId','flag_id')] + [int]$Id, + + [Parameter(ParameterSetName = 'List')] + [Alias("Flag_Type_ID","FlagType_ID","Flag_TypeId")] + [int]$FlagTypeId, + + [Parameter(ParameterSetName = 'List')] + [Alias('flagabletype',"flaggable_type","flaggabletype","Flag_type","FlagType")] + [ValidateSet('asset', 'assets', 'anlage', 'objekt', 'actif', 'bene', 'activo', 'website', 'webseite', 'site', 'sito', 'sitio', 'article', 'articles', 'kb', 'knowledgebase', 'artikel', 'articolo', 'artículo', 'assetpassword', 'asset_password', 'password', 'passwort', 'motdepasse', 'contraseña', 'company', 'companies', 'firma', 'entreprise', 'azienda', 'empresa', 'procedure', 'process', 'verfahren', 'procédure', 'procedura', 'procedimiento', 'rackstorage', 'rack_storage', 'rack', 'rackstorages', 'armoire', 'network', 'netzwerk', 'réseau', 'rete', 'red', 'ipaddress', 'ip_address', 'ip', 'ipadresse', 'adresseip', 'indirizzoip', 'direccionip', 'vlan', 'vlans', 'vlanzone', 'vlan_zone', 'zone', 'zonevlan',IgnoreCase = $true)] + [string]$flagable_type, + + [Parameter(ParameterSetName = 'List')] + [Alias("FlaggableId","flaggable_id","flagableid")] + [int]$flagable_id, + + [string]$Description + ) + + process { + if ($PSCmdlet.ParameterSetName -eq 'ById') { + $resp = Invoke-HuduRequest -Method GET -Resource "/api/v1/flags/$Id" + return ($resp.flag ?? $resp ?? $null) + } + + $params = @{} + if ($PSBoundParameters.ContainsKey('FlagTypeId')) { $params.flag_type_id = $FlagTypeId } + if ($PSBoundParameters.ContainsKey('flagable_type')) { + $params.flagable_type = $(Set-FlagableFromCanonical -inputData $flagable_type) + } + if ($PSBoundParameters.ContainsKey('flagable_id')) { $params.flagable_id = $flagable_id } + if ($PSBoundParameters.ContainsKey('Description')) { $params.description = $Description } + $params.page = 1 + $params.page_size = 1000 + $req = @{ + Method = 'GET' + Resource = "/api/v1/flags" + Params = $params + } + + $resp = Invoke-HuduRequestPaginated -HuduRequest $req -Property 'flags' + return $resp + } +} diff --git a/HuduAPI/Public/New-HuduFlag.ps1 b/HuduAPI/Public/New-HuduFlag.ps1 new file mode 100644 index 0000000..854ab62 --- /dev/null +++ b/HuduAPI/Public/New-HuduFlag.ps1 @@ -0,0 +1,69 @@ +function New-HuduFlag { +<# +.SYNOPSIS +Creates a Flag on a Hudu object (asset, website, article, etc.). + +.DESCRIPTION +Creates a new Flag record in Hudu by associating a Flag Type with a specific object +(e.g., a Company, Asset, Network, VLAN). Use FlagTypeId to choose the flag style/color, +and Flagable_Type + Flagable_Id to point at the target object. + +.PARAMETER FlagTypeId +The ID of the Flag Type to apply. Use Get-HuduFlagTypes to discover IDs. + +.PARAMETER Description +Optional note shown on the flag. Useful for context like "Needs review" or "Decommission pending". + +.PARAMETER Flagable_Type +The type of object to attach the flag to (e.g., Company, Asset, Website, Network). +This value is normalized to Hudu's canonical flagable_type before the request is sent. + +.PARAMETER flagable_id +The ID of the target object (matching Flagable_Type). For example, a Company ID if Flagable_Type is Company. + +.EXAMPLE +# Flag company 123 with flag type 5 +New-HuduFlag -FlagTypeId 5 -Flagable_Type Company -flagable_id 123 -Description "Contract renewal due" + +.EXAMPLE +# Flag asset 88 with flag type 2 +New-HuduFlag -FlagTypeId 2 -Flagable_Type Asset -flagable_id 88 + +.NOTES +API Endpoint: POST /api/v1/flags +Requires Hudu API access configured for Invoke-HuduRequest. +#> + [CmdletBinding(SupportsShouldProcess)] + param( + [Parameter(Mandatory)] + [int]$FlagTypeId, + + [Parameter()] + [string]$Description, + + [Parameter(Mandatory)] + [Alias('flaggabletype','flaggable_type','flagabletype','Flag_type','FlagType')] + [ValidateSet('asset', 'assets', 'anlage', 'objekt', 'actif', 'bene', 'activo', 'website', 'webseite', 'site', 'sito', 'sitio', 'article', 'articles', 'kb', 'knowledgebase', 'artikel', 'articolo', 'artículo', 'assetpassword', 'asset_password', 'password', 'passwort', 'motdepasse', 'contraseña', 'company', 'companies', 'firma', 'entreprise', 'azienda', 'empresa', 'procedure', 'process', 'verfahren', 'procédure', 'procedura', 'procedimiento', 'rackstorage', 'rack_storage', 'rack', 'rackstorages', 'armoire', 'network', 'netzwerk', 'réseau', 'rete', 'red', 'ipaddress', 'ip_address', 'ip', 'ipadresse', 'adresseip', 'indirizzoip', 'direccionip', 'vlan', 'vlans', 'vlanzone', 'vlan_zone', 'zone', 'zonevlan',IgnoreCase = $true)] + [string]$Flagable_Type, + + [Parameter(Mandatory)] + [Alias("FlaggableId","flaggable_id","flagableid")] + [int]$flagable_id + ) + + $bodyObj = @{ + flag = @{ + flag_type_id = $FlagTypeId + description = $Description + flagable_type = $(Set-FlagableFromCanonical -inputData $Flagable_Type) + flagable_id = $flagable_id + } + } + + $body = $bodyObj | ConvertTo-Json -Depth 99 + + if ($PSCmdlet.ShouldProcess("$flagable_type Id=$flagable_id", "Create Flag (FlagTypeId=$FlagTypeId)")) { + $resp = Invoke-HuduRequest -Method POST -Resource "/api/v1/flags" -Body $body + return ($resp.flag ?? $resp) + } +} diff --git a/HuduAPI/Public/New-HuduFlagType.ps1 b/HuduAPI/Public/New-HuduFlagType.ps1 new file mode 100644 index 0000000..692ec79 --- /dev/null +++ b/HuduAPI/Public/New-HuduFlagType.ps1 @@ -0,0 +1,47 @@ +function New-HuduFlagType { +<# +.SYNOPSIS +Creates a new Flag Type. + +.DESCRIPTION +Creates a Flag Type (name + color) that can be applied to objects via New-HuduFlag. +Flag Types are reusable and are referenced by ID (flag_type_id) when creating Flags. + +.PARAMETER Name +Display name for the Flag Type (e.g., "Needs Review", "Security Risk", "Onboarding"). + +.PARAMETER Color +Color name (canonicalized to Hudu). Controls the UI color used when displaying the flag. + +.EXAMPLE +New-HuduFlagType -Name "Security Risk" -Color Red + +.NOTES +API Endpoint: POST /api/v1/flag_types +#> + + [CmdletBinding(SupportsShouldProcess)] + param( + [Parameter(Mandatory)] + [ValidateNotNullOrEmpty()] + [string]$Name, + + [Parameter()] + [ValidateNotNullOrEmpty()] + [ValidateSet('red', 'crimson', 'scarlet', 'rot', 'karminrot', 'scharlachrot', 'rouge', 'cramoisi', 'écarlate', 'rosso', 'cremisi', 'scarlatto', 'rojo', 'carmesí', 'escarlata', 'blue', 'navy', 'blau', 'marineblau', 'bleu', 'bleu marine', 'blu', 'blu navy', 'azul', 'azul marino', 'green', 'lime', 'grün', 'limettengrün', 'vert', 'vert citron', 'verde', 'verde lime', 'verde lima', 'yellow', 'gold', 'gelb', 'jaune', 'or', 'giallo', 'oro', 'amarillo', 'purple', 'violet', 'lila', 'violett', 'pourpre', 'viola', 'porpora', 'púrpura', 'violeta', 'orange', 'arancione', 'naranja', 'light pink', 'pink', 'baby pink', 'hellrosa', 'rosa', 'rose clair', 'rose', 'rosa chiaro', 'rosa claro', 'light blue', 'baby blue', 'sky blue', 'hellblau', 'babyblau', 'himmelblau', 'bleu clair', 'bleu ciel', 'azzurro', 'blu chiaro', 'azul claro', 'celeste', 'light green', 'mint', 'hellgrün', 'mintgrün', 'vert clair', 'menthe', 'verde chiaro', 'menta', 'verde claro', 'light purple', 'lavender', 'helllila', 'lavendel', 'violet clair', 'lavande', 'viola chiaro', 'lavanda', 'morado claro', 'light orange', 'peach', 'hellorange', 'pfirsich', 'orange clair', 'pêche', 'arancione chiaro', 'pesca', 'naranja claro', 'melocotón', 'light yellow', 'cream', 'hellgelb', 'creme', 'jaune clair', 'crème', 'giallo chiaro', 'crema', 'amarillo claro', 'white', 'weiß', 'blanc', 'bianco', 'blanco', 'grey', 'gray', 'silver', 'grau', 'silber', 'gris', 'argent', 'grigio', 'argento', 'plateado', 'lightpink', 'lightblue', 'lightgreen', 'lightpurple', 'lightorange', 'lightyellow',IgnoreCase = $true)] + [string]$Color + ) + $bodyObj = @{ + flag_type = @{ + name = $Name + color = $(Set-ColorFromCanonical -inputData $Color) + } + } + + $body = $bodyObj | ConvertTo-Json -Depth 99 + + if ($PSCmdlet.ShouldProcess("Flag Type '$Name'", "Create")) { + $resp = Invoke-HuduRequest -Method POST -Resource "/api/v1/flag_types" -Body $body + return ($resp.flag_type ?? $resp) + } +} diff --git a/HuduAPI/Public/Remove-HuduFlag.ps1 b/HuduAPI/Public/Remove-HuduFlag.ps1 new file mode 100644 index 0000000..9b10b4b --- /dev/null +++ b/HuduAPI/Public/Remove-HuduFlag.ps1 @@ -0,0 +1,35 @@ +function Remove-HuduFlag { +<# +.SYNOPSIS +Deletes a Flag. + +.DESCRIPTION +Deletes a Flag by ID. This is destructive and cannot be undone (unless Hudu provides recovery). +Supports ShouldProcess for -WhatIf / -Confirm. + +.PARAMETER Id +The Flag ID to delete. + +.EXAMPLE +Remove-HuduFlag -Id 77 + +.EXAMPLE +Get-HuduFlags -flagable_type Company -flagable_id 123 | Remove-HuduFlag -WhatIf + +.NOTES +API Endpoint: DELETE /api/v1/flags/{id} +#> + + [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] + param( + [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName)] + [Alias('FlagId')] + [int]$Id + ) + + process { + if ($PSCmdlet.ShouldProcess("Flag Id=$Id", "Delete")) { + Invoke-HuduRequest -Method DELETE -Resource "/api/v1/flags/$Id" | Out-Null + } + } +} \ No newline at end of file diff --git a/HuduAPI/Public/Remove-HuduFlagType.ps1 b/HuduAPI/Public/Remove-HuduFlagType.ps1 new file mode 100644 index 0000000..e3b8eed --- /dev/null +++ b/HuduAPI/Public/Remove-HuduFlagType.ps1 @@ -0,0 +1,36 @@ +function Remove-HuduFlagType { +<# +.SYNOPSIS +Deletes a Flag Type. + +.DESCRIPTION +Deletes a Flag Type by ID. This may fail if the Flag Type is in use by existing Flags. +Supports ShouldProcess for -WhatIf / -Confirm. + +.PARAMETER Id +The Flag Type ID to delete. + +.EXAMPLE +Remove-HuduFlagType -Id 12 + +.EXAMPLE +Remove-HuduFlagType -Id 12 -WhatIf + +.NOTES +API Endpoint: DELETE /api/v1/flag_types/{id} +#> + + [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] + param( + [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)] + [Alias('FlagTypeId')] + [int]$Id + ) + + process { + if ($PSCmdlet.ShouldProcess("Flag Type Id=$Id", "Delete")) { + Invoke-HuduRequest -Method DELETE -Resource "/api/v1/flag_types/$Id" | Out-Null + return $true + } + } +} diff --git a/HuduAPI/Public/Set-HuduFlag.ps1 b/HuduAPI/Public/Set-HuduFlag.ps1 new file mode 100644 index 0000000..7e5218f --- /dev/null +++ b/HuduAPI/Public/Set-HuduFlag.ps1 @@ -0,0 +1,76 @@ +function Set-HuduFlag { + <# + .SYNOPSIS + Update a flag + + .DESCRIPTION + Uses Hudu API to update a Flag. If updating the flagable association, + flagable_type must be valid and the record must exist. + + .PARAMETER Id + ID of the flag to update + + .PARAMETER FlagTypeId + Updated flag type ID + + .PARAMETER Description + Updated description + + .PARAMETER flagable_type + Updated flagable type (Asset, Website, Article, AssetPassword, Company, Procedure, RackStorage, Network, IpAddress, Vlan, VlanZone) + + .PARAMETER flagable_id + Updated flagable record ID + + .EXAMPLE + Set-HuduFlag -Id 10 -Description "Updated flag description" -FlagTypeId 2 + + .EXAMPLE + Set-HuduFlag -Id 10 -flagable_type Asset -flagable_id 123 + #> + [CmdletBinding(SupportsShouldProcess)] + Param( + [Parameter(Mandatory = $true)] + [Alias('FlagId','flag_id')] + [int]$Id, + + [Alias('flag_type_id',"flagType_Id")] + [int]$FlagTypeId, + + [string]$Description = '', + + [Alias('flaggabletype','flaggable_type','flagabletype','Flag_type','FlagType')] + [ValidateSet('asset', 'assets', 'anlage', 'objekt', 'actif', 'bene', 'activo', 'website', 'webseite', 'site', 'sito', 'sitio', 'article', 'articles', 'kb', 'knowledgebase', 'artikel', 'articolo', 'artículo', 'assetpassword', 'asset_password', 'password', 'passwort', 'motdepasse', 'contraseña', 'company', 'companies', 'firma', 'entreprise', 'azienda', 'empresa', 'procedure', 'process', 'verfahren', 'procédure', 'procedura', 'procedimiento', 'rackstorage', 'rack_storage', 'rack', 'rackstorages', 'armoire', 'network', 'netzwerk', 'réseau', 'rete', 'red', 'ipaddress', 'ip_address', 'ip', 'ipadresse', 'adresseip', 'indirizzoip', 'direccionip', 'vlan', 'vlans', 'vlanzone', 'vlan_zone', 'zone', 'zonevlan',IgnoreCase = $true)] + [string]$Flagable_Type, + + [Alias("FlaggableId","flaggable_id","flagableid")] + [int]$flagable_id + ) + + $Object = Get-HuduFlags -Id $Id + if (-not $Object) { return $null } + + $Flag = [ordered]@{ flag = $Object } + + if ($PSBoundParameters.ContainsKey('FlagTypeId')) { + $Flag.flag.flag_type_id = $FlagTypeId + } + + if ($Description) { + $Flag.flag.description = $Description + } + + if ($flagable_type) { + $Flag.flag.flagable_type = $(Set-FlagableFromCanonical -inputData $flagable_type) + } + + if ($PSBoundParameters.ContainsKey('flagable_id')) { + $Flag.flag.flagable_id = $flagable_id + } + + $JSON = $Flag | ConvertTo-Json -Depth 10 + + if ($PSCmdlet.ShouldProcess($Id)) { + Invoke-HuduRequest -Method PUT -Resource "/api/v1/flags/$Id" -Body $JSON + } +} \ No newline at end of file diff --git a/HuduAPI/Public/Set-HuduFlagType.ps1 b/HuduAPI/Public/Set-HuduFlagType.ps1 new file mode 100644 index 0000000..17a69ac --- /dev/null +++ b/HuduAPI/Public/Set-HuduFlagType.ps1 @@ -0,0 +1,46 @@ +function Set-HuduFlagType { + <# + .SYNOPSIS + Update a flag type + + .DESCRIPTION + Uses Hudu API to update a Flag Type + + .PARAMETER Id + ID of the flag type to update + + .PARAMETER Name + Updated name + + .PARAMETER Color + Human friendly color name. Valid colors are: Red, Blue, Green, Yellow, Purple, Orange, LightPink, LightBlue, LightGreen, LightPurple, LightOrange, LightYellow, White, Grey + + .EXAMPLE + Set-HuduFlagType -Id 1 -Name "Updated Flag Type" -Color "Green" + #> + [CmdletBinding(SupportsShouldProcess)] + Param( + [Parameter(Mandatory = $true)] + [int]$Id, + + [string]$Name = '', + + [Parameter()] + [ValidateSet('red', 'crimson', 'scarlet', 'rot', 'karminrot', 'scharlachrot', 'rouge', 'cramoisi', 'écarlate', 'rosso', 'cremisi', 'scarlatto', 'rojo', 'carmesí', 'escarlata', 'blue', 'navy', 'blau', 'marineblau', 'bleu', 'bleu marine', 'blu', 'blu navy', 'azul', 'azul marino', 'green', 'lime', 'grün', 'limettengrün', 'vert', 'vert citron', 'verde', 'verde lime', 'verde lima', 'yellow', 'gold', 'gelb', 'jaune', 'or', 'giallo', 'oro', 'amarillo', 'purple', 'violet', 'lila', 'violett', 'pourpre', 'viola', 'porpora', 'púrpura', 'violeta', 'orange', 'arancione', 'naranja', 'light pink', 'pink', 'baby pink', 'hellrosa', 'rosa', 'rose clair', 'rose', 'rosa chiaro', 'rosa claro', 'light blue', 'baby blue', 'sky blue', 'hellblau', 'babyblau', 'himmelblau', 'bleu clair', 'bleu ciel', 'azzurro', 'blu chiaro', 'azul claro', 'celeste', 'light green', 'mint', 'hellgrün', 'mintgrün', 'vert clair', 'menthe', 'verde chiaro', 'menta', 'verde claro', 'light purple', 'lavender', 'helllila', 'lavendel', 'violet clair', 'lavande', 'viola chiaro', 'lavanda', 'morado claro', 'light orange', 'peach', 'hellorange', 'pfirsich', 'orange clair', 'pêche', 'arancione chiaro', 'pesca', 'naranja claro', 'melocotón', 'light yellow', 'cream', 'hellgelb', 'creme', 'jaune clair', 'crème', 'giallo chiaro', 'crema', 'amarillo claro', 'white', 'weiß', 'blanc', 'bianco', 'blanco', 'grey', 'gray', 'silver', 'grau', 'silber', 'gris', 'argent', 'grigio', 'argento', 'plateado', 'lightpink', 'lightblue', 'lightgreen', 'lightpurple', 'lightorange', 'lightyellow',IgnoreCase = $true)] + [string]$Color + ) + + $Object = Get-HuduFlagTypes -Id $Id + if (-not $Object) { return $null } + + $FlagType = [ordered]@{ flag_type = $Object } + if ($Name) { $FlagType.flag_type.name = $Name } + if ($Color) { $FlagType.flag_type.color = $(Set-ColorFromCanonical -inputData $Color) } + + $JSON = $FlagType | ConvertTo-Json -Depth 10 + + if ($PSCmdlet.ShouldProcess($Id)) { + $result = Invoke-HuduRequest -Method PUT -Resource "/api/v1/flag_types/$Id" -Body $JSON + return ($result.flag_type ?? $result) + } +} diff --git a/HuduAPI/tests/Flags-FlagTypes.Tests.ps1 b/HuduAPI/tests/Flags-FlagTypes.Tests.ps1 new file mode 100644 index 0000000..ab6a564 --- /dev/null +++ b/HuduAPI/tests/Flags-FlagTypes.Tests.ps1 @@ -0,0 +1,175 @@ +# Tests/Flags-FlagTypes.Tests.ps1 + +Context "Hudu Flags and Flag Types Integration Tests" { + + BeforeEach { + $HUDU_API_KEY = $env:HUDU_API_KEY ?? "$(Read-Host 'Enter Hudu API Key')" + $HUDU_BASE_URL = $env:HUDU_BASE_URL ?? "$(Read-Host 'Enter Hudu Base URL')" + + New-HuduBaseURL $HUDU_BASE_URL + New-HuduApiKey $HUDU_API_KEY + if (-not $env:HUDU_TEST_ASSET_ID){throw "Missing required test environment variable- HUDU_TEST_ASSET_ID"} + if (-not $env:HUDU_TEST_COMPANY_ID){throw "Missing required test environment variable- HUDU_TEST_COMPANY_ID"} + if (-not $env:HUDU_TEST_NETWORK_ID){throw "Missing required test environment variable- HUDU_TEST_NETWORK_ID"} + if (-not $env:HUDU_TEST_VLAN_ID){throw "Missing required test environment variable- HUDU_TEST_VLAN_ID"} + if (-not $env:HUDU_TEST_VLAN_ZONE_ID){throw "Missing required test environment variable- HUDU_TEST_VLAN_ZONE_ID"} + if (-not $env:HUDU_TEST_IP_ADDRESS_ID){throw "Missing required test environment variable- HUDU_TEST_IP_ADDRESS_ID"} + + $currentVersion = ([version]$((Get-HuduAppInfo).version)) + if ($currentVersion -lt [version]"2.4.0") { + throw "Hudu version 2.4.0 or higher is required for Flags and Flag Types tests. Current version: $currentVersion" + } else { + Write-Host "Setting up test for Flags endpoints... Hudu version: $currentVersion" + } + $TestCompany = Get-HuduCompanies -Id $env:HUDU_TEST_COMPANY_ID; $TestCompany=$TestCompany.company ?? $TestCompany; + if (-not $TestCompany) { + throw "HUDU_TEST_COMPANY_ID ($env:HUDU_TEST_COMPANY_ID) does not correspond to a valid Company in Hudu." + } else { + write-host "Using test Company: id=$($TestCompany.id), name=$($TestCompany.name)" + } + $LayoutForAssetAttribution = $(get-huduassetlayouts | where-object { -not ($_.active -eq $false) } | select-object -first 1) + $LayoutForAssetAttribution = $LayoutForAssetAttribution.asset_layout ?? $LayoutForAssetAttribution + if (-not $LayoutForAssetAttribution) { + throw "No active Asset Layouts found in Hudu; at least one is required for Flag tests." + } else { + write-host "Using Asset Layout for flaggable Asset creation: id=$($LayoutForAssetAttribution.id), name=$($LayoutForAssetAttribution.name)" + } + $flaggables = @{} + $flaggables["Asset"] = $env:HUDU_TEST_ASSET_ID + $flaggables["Company"] = $env:HUDU_TEST_COMPANY_ID + $flaggables["Network"] = $env:HUDU_TEST_NETWORK_ID + $flaggables["IpAddress"] = $env:HUDU_TEST_IP_ADDRESS_ID + $flaggables["Vlan"] = $env:HUDU_TEST_VLAN_ID + $flaggables["VlanZone"] = $env:HUDU_TEST_VLAN_ZONE_ID + $flaggables["RackStorage"] = $env:HUDU_TEST_RACK_STORAGE_ID + $flaggables["Website"] = $env:HUDU_TEST_WEBSITE_ID + $flaggables["Article"] = $env:HUDU_TEST_ARTICLE_ID + $flaggables["AssetPassword"] = $env:HUDU_TEST_PASSWORD_ID + $flaggables["Procedure"] = $env:HUDU_TEST_PROCEDURE_ID + + } + + It "Creates, retrieves, updates, and deletes Flag Types and Flags" { + $allFlagColors = @('Red', 'Blue', 'Green', 'Yellow', 'Purple', 'Orange', 'LightPink', 'LightBlue', 'LightGreen', 'LightPurple', 'LightOrange', 'LightYellow', 'White', 'Grey') + $allFlagTypes = @('Asset','Website','Article','AssetPassword','Company','Procedure','RackStorage','Network','IpAddress','Vlan','VlanZone') + + foreach ($flagable_type in $allFlagTypes) { + $flagTypeName = "IntegrationTestFlagType-$(Get-Random)" + $flagTypeColor = $allFlagColors | Get-Random + $flagable_id = $flaggables["$flagable_type"] + + write-host "starting flag tests for flagable type: $flagable_type, (object id: $flagable_id) will be using flag type name: $flagTypeName and color: $flagTypeColor" + + $createdFlagType = $null + $createdFlag = $null + + try { + $createdFlagType = New-HuduFlagType -Name $flagTypeName -Color $flagTypeColor + $createdFlagType | Should -Not -BeNullOrEmpty + $createdFlagType.id | Should -BeGreaterThan 0 + $createdFlagType.name | Should -Be $flagTypeName + $createdFlagType.color | Should -Be $flagTypeColor + + Write-Host "Created flag type: $($createdFlagType | ConvertTo-Json -Depth 6)" + + # 1.2 Retrieve Flag Type by ID + $fetchedFTById = Get-HuduFlagTypes -Id $createdFlagType.id + $fetchedFTById | Should -Not -BeNullOrEmpty + $fetchedFTById.id | Should -Be $createdFlagType.id + $fetchedFTById.name | Should -Be $flagTypeName + + # 1.3 Retrieve Flag Types by filter (Name) + # (Get endpoints can return an array; handle both single and multi) + $fetchedFTByName = @(Get-HuduFlagTypes -Name $flagTypeName) + $fetchedFTByName.Count | Should -BeGreaterThan 0 + ($fetchedFTByName.id -contains $createdFlagType.id) | Should -BeTrue + + # 1.4 Update Flag Type + $updatedFTName = "$flagTypeName-Updated" + $updatedFTColor = $allFlagColors | Where-Object { $_ -ne $flagTypeColor } | Get-Random + + $updatedFT = Set-HuduFlagType -Id $createdFlagType.id -Name $updatedFTName -Color $updatedFTColor + $updatedFT | Should -Not -BeNullOrEmpty + + # depending on your wrapper, Set may return full response or unwrapped object + $updatedFTObj = $updatedFT.flag_type ?? $updatedFT + $updatedFTObj.name | Should -Be $updatedFTName + $updatedFTObj.color | Should -Be $updatedFTColor + + # refresh + $refetchedFT = Get-HuduFlagTypes -Id $createdFlagType.id + $refetchedFT.name | Should -Be $updatedFTName + $refetchedFT.color | Should -Be $updatedFTColor + + + # ------------------------- + # 2) FLAG CRUD + # ------------------------- + + # 2.1 Create Flag + $flagDesc = "Integration test flag - $(Get-Random)" + + $createdFlag = New-HuduFlag -FlagTypeId $createdFlagType.id -Description $flagDesc -flagable_type $flagable_type -flagable_id $flagable_id + $createdFlag | Should -Not -BeNullOrEmpty + $createdFlag.id | Should -BeGreaterThan 0 + $createdFlag.flag_type_id | Should -Be $createdFlagType.id + $createdFlag.flagable_type | Should -Be $flagable_type + $createdFlag.flagable_id | Should -Be $flagable_id + $createdFlag.description | Should -Be $flagDesc + + Write-Host "Created flag: $($createdFlag | ConvertTo-Json -Depth 6)" + + # 2.2 Retrieve Flag by ID + $fetchedFById = Get-HuduFlags -id $createdFlag.id + $fetchedFById | Should -Not -BeNullOrEmpty + $fetchedFById.id | Should -Be $createdFlag.id + $fetchedFById.description | Should -Be $flagDesc + + # 2.3 Retrieve Flags by filter (flagable) + $fetchedFByTarget = @(Get-HuduFlags -flagable_type $flagable_type -flagable_id $flagable_id) + $fetchedFByTarget.Count | Should -BeGreaterThan 0 + ($fetchedFByTarget.id -contains $createdFlag.id) | Should -BeTrue + + # 2.4 Update Flag (description + (optionally) flag_type) + $updatedDesc = "$flagDesc (updated)" + + $updatedFlag = Set-HuduFlag -Id $createdFlag.id -Description $updatedDesc + $updatedFlag | Should -Not -BeNullOrEmpty + + $updatedFlagObj = $updatedFlag.flag ?? $updatedFlag + $updatedFlagObj.description | Should -Be $updatedDesc + + # refresh + $refetchedFlag = Get-HuduFlags -id $createdFlag.id + $refetchedFlag.description | Should -Be $updatedDesc + + + # ------------------------- + # 3) CLEANUP (delete flag first, then flag type) + # ------------------------- + + # 3.1 Delete Flag + $removedFlag = Remove-HuduFlag -Id $createdFlag.id -confirm:$false + # your Remove may return $true; if it returns nothing, that's fine too + # (assert by re-fetch) + $deletedFlag = Get-HuduFlags | where-object { $_.id -eq $createdFlag.id } + $deletedFlag | Should -BeNullOrEmpty + + # 3.2 Delete Flag Type + $removedFT = Remove-HuduFlagType -Id $createdFlagType.id -confirm:$false + $deletedFT = Get-HuduFlagTypes | where-object { $_.id -eq $createdFlagType.id } + $deletedFT | Should -BeNullOrEmpty + } + finally { + # Best-effort cleanup in case the test fails mid-way. + if ($createdFlag -and $createdFlag.id) { + try { Remove-HuduFlag -Id $createdFlag.id -confirm:$false | Out-Null } catch {} + } + + if ($createdFlagType -and $createdFlagType.id) { + try { Remove-HuduFlagType -Id $createdFlagType.id -confirm:$false | Out-Null } catch {} + } + } + } + } +} diff --git a/HuduAPI/tests/environ.example.ps1 b/HuduAPI/tests/environ.example.ps1 index 751eb88..caa2cdf 100644 --- a/HuduAPI/tests/environ.example.ps1 +++ b/HuduAPI/tests/environ.example.ps1 @@ -1,10 +1,17 @@ -$env:HUDU_API_KEY = "xyz" +$env:HUDU_API_KEY = "urkey" $env:HUDU_BASE_URL = "https://urinstance.huducloud.com" $env:HUDU_TEST_RACK_ROLE_ID = 2 +$env:HUDU_TEST_RACK_STORAGE_ID = 1 $env:HUDU_TEST_COMPANY_ID = 1 -$env:HUDU_TEST_ASSET_ID = 1 +$env:HUDU_TEST_PROCEDURE_ID = 2 +$env:HUDU_TEST_ASSET_ID = 21 +$env:HUDU_TEST_ARTICLE_ID = 4 $env:HUDU_TEST_USER_ID = 1 $env:HUDU_TEST_VLAN_ID = 1 $env:HUDU_TEST_IPAM_STATUS_ROLE_ID=1 $env:HUDU_TEST_IPAM_LIST_ITEM_ID=1 -$env:HUDU_TEST_NETWORK_ID = 1 \ No newline at end of file +$env:HUDU_TEST_NETWORK_ID = 1 +$env:HUDU_TEST_VLAN_ZONE_ID = 1 +$env:HUDU_TEST_IP_ADDRESS_ID = 1 +$env:HUDU_TEST_WEBSITE_ID = 1 +$env:HUDU_TEST_PASSWORD_ID = 1 \ No newline at end of file diff --git a/run-tests.ps1 b/run-tests.ps1 index eb9a181..2e3bad9 100644 --- a/run-tests.ps1 +++ b/run-tests.ps1 @@ -9,6 +9,11 @@ param ( $testsPath = Join-Path $PSScriptRoot "HuduAPI" "tests" $modulePath = Join-Path $PSScriptRoot "HuduAPI" 'Huduapi.psd1' $envFile = Join-Path $testsPath $EnvironFile +if (-not $envFile -or -not (Test-Path $envFile)) { + $baseName = [System.IO.Path]::GetFileNameWithoutExtension($EnvironFile) + $envFile = Get-ChildItem -Recurse -Path $(resolve-path .) -Filter "*$baseName*.ps1" | Select-Object -First 1 | ForEach-Object { $_.FullName } +} + Write-Host "Starting tests in: $testsPath" Write-Host "Using module: $modulePath" @@ -30,21 +35,26 @@ Import-Module $modulePath -Force # Load env if (Test-Path $envFile) { Write-Host "Sourcing environment from $envFile" -ForegroundColor Cyan - . $envFile + . "$envFile" } # Validate env vars $requiredVars = @( -"HUDU_API_KEY", -"HUDU_BASE_URL", "HUDU_TEST_RACK_ROLE_ID", +"HUDU_TEST_RACK_STORAGE_ID", "HUDU_TEST_COMPANY_ID", +"HUDU_TEST_PROCEDURE_ID", "HUDU_TEST_ASSET_ID", +"HUDU_TEST_ARTICLE_ID", "HUDU_TEST_USER_ID", "HUDU_TEST_VLAN_ID", +"HUDU_TEST_IPAM_STATUS_ROLE_ID", "HUDU_TEST_IPAM_LIST_ITEM_ID", -"HUDU_TEST_IPAM_LIST_ITEM_ID", -"HUDU_TEST_NETWORK_ID" +"HUDU_TEST_NETWORK_ID", +"HUDU_TEST_VLAN_ZONE_ID", +"HUDU_TEST_IP_ADDRESS_ID", +"HUDU_TEST_WEBSITE_ID", +"HUDU_TEST_PASSWORD_ID" ) foreach ($var in $requiredVars) { if (-not (Get-Item "env:$var" -ErrorAction SilentlyContinue)) { @@ -67,4 +77,4 @@ foreach ($integrationTest in $integrationTests) { $config.Run.Path = $integrationTest.FullName $config.Output.Verbosity = "detailed" Invoke-Pester -Configuration $config -} +} \ No newline at end of file