Microsoft Graph

Client Sync connects eCourtDate to a Microsoft Entra ID tenant through the Microsoft Graph API. On a set schedule, it reads user profiles and group memberships from the directory, creates and updates Clients in an eCourtDate agency, keeps those Clients in the agency organizations that bulk messages target, and can archive the Clients of users who leave. Entra ID is the source of truth for every mapped field and every audience rule, and the agency's Clients stay current without manual imports.

eCourtDate only reads the directory. It does not create, modify, or delete anything in Entra ID.

What Client Sync Does

Behavior	Detail
Selects users	Users are selected by Entra group membership, email domain, and directory attributes such as department, office location, or employee type.
Creates Clients	A selected directory user with no linked Client gets a new Client in the integration's Default Agency.
Updates Clients	A selected directory user with a linked Client has that Client's mapped fields brought in line with the directory on every run.
Writes only mapped fields	A Client field without a mapping row is never written.
Manages work contact details	The directory's email address and phone number are stored as a work email Contact and a work phone Contact on the Client. Other Contacts on the Client, such as a personal cell phone added later, are never changed.
Keeps audiences current	Audience rules place synced Clients in agency organizations based on Entra groups or attributes, and remove them when the rules no longer hold.
Handles departures	When a user is deleted or disabled in Entra ID, or no longer meets the population conditions, Client Sync either leaves their Client unchanged (the default) or archives it, as the agency chooses. Archiving stops messages to the Client and keeps its history. A limit stops one run from archiving more than a set share of Clients.
Never deletes	Client Sync never deletes a Client.
Sends no messages	Creating or updating a Client through Client Sync does not queue auto messages, including the client_created auto message.

Setup Overview

Setup happens in two places. Part 1 is done by an Entra administrator in Microsoft. Part 2 is done by an eCourtDate Super Admin in the eCourtDate Console. One person with both kinds of access can do both parts.

Step	Where	Who
1. Plan the population, fields, and audiences	Microsoft Entra admin center	Entra administrator, with the agency
2. Register an application	Microsoft Entra admin center	Entra administrator
3. Grant Microsoft Graph permissions	Microsoft Entra admin center	Privileged Role Administrator or Global Administrator
4. Create a credential	Workstation with OpenSSL, then Microsoft Entra admin center	Entra administrator
Hand off the values	Secure channel	Entra administrator to eCourtDate Super Admin
5. Create the integration	eCourtDate Console	eCourtDate Super Admin
6. Connect to Entra ID	eCourtDate Console	eCourtDate Super Admin
7. Choose which users to sync	eCourtDate Console	eCourtDate Super Admin
8. Map fields	eCourtDate Console	eCourtDate Super Admin
9. Set up audiences	eCourtDate Console	eCourtDate Super Admin
10. Preview and enable	eCourtDate Console	eCourtDate Super Admin
11. Verify the first run	eCourtDate Console and agency	eCourtDate Super Admin, with the agency

Run Part 2 against the agency's staging agency first, then repeat Steps 5 through 11 for the production agency. See Moving to Production.

Before Starting

Microsoft Entra roles. Registering an application requires the Application Administrator or Cloud Application Administrator role, unless the tenant allows all users to register applications. Granting admin consent for a Microsoft Graph application permission requires the Privileged Role Administrator or Global Administrator role.

eCourtDate access. Creating and editing integrations requires a Super Admin user in the eCourtDate Console.

Microsoft cloud. Identify the cloud the tenant belongs to. A tenant whose administrators sign in to the Azure portal at portal.azure.us is GCC High or DoD. A tenant whose administrators sign in at portal.azure.com is Worldwide, which includes commercial and Microsoft 365 GCC tenants.

Agency organizations. Audience rules fill organizations that already exist in the eCourtDate agency. Create the organizations the agency wants to target before Step 9.

OpenSSL. Creating a certificate credential in Step 4 uses OpenSSL. It is included with macOS, most Linux distributions, and Git for Windows.

---

Part 1: Microsoft Entra ID

Step 1: Plan the Population, Fields, and Audiences

