Content

Installation

Installing the Add-on

The add-on is available at the Atlassian Marketplace. To install the add-on, log in as a system administrator and navigate to the add-on management in the administration console (choose Cog icon > Add-ons at the top right of the screen, or for older systems Browse > Confluence Admin > Plugins). In the menu on the left click the “Find New Add-ons” link (in older systems enter the Plugins section and navigate to the “Install”-Tab). Search for “user profiles for confluence” to display our add-on “User Profiles for Confluence”. Click the Buy Now or Free Trial button to install the add-on.

If the installation was successful, a new section should appear on the left-hand panel in the administration console: “User Profiles for Confluence”. This is where the customization of the user profiles takes place. If this section is not visible, please ensure that all required modules of the add-on are enabled. For that purpose, select the “User Profiles for Confluence” from the list of installed add-ons. Of the listed modules, only the modules named “profile” are not required for the add-on to work. All the other modules should be enabled.

Enabling the Profile Macro

 


To benefit from all features of User Profiles for Confluence the appropriate macro has to be enabled.


 

Background-Knowledge: The profile macro (which is a part of the bundled add-on “Profile Macros”) is required to display user data in the people directory, the hover for users and in the personal space. User Profiles for Confluence provides its own version of this macro. This version behaves like the one from “Profile Macros”, but displays additionally created user profile elements too. To benefit from all features of User Profiles for Confluence the appropriate macro has to be enabled.

Enable the “profile” macro module of “User Profiles for Confluence”

Switch to the Confluence administration, via Cog icon or for older systems Browse > Confluence Admin.

  1. Go to the section User Profile Settings > click Advanced.
  2. Go the section Enable Enhanced Profile Macro.
  3. Check the checkbox "Enable enhanced profile macro" and save.

Licensing

The add-on needs a valid license to have all the provided features working. Valid licenses are either full licenses, renewal licenses, or 30-day trials and are available on the Atlassian Marketplace. The license model is the same model that Atlassian uses for its products – for further information see Atlassians docmentation.

To get a license and provide it for the add-on, please carry out the following instructions, (also see the screenshot below):

  • Go to the license settings page (Administration Console > Add-ons > Atlassian Makretplace: “Manage add-ons”)
  • Use the links to create a new license at the Atlassian Marketplace (use “Free trial” to get a new trial license or “Buy now” to purchase a full license), or copy a license you got from Communardo.
  • Enter the license key in the license screen

 

Workaround (if one of the steps above does not work or is not available – this may happen with older Confluence versions)

  • Create licenses with the links that are available in the Atlassian Marketplace
  • Enter the license in the configuration screen of the add-on into the section “License Administration”. The configuration screen is available via the link User Profiles for Confluence > License in the panel on the left side of the administration console (choose Cog icon > Confluence Admin at the top right of the screen or for older systems Browse > Confluence Admin).
Without a valid license, the user profiles shows the message “Plugin is not licensed” instead of the user profile data.

 

Configuration

Several configurations can be made that are listed below ...

User Profile Elements

Configuration Overview

You can access the configuration via the menu item User Profiles for Confluence > Profile Elements in the panel on the left side of the administration console (choose Cog icon > General configuration at the top right of the screen).

The configuration page allows you to add new elements for user profiles or to edit existing elements. This includes standard elements of the user profiles.

The standard elements “Full Name” and “Email” cannot be manipulated in order to protect important system functionalities, therefore they are not available in the configuration.

Additional elements are placed in alphabetical order into the sections “Personal” and “Company”. If the order of the profile elements has been changed once, all new elements will be placed at the end of the list.

You can change the order of the fields by clicking the arrows (↑ ↓). With one click you move the profile element one position up or down.

The section “Special Elements” contains the “About Me“ and you can configure the synchronization of user pictures in this section (Please find a more detailed description further down in the documentation.).

Please note:

  • You cannot change the order of the items of “Special Elements”, because “About Me“ is never displayed as part of the profile card and the profile picture has a fixed position within the profile.
  • The configuration here will be used for all user profiles in the system.

Configuration of Elements – Add and Edit

Click on the “Edit” or “Add Element” button to edit an existing item, or insert a new one.

