New-AMApplicationUsageSurveyCard

New-AMApplicationUsageSurveyCard

New-AMApplicationUsageSurveyCard

SYNOPSIS

Creates an Adaptive Card for an application usage survey.

SYNTAX

1

New-AMApplicationUsageSurveyCard [-OriginatorId <String>] [-ApplicationName] <String> [-Version <String>] [-Vendor <String>] [-LicenseCount <Int32>] [-ActiveUserCount <Int32>] [-RenewalDate <DateTime>] [-Department <String>] [-TicketNumber <String>] [-Description <String>] [-frequencyChoices <Object>] [-importanceChoices <Object>] [-AlternativeQuestion <Boolean>] [-TeamMemberUsage <Boolean>] [-Suggestion <Boolean>] [-ResponseEndpoint <String>] [-ResponseBody <String>] [-Verbose <SwitchParameter>] [-Debug <SwitchParameter>] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [-InformationAction <ActionPreference>] [-ProgressAction <ActionPreference>] [-ErrorVariable <String>] [-WarningVariable <String>] [-InformationVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>] [-PipelineVariable <String>] [<CommonParameters>]

DESCRIPTION

The New-AMApplicationUsageSurveyCard function generates an Adaptive Card to collect information about the usage, importance, and features of a specific application. The card includes fields for usage frequency, business function, importance rating, and suggestions for improvement. It also provides options for users to specify alternative applications and team member usage.

EXAMPLES

