projectdoc Toolbox

Space shortcuts

Page tree

projectdoc Toolbox


Accessing projectdoc Properties with cURL

Learn how to access projectdoc properties via REST API with cURL.

Parent
Tips
Audience
Author, Documentation Architect, Documentation Gardener
Level of Experience
Advanced Beginner
Expected Duration
15 min
Tags
Confluence, curl, property, REST
Type
Tip
Contents

projectdoc documents provide properties via the Document Properties Marker Macro.

These properties may define and document real configuration data or metadata information. Therefore there are use cases where teams want to access these properties from other information systems.

This tip will help you making the first steps using cURL from the command-line to access these properties.

The projectdoc Web API Extension provides REST resources which can be queried using REST API calls via cURL (a command-line tool for transferring data using various protocols).

Prerequisites

Install cURL

Download and install cURL.

Use apt

 

On ubuntu use:

apt-get install curl

Install the projectdoc Web API Extension

To use the REST API for the projectdoc Toolbox you have to install the Web API Extension for Confluence. The Web API Extension is available on the Atlassian Marketplace.

Optional

Learn how to Login to Confluence with cURL

To access Confluence via its REST API with cURL you typically need to authenticate. Learn how to login with cURL and avoid some common security pitfalls.

Read REST Login to Confluence with cURL to learn how to login using cURL.

Optional

Install XML Commandline Tool

xmlstarlet may be helpful to enhance the readability and for further processing of XML responses from the REST API.



Optional

Install JSON Processor

These additional tools may be helpful to enhance the readability and for further processing of JSON responses from the REST API:



Optional

Install Perl

install Perl using:

apt-get install perl

if you want to use urlencode to encode URLs containing special characters. 

Some other solutions are discussed here: how to urlencode data for curl command

Executing REST Calls

After having installed the projectdoc Web API Extension to your Confluence instance choose a login method and start using the REST API. All the following examples use a cookie based login but feel free to take another choice.

This section will provide some examples how to get you started.

Let's assume you have already created a projectdoc workspace and at least created a simple projectdoc document.

Query the Properties of a projectdoc Document

Query a newly created projectdoc document for its properties. To build such a query you need the ID of the projectdoc document. An easy way to get the ID of a document is to navigate to the Confluence page, since the page ID matches the document ID. Use the Confluence search and than click the "Page Information" action from the menu and copy the page ID from the URL:

Another option is to use the following JavaScript command in the console of your browser: AJS.params.pageId

 

This tip addresses all Web API Extension versions since 1.0. Starting with Version 1.1 it is mandatory to use the request parameter expand=property to retrieve properties. For older versions this property does not exist.

Now let us use this page ID in your first query:

Query the properties of a projectdoc document
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property

Here you can see the response:

Response
 {"id":123456789,"property":[{"name":"Doctype","value":"homepage"},{"name":"Name","value":"ManualTests Home"},{"name":"Short Description","value":"homepage"},{"name":"Tags","value":""},{"name":"use-confluence-macro-style","value":"false"},{"name":"name-list-default-boxstyle","value":"true"},{"name":"name-list-aaabb-boxstyle","value":"false"},{"name":"Creation Date","value":"22 Dec 2015"},{"name":"Creation Timestamp","value":"0000001450780454000"},{"name":"Creator","value":"anton.kronseder"},{"name":"Title","value":"ManualTests Home"},{"name":"Space Key","value":"MAN"},{"name":"Space Title","value":"ManualTests Home"},{"name":"Last Modification Date","value":"22 Dec 2015"},{"name":"Last Modification Timestamp","value":"0000001457108295000"},{"name":"Page ID","value":"4653082"},{"name":"Last Modifier","value":"anton.kronseder"},{"name":"Wiki Type","value":"page"},{"name":"Creation Date Timestamp","value":"0000001450738800000"},{"name":"Creation Date$","value":"22 Dec 2015"},{"name":"Creation Date§","value":"20151222"},{"name":"Last Modification Date Timestamp","value":"0000001450738800000"},{"name":"Last Modification Date$","value":"22 Dec 2015"},{"name":"Last Modification Date§","value":"20151222"},{"name":"Sort Key","value":"ManualTests Home"},{"name":"Index Key","value":"M"},{"name":"VersionHistory","value":"anton.kronseder:2016-03-04, anton.kronseder:2015-12-22"},{"name":"DocumentPropertyRefs","value":""},{"name":"Relative URL","value":"/display/MAN/ManualTests+Home"},{"name":"URL","value":"https://www.example.com/confluence/display/MAN/ManualTests+Home"},{"name":"Tiny URL","value":"https://www.example.com/confluence/x/GgBH"}]}

Now let us prettify the the response by sending the response to jq:

Query the properties of a projectdoc document (pretty)
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property | jq .
Response (pretty)
 {
  "id": 123456789,
  "property": [
    {
      "name": "Doctype",
      "value": "homepage"
    },
...
  ]
}

Besides JSON you can also get the response as XML. Just omit the extension or use .xml as extension:

