To obtain profile data, Linchpin User Profiles can use XML as source.
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.
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)
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 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.
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).
Important notice regarding the XML sync and case sensitivity
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.