Administrator's Guide (v 1.6)

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

Content

Compatibility

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

Installation Process

1. Installing the Plugin

The plugin is available at the Atlassian Plugin Repository. To install the plugin, log in as system administrator and navigate to the global administration (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.

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.

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

Uninstall Process

1. Uninstall User Profile Plugin

  • via "Global Administration" -> "Plugins"

2. 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

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 atthe 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 (Browse > Confluence Admin).

Without a valid license, the user profiles shows the message "Plugin is not licensed" instead of the user profile data.

Configuration of user profile elements

You can access the configuration via the menu item "User Profile Configuration" in the panel on the left side of the administration section (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. Additional elements are placed at the end of the sections Personal and Company.
This configuration will be used for all user profiles in the system.

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

  • A default title (in English) and a German title for 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:
    • Text field: A simple text field
    • Text area: This is convenient for elements which might carry longer texts (like the "About Me" element) since it renders wiki markup too.
    • User field: 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 %%delete_value%% as a placeholder to delete the data for a synchronized profile element.
  • The check box "Display in custom mode of {profile} macro" defines if the element will be shown in user profiles displayed by
    {profile:style=custom}
    • This only works if the profile-Macro had been exchanged, see above
  • Existing profile elements can be deleted (available for additional added user profile elements via check box "Delete Element") or hidden (available for standard elements 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 it is unchecked.
    • 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, see above

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.
  • For selected field types it is possible to change the type after the field as been initially created. This is necessary to avoid problems during the migration of the field types (like the migration of "Multiple Select" to "Text field")

(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 LDAP repository according to the mapping that was defined during configuration.

Manual Synchronization

The manual synchronization can be called from the configuration menu (there is a link at the bottom of the page). After clicking this link, 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.

As 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 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 into their profile, data is synchronized with the user repository. Note that the synchronization will only run for that single user.

(lightbulb) Demo of synchronization:

 

Export of User Data

The plugin allows you to export all user profile data. A CSV export file is automatically generated after the periodical user synchronization job has finished, or after a manual request for a new export. Generating a new profile export may take some time. The export contains all users matching the export filter that is defined with Lucene search syntax. The CSV files can be downloaded and stored on your local computer.

These features are available via links in the configuration screen in the section "Export of user data". The configuration screen is available via the menu item "User Profile Configuration" in the panel on the left side of the administration section (Browse > Confluence Admin).

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 and exported. 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 (Default): All users that are present in the system. That is, all users which exist in one of the configured "User Directories", even if they are not yet visible everywhere (e.g. the people directory). Please note, that users from an LDAP source, 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 by searching.
  • Visible Users: Only users currently visible, e.g. in the people directory and via search.

This configuration is available via a link in the configuration screen (find the screen via the menu item "User Profile Configuration" in the panel on the left side of the administration section (Browse > Confluence Admin))

General Hints

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

All Versions