Implement conditional rendering of permissions tables based on HTML comment command

[millicentachieng]

Introduction A new JSON permissions model was recently introduced to create a single source of truth for permissions information. The new JSON permissions model enables automation to help streamline content authoring and maintenance. Some areas have been identified where the JSON model and permissions automation process falls short of providing complete and accurate permissions information in the Microsoft Graph API reference.

Problem Statement The following issues have been identified:

• Multiple URLs Mapping: The HTTP request block mapped to the permissions tables often includes more than one URL. API Doctor assumes that the permissions for these bundled HTTP requests are identical, which is not always accurate. The current permissions automation process only reads the first request URL and generates the permissions table using that request only.
• Mismatch in Permissions Tables and Request URLs: There are instances in the graph documentation where the number of permissions tables does not match the number of request URLs. This discrepancy has resulted in incorrect data being used to populate the permissions tables.
• Combining Permissions for Multiple URLs: There are cases where permissions for multiple request URLs need to be combined into a single permissions table. The current automation does not support this functionality, leading to gaps in effectively representing permissions.

Solution The solution will include the following:

• To add the ability to specify a specific request URL to populate a permissions table. The structure of the metadata will be as follows:

  <!-- {  
    "blockType": "permissions",  
    "name": "accesspackage_delete_accesspackageresourcerolescopes", 
    "requestUrls" : [], 
  } --> 

• For cases where it’s appropriate to have a single table with shared permissions for multiple request URLs. For this scenario, we will use metadata in the HTML comments to instruct the automation to generate a single combined table for those URLs. The structure for the metadata is as follows:

<!-- {  
  "blockType": "permissions",  
  "name": "accesspackage_delete_accesspackageresourcerolescopes", 
  "requestUrls" : [], 
  "mergePermissions": true 
} --> 

Implementation Details

• Identify all the HTTP requests blocks that have multiple request URLs and do not have the same permission. This is to be presented to the docs team to indicate where tables should be combined or create multiple tables to match the request URLs.
• Identify all the topics where there's a mismatch between the number of permissions tables and HTTP request blocks. The docs team is to add the necessary metadata to indicate which URL should be used to fetch permissions for the affected tables where applicable.
• Update API Doctor to be able to process the additional data in the HTML comment metadata.