> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/administration/attributes/connect-an-attribute-source.md).

# Connect an attribute source

How attribute source connectors work, what Userlane reads from connected systems, and the shared setup steps that apply to every connector.

Connecting an attribute source lets you pull user attributes from a system you already use. Once connected, that information updates in Userlane automatically, so your audiences[^1] and your targeting stay accurate without anyone maintaining a list.

Each connector follows the same model: Userlane reads a fixed set of attributes[^2] from the source system, matches people by email address, and refreshes the data once a day. The individual connector pages cover system-specific setup. This page covers everything that is true regardless of which system you connect.

## What Userlane reads

Userlane has a fixed set of attributes it looks for. Every system you connect is matched against this same set.

<table><thead><tr><th width="246.55078125">Attribute</th><th>What exactly it holds</th></tr></thead><tbody><tr><td>Job title</td><td>The person's title as recorded in the source system</td></tr><tr><td>Department</td><td>The department or team they belong to</td></tr><tr><td>Manager</td><td>A reference to the person they report to</td></tr><tr><td>Whether they manage others</td><td>A yes or no value, where the source system provides one</td></tr><tr><td>Employment status</td><td>Whether they are currently active</td></tr><tr><td>Employment type</td><td>Full time, part time, contractor, and similar</td></tr><tr><td>Hire date</td><td>When they joined</td></tr><tr><td>Employee number</td><td>Their identifier in the source system</td></tr><tr><td>Company name</td><td>The legal entity or subsidiary they belong to</td></tr><tr><td>Company ID</td><td>The identifier for that entity, where one exists</td></tr><tr><td>Country</td><td>Their country</td></tr><tr><td>Region</td><td>State or province</td></tr><tr><td>City</td><td>Their city</td></tr><tr><td>Preferred language</td><td>The language they have set in the source system</td></tr><tr><td>App permission</td><td>Their permission level or profile in the source system, such as administrator or standard user</td></tr></tbody></table>

Anything not on this list is dropped at the point of collection. Phone numbers, home addresses, compensation, performance data, and any custom fields your team has added are not read and not stored.

If you need an attribute that is not on the list, talk to your Userlane contact before connecting. It will not arrive on its own.

## What appears after connecting

When a source provides one of the attributes above, Userlane creates it automatically and starts populating it. You do not need to create anything beforehand, and only attributes the source actually provides are created. If your system holds no hire date, no hire date attribute appears in Userlane.

Attributes are matched by name. If you already created an attribute called `job_title` and a connected system provides job title, the connection updates that existing attribute rather than creating a second one. Whatever was in it before is replaced, and it keeps being replaced every day the connection syncs.

This is usually what you want, because it means one attribute rather than two. It becomes a problem if you were populating that attribute from another source and expected it to stay as it was. If you have attributes coming from your own application or a manual upload, check their names against the list above before you connect a source.

## The connected system becomes the authority

Once a source is connected, it is the authority for the attributes it provides. Each sync writes what the source currently holds, so changes made by hand in Userlane are replaced the next time it runs.

This keeps the two systems from drifting apart. In practice it means that after connecting a source, corrections belong in that system rather than in Userlane. If someone's department is wrong here, fix it in the source system and it will be right within a day.

## How Userlane matches users

People are matched by work email address. Userlane compares the email on each incoming record with the email on existing Userlane users, ignoring capitalization and spaces. Where they match, the attributes are applied. Where they do not, nothing happens for that person.

Email is therefore the one field a source system has to provide. It is used to identify people rather than stored as an attribute, and a connection that cannot read it cannot match anyone at all.

This is the single most common reason a connection appears to do nothing. If your human resources (HR) system holds a different address than the one people sign in to Userlane with, the connection will run, succeed, and match nobody. It is worth comparing a handful of people in both systems before you connect.

{% hint style="info" %}
**A connector only updates people Userlane already knows about.** If someone appears in the source system but has not used Userlane yet, nothing is created for them. Attributes arrive when that person first appears in Userlane.
{% endhint %}

## What happens to fields the source does not provide

Not every system provides every attribute. A project tool may hold a language preference and nothing about employment. An HR system usually holds most of them. Userlane takes what is there and leaves the rest blank.

The same is true of fields your system holds but does not fill in. If job title exists in your system but half the records leave it empty, half your people will have no job title in Userlane. Connecting a source does not improve the data in it, so it is worth checking a few records before you connect rather than after.

