Support for the programmatic creation of communities on Viva Engage has been a long-time request from our customers. To kick off the New Year, we’re elated to announce that the Community Creation API is now available on Microsoft Graph Beta: Use the Microsoft Graph API to work with Viva Engage (preview)
Some things to note about the API:
1. It is M365 Groups unified.
2. It supports app-delegated (user auth) and app-only access.
3. It is limited to networks in Native mode – legacy and external Yammer networks will not be able to use this API for community creation.
4. Out of scope: community creation for an existing M365 group.
With this, Viva Engage joins the other Microsoft products like Teams and Outlook with public API on MS Graph, and we hope you are as excited about it as we are!
We invite you to try these API and reach out to us with your feedback. See Microsoft Graph REST API beta endpoint reference to learn more about the MS Graph beta program and best ways to provide feedback.
Community creation via these API.
a. The instructions require Postman API Platform setup.
b. Some steps require tenant admin approval
c. Please make sure to read through the Use the Microsoft Graph API to work with Viva Engage (preview) guide before you begin
1. Register a new app in Azure Active Directory
a. Go to Register an application - Microsoft Azure and register a new application.
b. Specify your custom callback url
c. Make note of the application (client) id and the tenant id. This information will be required in the following steps.
d. Make note of the endpoints. This information will be required in the following steps:
2. Select tokens to be issued by authorization endpoint
a. Click on ‘Authentication’ tab
b. Check ‘Access tokens’ and ‘ID tokens’
c. Click save
3. Request API Permissions
a. Go to ‘API permissions’ tab
b. Click on ‘Add a permission’
c. Select ‘Microsoft Graph’
d. Choose ‘Delegated permissions’ if testing the API with your own credentials. Choose ‘Application permissions’ if you wish to use app-only access, without a signed in user.
e. Choose between Read.All or ReadWrite.All permissions. Community creation requires Community.ReadWrite.All permission, but if you only want to test the community read operation, less privileged access Community.Read.All should be used:
f. Before your app can use these permissions, an admin must approve them. Share your app’s API permission url with a tenant admin, and ask them to grant admin consent:
g. Once the admin consent is granted:
4. Create a new Client secret
a. Go to the ‘Certificates & secrets’ tab
b. Click on ‘New client secret’ option and save a new secret.
c. A refresh every 6 months is recommended as security best practice
d. Make note of the secret value, it will be required in the following steps.
5. Create Community POST request url & body
a. Set up the Create community POST request on Postman
b. Request type: POST
c. Request URL: https://graph.microsoft.com/beta/employeeExperience/communities
d. Click on ‘Body’ tab
e. Select format as ‘raw’ and ‘JSON’
f. Provide required parameters: displayName, description, privacy. ‘owners’ can be added as optional, users added as owners will be reflected as admins for the community created via this process.
g. NOTE: Requestor’s AAD id is always added as an owner, if using app-delegated permissions.
h. NOTE: ‘owners’ param is required if using app-only access.
i. TIP: To find AAD id of the user to be added as owner, visit Users - Microsoft Azure portal and click on the specific user you are looking for. Copy the ‘Object id’
6. Set up ‘Authorization’ on Postman for app-only access
SKIP: if you are testing using user auth token. Proceed to the next step for relevant instructions.
a. Click on the ‘Authorization’ tab and select ‘Type’ as ‘OAuth 2.0’
b. Under ‘Configure New Token’ section, add pertinent details, collected in the previous steps
i. Access Token URL: https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/token
ii. Client ID: Your Client ID for your app (registered in step 1)
iii. Client Secret: The new secret created in step 4
iv. Scope: https://graph.microsoft.com/.default
c. Click ‘Get New Access Token’
7. Set up ‘Authorization’ on Postman for app-delegated (user) access
SKIP: if you are testing using app-only access. If so, please make sure to complete the previous step.
a. Click on the ‘Authorization’ tab and select ‘Type’ as ‘OAuth 2.0’
b. Under ‘Configure New Token’ section, add pertinent details, collected in the previous steps:
i. Grant type: Authorization Code
ii. Callback URL: https://www.getpostman.com/oauth2/callback
iii. Auth URL: https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/authorize
iv. Access Token URL: https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/token
v. Client ID: Your Client ID for your app (registered in step 1)
vi. Client Secret: The new secret created in step 4
vii. Scope: https://graph.microsoft.com/.default
c. Click ‘Get new Access Token’ button
8. Submit request for community creation
a. Once the token is generated (you might need to sign in), click ‘use token’
b. Send request
c. If the request is submitted successfully, a ‘202 Accepted’ response will be returned.
d. Open the Response Header tab
e. Copy the ‘Location’
9. Poll for community provisioning complete
a. Use a new Postman tab to poll for community creation status:
b. Request Type: GET
c. Request URL: the ‘Location’ url copied from the previous step
d. In the Authorization tab, select the token generated in the previous step. If expired, a new token should be generated before sending request.
e. Send request
f. Once, community (and associated M365 Group) provisioning is complete, this will return a ‘200 OK’ response, with
i. ‘status’ = ‘succeeded’
ii. ‘operationType’ = ‘createCommunity’
iii. ‘resourceLocation’ = READ url for the newly created community. Make note of this, as this would be required in the next step.
10. Read community details
a. Use a new Postman tab to read the details of the newly created community
b. Request Type = GET
c. Request URL = resourceLocation url copied in the previous step
d. Use the already generated Auth Token, or if expired, generate a new token
e. Send request
f. Upon success, a ‘200 OK’ response is returned along with Response body containing details of the community
11. Look up the community on Viva Engage and start collaborating!
