- Created by Seibert Media employee, last modified by Administrator on Jun 05, 2024
Documentation's navigation
On this page
How does XML work for Linchpin User Profiles?
By default, user directories configured in Confluence are used to fill the user profiles.
But you can also let Linchpin User Profiles (LUP) use an XML file to obtain user profile data.
Configure the XML import
Navigate to Confluence administration → Linchpin User Profiles → Data sources → XML.
Location of the xml file
Select the option you wish to use. You can either select a web server as a location of your XML file, or a specific file directory on your Confluence server.
Web Server
In the input field, enter the web address of the server which contains the XML file. Please enter the full URL. Also, please use HTTP, not HTTPS.
File directory
Enter the complete directory path to the XML file on your Confluence server.
Make sure the file has the UTF-8 preamble to get special characters encoded correctly. Also, the server should provide UTF-8 files.
User tag
Enter the XML node which contains the profile data.
For example: identity
(see our exemplary XML file below).
Username tag
Enter the XML node which contains the Confluence username.
For example: mx_user_name
(see our exemplary XML file below)
Please note that every user (or rather username) has to be unique in your file. If usernames occur several times the import will break.
Exemplary XML file
The XML file needs to comply with the following format.
<?xml version="1.0" encoding="utf-8"?> <identities> <identity> <mx_user_name>admin</mx_user_name> <department>IT</department> <team>BOFH</team> </identity> <identity> <mx_user_name>j.bond</mx_user_name> <department>MI6</department> </identity> <identity> <mx_user_name>a.schwarzenegger</mx_user_name> <department></department> <team>Expendables</team> </identity> </identities>
Please notice that in this example:
<identity>
is the user tag;<mx_user_name>
is the username tag;<team>
and<department>
are the XML node names.
Explanation
This example resolves around two profile fields - department
and team
.
When the scheduled job for XML import runs, the three users defined in the XML file (admin, j.bond, a.schwarzenegger) will be updated.
admin
Both the department
and team
fields have been set by the XML file. The user admin can not edit those fields by themselves anymore.
j.bond
Only the department
field has been set by the XML file. The user j.bond can not edit the department
field by themselves. They can edit the field team
.
a.schwarzenegger
Both the department
and team
fields have been set by the XML file. Even though the department
field is empty, as long as it's mentioned, it's set. The user a.schwarzenegger can not edit those fields by themselves anymore.
How to import multiple values into multiselect fields
Until Linchpin User Profiles 2.25, we didn't support multiple occurrences of tags (like <team>
or <department>
in the example above) per user.
However, there exists a workaround if you want to import multiple field values into a multi-select field. Instead of having multiple tags, use a single tag per user that contains a JSON array string.
<identity> <mx_user_name>m.ultiple</mx_user_name> <team>["First team","Second team","Another team"]</team> </identity>
That way, the values will be correctly imported.
From Linchpin User Profiles 2.26, we support multiple occurrences of tags (like <team>
or <department>
in the example above) per user.
<identity> <mx_user_name>m.ultiple</mx_user_name> <team>First team</team> <team>Second team</team> <team>Another team</team> </identity>
When importing multiple values into profile fields not supporting multiple values, they are written comma-separated ("First team, Second team, Another team").
How to use line breaks in the Multiline text field
As the name suggests, the Multiline text
field type offers the ability to store multiple lines of text in a profile field. If you wish to use this profile field via XML, here's what you need to consider:
- Use line breaks via
<br>
- Use CDATA
<name><![CDATA[John<br>Example]]></name>
How to use XML as a source for profile fields
Since Linchpin User Profiles 1.17 you can use XML as a source for almost all field types.
Please note that the field types 'Cascade select', 'Retrieved from LDAP' & 'Dependent field' do not work with XML.
Configuration
To use XML as a source, head over to the profile editor. Navigate to Confluence administration → Linchpin User Profiles → Profile Editor.
Enter the edit mode of any profile field you wish to edit. Scroll down to the Source section. In the Source field, select XML file. Then enter the XML node name (like team or department in the example above).
XML syncs and Linchpin User Profiles functions are both case sensitive! Please make sure that the username which is synced via XML corresponds to the case style your colleagues use within their profile field configuration.
An XML sync will import the AD's (or other source's) values as they are - which means that should these values not be identical, a function might not work as intended.
Example
: Let's take a look at Org Charts. If the supervisor is called Dirk Example, and the users enter Dirk.Example
as their supervisor's username, the user needs to be called Dirk.Example
(with large initial letters) within your XML source, too. If Dirk Example is named dirk.example
(with small initial letters) within your XML source, the Org Chart won't function correctly.
Synchronization
Navigate to Confluence administration → Administration → Scheduled Jobs.
Scroll down until you find LUP: Bulk profile update (XML sync).
To start the job (aka. synchronization), click on the Run button.
To create a schedule so this job runs regularly, click on the Edit button and follow the instructions provided by Confluence.
Additional benefits when importing into select or multi-select fields
After importing profile data from the XML file, the Linchpin User Profiles knows all distinct values. This means that you don't have to create all field options manually when importing into a select or multi-select field.
People directory filters for XML-imported select fields will show all existing values in their dropdowns.
Users that can edit such fields (because there was no data for them in the XML file), will also be able to choose from all existing values. This also works in Linchpin Assistant and Linchpin Onboarding.
How to clear the XML import configuration
Navigate to Confluence administration → Linchpin User Profiles → Data sources → XML.
Scroll down to the Clear XML import configuration section.
To clear/delete the configuration, click on the Clear now button. A pop-up window will ask for confirmation. Click OK to confirm the deletion.
Looking for an alternative in the Cloud?
Besides offering apps like Linchpin Intranet Suite, that is available for Atlassian Data Center, we also have apps for Confluence Cloud in our portfolio.
Like Mantra, the intranet for Confluence Cloud, developed by our joint-venture AppAnvil (known for hits like Aura & Karma).
Test the intranet for Confluence Cloud now for free:
Link to this page: https://seibert.biz/lup-xmlimport