> For the complete documentation index, see [llms.txt](https://docs.aohwv.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aohwv.dev/features/data-mapping.md).

# 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

{% stepper %}
{% step %}

#### Open Data Mapping

Navigate to **Data Mapping** in the sidebar.
{% endstep %}

{% step %}

#### Select Source System

Select your **Source System** from the dropdown.
{% endstep %}

{% step %}

#### View Mapping Table

View the mapping table.
{% endstep %}
{% endstepper %}

| 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

{% stepper %}
{% step %}

#### Open Mapping Editor

Click **"+ Add Mapping"** in the top right corner.
{% endstep %}

{% step %}

#### 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
```

{% endstep %}

{% step %}

#### Select Target Attribute

Choose the Azure AD attribute to populate:

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

{% endstep %}

{% step %}

#### 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" → "<john@company.com>" |
| `concat`      | Combine multiple fields            | "John" + "Doe" → "John Doe"   |
| {% endstep %} |                                    |                               |

{% step %}

#### Save Mapping

Click **"Save"** to add the mapping. It will take effect on the next sync.
{% endstep %}
{% endstepper %}

## 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: "john.doe@company.com"
```

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

{% stepper %}
{% step %}

#### Start Test

Click **"Test Mapping"** on any mapping row.
{% endstep %}

{% step %}

#### Select Sample Record

Enter or select a sample HR record.
{% endstep %}

{% step %}

#### Review Output

Review the transformed output.
{% endstep %}

{% step %}

#### Verify Format

Verify the target attribute format.
{% endstep %}
{% endstepper %}

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

## Editing and Deleting Mappings

### Edit a Mapping

{% stepper %}
{% step %}
Click the **pencil icon** on the mapping row.
{% endstep %}

{% step %}
Modify source, target, or transformation.
{% endstep %}

{% step %}
Click **"Save Changes"**.
{% endstep %}
{% endstepper %}

### Delete a Mapping

{% stepper %}
{% step %}
Click the **trash icon** on the mapping row.
{% endstep %}

{% step %}
Confirm deletion.
{% endstep %}

{% step %}
The attribute will no longer sync.
{% endstep %}
{% endstepper %}

{% hint style="danger" %}
Warning: Deleting a mapping does not remove data already synced to Azure AD.
{% endhint %}

## 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:

{% stepper %}
{% step %}
Verify the HR system connection is active
{% endstep %}

{% step %}
Check field permissions in the source system
{% endstep %}

{% step %}
Refresh the source schema
{% endstep %}
{% endstepper %}

## Related Topics

* [Job Scheduling](/features/scheduling.md) - Automate sync operations
* [Monitoring Syncs](/features/monitoring.md) - Track mapping effectiveness
* Sync Errors - Resolve data issues


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aohwv.dev/features/data-mapping.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.