## Behavior shared by every connector

Three things are true regardless of which system you connect.

**It only reads.** Userlane never writes to your source system, and never changes anything in it.

**It never removes anything.** A connector adds and updates attributes. If the source system stops providing a value, the last value Userlane received stays in place rather than being cleared. Nothing you connect can delete attribute data.

**It applies across your whole account.** A connected source applies to your entire Userlane account, not to one application or website. Connect your HR system once and the attributes are available everywhere you use Userlane. If you need attributes that apply to only one application, the [Attribute Import API](/developer-reference/push-user-attributes-via-api.md) (application programming interface) supports that.

## Who needs to be involved

Two things happen in the source system, and they can be done by two different people.

**Registering the connection.** Someone sets up an application, or an equivalent, in the source system. This is a one-time task and usually needs an administrator of that system.

**Authorizing it.** Someone signs in to approve the connection. This is the step that decides what Userlane can see, and it is where connections quietly go wrong.

{% hint style="warning" %}
**The most common failure has no error message.** A connection reads the directory using the permissions of whoever authorized it. If that person can only see their own record, Userlane receives only their record. In some systems the result is an empty list rather than a warning, and the connection will look successful in both systems. The permission matters more than the job title. See the page for your system for the specific permission needed.
{% endhint %}

In most cases you do not need to hand over full administrator rights. For [Salesforce](/administration/attributes/connect-an-attribute-source/salesforce.md) and [Jira](/administration/attributes/connect-an-attribute-source/jira.md) the permission needed can be granted to a normal account without making anyone an administrator. Microsoft Entra ID is the exception: approving the connection requires a **Global Administrator** or **Privileged Role Administrator**.

You also need an **Admin**, **Portfolio Owner**, or **Deployment Manager** role in Userlane to set the connection up on the Userlane side.

## Connecting a source

Before starting, ask your Userlane contact for the callback address for your system. Registering the application in your source system requires a redirect or callback address that is specific to Userlane, and you will not be able to work it out yourself.

{% stepper %}
{% step %}

#### Register an application in the source system

Follow the page for your system, listed under [Setup pages by system](#setup-pages-by-system). Each page has the steps and permissions for that system.
{% endstep %}

{% step %}

#### Open Attribute sources in Userlane

In the portal, go to **Attribute sources** under company settings.
{% endstep %}

{% step %}

#### Choose the system and enter the setup values

Select your system from the list and enter the values from the application you registered in the previous step.
{% endstep %}

{% step %}

#### Complete the sign-in step

Your source system presents an authorization screen. Sign in with an account that holds the permission described on that system's page.
{% endstep %}

{% step %}

#### Confirm the connection

Your system appears under connected sources. The first update usually arrives within about fifteen minutes.
{% endstep %}
{% endstepper %}

After the initial sync, Userlane refreshes overnight, once a day. You cannot change how often this happens, and there is no way to trigger an update on demand.

## If your system is not listed

The list shows every source you can connect. If yours is not there, speak to your Userlane contact. Some systems can be supported with a little preparation, and they can tell you whether yours is one of them.

In the meantime, you can send attribute information to Userlane directly through the [Attribute Import API](/developer-reference/push-user-attributes-via-api.md), which works with any system your team can export from. The API also supports two things connectors do not: it can target a single application rather than the whole account, and it can replace values rather than only adding them.

## Disconnecting a source

You can disable or remove a connected source at any time. Userlane stops reading from it immediately.

## Troubleshooting

<table><thead><tr><th width="194.6171875">Symptom</th><th width="313.6875">Likely cause</th><th>What to do</th></tr></thead><tbody><tr><td>Nothing has appeared yet</td><td>Give it fifteen minutes from connecting. After that, the most common cause is an email mismatch.</td><td>Check that a few people have the same email address in both systems.</td></tr><tr><td>Some people have attributes and others do not</td><td>Those people have a different email address in the two systems, or the account that authorized the connection cannot see them.</td><td>Check the permission described on the page for your system, then reconnect.</td></tr><tr><td>Some attributes are empty for everyone</td><td>The source system either does not hold that attribute or does not fill it in.</td><td>Check a few records in the source system directly.</td></tr><tr><td>An attribute you were already using now holds different values</td><td>A connected source is writing into it because it has the same name as one of the attributes Userlane collects.</td><td>See <a href="#what-appears-after-connecting">What appears after connecting</a>.</td></tr><tr><td>A change you made in Userlane has reverted</td><td>Expected. The connected system is the authority for the attributes it provides, so edits made in Userlane are replaced by the next sync.</td><td>Make the change in the source system instead.</td></tr><tr><td>Setup did not finish</td><td>This is usually in the source system rather than Userlane.</td><td>Check that setup was completed, that the values were copied in full, and that the callback address matches what your Userlane contact gave you. If the organization reviews new applications, it may still be waiting for approval.</td></tr><tr><td>Information stopped updating</td><td>The credentials may have expired, or the setup in the source system may have been changed or removed.</td><td>Reconnect the source.</td></tr><tr><td>A value changed unexpectedly</td><td>If more than one source provides the same attribute, the most recent update is the one you see.</td><td>Check whether another source is also providing that attribute.</td></tr></tbody></table>

If none of this resolves the problem, [contact Userlane support](/support/contact-and-escalation.md).

## Setup pages by system

{% columns %}
{% column width="50%" %}
{% content-ref url="/pages/tWyRuuxK4JQGiel23FTb" %}
[SAP SuccessFactors](/administration/attributes/connect-an-attribute-source/sap-successfactors.md)
{% endcontent-ref %}

{% content-ref url="/pages/ekEvKo622H3LyNoeLH8g" %}
[Google Workspace](/administration/attributes/connect-an-attribute-source/google-workspace.md)
{% endcontent-ref %}

{% content-ref url="/pages/b1SMRSBtvkd1sZZNi9U4" %}
[Salesforce](/administration/attributes/connect-an-attribute-source/salesforce.md)
{% endcontent-ref %}
{% endcolumn %}

{% column width="50%" %}
{% content-ref url="/pages/dOsfp2lveEGwAS8a7Pkt" %}
[ServiceNow](/administration/attributes/connect-an-attribute-source/servicenow.md)
{% endcontent-ref %}

{% content-ref url="/pages/Nlq8AtCgmbXQstjU6XiP" %}
[Jira](/administration/attributes/connect-an-attribute-source/jira.md)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}

