accessReviewScheduleDefinition resource type
Namespace: microsoft.graph
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Note
This is the recommended API for access reviews. The previous version of the access reviews API is deprecated.
Represents the scheduling of a Microsoft Entra access review.
An accessReviewScheduleDefinition contains a list of accessReviewInstance objects. Each recurrence of the schedule definition creates an instance. Instances also represent each unique resource being reviewed. If a schedule definition reviews multiple resources (including multiple groups), each resource has a unique instance per each recurrence. In the case of a one-time review, only one instance is created per resource.
Methods
| Method | Return Type | Description |
|---|---|---|
| List | accessReviewScheduleDefinition collection | Lists every accessReviewScheduleDefinition. Doesn't include associated accessReviewInstance objects in the results. |
| Get | accessReviewScheduleDefinition | Get an accessReviewScheduleDefinition with a specified id. Doesn't include associated accessReviewInstance objects in the results. |
| Create | accessReviewScheduleDefinition | Create a new accessReviewScheduleDefinition. |
| Delete | None. | Delete an accessReviewScheduleDefinition with a specified id. |
| Update | None. | Update properties of an accessReviewScheduleDefinition with a specified id. |
| Filter by current user | accessReviewScheduleDefinition collection | Retrieves all definitions for which the calling user is a reviewer on one or more instances. |
Properties
| Property | Type | Description |
|---|---|---|
| additionalNotificationRecipients | accessReviewNotificationRecipientItem collection | Defines the list of additional users or group members to be notified of the access review progress. |
| createdBy | userIdentity | User who created this review. Read-only. |
| createdDateTime | DateTimeOffset | Timestamp when the access review series was created. Supports $select. Read-only. |
| descriptionForAdmins | String | Description provided by review creators to provide more context of the review to admins. Supports $select. |
| descriptionForReviewers | String | Description provided by review creators to provide more context of the review to reviewers. Reviewers see this description in the email sent to them requesting their review. Email notifications support up to 256 characters. Supports $select. |
| displayName | String | Name of the access review series. Supports $select and $orderby. Required on create. |
| fallbackReviewers | accessReviewReviewerScope collection | This collection of reviewer scopes is used to define the list of fallback reviewers. These fallback reviewers will be notified to take action if no users are found from the list of reviewers specified. This could occur when either the group owner is specified as the reviewer but the group owner doesn't exist, or manager is specified as reviewer but a user's manager doesn't exist. See accessReviewReviewerScope. Replaces backupReviewers. Supports $select. NOTE: The value of this property will be ignored if fallback reviewers are assigned through the stageSettings property. |
| id | String | The feature-assigned unique identifier of an access review. Supports $select. Read-only. |
| instanceEnumerationScope | accessReviewScope | This property is required when scoping a review to guest users' access across all Microsoft 365 groups and determines which Microsoft 365 groups are reviewed. Each group becomes a unique accessReviewInstance of the access review series. For supported scopes, see accessReviewScope. Supports $select. For examples of options for configuring instanceEnumerationScope, see Configure the scope of your access review definition using the Microsoft Graph API. |
| instances | accessReviewInstance collection | Set of access reviews instances for this access review series. Access reviews that don't recur will only have one instance; otherwise, there's an instance for each recurrence. |
| lastModifiedDateTime | DateTimeOffset | Timestamp when the access review series was last modified. Supports $select. Read-only. |
| reviewers | accessReviewReviewerScope collection | This collection of access review scopes is used to define who are the reviewers. The reviewers property is only updatable if individual users are assigned as reviewers. Required on create. Supports $select. For examples of options for assigning reviewers, see Assign reviewers to your access review definition using the Microsoft Graph API. NOTE: The value of this property will be ignored if reviewers are assigned through the stageSettings property. |
| scope | accessReviewScope | Defines the entities whose access is reviewed. For supported scopes, see accessReviewScope. Required on create. Supports $select and $filter (contains only). For examples of options for configuring scope, see Configure the scope of your access review definition using the Microsoft Graph API. |
| stageSettings | accessReviewStageSettings collection | Required only for a multi-stage access review to define the stages and their settings. You can break down each review instance into up to three sequential stages, where each stage can have a different set of reviewers, fallback reviewers, and settings. Stages are created sequentially based on the dependsOn property. Optional. When this property is defined, its settings are used instead of the corresponding settings in the accessReviewScheduleDefinition object and its settings, reviewers, and fallbackReviewers properties. |
| settings | accessReviewScheduleSettings | The settings for an access review series, see type definition below. Supports $select. Required on create. |
| status | String | This read-only field specifies the status of an access review. The typical states include Initializing, NotStarted, Starting, InProgress, Completing, Completed, AutoReviewing, and AutoReviewed. Supports $select, $orderby, and $filter (eq only). Read-only. |
| backupReviewers (deprecated) | accessReviewReviewerScope collection | This collection of reviewer scopes is used to define the list of fallback reviewers. These fallback reviewers are notified to take action if no users are found from the list of reviewers specified. This could occur when either the group owner is specified as the reviewer but the group owner doesn't exist, or manager is specified as reviewer but a user's manager doesn't exist. Supports $select. Note: This property has been replaced by fallbackReviewers. However, specifying either backupReviewers or fallbackReviewers automatically populates the same values to the other property. |
Relationships
| Relationship | Type | Description |
|---|---|---|
instances |
accessReviewInstance collection | If the accessReviewScheduleDefinition is a recurring access review, instances represent each recurrence. A review that doesn't recur will have exactly one instance. Instances also represent each unique resource under review in the accessReviewScheduleDefinition. If a review has multiple resources and multiple instances, each resource has a unique instance for each recurrence. |
JSON representation
The following JSON representation shows the resource type.
{
"@odata.type": "#microsoft.graph.accessReviewScheduleDefinition",
"id": "String (identifier)",
"displayName": "String",
"createdDateTime": "String (timestamp)",
"lastModifiedDateTime": "String (timestamp)",
"status": "String",
"descriptionForAdmins": "String",
"descriptionForReviewers": "String",
"createdBy": {
"@odata.type": "microsoft.graph.userIdentity"
},
"scope": {
"@odata.type": "microsoft.graph.accessReviewScope"
},
"reviewers": [
{
"@odata.type": "microsoft.graph.accessReviewReviewerScope"
}
],
"fallbackReviewers": [
{
"@odata.type": "microsoft.graph.accessReviewReviewerScope"
}
],
"backupReviewers": [
{
"@odata.type": "microsoft.graph.accessReviewReviewerScope"
}
],
"instanceEnumerationScope": {
"@odata.type": "microsoft.graph.accessReviewScope"
},
"stageSettings": [
{
"@odata.type": "microsoft.graph.accessReviewStageSettings"
}
],
"settings": {
"@odata.type": "microsoft.graph.accessReviewScheduleSettings"
},
"additionalNotificationRecipients": [
{
"@odata.type": "microsoft.graph.accessReviewNotificationRecipientItem"
}
]
}