Scenario

You are configuring or troubleshooting a people integration and need to control how fields from your source system map to PlusPlus user attributes. For example, your HRIS returns manager information as a nested object, but PlusPlus expects a single email address — attribute mapping bridges that gap. You may also want to add custom attributes (cost center, business unit, worker type) for use in filtering, reporting, and automated rules.

Solution

How attribute mapping works

When PlusPlus receives a payload from your source system — a SCIM message, a Workday RaaS report, a Direct API response, or a CSV file — every PlusPlus user attribute (name, email, department, manager, etc.) is populated by extracting a value from that payload using a mapping expression.

All people integration methods use JMESPath — a query language for JSON — with one important difference between JSON and CSV sources. JSON-based payloads (SCIM, Workday, most Direct API integrations) support nested expressions, such as manager.Manager. CSV-based payloads (CSV over SFTP) are flat, so expressions are typically just the column name (e.g., Employee_Email).

Mappings cover two kinds of attributes:

Standard attributes. Fields PlusPlus knows about natively — name, email, title, department, location, manager, employee ID, hire date, and so on. These have dedicated mapping fields in the integration settings.
Custom attributes. Additional fields you want to bring over for filtering, reporting, or automated rules — cost center, business unit, worker type, etc. These are defined in a free-form custom attributes section.

View current mappings

Go to System Settings > Integrations > People.
Standard attribute mappings appear at the top of the page, with one field per PlusPlus attribute.
Custom attribute mappings appear in the Custom attributes section.

You can also access this page directly from the Syncs Dashboard by clicking People Integration Settings in the top right.

Edit a standard attribute mapping

Open System Settings > Integrations > People.
Locate the field for the attribute you want to change (e.g., Email, Manager, Department).
Edit the JMESPath expression to extract the correct value from your payload.
Save your changes.
Run a dry sync from the Syncs Dashboard to confirm the mapping behaves as expected before it runs against live data.

For complex expressions — anything involving filtering, joining, conditional fallbacks, or unfamiliar JMESPath features — work with PlusPlus support. Incorrect mappings are the most common cause of failed syncs.

Add a custom attribute

Custom attributes are defined as YAML-formatted key-value pairs in the Custom attributes field of the integration settings.

Open System Settings > Integrations > People.
Scroll to the Custom attributes section.
Add one mapping per line, in the format <attr_name>: <path-expression>. For example:

cost_center: costCenter

worker_type: WorkerType.WorkerType

language: preferred_language

roles: roles | join(', ', @)

Save your changes.
Run a dry sync to confirm the new attribute is being extracted correctly. Inspect a user's record via View Custom Attributes to confirm the value (see Verify mappings for an individual user below).

Naming rules:

Attribute names may contain only ASCII alphanumeric characters and underscores (e.g., cost_center, worker_type_id).
Path expressions follow the same JMESPath syntax as standard attribute mappings.
Multiple mappings are separated by new lines.

Exclude attributes from CSV export

You can prevent specific attributes from being included when exporting people integration data to CSV — useful when certain fields aren't relevant outside the platform, or you don't want them included in downloaded reports.

Open System Settings > Integrations > People.
In the Exclude attributes for CSV export field, enter a comma-separated list of attribute names to exclude.
Save your changes.

Verify mappings for an individual user

To see the actual values that have been mapped for a specific user, open the Custom Attributes modal from one of two places:

From the People dashboard — find the user, click the kebab menu (⋮) on their row, and select View Custom Attributes.
From a user's profile — click the kebab menu (⋮) in the top right of the profile, and select View Custom Attributes.

The modal shows the user's standard attributes (Title, Name, Email, Timezone, Department, Hire date) at the top, and a People Integration Data table below listing each custom attribute and its current value. If a mapping is missing or incorrectly extracted, this is where you'll see it.

Go deeper

JMESPath quick reference

JMESPath expressions extract values from a JSON payload. A few patterns admins commonly need:

Pattern	What it does	Example
field	Extract a top-level field	title
parent.child	Extract a nested field	manager.Manager
array[0]	Get the first item in an array	emails[0].value
array[?condition]	Filter an array	emails[?primary]
expr \| function(@)	Pipe into a function	roles \| join(', ', @)
expr1 \|\| expr2	Use the second expression if the first is null	cost_center_id \|\| '-1'
join(' ', [a, b])	Concatenate values with a separator	join(' ', [name.givenName, name.familyName])

For the full language reference and an interactive testing tool, see jmespath.org.

Test an expression against a sample payload

Before saving a mapping change, test it against a sample of your real payload:

From the Syncs Dashboard, open any sync run, click View User Records on a user, and select View Payload. Copy the JSON.
Go to jmespath.org.
Paste the JSON into the large text area on the page.
Type your expression into the small input above the text area. The extracted value appears below.

This lets you iterate on an expression before applying it to the live mapping configuration.

Example: SCIM payload mappings

Given the following SCIM payload:

{

"name": { "givenName": "John", "familyName": "Smith" },

"title": "Senior Manager, IT",

"active": true,

"emails": [ {"value": "[email protected]", "primary": true } ],

"manager": { "Manager": "100789" },

"HireDate": { "newHireDate": "2022-08-31" },

"userName": "[email protected]",

"WorkerType": { "WorkerType": "Employee" },

"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

"department": "Education",

"employeeNumber": "100123"

}

The corresponding mappings would be:

PlusPlus attribute	JMESPath expression
Name	join(" ", [name.givenName, name.familyName])
Email	emails[?primary].value \| [0] \|\| userName
Title	title
Department	"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User".department
Manager	manager.Manager
Manager type	Employee ID (selected from the Manager type dropdown)
Employee ID	"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User".employeeNumber
Hire date	HireDate.newHireDate
Active	active
Custom: worker_type	WorkerType.WorkerType

Example: Workday-style custom attributes

A typical custom attributes block for a Workday integration:

cost_center: costCenter

worker_type: WorkerType.WorkerType

language: preferred_language

roles: roles | join(', ', @)

cost_center_id: cost_center_id || '-1'

The last line uses the || fallback operator to default to '-1' when the source field is missing — useful when downstream automated rules expect every user to have a value.

Example: CSV column mappings

For a CSV file with the header row:

Employee_ID, Full_Name, Work_Email, Department, Manager Email, Cost Center