Merge branch 'main' into users/sitaolu/cloudPcDeviceImage_getSourceImages_doc_update

Author: JarbasHorst

.github/copilot-instructions.md

@@ -2,6 +2,19 @@
 
 You are a content reviewer for Microsoft Graph REST API reference documentation. Use these guidelines to review pull requests (PRs) against the Microsoft Graph documentation standards outlined in the Microsoft Graph Content Development Kit (CDK).
 
+## Additional Documentation Resources
+
+For comprehensive authoring and review guidance, reference these files located in the `.github/prompts/` folder:
+
+- **[author-api-docs.prompt.md](.github/prompts/author-api-docs.prompt.md)**: Complete authoring guidelines for creating and updating Microsoft Graph API reference documentation, including workflows for fresh APIs, promotions, and deprecations.
+- **[review-api-docs.prompt.md](.github/prompts/review-api-docs.prompt.md)**: Detailed review process guidelines that combine authoring best practices with the content standards outlined below.
+
+These files provide in-depth guidance on:
+- Documentation authoring workflows and scenarios
+- Content structure and organization requirements
+- Quality standards and validation processes
+- Common patterns and best practices specific to Microsoft Graph API documentation
+
 ## File Type Classifications
 
 This repository contains several types of files with different review requirements:

.github/prompts/author-api-docs.prompt.md

@@ -1,3 +1,4 @@
+#cSpell:ignore microsoftgraph msgraph hidi CSDL Mooncake
 name: Update cloud support status
 
 on:
@@ -31,7 +32,7 @@ jobs:
     - name: Setup .NET
       uses: actions/setup-dotnet@v4
       with:
-        dotnet-version: 9.x
+        dotnet-version: 10.x
     - name: Build cloud support tool
       working-directory: ./tool
       run: dotnet build --configuration Release
@@ -67,7 +68,7 @@ jobs:
         hidi transform --cs transformed_beta-Mooncake.csdl -o ../openapi/beta/Mooncake.yml --co -f Yaml --sp $Env:SETTINGS
     - name: Run cloud support tool
       env:
-        TOOL: ./tool/src/bin/Release/net9.0/CheckCloudSupport
+        TOOL: ./tool/src/bin/Release/net10.0/CheckCloudSupport
       run: |
         $TOOL --open-api ./openapi/v1.0 --api-docs ./docs/api-reference/v1.0/api --overrides ./docs/api-reference/cloud.api.overrides.json --excludes ./docs/api-reference/cloud.exclusions.json --remove-old-includes
         $TOOL --open-api ./openapi/beta --api-docs ./docs/api-reference/beta/api --overrides ./docs/api-reference/cloud.api.overrides.json --excludes ./docs/api-reference/cloud.exclusions.json --remove-old-includes

.github/prompts/review-api-docs.prompt.md

@@ -1,3 +1,4 @@
+# cSpell:ignore microsoftgraph msgraph bangbang
 name: Generate reference TOC
 
 on:
@@ -42,15 +43,23 @@ jobs:
     - name: Setup .NET
       uses: actions/setup-dotnet@v4
       with:
-        dotnet-version: 8.x
+        dotnet-version: 10.x
     - name: Build TOC generation tool
       working-directory: ./tool
       run: dotnet build --configuration Release
-    - name: Run cloud support tool
+    - name: Generate v1 TOC
+      id: v1_gen
+      continue-on-error: true
       env:
-        TOOL: ./tool/src/bin/Release/net8.0/GenerateTOC
+        TOOL: ./tool/src/bin/Release/net10.0/GenerateTOC
       run: |
         $TOOL --api-docs ./docs/api-reference/v1.0/api --resource-docs ./docs/api-reference/v1.0/resources --mapping ./docs/api-reference/v1.0/toc/toc.mapping.json --terms-override ./docs/api-reference/toc.terms.overrides.json --toc ./docs/api-reference/v1.0/toc.yml --static-toc ./docs/api-reference/v1.0/toc/static-toc.yml
+    - name: Generate beta TOC
+      id: beta_gen
+      continue-on-error: true
+      env:
+        TOOL: ./tool/src/bin/Release/net10.0/GenerateTOC
+      run: |
         $TOOL --api-docs ./docs/api-reference/beta/api --resource-docs ./docs/api-reference/beta/resources --mapping ./docs/api-reference/beta/toc/toc.mapping.json --terms-override ./docs/api-reference/toc.terms.overrides.json --toc ./docs/api-reference/beta/toc.yml --static-toc ./docs/api-reference/beta/toc/static-toc.yml
     - name: Get token
       id: get_token