Client Sync selects users and assigns audiences by Entra group membership, email domain, and directory attributes. Before configuring anything, confirm which of these are reliable in the tenant.

1. In the Microsoft Entra admin center, open Users, then All users, and select Download users to export the user list as a CSV file.
2. In the export, check which attributes are filled in consistently: department, job title, company name, office location, employee type, employee ID, city, state, country, and usage location.
3. Open Groups and note the Entra groups that describe who should be included, who should be excluded, and who belongs to each audience. Both security groups and Microsoft 365 groups work.
4. Agree with the agency on:
   • Who becomes a Client. For example, "members of the All Staff group whose email domain is agency.gov or courts.agency.gov".
   • Who is left out. For example, "members of the Service Accounts group". Service accounts, shared mailboxes, and other accounts that are not people need a group or an attribute value that separates them.
   • Which fields Entra ID manages. The common set is first name, last name, work email, mobile phone, department, and employee type.
   • Which audiences to fill. For each agency organization, the group or attribute value that decides membership. For example, "the Finance organization holds members of the Finance Team group" or "the Main Office organization holds users whose office location is Main Building".
   • What happens when someone leaves. Either leave their Client unchanged, or archive it so messages stop. If archiving, agree on the most Clients one run may archive, as a percentage of synced Clients.
5. Correct missing or inconsistent values in Entra ID before the first run.

Step 2: Register an Application

1. In the Microsoft Entra admin center, open App registrations and select New registration. For a GCC High or DoD tenant, use the Azure portal for US Government at portal.azure.us and open Microsoft Entra ID, then App registrations.
2. Enter a name such as eCourtDate Client Sync.
3. Under Supported account types, choose Accounts in this organizational directory only.
4. Leave Redirect URI empty and select Register.
5. On the application's Overview page, copy the Application (client) ID and the Directory (tenant) ID.

Use a dedicated application for Client Sync so its permissions and credential are managed on their own.

Step 3: Grant Microsoft Graph Permissions

Client Sync uses two Microsoft Graph application permissions:

Permission	Required when
User.Read.All	Always. Reads user profiles.
GroupMember.Read.All	A population condition or audience rule uses an Entra group. Reads group memberships.

1. In the application, open API permissions and select Add a permission.
2. Select Microsoft Graph, then Application permissions.
3. Search for and select User.Read.All. If the plan from Step 1 uses groups, also select GroupMember.Read.All. Select Add permissions.
4. Select Grant admin consent for the tenant name, then Yes.
5. Confirm the Status column shows Granted for each permission.

These are application permissions, not delegated permissions. They let the application read every user profile and group membership in the tenant. The population conditions in eCourtDate decide which of those users become Clients.

Step 4: Create a Credential

Choose one credential type. A certificate is recommended: Microsoft recommends certificates for production applications, and a client secret expires on a fixed date and must be replaced before then.

Option A: Certificate (recommended)

1. On a workstation with OpenSSL, run:

   openssl req -x509 -newkey rsa:2048 -sha256 -days 730 \
     -keyout ecourtdate-client-sync-key.pem \
     -out ecourtdate-client-sync-cert.pem \
     -subj "/CN=eCourtDate Client Sync"

2. Enter a passphrase when OpenSSL prompts for one. The command creates two files:

   • ecourtdate-client-sync-cert.pem: the public certificate.
   • ecourtdate-client-sync-key.pem: the private key, encrypted with the passphrase.

3. In the application in Entra, open Certificates & secrets, select the Certificates tab, and select Upload certificate.

4. Upload ecourtdate-client-sync-cert.pem and select Add.

5. Note the certificate's expiration date, 730 days from today with the command above, and set a reminder to replace it before then.

The private key never goes to Microsoft. It is entered only in eCourtDate, in Step 6.

Option B: Client secret

1. In the application in Entra, open Certificates & secrets, select the Client secrets tab, and select New client secret.
2. Enter a description, choose an expiration, and select Add.
3. Copy the secret's Value immediately. Microsoft shows it only once. The Secret ID is a different value and is not used.
4. Note the expiration date and set a reminder to replace the secret before then.

Hand Off the Values

