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.

Exemplary XML file
<?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.

Multiple values (until 2.25)
<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.

Multiple values (from 2.26)
<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

 

Line breaks in an XML user profiles sync
<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).


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.

 

 





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: 


Discover Mantra



This page was last edited on 06/05/2024.