The configuration page of an element allows you to create/edit an element of the user profile.


Title for this Element

  • A default title (“Title (Default)” and “Title (German)”) for the element can be defined. The information for “Title (Default)” is mandatory. The Default and German Title can only be edited for additional profile elements and not for standard elements.

Help Text for this Element

  •  Additionally, you can define help texts to support the users in filling out the element in their user profile.

Field Type Configuration

  • The “Field Type” of the element determines the kind of element:
    • Textfield: A simple text field
    • Textarea: This is convenient for elements which might carry longer texts (like the “About Me” element) since it renders wiki markup too.
    • Userfield: Carry a single username and supports auto complete while editing a user profile. On the rendered page, you have the typical mouseover popup for this user profile.
    • Textfield with Autocomplete: A text field to type in any text you want. Additionally, while editing it, the system will suggest values that other users have entered in this field before. User Profiles for Confluence suggests values that start with the same letter(s) that you already entered. Auto-completion is also available for several values, if they are separated by commas.
    • Single Select (Radiobuttons): Allows the configuration of pre-defined options. The user can select their profile information from one of these options.
    • Multiple Select (Checkboxes): Allows the configuration of pre-defined options. The user can select their profile information from more than one of these options.
  • Special feature for “User Field”. If this field type is selected, an additional check box “The field value is a DN reference to the user” appears. You can enable this check box to define that the user name in the user directory is a distinguished name.
  • For the synchronization to work, you have to provide a mapping of LDAP attributes to standard or additional user profile elements. It is possible to relate more than one LDAP attribute to one user profile element. The mapping has to be provided at “Mapping for LDAP Attribute(s)” by using the following syntax:
    • Any LDAP attribute has to be given as %%LDAP_ATTRIBUTE%% (i.e. name of an LDAP attribute enclosed in two percent signs (%%)).
    • Multiple LDAP attributes with the same name are supported. If there are such attributes they will be mapped to the same profile field, separated by comma.
    • You can also specify static text (e.g. %%street%% %%number%% in %%city%%)
    • Use %%upp_delete_value%% as a placeholder to delete the data for previously synchronized profile element.

Visibility

  • The check box “Display in People Directory and Custom Mode” defines, if the element will be shown in user profiles, hover cards or profile lists displayed with the display mode ‘custom’
    • It only works, if you have enabled the profile macros, as described in “Exchanging Profile Macros”.
    • It is not possible for the “About Me” field.

Configuration of Elements – Hide and Delete

Click on the “Hide” (default elements) or “Delete” (additional elements) button to hide an item, or delete it.


Existing additional profile elements can be deleted via the button “Delete”. Standard Elements can only be hidden via  “Hide”.

  • The data for hidden elements stays stored as long as the element is hidden and is displayed again after clicking “Show”.
  • When a previously added profile element is deleted, all the data belonging to this element is purged as well, for all users.
  • Hiding standard profile elements only works, if the profile macro has been exchanged.

 

  • Users cannot edit synchronized profile elements. An element is considered “synchronized”, if the field “Mapping for LDAP Attribute(s)” in the customization form is not empty, even if the value of the mapped LDAP attribute is empty. This restriction only applies to users who are synchronized via LDAP. Local users can edit each profile element.
  • Unknown LDAP attributes are recognized during synchronization and will be ignored. They are listed after each manual synchronization and produce a warning in the logs.
    For the data of the user profiles to be updated, a synchronization has to run first. See the next section for instructions.
  • Though supported, it’s recommended not to create more than 15 to 20 additional user profile elements.
  • Fields of the type “Textfield with Autocomplete”, “Single Select” and “Multiple Select” will not be synchronized.
  • While editing a profile element, only some of the field types can be selected. For fields of some types it is not possible to change the type at all. This is because data stored for fields of a specific type cannot be migrated automatically to data for fields of every other type. E.g. data stored for fields of type “Multiple Select” is completely different from data stored for any other field and therefore, the type of these elements cannot be changed. The following modifications are possible:
    • Textfield ↔ Textarea ↔ Textfield with Autocomplete
    • Userfield (no change possible) 
    • Checkbox (no change possible)
    • Radiobutton (no change possible)

 