Part 2 needs these values. Send them to the eCourtDate Super Admin through a secure channel. Never place a private key, passphrase, or client secret in a support ticket or ordinary email.

Value	Where it came from
Microsoft cloud	Before Starting: Worldwide, GCC High, or DoD
Directory (tenant) ID	Step 2, the application's Overview page
Application (client) ID	Step 2, the application's Overview page
Certificate, private key, and passphrase (Option A)	Step 4, the two .pem files and the passphrase
Client secret value and expiration date (Option B)	Step 4, the secret's Value
Group names	Step 1, the groups for inclusion, exclusion, and audiences
Population, field, and audience decisions	Step 1
Alert email addresses	The people who should be notified when a run fails

---

Part 2: eCourtDate Console

Step 5: Create the Integration

1. Log in to the eCourtDate Console and open Integrations.
2. In the Create Integration form:
   • Name: a name such as Entra Client Sync (Staging). This name is recorded as the creator of every Client the integration creates.
   • Region: the region where the target agency is hosted.
   • Integration: MicrosoftGraph.
3. Select Create. The integration page opens.
4. In Default Agency, choose the agency that should receive the Clients.
5. In Alerts, enter the alert email addresses, separated by commas.
6. Select Save changes at the top of the page.

The integration page shows these cards, from top to bottom: General, Connection, Field Mapping, Audiences, Replace credential, and Synchronization Status. Save changes saves the General, Connection, Field Mapping, and Audiences cards together. The Replace credential and Synchronization Status cards have their own buttons.

Step 6: Connect to Entra ID

1. In the Connection card, enter:
   • Microsoft cloud: Worldwide (includes Microsoft 365 GCC), GCC High, or DoD.
   • Directory (tenant) ID: the tenant GUID. A domain name is not accepted.
   • Application (client) ID: the application GUID.
2. Select Save changes.
3. Scroll to the Replace credential card and choose the Credential type.
4. For Certificate (recommended):
   • Paste the full contents of ecourtdate-client-sync-cert.pem into Certificate (PEM).
   • Paste the full contents of ecourtdate-client-sync-key.pem into Private key (PEM).
   • Enter the passphrase in Key passphrase.
5. For Client secret:
   • Paste the secret value into Client secret value.
   • Enter the expiration date in Secret expires on.
6. Select Verify and save credential. eCourtDate checks the credential with Microsoft before storing it, then stores it encrypted. It is never shown again.
7. Return to the Connection card and select Test Connection.

A passing test shows "Connected to" followed by the tenant name. The test reads the tenant and one user profile and writes nothing. If the test fails, see Troubleshooting.

Group searches in Step 7 use the saved connection and credential, so complete this step first.

Step 7: Choose Which Users to Sync

The General card decides which directory users become Clients.

1. Set the account settings:
   • Synchronization interval: Every hour (default), Every 4 hours, or Every 24 hours.
   • Default phone country: the two-letter country code used for directory phone numbers that have no country code. The default is US.
   • Disabled directory accounts: Exclude (recommended). A synced user who is later disabled then counts as having left the population.
   • Guest accounts: Exclude (recommended).
2. If any condition or audience rule uses an Entra group, add the group under Directory groups:
   • Type the start of the group's name, or paste its object ID, and select Search groups.
   • Select Add beside the group.
   • In Members that count, choose Direct and nested members (the default, which includes members of groups nested inside it) or Direct members only.
3. Under Only include users where, select Add condition for each rule from Step 1, and choose the Attribute, Condition, and Values.
4. Read the Selected population sentence below the conditions and confirm it describes the intended users.
5. Set the departure settings below the population:
   • When a user leaves the population: Leave the Client unchanged (default) or Archive the Client.
   • Archive at most this share of linked Clients in one run: a whole percentage from 1 to 100. The default is 10%. See Departures.
6. Select Save changes.
7. If a group was added, return to the Connection card and select Test Connection again. The test now also reads a group and confirms the GroupMember.Read.All permission. A passing test says the application can read "user profiles and group memberships".

Each condition compares one attribute. The attribute decides which comparisons are offered:

