Developer's Guide (v 1.2)
- Almuth Boehme [Communardo]
- Yelyzaveta Burda
About
Starting with Release 1.8, the User Profile Plugin provides a REST API which gives (read-only) access to data of the user profiles. Using the API you can get hold of the following data:
- all profile elements and their configuration
- the data which is stored for those elements for each user
General Information
We tried to keep as close as possible to the REST-Guidelines of Atlassian. So if you are familar with the REST API of Confluence, it should be quite easy for you to consume our API.
If you are using the Developer Tools Plugin, you can use the REST API Browser to play around with our API.
To access the API use the following URL
<Server Base URL>/rest/communardo/upp/<version>/<path to resource>
where
- <server base URL> is the server base URL of your Confluence instance
- <version> is the version of the API
- currently there is only one version: 1.0
- if you want to always use the most recent version of the API, use "latest" instead of "1.0"
- <path to resource> is the resource which you want to access, see below for details
Authentication
Depending on how you request the API you might have to consider authentication. If you are issuing requests using AJAX calls from a browser session you probably will not have to bother about this. Those calls will be authenticated using the browser session.
However, requests coming from other systems will have to authenticate in order to access the API. Currently the only authentication supported is basic access authentication:
- you have to provide anÂ
Authorization
header containing "Basic username:password
", with "username:password" being Base64 encoded - add the query parameter
os_authType=basic
to the URL (e.g. http://localhost:8080/rest/communardo/upp/latest/some/resource?os_authType=basic)
Data Formats
Currently responses by the API contain all data in JSON format only. There are no other formats supported.
Expansion
If you are familiar with the REST API of Confluence you might know the concept known as "expansion". It is basically allows you to control the amount of data, which each request to a resource returns by means of a request query parameter:
For each request to a resource supporting expansion you can provide a list of attributes with the parameter expand. The entities of those attributes will than contain more information. In order to find out which attributes you can expand on, you just have to check the attribute "expand" of the response. The value of this attribute lists all the supported attributes for expansion.
More details about this concept can be found in the Atlassian REST API Design Guidelines. Our examples below will also cover this topic in more detail.
Resources
The following sections describe the resources that are available via the API.
Profile Element Configuration
There are two resources which provide information about the profile element configuration.
Get a list of all profile elements (/profileElements)
- provides a list of all profile elements
- this are exactly the same elements as those accessible via the configuration of the user profile plugin
- the elements returned have the same order as defined via the configuration of the user profile plugin
- the result can be expanded on "profileElements", which will cause the returned list to contain all the information available for each element (see /profileElements/{elementKey} below for details)
Returned Data
The data structure returned by the request has the following attributes:
Attribute | Type | Value |
---|---|---|
expand | String | the name of the attribute which can be expanded on ("profileElements") |
profileElements | List | the list of profile elements
|
Example (without expansion)
Request:
http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/
Response:
{"expand":"profileElements", "profileElements":[{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/178640080"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/im"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/0861244944"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/phone"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/website"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/department"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/1185300867"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/location"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/position"}, {"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/personalInformation"}] }
Get information about a specific profile element - /profileElements/{elementKey}
- provides the information of the element with the key {elementKey}
- provides the same information as the configuration of the user profile plugin and some additional information
Returned Data
The entity returned by the request has the following attributes:
Attribute | Type | Value |
---|---|---|
key | String | the key of the profile element |
nameForCurrentLocale | String | the title of the profile element with the translation for the currently authenticated user (default or German) |
defaultName | String | the Default Title of the profile element |
germanName | String | the German Title of the profile element |
helpTextForCurrentLocale | String | the help text of the profile element with the translation for the currently authenticated user (default or German) |
defaultHelpText | String | the Default Help Text of the profile element |
germanHelpText | String | the German Help Text of the profile element |
profileGroup | String | the profile group which this element belongs to (either "personal" or "business") |
elementType | String | the Field Type of the profile element, one of:
|
ldapAttributeMapping | String | The value for the configured LDAP attribute mapping |
displayInCustomMode | Boolean | whether or not this element is displayed using the mode "custom" of the enhanced profile macro |
hidden | Boolean | whether this element is hidden (always false for additional profile elements, as those can currently not be hidden) |
personalInformationElement | Boolean | whether this element is the element containing the "About Me" information of the standard Confluence profile |
standard | Boolean | whether this element is a standard (true) or additional (false) profile element |
self | String | the URL of the returned resource |
Example (for request authenticated to user with German locale)
Request:
http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159
Response:
{"key":"01050669159", "nameForCurrentLocale":"Vorgesetzter", "defaultName":"Superior", "germanName":"Vorgesetzter", "helpTextForCurrentLocale":"Bitte hier den Vorgesetzten eingeben...", "defaultHelpText":"Enter your superior here...", "germanHelpText":"Bitte hier den Vorgesetzten eingeben...", "profileGroup":"personal", "elementType":"USER_FIELD", "ldapAttributeMapping":"%%superior%%", "displayInCustomMode":false, "hidden":false, "personalInformationElement":false, "standard":false, "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159" }
Profile Element Data
There are two resources provided to access profile data for individual users.
Get all profile data for a specific user (/profileData/{user})
- lists the profile data for each profile element for the user provided by {user}
- the returned list of element data has the same order as defined via the configuration of the user profile plugin
- the result can be expanded on "profileData.profileElement", which will cause the result to contain additional information about the profile elements (see /profileData/{user}/{elementKey} for an example)
Returned Data
The entity returned by the request has the following attributes:
Attribute | Type | Value |
---|---|---|
expand | String | the name of the attribute which can be expanded on ("profileData") Please Note: Expansion on "profileData" will not provide more information. But the entities of profile elements can also be expanded. You can use dot notation ("profileData.profileElement") to achieve this. See example below. |
profileData | List | the list of profile data for each profile element
|
Example (w/o expansion)
Request:
http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin
Response:
{"expand":"profileData", "profileData":[ {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/im"}, "data":"", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/im" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159"}, "data":"<a href=\"/confluence/display/~cptkolute\" class=\"confluence-userlink\" data-username=\"cptkolute\" >Cpt. Kolute</a>", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/01050669159" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/0861244944"}, "data":"", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/0861244944" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/178640080"}, "data":"Aikido", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/178640080" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/phone"}, "data":"0123456789", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/phone" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/website"}, "data":"", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/website" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/1482416734"}, "data":"extreme programming", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/1482416734" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/department"}, "data":"CS", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/department" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/1185300867"}, "data":"blue,green", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/1185300867" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/location"}, "data":"Dresden", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/location" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/position"}, "data":"developer", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/position" }, {"profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/personalInformation"}, "data":"", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/personalInformation" }] }
Example (with expansion)
Request
localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin?expand=profileData.profileElement
Note the request query parameter ?expand=profileData.profileElement, which causes the response to contain additional information about the profile elements.
Response (excerpt):
{"expand":"profileData", "profileData":[ {"expand":"profileElement", "profileElement": {"key":"im", "nameForCurrentLocale":"IM", "defaultName":"IM", "germanName":"IM", "helpTextForCurrentLocale":"", "defaultHelpText":"", "germanHelpText":"", "profileGroup":"personal", "elementType":"TEXT_FIELD", "ldapAttributeMapping":"", "displayInCustomMode":false, "hidden":false, "personalInformationElement":false, "standard":true, "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/im" }, "data":"", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/im" }, {"expand":"profileElement", "profileElement":{"key":"01050669159", "nameForCurrentLocale":"Vorgesetzter", "defaultName":"Superior", "germanName":"Vorgesetzter", "helpTextForCurrentLocale":"Bitte hier den Vorgesetzten eingeben...", "defaultHelpText":"Enter your superior here...", "germanHelpText":"Bitte hier den Vorgesetzten eingeben...", "profileGroup":"personal", "elementType":"USER_FIELD", "ldapAttributeMapping":"%%superior%%", "displayInCustomMode":false, "hidden":false, "personalInformationElement":false, "standard":false, "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159" }, "data":"<a href=\"/confluence/display/~andreas\" class=\"confluence-userlink\" data-username=\"andreas\" >Andreas Ebert</a>", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/01050669159" }, ... ] }
Get the data for a specific user and profile element (/profileData/{user}/{elementKey})
- returns the data for the user provided by {user} and the profile element with the key {elementKey}
- the result can be expanded on "profileElement", which will cause the data structure to contain all the information available for the associated profile element (see /profileElements/{elementKey} above for details and example below)
Returned Data
The entity returned by the request has the following attributes:
Attribute | Type | Value |
---|---|---|
expand | String | the name of the attribute which can be expanded on ("profileElement") |
profileElement | Object | the profile element for which the data is returned |
data | String | the data of the profile element for the given user Please Note: The data is returned in the same way as it would be for the enhanced profile macro. I.e. the data is rendered depending on the Field Type of the element. (See example below for the data of a field of type USER_FIELD) |
self | String | the URL of the returned resource |
Example (w/o expansion)
Request:
http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/01050669159
Response:
{"expand":"profileElement", "profileElement":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159"}, "data":"<a href=\"/confluence/display/~cptkolute\" class=\"confluence-userlink\" data-username=\"cptkolute\" >Cpt. Kolute</a>", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/01050669159" }
Example (with expansion)
Request:
http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/01050669159?expand=profileElement
Note the request query parameter ?expand=profileElement, which causes the response to contain additional information about the profile element.
Response:
{"expand":"profileElement", "profileElement":{"key":"01050669159", "nameForCurrentLocale":"Vorgesetzter", "defaultName":"Superior", "germanName":"Vorgesetzter", "helpTextForCurrentLocale":"Bitte hier den Vorgesetzten eingeben...", "defaultHelpText":"Enter your superior here...", "germanHelpText":"Bitte hier den Vorgesetzten eingeben...", "profileGroup":"personal", "elementType":"USER_FIELD", "ldapAttributeMapping":"%%superior%%", "displayInCustomMode":false, "hidden":false, "personalInformationElement":false, "standard":false, "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159" }, "data":"<a href=\"/confluence/display/~andreas\" class=\"confluence-userlink\" data-username=\"andreas\" >Andreas Ebert</a>", "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileData/admin/01050669159" }
All Versions
- Release (v 3.5)
- Release (v 3.4)
- Release (v 3.3)
- Release (v 3.2)
- Release (v 3.1)
- Release (v 3.0)
- Release (v 2.1)
- Release (v 2.0)
- Release (v 1.12)
- Release (v 1.11)
- Release (v 1.10)
- Release (v 1.9)
- Release (v 1.8)
- Release (v 1.7)
- Release (v 1.6)
- Release (v 1.5)
- Release (v 1.4)
- Release (v 1.3)
- Release (v 1.2)
- Release (v 1.1)
Disable checkingPremium suggestionsDisable checkingPremium suggestions