projectdoc Toolbox

Accessing projectdoc Properties with cURL

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

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:

JQ a lightweight and flexible command-line JSON processor
python (e.g. see: Parsing JSON from command line using Python)

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

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Prerequisites

Install cURL

Install the projectdoc Web API Extension

Learn how to Login to Confluence with cURL

Install XML Commandline Tool

Install JSON Processor

Install Perl

Executing REST Calls

Query the Properties of a projectdoc Document

Receiving Property Names, Values or both

Receive a single Property

References

About

Keep up-to-date!

Powered by