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

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

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.