> ## Documentation Index
> Fetch the complete documentation index at: https://docs.provisionr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled Sync

> The scheduled sync is where Provisionr evaluates every policy and provisions or deprovisions users across connected systems on a configurable cadence.

Everything you've learned so far, from integrations and users to dimensions, policies, and groups, comes together during the scheduled sync. This is when Provisionr evaluates your policies and makes changes in your connected systems.

Each scheduled sync runs these stages in order:

* A [user sync](#user-sync), which brings your directory up to date with the users in each integration
* Two [attribute syncs](#attribute-syncs), which qualify users for your directory attributes
* A [group and resource sync](#group-and-resource-sync), which qualifies users for your groups and resources and writes the changes to each vendor

This page starts with when the sync runs, and then walks through each stage. The last two sections cover how to pause the sync for a single group or resource, and how long we keep the personal data of users who have been deprovisioned.

## Sync Change Window

We want changes to happen during a change window that suits your business hours. Provisionr caches data from each vendor API on a recurring basis, based on the frequency that's included with your subscription plan and the sync window that you choose.

To avoid hourly API rate limits and to conserve CO2, we use a 3-hour time window for syncs instead of a 1-hour time window.

The frequency of the sync is determined by your subscription plan.

* Baseline plan, with a weekly sync. You choose the day of the week, along with the preferred and secondary time windows.
* Growth plan, with a daily sync. You choose the preferred and secondary time windows.
* Scale plan, with a sync every 3 hours.

You can choose the time of day when changes go live, so that they happen at a predictable time for your organization. The sync is dispatched at the start of your preferred time window, and if there's an issue with the sync, it retries during the secondary time window.

We don't allow syncs between 18:00 and 21:00 UTC, because that window is reserved for maintenance and upgrades to the Provisionr infrastructure.

| UTC | US Central Winter (UTC-6) | US Central Summer (UTC-5) |
| - | - | - |
| 00:00 to 03:00 UTC | 6pm to 9pm | 7pm to 10pm |
| 03:00 to 06:00 UTC | 9pm to 12am | 10pm to 1am |
| 06:00 to 09:00 UTC | 12am to 3am | 1am to 4am |
| 09:00 to 12:00 UTC | 3am to 6am | 4am to 7am |
| 12:00 to 15:00 UTC | 6am to 9am | 7am to 10am |
| 15:00 to 18:00 UTC | 9am to 12pm | 10am to 1pm |
| 18:00 to 21:00 UTC | N/A (Reserved for Maintenance Window) | N/A |
| 21:00 to 24:00 UTC | 3pm to 6pm | 4pm to 7pm |

The US Central times follow standard time from November to March, and daylight saving time from March to November.

## User Sync

The user sync runs first, so that every stage after it works from the latest data in your integrations.

**1. User Fetch**

We fetch the current users from the vendor API.

**2. Identity Changes**

We check for new users, which we import as identities, for users who have been deprovisioned, and for any changes to their profile data.

**3. Dimension Changes**

We check the identity profile data for any new, changed, or missing dimensions, which are the profile keys, and create, update, or deprecate the matching Directory Dimension records.

**4. Attribute Changes**

We check the identity profile data for any new, changed, or missing attributes, which are the unique profile values, and create, update, or deprecate the matching Directory Attribute records. Every newly imported attribute comes with an [Imported Attribute Ruleset](https://docs.provisionr.io/concepts/control/policies.md#imported-attribute-rulesets).

**5. New Directory Users**

When a new user appears in your primary integration, which is usually your IdP, we create a new Directory User. This is the record that qualifies for the rules of your attributes, groups, and resources.

**6. Deprovisioned Directory Users**

When an existing user is deactivated in your IdP, we deactivate the user in Provisionr, and they are removed from your attributes, groups, and resources.

**7. Manager Mapping**

We recalculate manager relationships, based on the integration field matching that you have configured.

## Attribute Syncs

A rule can have an [Attribute Condition](https://docs.provisionr.io/concepts/control/policies.md#attribute-conditions), which matches the users who hold another attribute. We run the attribute sync twice in a row to cover a user who qualifies for one attribute and also needs to qualify, in the same scheduled sync, for a rule that requires them to hold that attribute. The first attribute sync qualifies users for attributes through Identity, Manager, and User Conditions, and the second one qualifies users for the rules that use an Attribute Condition.

Each attribute sync follows the [qualification steps](https://docs.provisionr.io/concepts/control/qualification.md#qualification-steps) for every attribute ruleset.

**1. Attribute Rule Qualification**

We expire any rule whose expiration date has passed. Then we work out which users match all of the conditions of each remaining rule, and update the list of qualified users for each rule.

**2. Attribute Ruleset Manifest**

We look at the qualified users of every rule and combine them into a list of unique users. When a user qualifies for more than one rule, the rule that qualifies the most users is recorded as the one that grants their access, as [Rule Priority](https://docs.provisionr.io/concepts/control/qualification.md#rule-priority) explains.

**3. Attribute Policy User Changes**

We compare the manifest users with the current Policy Users of each ruleset.

* A user who newly qualifies gets a new Policy User.
* A user whose Policy User was granted by a different rule, or who qualifies again while their Policy User is `expiring`, gets a new Policy User, and the old one is expired. The new record is created first, so the user never leaves the manifest.
* A user whose rule was deactivated, and who doesn't qualify through another rule, is deactivated at once, without a grace period.
* A user who no longer qualifies is deprecated. Their Policy User moves to `expiring`, and its `expires_at` is set to the end of their grace period.

The grace period is the rule's `expires_after_days`, or the value it inherits from the ruleset, the dimension, and the workspace default, in that order. A grace period gives users time through changes, such as a department or team rename, so that a user who still has a business need for the access isn't disrupted while back-office attributes or rules are changing.

A Policy User is never made `active` again. Instead, each qualification gets its own record, so you can see the lifecycle of every qualification. [Qualification](https://docs.provisionr.io/concepts/control/qualification.md) explains each case in detail.

**4. Expired Attribute Policy Users**

Every `expiring` Policy User whose `expires_at` has passed moves to `expired`, and the user leaves the attribute's manifest. From that point on, rules that use the attribute in an Attribute Condition no longer match them.

## Group and Resource Sync

Once the user data is up to date and the attribute syncs have qualified users for every attribute, we can qualify users for the rules of your groups and resources.

To keep this explanation clear, we use groups throughout, but the concept is the same for resources, such as a GitLab project, a Google Drive folder, a Google Doc, or a Slack channel.

The badges on each step show which policies it applies to. The Ignored, Monitored, Additive, and Authoritative badges are the ruleset modes that [Groups & Resources](https://docs.provisionr.io/concepts/control/groups.md) describes.

**1. Group Fetch**

IgnoredMonitoredAdditiveAuthoritative

We fetch the existing groups from the vendor API.

**2. Group Changes**

IgnoredMonitoredAdditiveAuthoritative

We check for new groups, which we import, for groups that have been deleted or have gone missing, and for any changes to a group's name or metadata. A new group is imported with a policy in the integration's default mode, which never writes to the group, so nothing changes in the group until you choose to manage it.

**3. Group Member Fetch**

MonitoredAdditiveAuthoritative

For each group, we fetch the existing members, which are the users attached to it, from the vendor API.

**4. Group Member Changes**

MonitoredAdditiveAuthoritative

Existing group members who aren't Provisionr Policy Users are imported in the `UNMANAGED` state. Any users in the Provisionr database who no longer appear in the vendor's API response change to the `DEPROVISIONED` state. Together, these give you an audit trail of the users who are managed outside of Provisionr.

**5. Group Rule Qualification**

AdditiveAuthoritative

We expire any rule whose expiration date has passed. Then we work out which users match all of the conditions of each remaining rule, and update the list of qualified users for each rule.

**6. Group Ruleset Manifest**

AdditiveAuthoritative

We look at the qualified users of every rule and combine them into a list of unique users. When a user qualifies for more than one rule, the rule that qualifies the most users is recorded as the one that grants their access, as [Rule Priority](https://docs.provisionr.io/concepts/control/qualification.md#rule-priority) explains.

**7. Group Policy User Changes**

AdditiveAuthoritative

We compare the manifest users with the current Policy Users of the ruleset, in the same way as for [attributes](#attribute-syncs).

* A user who newly qualifies gets a new Policy User.
* A user who now qualifies under a different rule, or who qualifies again while `expiring`, gets a new Policy User that supersedes the old one.
* A user whose rule was deactivated, and who doesn't qualify through another rule, is deactivated at once, without a grace period.
* A user who no longer qualifies is deprecated.

The grace period for a deprecation is the rule's `expires_after_days`, or the value it inherits from the ruleset, the integration, and the workspace default, in that order. A grace period gives users time through changes, such as a department or team rename, so that a user who still has a business need to be a member of the group or resource isn't disrupted while back-office attributes or rules are changing.

A grace period is there to protect users whose attributes changed, not users who have left. When a user leaves, they're removed from the group in the vendor API on the same sync, whatever the grace period is. [Removing Access for Leavers](https://docs.provisionr.io/concepts/control/qualification.md#removing-access-for-leavers) explains how.

**8. Expired Policy Users**

AdditiveAuthoritative

The Policy Users who were deprecated in this sync or a previous one have an `expires_at` date. If that date is in the past at the time of the sync, the Policy User moves to the `expired` state, and its record is soft deleted. This removes the user from the manifest, which is the list of users that the next steps sync with the vendor API, so Provisionr no longer considers them a member of the group.

This keeps an audit trail of each user's lifecycle and qualifications over time. It also gives administrators a grace period to fix any issues with rules or attributes that caused users to be deprovisioned, before those users are fully expired and removed from the group in the vendor API.

**9. Policy User Provisioning**

AdditiveAuthoritative

We provision every Policy User who doesn't already exist in the group in the vendor API.

**10. Policy User Deprovisioning**

AdditiveAuthoritative

We remove any users who no longer match the policy. For an additive group, this applies only to users who aren't in the `UNMANAGED` state, which ensures that pre-existing users aren't removed in this step. For an authoritative group, any users who don't match the policy are removed in the next step.

**11. Unmanaged User Deprovisioning**

Authoritative

When a group is authoritative, you have given Provisionr the authority to be the source of truth for who should have access to that group. Any pre-existing user, or any user who is granted access outside of Provisionr, whether by hand in the vendor's console or by other automation, is a risk to least privilege access. To reduce that risk, any users who were added outside of Provisionr or who don't match the current policy are removed during each sync.

If a user is in the `UNMANAGED` state, doesn't qualify for any rules, and is still a member of the group in the vendor API, we change their state to `DEPROVISIONED` in Provisionr and remove them from the group in the vendor API. This ensures that users who were added outside of Provisionr are removed, so the group keeps to least privilege access.

[How the Okta Sync Works](https://docs.provisionr.io/integrations/okta/sync.md) and [Okta Groups](https://docs.provisionr.io/integrations/okta/groups.md) describe these stages for Okta specifically, including the safety checks that can hold changes for review before they're written.

## Disabling Sync for a Group or Resource

When a group or resource is in any mode other than `ignored`, its ruleset has `sync_enabled` set to `true` by default.

You can disable the sync for a specific group or resource, temporarily or permanently, by changing `sync_enabled` to `false` on its ruleset. This prevents any changes from being made to that group or resource during the sync, so no users are added to it or removed from it in the integration, whether or not they match its rules and conditions. Each sync that's skipped records a `policy.ruleset.sync.process.skipped` event with the reason.

```bash Disabling Sync for a Ruleset theme={null}
prv policy-ruleset:update --id=poset_01hq8xyzabc123def456ghj789 --key=sync_enabled --value=false
```

You can re-enable the sync at any time by changing `sync_enabled` back to `true`. Any changes that would have been made while the sync was disabled are applied during the next sync, based on the latest calculation of the ruleset's Policy Users. [Update Ruleset](https://docs.provisionr.io/cli/workspace/v1/policy-ruleset/update.md) lists the options for this command.

This gives you more control over when changes are made to your groups and resources, so you can avoid unexpected changes during a critical time. It's useful when you're running into errors, when you have a planned data migration, or when you just want to freeze the data at its current point in time. It's also useful for groups or resources that are archived or deprecated, which you're no longer actively managing.

## Data Retention Duration

Provisionr has a configurable retention policy for how long we keep the personally identifiable information (PII) of deprovisioned users in the database after they're deprovisioned in the vendor API. In other words, a set number of days after an employee leaves the company, we scrub their PII and replace it with a Ghost User and null values where appropriate, while keeping the same user ID and vendor ID for any existing log records that are associated with that user. You can choose the number of days that works best for your organization's internal processes and compliance requirements.

This happens when we fetch users from the API. Users who were deprovisioned more than the retention duration ago aren't imported or synced. Any existing log records stay mapped to the same user ID, but the user's PII is scrubbed and replaced with a Ghost User and null values where appropriate.

We do this to protect PII and to support GDPR compliance. Once we've verified that a user has left the company, and their access deprovisioning processes are completed and audited, we no longer have a business need to keep their data for role-based access control (RBAC).

Each integration has its own retention duration, in days, in its `retention_days` setting. The default is `90` for new integrations, and you can modify any of your existing integrations to decrease it, or to increase it up to `1095` (3 years). The lowest value that you can set is `10` days, which allows time for every deprovisioning lifecycle task and for your organization's internal processes to complete, and which keeps the background API sync jobs, which are eventually consistent, working from reliable data.

If you increase the value, users who were previously outside the retention duration are imported during the next sync. If you decrease it, users who were previously included are archived, and their PII is scrubbed. If you increase it again later, those users are matched to their `vendor_id`, and their PII is restored on the existing database records. All of these changes are logged, and they trigger events for each of the users they affect.

***

This completes the Concepts learning path. When you need to go deeper on any topic, these pages are the place to return to.

* [Users & Identities](https://docs.provisionr.io/concepts/control/users.md) covers user identities, state mapping, and sync flows.
* [Dimensions & Attributes](https://docs.provisionr.io/concepts/control/dimensions.md) covers dimension and attribute management.
* [Policies & Rules](https://docs.provisionr.io/concepts/control/policies.md) covers rulesets, conditions, and rule priority.
* [Qualification](https://docs.provisionr.io/concepts/control/qualification.md) covers how each sync qualifies users, Policy User records, and grace periods.
* [Integrations](https://docs.provisionr.io/integrations/overview.md) covers vendor support, workspace integrations, and configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.