Power Pages Web API to Retrieve Contacts with Specific Web Roles

In modern web applications, user roles play a critical role in determining access to resources and features. If you’re using Microsoft Power Pages and want to retrieve contacts assigned to a specific web role (like “Administrators”) using the Portals Web API, this guide will walk you through the process step-by-step.

What is the Power Pages Web API?

The Power Pages Web API allows you to interact with data in your Dataverse environment programmatically. You can use it to query, create, update, and delete records. In this example, we will retrieve contacts with a specific web role using the Web API.

Use Case: Retrieve Contacts with the “Administrators” Role

Imagine you need to fetch a list of all contacts in your Power Pages portal who belong to the “Administrators” role. This can be useful for reporting, sending notifications, or auditing purposes.

1. Understand the Relationship Between Contacts and Web Roles

In Dataverse, the relationship between Contacts and Web Roles is managed through an intermediate table called contactroles_association. Each contact associated with a web role has an entry in this table.

2. Enable the Portals Web API

Before using the Web API, ensure that it is enabled and configured in your environment:

1. Enable Web API:
   • Navigate to the Power Platform Admin Center.
   • Select your portal and enable the Portals Web API.
2. Set Entity Permissions:
   • Go to the Portals Management App.
   • Navigate to Entity Permissions and create or update permissions for the Contact table:
     • Allow Read access for the required web roles.
   • Ensure the contactroles_association and webroles tables also have the appropriate permissions.

3. Find the Web Role ID

You need the unique ID (GUID) of the “Administrators” web role:

1. In the Portals Management App, go to Web Roles.
2. Find the “Administrators” role and copy its GUID (e.g., b1234567-89ab-cdef-0123-456789abcdef).

4. Query the Contacts via Web API

Use the following API call to retrieve all contacts with the “Administrators” role: GET https://yourportalurl/_api/contacts?$expand=contactroles_association($filter=webroleid eq ‘b1234567-89ab-cdef-0123-456789abcdef’)

How it Works:

• The $expand query retrieves the contactroles_association table.
• The $filter ensures only records linked to the “Administrators” web role are returned.

5. Example API Response

The API returns a JSON array of contacts with the specified role:

{
“value”: [
{
“fullname”: “John Doe”,
“emailaddress1”: “john.doe@example.com”,
“contactid”: “12345678-1234-1234-1234-123456789abc”,
“contactroles_association”: [
{
“webroleid”: “b1234567-89ab-cdef-0123-456789abcdef”
}
]
},
{
“fullname”: “Jane Smith”,
“emailaddress1”: “jane.smith@example.com”,
“contactid”: “23456789-2345-2345-2345-234567890bcd”,
“contactroles_association”: [
{
“webroleid”: “b1234567-89ab-cdef-0123-456789abcdef”
}
]
}
]
}

6. Use the Data

Once you retrieve the data:

• Display it in your portal for administrative purposes.
• Use it to send targeted notifications or emails.
• Export it for analysis or reporting.

By using the Power Pages Web API, you can easily retrieve and manage data for specific user roles, such as “Administrators.” This approach simplifies access control, improves reporting capabilities, and enhances the functionality of your portal. Try this out today and take full advantage of the Web API’s potential!