Attribute	Comparisons	Values
Group membership	is a member of any of, is not a member of any of	Groups checked from the Directory groups list
Email (mail), User principal name (userPrincipalName)	domain is one of, domain is not one of	Email domains, comma separated, such as agency.gov, courts.agency.gov
Department, Job title, Company name, Office location, Employee type, Employee id, Usage location, Country, State, City, and Extension attribute 1 through 15	is, is one of, is not one of	One value for is, or a comma-separated list. Check Ignore case to match regardless of capitalization.

How conditions combine:

• Conditions are combined with AND, and the values within one condition with OR.
• A domain comparison uses the part of the address after the @, exactly. A subdomain such as mail.agency.gov is a different domain from agency.gov.
• A user whose attribute cannot be read is not selected. An empty value counts as "not one of", so a user with an empty department meets "department is not one of Finance".
• With no conditions, every account allowed by the disabled and guest account settings is selected, on every domain in the tenant.

For example, these three conditions select members of the All Staff group with an address on either of two domains, and leave out service accounts:

Attribute	Condition	Values
Group membership	is a member of any of	All Staff
Email	domain is one of	agency.gov, courts.agency.gov
Group membership	is not a member of any of	Service Accounts

Up to 50 directory groups can be added. Only groups that a condition or audience rule uses are read, in full, on every run.

Departures

A user leaves the population when a complete run no longer finds them: the user was deleted or disabled in Entra ID, or no longer meets the population conditions. With Archive the Client selected, Client Sync archives that user's Client at the end of the run. Archiving stops messages to the Client and keeps its history. Nothing is deleted.

Safeguards:

• Complete runs only. A run that did not read every page of users and every group it uses archives nothing.
• Unreadable values. A user excluded only because a condition's attribute could not be read has not left and is not archived.
• Departure limit. When more Clients would be archived in one run than the limit allows, none are archived, and the run ends as Completed with errors with a message such as "5 Clients would have been archived, more than the 10% limit of 1; none were." The limit is the chosen percentage of Clients linked before the run, rounded down, and never less than one.
• Returning users. When a user whose Client Client Sync archived is selected again, a later run restores the Client and updates it.

Organization memberships of an archived Client are left as they are.

Step 8: Map Fields

1. In the Field Mapping card, select Add suggested rows. This adds:

   Entra attribute	Client field	Transforms	Update policy
   First name (givenName)	First name	Trim	Replace
   Last name (surname)	Last name	Trim	Replace
   Email (mail)	Email	Trim, Lowercase	Replace
   Mobile phone (mobilePhone)	Phone	Phone number	Replace
   Department (department)	Group	Trim	Replace
   Employee type (employeeType)	Type	Trim	Replace
   Preferred language (preferredLanguage)	Language	Language code	Fill if empty

2. Remove any row for a field Entra ID should not manage, using the remove button at the end of the row.

3. Add a row for any other field from Step 1 with Add row, and choose its Entra attribute, Client field, Transforms, Update policy, and When the directory value is empty setting.

4. Select Save changes. The page lists any mapping errors to fix before saving.

Common adjustments:

• Mobile numbers are not kept in Entra ID. Map Business phones (businessPhones) to Phone with the transforms First listed value, then Phone number.
• The agency edits Status in eCourtDate. Do not map Status with Replace, because each run puts the directory value back. Use Fill if empty or leave Status unmapped.
• A field should be set once and then left to the agency. Use Fill if empty for that row.

The full list of attributes, Client fields, transforms, and rules is in Field Mapping Reference.

Step 9: Set Up Audiences

Audiences place synced Clients in the agency's organizations, which bulk messages can target. Skip this step if the agency does not target messages by organization.

1. In the Audiences card, select Add rule.
2. Choose the Organization the rule fills.
3. Choose the Attribute, Condition, and Values, using the same comparisons as population conditions in Step 7.
4. Repeat for each organization from Step 1. An organization can have several rules.
5. Select Save changes.
6. If a rule uses a group that no condition used before, select Test Connection again so the group permission is confirmed.

A synced Client is in an organization when any rule for that organization holds. For example:

Organization	Attribute	Condition	Values
Finance	Group membership	is a member of any of	Finance Team
Main Office	Office location	is one of	Main Building, Main Annex
Main Office	City	is	Example City

Every organization named in a rule is managed by the directory. On each run, Client Sync adds a synced Client to the organization when a rule holds and removes it when none does, including memberships an administrator added by hand. When a rule's attribute cannot be read for a user, that user's membership is left as it is. Clients added to eCourtDate another way, and organizations no rule names, are never changed.

The Organization list shows the agency's organizations that are not deleted or archived. If the list is empty, create the organizations in the agency first. Up to 100 audience rules can be added.

Step 10: Preview and Enable

1. In the Field Mapping card, select Preview sample. eCourtDate reads 20 directory users with the saved settings and shows what a run would do to each one, without writing anything.

2. Review the sample:

   • Create rows show the values a new Client would receive. Confirm names, email addresses, and phone numbers look right.
   • Groups and Organizations show the directory groups each user belongs to and the organizations the user would be in.
   • Not selected rows are users the population settings leave out. Confirm none of them should be included.
   • Skipped rows show a value that breaks a rule. Fix the value in Entra ID or adjust the mapping.

   Departures cannot be previewed from a sample, because a user leaves only when a complete run no longer finds them. The run history shows how many Clients each run archived and restored.

3. In the Synchronization Status card, check Before this integration can be enabled. It lists anything still missing.

4. Check the acknowledgement. It matches the departure setting: I understand this integration creates and updates Clients and leaves departed users' Clients unchanged, or I understand this integration creates and updates Clients and archives the Clients of users who leave the population.

5. Select Enable synchronization.

The first run starts within five minutes.

Step 11: Verify the First Run

1. Wait for the Synchronization Status card to show the first run as Succeeded or Completed with errors. The card refreshes while a run is in progress.
2. Compare the created count with the expected number of users.
3. Open several new Clients in the agency and confirm the names, work email, work phone, and other mapped fields.
4. Confirm no guest, disabled, or service accounts were created.
5. If departures are archived, confirm the departed and archived count is zero or matches the users expected to leave.
6. If audiences are set up, compare the organization memberships added count with the expected numbers, and open each audience organization to confirm its members.
7. If failed is above zero, see A run reports failed users.

Moving to Production

After the staging integration is verified:

1. Repeat Steps 5 through 11 with a new integration, choosing the production agency as the Default Agency, the full population in Step 7, and the production agency's organizations in Step 9.
2. Use the same Microsoft cloud, tenant ID, application ID, and credential as staging. One application registration serves both integrations.
3. Keep the staging integration enabled with a small test population for testing future changes, or disable it.

Each integration writes to one agency. Only one integration can be enabled for the same agency and tenant at a time.

---

Operating Client Sync

Monitoring

The Synchronization Status card shows whether synchronization is enabled, the interval, the last attempted run, the last successful run, the next scheduled run, and the last 20 runs. Each run shows Clients created, updated, unchanged, failed, and in conflict, the organization memberships added and removed, and the Clients departed and archived or restored.

When a run fails or completes with errors, eCourtDate emails a summary with counts to the Alerts addresses. The summary contains no directory data. eCourtDate support also monitors integrations for repeated failures and overdue runs.

Client Sync reads every group it uses before it writes anything. If a group cannot be read, the run fails before any Client or membership changes, so a partial read never narrows or widens the population or the audiences. A run that fails or is cancelled archives nothing.

Replacing the credential

Replace the certificate or client secret before it expires. The current credential stays in use until the replacement passes its check, so runs are not interrupted.

1. In Entra, create a new certificate or client secret for the same application, following Step 4.
2. In the eCourtDate integration, enter it in the Replace credential card and select Verify and save credential.
3. Select Test Connection.
4. In Entra, delete the old certificate or secret from Certificates & secrets.

People who leave or change roles

What happens when a person is disabled or deleted in Entra ID, or moves out of the population, depends on When a user leaves the population:

• Leave the Client unchanged. The Client stays active in eCourtDate. The agency updates or archives it.
• Archive the Client. The next complete run archives the Client, within the departure limit. See Departures.

