> 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/administration/settings.md).

# Settings

This guide covers CloudSync system configuration options available to administrators.

## Overview

System Settings let you configure global options that affect all CloudSync operations, including connections, sync behavior, notifications, and security.

## Who This Is For

* **Administrators** who need to configure system behavior
* **Operators** viewing current configuration (read-only)

## Prerequisites

* ✅ **Administrator role** — Required to change settings
* ✅ Operators can view but not modify

## Accessing Settings

{% stepper %}
{% step %}
Go to CloudSync and open the Settings menu.

Steps:

* Log in to CloudSync
* Click **Settings** in the sidebar
* Choose a settings category
  {% endstep %}
  {% endstepper %}

## Settings Categories

### Connections

Manage connections to HR systems and Microsoft Graph.

**Available options:**

| Setting               | Description                           |
| --------------------- | ------------------------------------- |
| **HR Connections**    | Add, edit, test HR system connections |
| **Microsoft Graph**   | Manage Azure AD app connection        |
| **Connection Health** | View status of all connections        |

#### Test a Connection

{% stepper %}
{% step %}
Go to **Settings** → **Connections**
{% endstep %}

{% step %}
Find the connection and click **Test**
{% endstep %}

{% step %}
View results (success or error details)
{% endstep %}
{% endstepper %}

#### Add an HR Connection

{% stepper %}
{% step %}
Click **+ Add Connection**
{% endstep %}

{% step %}
Select connection type (Workday, BambooHR, etc.)
{% endstep %}

{% step %}
Enter connection details:

* URL/endpoint
* Authentication (API key, OAuth, etc.)
* Credentials
  {% endstep %}

{% step %}
Click **Test Connection**
{% endstep %}

{% step %}
If successful, click **Save**
{% endstep %}
{% endstepper %}

### Sync Configuration

Control how syncs behave.

**Available options:**

| Setting            | Description                   | Default       |
| ------------------ | ----------------------------- | ------------- |
| **Sync Scope**     | Which users/groups to include | All           |
| **Sync Direction** | HR → Entra ID, bidirectional  | HR → Entra ID |
| **Batch Size**     | Records per batch             | 100           |
| **Timeout**        | Max time per sync             | 60 min        |
| **Retry Attempts** | Auto-retry on failure         | 2             |

#### Configure Sync Scope

{% stepper %}
{% step %}
Go to **Settings** → **Sync Configuration**
{% endstep %}

{% step %}
Click **Edit Scope**
{% endstep %}

{% step %}
Add rules:

* Include departments: Engineering, Sales
* Exclude departments: Contractors
* Include locations: US, UK
* Exclude: Test users (matching pattern)
  {% endstep %}

{% step %}
Click **Save**
{% endstep %}
{% endstepper %}

#### Conflict Resolution

When data differs between systems:

| Option            | Behavior                              |
| ----------------- | ------------------------------------- |
| **Source wins**   | HR data overwrites Entra ID (default) |
| **Target wins**   | Preserve Entra ID values              |
| **Manual review** | Flag for admin review                 |

### Notifications

Configure how you receive alerts.

**Available options:**

| Setting                 | Description                 |
| ----------------------- | --------------------------- |
| **Email Notifications** | Who receives alerts         |
| **Notification Types**  | What triggers notifications |
| **Digest Settings**     | Daily/weekly summaries      |

#### Email Notifications

{% stepper %}
{% step %}
Go to **Settings** → **Notifications**
{% endstep %}

{% step %}
Under **Email Recipients**, add addresses
{% endstep %}

{% step %}
Choose notification types:

* ✅ Sync failures
* ✅ Sync warnings
* ⬜ Sync success (optional)
* ✅ Connection issues
* ✅ Security alerts
  {% endstep %}

{% step %}
Click **Save**
{% endstep %}
{% endstepper %}

#### Digest Settings

Reduce notification volume with digests:

| Option            | Frequency                |
| ----------------- | ------------------------ |
| **Real-time**     | Immediate for each event |
| **Hourly digest** | Summary every hour       |
| **Daily digest**  | Summary at end of day    |
| **Weekly digest** | Weekly summary           |

### Security

Manage security settings and policies.

**Available options:**

| Setting               | Description                  |
| --------------------- | ---------------------------- |
| **Session Timeout**   | Auto-logout after inactivity |
| **Allowed IP Ranges** | Restrict access by IP        |
| **MFA Requirement**   | Enforce MFA for access       |
| **API Access**        | Manage API keys              |

#### Session Timeout

Go to **Settings** → **Security**

Set **Session Timeout** (e.g., 30 minutes)

Click **Save**

Note: Users will be logged out after this period of inactivity.

#### IP Restrictions