## Relevant articles

{% content-ref url="/pages/gtcOzAVjL7zzv75As2Jd" %}
[Attributes](/administration/attributes.md)
{% endcontent-ref %}

{% content-ref url="/pages/heUmxS6HxlGKqCQSjqbs" %}
[Attribute sources](/administration/attributes/attribute-sources.md)
{% endcontent-ref %}

{% content-ref url="/pages/eDKAypFN3hxD4iC2VJll" %}
[Attributes from SSO](/administration/attributes/attributes-from-sso.md)
{% endcontent-ref %}

{% content-ref url="/pages/Zk1PSRimln0YLI1l2ZkI" %}
[Build an audience from attribute rules](/administration/audiences/build-an-audience-from-attribute-rules.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>What systems can be connected as attribute sources?</summary>

Userlane supports connectors for SAP SuccessFactors, Microsoft Entra ID, Google Workspace, Salesforce, ServiceNow, and Jira. Each has a dedicated setup page. If your system is not listed, the Attribute Import API can send attribute data from any system your team can export from.

</details>

<details>

<summary>How often does Userlane sync with a connected source?</summary>

After the initial sync, which usually completes within about fifteen minutes of connecting, Userlane refreshes overnight once a day. There is no way to change this interval or trigger an update on demand.

</details>

<details>

<summary>Can I connect a source for a single application rather than the whole account?</summary>

No. A connected source applies to the entire Userlane account. If you need attributes scoped to a single application, use the Attribute Import API instead.

</details>

<details>

<summary>Does Userlane write anything back to the source system?</summary>

No. Every connector is read-only. Userlane never writes to, changes, or deletes anything in the connected system.

</details>

<details>

<summary>What happens if the same attribute comes from more than one source?</summary>

The most recent update is the one you see. If two sources provide the same attribute for the same person, whichever syncs last determines the current value.

</details>

[^1]: An audience is a reusable group of people defined by attribute rules. Audiences control which content and analytics apply to which people.

[^2]: Attributes are pieces of information Userlane holds about each person, such as their department, job title, or country. They come from connected systems, single sign-on, manual uploads, or the API.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/administration/attributes/connect-an-attribute-source.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.