Quick Start Guide

Download the following files

• user-profiles-external-api-1.0.0.jar

• Documentation: 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 UPJ 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>

Import UPJ components to your atlassian-plugin.xml

<component-import key="uppProfileElementManager" interface="de.communardo.atlassian.plugins.userprofile.external.api.service.UppProfileElementManager" />
<component-import key="uppProfileElementDataManager" interface="de.communardo.atlassian.plugins.userprofile.external.api.service.UppProfileElementDataManager" />

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

Check https://communardo.atlassian.net/wiki/spaces/UPJ/pages/473727121/Installation+and+Licensing+v+2.2 for further information.

Internal structure and basic usage

The UPJ 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 UPJ administration (check https://communardo.atlassian.net/wiki/spaces/UPJ/pages/473727136/Create+and+Edit+User+Profile+Elements+v+2.2 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:

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.

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

Collection<ProfileElement> profileElements =  uppProfileElementManager.getProfileElements();

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

ProfileElement profileElement = uppProfileElementManager.getProfileElement(1);
//or if you know the type of the profileElement (in this example it is a TextBasedProfileElement)
TextBasedProfileElement textbasedProfileElement = uppProfileElementManager.getProfileElement(1);

UppProfileElementDataManager

Loading profile element data for a profile element and an user

ProfileElementData data = uppProfileElementDataManager.getProfileElementData(userKey, profileElement);
//or if you know the type of the profileElement or the data (in this example it is a TextBasedProfileElementData)
TextBasedProfileElementData data = uppProfileElementDataManager.getProfileElementData(userKey, profileElement);

Loading all profile elements for an user

Map<ProfileElement, ProfileElementData> data = uppProfileElementDataManager.getProfileElementData(userKey);

Storing profile element data for a profile element and an user

uppProfileElementDataManager.storeProfileElementData(userKey, profileElement, data);

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