Administrator's Guide (v 1.9)

Owned by Former user (Deleted)
Last updated: Aug 17, 2016 by Almuth Boehme [Communardo]
11 min read

Content

Compatibility

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Overview'.

Installation

1. Installing the Plugin

The plugin is available at the Atlassian Marketplace. To install the plugin, log in as system administrator and navigate to the global administration (cog icon  or Browse > Confluence Admin). Enter the Plugins section and navigate to the "Install"-Tab". Search for "User Profile Plugin" and press "Install".

If the installation was successful, a new item should appear on the left-hand panel in the "Administration" section: "User Profile Configuration". This is where the customization of the user profiles takes place. If this link is not visible, please ensure that all required modules of the plugin are enabled. You can do this by clicking "Plugins" in the global administration and selecting the "User Profile Plugin". Of the listed, modules only the modules named "profile" are not required for the plugin to work. Each other module should be enabled.

Version 1.9 Upgrade

When upgrading to version 1.9, all profile data will be migrated to a new storage format. This is necessary because Confluence 5.3 allows changing usernames.

This process may take several minutes, depending on the number of users and additional profile fields. The detailed progress is logged into the Confluence log file (<confluence-home>/logs/atlassian-confluence.log) If any user edits its user data during the migration, the new values may get lost and be replaced by the previous value. So please upgrade the plugin after notifying your users.

 

2. Exchanging Profile Macros

Background-Knowledge: The profile-Macro (which is a part of the bundled plugin "Profile Macros") is required to display user data at the people directory, the hover for users and at the personal space. The User Profile Plugin provides its own version of this macro. This version behaves like the one from "Profile Macros", but displays additional created user profile elements too. To benefit from all features of the User Profile Plugin the macros should be exchanged.

 

Please note

It is important, that you keep the order of the steps, meaning first disable the standard profile macro and afterwards enable the User Profile macros!

 

Disable the "profile" macro module of the "Profile Macros" Plugin

  • Open the old plugin administration view via http://<server base url>/admin/viewplugins.action
  • Select the "Profile Macros" plugin and disable the "profile" macro module

Enable the "profile" macro module of the "User Profile" plugin

  • Switch to the default plugin administration, via "Global Administration" -> "Plugins"
    • Select the "User Profile Plugin"
    • Activate both macros withthe name "profile" (click "Enable" on the modules "profile")

Licensing

The plugin 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 at the Atlassian Marketplace. The license model is the same as Atlassian uses for its products - for further information see Atlassians docmentation.

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

  • Go to the license settings page (Global Administration > Plugins > Tab "Manage my plugins" or simular tab > Extend the "User Profile Plugin")
  • Use the links to create a new license at the Atlassian Marketplace (use "try" to get a new trial license or "buy" 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 plugin into the section "License Administration". The configuration screen is available via the menu item "User Profile Configuration" in the panel on the left side of the administration section (cog icon  or 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 Profile Configuration" in the panel on the left side of the administration section (cog icon or Browse > Confluence Admin).

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 at the end of the sections Personal and Company. 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 order of the About Me field cannot be changed since it is never displayed as part of the profile card.
This configuration will be used for all user profiles in the system.

Configuration of Elements

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

  • A default title (in English) and a German titlefor the element can be defined. The information for "Default Title" is mandatory. Additionally, you can to define help texts to support the users in filling this element in their user profile.
    • The Default and German Title can only be edited for additional profile elements and not for standard elements.
  • 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 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: Here you can type in any text you want. Additionally while you edit this, the system suggests values that other users entered in this field before. The User Profile Plugin suggests values that start with the same letter(s) that you already entered. This auto completion is also available for several values if they are separated by commas.
    • Single Select (Radiobuttons): Allows the configuration of predefined options. The user can select their profile information from one of these options.
    • Multiple Select (Checkboxes): Allows the configuration of predefined options. The user can select their profile information from more than one of these options.
  • 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 %%).
    • You can also specify static text (e.g. %%street%% %%number%% in %%city%%)
    • Use %%upp_delete_value%% as a placeholder to delete the data for a synchronized profile element.
  • The check box "Display in custom mode" defines if the element will be shown in user profiles or profile lists displayed with Style: custom
    • This only works if #2. Exchanging Profile Macros.
    • This is not possible for the About Me field
  • Existing additional profile elements can be deleted via check box "Delete Element". Standard Elements can only be hidden via check box "Hide Element".
    • The data for hidden elements stays stored as long as the check box "Hide Element" is active and is displayed again after unchecking.
    • When a previously added profile element is deleted, all the data belonging to this element is purged as well for each user.
    • Hiding standard profile elements only works if the profile-Macro had been exchanged.

Additional Notes

  • 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 on how this can be achieved.
  • 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 can't be migrated automatically into data for fields of every other type. E.g. data stored for fields of type "Multiple Select" is totally different from data stored for all other fields and so the type of such elements can't be changed.

(lightbulb) Demo of user profile configuration

Synchronization

There are 3 ways a synchronization can happen: Periodical or manual 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.

Please Note

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)".

Manual Synchonization

The manual synchronization can be started from the configuration menu. There is a button "Start synchronization" below the profile elements list. After clicking it, a full synchronization will happen. This means that the profile for every user 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 hour!

Periodical Synchronization

A full synchronization will be executed periodically. The plugin 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, his profile data is synchronized with the user repository. Note that the synchronization will only run for that single user.

(lightbulb) Demo of synchronization:

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 enter in their profile. One field has to be selected which defines the hierarchy (see the orange marking the screen shot below).

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

Additionally the the behaviour of the organization charts that are embedded on the user profile page and in the sidebar of the users personal space can be configured as pictured in the screen shot below. Go to the "User Profile Configuration" in the panel on the left side of the administration section (cog icon  or Browse > Confluence Admin). The Organization Chart Configuration can be entered by clicking the button "Configure Organization Charts" below the profile elements list.

If you are using Organization Charts with an external user directory, you have to get sure that the synchronized field only contains the username as plain text.  Using distinguished fields (e.g. manager) will not work.

 

Some notes about the behavior for the "Org Chart" 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 as long as it is not 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 as long as the cache is not refreshed, if
    • a user changed his parent (superior).
    • an administrator changed the parent (superior) of an user.
    • during synchronization with LDAP the parent (superior) is changed for a user.

The refresh of the cache is managed by 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 plugin allows you to export all user profile data. You can find the following option at the bottom of the "User Profile Configuration" page at the administration (cog icon  or Browse > Confluence Admin) .

Via the "Configure export" button, you can define criteria 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", you create a new export with the current export filter, which can be downloaded. But be aware, 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.

Please note

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 plugin allows you to configure which user is considered as being an "active" user. 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 usersthat are present in the system. That is, all users which are synchronized from the configured "User Directories", even if they are not yet visible everywhere (e.g. the people directory). This are all the users which are displayed to you after
    • navigating to "Manage Users" in the global administration and
    • clicking "Show all users"

    Please note

    Users from LDAP directories, which 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 button "Configure User Policy" below the profile elements list of the "User Profile Configuration" page at the administration (cog icon  or Browse > Confluence Admin) .

General Hints

  • the plugin does not work correctly with user names that are longer than 50 characters

Uninstall Process

  • Uninstall the User Profile Plugin via "Global Administration" -> "Plugins"

  • Enable the “profile” Macro Module of the “Profile Macros” Plugin :

    • Open the old plugin administration view via http://<server base url>/admin/viewplugins.action

    • Select the "Profile Macros" plugin and enable Profile Macros

 

for the profile-Macro if it had been exchanged

All Versions