I am finding a lot of limitations of the REST API.
I am creating the tickets and tagging them.
However.... that makes me think:

How will we handle a function that uses an API that does not work on all Confluence versions?

Current behavior

currently the method gettype() of a collection of custom object returns

System.Object[]

Expected behavior

the method gettype() of a collection of custom object returns a collection of the custom object. such as (for a collection of pages):

ConfluencePS.Page[]

The logic of building the GET parameter string is repeated in a lot of functions
These shall be extracted in order for Invoke-WikiMethod to hold that logic

In the latest version, and the immediately prior version, Get-WikiPage fails silently for "-Limit" values in the range [1..4] inclusive. However, 0 and seemingly any value above 4 works. Negative values result in an understandable HTTP 500 Server Error from Confluence.

Get-WikiPage -Title somepage -SpaceKey somespacekey -Limit n

Where:

• somepage exists (and is returned for limits of zero or above 4).
• somespacekey exists (and is returned for limits of zero or above 4).
• n is some limit number.

It's of course relatively easy to avoid the issue. Just thought you might want to know.
Oh! And, THANKS!! This tool looks very useful.

It is possible to add a mandatory parameter to all functions and set the value through $PSDefaultParameterValues in Set-WikiInfo.

This brings the advantage of allowing the user to use a function without having to set the wiki info before hand.
Behavior is unchanged if user uses the functions as currently implemented

My Confluence structure looks like this:

I can't refer to my parent page by name because of API restrictions (too many pages), so I refer to it by its ID and I get only it's name, id etc.
Looks like everything works how it's supposed to but I'd like to know, is there any way (using your module) to get all child pages from a parent one?

If not, I'll try to write a function that will do it using this example.

Implement pagination for Get-* functions

I'm using the latest version of module (cloned the repo today).

$pages = Get-WikiSpace -Name "KB" | Get-WikiPage -Limit 100 -Expand`

$pages.Title | Measure-Object -Line`

Lines Words Characters Property
----- ----- ---------- --------
  100                  

Okay, let's try to get all pages (I have about 107 pages).

$pages = Get-WikiSpace -Name "KB" | Get-WikiPage -Limit 300 -Expand

$pages.Title | Measure-Object -Line

Lines Words Characters Property
----- ----- ---------- --------
  100  

$pages = Get-WikiSpace -Name "KB" | Get-WikiPage -Limit 1000 -Expand

$pages.Title | Measure-Object -Line

Lines Words Characters Property
----- ----- ---------- --------
  100

Last 3 modules that Powershell got from Confluence

The rest of modules that wasn't included though they are present in Confluence among other pages.

I'm not sure if this REST API issue or ConfluencePS module issue or maybe some kind of limit but I've thought you should know that. You can freely contact me if you need any details.

Add a script for one-line installation in environments without PowerShellGet
(E.g.: jaykul/Profile)

It is possible to give permissions for resources on confluence to be accessible for non-authenticated users.

This behavior must be available with this module

thanks to @Jaykul

function scope { 
[CmdletBinding()]
param(
  [Parameter(Mandatory)]
  [scriptblock]$scriptblock,
  [Parameter(ValueFromRemainingArguments)]
  $Params
)
  $PSDefaultParameterValues = @{}  
  while($Params) {
    $param, $value, $Params = $Params
    $param = $param.trimStart("-").trimEnd(":")
    if($param -notmatch ":") {
        $param = "*:" + $param
    }
    $PSDefaultParameterValues[$param] = $value
  }
  $PSDefaultParameterValues | Out-Default
  . $scriptblock
}

$code = {Get-Verb | Format-Wide}

scope $code -Column 4 -Verb S*

The refactoring change a lot of parameters of the functions.
The .parameter, .example, .output, .input must be updated

It'd be nice if ConvertTo-WikiTable supported:

1. An option to output a header column, instead of a header row
2. Natively supporting being passed a hashtable object?

Description

The current implementation of Invoke-WikiMethod's paging does not support the pipeline correctly.

Demonstration

$result = Get-WikiPage -Space Foo -PageSize 100
$result.Count # = 1000

