Data Mapping

Data mapping defines how fields from your HR system translate to attributes in Microsoft Entra ID (Azure AD). Proper mapping ensures accurate user provisioning and attribute synchronization.

Overview

CloudSync connects source fields (from your HR system) to target attributes (in Azure AD):

┌──────────────────┐                    ┌──────────────────┐
│   HR System      │                    │   Azure AD       │
│   (Source)       │                    │   (Target)       │
├──────────────────┤    ┌──────────┐    ├──────────────────┤
│ employee_id      │───▶│ MAPPING  │───▶│ employeeId       │
│ first_name       │───▶│          │───▶│ givenName        │
│ last_name        │───▶│          │───▶│ surname          │
│ work_email       │───▶│          │───▶│ mail             │
│ job_title        │───▶│          │───▶│ jobTitle         │
│ department       │───▶│          │───▶│ department       │
│ manager_id       │───▶│          │───▶│ manager          │
└──────────────────┘    └──────────┘    └──────────────────┘

Viewing Current Mappings

1

Open Data Mapping

Navigate to Data Mapping in the sidebar.

2

Select Source System

Select your Source System from the dropdown.

3

View Mapping Table

View the mapping table.

Source Field	Target Attribute	Transform	Status
employee_id	employeeId	none	✓ Active
first_name	givenName	trim	✓ Active
last_name	surname	trim	✓ Active
work_email	mail	lowercase	✓ Active

Creating a New Mapping

1

Open Mapping Editor

Click "+ Add Mapping" in the top right corner.

2

Select Source Field

Choose the field from your HR system:

Source Field: [Select field ▾]
├── employee_id
├── first_name
├── last_name
├── work_email
├── job_title
├── department
├── cost_center
├── start_date
└── manager_id

3

Select Target Attribute

Choose the Azure AD attribute to populate:

Target Attribute: [Select attribute ▾]
├── employeeId
├── givenName
├── surname
├── displayName
├── mail
├── userPrincipalName
├── jobTitle
├── department
└── manager

4

Add Transformation (Optional)

Apply a transformation to the data before syncing:

Transform	Description	Example
none	Pass through unchanged	"John" → "John"
lowercase	Convert to lowercase	"JOHN" → "john"
uppercase	Convert to uppercase	"john" → "JOHN"
trim	Remove leading/trailing whitespace	" John " → "John"
prefix	Add text before value	"12345" → "EMP-12345"
suffix	Add text after value	"john" → "[e-mail]"
concat	Combine multiple fields	"John" + "Doe" → "John Doe"

5

Save Mapping

Click "Save" to add the mapping. It will take effect on the next sync.

Common Mapping Patterns

Basic User Attributes

HR Field	Azure AD Attribute	Notes
employee_id	employeeId	Unique identifier
first_name	givenName	First/given name
last_name	surname	Last/family name
work_email	mail	Primary email
work_email	userPrincipalName	For new user creation
job_title	jobTitle	Position title
department	department	Department name

Constructed Attributes

Some Azure AD attributes may require combining HR fields:

Display Name:

Source: first_name + " " + last_name
Transform: concat
Target: displayName
Result: "John Doe"

User Principal Name:

Source: first_name + "." + last_name + "@company.com"
Transform: concat, lowercase
Target: userPrincipalName
Result: "[e-mail]"

Manager Relationships

Linking users to their managers:

1. Map the HR manager_id to a temporary field
2. CloudSync resolves the manager reference
3. The manager attribute links to the Azure AD manager object

Testing Mappings

1

Start Test

Click "Test Mapping" on any mapping row.

2

Select Sample Record

Enter or select a sample HR record.

3

Review Output

Review the transformed output.

4

Verify Format

Verify the target attribute format.

Test Mapping: employee_id → employeeId
──────────────────────────────────────
Input:  "  12345  "
Transform: trim
Output: "12345"
✓ Ready to sync

Editing and Deleting Mappings

Edit a Mapping

1

Click the pencil icon on the mapping row.

2

Modify source, target, or transformation.

3

Click "Save Changes".

Delete a Mapping

1

Click the trash icon on the mapping row.

2

Confirm deletion.

3

The attribute will no longer sync.

Warning: Deleting a mapping does not remove data already synced to Azure AD.

Best Practices

Do:

• ✅ Test mappings with sample data before production
• ✅ Use trim on text fields to handle whitespace
• ✅ Use lowercase on email fields for consistency
• ✅ Document custom transformations

Don't:

• ❌ Map sensitive HR data unless required
• ❌ Create duplicate mappings for the same target
• ❌ Skip testing complex transformations

Troubleshooting

Mapping Not Taking Effect

• Check that the mapping status is Active
• Verify a sync has run since creating the mapping
• Check for transformation errors in the logs

Invalid Data Format

If Azure AD rejects values:

• Review the target attribute's format requirements
• Add appropriate transformations (e.g., email validation)
• Check for special characters that need escaping

Missing Source Fields

If an HR field isn't available:

1

Verify the HR system connection is active

2

Check field permissions in the source system

3

Refresh the source schema

Related Topics

• Job Scheduling - Automate sync operations
• Monitoring Syncs - Track mapping effectiveness
• Sync Errors - Resolve data issues