1 Quick Start Guide
- 1.1 Set up dependencies
  - 1.1.1 Download the following files
  - 1.1.2 Add the files to your Maven repository
    - 1.1.2.1 Install in the local Maven repository
    - 1.1.2.2 Deploy to a hosted Maven repository
    - 1.1.2.3 Include the UPC Java API in your Add-On pom.xml
  - 1.1.3 Download the following files
  - 1.1.4 Add the files to your Maven repository
    - 1.1.4.1 Install in the local Maven repository
    - 1.1.4.2 Deploy to a hosted Maven repository
    - 1.1.4.3 Include the UPC Java API in your Add-On pom.xml
  - 1.1.5 Usage in our own classes (e.g. your components)
  - 1.1.6 Make sure the User Profiles for Confluence Add-on is already installed on your Confluence system.
2 Internal structure and basic usage
- 2.1 Profile element and data types
- 2.2 Event publication
  - 2.2.1 ProfileElementDataChangedEvent
  - 2.2.2 ProfileElementNameChangedEvent
  - 2.2.3 ProfileElementRemovedEvent
  - 2.2.4 ProfileElementOptionNameChangedEvent
  - 2.2.5 ProfileElementOptionRemovedEvent
- 2.3 Examples
  - 2.3.1 UppProfileElementManager
    - 2.3.1.1 Loading all profile elements
    - 2.3.1.2 Loading a specific profile element with a specific id (for example 1)
  - 2.3.2 UppProfileElementDataManager

Quick Start Guide

Set up dependencies

Download the following files

library: user-profiles-external-api-1.0.0.jar
documentation of the library (Javadoc): user-profiles-external-api-1.0.0-javadoc.jar

Add the files to your Maven repository

There are two possibilities to install the library files. Either install them in a local Maven repository or deploy them to a hosted Maven repository.

Install in the local Maven repository

mvn install:install-file -Dfile=user-profiles-external-api-1.0.0.jar -DgroupId=de.communardo.atlassian.plugins.userprofile.external.api -DartifactId=user-profiles-external-api -Dversion=1.0.0 -Dpackaging=jar -Djavadoc=user-profiles-external-api-1.0.0-javadoc.jar

Deploy to a hosted Maven repository

mvn deploy:deploy-file -Dfile=user-profiles-external-api-1.0.0.jar -DgroupId=de.communardo.atlassian.plugins.userprofile.external.api -DartifactId=user-profiles-external-api -Dversion=1.0.0 -Dpackaging=jar -Djavadoc=user-profiles-external-api-1.0.0-javadoc.jar -DrepositoryId=<id-to-map-on-server-section-of-settings.xml> -Durl=<url-of-the-repository-to-deploy>

Include the UPC Java API in your Add-On pom.xml

<dependency>
    <groupId>de.communardo.atlassian.plugins.userprofile.external.api</groupId>
    <artifactId>user-profiles-external-api</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

Download the following files

library: user-profiles-external-api-1.1.0.jar
documentation of the library (Javadoc): user-profiles-external-api-1.1.0-javadoc.jar

Add the files to your Maven repository

There are two possibilities to install the library files. Either install them in a local Maven repository or deploy them to a hosted Maven repository.

Install in the local Maven repository

Deploy to a hosted Maven repository

Include the UPC Java API in your Add-On pom.xml

Usage in our own classes (e.g. your components)

To import the services provided by our API as components, using Atlassian Spring Scanner as an example:

Make sure the User Profiles for Confluence Add-on is already installed on your Confluence system.

Check Installation and Licensing (v 3.5) for further information.

Internal structure and basic usage

The UPC Java API consists out of two basic elements: the profile element and the profile element data. Profile elements can be added and removed in the UPC administration (check Configure User Profile Elements (v 3.5) for further information). Values may afterwards be added for every user via an LDAP sync or by manually editing user profiles (in the administration or the user does it on his own) or even by using our new Java API.

To interact with profile elements, just inject and use the provided UppProfileElementManager. With this manager you will be able to load the available profile elements. Afterwards you may want to access some data which is related to a user. To achieve that, just inject and use the provided UppProfileElementDataManager.

Profile element and data types

There are several profile element and data types which are used to work with the API. To provide you a better start, we are going to list all currently available profile elements and their matching data models in the following table:

Profile Element Models (package `de.communardo.atlassian.plugins.userprofile.external.api.model.elements`)	Profile Element Data Models (package `de.communardo.atlassian.plugins.userprofile.external.api.model.data`)

Profile Element Models (package `de.communardo.atlassian.plugins.userprofile.external.api.model.elements`)	Profile Element Data Models (package `de.communardo.atlassian.plugins.userprofile.external.api.model.data`)
AutocompleteProfileElement	AutocompleteProfileElementData
MultiSelectProfileElement	MultiSelectProfileElementData
SingleSelectProfileElement	SingleSelectProfileElementData
TextBasedProfileElement	TextBasedProfileElementData
UserProfileElement	UserProfileElementData

You have to use matching profile element and data types to be able to interact with the API. Furthermore, the specialized data objects make an interaction with a specific data type more easy.

Event publication

SINCE VERSION 3.3.15

ProfileElementDataChangedEvent

User Profiles for Confluence publishes events every minute, which contain all changes that happened since the last publication. One event contains a maximum of 1000 changes as a collection of updates. Each update contains a user key, a profile element and the new data. The following table shows the models of the change sets:

Profile Element Change Set Models (package `de.communardo.atlassian.plugins.userprofile.external.api.events.changes`)	Profile Element Models (package `de.communardo.atlassian.plugins.userprofile.external.api.model.elements`)	Data Models

Profile Element Change Set Models (package `de.communardo.atlassian.plugins.userprofile.external.api.events.changes`)	Profile Element Models (package `de.communardo.atlassian.plugins.userprofile.external.api.model.elements`)	Data Models
AutocompleteProfileElementDataUpdate	AutocompleteProfileElement	Set<String>
MultiSelectProfileElementDataUpdate	MultiSelectProfileElement	Set<OptionedProfileElement.Option>
SingleSelectProfileElementDataUpdate	SingleSelectProfileElement	OptionedProfileElement.Option
TextBasedProfileElementDataUpdate	TextBasedProfileElement	String
UserProfileElementDataUpdate	UserProfileElement	UserKey

ProfileElementNameChangedEvent

This event is published when the default name of a profile element is changed. It contains the updated profile element.

ProfileElementRemovedEvent

This event is published when a profile element is removed. It contains the removed profile element.

ProfileElementOptionNameChangedEvent

This event is published when the default name of an option of a profile element is changed. It contains the updated profile element and the updated option.

ProfileElementOptionRemovedEvent

This event is published when an option of a profile element is removed. It contains the updated profile element and the removed option.

Examples

To kickstart you a little bit more, we want to provide you with a few examples on what you can currently do with our Java API:

UppProfileElementManager

Loading all profile elements

Loading a specific profile element with a specific id (for example 1)

UppProfileElementDataManager

Loading profile element data for a profile element and a user

Loading all profile elements for a user

Storing profile element data for a profile element and a user

To be able to store data, the type of the profile Element must match the type of the data.