User Profiles for Confluence 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:
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
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:
Authorization
header containing "Basic username:password
", with "username:password" being Base64 encodedos_authType=basic
to the URL (e.g. http://localhost:8080/rest/communardo/upp/latest/some/resource?os_authType=basic)Currently responses by the API contain all data in JSON format only. There are no other formats supported.
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.
The following sections describe the resources that are available via the API.
There are two resources which provide information about the profile element configuration.
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
|
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"}] } |
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 ("options") | |
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 "prioritized" 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 | |
options | Object |
list of the options of the profile element
| |
self | String | the URL of the returned resource |
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, "options":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159/options"} "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159" } |
{"key":"01050669159", "nameForCurrentLocale":"Abteilung", "defaultName":"department", "germanName":"Abteilung", "helpTextForCurrentLocale":"Bitte hier die Abteilung auswählen.", "defaultHelpText":"Select your department here.", "germanHelpText":"Bitte hier die Abteilung auswählen.", "profileGroup":"business", "elementType":"SELECT_SINGLE", "ldapAttributeMapping":"", "displayInCustomMode":true, "hidden":false, "personalInformationElement":false, "standard":false, "options":{"self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159/options"} "self":"http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159" } |
The data structure returned by the request has the following attributes:
Attribute | Type | Value |
---|---|---|
options | List | the list of options as object |
self | String | the URL of the returned resource |
The data structure of an option:
Attribute | Type | Value |
---|---|---|
id | String | the id of the option |
nameForCurrentLocale | String | the name for the current locale |
defaultName | String | the default name of the option |
germanName | String | the gernam name of the option |
Request:
http://localhost:8080/confluence/rest/communardo/upp/1.0/profileElements/01050669159/options |
Response:
{"self":"http://localhost:8090/rest/communardo/upp/1.0/profileElements/01050669159/options", "options":[ {"id":"1", "nameForCurrentLocale":"Marketing", "defaultName":"Marketing", "germanName":"Marketing" }, {"id":"2", "nameForCurrentLocale":"Sales department", "defaultName":"Sales department", "germanName":"" } ] } |
There are two resources provided to access profile data for individual users.
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
|
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" }] } |
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" }, ... ] } |
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 |
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" } |
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" } |
Disable checkingPremium suggestions