New-AMApprovalCard

New-AMApprovalCard

New-AMApprovalCard

SYNOPSIS

Creates an Adaptive Card for approval requests.

SYNTAX

1

New-AMApprovalCard [-OriginatorId <String>] [-Title] <String> [-RequestID] <String> [-Requester] <String> [-Details <Hashtable[]>] [-Description <String>] [-Justification <String>] [-ApproveUrl <String>] [-ApproveBody <String>] [-RejectUrl <String>] [-RejectBody <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-AMApprovalCard function generates an Adaptive Card to notify approvers about a request that requires their decision. The card includes details about the request, requester, justification, and additional information. It also provides options for approvers to approve or reject the request, along with a comment field for additional input.

EXAMPLES

EXAMPLE 1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Example 1: Create an approval card using splatting
$approvalCardParams = @{
    OriginatorId  = "approval-system"
    Title         = "Purchase Request Approval"
    RequestID     = "REQ-2023-001"
    Requester     = "John Doe"
    Details       = @(
        @{ Title = "Amount"; Value = "$5000" },
        @{ Title = "Department"; Value = "Finance" }
    )
    Description   = "Approval is required for the purchase of new office equipment."
    Justification = "The current equipment is outdated and impacts productivity."
    ApproveUrl    = "https://api.example.com/approve"
    ApproveBody   = "{`"requestId`": `"$RequestID`", `"action`": `"approve`", `"approver`": `"`", `"comment`": `"`"}"
    RejectUrl     = "https://api.example.com/reject"
    RejectBody    = "{`"requestId`": `"$RequestID`", `"action`": `"reject`", `"approver`": `"`", `"comment`": `"`"}"
}

Example explanation

1

$approvalCard = New-AMApprovalCard @approvalCardParams

EXAMPLE 2

1
2
3
4
5
6
7
8
9
10

# Example 2: Create a simple approval card using splatting
$simpleApprovalCardParams = @{
    OriginatorId = "leave-approval-system"
    Title        = "Leave Request Approval"
    RequestID    = "REQ-2023-002"
    Requester    = "Jane Smith"
    Description  = "Approval is required for a leave request from Jane Smith."
    ApproveUrl   = "https://api.example.com/approve"
    RejectUrl    = "https://api.example.com/reject"
}

Example explanation

1

$approvalCard = New-AMApprovalCard @simpleApprovalCardParams

PARAMETERS

-OriginatorId

(Optional) 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

-Title

The title of the approval card, typically describing the request.

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

-RequestID

The unique identifier for the request.

1
2
3
4
5
6
7
8
9

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

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

-Requester

The name or email of the person submitting the request.

1
2
3
4
5
6
7
8
9

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

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

-Details

(Optional) A list of additional details about the request. Each entry should be a hashtable with Title and Value keys.

1
2
3
4
5
6
7
8
9

Type: Collections.Hashtable[]
Parameter Sets: (All)
Aliases: None

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

-Description

(Optional) A description of the request.

1
2
3
4
5
6
7
8
9

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

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

-Justification

(Optional) A justification for the request, explaining why it is needed.

1
2
3
4
5
6
7
8
9

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

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

-ApproveUrl

(Optional) The URL to send the approval action. Defaults to “https://api.example.com/approve”.

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

-ApproveBody

(Optional) The body of the POST request sent to the ApproveUrl. Defaults to: “{"requestId”: "$RequestID”, "action”: "approve”, "approver”: "”, "comment”: "”}”

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

-RejectUrl

(Optional) The URL to send the rejection action. Defaults to “https://api.example.com/reject”.

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

-RejectBody

(Optional) The body of the POST request sent to the RejectUrl. Defaults to: “{"requestId”: "$RequestID”, "action”: "reject”, "approver”: "”, "comment”: "”}”

1
2
3
4
5
6
7
8
9

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

Required: False
Position: 10
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 approval requests. The card can be exported and sent via email or other communication channels.