{% stepper %}
{% step %}
Under **Allowed IP Ranges**, click **Add**
{% endstep %}

{% step %}
Enter IP range in CIDR notation (e.g., 10.0.0.0/8)
{% endstep %}

{% step %}
Add description (e.g., "Corporate network")
{% endstep %}

{% step %}
Click **Save**
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Test IP restrictions before enabling to avoid locking yourself out.
{% endhint %}

### System

General system configuration.

**Available options:**

| Setting           | Description             |
| ----------------- | ----------------------- |
| **Timezone**      | For scheduling and logs |
| **Date Format**   | Display format          |
| **Language**      | UI language             |
| **Log Retention** | How long to keep logs   |

#### Set Timezone

{% stepper %}
{% step %}
Go to **Settings** → **System**
{% endstep %}

{% step %}
Select your **Timezone** from dropdown
{% endstep %}

{% step %}
Click **Save**
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Important: This affects when scheduled syncs run. Choose your primary operating timezone.
{% endhint %}

#### Log Retention

Control how long logs are kept:

| Period  | Use Case                 |
| ------- | ------------------------ |
| 30 days | Standard operation       |
| 90 days | Extended troubleshooting |
| 1 year  | Compliance requirements  |
| Custom  | Specific policy needs    |

### User Access

Manage who can access CloudSync (see [Roles and Permissions](file:///7252607/core-concepts/roles-permissions.md)).

**Available options:**

| Action            | Description               |
| ----------------- | ------------------------- |
| **Add User**      | Grant access to new user  |
| **Remove User**   | Revoke access             |
| **Change Role**   | Modify user's permissions |
| **View Activity** | See user's recent actions |

## What You Should See

After configuring settings:

* ✅ Connection tests pass
* ✅ Sync scope matches your org structure
* ✅ Notifications reach intended recipients
* ✅ Security policies are enforced

## Common Configuration Tasks

### Initial Setup

{% stepper %}
{% step %}
Configure HR connection
{% endstep %}

{% step %}
Configure Microsoft Graph connection
{% endstep %}

{% step %}
Set timezone
{% endstep %}

{% step %}
Define sync scope
{% endstep %}

{% step %}
Add admin users
{% endstep %}

{% step %}
Configure notifications
{% endstep %}

{% step %}
Set up first schedule
{% endstep %}
{% endstepper %}

### Adding a New HR System

{% stepper %}
{% step %}
Add connection (**Settings** → **Connections**)
{% endstep %}

{% step %}
Test connection
{% endstep %}

{% step %}
Add data mappings (**Data Mapping**)
{% endstep %}

{% step %}
Configure scope
{% endstep %}

{% step %}
Create schedule
{% endstep %}

{% step %}
Run test sync
{% endstep %}
{% endstepper %}

### Updating Credentials

{% stepper %}
{% step %}
Go to **Settings** → **Connections**
{% endstep %}

{% step %}
Click **Edit** on the connection
{% endstep %}

{% step %}
Update credentials
{% endstep %}

{% step %}
Click **Test Connection**
{% endstep %}

{% step %}
If successful, click **Save**
{% endstep %}
{% endstepper %}

## Troubleshooting

<details>

<summary>Connection test fails</summary>

| Symptom                 | Cause             | Solution                   |
| ----------------------- | ----------------- | -------------------------- |
| "Connection refused"    | Firewall blocking | Allow CloudSync IPs        |
| "Authentication failed" | Bad credentials   | Re-enter username/password |
| "Certificate error"     | SSL issue         | Check certificate validity |
| "Timeout"               | Network slow      | Increase timeout setting   |

</details>

<details>

<summary>Settings won't save</summary>

| Symptom             | Cause         | Solution                           |
| ------------------- | ------------- | ---------------------------------- |
| "Permission denied" | Not admin     | Contact administrator              |
| Validation error    | Invalid input | Check error message, correct input |
| "Save failed"       | System issue  | Retry; contact support             |

</details>

<details>

<summary>Notifications not arriving</summary>

| Symptom   | Cause             | Solution                    |
| --------- | ----------------- | --------------------------- |
| No emails | Wrong address     | Verify email in settings    |
| In spam   | Email filtering   | Whitelist CloudSync sender  |
| Disabled  | Notifications off | Check notification settings |

</details>

## Next Steps

* [User Management](/administration/users.md) — Manage synced users
* [Audit Logs](/administration/audit-logs.md) — Track configuration changes
* [Scheduling](/features/scheduling.md) — Set up sync schedules

## Related Topics

* [Roles and Permissions](broken://pages/Of80BY1YKe7rHee20jAe) — Access control
* Troubleshooting Hub — Fix issues
* Getting Support — Contact support


---

# 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/administration/settings.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.