When a person changes groups or attributes in Entra ID and is still in the population, the next run updates their audience memberships to match.

Restoring and archiving by hand:

• A Client that Client Sync archived and an administrator restores stays restored. Client Sync does not archive it again while the user is still gone.
• A Client that Client Sync archived is restored automatically when the user returns to the population.
• A Client that an administrator archives or deletes while the user is still in the population becomes a conflict. Client Sync does not restore or recreate it.

Changing settings

• Population, mappings, or audiences. Edit the General, Field Mapping, or Audiences card and select Save changes. The next run applies the change.
• Departure setting. Changing When a user leaves the population on an enabled integration takes effect at the next run. Switching to Leave the Client unchanged does not restore Clients that are already archived.
• Adding a group. After adding a group to a condition or audience rule, select Test Connection again before the next enable.
• Removing a mapping row. Client Sync stops managing that field. The field keeps its current value.
• Application (client) ID. It can be changed to another application in the same tenant without affecting existing Clients. Run Test Connection after the change.
• Default Agency, Microsoft cloud, and tenant ID. These lock after the first Client is linked. To sync a different agency or tenant, create a new integration.

Running on demand

Runs follow the synchronization interval. To start a run sooner, select Disable synchronization, then Enable synchronization. A run starts within five minutes. Disabling stops future runs, and a run in progress stops at its next page of results.

---

Field Mapping Reference

Entra attributes

Group	Attributes
Identity	id, userPrincipalName, accountEnabled, userType, createdDateTime, onPremisesSamAccountName
Name	displayName, givenName, surname
Work contact	mail, mobilePhone, businessPhones (a list)
Organization	jobTitle, department, companyName, officeLocation
Location	streetAddress, city, state, postalCode, country, usageLocation, preferredLanguage
Employee record	employeeId, employeeType
On-premises extension attributes	onPremisesExtensionAttributes.extensionAttribute1 through extensionAttribute15
Directory extensions	Any directory extension attribute, typed by its full name in the form extension_<app id>_<name>

The Console lists these attributes by name, such as First name for givenName and Mobile phone for mobilePhone. The directory id links each user to their Client automatically and does not need a mapping row. Group membership is used by conditions and audience rules and is not a mapping source.

Client fields

Client field	Maximum length	Can be cleared	Notes
First name	36	Yes
Middle name	30	Yes
Last name	40	Yes
Full name	75	No	Filled in from first and last name when not mapped.
Aliases	30	Yes
Email	55	No	Stored as a work email Contact on the Client.
Phone	55	No	Stored as a work phone Contact on the Client. Requires the Phone number transform.
Group	24	Yes	A short label, for example the department. This Client field is separate from Entra groups.
Type	24	Yes	A short label, for example the employee type.
Status	36	No	Use a value that matches one of the agency's client statuses.
Client reference	36	No	Map this field only when the directory is the source of the agency's client reference.
Language	5	No	A two-letter code such as en or es. New Clients default to en when Language is not mapped.
Notes	255	Yes

If any mapped value for a user breaks a rule, such as a value longer than the field's maximum length, none of that user's changes are written in that run, audience memberships included, and the user is counted as failed.

Transforms

Transform	Effect
Trim	Removes spaces before and after the value.
Uppercase	Converts the value to uppercase.
Lowercase	Converts the value to lowercase. Recommended for email addresses.
Title case	Capitalizes the first letter of each word.
First listed value	For list attributes such as businessPhones: uses the first entry that is not blank. Required first on a list attribute.
Phone number	Stores the number in international format, using the default phone country when the number has no country code. Required for the Phone field.
Language code	Turns a locale such as en-US into the two-letter code en.

Update policy

Policy	Effect
Replace	Entra ID controls the field. An edit made in eCourtDate is replaced with the directory value at the next run.
Fill if empty	The directory value is written only when the field is empty. A value already in eCourtDate is kept.

When the directory value is empty

Option	Effect
Keep the existing value (default)	The eCourtDate field stays unchanged.
Clear the field	The eCourtDate field is emptied. Available only for fields that can be cleared.