This code will have invoked Invoke-WikiMethod 10 time where each invocation returned a result set of 100 entries. Resulting in a collection of 1000 in total.

$result = Get-WikiPage -Space Foo -PageSize 100 | Select-Object -First 50
$result.Count # = 1000

This code will have done the same as the first, but will later select the first 50 entries of the result set and return them - where only 1 invocation of Invoke-WikiMethod would have been enough.

Fix

Invoke-WikiMethod must be updated so that it will no longer append to arrays, but return to StdOut at once:

# None paginated results / first page of pagination
if (($result) -and ($result | Get-Member -Name results)) {
    $result = $result.results
}
if($OutputType) { 
    $result | & $converter
} else {
    $result
}

if ($result._links.next) {
   Write-Verbose "[Invoke-WikiMethod] Invoking pagination"

   # Self-Invoke function for recursion
   $parameters = @{
       URi = "{0}{1}" -f $result._links.base, $result._links.next
       Method = $Method
   }
   if ($Body) {$parameters["Body"] = $Body}
   if ($Headers) {$parameters["Headers"] = $Headers}
   if ($GetParameters) {$parameters["Get$GetParameters"] = $GetParameters}

   Write-Output Invoke-WikiMethod @parameters
}

Additionally

[CmdletBinding(SupportsPaging = $true)] enables a function to support paging on itself.
This exposes parameters such as -Skip, -IncludeTotalCount and -First.
this could be implemented in the likes of:

$PSBoundParameters["Skip"] = $PSCmdlet.PagingParameters.Skip + $result.Count
$PSBoundParameters["First"] = $PSCmdlet.PagingParameters.First - $result.Count
Invoke-WikiMethod @PSBoundParameters

Hi.

I am very exited to have found your repo.
I wrote something similar a long time ago (using the SOAP api) and was feeling lazy migrating to the REST api; especial now, that a lot of methods are not yet supported by the REST api - or I am unsure how to support both (REST & XMLRPC) simultaneously (my company is still on 9.1.x - where REST is still seriously lacking).

In case you want to have a look, my repo is https://github.com/lipkau/PsConfluence

I am planing on submitting some PRs to this repo 👍

BR
Oliver

Test driving the 2.0 develop branch:

I dislike Add-WikiLabel having both a -Label and a -Labels parameter. It's ambiguous, and requires the user to Get-Help Add-WikiLabel -Parameter * to discern the difference.

https://github.com/brianbunke/ConfluencePS/blob/d7c9adfd9dec99f03a03097e020c5ca077ff236a/ConfluencePS/Public/Add-WikiLabel.ps1

Suggested Solution

Change -Labels to -LabelSet?

According to the API, Page, Attachment, Comment and Blog are "content".
It would be possible to reflect that in the module:

$result = Get-WikiContent -PageID 1234
$result.type -eq "page"

I like the dedicated functions and object types for different content types better.
But it is only fare to open it for discussion.

If we would do that, that would mean major breaking changes.
Further: it would not only be hard, but pointless of having custom objects

Applies to branch develop (2.0) as of 2017/06/18.

Expected Behavior

No error expected.

Current Behavior

# Didn't test if setting the PageSize helps cause this or not, so including just in case
Set-WikiInfo -BaseURi 'https://wiki.example.com' -PageSize 3 -PromptCredentials
Get-WikiSpace -Verbose

Get-WikiSpace passes $GETparameters to Invoke-WikiMethod.

