Validation rules and descriptions
Matching and validation rules by data type
| Data Type | Matching Rule | Validation Rule | Value Stored |
|---|---|---|---|
| Unique ID * | Case Sensitive | As received | |
| ENUM ** | Case Insensitive | Match to lower case | As camelCase |
| String | Case Sensitive | As received | |
| To lower case | RFC 5532 (3.4.1) | To lower case | |
| Date or DateTime | ISO8601 | ISO8601 | ISO8601 |
| Phone | E.164 | E.164 | As received |
| Boolean | Case Insensitive | Match to ‘true’ or ‘false’ | To lower case |
*The record is unique across all records. Globally unique identifier, though it may or may not take the form of a universal unique identifier (UUID).
** Leading zeros ‘0’ missing on incoming value for Grade Level ENUM, for example ‘1’, will match defined List of Value (ENUM) ‘01’ and will be stored as ‘01’.
** For more information default ENUM values, see the Default List of Values.
Expect phone and sms fields to be formatted based on the E.164 standard where the plus character is used and succeeded by the phone number, or rather the plus character followed by country code, area code, telephone prefix, and line number. (Example: +1234567890)
Rules and Descriptions
| Rule Name | Rule Description | Status | Rule Action | Friendly Message Example | Raised From (Source or Writing to Microsoft Entra ID) |
|---|---|---|---|---|---|
| Internal Application Error | An unexpected error occurred. | Catastrophic Error | Stops data run | There was an application error when trying to process: {error} | Connect data & Manage data |
| File Not Found | A required file couldn't be found. | Catastrophic Error | Stops data run | Unable to find {expectedFileName} in the path: {Path}. Please check the path of {Name} to ensure {expectedFileName} exists or the name of the file is {expectedFileName} and rerun sync. | Connect data |
| Operation Canceled | A problem occurred during the data run that required it to be canceled. | Catastrophic Error | Stops data run | The operation has been canceled with the message: {cancelMessage} | Connect data |
| Header Doesn't Exist | To ensure that a properly formatted file is being sent for processing that contains the defined file headers. | Catastrophic Error | Stops data run | Unable to find {expectedHeaderName} in {fileName}. Please correct extract to add or ensure it reads as {expectedHeaderName}. Upload corrected files and rerun sync. | Connect data |
| Duplicated Column In Header | To ensure that a properly formatted file is being sent for processing that contains the defined file header and not multiple of a same header(s). | Catastrophic Error | Stops data run | Two or more {expectedHeaderName} were found in {fileName}. Please correct extract, upload corrected files, and rerun sync. | Connect data |
| Invalid File Format | When non supported files or a folder is present in compressed file (zip). | Catastrophic Error | Stops data run | Archive Validation Failed. Non supported file {fileInArchive} found in archive {archiveName}. | Connect data |
| Duplicate Files Found | When archive contains a file that is also uploaded outside archive. Example: users.csv and users.zip are uploaded and users.zip also contains users.csv. | Catastrophic Error | Stops data run | Archive Validation Failed. Duplicate {fileInArchive} found in archive {archiveName} and outside archive. | Connect data |
| Duplicate File Found | When duplicate files are found in multiple archives. Example: users.zip and relationship.zip are uploaded and relationship.zip also contains users.csv. | Catastrophic Error | Stops data run | Archive Validation Failed. Duplicate {fileInArchive} found in archives {archiveName1}, {archiveName2}. | Connect data |
| Cross Reference Mapping Not Found | Validates that linked data is found across the associated data being provided (example: missing organization for a user, missing section for enrollments). | Error | Removes record from posting | A {entityType} record couldn't be found for {record} from source [{fileName}/{apiEndPoint}]. Confirm the {entityType} sourcedId and {record} sourcedId is correct or update data in source system and rerun sync. | Connect data & Manage data |
| Optional Cross Reference Mapping Not Found | Validates that linked data is found across the associated data being provided (example: missing organization for a user, missing section for enrollments). | Warning | Removes value from record, sends record for posting | Invalid optional reference value {value} in field {field} for {entityType} was found for {record} and the value was dropped from the record to proceed with processing. Confirm the {entityType} sourcedId and {record} sourcedId is correct or update data in the source system and rerun sync. | Connect data |
| Date Time Format Error | To ensure data values being passed have the proper format (ISO8601). | Error | Removes record from posting | The {record} in {field} from source [{fileName}/{apiEndPoint}] has a date that isn't in the proper format: 'YYYY-MM-DD'. | Connect data & Manage data |
| Missing Required Data | To detect missing value in a required field for a record. | Error | Removes record from posting | A required value for {record} is missing in field name: {field} from source [{fileName}/{apiEndPoint}] to create the record. | Connect data & Manage data |
| Format Value Error | To ensure data being passed in a field matches the defined formatting. Also see matching and validation rules by data type. | Error | Removes record from posting | The {record} found in {field} from source [{fileName}/{apiEndPoint}] doesn't have a properly formatted value for {field}. | Connect data & Manage data |
| Parse Error | To ensure for each record we're able associate the data in the correct column. Records may be flagged due to single commas, carriage returns found, or missing quotes. | Error | Removes record from posting | Unable to parse [if api: {apiEndpoint}] from source [{fileName}/{apiEndPoint}] to find data in columns. Ensure that the delimiter in the file is a single comma (,) and carriage returns in fields aren't permitted. Fields containing commas and double-quotes must be enclosed in double-quotes. If double-quotes are used to enclose a field, then a double-quote appearing inside the field must be escaped by preceding it with another double-quote. | Connect data |
| Max Field Length Constraint Violated | To ensure data being passed doesn't exceed the field length resulting in missing data. | Error | Removes record from posting | The value provided for {field} in {record} exceeds the maximum supported length of {length} characters. | Connect data |
| Invalid Or Missing Reference Code | Identifies if a required field’s reference value [Enum] being passed for a record isn't found to associate the record to. | Error | Removes record from posting | The value {refValue} for {field} in {record} isn't found in {refCodeEntity}. Please correct the source system. | Connect data |
| Invalid Optional Reference Code | Identifies if an optional field’s reference value [Enum] being passed for a record isn't found to associate the record to. | Warning | Removes value from record, sends record for posting | The value {refValue} for {field} in {record} isn't found in {refCodeEntity}. Please correct the source system. | Connect data |
| Optional Data Missing Corresponding Required Value | To ensure that if a record is passing a value for optional data that any additional associated data that now requires a value to also be present is also being supplied. | Warning | Removes value from record, sends record for posting | A value was provided in an optional field for {record} but is missing a corresponding value in associated field to successfully post the data. | Connect data |
| Circular Reference | To ensure that if a record has a parent association that a circular reference hasn't been supplied. | Warning | Removes value from record, sends record for posting | {entityType} {entityId} is linked in a circular reference with {entityType}(s) {entityList}. Value for {entityParentIdField} will be dropped from the record to proceed with processing. | Connect data |
| User Mapping Identifier Not Found | To ensure a value exists based on the user identity rules configured. | Error | Removed record from posting | User mapping identifier {identifierType} wasn't found for user {record}. | Connect data |
| User Mapping Multiple Matches Found | If multiple Microsoft Entra accounts are found to be a match for this user, only the first AAD account will be used for the match. Additional matches will be dropped. | Error | Removes secondary records from posting | User {record} with mapping identifier {identifierType}={value} found multiple matches in Microsoft Entra ID. Only the first match found will be used, see Microsoft Entra ObjectId {AadObjectId}. | Connect data |
| User Mapping Conflicting Matches Found | To prevent automated association of a different user to an existing and matched Microsoft Entra account. | Error | Removes record from posting | User {record} with mapping identifier {identifierType}={value} is matched to an existing mapped Microsoft Entra ObjectId {AadObjectId}. The existing match found will be used and this match will be skipped. | Connect data |
| User Match to Microsoft Entra ID Not Found | Notifies that a user record provided wasn't able to find a match to an Microsoft Entra User based on the user / identify matching rules configured. | Warning | Record not matched to Microsoft Entra ID | User {record} with mapping identifier {identifierType}={value} wasn't matched to any Microsoft Entra User. This could be that the value supplied is incorrect from the Source System based on the configured User identity rules, or Azure Active Directory Sync hasn't yet added the user prior to the latest run. | Connect data |
| Missing User Association | Notifies that a user record is provided but isn't associated as a Student or Staff role to an organization or Contact role to a Student. | Warning | Removes record from posting | User {record} from source [{fileName}/{apiEndPoint}] is missing either an Organization & Role association data or Contact Relationship association data. If this is a valid user, please update the source data to provide the proper Organization & Role or Contact Relationship associations. | Connect data |
| Primary Role Not Specified | Notifies that multiple role records are provided for a user but one of them isn't marked as the Primary role. | Warning | Record is added as received | Multiple role records from source [{fileName}/{apiEndPoint}] for User {record} was found without denoting one of the roles as the Primary role for the same organization. We recommend specifying one of this user's roles as Primary from the source | Connect data |
| Multiple Primary Roles Specified | Notifies that multiple role records are provided and multiple are marked as the Primary role | Warning | Record is added as received | Multiple role records from source [{fileName}/{apiEndPoint}] for User {record} was found and defined as the Primary role for the same organization. We recommend specifying one of this user's roles as Primary from the source. | Connect data |
| User Role Missing Role Group Association | Identifies that a user's was provided with a valid role but the role isn't associated to a Role Group, as such not sure what matching rules should be used. | Error | Removes record from posting | User {record} from source [{fileName}/{apiEndPoint}] is associated to a valid role {value} but the role isn't associated to a Role Group. You need to update your List of Values to associate the {value} to a Role Group. | Connect data |
| General Post Data Error | When submitting the record an error was returned. | Error | Removes record from posting | Unable to add {record} due to {error}. Please check or update the source system to correct. | Connect data |
| UPN Format Error | Notifies that the User Principal Name used or generated isn't properly formatted to meet Microsoft Entra requirements. | Error | Record not posted to Microsoft Entra ID | The user record: {record} doesn't have a properly formatted User Principal Name: {value} to create a user object in Microsoft Entra ID. Please correct data for this user’s record in the source system based on the fields selected for the Username configuration. | Manage data |
| Microsoft Entra Invalid Property Value | Notifies invalid characters were present why trying to write to Microsoft Entra ID | Error | Record not posted to Microsoft Entra ID | Can't create or update {record} in Active Directory due to one or more invalid properties. Check the values for the {record} in {field} to ensure they contain only alpha numeric characters and no whitespace and fewer than 256 characters. Please correct data in source system or activate setting for Replace special characters in {FlowName}. | Manage data |
| Missing Dependent License | Notifies a dependent license hasn't been assigned to the record. | Error | Record not posted to Microsoft Entra ID | A dependent license isn't currently assigned to the {record}. For example - the Classroom license requires that the {record} must already have a license for Exchange Online and SharePoint Online. Address this by assigning the dependent license and rerun sync. | Manage data |
| No Available Licenses | Notifies there were no licenses to assign to the user. | Error | Record not licensed | Failed to assign a license to the {record}. License is either expired or exhausted (All available licenses of this type have been assigned). Remediate by adding more licenses of {licenseType} and rerun sync. | Manage data |
| Last Owner of Group Can't be Removed | Notifies there are no owner records for an existing synced Team Class Group. | Error | Record not removed from Microsoft Entra ID | {record} couldn't be removed from a {teamsType} because a {teamsType} must have at least one owner. Please check or update data in the source system or check filter selections to ensure at least one owner is assigned. | Manage data |
| Resource Size Exceeded | Notifies a record has too many Organizations associations. | Error | Record not posted to Microsoft Entra ID | {record} has been assigned to too many schools (more than 30). Please remove the membership of the {record} from schools that are no longer needed. | Manage data |
| Duplicate Target Entries | Notifies two or more records exist with the same sourceId in Microsoft Entra ID. | Error | Record not posted to Microsoft Entra ID | Two or more records exist with the same sourcedId for {record} in Active Directory. Please identify and remove the incorrect identity. | Manage data |
| No Microsoft Entra Match Found | Notifies the link couldn't be added from the Source to Microsoft Entra ID because the target isn't found in Microsoft Entra ID. | Error | Record not linked to Microsoft Entra ID | {record} can't be updated as no matching entry in Active Directory was found. Verify the identity matching criteria for the Inbound flow. | Manage data |
| Existing Object Found | Notifies there's already a link found for the same sourceId in Microsoft Entra ID. | Error | Record not posted to Microsoft Entra ID | {record} for {entityType} has already been created in the past with the same sourcedId. Please retire or remove old {entityType}. | Manage data |
| Invalid Principal Name Format | Notifies the link couldn't be added due to unexpected format found on the User Principal Name being generated. | Error | Record not linked to Microsoft Entra ID | {record} can't be updated as no matching entry in Active Directory was found. The format of the user principal name is unexpected. | Manage data |
| Can't Sync On-Premise Owned Objects | Notifies the tenant is using Azure Active Directory Sync from an On-Premise to their Microsoft 365 tenant that a change seen for a user value in AAD will not be updated from the Source data. | Error | Record not posted to Microsoft Entra ID | Cannot update properties (such as: first name) for {record} that is syncing from an On-Premise Active Directory. Please make the change in On-Premise Active Directory first. | Manage data |
| Duplicate Security Group Ids | Notifies the tenant that a duplicate Security Group Id was generated after removing special characters that are not allowed in Microsoft Entra ID and cannot create the additional Security Group. | Error | Record not posted to Microsoft Entra ID | Multiple security groups have duplicate identifier values {identifierSource} after special characters were removed for org sourcedId: {identifierValue}. | Manage data |