Mapping rules

Saving the Field Mapping card checks that:

• At least one row exists.
• Each Client field is mapped only once.
• At least one of First name, Last name, Full name, or Client reference is mapped.
• The Phone field has the Phone number transform.
• A list attribute has the First listed value transform.
• Clear the field is used only on a field that can be cleared.

The card also shows warnings, which do not block saving, when userPrincipalName is mapped to Email, when Client reference is mapped, and when Status values do not match the agency's client statuses.

Record matching

Each Client is linked to its directory user by the Entra object id, together with the agency, Microsoft cloud, and tenant. As a result:

• A change of name, email address, or domain in Entra ID updates the existing Client and does not create a second one.
• Client Sync updates only Clients it created. A Client entered by hand or imported another way is not matched to a directory user.
• A new credential, a new application ID in the same tenant, or a new integration for the same agency and tenant keeps the existing links.

Preview labels

Label	Meaning
Create	The user is selected and has no linked Client. A run creates one.
Update	The user is selected and has a linked Client. A run applies the mapped values and audience memberships.
Conflict	The user's linked Client was deleted in eCourtDate, or archived by an administrator. A run does not restore or recreate it.
Skipped	A value breaks a rule, such as a value longer than the field's maximum length.
Not selected	The user does not meet the population settings or conditions.

The preview shows the values the directory provides. It does not compare them with the Client's current values in eCourtDate. The preview reads up to 20 pages of members for each group; a larger group shows an error in the preview, and runs still read every member.

Run statuses

Status	Meaning
Queued	The run is waiting to start.
Running	The run is in progress.
Succeeded	The run finished and every selected user was processed.
Completed with errors	The run finished, and one or more users failed, or departures were held back by the departure limit.
Failed	The run could not complete. Nothing was changed after the point of failure.
Cancelled	The run was stopped, for example because synchronization was disabled.

Troubleshooting

Test Connection or a run fails with a permissions error

The application is missing a Microsoft Graph application permission, or admin consent has not been granted. The message names the missing permission: User.Read.All for user profiles, or GroupMember.Read.All for group memberships. In Entra, open the application's API permissions and confirm each permission is listed with type Application and status Granted. See Step 3.

Enabling asks to run Test Connection again for group memberships

A condition or audience rule uses a group, and the last passing test was run before the group was added. Select Test Connection so it confirms the GroupMember.Read.All permission.

A directory group used by this integration no longer exists

A group in the Directory groups list was deleted in Entra ID. Runs fail until the group is removed from every condition and audience rule that uses it. Remove it from the Directory groups list as well, then select Save changes.

A group has too many members to preview

The preview reads a limited number of members for each group. Runs are not affected and read every member. Preview with a condition on a smaller group, or rely on the first run's counts.

Microsoft rejected the application credentials

The application (client) ID does not match the credential, or the credential is wrong. For a client secret, confirm the secret Value was entered, not the Secret ID. For a certificate, confirm the uploaded certificate and the private key come from the same OpenSSL command.

The certificate or client secret has expired

Create a new credential and replace it. See Replacing the credential.

The application (client) ID was not found in this tenant

The application ID is wrong, or the application is registered in a different tenant than the tenant ID entered.

The tenant ID was not found in the selected Microsoft cloud

The tenant ID is wrong, or the Microsoft cloud setting does not match the tenant. A GCC High or DoD tenant requires GCC High or DoD. A commercial or GCC tenant requires Worldwide (includes Microsoft 365 GCC).

Microsoft Graph does not recognize a requested property

A condition or mapping row names an attribute the tenant does not have, such as a directory extension with a mistyped name. Correct or remove the row.

Microsoft Graph is rate limiting requests, or could not be reached

The run stops, and the next scheduled run tries again. If the problem continues for several runs, open a support ticket.

Test Connection shows "Settings changed since"

The connection settings changed after the last test. Select Save changes, then Test Connection.

Enable synchronization is not available

The Before this integration can be enabled list in the Synchronization Status card names each missing item. Common items are a Test Connection that has not passed since the connection settings or groups changed, an audience organization that was deleted or archived, and another enabled integration for the same agency and tenant.