Invoke-WikiMethod then seems to go circular on itself, due to the parameter continuing to call ConvertTo-GetParameter on each iteration, malforming the URI with too many appends, and apparently retrying repeatedly when it fails? (Didn't care to investigate that last part too deeply.)

(See also: #51/#55)

Not copying further error details here because lazy + self-assigning.

Possible Solution

Submitting a PR shortly with my suggested fix. If we'd like to discuss further, we can cover options in the comments.

When using -InputObject on Set-WikiPage, the ancestors property is ignored.
This is must be implemented.

Current behavior

Currently there is one function to get pages, one to get child pages and one to get pages by label

Proposition

Allow Get-WikiPage to do all of these by:

# Get a page by object (useful, when you have a page object without all properties (eg: $page.ancestors))
Get-WikiPage -inputObject $somePage.ancestors

# Get a page by id
Get-WikiPage -pageID @(1,2,3)

# Get all pages of space
Get-WikiPage -spaceKey "RD"

# Get all pages with title
Get-WikiPage -Title "Home"

# Get a page with title in space
Get-WikiPage -Title "Home" -SpaceKey "RD"

# Get a page and all it's children (works with all inputs above)
$pageObject | Get-WikiPage -Recurse

# Get all pages with label
Get-WikiPage -label "meeting-notes","foo" [-SpaceKey <string>]

@brianbunke :
please let me know what you think
If you agree, I will make the changes and add them to my refactoring branch

Allow to write a comment when using Set-WikiPage

Expectation

Manage Comments
https://developer.atlassian.com/cloud/confluence/rest/#api-content-id-child-comment-get

Interactions:

• ADD
  Add a new comment to a page
• GET
  get a list of comments
• REMOVE
  remove a comment

Object:

ConfluencePS.Comment:

• ID
• Type = comment
• Title
• Body
• [Comment]ChildComments ?

Examples

.EXAMPLE
Get-WikiPage -PageID 1234 | Get-WikiComment
Returns a list of all page versions of page 1234

.EXAMPLE
Get-WikiComment -PageID 1234
Returns a list of all page versions of page 1234

Taking the 2.0 develop branch for a test drive.

https://github.com/brianbunke/ConfluencePS/blob/d7c9adfd9dec99f03a03097e020c5ca077ff236a/ConfluencePS/Private/Invoke-WikiMethod.ps1#L161

Expected Behavior

No error expected.

Current Behavior

Invoke-WikiMethod : A parameter cannot be found that matches parameter name 'GetSystem.Collections.Hashtable'.
[...]
\Private\Invoke-WikiMethod.ps1:164 char:41
$result.results += (Invoke-WikiMethod @parameters)

Steps to Reproduce (for bugs)

Set-WikiInfo -BaseURi 'https://wiki.example.com' -PromptCredentials -PageSize 3
Get-WikiSpace
# Same error occurs above and below
Get-WikiPage

Your Environment

• Operating System and PowerShell version: Win10 / 5.1.14393.1198
• ConfluencePS version: 2.0 develop

I personally find it confusing (or at least not aligned to best practices), that New-WikiLabel attaches a label to a page.
I would have believed that this functions creates a new label on confluence which I can use later on on pages.

I would propose to refactor the function so that:

# Gets all pages with label "important"
Get-WikiPage -Label "important"

# Adds a label to a page
$page | Add-WikiLabel -Label "label1","label2"

# Remove a label from a page
$page | Remove-WikiLabel -label "label1","label2"

this would deprecate New-WikiLabel

Some APIs (like Remove-WikiSpace) do not finish immediately, but return a "longtask" status link.

This must be handled. Maybe as a Job?

New-WikiLabel shall work in this 2 ways:

# Take pages from pipe
## sets the labels "1" and "2" on all pages in space "foo" 
Get-WikiPage -SpaceKey "foo" | New-WikiLabel -Label @(1,2)

# Take labels from pipe
## sets the labels from page 12345 to ALL pages in space "foo"
Get-WikiPageLabel -PageId 12345 | New-WikiLabel -PageID (Get-WikiPage -SpaceKey "foo")

Make ConvertTo-WikiPage more robust, in order to make ConvertTo-WikiPageAncestor superfluous.

The code used to determine what columns are returned from Get-WikiResults has a lot of duplication.
Refactor to reduce duplication / make it more apparent what the differences are for each condition.

Applies to branch develop (2.0) as of 2017/06/18.

Expected Behavior

Get-WikiPage returns all pages (or, once pagination is fixed, the correct page size).

Current Behavior

Get-WikiPage prompts for -PageID (a required parameter in the default parameter set), and fails when one is not provided.

Steps to Reproduce (for bugs)

1. Get-WikiPage

Possible Solution

I do not yet have a technical solution to propose. This issue is primarily intended to be a discussion.

Context

I expect Get-WikiSpace and Get-WikiPage, with no parameters, to be fairly common "discovery commands" from new users. I'm using them to wrap my head around the changes in the develop branch, so it's a little weird to me that Get-WikiPage is erroring out.

I've labeled this "Milestone v2.0," but I just want us to get on the same page before that ships. Fixing this isn't absolutely required if we agree on something else.

If we agree that these commands should work in "vanilla" mode (no other specified parameters), this usage needs to be added to the integration test suite.

Expectation

Manage Page versions

Interactions:

• GET
  return a list of version of a page

Object

ConfluencePS.History:

• user who saved the change
• time
• means to get the content (id of the version?)

Examples

.EXAMPLE
Get-WikiPage -PageID 1234 | Get-WikiPageHistory
Returns a list of all page versions of page 1234

.EXAMPLE
Get-WikiPageHistory -PageID 1234
Returns a list of all page versions of page 1234

In invoke-wikimethod is a dirty workaround to add the PSDefaultParameterValues from the global to the local scope.
I added it because I needed the proxy settings from my global PSDefaultParameterValues.

However, PSJira uses a similar architecture but does not need this workaround.

Page body contains some French characters, so I can't publish it on Confluence using New-WikiPage command. I know it's a json restriction but maybe there's a way to do this.
Example string:

From the Language drop down, select "Français (Canada)

I've tried to encode it using

$enc = [system.Text.Encoding]::UTF8
$encodedBytes = $enc.GetBytes($content)  
$decodedString = $enc.GetString($encodedBytes)  

but it didn't worked. Is there any workaround? Thanks.

Currently all functions use ConfirmImpact = 'Medium'.

Some functions should use ConfirmImpact = 'High'.
Such as:

• Add-WikiLabel --> Low
• New-WikiPage --> Low
• New-WikiSpace --> Low
• Remove-WikiSpace --> High
• Remove-WikiPage --> Medium
• Remove-WikiLabel --> Low
• Set-WikiLabel --> Low
• Set-WikiPage --> Medium

implementing this includes a -Force flag to confirm this

It seems like ConvertTo-WikiTable should return a string instead of an array.

Get-Service | select name,status -First 3 | ConvertTo-WikiTable | ConvertTo-WikiStorageFormat

I get multiple tables for each row:

<table><tbody>
<tr>
<th><p>Name</p></th>
<th><p>Status</p></th>
</tr>
</tbody></table>

<table><tbody>
<tr>
<td><p>AdobeARMservice</p></td>
<td><p>Running</p></td>
</tr>
</tbody></table>

<table><tbody>
<tr>
<td><p>AeLookupSvc</p></td>
<td><p>Stopped</p></td>
</tr>
</tbody></table>

<table><tbody>
<tr>
<td><p>ALG</p></td>
<td><p>Stopped</p></td>
</tr>
</tbody></table>

I tried a lot of combinations to try to get one table but finally figured out out-string fixes it:

Get-Service | select name,status -First 3 | ConvertTo-WikiTable | out-string | ConvertTo-WikiStorageFormat

<table><tbody>
<tr>
<th><p>Name</p></th>
<th><p>Status</p></th>
</tr>
<tr>
<td><p>AdobeARMservice</p></td>
<td><p>Running</p></td>
</tr>
<tr>
<td><p>AeLookupSvc</p></td>
<td><p>Stopped</p></td>
</tr>
<tr>
<td><p>ALG</p></td>
<td><p>Stopped</p></td>
</tr>
</tbody></table>

Or maybe ConvertTo-WikiStorage should convert it to string. Or at least somewhere in the help documentation mentioning Out-String for ConvertTo-WikiTable.

Get-WikiSpace should:

• accept a key by positional parameter
• accept more than 1 key at a time

I like to declare the entry and exit point of functions in the verbose.
I also like to prefix all verbose and debug msgs with the current function name.
E.g.: https://github.com/lipkau/PsIni/blob/master/Functions/Get-IniContent.ps1
This is useful to track when piping or when a function call an other function.

Are you against this?

The logic to check how many results where returns is being reproduced in a lot of functions.
This logic should be extracted or placed into invoke-wikimethod

ideally, any function should be able to write the result of invoke-wikimethod to the default stream (Write-Output).
In order to do this, invoke-wikimethod will have to take a parameter to know to how to cast the output... something like -OutputAs [ConfluencePS.Page]

Testing needs improvements

This is my suggestion. Feel free to give better ideas ( @brianbunke )

Unit Tests

File location

• Add Unit tests for each function into the .\Tests\ folder
• Add Unit tests for each function in the same folder as the function it tests is located

Scope

• test each possible parameter combination
• test each possible value type that can be sent as input or received as output
• test each parameter if it handles wrong input correctly (type, pipe, etc)

Integration Tests

Scope

• test each possible parameter combination

checkboxes visualize what has been agreed upon

Should Set-WikiPage allow to set the labels of the page?

Description

In order to have a documentation that is easier to access, easier to edit and maintain, and more flexible, we shall use PlatyPS for the help of the function.
Discussion on this topic: AtlassianPS/AtlassianPS#1

Task

• Migrate all Comment Based Help to .md files in /docs

Import-Module MyAwesomeModule
New-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\docs

• Edit the .md files (.EXAMPLE block can have more that 1 command in it)
• Create the about_<module>

New-MarkdownAboutHelp -OutputFolder C:\Test -AboutName

• Make AppVeyor generate the ExternalHelp file (.xml) when building

New-ExternalHelp -Path ".\docs" -OutputPath "out\platyPS\en-US"

• Remove the Comment Based Help from all functions in the module

As the v2.0 milestone is nearly finished, some tasks are still open in order to release v2.0:

• Update documentation
• Update README
• Version bump
• Merge develop into master

• Create release notes
• Add release notes to psd1

To restore a piece of content that has the status of trashed the content must have it's version incremented, and status set to current. No other field modifications will be performed when restoring a piece of content from the trash.
Request example to restore from trash: { "id": "557059", "status": "current", "version": { "number": 2 } }

Some functions lack the [OutputType()] declaration

-First is available on all 2.0 Get-* commands, but hasn't been implemented yet.

Expected Behavior

-First does something

Current Behavior

-First does nothing 😆
Get-ConfluenceSpace | Select -First 1 still works as expected.

Possible Solution

Comment it out in the 2.0 release, so that we have a head start for future implementation, while ensuring that we're not confusing anyone.

Steps to Reproduce (for bugs)

Get-ConfluenceChildPage
Get-ConfluenceLabel
Get-ConfluencePage
Get-ConfluenceSpace

Your Environment

ConfluencePS develop branch (future 2.0)

-IncludeTotalCount on the 2.0 Get-* commands seems to always return "Unknown total count" for me.

Expected Behavior

-IncludeTotalCount does something

Current Behavior

Regardless of whether PageSize is higher or lower than the actual total count of objects, I can't get any number to return. Instead, I always see "Unknown total count".

Possible Solution

I'd be fine if this parameter didn't exist. If you need to count, you can still (Get-ConfluenceSpace).Count. Happy to hear otherwise if I'm missing something, though.

Steps to Reproduce (for bugs)

Get-ConfluenceSpace -IncludeTotalCount
Get-ConfluencePage -SpaceKey TEST -IncludeTotalCount

Your Environment

ConfluencePS develop branch, future v2.0

Expectation

Manage attachments.
https://developer.atlassian.com/cloud/confluence/rest/#api-content-id-child-attachment-get

Interactions:

• ADD
  Add a new attachment to a page or create a new version of an existing attachment
• GET
  Get a list of attachments
• REMOVE
  Remove an attachment of a page

Object:

ConfluencePS.Attachment:

• ID
• Title
• MediaType
• MediaTypeDescription ?
• labels ?
• fileSize
• comment
• [History]history ?
• [Version]version
• Binary? Link to download binary?

Examples

.EXAMPLE
Get-WikiPage -PageID 1234 | Get-WikiAttachment
Returns a list of all page attachmanets of page 1234

.EXAMPLE
Get-WikiAttachment -PageID 1234
Returns a list of all page versions of page 1234

.EXAMPLE
Get-WikiAttachment -Label "meeting"
Returns a list of all attachments with label _meeting_