@@ -67,26 +76,35 @@ jobs:
       env:
         GH_TOKEN: ${{ steps.get_token.outputs.app-token }}
         PULL_REQUEST: ${{ inputs.pull_request }}
+        V1_OUTCOME: ${{ steps.v1_gen.outcome }}
+        BETA_OUTCOME: ${{ steps.beta_gen.outcome }}
       run: |
-        $status = git status --porcelain
-        if ($status -eq $null) {
-          echo "result=TOC generation resulted in no changes" >> $env:GITHUB_OUTPUT
-          Write-Host "No changes to commit." -ForegroundColor Green
+        $v1Failed = $env:V1_OUTCOME -eq "failure"
+        $betaFailed = $env:BETA_OUTCOME -eq "failure"
+        if ($v1Failed -or $betaFailed) {
+          echo "result=':bangbang: TOC generation failed - please check logs :bangbang:'" >> $env:GITHUB_OUTPUT
+          exit 1
         } else {
-          git config user.email "GraphTooling@service.microsoft.com"
-          git config user.name "Microsoft Graph DevX Tooling"
-          if ($Env:PULL_REQUEST -eq $true) {
-            $timestamp = Get-Date -Format FileDateTimeUniversal
-            git checkout -b ref-toc-generation/$timestamp
-            git add .
-            git commit -m "Update reference TOC"
-            git push --set-upstream origin ref-toc-generation/$timestamp
-            gh pr create --base main --title "Update reference TOC" --body "Ran TOC generation tool" --label "ready to merge"
-            echo "result=TOC generation changes submitted via PR" >> $env:GITHUB_OUTPUT
+          $status = git status --porcelain
+          if ($status -eq $null) {
+            echo "result=TOC generation resulted in no changes" >> $env:GITHUB_OUTPUT
+            Write-Host "No changes to commit." -ForegroundColor Green
           } else {
-            git add .
-            git commit -m "Update reference TOC"
-            git push
-            echo "result=TOC generation changes committed successfully" >> $env:GITHUB_OUTPUT
+            git config user.email "GraphTooling@service.microsoft.com"
+            git config user.name "Microsoft Graph DevX Tooling"
+            if ($Env:PULL_REQUEST -eq $true) {
+              $timestamp = Get-Date -Format FileDateTimeUniversal
+              git checkout -b ref-toc-generation/$timestamp
+              git add .
+              git commit -m "Update reference TOC"
+              git push --set-upstream origin ref-toc-generation/$timestamp
+              gh pr create --base main --title "Update reference TOC" --body "Ran TOC generation tool" --label "ready to merge"
+              echo "result=TOC generation changes submitted via PR" >> $env:GITHUB_OUTPUT
+            } else {
+              git add .
+              git commit -m "Update reference TOC"
+              git push
+              echo "result=TOC generation changes committed successfully" >> $env:GITHUB_OUTPUT
+            }
           }
         }

.github/workflows/cloud-support.yml

@@ -1,3 +1,4 @@
+# cSpell:ignore microsoftgraph
 name: On-demand reference TOC generation
 
 on:
@@ -51,6 +52,7 @@ jobs:
   update-pull-request:
     name: Update pull request
     runs-on: ubuntu-latest
+    if: ${{ always() }}
     needs: request-toc-gen
     steps:
     - uses: octokit/request-action@v2.x

.github/workflows/generate-ref-toc.yml

@@ -114,5 +114,5 @@ The following example shows the response.
 } -->
 
 ```http
-HTTP/1.1 200 Status OK
+HTTP/1.1 200 OK
 ```

.github/workflows/request-ref-toc-gen.yml

@@ -232,6 +232,65 @@ Content-Type: application/json
 
 ---
 
+### Response
+
+The following example shows the response.
+<!-- {
+  "blockType": "response",
+  "truncated": true
+}
+-->
+``` http
+HTTP/1.1 204 No Content
+```
+
+### Example 4: Resume an access package assignment request from a custom extension
+
+#### Request
+
+The following example shows a request of a call to resume an access package assignment request that's waiting for a callback from a custom extension to determine the approver of the access package assignment.
+
+<!-- {
+  "blockType": "request",
+  "name": "accesspackageassignmentrequestthis.resume.customextension"
+}
+-->
+``` http
+POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageAssignmentRequests/0e60f18c-b2a0-4887-9da8-da2e30a39d99/resume
+Content-Type: application/json
+
+{
+  "source": "Contoso.CustoEXT",
+  "type": "microsoft.graph.accessPackageCustomExtensionStage.assignmentRequestCreated",
+  "data": {
+    "@odata.type": "microsoft.graph.microsoft.graph.assignmentRequestApprovalStageCallbackData",
+    "approvalStage": {
+      "durationBeforeAutomaticDenial": "P2D",
+      "escalationApprovers": [],
+      "fallbackEscalationApprovers": [],
+      "fallbackPrimaryApprovers": [],
+      "isApproverJustificationRequired": false,
+      "isEscalationEnabled": false,
+      "primaryApprovers": [
+        {
+          "@@odata.type": "#microsoft.graph.singleUser",
+          "description": "Primary approver of access package assignment.",
+          "id": "",
+          "isBackup": false
+        }
+      ]
+    },
+    "customExtensionStageInstanceDetail": "A approval stage from Logic Apps",
+    "customExtensionStageInstanceId": "@{triggerBody()?['CustomExtensionStageInstanceId']}",
+    "stage": "assignmentRequestDeterminingApprovalRequirements"
+  },
+  "source": "LogicApps",
+  "type": "microsoft.graph.accessPackageCustomExtensionStage.assignmentRequestCreated"
+}
+
+```
+
+
 ### Response
 
 The following example shows the response.

api-reference/beta/api/accesspackageassignmentrequest-cancel.md

@@ -267,3 +267,77 @@ Content-Type: application/json
 }
 ```
 
+### Example 3: Create a custom extension for use with an approval stage callback
+
+The following is an example of a access package assignment request custom workflow extension.
+
+#### Request
+
+<!-- {
+  "blockType": "request",
+  "name": "create_accessPackageAssignmentRequestWorkflowExtension_direct_approval"
+}
+-->
+
+``` http
+POST https://graph.microsoft.com/beta/identityGovernance/entitlementManagement/accessPackageCatalogs/a9286c9c-7659-4b2e-ba44-4d1f2ce07746/accessPackagecustomWorkflowExtensions
+Content-Type: application/json
+
+{
+  "@odata.type": "#microsoft.graph.accessPackageAssignmentRequestWorkflowExtension",
+  "displayName": "test_action_0124_email",
+  "description": "this is for graph testing only",
+  "endpointConfiguration": {
+    "@odata.type": "#microsoft.graph.logicAppTriggerEndpointConfiguration",
+    "subscriptionId": "38ab2ccc-3747-4567-b36b-9478f5602f0d",
+    "resourceGroupName": "test",
+    "logicAppWorkflowName": "elm-extension-email"
+  },
+  "authenticationConfiguration": {
+    "@odata.type": "#microsoft.graph.azureAdPopTokenAuthentication"
+  },
+  "callbackConfiguration": {
+    "@odata.type": "microsoft.graph.accessPackageRequestApprovalStageCallbackConfiguration",
+    "durationBeforeTimeout": "PT1H"
+  }
+}
+```
+
+#### Response
+>**Note:** The response object shown here might be shortened for readability.
+<!-- {
+  "blockType": "response",
+  "truncated": true,
+  "@odata.type": "microsoft.graph.customCalloutExtension"
+}
+-->
+``` http
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+{
+   "value":{
+      "@odata.type":"#microsoft.graph.accessPackageAssignmentRequestWorkflowExtension",
+      "id":"5afcb385-d500-450c-bbf6-3b74a44403da",
+      "displayName":"test_action_0124_email",
+      "description":"this is for graph testing only",
+      "createdDateTime":"2022-01-24T21:48:57.15Z",
+      "lastModifiedDateTime":"2022-01-24T21:55:44.953Z",
+      "clientConfiguration":null,
+      "endpointConfiguration":{
+         "@odata.type":"#microsoft.graph.logicAppTriggerEndpointConfiguration",
+         "subscriptionId":"e8eb46ab-626d-451f-8668-9434e73cf43b",
+         "resourceGroupName":"test",
+         "logicAppWorkflowName":"elm-extension-email",
+         "url":"https://prod-31.eastus.logic.azure.com:443/workflows/8ccffea766ae48e680gd9a22d1549bbc/triggers/manual/paths/invoke?api-version=2016-10-01"
+      },
+      "authenticationConfiguration":{
+         "@odata.type":"#microsoft.graph.azureAdPopTokenAuthentication"
+      },
+      "callbackConfiguration":{
+         "@odata.type":"microsoft.graph.accessPackageRequestApprovalStageCallbackConfiguration",
+         "durationBeforeTimeout":"PT1H"
+      }
+   }
+} 
+```