Query the properties of a projectdoc document (xml)
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789?expand=property
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.xml?expand=property
Response (xml)
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?><document id="123456789"><property><name>Doctype</name><value>homepage</value></property><property><name>Name</name><value>ManualTests Home</value></property><property><name>Short Description</name><value>homepage</value></property><property><name>Tags</name><value></value></property><property><name>use-confluence-macro-style</name><value>false</value></property><property><name>name-list-default-boxstyle</name><value>true</value></property><property><name>name-list-aaabb-boxstyle</name><value>false</value></property><property><name>Creation Date</name><value>22 Dec 2015</value></property><property><name>Creation Timestamp</name><value>0000001450780454000</value></property><property><name>Creator</name><value>anton.kronseder</value></property><property><name>Title</name><value>ManualTests Home</value></property><property><name>Space Key</name><value>MAN</value></property><property><name>Space Title</name><value>ManualTests Home</value></property><property><name>Last Modification Date</name><value>22 Dec 2015</value></property><property><name>Last Modification Timestamp</name><value>0000001457108295000</value></property><property><name>Page ID</name><value>4653082</value></property><property><name>Last Modifier</name><value>anton.kronseder</value></property><property><name>Wiki Type</name><value>page</value></property><property><name>Creation Date Timestamp</name><value>0000001450738800000</value></property><property><name>Creation Date$</name><value>22 Dec 2015</value></property><property><name>Creation Date§</name><value>20151222</value></property><property><name>Last Modification Date Timestamp</name><value>0000001450738800000</value></property><property><name>Last Modification Date$</name><value>22 Dec 2015</value></property><property><name>Last Modification Date§</name><value>20151222</value></property><property><name>Sort Key</name><value>ManualTests Home</value></property><property><name>Index Key</name><value>M</value></property><property><name>VersionHistory</name><value>anton.kronseder:2016-03-04, anton.kronseder:2015-12-22</value></property><property><name>DocumentPropertyRefs</name><value></value></property><property><name>Relative URL</name><value>/display/MAN/ManualTests+Home</value></property><property><name>URL</name><value>https://www.example.com/confluence/display/MAN/ManualTests+Home</value></property><property><name>Tiny URL</name><value>https://www.example.com/confluence/x/GgBH</value></property></document>

In conjunction with xmlstarlet you can also prettyprint it:

Query the properties of a projectdoc document (xml | pretty)
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.xml?expand=property | xmlstarlet  format --indent-tab
Response (xml | pretty)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document id="123456789">
 <property>
 <name>Doctype</name>
 <value>homepage</value>
 </property>
 <property>
 <name>Name</name>
 <value>ManualTests Home</value>
 </property>
 <property>
 <name>Short Description</name>
 <value>homepage</value>
 </property>...</document>

Receiving Property Names, Values or both

Receiving only the property names or values or even both is very easy using jq for JSON:

Query the properties of a projectdoc document (pretty)
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property | jq .property[].name
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property | jq .property[].value
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property | jq .property[].
Responses
Names:
 
"Doctype"
"Name"
"Short Description"
...
 
Values:
 
"homepage"
"ManualTests Home"
"homepage"
...
 
Names and Values:
 
{
  "name": "Doctype",
  "value": "homepage"
}
...

If you would like to receive the values in a more compact form use the following expression:

Query the properties of a projectdoc document (pretty)
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property | \
	jq   '[.property[] | { key : .name , value: .value}] | from_entries '
Response
{
 "Doctype": "homepage",
 "Name": "ManualTests Home",
 "Short Description": "homepage",
 "Tags": "",
 ...
}

Receive a single Property

Receiving only one property by accessing it explicitly (instead of filtering for it).

  • get the full property
  • get only the value
  • get the value without quotes
Receive a single property
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/Doctype.json?expand=property | jq .
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/Doctype.json?expand=property | jq .value
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/Doctype.json?expand=property | jq -r .value
Responses
Full property:
 
{
  "name": "Short Description",
  "value": "homepage",
  "document-id": 123456789
}


Only the value:
 
"homepage"
 
The value without quotes:
 
homepage

If the property (key) contains special characters which can not be part of an URL, they have to be escaped. For example see how the property "Short Description" is retrieved:

Receive a single property with special chars
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/Short%20Description.json?expand=property | jq .
 
or using a variable in conjunction with perl:
 
property="$(perl -MURI::Escape -e 'print uri_escape($ARGV[0]);'  "Short Description")"
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/${property}.json?expand=property | jq .
Response
{
  "name": "Short Description",
  "value": "homepage",
  "document-id": 12456789
}

References

  • REST API Browser - Confluence Built-in API client to execute available methods and examine responses.
  • Confluence REST API Examples - This page contains examples of using the Confluence Content REST API using curl
  • JQ - a lightweight and flexible command-line JSON processor
  • xmlstarlet - Command Line XML Toolkit

Resources

Accessing projectdoc Space Properties with cURL
Learn how to access projectdoc space properties via REST API with cURL.
REST Login to Confluence with cURL
To access Confluence via its REST API with cURL you typically need to authenticate. Learn how to login with cURL and avoid some common security pitfalls.

About

This site is maintained by smartics.

Imprint / Impressum

Data Privacy / Datenschutz 

End User License Agreement (EULA)


To get in touch please send us an e-mail!

smartics email

Keep up-to-date!

Read our

smartics Blog

Follow us on

Twitter YouTube Prezi

Find us on

Bitbucket GitHub Atlassian Marketplace

Powered by




© 2001-2023 smartics - Kronseder & Reiner GmbH