Developer's Guide (v 1.2)

Owned by Almuth Boehme [Communardo]
Last updated: Mar 20, 2023 by 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:

AttributeTypeValue
expandStringthe name of the attribute which can be expanded on ("profileElements")
profileElementsList

the list of profile elements

  • each element is represented by the URL to the resource of the element
    • see /profileElements/{elementKey} below for details
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}

Returned Data

The entity returned by the request has the following attributes:

AttributeTypeValue

key

Stringthe key of the profile element
nameForCurrentLocaleStringthe title of the profile element with the translation for the currently authenticated user (default or German)
defaultNameStringthe Default Title of the profile element
germanNameStringthe German Title of the profile element
helpTextForCurrentLocaleStringthe help text of the profile element with the translation for the currently authenticated user (default or German)
defaultHelpTextStringthe Default Help Text of the profile element
germanHelpTextStringthe German Help Text of the profile element
profileGroupStringthe profile group which this element belongs to (either "personal" or "business")
elementTypeString

the Field Type of the profile element, one of:

  • TEXT_FIELD (for elements of type "Textfield")
  • TEXT_AREA (for elements of type "Textarea")
  • USER_FIELD (for elements of type "Userfield")
  • AUTOCOMPLETE_TEXTFIELD (for elements of type "Textfield with Autocomplete")
  • SELECT_SINGLE (for elements of type "Single Select (Radiobuttons)")
  • SELECT_MULTIPLE (for elements of type "Multiple Select (Checkboxes)")
ldapAttributeMappingStringThe value for the configured LDAP attribute mapping
displayInCustomModeBooleanwhether or not this element is displayed using the mode "custom" of the enhanced profile macro
hiddenBooleanwhether this element is hidden (always false for additional profile elements, as those can currently not be hidden)
personalInformationElementBooleanwhether this element is the element containing the "About Me" information of the standard Confluence profile
standardBooleanwhether this element is a standard (true) or additional (false) profile element
selfStringthe 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:

AttributeTypeValue
expandString

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.

profileDataList

the list of profile data for each profile element

  • each profile data item on the list has the same attributes as the data structures for the individual resources
    • see /profileData/{user}/{elementKey} below for details
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

(warning)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:

AttributeTypeValue
expandStringthe name of the attribute which can be expanded on ("profileElement")

profileElement

Objectthe 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)

selfStringthe 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

(warning)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

Disable checkingPremium suggestionsDisable checkingPremium suggestions