A run reports that Clients would have been archived

The run found more departures than the departure limit allows, so it archived none. The message reads, for example, "5 Clients would have been archived, more than the 10% limit of 1; none were." Check the directory for an unintended change, such as an emptied group, a renamed department, or a changed email domain, and correct it. If the departures are expected, such as after a reorganization, raise Archive at most this share of linked Clients in one run for one run, then set it back.

A run reports failed users

A failed user has a value that breaks a rule, such as a value longer than the Client field allows, or no name. Select Preview sample to see the reason for sampled users. Correct the value in Entra ID or adjust the mapping, and the next run tries again.

A run reports conflicts

The Client linked to a directory user was deleted in eCourtDate, or archived by an administrator while the user was still in the population. Client Sync does not restore or recreate it, and the user stays a conflict on later runs, even if the Client is restored. To sync that person again, open a support ticket. Clients archived by Client Sync as departures are not conflicts.

Users are missing from eCourtDate

Read the Selected population sentence and select Preview sample. Check the user's group memberships and email domain against the conditions. Users whose attribute cannot be read are not selected, and disabled and guest accounts are excluded by default.

A Client added to an organization by hand is removed

The organization is named in an audience rule, so Client Sync manages its membership for synced Clients. Add the person to the matching Entra group, or change the attribute value the rule uses, instead of adding the membership by hand.

An edit in eCourtDate keeps changing back

The field is mapped with Replace, so each run restores the directory value. Change the value in Entra ID, or change the row's policy to Fill if empty.

For anything else, open a support ticket in the Console using the Help button in the bottom-right corner.

Frequently Asked Questions

Which Microsoft permissions does Client Sync need? User.Read.All always, and GroupMember.Read.All when a condition or audience rule uses an Entra group. Both are application permissions with admin consent.

Is a certificate or a client secret better? A certificate. Microsoft recommends certificates for production applications, and a client secret expires on a fixed date.

Does Client Sync support GCC High and DoD tenants? Yes. Choose GCC High or DoD as the Microsoft cloud. Microsoft 365 GCC tenants use Worldwide (includes Microsoft 365 GCC).

Can the population be limited to a security group? Yes. Add the group under Directory groups and add the condition "is a member of any of" that group. Security groups and Microsoft 365 groups both work.

Do nested groups count? By default, yes. Each group in the Directory groups list is set to Direct and nested members or Direct members only.

Can a tenant with several email domains be synced? Yes. Without a domain condition, every domain in the tenant is included. To limit the domains, add a condition on Email with domain is one of and list each approved domain.

How are audiences used for messaging? Audience rules place synced Clients in agency organizations. Bulk messages that target an organization reach its members.

What happens when a person leaves? With Archive the Client selected, the next complete run archives their Client, which stops messages and keeps its history. With Leave the Client unchanged, the default, the agency updates or archives it.

What if a directory change makes many users leave at once? When a run would archive more Clients than the departure limit allows, it archives none and ends as Completed with errors, and the Alerts addresses are emailed. Correct the directory, such as an emptied group or a changed domain, and the next run proceeds normally.

Is a returning user's Client restored? Yes, when Client Sync archived it. The next run that selects the user restores and updates the Client.

If a person's email address changes, is a duplicate Client created? No. Clients are linked by the Entra object ID, which stays the same when a name, email address, or domain changes.

Does creating a Client send a message? No. Client Sync does not trigger auto messages.

Can agency staff edit a synced Client? Yes. A field mapped with Replace returns to the directory value at the next run. A field mapped with Fill if empty, or not mapped, keeps the edit. Contacts the agency adds to a synced Client are never changed. Memberships in organizations named by audience rules follow the directory.

Can staging and production use the same application registration? Yes. Both integrations use the same tenant ID, application ID, and credential, and each writes to its own agency.

Related

• Console: where integrations are configured.
• Common Concepts: Clients, Contacts, and agencies.
• Staging and Production: testing an integration before going live.
• Clients API: filtering Clients by organization.
• Integrations: other pre-built integrations.