(lightbulb) Demo of user profile configuration (If you cannot see the embedded video below, please check whether you have agreed to the privacy policy of this website or if your browser blocks unsafe content.)

 

 

Synchronize User Profile Pictures

The synchronization of user pictures from a central storage is supported (since version 1.10). You can find the configuration under “Special Elements” in the settings of User Profiles for Confluence (Administration Console > User Profiles for Confluence > Profile Elements).

 

  

To synchronize user pictures from a central user directory, you have to enter the attribute name where the picture is stored. The name of the attribute is typically “thumbnailPhoto” for Active Directory and “jpegPhoto” for OpenLDAP. You may set multiple attributes separated by a comma, i.e. “thumbnailPhoto,jpegPhoto”. This is useful, if you have configured multiple directories of different types.

The synchronization is based on the following features

  • While the synchronization process is running a picture of a user is read out, cropped to a square format and, if necessary, scaled down.
  • Pictures are stored in size 96 x 96, if the original has a sufficient resolution. Otherwise the picture is stored in 48 x 48.
  • If a picture is updated in the picture storage, the user picture will be overwritten in Confluence during the next synchronization.
  • Users can upload their own pictures in Confluence, but after the next synchronization the picture from the picture storage is displayed again.
    • (info) If there is no picture defined for the user in the external storage, the user's uploaded image will be preserved beyond the synchronization task.

Stop Synchronization of User Pictures

Leave the field “Attribute Name” blank, if no synchronization is required or if you want to stop the synchronization.

 

On systems with many users (1000+), the first synchronization may take very long (several hours) and can impact your system's performance. To improve the process or in case of synchronization errors, it is recommended to enable “Login Synchronization” for a couple of days.  

 

Synchronization

There are three different ways to synchronize: Periodically or manually for all users (full synchronization), or at login for a single user. During this process, the data of a users profile elements is updated with the values from the configured LDAP repositories according to the mapping that was defined during configuration of the profile fields.

The synchronization is only working in one direction. Data will only be pulled from a repository and will never be written back. This also applies to repositories which are configured as “Read/Write”.

The synchronization is currently not working for directories of type “Apache Directory Server (ApacheDS)”. Synchroniziation is also not working for delegated directories.

Manual Synchronization

The manual synchronization can be started from the advanced configuration setting (Administration Console > User Profiles for Confluence > Advanced). There is a button “Start Synchronization” below in the synchronization settings. After clicking it, a full synchronization will happen. This means that every user profile will be synchronized according to your configuration. After the synchronization, a short summary will be shown.

Since a full synchronization is a resource-consuming task, it should not be started during business hours!

Periodical Synchronization

A full synchronization will be executed periodically. The add-on is configured to start this synchronization by default at 1:11 a.m. each night.

You can customize or disable periodical synchronization via “Scheduled Jobs” in the administration. Look for the entry “External User Directory Sync Job” to configure the job that schedules periodical synchronizations.

Single-User Synchronization

Whenever a user logs in, their profile data is synchronized with the user repository. Since Version 1.10 this setting is disabled by default, because it can have an impact on the login performance.

You can enable this synchronization type, if you select the checkbox “Enable Login Synchronization” from the advanced configuration settings (Administration Console > User Profiles for Confluence > Advanced).

Note: The synchronization will only run for that single user.

(lightbulb) Demo of synchronization (If you can not see embedded video below, please check whether you have agreed to the privacy policy of this website or if your browser blocks unsafe content.)

 

Organization Charts

Starting from a particular user, the hierarchical relationships with superiors, colleagues and employees are visualized. The organizational charts contain the full name of the person displayed with a link to the profile, the user picture, as well as the department and the position.

The organizational charts are calculated based on the data the user enters in their profile. One field has to be selected which defines the hierarchy (see the orange mark in the screenshot below).

Only elements of type “Userfield” are available for selection. All the information about superiors, colleagues and employees is automatically calculated based on that field.

Additionally the behavior of the organization charts that are embedded on the user profile page can be configured as pictured in the screenshot below. The Organization Chart Configuration can be entered by going to the administration console (choose Cog icon > Confluence Admin at the top right of the screen or for older systems Browse > Confluence Admin) and click Organization Charts in the section User Profiles for Confluence in the panel on the left side.

