Skip to content

Commit

Permalink
Updated documentation on Add-JiraFilterPermission
Browse files Browse the repository at this point in the history
* added tests (WIP)
* added external help
* added -Id parameterSet
* changed documentation on other functions (WIP)
  • Loading branch information
lipkau committed Jun 14, 2018
1 parent 5c7f072 commit 6f76a61
Show file tree
Hide file tree
Showing 5 changed files with 237 additions and 63 deletions.
40 changes: 18 additions & 22 deletions JiraPS/Public/Add-JiraFilterPermission.ps1
Original file line number Diff line number Diff line change
@@ -1,37 +1,27 @@
function Add-JiraFilterPermission {
[CmdletBinding( SupportsShouldProcess )]
[CmdletBinding( SupportsShouldProcess, DefaultParameterSetName = 'ByInputObject' )]
[OutputType( [JiraPS.FilterPermission] )]
param(
# Filter object to which the permission should be applied
[Parameter( Mandatory, ValueFromPipeline )]
[Parameter( Position = 0, Mandatory, ValueFromPipeline, ParameterSetName = 'ByInputObject' )]
[ValidateNotNullOrEmpty()]
[PSTypeName('JiraPS.Filter')]
$Filter,

# Type of the permission to add
[Parameter( Mandatory )]
[Parameter( Position = 0, Mandatory, ValueFromPipeline, ParameterSetName = 'ById')]
[UInt32[]]
$Id,

[Parameter( Position = 1, Mandatory )]
[ValidateNotNullOrEmpty()]
[ValidateSet('Group', 'Project', 'ProjectRole', 'Authenticated', 'Global')]
[String]$Type,

# Value for the Type of the permission
#
# The Value differs per Type of the permission.
# Here is a table to know what Value to provide:
#
# |Type |Value |Source |
# |-------------|---------------------|----------------------------------------------------|
# |Group |Name of the Group |Can be retrieved with `(Get-JiraGroup ...).Name` |
# |Project |Id of the Project |Can be retrieved with `(Get-JiraProject ...).Id` |
# |ProjectRole |Id of the ProjectRole|Can be retrieved with `(Get-JiraProjectRole ...).Id`|
# |Authenticated| **must be null** | |
# |Global | **must be null** | |
[String]$Value,

# Credentials to use to connect to JIRA.
#
# If not specified, this function will use anonymous access.
[PSCredential]
$Credential
[Parameter()]
[System.Management.Automation.PSCredential]
[System.Management.Automation.Credential()]
$Credential = [System.Management.Automation.PSCredential]::Empty
)

begin {
Expand All @@ -44,6 +34,12 @@
Write-DebugMessage "[$($MyInvocation.MyCommand.Name)] ParameterSetName: $($PsCmdlet.ParameterSetName)"
Write-DebugMessage "[$($MyInvocation.MyCommand.Name)] PSBoundParameters: $($PSBoundParameters | Out-String)"

if ($PSCmdlet.ParameterSetName -eq 'ById') {
$InputObject = foreach ($_id in $Id) {
Get-JiraFilter -Id $_id
}
}

$body = @{
type = $Type.ToLower()
}
Expand Down
125 changes: 125 additions & 0 deletions Tests/Add-JiraFilterPermission.Tests.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
Describe 'Add-JiraFilterPermission' {
BeforeAll {
Remove-Module JiraPS -ErrorAction SilentlyContinue
Import-Module "$PSScriptRoot/../JiraPS" -Force -ErrorAction Stop
}

InModuleScope JiraPS {

. "$PSScriptRoot/Shared.ps1"

#region Definitions
$jiraServer = "https://jira.example.com"

$responseFilter = @"
{
"self": "$jiraServer/rest/api/latest/filter/12844",
"id": "12844",
"name": "{0}",
"jql": "{1}",
"favourite": false
}
"@
#endregion Definitions

#region Mocks
Mock Get-JiraConfigServer -ModuleName JiraPS {
$jiraServer
}

Mock ConvertTo-JiraFilterPermission -ModuleName JiraPS {
$i = (ConvertFrom-Json $responseFilter)
$i.PSObject.TypeNames.Insert(0, 'JiraPS.FilterPermission')
$i
}

Mock Get-JiraFilter -ModuleName JiraPS {
ConvertTo-JiraFilter
}

Mock Invoke-JiraMethod -ModuleName JiraPS -ParameterFilter {$Method -eq 'Post' -and $URI -like "$jiraServer/rest/api/*/filter"} {
ShowMockInfo 'Invoke-JiraMethod' 'Method', 'Uri', 'Body'
ConvertFrom-Json $responseFilter
}

Mock Invoke-JiraMethod -ModuleName JiraPS {
ShowMockInfo 'Invoke-JiraMethod' 'Method', 'Uri'
throw "Unidentified call to Invoke-JiraMethod"
}
#endregion Mocks

Context "Sanity checking" {
$command = Get-Command -Name Add-JiraFilterPermission

defParam $command 'Filter'
defParam $command 'Type'
defParam $command 'Value'
defParam $command 'Credential'
}

Context "Behavior testing" {
It "Invokes the Jira API to create a filter" {
{
$newData = @{
Name = "myName"
Description = "myDescription"
JQL = "myJQL"
Favorite = $true
}
New-JiraFilter @newData
} | Should Not Throw

Assert-MockCalled -CommandName Invoke-JiraMethod -ModuleName JiraPS -Exactly -Times 1 -Scope It -ParameterFilter {
$Method -eq 'Post' -and
$URI -like '*/rest/api/*/filter' -and
$Body -match "`"name`":\s*`"myName`"" -and
$Body -match "`"description`":\s*`"myDescription`"" -and
$Body -match "`"jql`":\s*`"myJQL`"" -and
$Body -match "`"favourite`":\s*true"
}
}
}

Context "Input testing" {
It "-Name and -JQL" {
{
$parameter = @{
Name = "newName"
JQL = "newJQL"
}
New-JiraFilter @parameter
} | Should Not Throw

Assert-MockCalled -CommandName Invoke-JiraMethod -ModuleName JiraPS -Exactly -Times 1 -Scope It
}
It "-Name and -Description and -JQL" {
{
$parameter = @{
Name = "newName"
Description = "newDescription"
JQL = "newJQL"
}
New-JiraFilter @parameter
} | Should Not Throw

Assert-MockCalled -CommandName Invoke-JiraMethod -ModuleName JiraPS -Exactly -Times 1 -Scope It
}
It "-Name and -Description and -JQL and -Favorite" {
{
$parameter = @{
Name = "newName"
Description = "newDescription"
JQL = "newJQL"
Favorite = $true
}
New-JiraFilter @parameter
} | Should Not Throw

Assert-MockCalled -CommandName Invoke-JiraMethod -ModuleName JiraPS -Exactly -Times 1 -Scope It
}
It "maps the properties of an object to the parameters" {
{ Get-JiraFilter "12345" | New-JiraFilter } | Should Not Throw
}
}
}
}
131 changes: 92 additions & 39 deletions docs/en-US/commands/Add-JiraFilterPermission.md
Original file line number Diff line number Diff line change
@@ -1,68 +1,74 @@
---
external help file: JiraPS-help.xml
Module Name: JiraPS
online version:
online version: https://atlassianps.org/docs/JiraPS/commands/Add-JiraFilterPermission/
locale: en-US
schema: 2.0.0
layout: documentation
permalink: /docs/JiraPS/commands/Add-JiraFilterPermission/
---

# Add-JiraFilterPermission

## SYNOPSIS
{{Fill in the Synopsis}}

Share a Filter with other users.

## SYNTAX

### ByInputObject (Default)

```powershell
Add-JiraFilterPermission [-Filter] <JiraPS.Filter> [-Type] <String> [[-Value] <String>]
[[-Credential] <PSCredential>] [-WhatIf] [-Confirm] [<CommonParameters>]
```
Add-JiraFilterPermission [-Filter] <Object> [-Type] <String> [[-Value] <String>] [[-Credential] <PSCredential>]
[-WhatIf] [-Confirm] [<CommonParameters>]

### ById

```powershell
Add-JiraFilterPermission [-Id] <UInt32> [-Type] <String> [[-Value] <String>]
[[-Credential] <PSCredential>] [-WhatIf] [-Confirm] [<CommonParameters>]
```

## DESCRIPTION
{{Fill in the Description}}

Share a Filter with other users, such as "Group", "Project", "ProjectRole",
"Authenticated" or "Global".

## EXAMPLES

### Example 1

```powershell
PS C:\> {{ Add example code here }}
Add-JiraFilterPermission -Filter (Get-JiraFilter 12345) -Type "Global"
#-------
Add-JiraFilterPermission -Id 12345 -Type "Global"
```

{{ Add example description here }}

## PARAMETERS
Two methods of sharing Filter 12345 with everyone.

### -Confirm
Prompts you for confirmation before running the cmdlet.

```yaml
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
### Example 2

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
```powershell
12345 | Add-JiraFilterPermission -Type "Authenticated"
```

### -Credential
{{Fill Credential Description}}
Share Filter 12345 with authenticated users.

```yaml
Type: PSCredential
Parameter Sets: (All)
Aliases:
_The Id could be read from a file._

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

```powershell
Get-JiraFilter 12345 | Add-JiraFilterPermission -Type "Group" -Value "administrators"
```

Share Filter 12345 only with users in the administrators groups.

## PARAMETERS

### -Filter
{{Fill Filter Description}}

Filter object to which the permission should be applied

```yaml
Type: Object
Expand All @@ -77,7 +83,8 @@ Accept wildcard characters: False
```
### -Type
{{Fill Type Description}}
Type of the permission to add
```yaml
Type: String
Expand All @@ -93,7 +100,19 @@ Accept wildcard characters: False
```
### -Value
{{Fill Value Description}}
Value for the Type of the permission.
The Value differs per Type of the permission.
Here is a table to know what Value to provide:
|Type |Value |Source |
|-------------|---------------------|----------------------------------------------------|
|Group |Name of the Group |Can be retrieved with `(Get-JiraGroup ...).Name` |
|Project |Id of the Project |Can be retrieved with `(Get-JiraProject ...).Id` |
|ProjectRole |Id of the ProjectRole|Can be retrieved with `(Get-JiraProjectRole ...).Id`|
|Authenticated| **must be null** | |
|Global | **must be null** | |

```yaml
Type: String
Expand All @@ -107,7 +126,25 @@ Accept pipeline input: False
Accept wildcard characters: False
```

### -Credential

Credentials to use to connect to JIRA.
If not specified, this function will use anonymous access.

```yaml
Type: PSCredential
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.

Expand All @@ -123,18 +160,34 @@ 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
```

### 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

### System.Object
### [JiraPS.Filter]

## OUTPUTS

### System.Object
### [JiraPS.FilterPermission]

## NOTES

Expand Down
Loading

0 comments on commit 6f76a61

Please sign in to comment.