EXAMPLE 1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# Example 1: Create an application usage survey card using splatting
$appCardParams = @{
    OriginatorId      = "your-originator-id"
    ApplicationName   = "Adobe Creative Cloud"
    Version           = "2023"
    Vendor            = "Adobe"
    LicenseCount      = 50
    ActiveUserCount   = 32
    RenewalDate       = (Get-Date).AddMonths(3)
    Department        = "IT Software Asset Management"
    TicketNumber      = "SAM-2023-003"
    Description       = "The IT department is conducting a review of software licenses and usage. Please provide information about your use of this application to help us optimize licensing costs and ensure continued access for essential business functions."
    FrequencyChoices  = [ordered]@{
        "daily" = "Daily"
        "weekly" = "Several times per week"
        "monthly" = "Few times per month"
        "rarely" = "Rarely (a few times per year)"
        "never" = "Never"
    }
    ImportanceChoices = [ordered]@{
        "critical" = "Critical - Cannot perform job without it"
        "important" = "Important - Major impact if unavailable"
        "useful" = "Useful - Improves efficiency but have workarounds"
        "optional" = "Optional - Nice to have but not essential"
        "unnecessary" = "Unnecessary - Could work without it"
    }
    AlternativeQuestion = $true
    TeamMemberUsage    = $true
    Suggestion         = $true
    ResponseEndpoint   = "https://api.example.com/application-usage"
    ResponseBody       = "{`"ticketNumber`": `"$TicketNumber`", `"applicationName`": `"$ApplicationName`", `"version`": `"$Version`", `"usageFrequency`": `"`", `"businessFunction`": `"`", `"usedFeatures`": `"`", `"importanceRating`": `"`", `"alternativesAware`": `"`", `"alternativesDetails`": `"`", `"teamUsage`": `"`", `"improvementSuggestions`": `"`}"
}

Example explanation

1

$appCard = New-AMApplicationUsageSurveyCard @appCardParams

EXAMPLE 2

1
2
3
4
5
6
7
8
9
10

# Example 2: Create a simple application usage survey card using splatting
$simpleAppCardParams = @{
    OriginatorId       = "software-survey-system"
    ApplicationName    = "Microsoft Excel"
    Version            = "2021"
    Vendor             = "Microsoft"
    Department         = "Finance"
    TicketNumber       = "SAM-2023-004"
    ResponseEndpoint   = "https://api.example.com/application-usage"
}

Example explanation

1

$appCard = New-AMApplicationUsageSurveyCard @simpleAppCardParams

PARAMETERS

-OriginatorId

The originator ID of the card. This is used to identify the source of the card. Defaults to “your-originator-id”.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 0
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ApplicationName

The name of the application being surveyed.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Version

(Optional) The version of the application.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Vendor

(Optional) The vendor or provider of the application.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-LicenseCount

(Optional) The total number of licenses available for the application.

1
2
3
4
5
6
7
8
9

Type: Int32
Parameter Sets: (All)
Aliases: None

Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ActiveUserCount

(Optional) The number of active users currently using the application.

1
2
3
4
5
6
7
8
9

Type: Int32
Parameter Sets: (All)
Aliases: None

Required: False
Position: 5
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-RenewalDate

(Optional) The renewal date for the application’s license.

1
2
3
4
5
6
7
8
9

Type: DateTime
Parameter Sets: (All)
Aliases: None

Required: False
Position: 6
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Department

(Optional) The department responsible for managing the application.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 7
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TicketNumber

(Optional) The ticket number associated with the application usage survey.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 8
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Description

(Optional) A description of the purpose of the survey. Defaults to a predefined message.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 9
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-frequencyChoices

(Optional) A hashtable of choices for the frequency of application usage. Each key-value pair represents an option and its description. Defaults to: [ordered]@{ “daily” = “Daily” “weekly” = “Several times per week” “monthly” = “Few times per month” “rarely” = “Rarely (a few times per year)” “never” = “Never” }

1
2
3
4
5
6
7
8
9

Type: Object
Parameter Sets: (All)
Aliases: None

Required: False
Position: 10
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-importanceChoices

(Optional) A hashtable of choices for the importance of the application. Each key-value pair represents an option and its description. Defaults to: [ordered]@{ “critical” = “Critical - Cannot perform job without it” “important” = “Important - Major impact if unavailable” “useful” = “Useful - Improves efficiency but have workarounds” “optional” = “Optional - Nice to have but not essential” “unnecessary” = “Unnecessary - Could work without it” }

1
2
3
4
5
6
7
8
9

Type: Object
Parameter Sets: (All)
Aliases: None

Required: False
Position: 11
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-AlternativeQuestion

(Optional) A boolean indicating whether to include a question about alternative applications. Defaults to $true.

1
2
3
4
5
6
7
8
9

Type: Boolean
Parameter Sets: (All)
Aliases: None

Required: False
Position: 12
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TeamMemberUsage

(Optional) A boolean indicating whether to include a question about team member usage of the application. Defaults to $true.

1
2
3
4
5
6
7
8
9

Type: Boolean
Parameter Sets: (All)
Aliases: None

Required: False
Position: 13
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Suggestion

(Optional) A boolean indicating whether to include a field for improvement suggestions. Defaults to $true.

1
2
3
4
5
6
7
8
9

Type: Boolean
Parameter Sets: (All)
Aliases: None

Required: False
Position: 14
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ResponseEndpoint

(Optional) The URL where the survey response will be sent. Defaults to “https://api.example.com/application-usage”.

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 15
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ResponseBody

(Optional) The body of the POST request sent to the ResponseEndpoint. This is a JSON string that includes placeholders for dynamic values such as the ticket number, application name, version, and survey responses. Defaults to: “{"ticketNumber”: "$TicketNumber”, "applicationName”: "$ApplicationName”, "version”: "$Version”, "usageFrequency”: "”, "businessFunction”: "”, "usedFeatures”: "”, "importanceRating”: "”, "alternativesAware”: "”, "alternativesDetails”: "”, "teamUsage”: "”, "improvementSuggestions”: "}”

1
2
3
4
5
6
7
8
9

Type: String
Parameter Sets: (All)
Aliases: None

Required: False
Position: 16
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.

INPUTS

None

OUTPUTS

None

NOTES

This function is part of the Actionable Messages module and is used to create Adaptive Cards for application usage surveys. The card can be exported and sent via email or other communication channels.