atlassianps / confluenceps Goto Github PK
View Code? Open in Web Editor NEWConfluence REST API (including Cloud) via PowerShell
Home Page: https://AtlassianPS.org/module/ConfluencePS
License: MIT License
Confluence REST API (including Cloud) via PowerShell
Home Page: https://AtlassianPS.org/module/ConfluencePS
License: MIT License
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*
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
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
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
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.
Applies to branch develop
(2.0
) as of 2017/06/18.
Get-WikiPage
returns all pages (or, once pagination is fixed, the correct page size).
Get-WikiPage
prompts for -PageID
(a required parameter in the default parameter set), and fails when one is not provided.
Get-WikiPage
I do not yet have a technical solution to propose. This issue is primarily intended to be a discussion.
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.
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]
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.
Change -Labels
to -LabelSet
?
The refactoring change a lot of parameters of the functions.
The .parameter, .example, .output, .input must be updated
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
.md
files in /docs
Import-Module MyAwesomeModule
New-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\docs
.md
files (.EXAMPLE
block can have more that 1 command in it)about_<module>
New-MarkdownAboutHelp -OutputFolder C:\Test -AboutName
New-ExternalHelp -Path ".\docs" -OutputPath "out\platyPS\en-US"
currently the method gettype()
of a collection of custom object returns
System.Object[]
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[]
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
-First
is available on all 2.0 Get-*
commands, but hasn't been implemented yet.
-First
does something
-First
does nothing 😆
Get-ConfluenceSpace | Select -First 1
still works as expected.
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.
Get-ConfluenceChildPage
Get-ConfluenceLabel
Get-ConfluencePage
Get-ConfluenceSpace
ConfluencePS develop
branch (future 2.0)
This is my suggestion. Feel free to give better ideas ( @brianbunke )
.\Tests\
foldercheckboxes visualize what has been agreed upon
Implement pagination for Get-*
functions
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?
Taking the 2.0 develop branch for a test drive.
No error expected.
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)
Set-WikiInfo -BaseURi 'https://wiki.example.com' -PromptCredentials -PageSize 3
Get-WikiSpace
# Same error occurs above and below
Get-WikiPage
develop
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 } }
Manage attachments.
https://developer.atlassian.com/cloud/confluence/rest/#api-content-id-child-attachment-get
ConfluencePS.Attachment
:
[History]
history ?[Version]
version.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_
Currently there is one function to get pages, one to get child pages and one to get pages by label
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
-IncludeTotalCount
on the 2.0 Get-*
commands seems to always return "Unknown total count" for me.
-IncludeTotalCount
does something
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".
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.
Get-ConfluenceSpace -IncludeTotalCount
Get-ConfluencePage -SpaceKey TEST -IncludeTotalCount
ConfluencePS develop
branch, future v2.0
Some APIs (like Remove-WikiSpace
) do not finish immediately, but return a "longtask" status link.
This must be handled. Maybe as a Job?
Currently all functions use ConfirmImpact = 'Medium'
.
Some functions should use ConfirmImpact = 'High'
.
Such as:
Add-WikiLabel
--> LowNew-WikiPage
--> LowNew-WikiSpace
--> LowRemove-WikiSpace
--> HighRemove-WikiPage
--> MediumRemove-WikiLabel
--> LowSet-WikiLabel
--> LowSet-WikiPage
--> Mediumimplementing 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.
Manage Page versions
ConfluencePS.History
:
.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
Allow to write a comment when using Set-WikiPage
Applies to branch develop
(2.0
) as of 2017/06/18.
No error expected.
# 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.)
Not copying further error details here because lazy + self-assigning.
Submitting a PR shortly with my suggested fix. If we'd like to discuss further, we can cover options in the comments.
Make ConvertTo-WikiPage
more robust, in order to make ConvertTo-WikiPageAncestor
superfluous.
Manage Comments
https://developer.atlassian.com/cloud/confluence/rest/#api-content-id-child-comment-get
ConfluencePS.Comment
:
[Comment]
ChildComments ?.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
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.
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.
Should Set-WikiPage
allow to set the labels of the page?
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.
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:
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.
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?
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.
Add a script for one-line installation in environments without PowerShellGet
(E.g.: jaykul/Profile)
As the v2.0 milestone is nearly finished, some tasks are still open in order to release v2.0:
develop
into master
The current implementation of Invoke-WikiMethod
's paging does not support the pipeline correctly.
$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.
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
}
[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
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")
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
When using -InputObject
on Set-WikiPage
, the ancestors property is ignored.
This is must be implemented.
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 functions lack the [OutputType()]
declaration
It'd be nice if ConvertTo-WikiTable
supported:
Get-WikiSpace
should:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.