Secondary Manager

If your organization is structured in such a way that employees can have two managers, you can set a secondary manager for your Organization Chart (compact), starting with version 1.12.

Prerequisites: 

  • At least two User Profile fields of the type "Userfield" need to be configured.
  • The Level of Parents is set to at least "1".

Steps to show an additional manager:

  1. Go to the Organization Chart Configuration (choose Cog icon > Confluence Admin at the top right of the screen or for older systems Browse > Confluence Admin) and click Organization Charts in the section User Profiles for Confluence in the panel on the left side.
  2. Scroll down to the section Secondary Manager Configuration and tick the checkbox Display Secondary Manager.
  3. Choose a user field from the drop-down list Secondary Manager.
    1. Make sure it is not the same field you have selected as your Manager field at the top of the page.
  4. Save your settings.

If the field you configured in 2. is filled, the Organization Chart (compact) will display a secondary manager after the Org Chart Cache Updater job has run.

Please note that this option controls the appearance of the Organization Chart only on the User Profile Page and in the sidebar of the users Personal Space.

 

Some notes about the behavior for the “Organization Chart (compact)” macro

Displayed hierarchy is outdated

Organization charts are stored in a cache, which is refreshed periodically (if needed). This means that the organization charts displayed by the macro will not be up to date until the cache is refreshed. The default refresh period is 30 minutes. Depending on how many users are in your instance, the refresh itself may take from some milliseconds for less then 100 users up to several minutes for 10k users or more. So users might notice outdated hierarchies.

The following scenarios might occur:

  • The cache will be flushed and until it is refreshed, the macro will display a hint that the hierarchy is being calculated if,
    • the user profile field which defines the hierarchy was removed by an administrator
    • the user profile field which defines the hierarchy has been changed by an administrator
  • All users will see an outdated hierarchy until the cache is refreshed, if
    • a user has changed his parent (superior)
    • an administrator has changed the parent (superior) of a user
    • during synchronization with LDAP the parent (superior) is changed for a user

Refresh the hierarchy manually

The cache is refreshed based on a scheduled job. If you need to force a cache refresh, you can run the job manually. For more details on where to find the scheduled jobs and how to run them manually, please refer to the documentation provided by Atlassian. The job is called “Org Chart Cache Updater”.

Macro renders an error

As long as the profile element, which defines the hierarchy, is not configured, the macro will render an error.

Export of User Data

The add-on allows you to export all user profile data. You can find the following option at the link User Profiles for Confluence > Export at the administration console (choose Cog icon > Confluence Admin at the top right of the screen or for older systems Browse > Confluence Admin).

Via Export Configuration, you can define criterias with Lucene search syntax to filter the users that will be exported. Leave the filter field empty to export all users.

If you click “Generate export now”, a new export is created with the current export filter, which can be downloaded. Please be aware that generating a new profile export may take some time.

“Download Last Export” allows the last written export CSV file to be downloaded and stored on your local computer.

A CSV export file is automatically generated after the periodical user synchronization job has finished using the defined export filter!

Configuration of Active User Policy

The add-on allows you to configure which users are considered “active” users. Only active users are synchronized, exported and considered for organization charts. This is useful if your user repository has users that are not real users – like rooms or computers. You can choose between two policies:

  • All users that are present in the system. That is, all users who are synchronized from the configured “User Directories”, even if they are not yet visible everywhere (e.g. the people directory). These are all the users who are displayed to you after
    • navigating to “Manage Users” in the global administration and
    • clicking “Show all users”
    Users from LDAP directories who are not yet visible will be “activated” during synchronization. This means that afterwards they are present in the people directory and can be found when searching.
  • Visible Users: Only users currently visible, e.g. in the people directory and via search.

This configuration is available by clicking the “Advanced” link in the “User Profiles for Confluence” section and the first section on this screen “Active User Policy” contains the configuration.

General Hints

  • The add-on does not work correctly with user names that are longer than 50 characters.

Uninstall Process

  • Uninstall User Profiles for Confluence via Global Administration > Add-onsh1.

Known Issues